diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d2fc82..fd84eac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,81 @@ All notable changes to @livetemplate/client will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **`lvt-*` attributes are now extensible: `LiveTemplateClient.registerAttribute()`.**
+  Adding an attribute used to mean forking this library — writing a `dom/*.ts`
+  module, importing it into `livetemplate-client.ts`, and inserting a call at the
+  right position in a hardcoded ~20-entry sequence. An app that wanted
+  `lvt-x:copy-to-clipboard` had no supported way to get one.
+
+  There are two layers. Most authors only need the declarative one: declare an
+  attribute *name* and get called per element.
+
+  ```html
+  <button lvt-x:copy="{{.ShareURL}}">Copy link</button>
+  <script src="{{ lvtClientScriptURL }}" defer></script>
+  <script>
+    LiveTemplateClient.registerAttribute({
+      attribute: "lvt-x:copy",
+      onElementAdded(el, ctx) {
+        el.addEventListener("click", () => navigator.clipboard.writeText(ctx.value));
+      },
+    });
+  </script>
+  ```
+
+  The framework owns selector escaping, the DOM scan, per-element match
+  tracking, empty-value rejection, and sweeping elements that lost the attribute
+  or left the DOM — the sweep runs on every render, so `onElementRemoved` is
+  never deferred — so the three classic mistakes (no sweep, listeners stacking
+  on every render, a captured transport that dies at reconnect) are not
+  reachable from this layer. `ctx.value` and `ctx.send` are live accessors, so a
+  listener wired once still reads the current attribute value and dispatches
+  through the current transport.
+
+  Set `needsServerChannel: true` to get `ctx.send`; the message routes through
+  the same path an `lvt-on:click` action uses, and the server cannot tell the
+  difference. No server-side registration, no new wire message type, no build
+  step.
+
+  A `selectors` + `setup()`/`teardown()` escape hatch covers handlers with
+  cross-element state; every built-in uses it, so an author is never on a lesser
+  API than the framework itself.
+
+  Registration is static and late registration is supported: calling
+  `registerAttribute` after the client has connected runs the handler against
+  the live DOM immediately, rather than waiting for the next render. That is the
+  only sequence available to a second `<script>`, because `autoInit()` has
+  already connected by the time one evaluates.
+
+  Exported types: `AttributeHandler`, `DeclarativeHandler`, `LowLevelHandler`,
+  `ElementContext`, `SetupContext`, `SendFn`, `HandlerCategory`.
+
+  `registerAttribute` is deliberately unauthenticated, and grants no capability
+  a page script did not already have: `window.liveTemplateClient.send()` has
+  always been public, so any script with page access could already dispatch
+  arbitrary actions. Server-side authorization is unchanged and remains the
+  boundary that matters.
+
+  Two limits worth knowing before you build on this. Registration is
+  append-only — there is no `unregisterAttribute` yet, so a dev server that
+  hot-reloads a handler bundle accumulates one live handler per reload; the
+  production `<script defer>` pattern, where a bundle evaluates once, is
+  unaffected. And `dispose()` runs when the *last* client on the page
+  disconnects, because the registry is shared by all of them; per-client
+  cleanup belongs in `teardown(root)`, which runs for each client as it goes.
+
+### Changed
+
+- **Every built-in attribute handler now runs through that same registry.** The
+  hardcoded post-render call sequence and the matching `disconnect()` teardown
+  list are gone, replaced by a loop over registered handlers. No attribute
+  changed its spelling, semantics, or server-side treatment, and no template
+  needs an edit; all 824 pre-existing tests pass unmodified.
+
 ## [v0.25.0] - 2026-08-15
 
 ### Changes
