@abide/abide 0.28.0

package/src/lib/ui/installHotBridge.ts

@@ -0,0 +1,73 @@
+import { html } from '../shared/html.ts'
+import { snippet } from '../shared/snippet.ts'
+import { derived } from './derived.ts'
+import { doc } from './doc.ts'
+import { appendSnippet } from './dom/appendSnippet.ts'
+import { appendStatic } from './dom/appendStatic.ts'
+import { appendText } from './dom/appendText.ts'
+import { attach } from './dom/attach.ts'
+import { attr } from './dom/attr.ts'
+import { awaitBlock } from './dom/awaitBlock.ts'
+import { cloneStatic } from './dom/cloneStatic.ts'
+import { each } from './dom/each.ts'
+import { eachAsync } from './dom/eachAsync.ts'
+import { hydrate } from './dom/hydrate.ts'
+import { mount } from './dom/mount.ts'
+import { mountChild } from './dom/mountChild.ts'
+import { on } from './dom/on.ts'
+import { openChild } from './dom/openChild.ts'
+import { openRoot } from './dom/openRoot.ts'
+import { switchBlock } from './dom/switchBlock.ts'
+import { tryBlock } from './dom/tryBlock.ts'
+import { when } from './dom/when.ts'
+import { effect } from './effect.ts'
+import { enterRenderPass } from './runtime/enterRenderPass.ts'
+import { exitRenderPass } from './runtime/exitRenderPass.ts'
+import { hotReloadEnabled } from './runtime/hotReloadEnabled.ts'
+import { hotReplace } from './runtime/hotReplace.ts'
+import { nextBlockId } from './runtime/nextBlockId.ts'
+import { state } from './state.ts'
+
+/*
+Dev-only: exposes the abide-ui runtime plus `hotReplace` on `window.__abide`, and
+flips on `hotReloadEnabled` so `mountChild` records every instance it mounts. A
+hot module (the dev server's standalone recompile of one edited `.abide`) reads
+its runtime from this object instead of importing fresh copies — so it shares the
+one reactive graph and instance registry — then calls `hotReplace` to swap every
+live instance in place. The keys mirror `UI_RUNTIME_IMPORTS` (+ `hotReplace`); a
+test guards that pairing. `startClient` calls this when the server marks the page
+dev (the live-reload script sets `window.__abideDev`).
+*/
+export function installHotBridge(): void {
+    ;(globalThis as { __abide?: Record<string, unknown> }).__abide = {
+        html,
+        snippet,
+        doc,
+        state,
+        derived,
+        effect,
+        mount,
+        openChild,
+        openRoot,
+        appendText,
+        appendSnippet,
+        appendStatic,
+        cloneStatic,
+        attr,
+        on,
+        attach,
+        each,
+        eachAsync,
+        when,
+        awaitBlock,
+        tryBlock,
+        switchBlock,
+        mountChild,
+        hydrate,
+        nextBlockId,
+        enterRenderPass,
+        exitRenderPass,
+        hotReplace,
+    }
+    hotReloadEnabled.current = true
+}

package/src/lib/ui/matchRoute.ts

