@abide/abide 0.36.0 → 0.38.0

package/src/lib/ui/router.ts

@@ -6,7 +6,9 @@ import { clientPage } from './runtime/clientPage.ts'
 import { enterRenderPass } from './runtime/enterRenderPass.ts'
 import { exitRenderPass } from './runtime/exitRenderPass.ts'
 import { firstOutlet } from './runtime/firstOutlet.ts'
+import { historyEntries } from './runtime/historyEntries.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
+import type { AbideHistoryState } from './runtime/types/AbideHistoryState.ts'
 import type { NavVerdict } from './runtime/types/NavVerdict.ts'
 import type { Route } from './runtime/types/Route.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
@@ -20,6 +22,15 @@ type MountedLayout = { key: string; dispose: () => void; outlet: Element }
 /* A layout mount that returns no disposer still needs one for the chain teardown. */
 const noop = (): void => {}
 
+/* The destination URL for a navigation `path`. On the server / headless there is no
+   `location`, so resolve against a localhost origin; in the browser, against the real
+   origin — `location` is already updated to `path` by the time a swap reads it, so this
+   matches `new URL(location.href)`. */
+const resolveUrl = (path: string): URL =>
+    typeof location === 'undefined'
+        ? new URL(`http://localhost${path}`)
+        : new URL(path, location.origin)
+
 /*
 A minimal client router on the History API. `router` matches the current path
 against the route patterns (literal / `[name]` / `[...rest]`, via matchRoute),
@@ -34,6 +45,11 @@ is disposed and rebuilt, and the page (always the leaf) re-mounts every time. Th
 reactive `page` proxy means a persisted layout reading route/params updates in place
 without a remount. Each chunk loads only on first visit, cached after.
 
+Scroll restoration is manual (`historyEntries`): because the page is rebuilt after the
+browser would restore scroll, each history entry's offset is bucketed by an `abideEntry`
+id and reapplied once the destination DOM exists — back/forward returns to its offset, a
+fresh navigation scrolls to the top.
+
 `probe` (when given) runs each post-boot navigation's destination through the
 server's app.handle first, so auth/redirect gating applies to client navigation
 just as it does to a fresh load; its verdict either clears the mount, soft-redirects
@@ -134,9 +150,22 @@ export function router(
         run()
     }
 
+    const entryOf = (): number =>
+        (history.state as AbideHistoryState | null)?.abideEntry ?? historyEntries.current
     const onPopState = (): void => {
+        /* Bucket the leaving entry's scroll (current still its id) before adopting the
+           one back/forward landed on; `swap` restores the adopted entry's offset once
+           its DOM is rebuilt. */
+        historyEntries.save()
+        historyEntries.adopt(entryOf())
         runtimePath.value = location.pathname + location.search + location.hash
     }
+    const onPageHide = (): void => {
+        /* Mirror the live scroll into the active entry's state before it unloads, so a
+           reload can recover it — the in-memory bucket is gone and `manual` keeps the
+           browser from restoring. */
+        historyEntries.persist()
+    }
     const onClick = (event: MouseEvent): void => {
         /* Let the browser own anything that isn't a plain primary-button click:
            modified clicks (open in a new tab/window), middle/right buttons, and
@@ -175,7 +204,22 @@ export function router(
         navigate(destination.pathname + destination.search + destination.hash)
     }
     if (typeof window !== 'undefined') {
+        /* Own scroll restoration: the browser would restore against the pre-teardown
+           DOM. Adopt the initial entry's id (survives a reload) and stamp it onto the
+           landing entry — merging so any `scroll` a prior unload persisted into this
+           entry's state stays put for the first-paint `restore` to recover. */
+        if ('scrollRestoration' in history) {
+            history.scrollRestoration = 'manual'
+        }
+        historyEntries.adopt(entryOf())
+        const landingState = (history.state as AbideHistoryState | null) ?? {}
+        history.replaceState(
+            { ...landingState, abideEntry: historyEntries.current },
+            '',
+            location.href,
+        )
         window.addEventListener('popstate', onPopState)
+        window.addEventListener('pagehide', onPageHide)
         document.addEventListener('click', onClick as EventListener)
     }
 
