@abide/abide 0.36.0 → 0.38.0

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

@@ -5,74 +5,137 @@ import type { SkeletonContext } from './types/SkeletonContext.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 
 /*
-The single source of truth for where skeleton markers go. One top-down walk records,
-per node, whether it sits inside a parser-backed skeleton clone (`inSkeleton`) and
-whether its reactive text is interleaved (`markText`) — the two facts that decide
-`<!--a-->` anchor placement. Both back-ends read this instead of re-deriving the
-position (the client structurally, the server as mutable traversal state), which is
-what let them drift: a fresh-context boundary the server forgot to reset leaked an
-anchor the client never emitted, desyncing hydration.
+The single source of truth for where skeleton markers go AND what their hole indices are.
+One top-down walk records, per node, whether it sits inside a parser-backed skeleton clone
+(`inSkeleton`) and whether its reactive text is interleaved (`markText`) — the two facts
+that decide `<!--a-->` anchor placement — and assigns each hole its `el`/`an` index.
+`generateBuild` reads these indices instead of threading its own counter through a second
+document-order walk, so the numbering cannot drift from the decisions: one walk owns both.
 
-A fresh-context boundary resets to NOT-in-skeleton, because the content there is
-built by its own runtime (a control-flow block's branch, a component's slot content,
-a `<slot>`'s fallback, a snippet's body) — never cloned by the enclosing skeleton —
-so an enclosing skeletonable subtree must not stamp markers onto it. Enumerating
-every such boundary HERE, once, makes "forgetting to reset one" impossible.
+The index assignment is scoped per skeleton root (a `skeletonable` element not already in a
+skeleton — the unit `generateSkeleton` instantiates with `{ el: 0, an: 0 }`; a standalone
+component roots its own skeleton too). `el` numbers element holes in pre-order; `an` numbers
+anchor holes (interleaved reactive text PARTS, control-flow blocks, `<slot>` outlets) in
+document order — the orders the runtime's `indexElementHoles`/`scanAnchors` re-derive from
+the realized DOM, so the compile-time numbers and the runtime positions line up.
+
+A fresh-context boundary resets to NOT-in-skeleton (and to no active counter), because the
+content there is built by its own runtime (a control-flow block's branch, a component's slot
+content, a `<slot>`'s fallback, a snippet's body) — never cloned by the enclosing skeleton.
 */
 export function skeletonContext(nodes: TemplateNode[]): SkeletonContext {
     const inSkeleton = new WeakMap<TemplateNode, boolean>()
     const markText = new WeakMap<TemplateNode, boolean>()
+    /* Element holes keyed by node; anchor holes keyed by node (control-flow/slot) OR by the
+       reactive text PART object (a text node carries one anchor per reactive part). */
+    const elIndex = new WeakMap<TemplateNode, number>()
+    const anIndex = new WeakMap<object, number>()
+
+    type Counter = { el: number; an: number }
 
-    /* Walk `node` carrying the context that applies AT it; recurse into children with the
-       context that applies to THEM. */
-    function visit(node: TemplateNode, nodeInSkeleton: boolean, nodeMarkText: boolean): void {
+    /* Walk `node` carrying the context AND the active skeleton counter that apply AT it
+       (`counter === undefined` outside any skeleton — no holes are numbered there). */
+    function visit(
+        node: TemplateNode,
+        nodeInSkeleton: boolean,
+        nodeMarkText: boolean,
+        counter: Counter | undefined,
+    ): void {
         inSkeleton.set(node, nodeInSkeleton)
         markText.set(node, nodeMarkText)
 
-        /* Control-flow branches, component slot content, and snippet bodies are fresh build
-           contexts — their children re-enter the skeleton only via their own skeletonable
-           elements, so reset both flags. (A standalone branch/case is reached as a child of
-           its control-flow node and likewise resets.) */
+        /* Control-flow blocks, components, and snippets are fresh build contexts. The node
+           ITSELF is a hole in the enclosing skeleton (an anchor for a block, an element hole
+           for a component); its children re-enter the skeleton only via their own roots. */
         if (isControlFlow(node) || node.kind === 'component' || node.kind === 'snippet') {
+            /* A control-flow block takes an anchor only inside an enclosing skeleton (a
+               standalone block routes through `generateIf`/etc, not the skeleton path). */
+            if (counter !== undefined && isControlFlow(node)) {
+                anIndex.set(node, counter.an++)
+            }
+            /* A component is its OWN element hole either way: in the enclosing skeleton's
+               counter when nested, else as the root (index 0) of its own standalone skeleton
+               (`generateChild` routes a lone component through `generateSkeleton` too). */
+            if (node.kind === 'component') {
+                const componentCounter = counter ?? { el: 0, an: 0 }
+                elIndex.set(node, componentCounter.el++)
+            }
             for (const child of childrenOf(node)) {
-                visit(child, false, false)
+                visit(child, false, false, undefined)
             }
             return
         }
-        /* A `branch`/`case` is a transparent grouping inside its control-flow block (its
-           children are generated directly, the wrapper never emits markup) — pass the
-           already-reset context through so a skeletonable element inside it re-enters. */
+        /* A `branch`/`case` is a transparent grouping inside its control-flow block — pass the
+           already-reset context (and absent counter) through so a skeletonable element inside
+           it opens its own skeleton. */
         if (node.kind === 'branch' || node.kind === 'case') {
             for (const child of node.children) {
-                visit(child, nodeInSkeleton, nodeMarkText)
+                visit(child, nodeInSkeleton, nodeMarkText, counter)
+            }
+            return
+        }
+        if (node.kind === 'text') {
+            /* Interleaved reactive text (markText true): each reactive part takes an `<!--a-->`
+               anchor, numbered in document order. A text-leaf's text (markText false) binds
+               marker-free via the element, so its parts take no anchor. */
+            if (counter !== undefined && nodeMarkText) {
+                for (const part of node.parts) {
+                    if (part.kind !== 'static') {
+                        anIndex.set(part, counter.an++)
+                    }
+                }
             }
             return
         }
         if (node.kind !== 'element') {
-            return // text / script / style carry no skeleton children
+            return // script / style carry no skeleton children and no hole
         }
         if (node.tag === 'slot') {
-            /* The slot's own children are its fallback — a fresh context built by `mountSlot`,
-               not the enclosing clone. */
+            /* The slot outlet is an anchor hole in the enclosing skeleton; its children are
+               the fallback — a fresh context built by `mountSlot`. */
+            if (counter !== undefined) {
+                anIndex.set(node, counter.an++)
+            }
             for (const child of node.children) {
-                visit(child, false, false)
+                visit(child, false, false, undefined)
             }
             return
         }
-        /* A skeletonable element not already in a skeleton opens one; its descendants are in
-           skeleton. Reactive text interleaves (takes an anchor) unless this element is a
-           text-leaf (only text/style children), which binds its text marker-free. */
+        /* A skeletonable element not already in a skeleton OPENS one (a fresh counter — the
+           `generateSkeleton` unit). An element already in a skeleton uses the enclosing
+           counter. A static element outside any skeleton numbers nothing. */
+        const opensSkeleton = !nodeInSkeleton && skeletonable(node)
         const childInSkeleton = nodeInSkeleton || skeletonable(node)
+        const effectiveCounter = nodeInSkeleton
+            ? counter
+            : opensSkeleton
+              ? { el: 0, an: 0 }
+              : undefined
         const childMarkText = childInSkeleton && !isTextLeaf(node)
+
+        if (effectiveCounter !== undefined) {
+            /* The element is a located hole when it carries a reactive attr/listener/bind, or
+               binds text-leaf reactive text on itself. Take its `el` index BEFORE recursing,
+               so holes number in pre-order — the order the runtime's path walk produces them. */
+            const hasReactiveAttr = node.attrs.some((attr) => attr.kind !== 'static')
+            const reactiveTextChild = node.children.find(
+                (child) =>
+                    child.kind === 'text' && child.parts.some((part) => part.kind !== 'static'),
+            )
+            const textLeafBind = reactiveTextChild !== undefined && isTextLeaf(node)
+            if (hasReactiveAttr || textLeafBind) {
+                elIndex.set(node, effectiveCounter.el++)
+            }
+        }
         for (const child of node.children) {
-            visit(child, childInSkeleton, childMarkText)
+            visit(child, childInSkeleton, childMarkText, effectiveCounter)
         }
     }
 
     for (const node of nodes) {
-        visit(node, false, false)
+        visit(node, false, false, undefined)
     }
-    return { inSkeleton, markText }
+    return { inSkeleton, markText, elIndex, anIndex }
 }
 
 /* The child list of any node that has one (control-flow, component, snippet, element);

package/src/lib/ui/compile/types/SkeletonContext.ts

@@ -12,4 +12,10 @@ filled by one shared `skeletonContext` pass over the parsed tree.
 export type SkeletonContext = {
     inSkeleton: WeakMap<TemplateNode, boolean>
     markText: WeakMap<TemplateNode, boolean>
+    /* Per-hole indices assigned in the same walk, so `generateBuild` reads its `sk.el`/`sk.an`
+       numbering rather than re-deriving it. `elIndex` keyed by element/component node;
+       `anIndex` keyed by control-flow/slot node OR by a reactive text PART object (a text node
+       carries one anchor per reactive part). */
+    elIndex: WeakMap<TemplateNode, number>
+    anIndex: WeakMap<object, number>
 }

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/appendSnippet.ts