@@ -0,0 +1,89 @@
+import type { RouteSegment } from '../shared/parseRouteSegments.ts'
+import { parseRouteSegments } from '../shared/parseRouteSegments.ts'
+
+/*
+Per-route parse cache. The route set is stable across a session, so parsing a
+pattern into segments (and counting its literals, the specificity tie-breaker) is
+done once per route rather than twice per route on every navigation. Keyed by the
+pattern string; entries never need eviction since routes don't churn.
+*/
+const PARSED_ROUTES = new Map<string, { segments: RouteSegment[]; literals: number }>()
+
+function parsedRoute(route: string): { segments: RouteSegment[]; literals: number } {
+    let parsed = PARSED_ROUTES.get(route)
+    if (parsed === undefined) {
+        const segments = parseRouteSegments(route)
+        const literals = segments.filter((segment) => segment.kind === 'literal').length
+        parsed = { segments, literals }
+        PARSED_ROUTES.set(route, parsed)
+    }
+    return parsed
+}
+
+/*
+Client route matcher: given the registered route patterns and the current
+pathname, returns the matching route + decoded params, or undefined. Mirrors the
+server's segment grammar via the shared `parseRouteSegments` (literal / `[name]` /
+`[...rest]`), so client navigation decodes params the same way SSR does. The most
+specific match wins — the pattern with the most literal segments — so a static
+route beats a param route at the same depth.
+*/
+export function matchRoute(
+    routes: string[],
+    pathname: string,
+): { route: string; params: Record<string, string> } | undefined {
+    /* Normalize a trailing slash (except root) so `/users/` matches `/users` —
+       otherwise the extra empty segment makes the length guard reject it (a 404 the
+       server's own routing wouldn't give) or lets `/users/[id]` capture an empty id. */
+    const normalized =
+        pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname
+    const pathSegments = normalized.split('/')
+    let best: { route: string; params: Record<string, string>; literals: number } | undefined
+    for (const route of routes) {
+        const parsed = parsedRoute(route)
+        const params = matchSegments(parsed.segments, pathSegments)
+        if (params === undefined) {
+            continue
+        }
+        if (best === undefined || parsed.literals > best.literals) {
+            best = { route, params, literals: parsed.literals }
+        }
+    }
+    return best === undefined ? undefined : { route: best.route, params: best.params }
+}
+
+/* Matches one parsed pattern against the path's segments, capturing params;
+   undefined on mismatch. A catch-all consumes every remaining segment. */
+function matchSegments(
+    segments: RouteSegment[],
+    pathSegments: string[],
+): Record<string, string> | undefined {
+    const params: Record<string, string> = {}
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index]
+        if (segment === undefined) {
+            return undefined
+        }
+        if (segment.kind === 'param' && segment.catchAll) {
+            params[segment.name] = pathSegments.slice(index).join('/')
+            return params
+        }
+        const value = pathSegments[index]
+        if (value === undefined) {
+            return undefined
+        }
+        if (segment.kind === 'literal') {
+            if (segment.value !== value) {
+                return undefined
+            }
+        } else {
+            /* A `[name]` param never captures an empty segment (e.g. `/users//5`). */
+            if (value === '') {
+                return undefined
+            }
+            params[segment.name] = value
+        }
+    }
+    /* No catch-all consumed the tail, so the path must have no extra segments. */
+    return pathSegments.length === segments.length ? params : undefined
+}

package/src/lib/ui/navigate.ts

@@ -0,0 +1,17 @@
+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. */
+// @readme plumbing
+export function navigate(path: string, replace = false): void {
+    if (typeof history !== 'undefined') {
+        if (replace) {
+            history.replaceState({}, '', path)
+        } else {
+            history.pushState({}, '', path)
+        }
+    }
+    runtimePath.value = path
+}

package/src/lib/ui/probeNavigation.ts

@@ -0,0 +1,33 @@
+import { NAV_HEADER } from '../shared/NAV_HEADER.ts'
+import type { NavVerdict } from './runtime/types/NavVerdict.ts'
+
+/*
+The client router's SPA navigation probe: runs `path` through the server's
+app.handle without a render. It's a fetch stamped with NAV_HEADER, which the page
+dispatcher answers 204 once handle() has cleared it — so the round trip pays for
+handle()'s auth/redirect gating, not a server render. fetch follows handle()'s
+redirects server-side, so a redirected response's `url` is the final cleared
+location: same-origin yields a soft client redirect (the router re-probes there),
+cross-origin a full browser load. A non-OK status (handle() blocked it) or a thrown
+fetch (offline) also hands off to the browser, so the server's real response —
+a login page, an error page — is what renders.
+*/
+// @readme plumbing
+export async function probeNavigation(path: string): Promise<NavVerdict> {
+    let response: Response
+    try {
+        response = await fetch(path, { headers: { [NAV_HEADER]: '1' } })
+    } catch {
+        return { kind: 'reload', url: path }
+    }
+    if (response.redirected) {
+        const target = new URL(response.url)
+        return target.origin === location.origin
+            ? { kind: 'redirect', path: target.pathname + target.search }
+            : { kind: 'reload', url: response.url }
+    }
+    if (!response.ok) {
+        return { kind: 'reload', url: path }
+    }
+    return { kind: 'mount' }
+}

