From d9c79cf444b6113fabce3aba75bd73d2b515a06d Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Tue, 25 Aug 2026 19:38:28 +0000
Subject: [PATCH 1/5] feat(attributes): make lvt-* attributes extensible via a
 handler registry

Adding an lvt-* attribute meant 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 post-render sequence, with a
matching entry in disconnect()'s teardown list. An app that wanted
lvt-x:copy-to-clipboard had no supported way to get one, and ~2,400 lines
of handlers with exactly one consumer shipped to every LiveTemplate user
because there was no mechanism for a downstream app to own them.

Replace both hardcoded lists with a registry of handler objects and a
public LiveTemplateClient.registerAttribute(). Every built-in registers
through the same interface an external author uses -- there is no
privileged internal path, so a gap in the public API shows up as a gap for
the framework itself.

Two layers. Declarative (declare an attribute NAME, get called per
element) is what most authors should touch; the framework owns selector
escaping, the scan, per-element tracking, empty-value rejection and
sweep-on-removal, which makes the three classic handler bugs -- no sweep,
listeners stacking every render, a captured transport that dies at
reconnect -- unreachable from it. A selectors + setup()/teardown() escape
hatch covers cross-element state; the built-ins use it, because their
bodies are unchanged and their existing tests call them directly.

Registration is static, and late registration catches up against the live
DOM immediately: under the documented <script defer> pattern autoInit()
has already connected by the time a second script evaluates, so an
instance method could never have worked. registerAttribute is a
module-level named export because --global-name over a module that also
exports a class of that name makes window.LiveTemplateClient the module
namespace -- the spelling every doc example uses resolves to the export,
not the class static. Both are pinned by tests against the built bundle.

No behaviour change: all 824 pre-existing tests pass unedited, and lvt's
chromedp suite passes against the locally built bundle.

