The JavaScript Layer

Why a JavaScript layer at all

The declarative layers, templating, bindings, and reactivity, cover the large majority of interface work with no script. But some behavior is irreducibly imperative: a setInterval clock, a Server-Sent-Events stream, an IntersectionObserver, wrapping a mapping or charting library, or computation too involved for a pure expression. That work needs JavaScript, and pretending otherwise would push authors back into inline handlers and eval-shaped escapes.

So HTML Next draws a firm line. A component definition is declarative data: no <script>, no inline handlers, importable and inspectable without executing anything, and renderable on a server. Imperative JavaScript is a separate concern in an ordinary ES module. The two never fuse; they meet at a named seam.

The controller

A component that needs imperative behavior gets a controller: a function attached to the component tag, run once per instance. It is the decoupled equivalent of a custom element's class plus its ElementInternals¹, the same behavior a Web Component would put in a class, attached instead to a definition made of data. The registration verb is deliberately the platform's: defineController(tag, fn) reads like customElements.define(tag, class).

<!-- x-map.html: pure data. It names a $ref and a state, and mentions no JavaScript. -->
<template component="x-map">
  <defs>
    <state name="center" :value="[0, 0]">
  </defs>
  <div $ref="canvas"></div>
</template>

// x-map.js: an ordinary ES module, the imperative controller for <x-map>.
import { defineController } from "@nextweb/html";

export const controller = (host) => {
  const map = new MapLib(host.refs.canvas);             // a declared $ref, never a querySelector
  host.effect(() => map.setCenter(host.state.center));  // re-runs whenever center changes
  host.on("disconnect", () => map.destroy());           // teardown
};

// Link the controller to the tag. Mirrors customElements.define(tag, class).
defineController("x-map", controller);

The controller is written as a pure function of host and exported, with the tag registration a thin wrapper around it. That export is what lets the same controller run unchanged in the browser runtime and compile to a framework target (below). The definition, meanwhile, references no JavaScript symbol: it declares a <state> and a $ref, and the controller reaches in through those.

host: the ElementInternals of a data component

The controller receives one argument, host, its window onto the instance. The name is the platform's: Shadow DOM already calls the component element seen from inside :host³. Every capability on it is a thin, framework-neutral surface with a native anchor, which is precisely what makes it portable across compile targets.

Teardown is either a disposer returned from an host.on("connect", …) callback or an explicit host.on("disconnect", …); host.effect cleans itself up. This is the same connect-and-return-a-disposer shape used across the platform and userland alike.

Element handles: $ref

A controller often needs a specific element, the node a library mounts into. Rather than a fragile querySelector that reaches into runtime-owned markup, the definition declares the handle with $ref="name", and the controller reads it as host.refs.name.

<!-- $ref is a directive: consumed at lowering, so no non-conforming attribute ships. -->
<div $ref="canvas"></div>
<canvas $ref="surface" width="640" height="480"></canvas>

<!-- in the controller -->
host.refs.canvas    // the <div>
host.refs.surface   // the <canvas>

<!-- native form controls are also reachable by their real name, like form.elements -->
<input name="email" type="email">
host.elements.email // the <input></input>

$ref is a directive, part of the $ family ($if, $each, $value): the runtime reads it, records the node for the controller, and strips it at lowering. So the final DOM carries no ref attribute, which matters because a literal ref (or a name on a non-form element) would be non-conforming HTML. A consumed directive sidesteps that entirely. Native form controls need no $ref: their real name already identifies them, and host.elements reaches them the way form.elements does⁹.

Ownership: drive state, not the DOM

Because a component lowers to real DOM with no shadow boundary, a controller could reach in and mutate bound nodes, and if it did, two writers, the controller and the runtime, would fight over the same DOM and thrash. The rule that prevents this is a single sentence:

// The controller drives STATE. The runtime reflects state to the DOM.
host.state.center = [51.5, -0.1];   // a write; the graph updates every binding that reads center
host.state.center;                  // a read

// It never writes bound DOM directly. That stays the runtime's, so there is one writer
// to the DOM and one source of truth. The map library owns its own (unbound) canvas subtree.