@@ -1,34 +1,74 @@
 import { snippetPayload } from '../../shared/snippet.ts'
-import { claimChild } from '../runtime/claimChild.ts'
+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'
 
 /*
-A `{snippet(args)}` interpolation: mount the branded builder's nodes at this
-position. The builder builds straight into `parent` — sequential build order
-places it correctly among siblings, and its effects join the surrounding
-component scope (so they tear down with it). The body's reactive reads update
-fine-grained via those effects; an enclosing `each` re-mounts on list changes.
+A `{snippet(args)}` interpolation: mount the branded builder's nodes in a range
+bounded by two comment markers. The content builds straight into `parent` —
+sequential build order places it correctly among siblings — and its effects join
+the surrounding component scope, so the body's reactive reads update fine-grained.
+
+The CALL is reactive in its arguments: an effect re-reads `read()` so a change in
+the argument expression (e.g. `{row(items())}`) tears the range down and rebuilds
+with fresh args. `read()` returns a fresh builder closing over freshly-evaluated
+args each call, so there is nothing to diff — the snippet re-mounts as a unit, the
+same coarse model as `when`/`each` (args behave like props). The body's own reads
+stay fine-grained within a single mount; the outer effect tracks only the args,
+since `fillBefore` wraps the body in its own scope.
 
 On hydrate the builder runs against the server-rendered nodes between the
 `<!--abide:snippet-->`/`<!--/abide:snippet-->` markers — its `skeleton`/`appendText`
-claim them in place. The cursor is advanced past the open marker before, and past
-the close marker after, so the markers themselves are skipped.
+claim them in place — and the effect's first run is a no-op that only subscribes to
+the args; a later argument change rebuilds fresh (the SSR markers stay as the range).
 */
 // @documentation plumbing
 export function appendSnippet(parent: Node, read: () => unknown): void {
-    const builder = snippetPayload(read())
-    if (typeof builder !== 'function') {
-        return
-    }
-    const mount = builder as (host: Node) => void
     const hydration = RENDER.hydration
+    /* Mount scopes register with the owner so they dispose on owner teardown, not
+       only on an argument-driven rebuild via clearBetween. */
+    const group = scopeGroup()
+    let dispose: (() => void) | undefined
+
+    /* The branded builder, or undefined for anything else (a non-snippet value
+       mounts nothing — the range stays empty until the args yield a builder). */
+    const builderOf = (): ((host: Node) => void) | undefined => {
+        const payload = snippetPayload(read())
+        return typeof payload === 'function' ? (payload as (host: Node) => void) : undefined
+    }
+
+    let open: Comment
+    let close: Comment
     if (hydration !== undefined) {
-        const open = claimChild(hydration, parent)
-        hydration.next.set(parent, open === null ? null : open.nextSibling)
-        mount(parent)
-        const close = claimChild(hydration, parent)
-        hydration.next.set(parent, close === null ? null : close.nextSibling)
-        return
+        open = openMarker(parent, 'abide:snippet')
+        const builder = builderOf()
+        if (builder !== undefined) {
+            dispose = group.track(scope(() => builder(parent))) // content claims the SSR nodes in place
+        }
+        close = openMarker(parent, '/abide:snippet')
+    } else {
+        open = openMarker(parent, 'abide:snippet')
+        close = openMarker(parent, '/abide:snippet')
+        const builder = builderOf()
+        if (builder !== undefined) {
+            dispose = group.track(fillBefore(close, builder))
+        }
     }
-    mount(parent)
+
+    /* The initial mount is built above (create or hydrate); the first effect run only
+       subscribes to the args via `builderOf`, then later argument changes rebuild. */
+    let first = true
+    effect(() => {
+        const builder = builderOf()
+        if (first) {
+            first = false
+            return
+        }
+        clearBetween(open, close, dispose)
+        dispose = builder !== undefined ? group.track(fillBefore(close, builder)) : undefined
+    })
 }

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

