@abide/abide 0.35.0 → 0.37.0

package/src/lib/ui/compile/componentWrapperTag.ts

@@ -1,23 +1,13 @@
-import { HTML_TAGS } from './HTML_TAGS.ts'
-
 /*
-The element tag a component instance mounts into. Normally the component name
-lowercased — readable in devtools, a real box like any abide wrapper. But a name
-that lowercases to a real HTML element (`Button`→`button`, `Input`→`input`) yields a
-wrapper with a content model the parser enforces: void elements self-close, and
-`<button>`/`<a>`/table/list/select families reject or foster the component's own
-markup as the wrapper's siblings — so on hydration the skeleton locates the wrapper
-empty, claims `null`, and `attr` throws on it. Those names map to a hyphenated
-custom-element tag (a custom element is never void and has no content model) made
-layout-transparent with `display:contents`, so the component's real root still lays
-out as a direct child of the parent the way the (parse-broken) wrapper would have.
-A name that is NOT a known HTML element (the common case — `Card`, `Dropdown`) is an
-inert unknown tag that holds any content untouched, so it stays as-is. Both back-ends
-call this so the SSR string and the client build agree on the wrapper.
+The element tag a component instance mounts into: always `abide-<name>` lowercased. The
+`abide-` prefix makes every wrapper a valid custom element (contains a hyphen) — never
+void, no content model — so it holds the component's own markup untouched and hydrates
+cleanly, regardless of whether the name collides with an HTML element (`Button`, `Input`).
+Emitted with `display:contents` (see the back-ends) so the wrapper stays out of layout: a
+pure mount host whose real root lays out as a direct child of the parent, keeping the
+component invisible to `grid`/`subgrid`/`flex`. Both back-ends call this so the SSR string
+and the client build agree on the wrapper.
 */