Phase 1 of livetemplate/livetemplate#473. Phase 2's client half (the
meta.attributes census diff) is assigned to Phase 3; M2 extraction must
not start before it lands, since that warning is what makes Phase 4's
break loud instead of silent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N6hr7ZCG9o4pCmtnA8qhSq
---
 CHANGELOG.md                     |  60 ++++
 attribute-registry.ts            | 567 +++++++++++++++++++++++++++++++
 dom/builtin-handlers.ts          | 218 ++++++++++++
 event-spec.ts                    |  84 +++++
 livetemplate-client.ts           | 305 ++++++++++-------
 tests/attribute-registry.test.ts | 378 +++++++++++++++++++++
 tests/builtin-handlers.test.ts   | 117 +++++++
 tests/public-api-surface.test.ts |  64 ++++
 8 files changed, 1661 insertions(+), 132 deletions(-)
 create mode 100644 attribute-registry.ts
 create mode 100644 dom/builtin-handlers.ts
 create mode 100644 event-spec.ts
 create mode 100644 tests/attribute-registry.test.ts
 create mode 100644 tests/builtin-handlers.test.ts
 create mode 100644 tests/public-api-surface.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d2fc82..f2e0b24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,66 @@ 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 — 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`.
+
+### 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..96fa239
--- /dev/null
+++ b/attribute-registry.ts
@@ -0,0 +1,567 @@
+/**
+ * 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.
+ *   always           — every render, unconditionally, including renders a
+ *                      future optimization might skip. For handlers that must
+ *                      process REMOVALS, not just current matches.
+ *
+ * `always` and `fire-on-change` are indistinguishable today, because `updateDOM`
+ * runs its post-render block unconditionally — there is no empty-diff skip to
+ * be exempt from. The distinction is kept because it records intent: if such a
+ * skip ever lands, `always` is the category that must not be caught by it.
+ */
+export type HandlerCategory = "always" | "fire-on-change" | "wire-idempotent";
+
+interface BaseHandler {
+  /** Defaults to `attribute` for declarative handlers; required for low-level. */
+  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 on every disconnect whether or not a wrapper
+   * element exists.
+   *
+   * `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. */
+  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 lost the attribute via a server diff. */
+  onElementRemoved?(el: Element): void;
+}
+
+export interface LowLevelHandler extends BaseHandler {
+  /** 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;
+}
+
+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: for a
+ * `fire-on-change` handler that window is one render, for a `wire-idempotent`
+ * one it lasts until the next render that adds nodes.
+ *
+ * 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, ElementContext>>();
+
+/**
+ * The transport each handler's contexts should currently dispatch through.
+ *
+ * Kept OUTSIDE the context object on purpose. A handler wires a listener in
+ * `onElementAdded` and that listener captures the `ctx` it was handed — once,
+ * on the render the element first appeared. A reconnect rebuilds the transport,
+ * so a context that closed over the send it was constructed with would keep
+ * dispatching into the dead one for the rest of the page's life. Storing the
+ * send here and reading it through the accessor means every captured context
+ * follows the reconnect, which is the guarantee `ElementContext` documents.
+ */
+const currentSend = new WeakMap<AttributeHandler, SendFn>();
+
+/**
+ * The roots of the dispatch currently in flight, per handler.
+ *
+ * Exists for the same reason as `currentSend`: a cached `ElementContext` must
+ * report the wrapper of the render being processed, not the one that happened
+ * to be live when the element was first seen. Cross-handler navigation
+ * replaces the wrapper.
+ */
+const currentRoots = new WeakMap<AttributeHandler, { scanRoot: Element; 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 }>();
+
+function trackedMap(handler: AttributeHandler): Map<Element, ElementContext> {
+  let map = tracked.get(handler);
+  if (!map) {
+    map = new Map<Element, ElementContext>();
+    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.
+ *
+ * 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;
+  }
+
+  // Duplicate claim warning. Keyed on the DECLARATIVE attribute name and on 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.
+  const key = claimKey(handler);
+  const clash = key !== null && registry.some((existing) => claimKey(existing) === key);
+  if (clash) {
+    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: declarative ? lvtSelector((handler as DeclarativeHandler).attribute) : "",
+  });
+
+  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);
+  }
+}
+
+/** The live registry. Read on every render, never snapshotted at construction. */
+export function getRegisteredAttributes(): readonly AttributeHandler[] {
+  return 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);
+}
+
+/**
+ * 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
+): void {
+  const channel = handler.needsServerChannel ? send : undefined;
+  if (channel && currentSend.get(handler) !== channel) currentSend.set(handler, channel);
+
+  if (!isDeclarative(handler)) {
+    handler.setup({ scanRoot: roots.scanRoot, wrapperRoot: roots.wrapperRoot, send: channel });
+    return;
+  }
+
+  dispatchDeclarative(handler, roots);
+}
+
+/**
+ * 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) {
+    if (shouldRun(handler, domChanged)) {
+      runHandler(handler, roots, send);
+    }
+  }
+}
+
+/**
+ * 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 }
+): void {
+  const attribute = handler.attribute;
+  const seen = trackedMap(handler);
+  currentRoots.set(handler, roots);
+
+  sweep(handler, seen);
+
+  // 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 ctx = seen.get(el);
+
+    if (!ctx) {
+      // Every handler needed this check, so it stopped being the author's job.
+      if (!el.getAttribute(attribute)) {
+        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;
+      }
+      ctx = makeElementContext(handler, el);
+      seen.set(el, ctx);
+      if (wantsAdded) {
+        try {
+          handler.onElementAdded!(el, ctx);
+        } catch (error) {
+          reportHookError(handler, "onElementAdded", error);
+        }
+      }
+    }
+
+    if (wantsEvery) {
+      try {
+        handler.onElement!(el, 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): ElementContext {
+  return {
+    get value(): string {
+      return el.getAttribute(handler.attribute) || "";
+    },
+    get send(): SendFn | undefined {
+      return handler.needsServerChannel ? currentSend.get(handler) : undefined;
+    },
+    get wrapperRoot(): Element {
+      // Only reachable from inside or after a dispatch, which always sets this.
+      return currentRoots.get(handler)!.wrapperRoot;
+    },
+  };
+}
+
+/**
+ * Drops elements that detached from the document or lost the attribute via a
+ * server diff, notifying the handler about each.
+ *
+ * Runs at the top of every dispatch rather than only when the render added
+ * nodes: 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. The cost is two
+ * O(1) reads per tracked element per dispatch.
+ *
+ * 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, ElementContext>): void {
+  if (seen.size === 0) return;
+  for (const el of Array.from(seen.keys())) {
+    if (el.isConnected && el.hasAttribute(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..ae579a8
--- /dev/null
+++ b/dom/builtin-handlers.ts
@@ -0,0 +1,218 @@
+/**
+ * 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),
+  },
+];
+
+/**
+ * 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.
+ */
+export function registerBuiltinHandlers(): void {
+  for (const handler of builtinHandlers) {
+    registerAttribute(handler);
+  }
+}
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..2db06ad 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,20 @@ 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,
+  getRegisteredAttributes,
+  registerAttribute,
+  runHandlers,
+  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 +63,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 +121,34 @@ 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[];
+
+  /**
+   * 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. Accessors, not fields: the wrapper is reassigned on
+   * cross-handler navigation, and `send` must resolve the transport that is
+   * live at call time rather than the one that existed at attach time.
+   */
+  /**
+   * One `send` for the client's whole life, so the per-render dispatch does not
+   * allocate a closure (and the registry's per-handler transport cache does not
+   * see a "new" transport) on every render.
+   */
+  private readonly boundSend: SendFn = (message) => this.send(message);
+
+  private registryRoot: RegistryRoot = {
+    root: () => this.wrapperElement,
+    send: (message) => this.send(message),
+  };
+
   // Initialization tracking for loading indicator
   private isInitialized: boolean = false;
 