package/src/lib/ui/remoteProxy.ts

@@ -0,0 +1,97 @@
+import { browserClientFlags } from '../shared/browserClientFlags.ts'
+import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { createRemoteFunction } from '../shared/createRemoteFunction.ts'
+import { HttpError } from '../shared/HttpError.ts'
+import { OFFLINE_HEADER } from '../shared/OFFLINE_HEADER.ts'
+import { rpcTimeoutSlot } from '../shared/rpcTimeoutSlot.ts'
+import { trace } from '../shared/trace.ts'
+import type { HttpVerb } from '../shared/types/HttpVerb.ts'
+import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+import { withBase } from '../shared/withBase.ts'
+
+/*
+Client-side substitute for a verb-defined handler. The bundler emits one
+call per verb export inside an `$rpc/**` module (GET / POST / …): server
+target uses defineVerb (real handler), browser target uses remoteProxy
+(fetch over the network). Both paths produce identical RemoteFunction
+shapes and identical WeakMap metadata so cache() works the same on either
+side.
+
+`url` is the flat rpc route. Args go in the JSON body (POST/PUT/PATCH) or
+the query string (GET/DELETE/HEAD). Plain `fn(args)` decodes the Response
+by Content-Type and throws HttpError on non-2xx; `.raw(args)` is the
+escape hatch that returns the Response untouched.
+*/
+// @readme plumbing
+export function remoteProxy<Args, Return>(
+    method: HttpVerb,
+    url: string,
+): RemoteFunction<Args, Return> {
+    return createRemoteFunction<Args, Return>({
+        method,
+        url,
+        clients: browserClientFlags,
+        /*
+        The Request URL carries the mount base so the fetch routes through the
+        proxy (/v2/rpc/…); the cache key keeps the bare `url` (keyForRemoteCall
+        reads fn.url), so SSR snapshots round-trip base-independently.
+        */
+        buildRequest: (args) =>
+            buildRpcRequest({
+                method,
+                url: withBase(url),
+                args,
+                baseUrl: window.location.href,
+                headers: rpcHeaders(),
+            }),
+        /*
+        Forcing `getRequest()` once builds the Request and seeds the
+        cache meta thunk in createRemoteFunction with the same instance,
+        so cache() readers don't reconstruct it.
+        */
+        invoke: (_args, getRequest) => fetchWithTimeout(getRequest()),
+    })
+}
+
+/*
+Applies the env-configured client timeout (ABIDE_CLIENT_TIMEOUT, ms) when one
+is set; an unset slot fetches unbounded, exactly as before. A timeout abort
+surfaces as a 504 HttpError so a consumer reads an honest status instead of a
+raw DOMException → 500. Other rejections (genuine network failure) propagate untouched.
+*/
+function fetchWithTimeout(request: Request): Promise<Response> {
+    const timeout = rpcTimeoutSlot.ms
+    if (timeout === undefined) {
+        return fetch(request)
+    }
+    return fetch(request, { signal: AbortSignal.timeout(timeout) }).catch((error: unknown) => {
+        if (error instanceof DOMException && error.name === 'TimeoutError') {
+            throw new HttpError(
+                new Response('client timeout', { status: 504, statusText: 'Gateway Timeout' }),
+            )
+        }
+        throw error
+    })
+}
+
+/*
+abide's per-RPC headers: the page traceparent (continues the server trace) and,
+only while offline, the offline marker so the handler's online() reflects the
+caller's connectivity. Returns undefined when neither applies so the
+allocation-free fetch path stays the common case.
+*/
+function rpcHeaders(): Headers | undefined {
+    const headers = new Headers()
+    let any = false
+    const traceparent = trace()
+    if (traceparent) {
+        headers.set('traceparent', traceparent)
+        any = true
+    }
+    /* Presence = offline; absence = online/unknown. navigator.onLine's offline signal is the reliable direction. */
+    if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+        headers.set(OFFLINE_HEADER, '1')
+        any = true
+    }
+    return any ? headers : undefined
+}