diff --git a/attribute-registry.ts b/attribute-registry.ts
new file mode 100644
index 0000000..222dd87
--- /dev/null
+++ b/attribute-registry.ts
@@ -0,0 +1,857 @@
+/**
+ * LiveTemplate attribute handler registry.
+ *
+ * The public extension point for `lvt-*` attributes. Instead of the core client
+ * hardcoding a call to every handler it knows about, handlers register
+ * themselves here and the post-render loop scans the registry.
+ *
+ * Two layers, both of them `AttributeHandler`:
+ *
+ *   DECLARATIVE — declare an attribute NAME. The framework escapes it, scans
+ *   for it, tracks which elements match, reads the value, and sweeps elements
+ *   that lost it. This is what most authors should use; it makes the three
+ *   classic mistakes (no sweep, non-idempotent wiring, a stale captured `send`)
+ *   impossible by construction.
+ *
+ *   LOW-LEVEL — supply `selectors` + `setup()`/`teardown()`. The escape hatch
+ *   for handlers with cross-element state, multi-attribute matches, or
+ *   selectors that aren't a plain attribute-presence match. Every built-in uses
+ *   this layer, because each one predates the registry and keeps its own body.
+ *
+ * REGISTRATION IS MODULE-LEVEL AND STATIC, never instance-scoped, and late
+ * registration is a supported path — a second bundle can only evaluate after
+ * the core bundle has already auto-initialized and connected, so there is no
+ * instance for it to call a method on. See `docs/plans/issue-473.md` § Design 2
+ * ("Bootstrap timing") in the livetemplate repo for the full argument.
+ *
+ * WHAT THE REGISTRY CAN ANSWER ABOUT ITSELF. A declarative handler's
+ * `attribute` is authoritative: it is a plain name, the framework owns the
+ * scan, and comparing it against the server's attribute census is a string
+ * match. A low-level handler's `selectors` is NOT authoritative — it is
+ * author-supplied prose that the loop never reads, and two built-ins
+ * (`setupFxDOMEventTriggers`, the `lvt-el:` delegator) legitimately scan
+ * `querySelectorAll("*")` and so claim no attribute at all. Low-level handlers
+ * are therefore excluded from the attribute-census comparison that Phase 3
+ * ships, and from the duplicate-registration warning below.
+ */
+
+import { lvtSelector } from "./utils/lvt-selector";
+import { createLogger } from "./utils/logger";
+
+const logger = createLogger({ scope: "AttributeRegistry" });
+
+/**
+ * Dispatches a server action through the client's live transport. Identical to
+ * the path an `lvt-on:click` action takes — a custom attribute's action is
+ * indistinguishable from a built-in one by the time it reaches the server.
+ */
+export type SendFn = (message: { action: string; data: Record<string, unknown> }) => void;
+
+/**
+ * When a handler runs, relative to the post-render pipeline.
+ *
+ *   fire-on-change   — every render. For handlers reacting to a VALUE changing
+ *                      on an element that already exists (a highlight flash, a
+ *                      scroll-to, a re-read of the attribute).
+ *   wire-idempotent  — only when morphdom added nodes or touched a directive
+ *                      attribute. For handlers that walk many descendants to
+ *                      attach listeners; skipping saves ~150-200ms per render
+ *                      at 80k nodes.
+ *
+ * This gates the SCAN only. A declarative handler's sweep runs on every render
+ * whatever its category, because skipping cleanup is a correctness bug while
+ * skipping a scan is just work avoided (see runHandler).
+ *
+ * There was a third member, `always`, meaning "every render even if a future
+ * empty-diff optimization skips other handlers". It was cut before this
+ * interface shipped: nothing consumed it, `updateDOM` has no such skip to be
+ * exempt from, and so it was indistinguishable from `fire-on-change` in every
+ * observable way. Adding a union member later is a minor release; removing one
+ * is a major, so unused surface does not get to ship first and be justified
+ * afterwards.
+ */
+export type HandlerCategory = "fire-on-change" | "wire-idempotent";
+
+interface BaseHandler {
+  /**
+   * Defaults to `attribute` for declarative handlers; REQUIRED for low-level
+   * ones, where `LowLevelHandler` narrows it to non-optional.
+   *
+   * Required there because it is the only thing a low-level handler can be
+   * identified by: `selectors` is descriptive and the duplicate-registration
+   * warning deliberately never keys on it, so a nameless low-level handler is
+   * invisible to that warning — and a silent clash is the one case where it
+   * matters most.
+   */
+  name?: string;
+
+  /**
+   * Omit to derive: declaring `onElement` => "fire-on-change"; only
+   * `onElementAdded`/`onElementRemoved` => "wire-idempotent". An explicit
+   * value always wins.
+   */
+  category?: HandlerCategory;
+
+  /** Whether this handler dispatches server actions. Default false. */
+  needsServerChannel?: boolean;
+
+  /**
+   * Root-less cleanup, run when the LAST client disconnects, whether or not a
+   * wrapper element exists.
+   *
+   * Scoped to the last client on purpose. The registry is module-level and
+   * shared by every client on the page, so a handler's module-global state is
+   * too — disposing it when one of two clients disconnects would pull it out
+   * from under the other. Per-client state does not belong here; it belongs in
+   * `teardown(root)`, which runs for each client as it goes.
+   *
+   * `teardown(root)` can only express cleanup scoped to a subtree, but plenty
+   * of handlers own module-global state — a timer map, a document-level
+   * listener — that has no root to be scoped to. Without this hook such a
+   * handler's cleanup has to stay a hardcoded call in the core client, which
+   * makes it unrelocatable and the registry a half-interface.
+   */
+  dispose?(): void;
+
+  // Reserved: per-element morphdom predicates (onBeforeElUpdated?, ...).
+  // Deferred, not designed. Every extension point on this interface is an
+  // OPTIONAL member by construction, so adding one stays a minor release.
+}
+
+/**
+ * Per-element context handed to a declarative handler's callbacks.
+ *
+ * Both members are LIVE ACCESSORS, deliberately. Capturing `ctx` inside a
+ * listener is the normal thing to do, so reading it later has to be correct:
+ *
+ *   - `value` re-reads the attribute, so a server re-render is picked up rather
+ *     than the callback holding the value it saw at wiring time;
+ *   - `send` resolves the current transport, so a captured `ctx` survives a
+ *     WebSocket reconnect instead of dispatching into a dead socket.
+ */
+export interface ElementContext {
+  readonly value: string;
+  readonly send?: SendFn;
+  readonly wrapperRoot: Element;
+}
+
+/** Context handed to a low-level handler's `setup()`. */
+export interface SetupContext {
+  /** Element subtree to scan. */
+  scanRoot: Element;
+  /** Top-level wrapper, for event-listener storage keyed per wrapper. */
+  wrapperRoot: Element;
+  /** Only provided when `needsServerChannel` is true. */
+  send?: SendFn;
+}
+
+export interface DeclarativeHandler extends BaseHandler {
+  /**
+   * A plain attribute name, e.g. "lvt-x:copy". Never a CSS selector.
+   *
+   * An element is claimed while it carries this attribute WITH a non-empty
+   * value. Emptying the value is treated exactly like removing the attribute:
+   * the value is the handler's configuration, so an empty one means unarmed,
+   * and `onElementRemoved` fires.
+   */
+  attribute: string;
+  selectors?: undefined;
+
+  /** Once per element, the first time it matches. */
+  onElementAdded?(el: Element, ctx: ElementContext): void;
+  /** Every run, for every currently matching element. */
+  onElement?(el: Element, ctx: ElementContext): void;
+  /**
+   * The element detached, or its attribute was removed or emptied by a server
+   * diff. Fires on every render — it is never deferred by `category`.
+   *
+   * Requires `onElementAdded` or `onElement`: elements are only tracked when
+   * one of those claims them, so this callback on its own could never fire.
+   * Registration rejects that shape rather than accepting a handler that does
+   * nothing forever.
+   */
+  onElementRemoved?(el: Element): void;
+}
+
+export interface LowLevelHandler extends BaseHandler {
+  /** Required: the handler's identity for diagnostics. See BaseHandler.name. */
+  name: string;
+
+  /** Descriptive only — see the file header. e.g. '[lvt-fx\\:scroll]'. */
+  selectors: string[];
+  attribute?: undefined;
+
+  setup(ctx: SetupContext): void;
+  teardown?(root: Element): void;
+}
+
+export type AttributeHandler = DeclarativeHandler | LowLevelHandler;
+
+export function isDeclarative(h: AttributeHandler): h is DeclarativeHandler {
+  return typeof (h as DeclarativeHandler).attribute === "string";
+}
+
+/**
+ * A live client, from the registry's point of view. Clients attach on connect
+ * and detach on disconnect so that late registration has somewhere to catch up
+ * to, without the registry importing the client class.
+ */
+export interface RegistryRoot {
+  /** The client's wrapper, read at call time — it is replaced on navigation. */
+  root(): Element | null;
+  send: SendFn;
+}
+
+// MODULE-LEVEL STATE, AND WHAT EACH PIECE IS KEYED BY.
+//
+// Two defects in review of this file were the same mistake — state keyed by
+// something other than what owns the guarantee it backs — so the keys are
+// listed here together, where a mismatch is easier to see than it is at five
+// separate declarations:
+//
+//   registry     — page-wide. The set of handlers, shared by every client, by
+//                  design (see the file header).
+//   liveRoots    — page-wide. Which clients are attached; only used to answer
+//                  "is this the last one?" for dispose().
+//   tracked      — per handler, then per element. Holds each element's
+//                  ElementContext AND the transport it dispatches through,
+//                  which must be per element: two clients can both have
+//                  elements claimed by the same handler, and an element's
+//                  transport belongs to the client whose subtree contains it.
+//   resolved     — per handler. Values fixed at registration, so nothing about
+//                  a client or an element can vary them.
+//   warnedEmpty  — per handler, then per element. One element can carry two
+//                  handlers' attributes, so "already warned about this element"
+//                  is only meaningful alongside "by which handler".
+const registry: AttributeHandler[] = [];
+const liveRoots = new Set<RegistryRoot>();
+
+/**
+ * Per-handler element tracking for the declarative layer.
+ *
+ * The VALUE is an enumerable Map, not a WeakMap, because sweeping requires
+ * ENUMERATING what matched before — a WeakMap can answer "is this element
+ * tracked?" but not "which tracked elements are gone?". The cost is that a
+ * detached element stays reachable until the next sweep drops it, and since
+ * sweeps run on every render regardless of category, that window is one
+ * render for every handler.
+ *
+ * The value cached against each element is its `ElementContext`, built once for
+ * the element's lifetime. Rebuilding it per render would allocate an object and
+ * three accessor closures for every match on every render — on a 10k-row table
+ * with one custom attribute per row, ~40k allocations a render — and would buy
+ * nothing: the context's members are accessors precisely so a single instance
+ * stays correct as the value, transport and wrapper change beneath it.
+ */
+const tracked = new WeakMap<AttributeHandler, Map<Element, ElementEntry>>();
+
+/**
+ * What one tracked element's context reads through.
+ *
+ * Per ELEMENT, not per handler, and that distinction is load-bearing. The
+ * registry is module-level by design, so two LiveTemplateClient instances can
+ * be live on one page with elements matching the same attribute. Keying the
+ * transport by handler alone meant whichever client rendered most recently
+ * owned the slot for every other client's elements too, and a listener wired on
+ * client A's element would dispatch through client B's socket.
+ *
+ * An element only ever matches during a dispatch whose scanRoot contains it —
+ * its own client's — so a per-element record is written by exactly one client,
+ * and cross-contamination stops being possible rather than being avoided.
+ *
+ * The fields are refreshed on every dispatch rather than captured once, which
+ * is what keeps a context correct across a reconnect: the client hands in a new
+ * transport and the element's own next render adopts it.
+ */
+interface ElementEntry {
+  ctx: ElementContext;
+  send: SendFn | undefined;
+  wrapperRoot: Element;
+}
+
+/**
+ * Values fixed at registration, computed once instead of per render: the
+ * resolved category (`shouldRun` asks 19 times a render otherwise) and, for a
+ * declarative handler, its escaped attribute selector.
+ */
+const resolved = new WeakMap<AttributeHandler, { category: HandlerCategory; selector: string }>();
+
+/**
+ * Elements already warned about for an empty attribute value, per handler.
+ *
+ * Keyed by HANDLER and then element, not by element alone. One element can
+ * carry two independently registered attributes — `<div lvt-x:copy=""
+ * lvt-x:rate="5">` — and a set shared across handlers makes them corrupt each
+ * other's bookkeeping in both directions: the populated handler's "this element
+ * is fine" clears the empty handler's "already warned", so the warning re-fires
+ * every render; and two empty attributes on one element report only the first,
+ * silently swallowing the second template bug.
+ *
+ * The empty-value check runs on every render, because an element with no value
+ * is deliberately never tracked so it can heal the moment a real value arrives.
+ * This is what stops that check becoming one warning per render — once per
+ * element per handler, cleared when it heals so a value that empties again is
+ * reported again.
+ */
+const warnedEmpty = new WeakMap<AttributeHandler, WeakSet<Element>>();
+
+function warnedEmptySet(handler: AttributeHandler): WeakSet<Element> {
+  let set = warnedEmpty.get(handler);
+  if (!set) {
+    set = new WeakSet<Element>();
+    warnedEmpty.set(handler, set);
+  }
+  return set;
+}
+
+function trackedMap(handler: AttributeHandler): Map<Element, ElementEntry> {
+  let map = tracked.get(handler);
+  if (!map) {
+    map = new Map<Element, ElementEntry>();
+    tracked.set(handler, map);
+  }
+  return map;
+}
+
+/** Resolved display name, for warnings. */
+function handlerName(h: AttributeHandler): string {
+  return h.name || (isDeclarative(h) ? h.attribute : h.selectors.join(","));
+}
+
+/**
+ * What a handler CLAIMS, for the duplicate-registration warning, or null if it
+ * claims nothing checkable.
+ *
+ * Never `selectors`: that field is descriptive (the loop dispatches by calling
+ * `setup()` and never reads it), and two built-ins legitimately scan
+ * `querySelectorAll("*")`, so keying the warning on it would make the registry
+ * warn about its own core handlers on every page load.
+ */
+function claimKey(h: AttributeHandler): string | null {
+  if (isDeclarative(h)) return h.attribute.toLowerCase();
+  return h.name ? h.name.toLowerCase() : null;
+}
+
+/**
+ * The category a handler runs under, derived when not declared.
+ *
+ * Declarative: `onElement` means "react to a value that can change on an
+ * element that already exists", which only works if the handler runs every
+ * render. Wiring-only handlers (`onElementAdded`/`onElementRemoved`) would do
+ * nothing on an unchanged DOM, so they earn the skip.
+ *
+ * Low-level: there is nothing to derive from, so an omitted category means
+ * "fire-on-change" — the conservative default, because running too often is a
+ * performance bug while running too rarely is a correctness bug. A low-level
+ * handler that can afford the skip has to say so explicitly.
+ */
+export function resolveCategory(h: AttributeHandler): HandlerCategory {
+  const cached = resolved.get(h);
+  if (cached) return cached.category;
+  return deriveCategory(h);
+}
+
+function deriveCategory(h: AttributeHandler): HandlerCategory {
+  if (h.category) return h.category;
+  if (isDeclarative(h)) {
+    return h.onElement ? "fire-on-change" : "wire-idempotent";
+  }
+  return "fire-on-change";
+}
+
+/** Whether a handler runs for a render with this much change in it. */
+export function shouldRun(h: AttributeHandler, domChanged: boolean): boolean {
+  return resolveCategory(h) !== "wire-idempotent" || domChanged;
+}
+
+/**
+ * Registers an attribute handler.
+ *
+ * THREAT MODEL. This is a public, unauthenticated entry point: any script with
+ * page access can register a handler with `needsServerChannel: true` and
+ * dispatch actions the server cannot distinguish from an `lvt-on:click`. That
+ * is intended, and it grants nothing new — `autoInit` already assigns the live
+ * client to `window.liveTemplateClient`, whose `send()` is public, so a script
+ * on the page could always dispatch arbitrary actions. It could equally click a
+ * real `lvt-on:` element or POST to the live endpoint with the session cookie.
+ *
+ * The boundary that matters is the server's, and it has not moved: actions
+ * arriving this way are still just actions, subject to whatever authorization
+ * the handler applies. A same-origin script is fully trusted by the browser's
+ * own model, so a page that runs untrusted script is already compromised in
+ * ways no client-side check could fix. Never treat a registered handler as
+ * evidence of anything about the caller.
+ *
+ * Static by design (see the file header). Registering after a client already
+ * exists immediately runs the handler against every live wrapper, so a bundle
+ * that loads after core participates from the current render rather than
+ * silently doing nothing until the user happens to trigger the next one.
+ */
+export function registerAttribute(handler: AttributeHandler): void {
+  if (!handler || typeof handler !== "object") {
+    logger.warn("registerAttribute: expected a handler object, got", handler);
+    return;
+  }
+
+  const declarative = isDeclarative(handler);
+  if (declarative && (handler as any).selectors) {
+    logger.warn(
+      `registerAttribute("${handlerName(handler)}"): a handler declares either ` +
+        `\`attribute\` (declarative) or \`selectors\` (low-level), never both. Ignored.`
+    );
+    return;
+  }
+  if (
+    !declarative &&
+    (!Array.isArray((handler as LowLevelHandler).selectors) ||
+      typeof (handler as LowLevelHandler).setup !== "function")
+  ) {
+    logger.warn(
+      "registerAttribute: a handler declares either an `attribute` name (declarative) " +
+        "or a `selectors` array with a setup() function (low-level). Ignored."
+    );
+    return;
+  }
+  // Checked at runtime as well as in the type, because this API is reachable
+  // from a plain <script> where no type ever ran. Without a name a low-level
+  // handler cannot be named in any diagnostic, and is invisible to the
+  // duplicate-registration warning — silently, which is the one outcome this
+  // registry's diagnostics exist to prevent.
+  if (!declarative && !handler.name) {
+    logger.warn(
+      "registerAttribute: a low-level handler must supply `name` — it is what " +
+        "diagnostics identify it by, and `selectors` is descriptive. Ignored."
+    );
+    return;
+  }
+
+  if (declarative) {
+    const d = handler as DeclarativeHandler;
+    // A declarative handler is tracked by the scan, and the scan only runs for
+    // handlers with something to call on a match. So onElementRemoved on its
+    // own can never fire: nothing is ever tracked, so nothing is ever swept.
+    // All three callbacks are optional, so this shape type-checks — which makes
+    // rejecting it loudly the only thing standing between the author and a
+    // handler that does nothing forever.
+    if (!d.onElementAdded && !d.onElement) {
+      logger.warn(
+        `registerAttribute("${handlerName(handler)}"): a declarative handler needs ` +
+          `onElementAdded or onElement — ` +
+          (d.onElementRemoved
+            ? `onElementRemoved alone can never fire, because elements are only tracked when one of the other two claims them.`
+            : `it declares no callbacks at all.`) +
+          ` Ignored.`
+      );
+      return;
+    }
+  }
+
+  let selector = "";
+  if (declarative) {
+    selector = lvtSelector((handler as DeclarativeHandler).attribute);
+    // Validate ONCE, here, rather than discovering it on every render.
+    // lvtSelector escapes ':' — the character that actually appears in lvt-*
+    // names — but a name containing ']' or a quote would close the attribute
+    // selector early and make querySelectorAll throw SyntaxError on every
+    // render for the life of the page. Rejecting at registration turns a
+    // recurring render-time crash into one warning the author can act on.
+    //
+    // Skipped when there is no DOM. Registration itself is deliberately
+    // DOM-free — which is why `registerBuiltinHandlers()` can run at module
+    // load with no `typeof window` guard, unlike autoInit() — and this probe
+    // was the one exception. A module imported by SSR or tooling must not throw
+    // on a declarative registration; the check still runs for every
+    // registration that happens in a browser, which is every registration that
+    // can reach a render.
+    if (typeof document !== "undefined") {
+      try {
+        document.createDocumentFragment().querySelector(selector);
+      } catch {
+        logger.warn(
+          `registerAttribute("${handlerName(handler)}"): not a usable attribute name — ` +
+            `it does not form a valid CSS attribute selector (${selector}). Ignored.`
+        );
+        return;
+      }
+    }
+  }
+
+  // Duplicate claim warning. Deliberately LAST, after every rejection above:
+  // it says "both will run", which is only true of a handler that is actually
+  // about to be accepted. Warning earlier meant a handler that reused a name
+  // AND was invalid got told both would run immediately before being rejected.
+  //
+  // Keyed on the declarative attribute name and the resolved handler name —
+  // never on `selectors`, which is descriptive and which two built-ins
+  // legitimately set to a bare "*" walk.
+  //
+  // Case-folded because HTML parsers ASCII-lowercase attribute names, so
+  // `lvt-x:doThing` and `lvt-x:dothing` are the same attribute in the DOM even
+  // though they are different strings here. The scan relies on the same fact
+  // from the other side: it never normalizes case, because CSS attribute
+  // selectors match attribute NAMES ASCII-case-insensitively in HTML documents.
+  // Both halves therefore assume an HTML document — in an XML or standalone SVG
+  // context neither assumption holds, and the two would have to agree some
+  // other way.
+  const key = claimKey(handler);
+  if (key !== null && registry.some((existing) => claimKey(existing) === key)) {
+    logger.warn(
+      `registerAttribute("${handlerName(handler)}"): another handler already claims this ` +
+        `name. Both will run; the earlier registration is not replaced. Third-party ` +
+        `attributes should avoid the lvt-fx:/lvt-el:/lvt-form: namespaces.`
+    );
+  }
+
+  resolved.set(handler, { category: deriveCategory(handler), selector });
+
+  registry.push(handler);
+
+  // Late-registration catch-up.
+  //
+  // Deliberately NOT gated on `shouldRun`: category answers "did this render
+  // change enough to be worth re-running?", and registration is not a render.
+  // A handler that has never run has everything to do, whatever its category.
+  for (const liveRoot of liveRoots) {
+    const root = liveRoot.root();
+    if (!root) continue;
+    runHandler(handler, { scanRoot: root, wrapperRoot: root }, liveRoot.send);
+  }
+}
+
+/**
+ * There is deliberately no `unregisterAttribute` in Phase 1.
+ *
+ * Registration is append-only and duplicates both run (see the warning in
+ * registerAttribute), which is correct for the documented `<script defer>`
+ * production pattern where a bundle evaluates once. It is NOT sufficient for a
+ * dev server that hot-reloads a handler bundle: each reload registers again and
+ * the old handler keeps firing.
+ *
+ * Deferred rather than overlooked, because removal is not the one-liner it
+ * looks like — it has to sweep the handler's tracked elements and fire
+ * `onElementRemoved` for each, or the listeners the handler wired outlive the
+ * handler itself, which is the exact leak the declarative layer exists to
+ * prevent. That is a public-API design question, and Phase 3 is where the
+ * public API is settled.
+ */
+
+/**
+ * A snapshot of the registered handlers, for inspection.
+ *
+ * A COPY, not the live array. `readonly` is erased at compile time, so handing
+ * out the real one lets any caller push into the registry or reorder it. The
+ * render, teardown and dispose paths deliberately do not use this — they call
+ * the runRegisteredHandlers / teardownRegisteredHandlers /
+ * disposeRegisteredHandlers helpers below, which iterate the internal array
+ * directly and so allocate nothing on the hot path.
+ */
+export function getRegisteredAttributes(): readonly AttributeHandler[] {
+  return registry.slice();
+}
+
+/**
+ * Runs every registered handler for one render.
+ *
+ * The registry iterates itself rather than exporting its array for a caller to
+ * loop over: it keeps the internal array unreachable, and it means the render
+ * path costs no allocation. The array is read LIVE here, so a handler
+ * registered by a bundle that loaded after core participates from its very next
+ * render.
+ */
+export function runRegisteredHandlers(
+  roots: { scanRoot: Element; wrapperRoot: Element },
+  send: SendFn,
+  domChanged: boolean
+): void {
+  runHandlers(registry, roots, send, domChanged);
+}
+
+/** Tears every registered handler down against one root. */
+export function teardownRegisteredHandlers(root: Element): void {
+  for (const handler of registry) {
+    teardownHandler(handler, root);
+  }
+}
+
+/** Runs every registered handler's root-less cleanup. */
+export function disposeRegisteredHandlers(): void {
+  disposeHandlers(registry);
+}
+
+/**
+ * Test-only: empties the registry and detaches every live root.
+ *
+ * Element tracking is not cleared and does not need to be: it is keyed by
+ * handler object, so a discarded handler's entry is unreachable.
+ */
+export function __resetRegistryForTesting(): void {
+  registry.length = 0;
+  liveRoots.clear();
+}
+
+/** Attaches a live client so late registration has somewhere to catch up to. */
+export function attachRegistryRoot(root: RegistryRoot): void {
+  liveRoots.add(root);
+}
+
+export function detachRegistryRoot(root: RegistryRoot): void {
+  liveRoots.delete(root);
+}
+
+/**
+ * Whether any client is still attached.
+ *
+ * Exists so a disconnecting client can tell whether it is the LAST one, which
+ * is the condition for running `dispose()`. Module-global handler state outlives
+ * any single client, so tearing it down while another client is still rendering
+ * through the same handler would break that client.
+ */
+export function hasLiveRoots(): boolean {
+  return liveRoots.size > 0;
+}
+
+/**
+ * Runs one handler against one root. `send` is passed separately from the
+ * context so it can be withheld from handlers that didn't ask for it — a
+ * handler without `needsServerChannel` never sees a transport.
+ */
+export function runHandler(
+  handler: AttributeHandler,
+  roots: { scanRoot: Element; wrapperRoot: Element },
+  send: SendFn,
+  domChanged = true
+): void {
+  const channel = handler.needsServerChannel ? send : undefined;
+
+  if (!isDeclarative(handler)) {
+    if (!shouldRun(handler, domChanged)) return;
+    // setup() is third-party code on the public path, so it gets the same
+    // isolation as every other hook: one handler throwing must not strand the
+    // handlers registered after it, nor abort the rest of the render (the
+    // event delegator, the upload wiring and the change auto-wirer all run
+    // after this loop).
+    try {
+      handler.setup({ scanRoot: roots.scanRoot, wrapperRoot: roots.wrapperRoot, send: channel });
+    } catch (error) {
+      reportHookError(handler, "setup", error);
+    }
+    return;
+  }
+
+  // A declarative handler ALWAYS sweeps, whatever its category, and scans only
+  // when the render earned it. The two halves have opposite cost profiles and
+  // opposite failure modes:
+  //
+  //   sweep — O(tracked) with two O(1) reads per element. Skipping it leaves a
+  //           disarmed element holding its listeners, which is a correctness
+  //           bug and the single most common failure in the hardcoded handlers
+  //           this registry replaced.
+  //   scan  — a querySelectorAll walk. Skipping it costs nothing when nothing
+  //           was added, which is exactly what `wire-idempotent` is for.
+  //
+  // Gating both on the category broke the most natural handler shape there is:
+  // onElementAdded + onElementRemoved derives `wire-idempotent`, so removal
+  // notifications were deferred to the next render that happened to add a node.
+  // Worse, the flag can never see the render that matters — the morphdom hook
+  // that sets `directiveTouchedThisRender` inspects the NEW element's
+  // attributes, so it detects an attribute being added and never one being
+  // removed.
+  const seen = trackedMap(handler);
+  sweep(handler, seen);
+
+  if (!shouldRun(handler, domChanged)) return;
+  dispatchDeclarative(handler, roots, seen, channel);
+}
+
+/**
+ * Runs a list of handlers against one root, skipping those the render did not
+ * earn.
+ *
+ * The gate and the dispatch belong together: exporting only the two halves
+ * invites every caller — including tests — to hand-copy the loop that joins
+ * them, and a hand-copied loop in a test silently stops pinning the production
+ * one the moment either changes.
+ */
+export function runHandlers(
+  handlers: readonly AttributeHandler[],
+  roots: { scanRoot: Element; wrapperRoot: Element },
+  send: SendFn,
+  domChanged: boolean
+): void {
+  for (const handler of handlers) {
+    runHandler(handler, roots, send, domChanged);
+  }
+}
+
+/**
+ * Runs every handler's root-less cleanup. Called unconditionally on disconnect,
+ * including when there is no wrapper element to scope a teardown to.
+ */
+export function disposeHandlers(handlers: readonly AttributeHandler[]): void {
+  for (const handler of handlers) {
+    if (!handler.dispose) continue;
+    try {
+      handler.dispose();
+    } catch (error) {
+      reportHookError(handler, "dispose", error);
+    }
+  }
+}
+
+/**
+ * Runs the teardown side of one handler against one root.
+ *
+ * For a declarative handler this means sweeping every tracked element, which is
+ * what makes `onElementRemoved` a reliable cleanup hook rather than a
+ * best-effort one.
+ */
+export function teardownHandler(handler: AttributeHandler, root: Element): void {
+  if (!isDeclarative(handler)) {
+    handler.teardown?.(root);
+    return;
+  }
+  const map = trackedMap(handler);
+  if (!handler.onElementRemoved && map.size === 0) return;
+  for (const el of Array.from(map.keys())) {
+    if (root.contains(el) || !el.isConnected) {
+      map.delete(el);
+      notifyRemoved(handler, el);
+    }
+  }
+}
+
+/**
+ * A third-party callback throwing must not abort the render or strand the
+ * handlers registered after it — the registry is a public extension point, so
+ * other people's code runs in this loop.
+ */
+function reportHookError(handler: AttributeHandler, hook: string, error: unknown): void {
+  logger.error(`${handlerName(handler)}.${hook}() threw:`, error);
+}
+
+function notifyRemoved(handler: DeclarativeHandler, el: Element): void {
+  if (!handler.onElementRemoved) return;
+  try {
+    handler.onElementRemoved(el);
+  } catch (error) {
+    reportHookError(handler, "onElementRemoved", error);
+  }
+}
+
+function dispatchDeclarative(
+  handler: DeclarativeHandler,
+  roots: { scanRoot: Element; wrapperRoot: Element },
+  seen: Map<Element, ElementEntry>,
+  channel: SendFn | undefined
+): void {
+  const attribute = handler.attribute;
+
+  // Hoisted: a wiring-only handler declares no onElement, and checking that
+  // per element per render costs a branch and a closure for nothing.
+  const wantsAdded = !!handler.onElementAdded;
+  const wantsEvery = !!handler.onElement;
+  if (!wantsAdded && !wantsEvery) return;
+
+  // querySelectorAll returns a STATIC NodeList, so it is safe to iterate
+  // directly even though the callbacks below can mutate the DOM.
+  const matches = roots.scanRoot.querySelectorAll<Element>(resolved.get(handler)!.selector);
+  for (const el of matches) {
+    let entry = seen.get(el);
+
+    if (entry) {
+      // Refresh before any callback runs: a reconnect hands in a new transport,
+      // and a cross-handler navigation replaces the wrapper.
+      entry.send = channel;
+      entry.wrapperRoot = roots.wrapperRoot;
+    } else {
+      // Every handler needed this check, so it stopped being the author's job.
+      if (!el.getAttribute(attribute)) {
+        const warned = warnedEmptySet(handler);
+        if (!warned.has(el)) {
+          warned.add(el);
+          logger.warn(
+            `${attribute} on <${el.tagName.toLowerCase()}> has an empty value; skipping. ` +
+              `An attribute handler's value is its configuration — an empty one is a template bug.`
+          );
+        }
+        continue;
+      }
+      warnedEmpty.get(handler)?.delete(el);
+      entry = { ctx: null as unknown as ElementContext, send: channel, wrapperRoot: roots.wrapperRoot };
+      entry.ctx = makeElementContext(handler, el, entry);
+      seen.set(el, entry);
+      if (wantsAdded) {
+        try {
+          handler.onElementAdded!(el, entry.ctx);
+        } catch (error) {
+          reportHookError(handler, "onElementAdded", error);
+        }
+      }
+    }
+
+    if (wantsEvery) {
+      try {
+        handler.onElement!(el, entry.ctx);
+      } catch (error) {
+        reportHookError(handler, "onElement", error);
+      }
+    }
+  }
+}
+
+/**
+ * Builds the per-element context ONCE. Every member is an accessor, which is
+ * what lets a single instance stay correct for the element's whole life:
+ * `value` re-reads the attribute after a server re-render, `send` follows a
+ * reconnect, and `wrapperRoot` follows a cross-handler navigation. A handler
+ * captures this object in a listener and keeps reading through it.
+ */
+function makeElementContext(
+  handler: DeclarativeHandler,
+  el: Element,
+  entry: ElementEntry
+): ElementContext {
+  return {
+    get value(): string {
+      return el.getAttribute(handler.attribute) || "";
+    },
+    get send(): SendFn | undefined {
+      return entry.send;
+    },
+    get wrapperRoot(): Element {
+      return entry.wrapperRoot;
+    },
+  };
+}
+
+/**
+ * Drops elements that detached from the document or lost the attribute via a
+ * server diff, notifying the handler about each.
+ *
+ * Runs on every render, including ones no scan is performed for: an attribute
+ * can be removed by a diff that adds nothing, and a handler that keeps firing
+ * for an element the server has disarmed is the single most common bug in the
+ * hardcoded handlers this registry replaced. See runHandler for why the sweep
+ * and the scan are gated differently. The cost is two O(1) reads per tracked
+ * element per render.
+ *
+ * Snapshotting the keys is deliberate: the loop calls third-party code that may
+ * itself touch the DOM, and iterating a Map while a callback mutates it is not
+ * a contract worth exporting.
+ */
+function sweep(handler: DeclarativeHandler, seen: Map<Element, ElementEntry>): void {
+  if (seen.size === 0) return;
+  for (const el of Array.from(seen.keys())) {
+    // An element counts as armed iff it is in the document AND its attribute
+    // still carries a value. Emptying the value is treated exactly like
+    // removing the attribute, which is the same rule the scan applies when it
+    // decides whether to track an element in the first place: a handler's value
+    // is its configuration, so no configuration means not armed. Without this
+    // the two halves disagree — the scan refuses to arm an empty element while
+    // the sweep insists an emptied one is still live — and a handler wired for
+    // `{{.ShareURL}}` keeps its listeners after the URL goes away.
+    if (el.isConnected && el.getAttribute(handler.attribute)) continue;
+    seen.delete(el);
+    notifyRemoved(handler, el);
+  }
+}
diff --git a/dom/builtin-handlers.ts b/dom/builtin-handlers.ts
new file mode 100644
index 0000000..b5ab894
--- /dev/null
+++ b/dom/builtin-handlers.ts
@@ -0,0 +1,236 @@
+/**
+ * The built-in `lvt-*` attribute handlers, expressed as registry entries.
+ *
+ * Every handler here goes through the SAME public interface an external author
+ * uses — that is the point of the file. There is no privileged internal path:
+ * if a built-in needs something `AttributeHandler` can't express, that is a gap
+ * in the public API, not a reason for a side door.
+ *
+ * All of them use the LOW-LEVEL layer (`selectors` + `setup`/`teardown`), not
+ * the declarative one. They predate the registry, their bodies are unchanged by
+ * the migration, and `tests/directives.test.ts` calls those bodies directly —
+ * so keeping the functions intact is what makes the existing suite a regression
+ * net for this refactor rather than a casualty of it. New handlers, and the
+ * ones that move to their owning app in Phase 4, should prefer the declarative
+ * layer.
+ *
+ * `selectors` is descriptive here: the loop dispatches by calling `setup()`,
+ * never by reading the array. It documents what the handler claims, for a human
+ * and for the duplicate-registration warning. Two entries below legitimately
+ * walk every descendant and say so.
+ *
+ * REGISTRATION ORDER IS BEHAVIOUR. These register in exactly the order the
+ * hardcoded post-render sequence called them, because a handler that flashes a
+ * highlight and one that scrolls the same element are not commutative.
+ */
+
+import { registerAttribute, type AttributeHandler } from "../attribute-registry";
+import {
+  handleAnimateDirectives,
+  handleAreaSelectDirectives,
+  handleAutoClickDirectives,
+  handleHighlightDirectives,
+  handleIframeAutoHeightDirectives,
+  handlePreviewBridgeDirectives,
+  handleProxyBridgeDirectives,
+  handleRegionSelectDirectives,
+  handleScrollDirectives,
+  handleShadowRootHydration,
+  handleTextSelectDirectives,
+  handleToastDirectives,
+  handleURLHashDirective,
+  handleViewportReportDirectives,
+  setupFxDOMEventTriggers,
+  teardownAreaSelectForRoot,
+  teardownAutoClickTimers,
+  teardownFxDOMEventTriggers,
+  teardownIframeAutoHeightForRoot,
+  teardownPreviewBridgeForRoot,
+  teardownProxyBridgeForRoot,
+  teardownRegionSelectForRoot,
+  teardownTextSelectForRoot,
+  teardownURLHashForRoot,
+  teardownViewportReportForRoot,
+} from "./directives";
+import { handleResizeDirectives, teardownResizeForRoot } from "./resize";
+import { setupScrollAway, teardownScrollAway } from "./scroll-away";
+import { setupSpy, teardownSpy } from "./spy";
+
+/**
+ * Every built-in, in the order the hardcoded post-render sequence called them.
+ *
+ * The order is PRESERVED rather than asserted to matter: this migration's bar
+ * is that nothing changes behaviour, and reordering would be a change made
+ * without evidence. No non-commuting pair is currently known.
+ *
+ * Phase 4 will test that: the handlers marked below as relocating move to a
+ * bundle that necessarily evaluates AFTER core, so they will register last
+ * rather than in the middle. If that turns out to matter for any pair, order
+ * has to become something the interface expresses — a coarse stable-sorted
+ * phase, never integer priorities, which in a public registry become a z-index
+ * war. If it does not matter, this note can go.
+ */
+const builtinHandlers: AttributeHandler[] = [
+  // ---- core: referenced by code the framework ships, or by 2+ apps ----
+  {
+    name: "lvt-fx:scroll",
+    selectors: ["[lvt-fx\\:scroll]"],
+    setup: ({ scanRoot }) => handleScrollDirectives(scanRoot),
+  },
+  {
+    name: "lvt-fx:highlight",
+    selectors: ["[lvt-fx\\:highlight]"],
+    setup: ({ scanRoot }) => handleHighlightDirectives(scanRoot),
+  },
+  {
+    name: "lvt-fx:animate",
+    selectors: ["[lvt-fx\\:animate]"],
+    setup: ({ scanRoot }) => handleAnimateDirectives(scanRoot),
+  },
+  {
+    // Claims [data-toast-trigger] and the toast stack, not an lvt-* name: the
+    // framework emits the markers itself from lvt/components/toast.
+    name: "lvt-toast-stack",
+    selectors: ["[data-toast-trigger]", "[data-lvt-toast-stack]"],
+    setup: ({ scanRoot }) => handleToastDirectives(scanRoot),
+  },
+
+  // ---- relocating to prereview in Phase 4 ----
+  //
+  // Their only consumer is prereview. They register through the public
+  // interface from this repo today so that Phase 4 is a file move rather than a
+  // rewrite. Six of them are the `needsServerChannel` path's real consumers —
+  // no core handler exercises that flag, so without these it would ship
+  // untried.
+  {
+    name: "lvt-fx:auto-click",
+    selectors: ["[lvt-fx\\:auto-click]"],
+    setup: ({ scanRoot }) => handleAutoClickDirectives(scanRoot),
+    // dispose(), not teardown(root): the timers this arms are module-global,
+    // so there is no root to scope their cleanup to. dispose() runs on every
+    // disconnect, including one with no wrapper element — which is what the
+    // hardcoded teardownAutoClickTimers() call used to guarantee.
+    dispose: () => teardownAutoClickTimers(),
+  },
+  {
+    name: "lvt-fx:area-select",
+    selectors: ["[lvt-fx\\:area-select]"],
+    needsServerChannel: true,
+    setup: ({ scanRoot, send }) => handleAreaSelectDirectives(scanRoot, send!),
+    teardown: (root) => teardownAreaSelectForRoot(root),
+  },
+  {
+    name: "lvt-fx:resize",
+    selectors: ["[lvt-fx\\:resize]"],
+    setup: ({ scanRoot }) => handleResizeDirectives(scanRoot),
+    teardown: (root) => teardownResizeForRoot(root),
+  },
+  {
+    name: "lvt-fx:region-select",
+    selectors: ["[lvt-fx\\:region-select]"],
+    needsServerChannel: true,
+    setup: ({ scanRoot, send }) => handleRegionSelectDirectives(scanRoot, send!),
+    teardown: (root) => teardownRegionSelectForRoot(root),
+  },
+  {
+    name: "lvt-fx:text-select",
+    selectors: ["[lvt-fx\\:text-select]"],
+    needsServerChannel: true,
+    setup: ({ scanRoot, send }) => handleTextSelectDirectives(scanRoot, send!),
+    teardown: (root) => teardownTextSelectForRoot(root),
+  },
+  {
+    name: "lvt-fx:viewport-report",
+    selectors: ["[lvt-fx\\:viewport-report]"],
+    needsServerChannel: true,
+    setup: ({ scanRoot, send }) => handleViewportReportDirectives(scanRoot, send!),
+    teardown: (root) => teardownViewportReportForRoot(root),
+  },
+  {
+    name: "lvt-fx:proxy-bridge",
+    selectors: ["[lvt-fx\\:proxy-bridge]"],
+    needsServerChannel: true,
+    setup: ({ scanRoot, send }) => handleProxyBridgeDirectives(scanRoot, send!),
+    teardown: (root) => teardownProxyBridgeForRoot(root),
+  },
+  {
+    name: "lvt-fx:iframe-autoheight",
+    selectors: ["iframe[lvt-fx\\:iframe-autoheight]"],
+    setup: ({ scanRoot }) => handleIframeAutoHeightDirectives(scanRoot),
+    teardown: (root) => teardownIframeAutoHeightForRoot(root),
+  },
+  {
+    name: "lvt-fx:preview-bridge",
+    selectors: ["iframe[lvt-fx\\:preview-bridge]"],
+    setup: ({ scanRoot }) => handlePreviewBridgeDirectives(scanRoot),
+    teardown: (root) => teardownPreviewBridgeForRoot(root),
+  },
+  {
+    name: "lvt-fx:url-hash",
+    selectors: ["[lvt-fx\\:url-hash]"],
+    needsServerChannel: true,
+    setup: ({ scanRoot, send }) => handleURLHashDirective(scanRoot, send!),
+    teardown: (root) => teardownURLHashForRoot(root),
+  },
+
+  // ---- core, continued (these ran after the relocating group) ----
+  {
+    // A platform bridge, not an app feature: it activates Declarative Shadow
+    // DOM that morphdom inserted via DOM APIs, which don't auto-hydrate.
+    name: "shadow-root-hydration",
+    selectors: ["template[shadowrootmode]"],
+    setup: ({ scanRoot }) => handleShadowRootHydration(scanRoot),
+  },
+  {
+    name: "lvt-scroll-away",
+    selectors: ["[lvt-scroll-away]"],
+    setup: ({ scanRoot }) => setupScrollAway(scanRoot),
+    teardown: (root) => teardownScrollAway(root),
+  },
+  {
+    name: "lvt-spy",
+    selectors: ["[lvt-spy]"],
+    setup: ({ scanRoot }) => setupSpy(scanRoot),
+    teardown: (root) => teardownSpy(root),
+  },
+  {
+    // Walks every descendant to attach direct listeners for
+    // lvt-fx:<effect>:on:<domevent>, so it earns the wire-idempotent skip:
+    // at 80k descendants the walk costs ~150-200ms and re-running on an
+    // unchanged DOM finds nothing new.
+    name: "lvt-fx:*:on:*",
+    selectors: ["*"],
+    category: "wire-idempotent",
+    setup: ({ scanRoot, wrapperRoot }) => setupFxDOMEventTriggers(scanRoot, wrapperRoot),
+    teardown: (root) => teardownFxDOMEventTriggers(root),
+  },
+];
+
+let registered = false;
+
+/**
+ * Registers every built-in. Called once at module load, before any user code
+ * can run, so built-ins always occupy the earliest registry slots and a
+ * third-party handler claiming the same name is the one that gets warned about.
+ *
+ * Guarded, because the registry is module-level state and this is now a named
+ * entry point rather than inline top-of-file code. A page that evaluates the
+ * bundle twice — a duplicated <script>, a bundler that fails to dedupe — would
+ * otherwise register all eighteen handlers a second time, and the six that
+ * carry needsServerChannel would dispatch every action to the server twice.
+ * The duplicate-name warning would fire eighteen times on the way there, so it
+ * would not be silent, but a doubled action is not something to leave to a
+ * console warning.
+ */
+export function registerBuiltinHandlers(): void {
+  if (registered) return;
+  registered = true;
+  for (const handler of builtinHandlers) {
+    registerAttribute(handler);
+  }
+}
+
+/** Test-only: lets a suite re-register after clearing the registry. */
+export function __resetBuiltinRegistrationForTesting(): void {
+  registered = false;
+}
diff --git a/event-spec.ts b/event-spec.ts
new file mode 100644
index 0000000..ba2c0e4
--- /dev/null
+++ b/event-spec.ts
@@ -0,0 +1,84 @@
+/**
+ * The LiveTemplate client lifecycle event contract.
+ *
+ * These events already existed, dispatched from four different modules with no
+ * single place describing them. This file is that place: it is the stable
+ * contract a custom attribute handler programs against, and it is DESCRIPTIVE —
+ * every name and payload below is what the client dispatches today, not a
+ * proposal.
+ *
+ * Handlers observe these through the DOM, so there is no second interface to
+ * implement. `AttributeHandler` (see `attribute-registry.ts`) stays the only
+ * type an author implements; this one is here to be read, and to give the
+ * payloads names that survive a refactor.
+ *
+ * WHERE EACH EVENT IS DISPATCHED MATTERS. They do not all fire on the same
+ * node, and none of them bubble by default — a handler that listens on the
+ * wrapper will not see a form event, and vice versa. The `target` column below
+ * is part of the contract, not an implementation detail.
+ */
+
+import type { ResponseMetadata } from "./types";
+
+/**
+ * Action lifecycle, dispatched on the ACTIVE FORM by FormLifecycleManager.
+ *
+ *   lvt:done     — every response for a form action, success or failure, first.
+ *   lvt:success  — meta.success === true.
+ *   lvt:error    — meta.success === false; meta.errors carries the field errors.
+ */
+export type FormLifecycleEventName = "lvt:done" | "lvt:success" | "lvt:error";
+
+export type FormLifecycleEvent = CustomEvent<ResponseMetadata>;
+
+/**
+ * Dispatched on the ELEMENT THAT TRIGGERED an action, by the event delegator,
+ * at the moment the action is sent. `detail` is the outgoing action message.
+ */
+export type PendingEvent = CustomEvent<{ action: string; data?: unknown }>;
+
+/** Dispatched on the WRAPPER after every applied tree update. */
+export type UpdatedEvent = CustomEvent<{
+  messageCount: number;
+  action?: string;
+  success?: boolean;
+}>;
+
+/**
+ * Dispatched on the WRAPPER for a topic-level error envelope.
+ *
+ * Note the name collision, which is load-bearing to know about: `lvt:error` is
+ * ALSO the form-lifecycle failure event, with a completely different payload
+ * (`ResponseMetadata` vs `{code, topic}`) on a different target (the form vs
+ * the wrapper). A listener bound to `document` in the capture phase sees both.
+ * Documented rather than changed — renaming either one is a wire-visible
+ * behaviour change and belongs to its own release, not to a refactor.
+ */
+export type TopicErrorEvent = CustomEvent<{ code: string; topic?: string }>;
+
+/** Transport state, dispatched on the WRAPPER as plain (detail-less) Events. */
+export type ConnectionEventName = "lvt:connected" | "lvt:disconnected" | "lvt:reconnected";
+
+/** Upload progress, dispatched on the WRAPPER. */
+export type UploadEventName = "lvt:upload:progress" | "lvt:upload:complete" | "lvt:upload:error";
+
+/**
+ * Every lifecycle event name the client dispatches, for a handler that wants to
+ * subscribe defensively (or a test that wants to assert the surface hasn't
+ * grown silently).
+ */
+export const LIFECYCLE_EVENTS = [
+  "lvt:pending",
+  "lvt:done",
+  "lvt:success",
+  "lvt:error",
+  "lvt:updated",
+  "lvt:connected",
+  "lvt:disconnected",
+  "lvt:reconnected",
+  "lvt:upload:progress",
+  "lvt:upload:complete",
+  "lvt:upload:error",
+] as const;
+
+export type LifecycleEventName = (typeof LIFECYCLE_EVENTS)[number];
diff --git a/livetemplate-client.ts b/livetemplate-client.ts
index fc77117..7760d75 100644
--- a/livetemplate-client.ts
+++ b/livetemplate-client.ts
@@ -8,36 +8,11 @@
 import morphdom from "morphdom";
 import { FocusManager } from "./dom/focus-manager";
 import {
-  handleAnimateDirectives,
-  handleAreaSelectDirectives,
-  handleAutoClickDirectives,
-  handleHighlightDirectives,
-  handleIframeAutoHeightDirectives,
-  handlePreviewBridgeDirectives,
-  handleProxyBridgeDirectives,
-  handleRegionSelectDirectives,
-  handleTextSelectDirectives,
-  handleViewportReportDirectives,
-  handleScrollDirectives,
-  handleShadowRootHydration,
-  handleToastDirectives,
   handleURLHashDirective,
-  teardownAreaSelectForRoot,
-  teardownIframeAutoHeightForRoot,
-  teardownPreviewBridgeForRoot,
-  teardownProxyBridgeForRoot,
-  teardownRegionSelectForRoot,
-  teardownTextSelectForRoot,
-  teardownViewportReportForRoot,
-  teardownURLHashForRoot,
-  teardownAutoClickTimers,
   setupToastClickOutside,
-  setupFxDOMEventTriggers,
-  teardownFxDOMEventTriggers,
-  setupFxLifecycleListeners,
   teardownFxLifecycleListeners,
+  setupFxLifecycleListeners,
 } from "./dom/directives";
