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: declarative data plus a controller REQUEST. The link does not authorize code. -->
<link rel="controller" href="./x-map.js">
<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 against the small host interface and exported, with the tag registration a thin wrapper around it. That convention lets the same controller run unchanged in the browser runtime and compile to a framework target (below). It is a portability contract, not a security boundary: an ES module can still use window, document, storage, network APIs, and anything else page JavaScript can reach. The definition declares its requested controller URL as metadata, plus a <state> and a $ref; only the application can authorize that request.

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" -->
<link rel="controller" href="./x-chart.js">  <!-- discovers a request; does not authorize it -->
<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: the application authorizes code

Because registration is by tag, loading a controller reduces to loading a module that calls defineController. What matters is the difference between naming and authorizing. A transitive component definition names the module it requests with <link rel="controller" href>, keeping its dependency local and discoverable. The application independently maps the conventional bare specifier html-next-controller/tag to the approved URL, or loads the module eagerly itself:

<!-- EAGER: the application loads and authorizes the exact module. -->
<script type="module" src="/components/b.js" integrity="sha384-…"></script>

<!-- LAZY: the definition names the controller it requests. Importing this file runs nothing. -->
<link rel="controller" href="./b.js">
<template component="x-chart">…</template>

<!-- The application owns the tag-to-module decision. An unmapped request executes nothing. -->
<script type="importmap">
{
  "imports": {
    "html-next-controller/x-chart": "/components/b.js"
  },
  "integrity": {
    "/components/b.js": "sha384-…"
  }
}
</script>

Eagerly, the application loads the controller module like any script and it self-registers, identical to shipping a custom element. Lazily, the runtime records the definition's requested URL but does not import it. On first connect, import.meta.resolve()⁷ resolves the conventional specifier through the application's ordinary import map. Only an exact URL match can load; an absent mapping throws before fetch and a different mapping fails closed:

// Inside /htmlnext.js. b.html requested /components/b.js for x-chart.
const requested = controllerRequest.get("x-chart");
const specifier = "html-next-controller/x-chart";
const approved = import.meta.resolve(specifier); // resolves through the APPLICATION'S import map

if (requested !== approved) return; // absent or different approval: execute nothing
await import(specifier);             // CSP and CORS apply; import-map integrity pins the bytes

// The approved module's own defineController("x-chart", …) call registers the controller
// and upgrades this instance, like a late customElements.define upgrades <my-el>.

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 — data that NAMES a requested controller but cannot authorize it. -->
<link rel="controller" href="./b.js">

<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 data. Its <link rel="controller" href="./b.js"> identifies the module it requests, so the component remains self-describing, but the link has no execution semantics. The application independently maps html-next-controller/x-chart → /components/b.js and pins those bytes in its import map. The definition contains no <script> or JavaScript symbol; it records a dependency request and exposes a $ref for an approved controller to use.

// /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 component JavaScript in the tree, an ordinary ES module with a named export. The page owns the executable mapping:

<!doctype html>
<link rel="component" href="/components/a.html">     <!-- resolve only the ENTRY; B comes from A -->
<script type="importmap">                            <!-- the APPLICATION authorizes executable modules -->
{
  "imports": {
    "html-next-controller/x-chart": "/components/b.js",
    "chart-lib": "/vendor/chart-lib.js"
  },
  "integrity": {
    "/components/b.js": "sha384-…",
    "/vendor/chart-lib.js": "sha384-…"
  }
}
</script>
<script type="module" src="/htmlnext.js" integrity="sha384-…"></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 controller link records the resolved request x-chart → /components/b.js. Nothing executes. <x-chart> lowers to <figure><canvas>.
5. The <x-chart> instance connects. Only now does the runtime run:

// Inside /htmlnext.js. b.html requested /components/b.js for x-chart.
const requested = controllerRequest.get("x-chart");
const specifier = "html-next-controller/x-chart";
const approved = import.meta.resolve(specifier); // resolves through the APPLICATION'S import map

if (requested !== approved) return; // absent or different approval: execute nothing
await import(specifier);             // CSP and CORS apply; import-map integrity pins the bytes

// The approved module's own defineController("x-chart", …) call registers the controller
// and upgrades this instance, like a late customElements.define upgrades <my-el>.

That is the entire lazy mechanism: compare the discovered request with import.meta.resolve("html-next-controller/" + tag), then use standard import(specifier) at the moment an instance connects. Deduplication, one-time evaluation, and caching are the ES-module loader's job. If the application did not approve that exact tag and URL, no code runs. If metrics stay empty and the chart arm never renders, neither b.html nor b.js is 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 authored against host, each target ships a small host adapter that builds that interface from the framework's own primitives and runs the controller against it. The imperative body ports unchanged, provided it observes that portability contract; direct use of browser globals is allowed JavaScript but naturally makes the controller browser-specific.

<!-- 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, their integrity metadata, and import.meta.resolve(): the existing name resolution, byte-pinning, and module-loading machinery used for approved controllers.
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.