package/src/lib/ui/renderChain.ts

@@ -0,0 +1,50 @@
+import { enterRenderPass } from './runtime/enterRenderPass.ts'
+import { exitRenderPass } from './runtime/exitRenderPass.ts'
+import { OUTLET_TAG } from './runtime/OUTLET_TAG.ts'
+import type { SsrRender } from './runtime/types/SsrRender.ts'
+import type { UiComponent } from './runtime/types/UiComponent.ts'
+
+const OUTLET_OPEN = `<${OUTLET_TAG}>`
+const OUTLET_CLOSE = `</${OUTLET_TAG}>`
+const OUTLET_PLACEHOLDER = `${OUTLET_OPEN}${OUTLET_CLOSE}`
+
+/*
+Server-renders a route's layout chain wrapped around its page into one SsrRender.
+`views` is ordered outermost layout → … → page. The whole chain renders under a
+SINGLE render pass: one outer `enterRenderPass` resets the block-id counter, then
+each `render()` runs nested (depth > 0, no reset), so every `await`/`try` block
+across all layers draws a unique id from the shared counter — in the same
+layer-sequential order the client hydrates them, keeping the streamed fragments and
+the resume manifest aligned.
+
+The html nests inner-to-outer: each parent's empty `<abide-outlet>` is filled with
+the accumulated child html — the outlet ELEMENT is kept (it stays the live mount
+container the client router fills/hydrates the child into, found by tag), so the
+SSR DOM and the client-nested DOM match exactly. Awaits concatenate (already
+uniquely numbered); state merges. A single component renders unchanged — its own
+render with no wrapping. A layout missing its `<slot/>` is a build error surfaced here.
+*/
+export function renderChain(views: UiComponent[], params: Record<string, string>): SsrRender {
+    enterRenderPass()
+    try {
+        const renders = views.map((view) => view.render(params))
+        let html = renders[renders.length - 1]?.html ?? ''
+        for (let index = renders.length - 2; index >= 0; index -= 1) {
+            const parent = renders[index] as SsrRender
+            if (!parent.html.includes(OUTLET_PLACEHOLDER)) {
+                throw new Error('[abide] a layout.abide must contain exactly one <slot/> outlet')
+            }
+            /* Fill the outlet element (keep it), function replacement so `$&`/`$\`` in
+               the child html insert literally. */
+            const child = html
+            html = parent.html.replace(OUTLET_PLACEHOLDER, () => OUTLET_OPEN + child + OUTLET_CLOSE)
+        }
+        return {
+            html,
+            awaits: renders.flatMap((render) => render.awaits),
+            state: Object.assign({}, ...renders.map((render) => render.state)),
+        }
+    } finally {
+        exitRenderPass()
+    }
+}

package/src/lib/ui/renderToStream.ts