@@ -18,6 +18,16 @@ would otherwise make the build helpers claim SSR nodes that don't exist for fres
 content. The same cursor is restored after (mirrors awaitBlock/tryBlock/each).
 */
 export function fillBefore(end: Node, content: (into: Node) => void): () => void {
+    /* A control-flow effect can fire one final time after its block was already
+       detached — e.g. an enclosing await/each block tears the branch down in the same
+       microtask flush that re-ran this effect, before the owner scope disposes it. The
+       end marker then has no live parent, so there is nowhere to build into; inserting
+       a fragment before a parentless comment throws HierarchyRequestError ("would yield
+       an incorrect node tree"). Skip the rebuild — owner teardown disposes this dead
+       block anyway. */
+    if (!end.parentNode) {
+        return () => {}
+    }
     const fragment = document.createDocumentFragment()
     const previousHydration = RENDER.hydration
     RENDER.hydration = undefined

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/mountSlot.ts

@@ -1,5 +1,6 @@
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
 
@@ -21,12 +22,16 @@ export function mountSlot(
     before: Node | null = null,
 ): void {
     const hydration = RENDER.hydration
+    /* The slot content's scope, registered with the owner so its effects/listeners
+       dispose on owner teardown (a navigation) — the slot never toggles, so the
+       group only ever tracks this one child. */
+    const group = scopeGroup()
     openMarker(parent, '[', before)
     if (hydration !== undefined) {
-        scope(() => render(parent)) // content claims the SSR range in place
+        group.track(scope(() => render(parent))) // content claims the SSR range in place
         openMarker(parent, ']')
     } else {
         const end = openMarker(parent, ']', before)
-        fillBefore(end, render)
+        group.track(fillBefore(end, render))
     }
 }

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

@@ -0,0 +1,19 @@
+/*
+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.
+*/
+import { COMPONENT_WRAPPER_PREFIX } from '../COMPONENT_WRAPPER_PREFIX.ts'
+
+export function scopeLabel(host: Element): string | undefined {
+    const tag = host.tagName?.toLowerCase()
+    if (tag === undefined) {
+        return undefined
+    }
+    return tag.startsWith(COMPONENT_WRAPPER_PREFIX)
+        ? tag.slice(COMPONENT_WRAPPER_PREFIX.length)
+        : tag
+}

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

@@ -1,3 +1,4 @@
+import { COMPONENT_WRAPPER_PREFIX } from '../COMPONENT_WRAPPER_PREFIX.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { HOLE_ATTRIBUTE } from '../runtime/HOLE_ATTRIBUTE.ts'
 import { RENDER } from '../runtime/RENDER.ts'
@@ -26,6 +27,18 @@ 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(COMPONENT_WRAPPER_PREFIX)
+    )
+}
+
 /* 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 +126,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/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)
+}

package/src/lib/ui/navigate.ts

@@ -1,16 +1,24 @@
+import { historyEntries } from './runtime/historyEntries.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 
 /* Navigates to `path`: writes a history entry (when available) and updates the
    reactive route, which re-mounts the matching page via `router`. `replace` swaps
    the current entry instead of pushing — used when honouring a server redirect, so
-   the blocked URL isn't left behind in history. */
+   the blocked URL isn't left behind in history. Each entry carries a monotonic
+   `abideEntry` id so the router can bucket/restore its scroll offset across the page
+   teardown the rebuild does. A push leaves the current entry behind — its scroll is
+   bucketed so back restores it — and mints a fresh id. A replace destroys the current
+   entry and lands fresh content (a redirect), so its saved scroll no longer applies:
+   the bucket is discarded and the id kept, so the new page restores to top/anchor. */
 // @documentation navigate
 export function navigate(path: string, replace = false): void {
     if (typeof history !== 'undefined') {
         if (replace) {
-            history.replaceState({}, '', path)
+            historyEntries.discard()
+            history.replaceState({ abideEntry: historyEntries.current }, '', path)
         } else {
-            history.pushState({}, '', path)
+            historyEntries.save()
+            history.pushState({ abideEntry: historyEntries.next() }, '', path)
         }
     }
     runtimePath.value = path

package/src/lib/ui/persist.ts

@@ -1,3 +1,4 @@
+import { escapeKey } from './runtime/escapeKey.ts'
 import { localStoragePersistence } from './runtime/localStoragePersistence.ts'
 import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
 import type { Doc } from './runtime/types/Doc.ts'
@@ -99,8 +100,10 @@ export function persist(
 function restore(doc: Doc, saved: unknown): void {
     const current = doc.snapshot()
     if (isPlainObject(saved) && isPlainObject(current)) {
+        /* `replace` takes a `/`-delimited escaped path, so a top-level key containing
+           `/` or `~` must be escaped to a single segment or it'd be mis-routed. */
         for (const key of Object.keys(saved)) {
-            doc.replace(key, saved[key])
+            doc.replace(escapeKey(key), saved[key])
         }
         return
     }