@@ -200,6 +244,29 @@ export function router(
             /* The route matches on the pathname only; the query/hash ride along for
                the probe (so server gating sees them) and for clientPage.url. */
             const pathname = path.split(/[?#]/)[0] ?? path
+            /* A same-document navigation — only the `#hash` (and thus scroll) differs from
+               the mounted page — needs no teardown: the live page stays, page.url
+               republishes (so `page.url.hash` updates in place), and we restore the entry's
+               scroll bucket or scroll to the anchor. A differing pathname or query still
+               rebuilds (a query is page data). Skipped on first paint — nothing is mounted. */
+            const targetUrl = resolveUrl(path)
+            const mountedUrl = clientPage.value.url
+            if (
+                !first &&
+                mountedUrl.pathname === targetUrl.pathname &&
+                mountedUrl.search === targetUrl.search &&
+                mountedUrl.hash !== targetUrl.hash
+            ) {
+                /* Invalidate any in-flight full navigation so its late `.then` can't
+                   rebuild over the page this hash hop keeps mounted (the token guard
+                   only bails on a NEWER sequence). That bailed `.then` is also the only
+                   writer of `navigating: false`, so clear the flag here — a hash hop is
+                   synchronous and settles immediately. */
+                sequence += 1
+                clientPage.value = { ...clientPage.value, url: targetUrl, navigating: false }
+                historyEntries.restore(targetUrl.hash)
+                return
+            }
             const matched = matchRoute(patterns, pathname)
             const key = matched?.route ?? '*'
             const params = matched?.params ?? {}
@@ -275,19 +342,19 @@ export function router(
                        while it's still mounted. Disposing first kills that scope; surviving
                        prefix layouts then update in place on publish. */
                     const base = disposeFrom(divergence)
-                    clientPage.value = {
-                        route: chainRoute,
-                        params,
-                        url:
-                            typeof location === 'undefined'
-                                ? new URL(`http://localhost${path}`)
-                                : new URL(location.href),
-                        navigating: false,
-                    }
+                    const url = resolveUrl(path)
+                    clientPage.value = { route: chainRoute, params, url, navigating: false }
                     if (!hydrating) {
                         base.textContent = ''
                     }
                     buildFrom(base, divergence, chainKeys, layoutViews, pageView, params, hydrating)
+                    /* Reapply the destination entry's scroll once its DOM exists — a
+                       back/forward restores its offset, a fresh nav scrolls to the `#hash`
+                       anchor (now built) or the top. Runs on the initial paint too: with
+                       `scrollRestoration='manual'` the browser does NOT restore a reload's
+                       offset, so first paint recovers it from the persisted `history.state`
+                       (a fresh load with no persisted offset falls through to hash/top). */
+                    historyEntries.restore(url.hash)
                 }
                 /* Wrap the swap in a View Transition where the browser supports it, so
                    the page change cross-fades (and shared `view-transition-name` elements
@@ -311,6 +378,7 @@ export function router(
         disposed = true
         if (typeof window !== 'undefined') {
             window.removeEventListener('popstate', onPopState)
+            window.removeEventListener('pagehide', onPageHide)
             document.removeEventListener('click', onClick as EventListener)
         }
         stop()

package/src/lib/ui/runtime/createDoc.ts

@@ -14,6 +14,13 @@ import { unescapeKey } from './unescapeKey.ts'
 import { walkPath } from './walkPath.ts'
 import { writeNode } from './writeNode.ts'
 
+/* `path` minus its last segment — the parent container's path, '' at the root.
+   The same string `segments.slice(0, -1).join('/')` rebuilds, by one slice. */
+function parentPathOf(path: string): string {
+    const lastSlash = path.lastIndexOf('/')
+    return lastSlash === -1 ? '' : path.slice(0, lastSlash)
+}
+
 /*
 Builds a reactive document over `initial`. Each path read for the first time
 mints a signal node; the node is the notification token, the (mutable) tree is
@@ -132,10 +139,7 @@ export function createDoc(initial: unknown): Doc {
            remove (computed post-apply, below, to resolve an array append's index). */
         const before = PATCH_BUS.active ? walkPath(tree, patch.path) : undefined
         tree = applyPatchToTree(tree, patch, segments)
-        /* parentPath is patch.path minus its last segment — the same string
-           `segments.slice(0, -1).join('/')` rebuilds, taken by one slice instead. */
-        const lastSlash = patch.path.lastIndexOf('/')
-        const parentPath = lastSlash === -1 ? '' : patch.path.slice(0, lastSlash)
+        const parentPath = parentPathOf(patch.path)
         const parentValue = walkPath(tree, parentPath).value
         const leafKey = segments[segments.length - 1] as string | undefined
         /* A structural change (add/remove, or an array element replaced by index)
@@ -194,8 +198,7 @@ export function createDoc(initial: unknown): Doc {
         before: ReturnType<typeof walkPath> | undefined,
     ): Patch | undefined {
         if (patch.op === 'add') {
-            const lastSlash = patch.path.lastIndexOf('/')
-            const parentPath = lastSlash === -1 ? '' : patch.path.slice(0, lastSlash)
+            const parentPath = parentPathOf(patch.path)
             const parent = walkPath(tree, parentPath).value
             const resolved =
                 Array.isArray(parent) && patch.path.endsWith('/-')
@@ -223,9 +226,19 @@ export function createDoc(initial: unknown): Doc {
         const node = nodeFor(path)
         const segments = path.split('/').map(unescapeKey)
         const leafKey = segments[segments.length - 1] as string
+        /* Auto-vivify missing ancestor objects so binding a nested path on a doc
+           booted shallow (e.g. `state({})`) doesn't crash, and a later `set` writes
+           into the LIVE tree (so snapshot/persist see it). Mirrors the container
+           assumption applyPatchToTree makes — except the patch path is authored, this
+           walk is compiler-emitted, so the intermediates may not exist yet. */
         let parent = tree as Record<string, unknown>
         for (const segment of segments.slice(0, -1)) {
-            parent = parent[segment] as Record<string, unknown>
+            let next = parent[segment]
+            if (next === null || typeof next !== 'object') {
+                next = {}
+                parent[segment] = next
+            }
+            parent = next as Record<string, unknown>
         }
         return {
             get: () => readNode(node) as T,

package/src/lib/ui/runtime/historyEntries.ts

@@ -0,0 +1,113 @@
+import type { AbideHistoryState } from './types/AbideHistoryState.ts'
+
+/*
+Per-history-entry scroll buckets for manual scroll restoration. The browser's own
+restoration is disabled (`history.scrollRestoration = 'manual'` at router boot)
+because the router tears the page down and rebuilds it AFTER the browser would have
+restored scroll — so the offset is lost against a node that no longer exists. Instead
+each history entry carries a monotonic id (stamped into `history.state.abideEntry` by
+`navigate`), and this module buckets that entry's scroll offset: `save()` records the
+outgoing offset before history moves, `restore()` reapplies the destination entry's
+offset after its DOM is rebuilt (or, for an entry seen for the first time — a fresh
+navigation — honours a `#hash` anchor when one resolves, else scrolls to the top). A
+back/forward `adopt`s the entry id read from history.state; a `replace` `discard`s the
+current bucket (its content is superseded). The in-memory `offsets` Map covers the
+same-session back/forward path; `persist()` also mirrors the live scroll into
+`history.state` (on pagehide, when state still reflects the active entry) so a RELOAD
+— where the Map is gone and `scrollRestoration='manual'` keeps the browser from
+restoring — can still recover it via `restore()`'s `persistedOffset` fallback.
+
+Scroll APIs are reached off `globalThis` (guarded) so the module is a no-op on the
+server and in headless tests that never install a window. Shared mutable singleton on
+one object, reached without a barrel — mirrors `reactiveAbortState`/`clientPage`.
+*/
+
+/* The scroll surface: the real `Window` shape, made `Partial` so every member is
+   optional — the module degrades to a no-op on the server / in headless tests that
+   never install a window. */
+const view = globalThis as unknown as Partial<Window>
+
+/* The active entry's offset persisted in `history.state` — survives a reload (the
+   in-memory `offsets` Map does not). Honoured only when the stored id matches `current`,
+   so a foreign history entry's state never restores the wrong scroll. */
+function persistedOffset(): [number, number] | undefined {
+    const state = view.history?.state as AbideHistoryState | null
+    if (state?.abideEntry === current && Array.isArray(state.scroll)) {
+        return state.scroll
+    }
+    return undefined
+}
+
+/* The element a `#hash` addresses, if the document holds one. */
+function anchorFor(hash: string | undefined): HTMLElement | undefined {
+    if (hash === undefined || hash.length <= 1 || view.document === undefined) {
+        return undefined
+    }
+    return view.document.getElementById(hash.slice(1)) ?? undefined
+}
+
+/* The active entry's scroll offset is buckets.get(current); `seq` mints fresh ids. */
+const offsets = new Map<number, [number, number]>()
+let current = 0
+let seq = 0
+
+export const historyEntries = {
+    /* The active history entry's id — stamped into history.state by `navigate`. */
+    get current(): number {
+        return current
+    },
+    /* Mint the next entry id for a pushed history entry, making it active. */
+    next(): number {
+        current = seq += 1
+        return current
+    },
+    /* A back/forward landed on an existing entry — make it active so the following
+       save/restore target its bucket. Keeps `seq` ahead of any adopted id. */
+    adopt(entry: number): void {
+        current = entry
+        if (entry > seq) {
+            seq = entry
+        }
+    },
+    /* Bucket the active entry's current scroll offset, before history moves away. */
+    save(): void {
+        if (typeof view.scrollTo === 'function') {
+            offsets.set(current, [view.scrollX ?? 0, view.scrollY ?? 0])
+        }
+    },
+    /* Drop the active entry's bucket — a replace lands fresh content, so the saved
+       scroll no longer applies. (The replace's own `replaceState` overwrites the
+       persisted copy in `history.state`, so the durable fallback clears too.) */
+    discard(): void {
+        offsets.delete(current)
+    },
+    /* Mirror the live scroll into the active entry's `history.state` so it survives a
+       reload (the in-memory Map does not). Called on pagehide — when `history.state`
+       still reflects the active entry — merging to keep its `abideEntry` stamp. */
+    persist(): void {
+        if (typeof view.scrollTo !== 'function' || view.history === undefined) {
+            return
+        }
+        const state = (view.history.state as AbideHistoryState | null) ?? {}
+        view.history.replaceState({ ...state, scroll: [view.scrollX ?? 0, view.scrollY ?? 0] }, '')
+    },
+    /* Reapply the active entry's scroll once its DOM exists. A back/forward to a saved
+       entry returns to its offset (in-memory, else the reload-durable persisted copy);
+       a fresh entry honours a `#hash` anchor when one resolves, else scrolls to the top. */
+    restore(hash?: string): void {
+        if (typeof view.scrollTo !== 'function') {
+            return
+        }
+        const offset = offsets.get(current) ?? persistedOffset()
+        if (offset !== undefined) {
+            view.scrollTo(offset[0], offset[1])
+            return
+        }
+        const anchor = anchorFor(hash)
+        if (anchor !== undefined) {
+            anchor.scrollIntoView()
+            return
+        }
+        view.scrollTo(0, 0)
+    },
+}

package/src/lib/ui/runtime/liveScopes.ts

@@ -0,0 +1,15 @@
+import type { Scope } from '../types/Scope.ts'
+
+/*
+Dev-only registry of every live scope, for the inspector's Reactive tab. `scopes`
+stays empty and untouched unless installInspectorBridge flips `enabled` (gated by
+the server-injected `__abideInspect`), so production allocates and tracks nothing.
+createScope adds on construction and removes on dispose; the bridge reconstructs
+the scope forest from each entry's `id` + `parent.id` (the Scope surface exposes
+no children accessor, so the flat set + parent links is the traversal path). One
+mutable singleton object — mirrors `reactiveAbortState`, reached without a barrel.
+*/
+export const liveScopes: { enabled: boolean; scopes: Set<Scope> } = {
+    enabled: false,
+    scopes: new Set(),
+}

package/src/lib/ui/runtime/types/AbideHistoryState.ts

@@ -0,0 +1,9 @@
+/* The shape abide stamps into `History.state`: a monotonic `abideEntry` id the router
+   buckets scroll by, and the last `scroll` offset persisted for that entry (so a reload
+   can recover it — the in-memory bucket does not survive). Both optional: a foreign or
+   bare entry (one another script pushed, or the first landing before a stamp) carries
+   neither, which the readers treat as "no abide data". */
+export type AbideHistoryState = {
+    abideEntry?: number
+    scroll?: [number, number]
+}

package/src/lib/ui/seedStreamedResolution.ts

@@ -18,5 +18,14 @@ export function seedStreamedResolution(resolution: StreamedResolution): void {
     if ('miss' in resolution) {
         return
     }
-    activeCacheStore().entries.set(resolution.key, cacheEntryFromSnapshot(resolution))
+    /* Only seed when nothing live holds the key — or when the existing entry is itself
+       an unconsumed hydrated seed (`hydrated === true`, cleared by the first cache()
+       read). A live/settled non-hydrated entry is authoritative; clobbering it with a
+       stale snapshot would drop a fresher value (e.g. one a live fetch already wrote). */
+    const { entries } = activeCacheStore()
+    const existing = entries.get(resolution.key)
+    if (existing !== undefined && existing.hydrated !== true) {
+        return
+    }
+    entries.set(resolution.key, cacheEntryFromSnapshot(resolution))
 }

package/src/lib/ui/startClient.ts

@@ -6,6 +6,7 @@ import { setPageResolver } from '../shared/setPageResolver.ts'
 import type { CacheSnapshotEntry } from '../shared/types/CacheSnapshotEntry.ts'
 import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
 import { installHotBridge } from './installHotBridge.ts'
+import { installInspectorBridge } from './installInspectorBridge.ts'
 import { probeNavigation } from './probeNavigation.ts'
 import { router } from './router.ts'
 import { clientPage } from './runtime/clientPage.ts'
@@ -42,6 +43,11 @@ export function startClient(
     if ((globalThis as { __abideDev?: boolean }).__abideDev) {
         installHotBridge()
     }
+    /* Inspector only: the server injects `__abideInspect` when ABIDE_ENABLE_INSPECTOR
+       is on, so the scope/router bridge arms before the router builds any scope. */
+    if ((globalThis as { __abideInspect?: boolean }).__abideInspect) {
+        installInspectorBridge()
+    }
     const ssr = (globalThis as { __SSR__?: SsrPayload }).__SSR__ ?? {}
     setBaseResolver(() => ssr.base ?? '')
     /* The `page` proxy reads route/params/url off the router-updated snapshot. */

package/src/lib/ui/types/Scope.ts

@@ -22,6 +22,9 @@ the ONLY public entry; everything else is a method reached through it (the
 */
 export type Scope = {
     readonly id: string
+    /* Dev-only display name (the host component/element it mounted into) for the
+       inspector's Reactive tab; undefined for SSR/detached/child scopes. */
+    readonly label?: string
     readonly parent: Scope | undefined
     /* data — mirrors Doc */
     read: <T>(path: string) => T

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

@@ -1,132 +0,0 @@
-/*
-Every standard HTML element name (lowercase), plus the two foreign-content roots
-`svg`/`math`. A component wrapper tag that collides with one of these is a real
-element with a content model and parser quirks — `<button>`/`<a>` reject interactive
-descendants, table/list/select families foster or auto-close non-conforming children,
-void elements self-close, and `<svg>`/`<math>` switch the parser into SVG/MathML
-namespace so the wrapper's HTML children break out (foster-parent) of it entirely —
-so the parser reparents the component's own markup out of the wrapper and hydration
-claims `null`. `componentWrapperTag` remaps any such name to a transparent custom
-element instead. Pure SVG/MathML descendant names (`circle`, `path`, `mrow`, …) are
-NOT here: in HTML context they are inert unknown elements that hold children fine, so
-a `<Circle>` component stays as-is like any non-element name. Superset of VOID_TAGS
-(which the parser/SSR still use for self-closing); this set is only the
-wrapper-safety check.
-*/
-export const HTML_TAGS: ReadonlySet<string> = new Set([
-    'a',
-    'abbr',
-    'address',
-    'area',
-    'article',
-    'aside',
-    'audio',
-    'b',
-    'base',
-    'bdi',
-    'bdo',
-    'blockquote',
-    'body',
-    'br',
-    'button',
-    'canvas',
-    'caption',
-    'cite',
-    'code',
-    'col',
-    'colgroup',
-    'data',
-    'datalist',
-    'dd',
-    'del',
-    'details',
-    'dfn',
-    'dialog',
-    'div',
-    'dl',
-    'dt',
-    'em',
-    'embed',
-    'fieldset',
-    'figcaption',
-    'figure',
-    'footer',
-    'form',
-    'h1',
-    'h2',
-    'h3',
-    'h4',
-    'h5',
-    'h6',
-    'head',
-    'header',
-    'hgroup',
-    'hr',
-    'html',
-    'i',
-    'iframe',
-    'img',
-    'input',
-    'ins',
-    'kbd',
-    'label',
-    'legend',
-    'li',
-    'link',
-    'main',
-    'map',
-    'mark',
-    'math',
-    'menu',
-    'meta',
-    'meter',
-    'nav',
-    'noscript',
-    'object',
-    'ol',
-    'optgroup',
-    'option',
-    'output',
-    'p',
-    'param',
-    'picture',
-    'pre',
-    'progress',
-    'q',
-    'rp',
-    'rt',
-    'ruby',
-    's',
-    'samp',
-    'script',
-    'search',
-    'section',
-    'select',
-    'slot',
-    'small',
-    'source',
-    'span',
-    'strong',
-    'style',
-    'sub',
-    'summary',
-    'sup',
-    'svg',
-    'table',
-    'tbody',
-    'td',
-    'template',
-    'textarea',
-    'tfoot',
-    'th',
-    'thead',
-    'time',
-    'title',
-    'tr',
-    'track',
-    'u',
-    'ul',
-    'var',
-    'video',
-    'wbr',
-])