The runtime owns the subtree it lowered and every bound attribute and text node in it. The controller writes state; the runtime reflects state to the DOM. That keeps one writer to the DOM and one source of truth. A controller only touches DOM directly in its own foreign subtree, the canvas a map library renders into, which is unbound and therefore no one else's. User- and browser-driven native state (:checked, <details open>, form values) is treated as input through bind:, not fought.

Communication upward is an event, not a mutated ancestor: host.dispatch raises a component event the parent catches declaratively.

// Raise a component event; a parent listens with on:event, exactly like a <handler> dispatch.
host.dispatch("locationchange", { lat, lng });

// <x-map on:locationchange="recenter">

Registration: joined by tag, like custom elements

None of this is the runtime scanning and guessing. Markup and behavior are wired the way the platform already wires them: by a tag name in a registry, exactly as custom elements join <my-el> to a class through customElements.define("my-el", …). Three things register under one tag, and none references any other:

<!-- 1. the DEFINITION, registered under the tag "x-chart" (declarative, like <template shadowrootmode>) -->
<template component="x-chart"> … </template>

// 2. the CONTROLLER, registered under the SAME tag (an explicit call, like customElements.define)
defineController("x-chart", (host) => { … });

<!-- 3. INSTANCES in the page: they upgrade once a definition and (if any) a controller exist for "x-chart" -->
<x-chart></x-chart>

// Nothing points at anything else. The TAG "x-chart" is the join key, exactly as in custom elements:
//   <my-el>  +  customElements.define("my-el", class)  meet only at the string "my-el".

The definition registers declaratively, by being a parsed <template component="x-chart">, the same way the parser acts on <template shadowrootmode>, or imperatively through the registry. The controller registers with an explicit defineController("x-chart", fn) call, shaped precisely like customElements.define and, like it, upgrading every connected instance the moment it runs. Instances upgrade once a definition, and any controller, exist for their tag. The join is the string "x-chart"; nothing points at anything else.

The registry API

The registry mirrors customElements¹, with one addition for the behavior half:

// The registry is shaped like customElements. Declarative registration is primary; these
// imperative calls exist for JS-driven registration and for controllers.
components.define("x-chart", templateEl);              // register a definition (cf. customElements.define)
components.defineController("x-chart", (host) => …);   // register behavior; upgrades matching instances
components.get("x-chart");                             // the registered definition
await components.whenDefined("x-chart");               // resolves when registered (cf. whenDefined)

In the polyfill this is an object the runtime provides; the shape is what a native implementation would expose. Declarative registration (<template component>, <link rel="component">) is the primary path; these calls are for JavaScript-driven registration and for controllers.

Loading a controller: eager is native, lazy is a hint

Because registration is by tag, loading a controller needs no special mechanism, it is just loading a module that calls defineController:

<!-- EAGER: load the controller module like any script. It calls defineController; instances upgrade.
     This is identical to how you ship a custom element today. -->
<script type="module" src="/components/b.js"></script>

<!-- LAZY (optional): do not load it yet. The definition hints where the controller lives, and the
     runtime defers import() until the first <x-chart> connects. The hint is a loader detail, not the wiring. -->
<link rel="controller" href="./b.js">   <!-- declared inside b.html -->

Eagerly, you load the controller module like any script and it self-registers, identical to shipping a custom element. Lazily, the definition carries a <link rel="controller"> hint and the runtime defers the import() until the first instance connects. That deferral is the entire extent of what the runtime adds, and even it resolves to a standard dynamic import:

// Inside /htmlnext.js. b.html's <link rel="controller"> told it: x-chart -> /components/b.js.
// On the FIRST connect of an <x-chart> that has no controller registered yet, it does one thing:
const url = controllerHint.get("x-chart");   // "/components/b.js", from the <link rel="controller">
if (url) await import(url);                   // runs the module; the module's OWN defineController("x-chart", …)
                                             // call registers the controller and upgrades this instance,
                                             // exactly like a late customElements.define upgrades <my-el>.
                                             // (If a <link rel="modulepreload" integrity> was declared, the
                                             //  browser already hash-checked b.js and import() reuses it.)