-import { handleResizeDirectives, teardownResizeForRoot } from "./dom/resize";
 import { EventDelegator } from "./dom/event-delegation";
 import { LinkInterceptor } from "./dom/link-interceptor";
 import { ObserverManager } from "./dom/observer-manager";
@@ -47,9 +22,23 @@ import { setupReactiveAttributeListeners } from "./dom/reactive-attributes";
 import { preserveOneShotGuards, reapplyClientOwnedState } from "./dom/client-owned-state";
 import { setupInvokerPolyfill } from "./dom/invoker-polyfill";
 import { setupHashLink, teardownHashLink, openFromHash, safeMatchesPopoverOpen } from "./dom/hash-link";
-import { setupScrollAway, teardownScrollAway } from "./dom/scroll-away";
-import { setupSpy, teardownSpy } from "./dom/spy";
 import { hydrateRedactedTokens } from "./dom/redact";
+import {
+  attachRegistryRoot,
+  detachRegistryRoot,
+  disposeHandlers,
+  disposeRegisteredHandlers,
+  hasLiveRoots,
+  registerAttribute,
+  runHandlers,
+  runRegisteredHandlers,
+  teardownRegisteredHandlers,
+  teardownHandler,
+  type AttributeHandler,
+  type RegistryRoot,
+  type SendFn,
+} from "./attribute-registry";
+import { registerBuiltinHandlers } from "./dom/builtin-handlers";
 import { TreeRenderer } from "./state/tree-renderer";
 import {
   RangeDomApplier,
@@ -77,6 +66,34 @@ import { createLogger, Logger } from "./utils/logger";
 export { loadAndApplyUpdate, compareHTML } from "./utils/testing";
 export { setupReactiveAttributeListeners } from "./dom/reactive-attributes";
 
+// The public attribute-handler API. `registerAttribute` MUST be a module-level
+// named export, not only a class static: the browser build runs
+// `--global-name=LiveTemplateClient` over this module, so `window.LiveTemplateClient`
+// is the module NAMESPACE object and `LiveTemplateClient.registerAttribute(...)`
+// — the spelling every doc example uses — resolves to this export. The class
+// itself sits at `LiveTemplateClient.LiveTemplateClient` in that build.
+export { registerAttribute } from "./attribute-registry";
+export { LIFECYCLE_EVENTS } from "./event-spec";
+export type {
+  LifecycleEventName,
+  FormLifecycleEvent,
+  FormLifecycleEventName,
+  PendingEvent,
+  UpdatedEvent,
+  TopicErrorEvent,
+  ConnectionEventName,
+  UploadEventName,
+} from "./event-spec";
+export type {
+  AttributeHandler,
+  DeclarativeHandler,
+  LowLevelHandler,
+  ElementContext,
+  SetupContext,
+  SendFn,
+  HandlerCategory,
+} from "./attribute-registry";
+
 export class LiveTemplateClient {
   private readonly treeRenderer: TreeRenderer;
   private readonly rangeDomApplier: RangeDomApplier;
@@ -107,6 +124,38 @@ export class LiveTemplateClient {
   private uploadHandler: UploadHandler;
   private changeAutoWirer: ChangeAutoWirer;
 
+  /**
+   * Built-in handlers that close over a per-client object rather than module
+   * state, so they cannot live in the module-level registry. Kept separate
+   * (not registered) so that two clients on one page don't register the same
+   * handler twice, and so the public registry stays exactly what the page
+   * declared.
+   */
+  private instanceHandlers: AttributeHandler[];
+
+  /**
+   * One `send` for the client's whole life, so the per-render dispatch does not
+   * allocate a closure on every render. It delegates to `this.send`, which
+   * resolves the transport at call time — so a context holding this stays
+   * correct across a reconnect without the registry re-keying anything.
+   */
+  private readonly boundSend: SendFn = (message) => this.send(message);
+
+  /**
+   * This client's face to the registry, so a handler registered AFTER connect
+   * can immediately catch up against the live DOM instead of waiting for the
+   * next render. An accessor, not a field: the wrapper is reassigned on
+   * cross-handler navigation, so reading it at call time is what keeps a
+   * late-registered handler pointed at the current one.
+   */
+  private registryRoot: RegistryRoot = {
+    root: () => this.wrapperElement,
+    // Reuses boundSend rather than allocating a second identical closure.
+    // Field initializers run in declaration order, so boundSend above is
+    // already assigned, and it is readonly — this cannot go stale.
+    send: this.boundSend,
+  };
+
   // Initialization tracking for loading indicator
   private isInitialized: boolean = false;
 
@@ -196,6 +245,17 @@ export class LiveTemplateClient {
       ...restOptions,
     };
 
+    this.instanceHandlers = [
+      {
+        // File-input upload wiring. An attribute scan like any other, but it
+        // needs this client's UploadHandler, so it is instance-bound.
+        name: "lvt-upload",
+        selectors: ['input[type="file"][lvt-upload]'],
+        category: "wire-idempotent",
+        setup: ({ scanRoot }) => this.uploadHandler.initializeFileInputs(scanRoot),
+      },
+    ];
+
     this.treeRenderer = new TreeRenderer(this.logger.child("TreeRenderer"));
     this.rangeDomApplier = new RangeDomApplier({
       logger: this.logger.child("RangeDomApplier"),
@@ -379,6 +439,27 @@ export class LiveTemplateClient {
    * Auto-initialize when DOM is ready
    * Called automatically when script loads
    */
+  /**
+   * Registers a custom `lvt-*` attribute handler.
+   *
+   * Static, not an instance method, and that is not an accident: under the
+   * documented `<script defer>` load pattern autoInit() has already
+   * constructed and connected a client by the time a second script evaluates,
+   * so there is no pre-init instance to call a method on — and a separate IIFE
+   * bundle reaches core only through the global. Registering after a client
+   * exists is fully supported: the handler catches up against every live
+   * wrapper immediately.
+   *
+   * Mirrors the module-level `registerAttribute` export. The IIFE build sets
+   * `--global-name=LiveTemplateClient` on the module namespace, so a page
+   * script calls `LiveTemplateClient.registerAttribute(handler)` and reaches
+   * the named export; this static is the path for ESM consumers who imported
+   * the class alone.
+   */
+  static registerAttribute(handler: AttributeHandler): void {
+    registerAttribute(handler);
+  }
+
   static autoInit(): void {
     const autoInitLogger = createLogger({ scope: "Client:autoInit" });
     const init = () => {
@@ -691,9 +772,27 @@ export class LiveTemplateClient {
     // available` fallback that posts via HTTP, so the initial-arm
     // dispatch always reaches the server — no "best-effort" caveat.
     if (this.wrapperElement) {
+      // Connect-time arming, deliberately NOT the registry pass. Page load
+      // produces no updateDOM call, so a handler that only runs post-render
+      // never arms and a `#path:L4` URL is ignored until something else
+      // triggers a render.
+      //
+      // url-hash is not alone in needing this — initializeFileInputs above has
+      // the identical requirement for SSR'd inputs (issue #453), and so would
+      // any third-party handler over server-rendered markup. That makes
+      // connect-time arming a lifecycle phase the interface should express
+      // (an opt-in flag, with late registration's catch-up gated on the same
+      // predicate) rather than two hardcoded calls. Deferred to Phase 3: doing
+      // it here would move these calls relative to the rest of connect(), and
+      // this phase's bar is that nothing changes behaviour.
       handleURLHashDirective(this.wrapperElement, (message) => this.send(message));
     }
 
+    // Make this client visible to the registry, so a handler registered after
+    // connect catches up against the live DOM immediately rather than waiting
+    // for a render that may never come. Idempotent: the registry holds a Set.
+    attachRegistryRoot(this.registryRoot);
+
     // Set up lifecycle listeners for lvt-fx:*:on:{lifecycle} attributes
     setupFxLifecycleListeners(this.wrapperElement);
 
@@ -721,23 +820,37 @@ export class LiveTemplateClient {
     this.uploadHandler.revokePreviews();
     this.eventDelegator.teardownDOMEventTriggerDelegation();
     teardownHashLink();
-    teardownAutoClickTimers();
     this.loadingIndicator.disablePerActionIndicator();
     if (this.wrapperElement) {
-      teardownFxDOMEventTriggers(this.wrapperElement);
+      // Mirror of the post-render loop: every registered handler gets its
+      // teardown, in registration order. A handler that can be registered but
+      // not torn down is half an interface — and Phase 4 cannot relocate a
+      // handler whose cleanup is still named in core.
+      teardownRegisteredHandlers(this.wrapperElement);
+      for (const handler of this.instanceHandlers) {
+        teardownHandler(handler, this.wrapperElement);
+      }
+      // Connect-time, not per-render: setupFxLifecycleListeners is wired once
+      // in connect(), so it is not a registry entry and needs its own teardown.
       teardownFxLifecycleListeners(this.wrapperElement);
-      teardownScrollAway(this.wrapperElement);
-      teardownSpy(this.wrapperElement);
-      teardownAreaSelectForRoot(this.wrapperElement);
-      teardownResizeForRoot(this.wrapperElement);
-      teardownRegionSelectForRoot(this.wrapperElement);
-      teardownTextSelectForRoot(this.wrapperElement);
-      teardownViewportReportForRoot(this.wrapperElement);
-      teardownProxyBridgeForRoot(this.wrapperElement);
-      teardownIframeAutoHeightForRoot(this.wrapperElement);
-      teardownPreviewBridgeForRoot(this.wrapperElement);
-      teardownURLHashForRoot(this.wrapperElement);
     }
+    detachRegistryRoot(this.registryRoot);
+
+    // Root-less cleanup, deliberately outside the wrapper guard above: a
+    // handler whose state is module-global still has to be cleaned up when the
+    // client disconnects without ever having had a wrapper.
+    //
+    // instanceHandlers belong to THIS client, so they dispose unconditionally.
+    // The module registry is shared by every client on the page, so its
+    // handlers' global state may only be torn down once the last client has
+    // detached — which is why this runs after detachRegistryRoot rather than
+    // before it. In the single-client case autoInit produces, the two are the
+    // same moment.
+    disposeHandlers(this.instanceHandlers);
+    if (!hasLiveRoots()) {
+      disposeRegisteredHandlers();
+    }
+
     this.resetSessionState();
   }
 
@@ -2200,102 +2313,40 @@ export class LiveTemplateClient {
     // Restore focus to previously focused element
     this.focusManager.restoreFocusedElement();
 
-    // Two classes of post-render scans:
-    //
-    //   FIRE-ON-CHANGE (always run): handleScrollDirectives,
-    //   handleHighlightDirectives, handleAnimateDirectives,
-    //   handleToastDirectives, setupScrollAway. These detect VALUE changes
-    //   on existing directive-bearing elements (e.g. lvt-fx:highlight
-    //   flashes on every render where the underlying value changed) — so
-    //   they must run on every render. Cost is bounded: each does a CSS
-    //   attribute selector qsa for its specific directive (`[lvt-fx\:highlight]`
-    //   etc.); for a 10k-row LargeTable where rows DON'T have these
-    //   directives, the qsa returns empty in ~1-3ms total.
+    // Post-render attribute pass.
     //
-    //   WIRE-IDEMPOTENT (skip when nothing new): setupFxDOMEventTriggers,
-    //   setupDOMEventTriggerDelegation, uploadHandler.initializeFileInputs.
-    //   These walk EVERY descendant via qsa("*") to attach event listeners
-    //   on lvt-fx:event:on:trigger / lvt-el: / file inputs. They have
-    //   per-element guards so re-running is safe but wasteful — at 80k
-    //   descendants the walk costs ~150-200ms each. Skip when neither
-    //   morphdom.onNodeAdded fired nor a new lvt-* directive attribute
-    //   appeared on any morphed element (tracked via onBeforeElUpdated).
-    handleScrollDirectives(element);
-    handleHighlightDirectives(element);
-    handleAnimateDirectives(element);
-    handleToastDirectives(element);
-    handleAutoClickDirectives(element);
-    // Area-select needs the send() callback to dispatch the final-
-    // coords action on pointerup, unlike the other directives in this
-    // block (which are visual-only or click-through). Reuse the same
-    // send the event delegator uses so the WS/HTTP routing is
-    // identical to a normal action.
-    handleAreaSelectDirectives(element, (message) => this.send(message));
-    // resize is client-only (updates a CSS var on :root + localStorage), so
-    // unlike area-select it needs no send() callback. Arm/sweep is idempotent
-    // so an in-flight drag survives a re-render.
-    handleResizeDirectives(element);
-    // region-select is the area-select drag spine over an iframe / code
-    // overlay: a drawn box is hit-tested to a source line range. Same
-    // send-callback wiring; the overlay is parent light DOM so it works
-    // on iOS (unlike the deleted in-iframe tap).
-    handleRegionSelectDirectives(element, (message) => this.send(message));
-    // text-select captures a native text selection over the diff and dispatches
-    // a character range (word / phrase / multi-line span). Same send-callback
-    // wiring; uses window.getSelection rather than a drawn box, so it covers
-    // mouse, touch, and keyboard from one path.
-    handleTextSelectDirectives(element, (message) => this.send(message));
-    // viewport-report tracks how far the reviewer has scrolled/read and reports
-    // the visible line keys to the server (read-progress). Same send wiring;
-    // dumb reporter, server owns the logic.
-    handleViewportReportDirectives(element, (message) => this.send(message));
-    // proxy-bridge is the --external live-site bridge: it relays the proxied
-    // page's nav (→ setProxyURL) and scroll (→ pin-layer transform, no server
-    // hop) from the cross-origin beacon. Same send-callback wiring; the only
-    // thing that reaches across the cross-origin boundary, read-only.
-    handleProxyBridgeDirectives(element, (message) => this.send(message));
-    // iframe-autoheight sizes the sandboxed HTML-preview iframe to its
-    // content (iframes don't size to content). Selection over the preview
-    // is handled by a parent-document overlay (area/region-select), not
-    // from inside the iframe, so this directive needs no send callback.
-    handleIframeAutoHeightDirectives(element);
-    // preview-bridge is the opaque-origin successor to iframe-autoheight for the
-    // HTML preview: the iframe runs the page's own scripts (sandbox=allow-scripts)
-    // so contentDocument is unreadable, and the in-iframe beacon posts the height
-    // (auto-size) + the [data-from] block rects (region-select hit-testing) out
-    // via postMessage. No send callback — it only caches + sizes; region-select
-    // does the sending.
-    handlePreviewBridgeDirectives(element);
-    // url-hash bridges server state ↔ location.hash. Same send-callback
-    // wiring as area-select: the directive needs to dispatch a server
-    // action on user-driven hashchange events (anchor click, address-bar
-    // edit, back-button) and read the latest server-rendered hash from
-    // `data-lvt-url-hash` on every render.
-    handleURLHashDirective(element, (message) => this.send(message));
-    // Hydrate any server-emitted Declarative Shadow DOM templates that
-    // morphdom inserted via DOM APIs (which don't auto-activate them).
-    // Cheap when no templates are present (one querySelectorAll).
+    // Every lvt-* attribute handler — built-in and third-party alike — is a
+    // registry entry, and this loop is the only thing that runs them. The
+    // registry is read LIVE on every render rather than snapshotted at
+    // construction, so a handler registered by a bundle that loaded after core
+    // participates from its very next render.
     //
-    // Hard limitation: livetemplate directives placed INSIDE shadow
-    // content (e.g. lvt-on:click on an element inside a `<template
-    // shadowrootmode>`) NEVER register, on any render. The directive
-    // sweeps above (setupFxDOMEventTriggers, eventDelegator) walk via
-    // querySelectorAll which stops at shadow boundaries, and the
-    // hydration that follows doesn't run them against the new shadow
-    // root either. Treat shadow DOM as a style/structure isolation
-    // primitive only — keep directives in light DOM. (Consumers that
-    // need a real viewport for untrusted markup — e.g. prereview's HTML
-    // preview — use a sandboxed iframe + handleIframeAutoHeightDirectives
-    // instead, reaching the content via the same-origin contentDocument.)
-    handleShadowRootHydration(element);
-    setupScrollAway(element);
-    setupSpy(element);
-    if (this.nodesAddedThisRender > 0 || this.directiveTouchedThisRender) {
-      setupFxDOMEventTriggers(element, this.wrapperElement || undefined);
+    // A handler's category decides whether it runs on a render that changed
+    // nothing structural (see attribute-registry.ts). `wire-idempotent`
+    // handlers walk every descendant to attach listeners; at 80k descendants
+    // that walk costs ~150-200ms and finds nothing new, so they are skipped
+    // unless morphdom added a node or touched a directive attribute.
+    const domChanged =
+      this.nodesAddedThisRender > 0 || this.directiveTouchedThisRender;
+    const roots = {
+      scanRoot: element,
+      wrapperRoot: this.wrapperElement || element,
+    };
+    runRegisteredHandlers(roots, this.boundSend, domChanged);
+
+    if (domChanged) {
+      // Event delegation stays OUTSIDE the registry by design: action routing
+      // (lvt-on:, lvt-mod:, lvt-key) must remain single-implementation, and a
+      // second delegator would fork the protocol. Handlers extend the event
+      // SET via `delegatedEvents`, never the routing.
       this.eventDelegator.setupDOMEventTriggerDelegation(element);
-      this.uploadHandler.initializeFileInputs(element);
     }
 
+    // Instance-bound built-ins: handlers that need a per-client object rather
+    // than module state, so they cannot be registered at module load. They run
+    // after the module registry, holding the position their hardcoded calls had.
+    runHandlers(this.instanceHandlers, roots, this.boundSend, domChanged);
+
     // changeAutoWirer always runs: its eviction loop must process
     // wirings on removed elements too, regardless of additions.
     this.changeAutoWirer.wireElements();
@@ -2401,6 +2452,12 @@ export class LiveTemplateClient {
   }
 }
 
+// Built-ins register first, at module load, before any page script can run.
+// That ordering is what gives them the earliest registry slots — so a
+// third-party handler claiming a built-in name is the one that gets warned
+// about, and built-ins keep the order their hardcoded call sequence had.
+registerBuiltinHandlers();
+
 // Auto-initialize when script loads (for browser use)
 if (typeof window !== "undefined") {
   LiveTemplateClient.autoInit();
diff --git a/tests/attribute-registry-node.test.ts b/tests/attribute-registry-node.test.ts
new file mode 100644
index 0000000..79d527a
--- /dev/null
+++ b/tests/attribute-registry-node.test.ts
@@ -0,0 +1,60 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The registry in a non-browser context (SSR, build tooling, a test harness
+ * that imports the package for its types or testing utilities).
+ *
+ * Deliberately a separate file with a `node` environment rather than a case in
+ * the jsdom suite: jsdom defines `document` as NON-CONFIGURABLE, so
+ * `delete globalThis.document` silently no-ops and a test written that way
+ * passes without ever simulating the thing it claims to. This environment has
+ * genuinely never had a `document`.
+ *
+ * What must hold here: importing the module and registering handlers does not
+ * throw. Nothing renders in this context, so the DOM-dependent half of
+ * registration is skipped rather than failed.
+ */
+
+import {
+  getRegisteredAttributes,
+  registerAttribute,
+  __resetRegistryForTesting,
+} from "../attribute-registry";
+import {
+  registerBuiltinHandlers,
+  __resetBuiltinRegistrationForTesting,
+} from "../dom/builtin-handlers";
+
+beforeEach(() => {
+  __resetRegistryForTesting();
+  __resetBuiltinRegistrationForTesting();
+});
+
+it("has no document, which is the point of this file", () => {
+  expect(typeof document).toBe("undefined");
+});
+
+it("registers the built-ins at module load without a DOM", () => {
+  // registerBuiltinHandlers() runs unconditionally at module load, so this is
+  // what an SSR import already does today.
+  expect(() => registerBuiltinHandlers()).not.toThrow();
+  expect(getRegisteredAttributes().length).toBeGreaterThan(0);
+});
+
+it("registers a declarative handler without a DOM", () => {
+  // The selector-validity probe is the only DOM access on the registration
+  // path. It has to degrade rather than throw.
+  expect(() =>
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} })
+  ).not.toThrow();
+  expect(getRegisteredAttributes()).toHaveLength(1);
+});
+
+it("still applies the shape checks that need no DOM", () => {
+  // Skipping the selector probe must not turn registration into a free-for-all:
+  // everything that can be validated without a document still is.
+  registerAttribute({ attribute: "lvt-x:copy", onElementRemoved: () => {} } as any);
+  expect(getRegisteredAttributes()).toHaveLength(0);
+});
diff --git a/tests/attribute-registry.test.ts b/tests/attribute-registry.test.ts
new file mode 100644
index 0000000..a4e5e26
--- /dev/null
+++ b/tests/attribute-registry.test.ts
@@ -0,0 +1,705 @@
+/**
+ * Attribute registry — the public extension point for lvt-* attributes.
+ *
+ * These tests cover the contract an external author programs against. The
+ * built-ins' own behaviour is covered by the pre-existing suites (they were not
+ * rewritten by the registry migration, only re-dispatched), so nothing here
+ * duplicates them.
+ */
+
+import {
+  attachRegistryRoot,
+  detachRegistryRoot,
+  disposeHandlers,
+  getRegisteredAttributes,
+  hasLiveRoots,
+  isDeclarative,
+  registerAttribute,
+  resolveCategory,
+  runHandlers,
+  teardownHandler,
+  __resetRegistryForTesting,
+  type AttributeHandler,
+  type ElementContext,
+  type RegistryRoot,
+  type SendFn,
+} from "../attribute-registry";
+
+const noopSend: SendFn = () => {};
+
+function makeRoot(html: string): Element {
+  document.body.innerHTML = `<div data-lvt-id="lvt-test">${html}</div>`;
+  return document.body.firstElementChild as Element;
+}
+
+/**
+ * One render pass, through the SAME entry point updateDOM uses. Calling
+ * runHandlers rather than re-implementing the gate-and-dispatch loop is what
+ * makes these tests pin production behaviour instead of a copy of it.
+ */
+function render(root: Element, domChanged = true, send: SendFn = noopSend): void {
+  runHandlers(getRegisteredAttributes(), { scanRoot: root, wrapperRoot: root }, send, domChanged);
+}
+
+/** A live client, as the registry sees one. Detached automatically in afterEach. */
+function liveRoot(root: Element): RegistryRoot {
+  const registryRoot: RegistryRoot = { root: () => root, send: noopSend };
+  attachedRoots.push(registryRoot);
+  return registryRoot;
+}
+
+let attachedRoots: RegistryRoot[] = [];
+let warn: jest.SpyInstance;
+let error: jest.SpyInstance;
+
+beforeEach(() => {
+  __resetRegistryForTesting();
+  warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+  error = jest.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  // Detach here rather than at the end of each test: an assertion that fails
+  // mid-test would otherwise leak a live root into the next one.
+  for (const root of attachedRoots) detachRegistryRoot(root);
+  attachedRoots = [];
+  warn.mockRestore();
+  error.mockRestore();
+  document.body.innerHTML = "";
+});
+
+describe("declarative layer", () => {
+  it("fires onElementAdded exactly once across repeated renders", () => {
+    const added = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: added });
+
+    const root = makeRoot(`<button lvt-x:copy="https://example.test">Copy</button>`);
+    render(root);
+    render(root);
+    render(root);
+
+    expect(added).toHaveBeenCalledTimes(1);
+  });
+
+  it("matches an attribute containing ':' without the author escaping anything", () => {
+    const added = jest.fn();
+    // The author writes a plain name. If the framework did not escape it, this
+    // selector would throw SyntaxError inside querySelectorAll.
+    registerAttribute({ attribute: "lvt-x:deep:name", onElementAdded: added });
+
+    const root = makeRoot(`<div lvt-x:deep:name="v"></div>`);
+    render(root);
+
+    expect(added).toHaveBeenCalledTimes(1);
+  });
+
+  it("fires onElementRemoved when a server diff drops the attribute", () => {
+    const removed = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {}, onElementRemoved: removed });
+
+    const root = makeRoot(`<button lvt-x:copy="a">Copy</button>`);
+    render(root);
+    expect(removed).not.toHaveBeenCalled();
+
+    root.firstElementChild!.removeAttribute("lvt-x:copy");
+    render(root);
+
+    expect(removed).toHaveBeenCalledTimes(1);
+  });
+
+  it("fires onElementRemoved when the element detaches", () => {
+    const removed = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {}, onElementRemoved: removed });
+
+    const root = makeRoot(`<button lvt-x:copy="a">Copy</button>`);
+    render(root);
+
+    root.innerHTML = "";
+    render(root);
+
+    expect(removed).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-adds an element that lost and regained the attribute", () => {
+    const added = jest.fn();
+    const removed = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: added, onElementRemoved: removed });
+
+    const root = makeRoot(`<button lvt-x:copy="a"></button>`);
+    const el = root.firstElementChild!;
+    render(root);
+    el.removeAttribute("lvt-x:copy");
+    render(root);
+    el.setAttribute("lvt-x:copy", "b");
+    render(root);
+
+    expect(added).toHaveBeenCalledTimes(2);
+    expect(removed).toHaveBeenCalledTimes(1);
+  });
+
+  it("warns on an empty value and does not invoke the callback", () => {
+    const added = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: added });
+
+    render(makeRoot(`<button lvt-x:copy=""></button>`));
+
+    expect(added).not.toHaveBeenCalled();
+    expect(warn.mock.calls.flat().join(" ")).toContain("lvt-x:copy");
+  });
+
+  it("re-reads ctx.value after a re-render rather than capturing it", () => {
+    let ctx: ElementContext | undefined;
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: (_el, c) => { ctx = c; } });
+
+    const root = makeRoot(`<button lvt-x:copy="first"></button>`);
+    render(root);
+    expect(ctx!.value).toBe("first");
+
+    // A server re-render changes the value; the listener captured ctx long ago.
+    root.firstElementChild!.setAttribute("lvt-x:copy", "second");
+    expect(ctx!.value).toBe("second");
+  });
+
+  it("resolves ctx.send to the transport live at call time, not at wiring time", () => {
+    let ctx: ElementContext | undefined;
+    registerAttribute({
+      attribute: "lvt-x:rating",
+      needsServerChannel: true,
+      onElementAdded: (_el, c) => { ctx = c; },
+    });
+
+    const root = makeRoot(`<div lvt-x:rating="SetRating"></div>`);
+    const first: SendFn = jest.fn();
+    render(root, true, first);
+
+    // Reconnect rebuilds the transport; the captured ctx must follow it.
+    const second: SendFn = jest.fn();
+    render(root, true, second);
+
+    ctx!.send!({ action: "SetRating", data: { stars: 4 } });
+    expect(second).toHaveBeenCalledWith({ action: "SetRating", data: { stars: 4 } });
+    expect(first).not.toHaveBeenCalled();
+  });
+
+  it("withholds send from a handler that did not ask for it", () => {
+    let ctx: ElementContext | undefined;
+    registerAttribute({ attribute: "lvt-x:visual", onElementAdded: (_el, c) => { ctx = c; } });
+
+    render(makeRoot(`<div lvt-x:visual="v"></div>`), true, jest.fn());
+
+    expect(ctx!.send).toBeUndefined();
+  });
+
+  it("keeps rendering after a handler callback throws", () => {
+    const later = jest.fn();
+    registerAttribute({
+      attribute: "lvt-x:bad",
+      onElementAdded: () => { throw new Error("boom"); },
+    });
+    registerAttribute({ attribute: "lvt-x:good", onElementAdded: later });
+
+    render(makeRoot(`<div lvt-x:bad="a"></div><div lvt-x:good="b"></div>`));
+
+    expect(later).toHaveBeenCalledTimes(1);
+    expect(error).toHaveBeenCalled();
+  });
+
+  it("reuses one context per element across renders", () => {
+    const seen: unknown[] = [];
+    registerAttribute({
+      attribute: "lvt-x:copy",
+      onElement: (_el, ctx) => { seen.push(ctx); },
+    });
+
+    const root = makeRoot(`<button lvt-x:copy="a"></button>`);
+    render(root);
+    render(root);
+    render(root);
+
+    // Three dispatches, one context: the members are accessors, so a handler
+    // that captured the first one keeps reading current values through it.
+    expect(seen).toHaveLength(3);
+    expect(new Set(seen).size).toBe(1);
+  });
+
+  it("sweeps tracked elements on teardown", () => {
+    const removed = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {}, onElementRemoved: removed });
+
+    const root = makeRoot(`<button lvt-x:copy="a"></button>`);
+    render(root);
+    teardownHandler(getRegisteredAttributes()[0], root);
+
+    expect(removed).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("dispose", () => {
+  it("runs root-less cleanup for handlers that declare it", () => {
+    const disposed = jest.fn();
+    registerAttribute({ name: "global-state", selectors: ["*"], setup: () => {}, dispose: disposed });
+    registerAttribute({ name: "no-global-state", selectors: ["*"], setup: () => {} });
+
+    disposeHandlers(getRegisteredAttributes());
+
+    expect(disposed).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps disposing after one handler throws", () => {
+    const later = jest.fn();
+    registerAttribute({
+      name: "bad", selectors: ["*"], setup: () => {},
+      dispose: () => { throw new Error("boom"); },
+    });
+    registerAttribute({ name: "good", selectors: ["*"], setup: () => {}, dispose: later });
+
+    disposeHandlers(getRegisteredAttributes());
+
+    expect(later).toHaveBeenCalledTimes(1);
+    expect(error).toHaveBeenCalled();
+  });
+});
+
+describe("category", () => {
+  it("derives fire-on-change when onElement is declared", () => {
+    expect(resolveCategory({ attribute: "lvt-x:a", onElement: () => {} })).toBe("fire-on-change");
+  });
+
+  it("derives wire-idempotent for wiring-only handlers", () => {
+    expect(resolveCategory({ attribute: "lvt-x:a", onElementAdded: () => {} })).toBe("wire-idempotent");
+  });
+
+  it("lets an explicit category win over the derivation", () => {
+    // Wiring-only callbacks derive wire-idempotent; the explicit value wins.
+    expect(
+      resolveCategory({ attribute: "lvt-x:a", onElementAdded: () => {}, category: "fire-on-change" })
+    ).toBe("fire-on-change");
+  });
+
+  it("skips wire-idempotent handlers when the render added nothing", () => {
+    const added = jest.fn();
+    const perRender = jest.fn();
+    registerAttribute({ attribute: "lvt-x:wire", onElementAdded: added });
+    registerAttribute({ attribute: "lvt-x:live", onElement: perRender });
+
+    const root = makeRoot(`<div lvt-x:wire="a"></div><div lvt-x:live="b"></div>`);
+    render(root, false);
+
+    expect(added).not.toHaveBeenCalled();
+    expect(perRender).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("registration", () => {
+  it("warns when two handlers claim the same name, and keeps both", () => {
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+
+    expect(getRegisteredAttributes()).toHaveLength(2);
+    expect(warn.mock.calls.flat().join(" ")).toContain("already claims this name");
+  });
+
+  it("folds case when comparing names, because the DOM does", () => {
+    registerAttribute({ attribute: "lvt-x:doThing", onElementAdded: () => {} });
+    registerAttribute({ attribute: "lvt-x:dothing", onElementAdded: () => {} });
+
+    expect(warn.mock.calls.flat().join(" ")).toContain("already claims this name");
+  });
+
+  it("does NOT warn for two low-level handlers that both walk '*'", () => {
+    // The two built-in descendant walkers are a legitimate overlap: `selectors`
+    // is descriptive and the warning must not key on it, or the registry warns
+    // about its own core handlers on every page load.
+    registerAttribute({ name: "walker-a", selectors: ["*"], category: "wire-idempotent", setup: () => {} });
+    registerAttribute({ name: "walker-b", selectors: ["*"], category: "wire-idempotent", setup: () => {} });
+
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("rejects a handler declaring both attribute and selectors", () => {
+    registerAttribute({ attribute: "lvt-x:a", selectors: ["[lvt-x\\:a]"], setup: () => {} } as any);
+
+    expect(getRegisteredAttributes()).toHaveLength(0);
+    expect(warn.mock.calls.flat().join(" ")).toContain("never both");
+  });
+
+  it("rejects a low-level handler with no setup()", () => {
+    registerAttribute({ name: "x", selectors: ["[x]"] } as any);
+    expect(getRegisteredAttributes()).toHaveLength(0);
+  });
+
+  it("rejects a handler that is neither declarative nor low-level", () => {
+    registerAttribute({ name: "x" } as any);
+    expect(getRegisteredAttributes()).toHaveLength(0);
+  });
+
+  it("catches up immediately when registered after a client is live", () => {
+    const root = makeRoot(`<button lvt-x:copy="a"></button>`);
+    const registryRoot = liveRoot(root);
+    attachRegistryRoot(registryRoot);
+
+    const added = jest.fn();
+    // No render() call: registration alone must reach the live DOM, because a
+    // second bundle can only load after core has already connected.
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: added });
+
+    expect(added).toHaveBeenCalledTimes(1);
+  });
+
+  it("catches a low-level handler up too", () => {
+    const root = makeRoot(`<div></div>`);
+    const registryRoot = liveRoot(root);
+    attachRegistryRoot(registryRoot);
+
+    const setup = jest.fn();
+    registerAttribute({ name: "late", selectors: ["*"], category: "fire-on-change", setup });
+
+    expect(setup).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not catch up after the client detaches", () => {
+    const root = makeRoot(`<button lvt-x:copy="a"></button>`);
+    const registryRoot = liveRoot(root);
+    attachRegistryRoot(registryRoot);
+    // The detach is the subject here, not cleanup — afterEach's detach would
+    // happen far too late to prove anything.
+    detachRegistryRoot(registryRoot);
+
+    const added = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: added });
+
+    expect(added).not.toHaveBeenCalled();
+  });
+
+  it("classifies the two layers", () => {
+    const decl: AttributeHandler = { attribute: "lvt-x:a" };
+    const low: AttributeHandler = { name: "b", selectors: ["[b]"], category: "fire-on-change", setup: () => {} };
+    expect(isDeclarative(decl)).toBe(true);
+    expect(isDeclarative(low)).toBe(false);
+  });
+});
+
+describe("regressions", () => {
+  // Reported on PR #159. The natural declarative shape — wire on add, clean up
+  // on remove — derives `wire-idempotent`, so gating the SWEEP on the category
+  // meant an element that lost its attribute kept its listeners until some
+  // later render happened to add a node. Worse than it first looked: the
+  // morphdom hook that sets `directiveTouchedThisRender` only inspects the NEW
+  // element's attributes (livetemplate-client.ts), so it detects an attribute
+  // being ADDED and never one being REMOVED — the exact render this handler
+  // shape cares about is the one that cannot set the flag.
+  it("fires onElementRemoved on a render that added nothing", () => {
+    const removed = jest.fn();
+    registerAttribute({
+      attribute: "lvt-x:copy",
+      onElementAdded: () => {},
+      onElementRemoved: removed,
+    });
+
+    const root = makeRoot(`<button lvt-x:copy="a"></button>`);
+    render(root, true);
+    root.firstElementChild!.removeAttribute("lvt-x:copy");
+
+    // domChanged === false: nothing was added, and removal cannot set the flag.
+    render(root, false);
+
+    expect(removed).toHaveBeenCalledTimes(1);
+  });
+
+  it("still skips the expensive scan on a render that added nothing", () => {
+    const added = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: added });
+
+    const root = makeRoot(`<button lvt-x:copy="a"></button>`);
+    render(root, false);
+
+    // The sweep is cheap and correctness-critical; the scan is the ~150-200ms
+    // walk the category exists to skip. Separating them must not un-skip it.
+    expect(added).not.toHaveBeenCalled();
+  });
+
+  it("keeps rendering when a low-level setup() throws", () => {
+    const later = jest.fn();
+    registerAttribute({
+      name: "bad-setup",
+      selectors: ["*"],
+      setup: () => { throw new Error("boom"); },
+    });
+    registerAttribute({ name: "after", selectors: ["*"], setup: later });
+
+    const root = makeRoot(`<div></div>`);
+    expect(() => render(root)).not.toThrow();
+    expect(later).toHaveBeenCalledTimes(1);
+    expect(error).toHaveBeenCalled();
+  });
+
+  it("rejects an attribute name that cannot form a valid selector", () => {
+    const added = jest.fn();
+    // lvtSelector escapes ':' only, so a ']' would close the attribute selector
+    // early and make querySelectorAll throw on EVERY render. Registration is
+    // where that has to be caught.
+    registerAttribute({ attribute: "lvt-x:bad]name", onElementAdded: added });
+
+    expect(getRegisteredAttributes()).toHaveLength(0);
+    expect(warn.mock.calls.flat().join(" ")).toContain("not a usable attribute name");
+
+    expect(() => render(makeRoot(`<div></div>`))).not.toThrow();
+    expect(added).not.toHaveBeenCalled();
+  });
+});
+
+describe("shapes that cannot work", () => {
+  // Reported on PR #159, round 2. Elements are only tracked by the scan, and
+  // the scan is skipped when there is nothing to call — so a handler declaring
+  // ONLY onElementRemoved tracks nothing, sweeps nothing, and silently never
+  // fires. It type-checks, because all three callbacks are optional.
+  it("rejects a declarative handler that can never fire", () => {
+    const removed = jest.fn();
+    registerAttribute({ attribute: "lvt-x:copy", onElementRemoved: removed });
+
+    expect(getRegisteredAttributes()).toHaveLength(0);
+    expect(warn.mock.calls.flat().join(" ")).toContain("onElementRemoved");
+  });
+
+  it("rejects a declarative handler with no callbacks at all", () => {
+    registerAttribute({ attribute: "lvt-x:copy" });
+    expect(getRegisteredAttributes()).toHaveLength(0);
+  });
+
+  it("accepts onElementRemoved alongside a callback that can track", () => {
+    registerAttribute({
+      attribute: "lvt-x:copy",
+      onElementAdded: () => {},
+      onElementRemoved: () => {},
+    });
+    expect(getRegisteredAttributes()).toHaveLength(1);
+  });
+
+  it("warns once per element for a persistently empty value, not once per render", () => {
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+
+    const root = makeRoot(`<button lvt-x:copy=""></button>`);
+    render(root);
+    render(root);
+    render(root);
+
+    // A template that re-renders on every keystroke would otherwise emit one
+    // warning per keystroke for the same element.
+    const emptyWarnings = warn.mock.calls
+      .flat()
+      .filter((c) => typeof c === "string" && c.includes("has an empty value"));
+    expect(emptyWarnings).toHaveLength(1);
+  });
+
+  it("still reports an element that heals and then empties again", () => {
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+
+    const root = makeRoot(`<button lvt-x:copy=""></button>`);
+    const el = root.firstElementChild!;
+    render(root);
+    el.setAttribute("lvt-x:copy", "real");
+    render(root);
+    el.setAttribute("lvt-x:copy", "");
+    render(root);
+
+    const emptyWarnings = warn.mock.calls
+      .flat()
+      .filter((c) => typeof c === "string" && c.includes("has an empty value"));
+    expect(emptyWarnings).toHaveLength(2);
+  });
+});
+
+describe("two clients on one page", () => {
+  // Reported on PR #159, round 3. The registry is module-level BY DESIGN and
+  // liveRoots is a Set, so two LiveTemplateClient instances can be live at
+  // once. Keying the transport by handler alone let whichever client rendered
+  // most recently win the slot for every element of every other client.
+  function twoRoots(): { a: Element; b: Element } {
+    document.body.innerHTML =
+      `<div id="a" data-lvt-id="a"><div lvt-x:rating="RateA"></div></div>` +
+      `<div id="b" data-lvt-id="b"><div lvt-x:rating="RateB"></div></div>`;
+    return {
+      a: document.getElementById("a") as Element,
+      b: document.getElementById("b") as Element,
+    };
+  }
+
+  it("keeps each element dispatching through its own client's transport", () => {
+    const contexts = new Map<string, ElementContext>();
+    registerAttribute({
+      attribute: "lvt-x:rating",
+      needsServerChannel: true,
+      onElementAdded: (_el, ctx) => { contexts.set(ctx.value, ctx); },
+    });
+
+    const { a, b } = twoRoots();
+    const sendA: SendFn = jest.fn();
+    const sendB: SendFn = jest.fn();
+
+    render(a, true, sendA);
+    render(b, true, sendB);
+    // Client B rendered most recently. A's element must still reach A.
+    render(b, true, sendB);
+
+    contexts.get("RateA")!.send!({ action: "RateA", data: {} });
+    expect(sendA).toHaveBeenCalledWith({ action: "RateA", data: {} });
+    expect(sendB).not.toHaveBeenCalled();
+  });
+
+  it("keeps each element reporting its own client's wrapper", () => {
+    const contexts = new Map<string, ElementContext>();
+    registerAttribute({
+      attribute: "lvt-x:rating",
+      onElementAdded: (_el, ctx) => { contexts.set(ctx.value, ctx); },
+    });
+
+    const { a, b } = twoRoots();
+    render(a);
+    render(b);
+
+    expect(contexts.get("RateA")!.wrapperRoot).toBe(a);
+    expect(contexts.get("RateB")!.wrapperRoot).toBe(b);
+  });
+
+  it("follows its own client's transport across a reconnect", () => {
+    // Capture by value, not "the last one added" — onElementAdded fires for
+    // both clients' elements, so a bare `ctx = c` would hold B's.
+    const contexts = new Map<string, ElementContext>();
+    registerAttribute({
+      attribute: "lvt-x:rating",
+      needsServerChannel: true,
+      onElementAdded: (_el, c) => { contexts.set(c.value, c); },
+    });
+
+    const { a, b } = twoRoots();
+    render(a, true, jest.fn());
+    render(b, true, jest.fn());
+
+    // A reconnects: same client, new transport. The context must follow it,
+    // and must not be diverted by B's interleaved renders.
+    const reconnectedA: SendFn = jest.fn();
+    render(a, true, reconnectedA);
+    render(b, true, jest.fn());
+
+    contexts.get("RateA")!.send!({ action: "RateA", data: {} });
+    expect(reconnectedA).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("registration diagnostics", () => {
+  // Reported on PR #159, round 5. The clash check ran before the shape and
+  // selector checks, so a handler that reused a name AND was invalid got told
+  // "Both will run" immediately before being rejected.
+  it("does not claim 'both will run' about a handler it is about to reject", () => {
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+    warn.mockClear();
+
+    // Same name, but a shape that can never fire.
+    registerAttribute({ attribute: "lvt-x:copy", onElementRemoved: () => {} });
+
+    const text = warn.mock.calls.flat().join(" ");
+    expect(text).toContain("onElementRemoved");
+    expect(text).not.toContain("Both will run");
+    expect(getRegisteredAttributes()).toHaveLength(1);
+  });
+
+  it("still warns about a genuine clash between two valid handlers", () => {
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+    warn.mockClear();
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+
+    expect(warn.mock.calls.flat().join(" ")).toContain("already claims this name");
+    expect(getRegisteredAttributes()).toHaveLength(2);
+  });
+});
+
+describe("dispose scoping", () => {
+  // Reported on PR #159, round 5. dispose() is for MODULE-GLOBAL state, which
+  // outlives any one client, so it must not run while another client is still
+  // using it.
+  it("defers dispose while another client is still live", () => {
+    const disposed = jest.fn();
+    registerAttribute({ name: "global", selectors: ["*"], setup: () => {}, dispose: disposed });
+
+    const a = liveRoot(makeRoot(`<div></div>`));
+    const b = liveRoot(makeRoot(`<div></div>`));
+    attachRegistryRoot(a);
+    attachRegistryRoot(b);
+
+    detachRegistryRoot(a);
+    expect(hasLiveRoots()).toBe(true);
+
+    detachRegistryRoot(b);
+    expect(hasLiveRoots()).toBe(false);
+  });
+
+  it("reports no live roots on a page that never attached one", () => {
+    expect(hasLiveRoots()).toBe(false);
+  });
+});
+
+describe("state scoping across handlers", () => {
+  // Reported on PR #159, round 7 — the same defect class as round 3's
+  // cross-client transport leak, mirrored. Round 3 was state keyed too COARSELY
+  // for its guarantee (per handler, when ownership was per element); this is
+  // state keyed too coarsely in the other axis (per element, when the guarantee
+  // is per handler-and-element). One element can carry two independent
+  // attributes, so their handlers must not share warning state about it.
+  it("does not let one handler clear another's empty-value warning state", () => {
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+    registerAttribute({ attribute: "lvt-x:rate", onElementAdded: () => {} });
+
+    // One element, two attributes: copy is empty, rate is populated. The
+    // populated handler's "this element is fine now" bookkeeping must not
+    // reset the empty handler's "already warned" bookkeeping.
+    const root = makeRoot(`<div lvt-x:copy="" lvt-x:rate="5"></div>`);
+    render(root);
+    render(root);
+    render(root);
+
+    const emptyWarnings = warn.mock.calls
+      .flat()
+      .filter((c) => typeof c === "string" && c.includes("has an empty value"));
+    expect(emptyWarnings).toHaveLength(1);
+  });
+
+  it("warns separately for two empty attributes on one element", () => {
+    registerAttribute({ attribute: "lvt-x:copy", onElementAdded: () => {} });
+    registerAttribute({ attribute: "lvt-x:rate", onElementAdded: () => {} });
+
+    const root = makeRoot(`<div lvt-x:copy="" lvt-x:rate=""></div>`);
+    render(root);
+    render(root);
+
+    const emptyWarnings = warn.mock.calls
+      .flat()
+      .filter((c) => typeof c === "string" && c.includes("has an empty value"));
+    // Two distinct problems in the template, reported once each — not one
+    // report, and not one per render.
+    expect(emptyWarnings).toHaveLength(2);
+    expect(emptyWarnings.some((w) => w.includes("lvt-x:copy"))).toBe(true);
+    expect(emptyWarnings.some((w) => w.includes("lvt-x:rate"))).toBe(true);
+  });
+});
+
+describe("low-level identity", () => {
+  // Reported on PR #159, round 11. `selectors` is descriptive and the
+  // duplicate-registration warning deliberately never keys on it, so a
+  // nameless low-level handler was invisible to that warning — silently, which
+  // is the one outcome the diagnostics exist to prevent. Required in the type
+  // AND at runtime, since the API is reachable from a plain <script>.
+  it("rejects a low-level handler with no name", () => {
+    registerAttribute({ selectors: ["[data-x]"], setup: () => {} } as any);
+
+    expect(getRegisteredAttributes()).toHaveLength(0);
+    expect(warn.mock.calls.flat().join(" ")).toContain("must supply `name`");
+  });
+
+  it("warns when two named low-level handlers claim the same name", () => {
+    registerAttribute({ name: "dup", selectors: ["[a]"], setup: () => {} });
+    warn.mockClear();
+    registerAttribute({ name: "dup", selectors: ["[b]"], setup: () => {} });
+
+    expect(warn.mock.calls.flat().join(" ")).toContain("already claims this name");
+  });
+});
diff --git a/tests/builtin-handlers.test.ts b/tests/builtin-handlers.test.ts
new file mode 100644
index 0000000..88866ac
--- /dev/null
+++ b/tests/builtin-handlers.test.ts
@@ -0,0 +1,128 @@
+/**
+ * The built-in handler registration list.
+ *
+ * WHY THIS EXISTS, since every built-in already has its own behavioural suite:
+ * those suites call the handler FUNCTIONS directly (`handleScrollDirectives`,
+ * `setupSpy`, …), which is what made them a clean regression net for the
+ * registry migration — the functions did not change. The cost of that property
+ * is that they cannot see the wiring at all. A registration list that silently
+ * lost fourteen of its eighteen entries left every one of them green, and only
+ * the bundle size gave it away.
+ *
+ * So this file asserts the wiring itself: the exact set, and the exact order.
+ */
+
+import {
+  registerBuiltinHandlers,
+  __resetBuiltinRegistrationForTesting,
+} from "../dom/builtin-handlers";
+import {
+  getRegisteredAttributes,
+  isDeclarative,
+  resolveCategory,
+  __resetRegistryForTesting,
+} from "../attribute-registry";
+
+/**
+ * The order the hardcoded post-render sequence called these in. Order is
+ * preserved rather than asserted to matter (see the module header), but it is
+ * pinned so that a change to it is a deliberate edit to this list rather than a
+ * side effect of moving code around.
+ */
+const EXPECTED_ORDER = [
+  "lvt-fx:scroll",
+  "lvt-fx:highlight",
+  "lvt-fx:animate",
+  "lvt-toast-stack",
+  "lvt-fx:auto-click",
+  "lvt-fx:area-select",
+  "lvt-fx:resize",
+  "lvt-fx:region-select",
+  "lvt-fx:text-select",
+  "lvt-fx:viewport-report",
+  "lvt-fx:proxy-bridge",
+  "lvt-fx:iframe-autoheight",
+  "lvt-fx:preview-bridge",
+  "lvt-fx:url-hash",
+  "shadow-root-hydration",
+  "lvt-scroll-away",
+  "lvt-spy",
+  "lvt-fx:*:on:*",
+];
+
+/** The six handlers that dispatch server actions. */
+const SERVER_CHANNEL = [
+  "lvt-fx:area-select",
+  "lvt-fx:region-select",
+  "lvt-fx:text-select",
+  "lvt-fx:viewport-report",
+  "lvt-fx:proxy-bridge",
+  "lvt-fx:url-hash",
+];
+
+beforeEach(() => {
+  __resetRegistryForTesting();
+  __resetBuiltinRegistrationForTesting();
+  registerBuiltinHandlers();
+});
+
+afterEach(() => {
+  __resetRegistryForTesting();
+});
+
+describe("built-in registration", () => {
+  it("registers every built-in, in the historic call order", () => {
+    expect(getRegisteredAttributes().map((h) => h.name)).toEqual(EXPECTED_ORDER);
+  });
+
+  it("gives every built-in a setup function and a claimable name", () => {
+    for (const handler of getRegisteredAttributes()) {
+      expect(handler.name).toBeTruthy();
+      expect(isDeclarative(handler)).toBe(false);
+      expect(typeof (handler as any).setup).toBe("function");
+    }
+  });
+
+  it("grants the server channel to exactly the handlers that dispatch actions", () => {
+    const withChannel = getRegisteredAttributes()
+      .filter((h) => h.needsServerChannel)
+      .map((h) => h.name);
+    expect(withChannel.sort()).toEqual([...SERVER_CHANNEL].sort());
+  });
+
+  it("keeps only the descendant walker on the wire-idempotent skip", () => {
+    // Everything else must run on every render: they react to a value changing
+    // on an element that already exists, which a skip would swallow.
+    const skippable = getRegisteredAttributes()
+      .filter((h) => resolveCategory(h) === "wire-idempotent")
+      .map((h) => h.name);
+    expect(skippable).toEqual(["lvt-fx:*:on:*"]);
+  });
+
+  it("registers no two handlers claiming the same name", () => {
+    const names = getRegisteredAttributes().map((h) => h.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it("declares root-less cleanup only where teardown(root) cannot express it", () => {
+    const disposers = getRegisteredAttributes()
+      .filter((h) => h.dispose)
+      .map((h) => h.name);
+    // auto-click arms module-global timers, so there is no root to scope them to.
+    expect(disposers).toEqual(["lvt-fx:auto-click"]);
+  });
+
+  it("does not re-register if the module is evaluated twice", () => {
+    // A duplicated <script> or a bundler dedupe failure would otherwise give
+    // every built-in a second registration — and the six needsServerChannel
+    // handlers would dispatch every action to the server twice.
+    const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const before = getRegisteredAttributes().length;
+
+    registerBuiltinHandlers();
+
+    expect(getRegisteredAttributes()).toHaveLength(before);
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
diff --git a/tests/public-api-surface.test.ts b/tests/public-api-surface.test.ts
new file mode 100644
index 0000000..8a57247
--- /dev/null
+++ b/tests/public-api-surface.test.ts
@@ -0,0 +1,64 @@
+/**
+ * The built browser bundle's public surface.
+ *
+ * Deliberately tested against dist/, not against the source. The finding this
+ * pins is a property of the BUILD: esbuild runs
+ * `--global-name=LiveTemplateClient` over a module that also exports a class of
+ * that name, so `window.LiveTemplateClient` is the module NAMESPACE object and
+ * the class sits at `LiveTemplateClient.LiveTemplateClient`. Every documented
+ * example writes `LiveTemplateClient.registerAttribute(...)`, which therefore
+ * resolves to the module-level named export and NOT to the class static. A
+ * source-level test cannot tell those two apart; this one can.
+ *
+ * Requires `npm run build` first — see the note in the skip below.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+const BUNDLE = path.join(__dirname, "..", "dist", "livetemplate-client.browser.js");
+
+describe("built browser bundle", () => {
+  const built = fs.existsSync(BUNDLE);
+
+  // Not a silent skip: if the bundle is missing the message says how to get it,
+  // rather than the suite quietly reporting green on an unbuilt artefact.
+  const testIfBuilt = built ? it : it.skip;
+  if (!built) {
+    // eslint-disable-next-line no-console
+    console.warn(`[public-api-surface] ${BUNDLE} missing — run \`npm run build\`.`);
+  }
+
+  testIfBuilt("exposes registerAttribute on the IIFE global", () => {
+    const code = fs.readFileSync(BUNDLE, "utf8");
+    // The bundle opens with "use strict", and a strict-mode EVAL keeps its
+    // `var` bindings local — unlike a real <script>, where a top-level `var`
+    // becomes a global whether the script is strict or not. So the assignment
+    // is appended rather than relying on the leak a browser would give us.
+    // eslint-disable-next-line no-eval
+    (0, eval)(code + "\n;globalThis.LiveTemplateClient = LiveTemplateClient;");
+
+    const globalNamespace = (globalThis as any).LiveTemplateClient;
+    expect(typeof globalNamespace.registerAttribute).toBe("function");
+    expect(typeof globalNamespace.LiveTemplateClient).toBe("function");
+    expect(typeof globalNamespace.LiveTemplateClient.registerAttribute).toBe("function");
+  });
+
+  testIfBuilt("ships the handler types in the emitted declarations", () => {
+    const dts = fs.readFileSync(
+      path.join(__dirname, "..", "dist", "attribute-registry.d.ts"),
+      "utf8"
+    );
+    for (const symbol of [
+      "AttributeHandler",
+      "DeclarativeHandler",
+      "LowLevelHandler",
+      "ElementContext",
+      "SetupContext",
+      "SendFn",
+      "registerAttribute",
+    ]) {
+      expect(dts).toContain(symbol);
+    }
+  });
+});