-export function componentWrapperTag(name: string): { tag: string; transparent: boolean } {
-    const lower = name.toLowerCase()
-    return HTML_TAGS.has(lower)
-        ? { tag: `abide-${lower}`, transparent: true }
-        : { tag: lower, transparent: false }
+export function componentWrapperTag(name: string): string {
+    return `abide-${name.toLowerCase()}`
 }

package/src/lib/ui/compile/generateBuild.ts

@@ -4,9 +4,9 @@ import { bindListenEvent } from './bindListenEvent.ts'
 import { componentWrapperTag } from './componentWrapperTag.ts'
 import { groupBindParts } from './groupBindParts.ts'
 import { isControlFlow } from './isControlFlow.ts'
-import { isTextLeaf } from './isTextLeaf.ts'
 import { lowerContext } from './lowerContext.ts'
 import { scopeAttr } from './scopeAttr.ts'
+import { skeletonContext } from './skeletonContext.ts'
 import { staticAttr } from './staticAttr.ts'
 import { staticTextPart } from './staticTextPart.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
@@ -32,6 +32,13 @@ export function generateBuild(
     let counter = 0
     const nextVar = (prefix: string): string => `${prefix}${counter++}`
 
+    /* Per-node skeleton position from the SAME pass the SSR back-end reads — so the client's
+       anchor/text-leaf decisions consult one source of truth instead of re-deriving the
+       position structurally (the drift the shared context exists to prevent). `asOutlet`
+       only rewrites layout `<slot>`s and preserves text-node identity, so the original
+       `nodes` key the same text markers the build traversal looks up. */
+    const { markText } = skeletonContext(nodes)
+
     /* The shared signal→`model` lowering + branch-scoped nested-script deref scope. */
     const {
         expression: lowerExpression,
@@ -135,13 +142,12 @@ export function generateBuild(
         }
         if (node.kind === 'component') {
             /* The wrapper element is a positioned hole in the skeleton; the child mounts
-               into the located node (idempotent display:contents for a transparent wrap,
-               static so it lives in the markup). */
-            const { tag, transparent } = componentWrapperTag(node.name)
+               into the located node. display:contents (idempotent, static so it lives in
+               the markup) keeps the wrapper out of layout — a pure mount host. */
+            const tag = componentWrapperTag(node.name)
             const { code } = mountComponent(node, `${skVar}.el[${counter.el++}]`)
             binds.push(code)
-            const style = transparent ? ' style="display:contents"' : ''
-            return `<${tag} ${HOLE_ATTRIBUTE}${style}></${tag}>`
+            return `<${tag} ${HOLE_ATTRIBUTE} style="display:contents"></${tag}>`
         }
         if (node.kind === 'script') {
             /* A nested `<script>` (scoped reactive block) emits no markup — its lowered body
@@ -172,13 +178,16 @@ export function generateBuild(
             return '<!--a-->'
         }
         const hasReactiveAttr = node.attrs.some((attr) => attr.kind !== 'static')
-        const hasReactiveText = node.children.some(
+        const reactiveTextChild = node.children.find(
             (child) => child.kind === 'text' && child.parts.some((part) => part.kind !== 'static'),
         )
         /* A text-leaf (only text/style children) with reactive text binds marker-free via
            `generateChildren` on the located element; otherwise reactive text is interleaved
-           and uses `<!--a-->` anchors during the child recursion below. */
-        const textLeafBind = hasReactiveText && isTextLeaf(node)
+           and uses `<!--a-->` anchors during the child recursion below. The shared context
+           records the leaf's text as NOT interleaved (`markText` false) — read that flag the
+           SSR back-end also reads, rather than re-deriving leaf-ness via `isTextLeaf` here. */
+        const textLeafBind =
+            reactiveTextChild !== undefined && markText.get(reactiveTextChild) === false
         let openTag = `<${node.tag}`
         let elVar = ''
         if (hasReactiveAttr || textLeafBind) {

package/src/lib/ui/compile/generateSSR.ts

@@ -184,7 +184,7 @@ export function generateSSR(
                the same wrapper the client mounts into, so SSR and client agree.
                Props pass as thunks; slot content passes as a string-returning
                `$children` the child invokes from its <slot>. */
-            const { tag, transparent } = componentWrapperTag(node.name)
+            const tag = componentWrapperTag(node.name)
             const parts = node.props.map(
                 (prop) => `${JSON.stringify(prop.name)}: () => (${lowerExpression(prop.code)})`,
             )
@@ -206,7 +206,7 @@ export function generateSSR(
                the enclosing render body, including from branch closures.) */
             const result = nextVar('$child')
             return (
-                push(target, `<${tag}${transparent ? ' style="display:contents"' : ''}>`) +
+                push(target, `<${tag} style="display:contents">`) +
                 `const ${result} = ${node.name}.render({ ${parts.join(', ')} });\n` +
                 `${target}.push(${result}.html);\n` +
                 `for (const $a of ${result}.awaits) { $awaits.push($a); }\n` +

package/src/lib/ui/createScope.ts

@@ -3,6 +3,7 @@ import { history } from './history.ts'
 import { linked } from './linked.ts'
 import { persist as persistDoc } from './persist.ts'
 import { createDoc } from './runtime/createDoc.ts'
+import { liveScopes } from './runtime/liveScopes.ts'
 import type { Doc } from './runtime/types/Doc.ts'
 import { state } from './state.ts'
 import { sync } from './sync.ts'
@@ -28,6 +29,7 @@ export function createScope(
     initial: unknown = {},
     parent: Scope | undefined = undefined,
     awaiting = false,
+    label: string | undefined = undefined,
 ): Scope {
     /* Eager unless awaiting adoption; `data()` lazily mints an empty doc if a body
        never created one (a stateless component that still reaches for its scope). */
@@ -41,6 +43,7 @@ export function createScope(
 
     const self: Scope = {
         id,
+        label,
         parent,
         read: (path) => data().read(path),
         replace: (path, value) => data().replace(path, value),
@@ -85,7 +88,15 @@ export function createScope(
             persistence = undefined
             unsync?.()
             unsync = undefined
+            if (liveScopes.enabled) {
+                liveScopes.scopes.delete(self)
+            }
         },
     }
+    /* Dev-only: register for the inspector's scope-tree view. Gated, so production
+       never touches the set. */
+    if (liveScopes.enabled) {
+        liveScopes.scopes.add(self)
+    }
     return self
 }

package/src/lib/ui/dom/awaitBlock.ts

@@ -3,6 +3,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { discardBoundary } from './discardBoundary.ts'
 import { enterNamespace } from './enterNamespace.ts'
 
@@ -41,6 +42,9 @@ export function awaitBlock(
     before: Node | null = null,
 ): void {
     const hydration = RENDER.hydration
+    /* The live branch's scope, registered with the owner so it disposes on owner
+       teardown — not only when a settle/re-run swaps branches via detach. */
+    const group = scopeGroup()
     let active: { nodes: Node[]; dispose: () => void } | undefined
     let anchor: Node | undefined
     let first = true
@@ -67,8 +71,8 @@ export function awaitBlock(
     const place = (build: (parent: Node) => void): void => {
         detach()
         const fragment = document.createDocumentFragment()
-        const dispose = enterNamespace(anchor?.parentNode ?? parent, () =>
-            scope(() => build(fragment)),
+        const dispose = group.track(
+            enterNamespace(anchor?.parentNode ?? parent, () => scope(() => build(fragment))),
         )
         const nodes = [...fragment.childNodes]
         ;(anchor?.parentNode ?? parent).insertBefore(fragment, anchor ?? null)
@@ -112,7 +116,7 @@ export function awaitBlock(
     const adopt = (open: Node | null, build: (parent: Node) => void): void => {
         const cursor = hydration as NonNullable<typeof hydration>
         cursor.next.set(parent, open?.nextSibling ?? null)
-        const dispose = scope(() => build(parent))
+        const dispose = group.track(scope(() => build(parent)))
         const close = claimChild(cursor, parent)
         cursor.next.set(parent, close?.nextSibling ?? null)
         const nodes: Node[] = []

package/src/lib/ui/dom/each.ts

@@ -1,9 +1,9 @@
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { claimExpected } from '../runtime/claimExpected.ts'
-import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { enterNamespace } from './enterNamespace.ts'
 import { moveRange } from './moveRange.ts'
 import { removeRange } from './removeRange.ts'
@@ -36,6 +36,9 @@ export function each<T>(
     before: Node | null = null,
 ): void {
     const rows = new Map<string, EachRow>()
+    /* Each row's scope, registered with the owner so every live row disposes on owner
+       teardown (the effect's own disposer only unsubscribes it from `items()`). */
+    const group = scopeGroup()
 
     /* Build a row's range. Hydrate mode (only while the claim cursor is active —
        read fresh, since a row built by a post-hydration reconcile must create, not
@@ -47,7 +50,7 @@ export function each<T>(
         if (hydration !== undefined) {
             const start = claimExpected(hydration, parent, 'each row start marker')
             hydration.next.set(parent, start.nextSibling)
-            const dispose = scope(() => render(parent, item))
+            const dispose = group.track(scope(() => render(parent, item)))
             const end = claimExpected(hydration, parent, 'each row end marker')
             hydration.next.set(parent, end.nextSibling)
             return { start, end, dispose }
@@ -58,7 +61,9 @@ export function each<T>(
         pending.appendChild(start)
         /* Build under `parent`'s foreign namespace so foreign row elements (svg/math)
            built into the detached fragment are namespaced, not built as HTML. */
-        const dispose = enterNamespace(parent, () => scope(() => render(pending, item)))
+        const dispose = group.track(
+            enterNamespace(parent, () => scope(() => render(pending, item))),
+        )
         pending.appendChild(end)
         return { start, end, dispose, pending }
     }
@@ -146,16 +151,4 @@ export function each<T>(
             RENDER.hydration = previousHydration
         }
     })
-
-    /* Dispose every row still live when the enclosing scope tears down (the effect's
-       own disposer only unsubscribes it from `items()`). The host's DOM is cleared by
-       `mount`, so disposal need not remove the nodes. */
-    if (OWNER.current !== undefined) {
-        OWNER.current.push(() => {
-            for (const row of rows.values()) {
-                row.dispose()
-            }
-            rows.clear()
-        })
-    }
 }

package/src/lib/ui/dom/eachAsync.ts

@@ -3,6 +3,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { enterNamespace } from './enterNamespace.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
@@ -32,6 +33,9 @@ export function eachAsync<T>(
     before: Node | null = null,
 ): void {
     const rows = new Map<string, EachRow>()
+    /* Each row's (and the error branch's) scope, registered with the owner so they
+       dispose on owner teardown; the block's own teardown only stops the stream. */
+    const group = scopeGroup()
     const hydration = RENDER.hydration
     const anchor = document.createTextNode('')
     if (hydration !== undefined) {
@@ -46,8 +50,8 @@ export function eachAsync<T>(
         const end = document.createComment(']')
         const fragment = document.createDocumentFragment()
         fragment.appendChild(start)
-        const dispose = enterNamespace(anchor.parentNode ?? parent, () =>
-            scope(() => build(fragment)),
+        const dispose = group.track(
+            enterNamespace(anchor.parentNode ?? parent, () => scope(() => build(fragment))),
         )
         fragment.appendChild(end)
         /* Insert via the anchor's LIVE parent: when this `each` is a bare child of a
@@ -127,18 +131,13 @@ export function eachAsync<T>(
     })
 
     /* Stop the live stream when the enclosing scope tears down: bump the generation so
-       the drain abandons its loop, `return()` the iterator to release the source, drop
-       the error branch, and dispose every surviving row. */
+       the drain abandons its loop and `return()` the iterator to release the source. The
+       rows and error branch are disposed by the group (their scopes were tracked). */
     if (OWNER.current !== undefined) {
         OWNER.current.push(() => {
             generation += 1
             iterator?.return?.(undefined)?.catch(() => undefined)
             iterator = undefined
-            clearError()
-            for (const row of rows.values()) {
-                row.dispose()
-            }
-            rows.clear()
         })
     }
 }

package/src/lib/ui/dom/hydrate.ts

@@ -4,6 +4,7 @@ import { enterRenderPass } from '../runtime/enterRenderPass.ts'
 import { exitRenderPass } from '../runtime/exitRenderPass.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeLabel } from './scopeLabel.ts'
 
 /*
 Adopts existing server-rendered DOM instead of rebuilding it. Runs `build(host)`
@@ -28,7 +29,7 @@ export function hydrate(host: Element, build: (host: Element) => void): () => vo
     /* Same lexical scope establishment as `mount` — a hydrated component owns a scope
        too, adopting the model its build adopts. */
     const parentScope = CURRENT_SCOPE.current
-    const lexical = createScope({}, parentScope, true)
+    const lexical = createScope({}, parentScope, true, scopeLabel(host))
     CURRENT_SCOPE.current = lexical
     try {
         const stop = scope(() => {

package/src/lib/ui/dom/mount.ts

@@ -3,6 +3,7 @@ import { CURRENT_SCOPE } from '../runtime/CURRENT_SCOPE.ts'
 import { enterRenderPass } from '../runtime/enterRenderPass.ts'
 import { exitRenderPass } from '../runtime/exitRenderPass.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeLabel } from './scopeLabel.ts'
 
 /*
 Mounts a component into `host`: runs `build(host)` under an ownership scope so
@@ -22,7 +23,7 @@ export function mount(host: Element, build: (host: Element) => void): () => void
        `scope()` and its capabilities resolve to it during the build; the previous
        scope is restored after (synchronous build, so the restore is exact). */
     const parentScope = CURRENT_SCOPE.current
-    const lexical = createScope({}, parentScope, true)
+    const lexical = createScope({}, parentScope, true, scopeLabel(host))
     CURRENT_SCOPE.current = lexical
     const stop = scope(() => {
         try {

package/src/lib/ui/dom/scopeLabel.ts

@@ -0,0 +1,15 @@
+/*
+The human-readable name for the scope a mount/hydrate establishes, derived from
+its host element's tag. A nested component mounts into its `abide-<name>` wrapper
+(see `componentWrapperTag`), so stripping the `abide-` prefix recovers the
+component name; any other host (a page/layout outlet) yields its lowercased tag.
+Dev-only — feeds the inspector's Reactive tab so a scope reads `<Counter>` rather
+than an opaque counter id. Returns undefined when there's no element to name from.
+*/
+export function scopeLabel(host: Element): string | undefined {
+    const tag = host.tagName?.toLowerCase()
+    if (tag === undefined) {
+        return undefined
+    }
+    return tag.startsWith('abide-') ? tag.slice('abide-'.length) : tag
+}

package/src/lib/ui/dom/skeleton.ts

@@ -26,6 +26,16 @@ function isElement(node: Node): node is Element {
     return typeof (node as Element).hasAttribute === 'function'
 }
 
+/* A child component's mount wrapper (`abide-<name>`, see `componentWrapperTag`). Its
+   content is a SEPARATE skeleton (the child's own), so the parent's walks must treat it
+   as opaque: in the shallow skeleton it's an empty leaf, so the compiler counts no
+   anchors inside it; on hydrate it's populated, so a descent would over-collect the
+   child's anchors and shift every parent index past it (same hazard as a block range,
+   but bounded by the wrapper element instead of `[`…`]` markers). */
+function isComponentWrapper(node: Node): boolean {
+    return isElement(node) && (node.tagName ?? '').toLowerCase().startsWith('abide-')
+}
+
 /* A comment node's data, or undefined for elements/text. A comment is a node that is
    neither an element (`hasAttribute`) nor a text node (`splitText`); the mini-dom
    exposes no `nodeType`, so detect by method. */
@@ -113,7 +123,9 @@ function scanAnchors(nodes: ArrayLike<Node>, anchors: Node[]): void {
         const node = nodes[index] as Node
         const data = commentData(node)
         if (data === undefined) {
-            if (isElement(node) && depth === 0) {
+            /* Recurse into this skeleton's own elements, but NOT a child component's
+               wrapper — its anchors belong to the child's skeleton (see above). */
+            if (isElement(node) && depth === 0 && !isComponentWrapper(node)) {
                 scanAnchors(node.childNodes, anchors)
             }
         } else if (isCloseMarker(data)) {

package/src/lib/ui/dom/switchBlock.ts

@@ -1,6 +1,7 @@
 import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { clearBetween } from './clearBetween.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
@@ -26,6 +27,9 @@ export function switchBlock(
     before: Node | null = null,
 ): void {
     const hydration = RENDER.hydration
+    /* The live case's scope, registered with the owner so it disposes on owner
+       teardown — not only when the subject switches cases via clearBetween. */
+    const group = scopeGroup()
     let dispose: (() => void) | undefined
     let activeIndex: number
     let end: Comment
@@ -46,7 +50,7 @@ export function switchBlock(
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
         if (chosen !== undefined) {
-            dispose = scope(() => chosen.render(parent)) // claim the SSR nodes in place
+            dispose = group.track(scope(() => chosen.render(parent))) // claim the SSR nodes in place
         }
         end = openMarker(parent, ']')
     } else {
@@ -54,7 +58,7 @@ export function switchBlock(
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, (p) => chosen.render(p))
+            dispose = group.track(fillBefore(end, (p) => chosen.render(p)))
         }
     }
 
@@ -68,7 +72,7 @@ export function switchBlock(
         activeIndex = index
         const chosen = caseAt(index)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, (p) => chosen.render(p))
+            dispose = group.track(fillBefore(end, (p) => chosen.render(p)))
         }
     })
 }

package/src/lib/ui/dom/tryBlock.ts

@@ -1,6 +1,7 @@
 import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { discardBoundary } from './discardBoundary.ts'
 import { enterNamespace } from './enterNamespace.ts'
 
@@ -28,20 +29,30 @@ export function tryBlock(
     renderCatch?: (parent: Node, error: unknown) => void,
     before: Node | null = null,
 ): void {
-    /* Run a void build under a fresh ownership scope; on throw, tear down the partial
-       effects/listeners it registered and rethrow so the caller can fall back. */
+    /* The guarded subtree's scope, registered with the owner so it disposes on owner
+       teardown. The block renders once, so there is at most one tracked subtree (the
+       try branch, or the catch branch if try threw). */
+    const group = scopeGroup()
+    /* Run a void build under a fresh ownership scope. On success, hand its disposers to
+       the group so the subtree tears down with the owner (they were previously dropped —
+       the leak). On throw, tear down the partial build now and rethrow so the caller can
+       fall back to the catch branch. */
     const guard = (build: () => void): void => {
         const previous = OWNER.current
         const disposers: Array<() => void> = []
         OWNER.current = disposers
+        const disposeAll = (): void => {
+            for (let index = disposers.length - 1; index >= 0; index -= 1) {
+                disposers[index]?.()
+            }
+        }
         try {
             build()
             OWNER.current = previous
+            group.track(disposeAll)
         } catch (error) {
             OWNER.current = previous
-            for (let index = disposers.length - 1; index >= 0; index -= 1) {
-                disposers[index]?.()
-            }
+            disposeAll()
             throw error
         }
     }

package/src/lib/ui/dom/when.ts

@@ -1,6 +1,7 @@
 import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { clearBetween } from './clearBetween.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
@@ -28,6 +29,9 @@ export function when(
 ): void {
     const hydration = RENDER.hydration
     const chosenFor = (branch: 'then' | 'else') => (branch === 'then' ? render : renderElse)
+    /* The live branch's scope, registered with the owner so it disposes on owner
+       teardown — not only on a branch flip via clearBetween. */
+    const group = scopeGroup()
     let dispose: (() => void) | undefined
     let activeBranch: 'then' | 'else'
     let end: Comment
@@ -40,7 +44,7 @@ export function when(
         activeBranch = condition() ? 'then' : 'else'
         const chosen = chosenFor(activeBranch)
         if (chosen !== undefined) {
-            dispose = scope(() => chosen(parent)) // content claims the SSR nodes in place
+            dispose = group.track(scope(() => chosen(parent))) // content claims the SSR nodes in place
         }
         end = openMarker(parent, ']')
     } else {
@@ -48,7 +52,7 @@ export function when(
         activeBranch = condition() ? 'then' : 'else'
         const chosen = chosenFor(activeBranch)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, chosen)
+            dispose = group.track(fillBefore(end, chosen))
         }
     }
 
@@ -62,7 +66,7 @@ export function when(
         activeBranch = branch
         const chosen = chosenFor(branch)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, chosen)
+            dispose = group.track(fillBefore(end, chosen))
         }
     })
 }

package/src/lib/ui/installInspectorBridge.ts

@@ -0,0 +1,138 @@
+import { effect } from './effect.ts'
+import { clientPage } from './runtime/clientPage.ts'
+import { historyEntries } from './runtime/historyEntries.ts'
+import { liveScopes } from './runtime/liveScopes.ts'
+import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
+import { runtimePath } from './runtime/runtimePath.ts'
+
+/* Same-origin cross-tab channel the inspector page listens on. The app tab
+   publishes scope + router state; the inspector subscribes. Web-standard, so no
+   server route or buffer is involved — core publishes, the package consumes. */
+const CHANNEL = 'abide:inspector'
+
+/* Coalesce a burst of patches into one snapshot — the post is the cost, the read is cheap. */
+const SNAPSHOT_DEBOUNCE_MS = 60
+
+/* JSON round-trip to strip anything structured-clone can't carry (functions,
+   class instances, DOM nodes) before postMessage, degrading to undefined rather
+   than throwing into the channel. */
+function cloneable(value: unknown): unknown {
+    try {
+        return JSON.parse(JSON.stringify(value))
+    } catch {
+        return undefined
+    }
+}
+
+/* The live scope forest as a flat list — the inspector rebuilds the tree from
+   each node's `parent` id (the Scope surface exposes no children accessor). */
+function scopeNodes(): Array<{
+    id: string
+    label: string | undefined
+    parent: string | undefined
+    state: unknown
+    recorded: boolean
+}> {
+    return Array.from(liveScopes.scopes, (scope) => ({
+        id: scope.id,
+        label: scope.label,
+        parent: scope.parent?.id,
+        state: cloneable(scope.snapshot()),
+        recorded: scope.canUndo() || scope.canRedo(),
+    }))
+}
+
+/* Router state off the existing reactive holders — read, not subscribed, here;
+   the nav effect drives re-reads. */
+function routerState() {
+    const page = clientPage.value
+    return {
+        path: runtimePath.value,
+        route: page.route,
+        params: page.params,
+        navigating: page.navigating,
+        url: page.url.href,
+        entry: historyEntries.current,
+    }
+}
+
+/*
+Installs the client→inspector bridge: a BroadcastChannel the inspector page reads
+to render its Reactive + Router tabs. Gated by `__abideInspect` (server-injected
+only when the inspector is enabled) and called from startClient before the router
+builds any scope — so registration is armed before the first scope exists. A
+no-op where BroadcastChannel is absent (SSR, old runtimes). Mirrors
+installHotBridge: dev instrumentation, not public surface.
+*/
+export function installInspectorBridge(): void {
+    /* No BroadcastChannel means no consumer for the scope registry — bail before
+       arming `liveScopes.enabled`, so createScope never pays scope tracking for a
+       set nothing reads. */
+    if (typeof BroadcastChannel === 'undefined') {
+        return
+    }
+    liveScopes.enabled = true
+    const channel = new BroadcastChannel(CHANNEL)
+    const tab = typeof crypto !== 'undefined' ? crypto.randomUUID() : String(performance.now())
+    const post = (message: object) => {
+        try {
+            channel.postMessage({ tab, ...message })
+        } catch {
+            /* A non-cloneable slipped through despite the JSON pass — drop the frame
+               rather than throw into a patch/nav handler. */
+        }
+    }
+
+    const announce = () =>
+        post({
+            kind: 'announce',
+            url: typeof location !== 'undefined' ? location.href : '',
+            app: typeof document !== 'undefined' ? document.title : '',
+        })
+    const sendSnapshot = () =>
+        post({ kind: 'snapshot', scopes: scopeNodes(), router: routerState() })
+
+    let snapshotTimer: ReturnType<typeof setTimeout> | undefined
+    const scheduleSnapshot = () => {
+        clearTimeout(snapshotTimer)
+        snapshotTimer = setTimeout(sendSnapshot, SNAPSHOT_DEBOUNCE_MS)
+    }
+
+    /* Inspector handshakes: `hello` (it just opened — everyone re-announce + push)
+       and `request` (it wants a fresh snapshot of this tab). */
+    channel.onmessage = (event) => {
+        const message = event.data as { kind?: string; tab?: string }
+        if (message.kind === 'hello') {
+            announce()
+            sendSnapshot()
+        } else if (message.kind === 'request' && message.tab === tab) {
+            sendSnapshot()
+        }
+    }
+
+    /* Every doc mutation flows through PATCH_BUS; forward the patch as a live
+       mutation event and re-snapshot (debounced) so values stay current. */
+    PATCH_BUS.subscribe((patchEvent) => {
+        post({ kind: 'patch', op: patchEvent.patch.op, path: patchEvent.patch.path })
+        scheduleSnapshot()
+    })
+
+    /* Reading the page + path States tracks them, so this re-runs on navigation. */
+    effect(() => {
+        clientPage.value
+        runtimePath.value
+        post({ kind: 'nav', router: routerState() })
+    })
+
+    if (typeof addEventListener === 'function') {
+        addEventListener('pagehide', () => {
+            post({ kind: 'bye' })
+            channel.close()
+        })
+    }
+
+    announce()
+    /* First snapshot once the router has built the initial scope tree (this runs
+       before router()). */
+    setTimeout(sendSnapshot, 0)
+}