So the design reduces to two registries that never overlap, both keyed by tag:

A worked example: a component that uses another

Take a dashboard, <x-dashboard> (component A), that reads metrics and renders a chart, <x-chart> (component B). A is purely declarative and needs no JavaScript at all; B wraps a charting library, so it has a controller. Here are the whole files.

<!-- /components/a.html — the <x-dashboard> component. Pure data: no <script>, no controller. -->
<link rel="component" href="./b.html">            <!-- A renders <x-chart>: declare the edge -->

<template component="x-dashboard">
  <defs>
    <prop name="title" type="string" default="Overview">Panel heading.</prop>
    <data name="metrics" src="/api/metrics">        <!-- a declared, reactive read -->
  </defs>

  <section>
    <h1 $value="title"></h1>
    <template $match>
      <p $when="metrics.pending">Loading…</p>
      <x-chart $else :series="metrics.value.series"></x-chart>
    </template>
  </section>
</template>

A declares its dependency on B with <link rel="component"> and mentions no script. Its behavior, a reactive <data> read and a $match, is entirely declarative.

<!-- /components/b.html — the <x-chart> component. Data plus a DECLARED controller. Still no <script>. -->
<link rel="controller" href="./b.js">                          <!-- which module is x-chart's controller -->
<link rel="modulepreload" href="./b.js" integrity="sha384-…">  <!-- optional: pin the hash + warm the cache -->

<template component="x-chart">
  <defs>
    <prop name="series" type="array" required>The data to plot.</prop>
  </defs>

  <figure>
    <canvas $ref="surface" role="img" aria-label="Revenue by month"></canvas>
  </figure>
</template>

B is also pure data, but it declares a controller with <link rel="controller"> (the tag → module mapping the runtime reads), and optionally pins its bytes with a companion <link rel="modulepreload" integrity>, since a bare import() cannot itself carry SRI. The definition still contains no <script>; it only names where the behavior lives and exposes a $ref for it to grab.

// /components/b.js — an ordinary ES module: the ONLY JavaScript in the whole tree.
import { defineController } from "html/components";  // the registration API (see below)
import { Chart } from "chart-lib";                  // a bare specifier; the import map resolves it

export const controller = (host) => {               // exported so an ahead-of-time target can lift it
  const chart = new Chart(host.refs.surface, { data: host.state.series });
  host.effect(() => chart.update(host.state.series));   // re-plot when series changes
  host.on("disconnect", () => chart.destroy());         // teardown
};

// The explicit registration call, shaped exactly like customElements.define(tag, class).
// Running it registers the controller and upgrades any connected <x-chart> instances.
defineController("x-chart", controller);

The controller is the sole piece of JavaScript in the tree, an ordinary ES module with a default export. The page wires only the entry:

<!doctype html>
<link rel="component" href="/components/a.html">     <!-- resolve only the ENTRY; B comes from A -->
<script type="module" src="/htmlnext.js"></script>  <!-- the runtime: one module -->
<script type="importmap">                            <!-- import map: JS bare specifiers, its real job -->
  { "imports": { "chart-lib": "/vendor/chart-lib.js" } }
</script>

<x-dashboard title="Q3 revenue"></x-dashboard>

How it loads, step by step

1. The browser loads /htmlnext.js (the runtime) as a module. The runtime reads <link rel="component" href="/components/a.html"> and fetches a.html. (rel="component" is not a scanner-preloaded rel, so this fetch starts once the runtime runs; to pull it forward, pair it with a <link rel="preload">, or resolve the graph at SSR time, see below.)
2. The runtime scans the DOM, finds <x-dashboard>, resolves it to a.html, and fetches and parses that file as inert data, executing nothing. Registering it, the runtime reads <link rel="component" href="./b.html"> and records x-chart → /components/b.html (it does not fetch B yet).
3. It lowers <x-dashboard>: the <h1> renders, the <data> fetch to /api/metrics starts, and the $match shows Loading… while metrics.pending.
4. When metrics resolve, the $match switches to the <x-chart> arm. Now an x-chart is needed, so b.html is fetched (again, inert data), registered, and its <link rel="controller"> records x-chart → /components/b.js. <x-chart> lowers to <figure><canvas>.
5. The <x-chart> instance connects. Only now does the runtime run:

// Inside /htmlnext.js. b.html's <link rel="controller"> told it: x-chart -> /components/b.js.
// On the FIRST connect of an <x-chart> that has no controller registered yet, it does one thing:
const url = controllerHint.get("x-chart");   // "/components/b.js", from the <link rel="controller">
if (url) await import(url);                   // runs the module; the module's OWN defineController("x-chart", …)
                                             // call registers the controller and upgrades this instance,
                                             // exactly like a late customElements.define upgrades <my-el>.
                                             // (If a <link rel="modulepreload" integrity> was declared, the
                                             //  browser already hash-checked b.js and import() reuses it.)

That is the entire mechanism: import(url), the platform's own dynamic import, on a URL the runtime read from a <link>, at the moment an instance connects. Deduplication, one-time evaluation, and caching are the standard ES-module loader's job because it is the standard loader; the runtime adds nothing. If metrics stay empty and the chart arm never renders, neither b.html nor b.js is ever fetched; and with no runtime at all, steps 1–4 still produce the server-rendered declarative baseline, only the chart library is skipped.

Compiling to React, Vue, and Svelte

A controller is imperative JavaScript, so it is not transpiled into idiomatic framework code; it is run as-is. Because it is a pure function of host, each target ships a small host adapter that builds a host from that framework's own primitives and runs the controller against it. The imperative body ports unchanged.

<!-- Vue output. The controller body is reused verbatim; only the host is adapted. -->
<script setup>
import { controller } from "./x-map.js";
import { adaptVue } from "@nextweb/html/vue";

const props = defineProps({ center: { type: Array, default: () => [0, 0] } });
const canvas = ref();
adaptVue(controller, { refs: { canvas }, state: props });
</script>

<template>
  <div ref="canvas"></div>
</template>

This works because host is deliberately tiny, and every target already has all of it natively: lifecycle (Vue onMounted/onUnmounted, Svelte onMount/onDestroy, Solid onMount/onCleanup, React useEffect), effects (Vue watchEffect, Svelte $effect, Solid createEffect), refs (Vue ref, Svelte bind:this, React useRef), and props-or-state for host.state. $ref="name" maps to each target's ref idiom; host.dispatch to its event mechanism.

Lifecycle and hydration

A controller's connect fires when the instance connects, on first mount and on any later reconnection, matching the custom-element reaction rather than a once-only mount¹. On a server-rendered page, the markup arrives already lowered and inert; the controller attaches at hydration, where connect first runs in the browser. disconnect fires on removal, running teardown. Because the first render never depends on the controller, hydration is adopt-in-place: the controller binds to existing nodes rather than rebuilding them (see Components).

Reference

References

1. WHATWG HTML, custom elements (customElements.define, connectedCallback/disconnectedCallback): a controller is the same behavior, attached by tag to a data-defined component instead of authored as a class.
2. WHATWG HTML, ElementInternals and custom states with CSS :state(): the native model for the internal state of an element, generalized here from boolean flags to values.
3. CSS Scoping, Shadow Parts (part / ::part()) and :host: the platform words for a component element seen from inside, and for a named internal piece exposed to outside CSS.
4. TC39, Signals (computed values and effects): the standards-track basis for host.effect, a computation re-run when its tracked reads change.
5. Lit, Reactive Controllers (hostConnected/hostDisconnected, a controller object attached to a host): direct prior art for the controller-plus-host shape, adapted to a script-free definition.
6. W3C, HTML Imports (discontinued): the approach this layer deliberately avoids, fusing markup, style, and executing script into one imported document.
7. WHATWG HTML, import maps and ES modules: the platform module system that carries the JavaScript, kept separate from the component data.
8. WHATWG DOM, CustomEvent and dispatchEvent: what host.dispatch lowers to.
9. WHATWG HTML, form.elements named access: the native precedent for reaching a control within a container by its name, echoed by host.elements.