@@ -0,0 +1,104 @@
+import type { ResumeEntry } from './runtime/RESUME.ts'
+import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
+
+/*
+Out-of-order SSR streaming. Yields the pending shell first (so the browser paints
+immediately), then one resolved fragment per await block as its promise settles —
+in completion order, not source order, so a slow read never blocks a fast one.
+Each resolved fragment is a `<abide-resolve data-id="ID" data-resume="…">…</abide-resolve>`
+that `applyResolved` swaps into the matching `<!--abide:await:ID-->` boundary; the
+`data-resume` payload is the JSON-serialized value, registered for hydration so an
+`await` block adopts the resolved branch on resume instead of re-running.
+
+This is the await-block-streams half of the cache rule: a top-level `await` in the
+script would have blocked the shell (inlined), but an await *block* flushes its
+shell now and streams the value when ready. Driven by a plain `render()` result,
+so it composes with any transport (HTTP chunked, a socket frame, a test).
+
+A `then` on the `await` tag makes the block BLOCKING: it settles before the first
+flush, its resolved branch spliced into its (empty) boundary and its value seeded
+into the resume manifest inline — so the value is in the first paint, no pending
+shell, no swap. The first yield therefore awaits all blocking blocks; only the
+remaining streaming blocks flush out of order after it.
+*/
+// @readme plumbing
+export async function* renderToStream(render: () => SsrRender): AsyncGenerator<string> {
+    const { html, awaits } = render()
+    /* Blocking awaits (a `then` on the `await` tag) settle BEFORE the first flush:
+       their resolved branch is spliced into its empty boundary and its value registered
+       inline, so the first paint already has the value — no pending, no swap. */
+    const blocking = awaits.filter((block) => block.blocking === true)
+    let shell = html
+    const resumed: Record<number, ResumeEntry> = {}
+    for (const settled of await Promise.all(blocking.map(settle))) {
+        shell = spliceResolved(shell, settled.id, settled.html)
+        resumed[settled.id] = settled.resume
+    }
+    yield shell + resumeScript(resumed)
+    /* Streaming awaits flush their resolved fragment out of order as each settles. */
+    const inflight = new Map<number, Promise<Settled>>()
+    for (const block of awaits) {
+        if (block.blocking !== true) {
+            inflight.set(block.id, settle(block))
+        }
+    }
+    while (inflight.size > 0) {
+        const resolved = await Promise.race(inflight.values())
+        inflight.delete(resolved.id)
+        const resume = encodeResume(resolved.resume)
+        yield `<abide-resolve data-id="${resolved.id}" data-resume="${resume}">${resolved.html}</abide-resolve>`
+    }
+}
+
+/* Inserts a blocking await's resolved markup into its (empty) boundary in the shell,
+   between the open and close markers. */
+function spliceResolved(shell: string, id: number, resolved: string): string {
+    const open = `<!--abide:await:${id}-->`
+    const close = `<!--/abide:await:${id}-->`
+    /* A function replacement, so a `$&`/`$\`` etc. in the rendered value is inserted
+       literally rather than interpreted as a special replacement pattern. */
+    return shell.replace(`${open}${close}`, () => `${open}${resolved}${close}`)
+}
+
+/* A self-contained script seeding the resume manifest with the blocking values, so
+   client hydration adopts each resolved branch instead of re-running the promise.
+   Empty when no blocking awaits settled. */
+function resumeScript(resumed: Record<number, ResumeEntry>): string {
+    if (Object.keys(resumed).length === 0) {
+        return ''
+    }
+    const payload = JSON.stringify(resumed).replace(/</g, '\\u003c')
+    return `<script>Object.assign(window.__abideResume=window.__abideResume||{},${payload})</script>`
+}
+
+type Settled = { id: number; html: string; resume: ResumeEntry }
+
+/* Awaits one block's promise and renders the resolved or error branch to HTML,
+   capturing the value (serializable) for the resume manifest. Errors serialize as
+   their message — enough for the catch branch, without leaking a stack. */
+function settle(block: SsrAwait): Promise<Settled> {
+    return Promise.resolve(block.promise()).then(
+        (value) => ({ id: block.id, html: block.then(value), resume: { ok: true, value } }),
+        (error) => {
+            /* No catch branch → surface the rejection (500 before the first flush,
+               mid-stream error after) instead of swallowing it into an empty fragment. */
+            if (block.catch === undefined) {
+                throw error
+            }
+            return {
+                id: block.id,
+                html: block.catch(error),
+                resume: { ok: false, error: String(error) },
+            }
+        },
+    )
+}
+
+/* JSON for an HTML double-quoted attribute: escape `"` and `&` (and `<` for safety
+   inside markup). `applyResolved`/the inline swap script decode it via the DOM. */
+function encodeResume(resume: ResumeEntry): string {
+    return JSON.stringify(resume)
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+}