@@ -196,6 +238,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 +432,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 +765,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 +813,28 @@ export class LiveTemplateClient {
     this.uploadHandler.revokePreviews();
     this.eventDelegator.teardownDOMEventTriggerDelegation();
     teardownHashLink();
-    teardownAutoClickTimers();
+    // Root-less handler cleanup, deliberately outside the wrapper guard below:
+    // a handler whose state is module-global still has to be cleaned up when
+    // the client disconnects without ever having had a wrapper.
+    disposeHandlers(getRegisteredAttributes());
+    disposeHandlers(this.instanceHandlers);
     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.
+      for (const handler of getRegisteredAttributes()) {
+        teardownHandler(handler, 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);
     this.resetSessionState();
   }
 
@@ -2200,102 +2297,40 @@ export class LiveTemplateClient {
     // Restore focus to previously focused element
     this.focusManager.restoreFocusedElement();
 
-    // Two classes of post-render scans:
+    // Post-render attribute pass.
     //
-    //   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.
+    // 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.
     //
-    //   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).
-    //
-    // 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,
+    };
+    runHandlers(getRegisteredAttributes(), 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 +2436,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.test.ts b/tests/attribute-registry.test.ts
new file mode 100644
index 0000000..6764ecb
--- /dev/null
+++ b/tests/attribute-registry.test.ts
@@ -0,0 +1,378 @@
+/**
+ * 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,
+  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", () => {
+    expect(
+      resolveCategory({ attribute: "lvt-x:a", onElementAdded: () => {}, category: "always" })
+    ).toBe("always");
+  });
+
+  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: "always", setup: () => {} };
+    expect(isDeclarative(decl)).toBe(true);
+    expect(isDeclarative(low)).toBe(false);
+  });
+});
diff --git a/tests/builtin-handlers.test.ts b/tests/builtin-handlers.test.ts
new file mode 100644
index 0000000..a9c87b4
--- /dev/null
+++ b/tests/builtin-handlers.test.ts
@@ -0,0 +1,117 @@
+/**
+ * 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 all 851 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 } 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();
+  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("is idempotent enough to warn rather than silently double-register", () => {
+    const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    registerBuiltinHandlers();
+    expect(warn.mock.calls.flat().join(" ")).toContain("already claims this name");
+    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);
+    }
+  });
+});

From cf8a32c79e46628a7ae94aa6b04e2baf9b61faec Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Mon, 31 Aug 2026 18:39:34 +0000
Subject: [PATCH 2/5] fix(attributes): sweep every render, and isolate setup()
 like every other hook

Two defects found in review of #159.

1. onElementRemoved could be deferred indefinitely.

Gating the sweep on the handler's category broke the most natural
declarative shape there is: onElementAdded + onElementRemoved derives
`wire-idempotent`, so an element that lost its attribute kept its
listeners until some later render happened to add a node.

Worse, the flag can never see the render that matters.
`directiveTouchedThisRender` is set by a morphdom hook that inspects the
NEW element's attributes, so it detects an attribute being ADDED and
never one being REMOVED -- precisely the render this handler shape
exists to handle.

The sweep and the scan have opposite cost profiles and opposite failure
modes, so they now gate differently: the sweep is O(tracked) with two
O(1) reads and skipping it is a correctness bug, so it runs every
render; the scan is the querySelectorAll walk `wire-idempotent` exists
to skip, so it stays gated. The category never meant "skip cleanup".

2. setup() and the scan were the only unisolated paths.

Every other hook runs under reportHookError so that third-party code
throwing cannot strand the handlers after it -- but setup(), which is
the low-level layer's entire entry point, was unguarded. An exception
propagated out of updateDOM, silently skipping every later handler plus
the event delegator, the upload wiring and the change auto-wirer.

setup() is now wrapped. The scan is handled at the other end instead:
lvtSelector escapes ':' but not ']' or quotes, so a malformed attribute
name would throw SyntaxError on every render for the life of the page.
Validating once at registration turns a recurring render-time crash into
one actionable warning.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N6hr7ZCG9o4pCmtnA8qhSq
---
 CHANGELOG.md                     |  3 +-
 attribute-registry.ts            | 93 ++++++++++++++++++++++++--------
 tests/attribute-registry.test.ts | 69 ++++++++++++++++++++++++
 3 files changed, 141 insertions(+), 24 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f2e0b24..4eb4c4e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,7 +33,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   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 — so the three classic mistakes (no sweep, listeners stacking
+  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
diff --git a/attribute-registry.ts b/attribute-registry.ts
index 96fa239..d1f7df6 100644
--- a/attribute-registry.ts
+++ b/attribute-registry.ts
@@ -174,9 +174,9 @@ const liveRoots = new Set<RegistryRoot>();
  * 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: for a
- * `fire-on-change` handler that window is one render, for a `wire-idempotent`
- * one it lasts until the next render that adds nodes.
+ * 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
@@ -327,10 +327,27 @@ export function registerAttribute(handler: AttributeHandler): void {
     );
   }
 
-  resolved.set(handler, {
-    category: deriveCategory(handler),
-    selector: declarative ? lvtSelector((handler as DeclarativeHandler).attribute) : "",
-  });
+  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.
+    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;
+    }
+  }
+
+  resolved.set(handler, { category: deriveCategory(handler), selector });
 
   registry.push(handler);
 
@@ -379,17 +396,51 @@ export function detachRegistryRoot(root: RegistryRoot): void {
 export function runHandler(
   handler: AttributeHandler,
   roots: { scanRoot: Element; wrapperRoot: Element },
-  send: SendFn
+  send: SendFn,
+  domChanged = true
 ): void {
   const channel = handler.needsServerChannel ? send : undefined;
   if (channel && currentSend.get(handler) !== channel) currentSend.set(handler, channel);
 
   if (!isDeclarative(handler)) {
-    handler.setup({ scanRoot: roots.scanRoot, wrapperRoot: roots.wrapperRoot, send: channel });
+    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;
   }
 
-  dispatchDeclarative(handler, roots);
+  // 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);
+  currentRoots.set(handler, roots);
+  sweep(handler, seen);
+
+  if (!shouldRun(handler, domChanged)) return;
+  dispatchDeclarative(handler, roots, seen);
 }
 
 /**
@@ -408,9 +459,7 @@ export function runHandlers(
   domChanged: boolean
 ): void {
   for (const handler of handlers) {
-    if (shouldRun(handler, domChanged)) {
-      runHandler(handler, roots, send);
-    }
+    runHandler(handler, roots, send, domChanged);
   }
 }
 
@@ -471,13 +520,10 @@ function notifyRemoved(handler: DeclarativeHandler, el: Element): void {
 
 function dispatchDeclarative(
   handler: DeclarativeHandler,
-  roots: { scanRoot: Element; wrapperRoot: Element }
+  roots: { scanRoot: Element; wrapperRoot: Element },
+  seen: Map<Element, ElementContext>
 ): void {
   const attribute = handler.attribute;
-  const seen = trackedMap(handler);
-  currentRoots.set(handler, roots);
-
-  sweep(handler, seen);
 
   // Hoisted: a wiring-only handler declares no onElement, and checking that
   // per element per render costs a branch and a closure for nothing.
@@ -547,11 +593,12 @@ function makeElementContext(handler: DeclarativeHandler, el: Element): ElementCo
  * Drops elements that detached from the document or lost the attribute via a
  * server diff, notifying the handler about each.
  *
- * Runs at the top of every dispatch rather than only when the render added
- * nodes: 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. The cost is two
- * O(1) reads per tracked element per dispatch.
+ * 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
diff --git a/tests/attribute-registry.test.ts b/tests/attribute-registry.test.ts
index 6764ecb..25a1831 100644
--- a/tests/attribute-registry.test.ts
+++ b/tests/attribute-registry.test.ts
@@ -376,3 +376,72 @@ describe("registration", () => {
     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();
+  });
+});

From df058099c8ff60b344906600af300d0ea713be70 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Mon, 31 Aug 2026 18:45:59 +0000
Subject: [PATCH 3/5] fix(attributes): reject handlers that can never fire;
 unify empty-value rule

Review round 2 on #159.

1. onElementRemoved on its own silently did nothing, forever.

Elements are tracked by the scan, and the scan only runs for handlers
with something to call on a match -- so a declarative handler declaring
ONLY onElementRemoved tracked nothing, swept nothing, and never fired.
All three callbacks are optional, so the shape type-checked and
registered without complaint. Rejected at registration now, with a
message that names the missing callback. Same rule covers a declarative
handler with no callbacks at all.

2. The empty-value warning fired once per render, not once per element.

An element with an empty value is deliberately never tracked, so it can
heal the moment a real value arrives -- which meant one warning per
render for as long as it persisted, i.e. once per keystroke on a
template that re-renders on input. Warned once per element now, and the
mark is cleared when the element heals so a value that empties again is
reported again.

3. The scan and the sweep disagreed about what "empty" means.

Fixing (2) surfaced it: the scan refuses to arm an element whose value
is empty, while the sweep asked only hasAttribute() and so insisted an
emptied element was still live. A handler wired for {{.ShareURL}} kept
its listeners after the URL went away, and could never be re-armed
because it was still tracked.

One rule now, in both halves: an element is claimed while it carries the
attribute WITH a non-empty value. Emptying is treated exactly like
removal -- the value is the handler's configuration, so an empty one
means unarmed. Documented on DeclarativeHandler, where an author looks.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N6hr7ZCG9o4pCmtnA8qhSq
---
 attribute-registry.ts            | 74 +++++++++++++++++++++++++++++---
 tests/attribute-registry.test.ts | 61 ++++++++++++++++++++++++++
 2 files changed, 128 insertions(+), 7 deletions(-)

diff --git a/attribute-registry.ts b/attribute-registry.ts
index d1f7df6..eb21d20 100644
--- a/attribute-registry.ts
+++ b/attribute-registry.ts
@@ -127,7 +127,14 @@ export interface SetupContext {
 }
 
 export interface DeclarativeHandler extends BaseHandler {
-  /** A plain attribute name, e.g. "lvt-x:copy". Never a CSS selector. */
+  /**
+   * 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;
 
@@ -135,7 +142,15 @@ export interface DeclarativeHandler extends BaseHandler {
   onElementAdded?(el: Element, ctx: ElementContext): void;
   /** Every run, for every currently matching element. */
   onElement?(el: Element, ctx: ElementContext): void;
-  /** The element detached, or lost the attribute via a server diff. */
+  /**
+   * 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;
 }
 
@@ -217,6 +232,18 @@ const currentRoots = new WeakMap<AttributeHandler, { scanRoot: Element; wrapperR
  */
 const resolved = new WeakMap<AttributeHandler, { category: HandlerCategory; selector: string }>();
 
+/**
+ * Elements already warned about for an empty attribute value.
+ *
+ * The empty-value check runs on every render (an element with no value is
+ * deliberately never tracked, so it can heal the moment a real value arrives),
+ * which without this would emit one warning per render for as long as the
+ * element persists — once per keystroke on a template that re-renders on
+ * input. Cleared when the element heals, so a value that empties again is
+ * reported again.
+ */
+const warnedEmpty = new WeakSet<Element>();
+
 function trackedMap(handler: AttributeHandler): Map<Element, ElementContext> {
   let map = tracked.get(handler);
   if (!map) {
@@ -327,6 +354,27 @@ export function registerAttribute(handler: AttributeHandler): void {
     );
   }
 
+  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);
@@ -540,12 +588,16 @@ function dispatchDeclarative(
     if (!ctx) {
       // Every handler needed this check, so it stopped being the author's job.
       if (!el.getAttribute(attribute)) {
-        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.`
-        );
+        if (!warnedEmpty.has(el)) {
+          warnedEmpty.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.delete(el);
       ctx = makeElementContext(handler, el);
       seen.set(el, ctx);
       if (wantsAdded) {
@@ -607,7 +659,15 @@ function makeElementContext(handler: DeclarativeHandler, el: Element): ElementCo
 function sweep(handler: DeclarativeHandler, seen: Map<Element, ElementContext>): void {
   if (seen.size === 0) return;
   for (const el of Array.from(seen.keys())) {
-    if (el.isConnected && el.hasAttribute(handler.attribute)) continue;
+    // 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/tests/attribute-registry.test.ts b/tests/attribute-registry.test.ts
index 25a1831..1d5e4f5 100644
--- a/tests/attribute-registry.test.ts
+++ b/tests/attribute-registry.test.ts
@@ -445,3 +445,64 @@ describe("regressions", () => {
     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);
+  });
+});

From fff48e31588b3b7606fdf323efb98cb21b773876 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Mon, 31 Aug 2026 18:53:10 +0000
Subject: [PATCH 4/5] fix(attributes): scope a context's transport to its own
 client

Review round 3 on #159.

currentSend and currentRoots were module-level WeakMaps keyed by the
handler object alone. The registry is module-level BY DESIGN and
liveRoots is a Set, so two LiveTemplateClient instances can be live on
one page -- and if both contained elements matching the same declarative
attribute, whichever client rendered most recently owned the slot for
every other client's elements too. A listener wired on client A's
element, fired after client B's next render, dispatched through B's
socket and reported B's wrapper.

Both slots are gone. The transport and wrapper now live on the
per-element entry the tracking map already held, so they are written by
exactly one client: an element only ever matches during a dispatch whose
scanRoot contains it, which is its own client's. Cross-contamination
stops being possible rather than being avoided.

The fields are refreshed on every dispatch rather than captured at
creation, which is what keeps the reconnect guarantee that ElementContext
documents -- the client hands in a new transport and the element's own
next render adopts it. This is the same guarantee that motivated the
WeakMap indirection in the first place; the defect was its granularity,
not its existence.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N6hr7ZCG9o4pCmtnA8qhSq
---
 attribute-registry.ts            | 83 ++++++++++++++++++--------------
 tests/attribute-registry.test.ts | 77 +++++++++++++++++++++++++++++
 2 files changed, 123 insertions(+), 37 deletions(-)

diff --git a/attribute-registry.ts b/attribute-registry.ts
index eb21d20..071118a 100644
--- a/attribute-registry.ts
+++ b/attribute-registry.ts
@@ -200,30 +200,31 @@ const liveRoots = new Set<RegistryRoot>();
  * 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, ElementContext>>();
+const tracked = new WeakMap<AttributeHandler, Map<Element, ElementEntry>>();
 
 /**
- * The transport each handler's contexts should currently dispatch through.
+ * What one tracked element's context reads through.
  *
- * Kept OUTSIDE the context object on purpose. A handler wires a listener in
- * `onElementAdded` and that listener captures the `ctx` it was handed — once,
- * on the render the element first appeared. A reconnect rebuilds the transport,
- * so a context that closed over the send it was constructed with would keep
- * dispatching into the dead one for the rest of the page's life. Storing the
- * send here and reading it through the accessor means every captured context
- * follows the reconnect, which is the guarantee `ElementContext` documents.
- */
-const currentSend = new WeakMap<AttributeHandler, SendFn>();
-
-/**
- * The roots of the dispatch currently in flight, per handler.
+ * 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.
  *
- * Exists for the same reason as `currentSend`: a cached `ElementContext` must
- * report the wrapper of the render being processed, not the one that happened
- * to be live when the element was first seen. Cross-handler navigation
- * replaces the wrapper.
+ * 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.
  */
-const currentRoots = new WeakMap<AttributeHandler, { scanRoot: Element; wrapperRoot: Element }>();
+interface ElementEntry {
+  ctx: ElementContext;
+  send: SendFn | undefined;
+  wrapperRoot: Element;
+}
 
 /**
  * Values fixed at registration, computed once instead of per render: the
@@ -244,10 +245,10 @@ const resolved = new WeakMap<AttributeHandler, { category: HandlerCategory; sele
  */
 const warnedEmpty = new WeakSet<Element>();
 
-function trackedMap(handler: AttributeHandler): Map<Element, ElementContext> {
+function trackedMap(handler: AttributeHandler): Map<Element, ElementEntry> {
   let map = tracked.get(handler);
   if (!map) {
-    map = new Map<Element, ElementContext>();
+    map = new Map<Element, ElementEntry>();
     tracked.set(handler, map);
   }
   return map;
@@ -448,7 +449,6 @@ export function runHandler(
   domChanged = true
 ): void {
   const channel = handler.needsServerChannel ? send : undefined;
-  if (channel && currentSend.get(handler) !== channel) currentSend.set(handler, channel);
 
   if (!isDeclarative(handler)) {
     if (!shouldRun(handler, domChanged)) return;
@@ -484,11 +484,10 @@ export function runHandler(
   // attributes, so it detects an attribute being added and never one being
   // removed.
   const seen = trackedMap(handler);
-  currentRoots.set(handler, roots);
   sweep(handler, seen);
 
   if (!shouldRun(handler, domChanged)) return;
-  dispatchDeclarative(handler, roots, seen);
+  dispatchDeclarative(handler, roots, seen, channel);
 }
 
 /**
@@ -569,7 +568,8 @@ function notifyRemoved(handler: DeclarativeHandler, el: Element): void {
 function dispatchDeclarative(
   handler: DeclarativeHandler,
   roots: { scanRoot: Element; wrapperRoot: Element },
-  seen: Map<Element, ElementContext>
+  seen: Map<Element, ElementEntry>,
+  channel: SendFn | undefined
 ): void {
   const attribute = handler.attribute;
 
@@ -583,9 +583,14 @@ function dispatchDeclarative(
   // 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 ctx = seen.get(el);
-
-    if (!ctx) {
+    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)) {
         if (!warnedEmpty.has(el)) {
@@ -598,11 +603,12 @@ function dispatchDeclarative(
         continue;
       }
       warnedEmpty.delete(el);
-      ctx = makeElementContext(handler, el);
-      seen.set(el, ctx);
+      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, ctx);
+          handler.onElementAdded!(el, entry.ctx);
         } catch (error) {
           reportHookError(handler, "onElementAdded", error);
         }
@@ -611,7 +617,7 @@ function dispatchDeclarative(
 
     if (wantsEvery) {
       try {
-        handler.onElement!(el, ctx);
+        handler.onElement!(el, entry.ctx);
       } catch (error) {
         reportHookError(handler, "onElement", error);
       }
@@ -626,17 +632,20 @@ function dispatchDeclarative(
  * 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): ElementContext {
+function makeElementContext(
+  handler: DeclarativeHandler,
+  el: Element,
+  entry: ElementEntry
+): ElementContext {
   return {
     get value(): string {
       return el.getAttribute(handler.attribute) || "";
     },
     get send(): SendFn | undefined {
-      return handler.needsServerChannel ? currentSend.get(handler) : undefined;
+      return entry.send;
     },
     get wrapperRoot(): Element {
-      // Only reachable from inside or after a dispatch, which always sets this.
-      return currentRoots.get(handler)!.wrapperRoot;
+      return entry.wrapperRoot;
     },
   };
 }
@@ -656,7 +665,7 @@ function makeElementContext(handler: DeclarativeHandler, el: Element): ElementCo
  * 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, ElementContext>): void {
+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
diff --git a/tests/attribute-registry.test.ts b/tests/attribute-registry.test.ts
index 1d5e4f5..fc872a4 100644
--- a/tests/attribute-registry.test.ts
+++ b/tests/attribute-registry.test.ts
@@ -506,3 +506,80 @@ describe("shapes that cannot work", () => {
     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);
+  });
+});

From 03496b5ba2e9229471e11c4223c0625c0c2dc299 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Mon, 31 Aug 2026 18:57:29 +0000
Subject: [PATCH 5/5] docs(attributes): reattach the registryRoot JSDoc to its
 own field

Review round 4 on #159, doc-only.

Inserting boundSend landed it between registryRoot's JSDoc and the field
it documents, so that block described the wrong member -- and it still
described `send` as an accessor resolving the transport, which stopped
being registryRoot's job when round 3 moved transport ownership onto the
per-element entry.

Each field now carries its own comment, and boundSend's says where the
reconnect guarantee actually comes from: it delegates to this.send,
which resolves the transport at call time, so a context holding it stays
correct without the registry re-keying anything.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N6hr7ZCG9o4pCmtnA8qhSq
---
 livetemplate-client.ts | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/livetemplate-client.ts b/livetemplate-client.ts
index 2db06ad..a3ee520 100644
--- a/livetemplate-client.ts
+++ b/livetemplate-client.ts
@@ -130,20 +130,21 @@ export class LiveTemplateClient {
    */
   private instanceHandlers: AttributeHandler[];
 
-  /**
-   * 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. Accessors, not fields: the wrapper is reassigned on
-   * cross-handler navigation, and `send` must resolve the transport that is
-   * live at call time rather than the one that existed at attach time.
-   */
   /**
    * One `send` for the client's whole life, so the per-render dispatch does not
-   * allocate a closure (and the registry's per-handler transport cache does not
-   * see a "new" transport) on every render.
+   * 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,
     send: (message) => this.send(message),