@abide/abide 0.58.0 → 0.100.0

package/src/lib/ui/renderChain.ts

@@ -1,113 +0,0 @@
-import { isolateCellBarrier } from './isolateCellBarrier.ts'
-import { CHILD_PRESENT } from './runtime/CHILD_PRESENT.ts'
-import { OUTLET_CLOSE, OUTLET_OPEN } from './runtime/OUTLET_MARKER.ts'
-import type { RenderContext } from './runtime/types/RenderContext.ts'
-import type { SsrRender } from './runtime/types/SsrRender.ts'
-import type { UiComponent } from './runtime/types/UiComponent.ts'
-import type { UiProps } from './runtime/types/UiProps.ts'
-import { withPath } from './runtime/withPath.ts'
-
-const OPEN = `<!--${OUTLET_OPEN}-->`
-const CLOSE = `<!--${OUTLET_CLOSE}-->`
-/* A layout's empty outlet boundary, before the child layer is folded in. */
-const OUTLET_PLACEHOLDER = `${OPEN}${CLOSE}`
-
-/*
-Server-renders a route's layout chain wrapped around its page into one SsrRender.
-`views` is ordered outermost layout → … → page. The whole chain shares ONE request-local
-block-id counter map (`$ctx`): each `await`/`try` block draws a path-namespaced id
-(`${render-path}:${n}`, ADR-0037), so ids stay unique across layers by path rather than by
-a shared sequential draw — keeping the streamed fragments and the resume manifest aligned
-with the client (which composes the same path-keyed ids). The layers render IN PARALLEL
-(`Promise.all`, ADR-0038): each roots a distinct route-key path so their block ids never collide,
-and each runs under `isolateCellBarrier` so their async-cell barriers don't cross-drain — the html
-fold + state/awaits/resume aggregation below run after all settle and are order-independent.
-
-The html nests inner-to-outer: each parent layout's empty outlet boundary
-(`<!--abide:outlet--><!--/abide:outlet-->`) is filled with the accumulated child html —
-no `<abide-outlet>` ELEMENT, so the filled child lays out as a direct child of the
-slot's parent (the router mounts/hydrates it as a marker range, see `outlet`/`fillBoundary`).
-The whole chain is wrapped in a ROOT boundary the router fills into `#app`. Awaits
-concatenate (already uniquely numbered); state and inline blocking `resume` values merge.
-A layout missing its `<slot/>` is a build error surfaced here.
-*/
-export async function renderChain(
-    views: UiComponent[],
-    params: Record<string, string>,
-    /* Each view's route key (layout directory URL / page route pattern), aligned 1:1 with `views`
-       and byte-identical to the client router's `chainKeys`/`pageKey`. Each roots its layer's
-       render-path (`withPath`) so a cell's scope id matches the client's for the warm-seed key. */
-    keys: string[] = [],
-): Promise<SsrRender> {
-    const ctx: RenderContext = new Map()
-    const renders: SsrRender[] = []
-    /* Route params as thunks (static server-side — only shape parity with the client so
-       `props()` reads `$props["id"]?.()` resolve). A layout (every view but the last) also
-       gets `children` set to `CHILD_PRESENT` so SSR renders `{#if children}` the same way
-       the client does, keeping hydration congruent. The sentinel itself must be thunk-wrapped
-       (`() => CHILD_PRESENT`) since the destructure lowering CALLS every bag entry — leaving
-       it raw would invoke `CHILD_PRESENT` (a function) and read back `undefined`. */
-    const paramThunks: UiProps = {}
-    for (const key of Object.keys(params)) {
-        paramThunks[key] = () => params[key]
-    }
-    if (views.length > 1) {
-        /* ADR-0038: a route WITH layouts renders its layers IN PARALLEL. Block ids are path-keyed
-           (ADR-0037) and each layer roots a DISTINCT route-key path, so their id allocations never
-           collide even as the async continuations interleave; the fold + state/awaits/resume
-           aggregation below run AFTER all settle and are order-independent (keyed merges /
-           index-ordered). Each layer runs under `isolateCellBarrier` so its async-cell barrier drains
-           its OWN pending list — without it, two layers registering cells concurrently into the one
-           request-scoped list would splice-drain each other (the hazard ADR-0037 fixed for sibling
-           children). Scope needs no isolation: the shipped parallel child renders tolerate the
-           identical per-request CURRENT_SCOPE clobber (all scope-sensitive construction is
-           synchronous in each render's prefix). */
-        const collected = await Promise.all(
-            views.map((view, index) => {
-                const hasChild = index < views.length - 1
-                const props: UiProps = hasChild
-                    ? { ...paramThunks, children: () => CHILD_PRESENT }
-                    : paramThunks
-                const key = keys[index]
-                const run = () => isolateCellBarrier(() => view.render(props, ctx))
-                return key === undefined ? run() : withPath(key, run)
-            }),
-        )
-        renders.push(...collected)
-    } else if (views.length === 1) {
-        /* A lone page (no layouts) — the common case — renders DIRECTLY: no parallelism to gain, and
-           no `Promise.all`/`isolateCellBarrier` wrap, so its bare-read/settle timing is byte-identical
-           to the pre-ADR-0038 path (a fast in-process read stays pending → streams, rather than
-           slipping settled → inline behind an extra microtask). */
-        const view = views[0] as UiComponent
-        const key = keys[0]
-        renders.push(
-            key === undefined
-                ? await view.render(paramThunks, ctx)
-                : await withPath(key, () => view.render(paramThunks, ctx)),
-        )
-    }
-    let html = renders[renders.length - 1]?.html ?? ''
-    for (let index = renders.length - 2; index >= 0; index -= 1) {
-        const parent = renders[index] as SsrRender
-        /* EXACTLY one outlet, not at-least-one: `.replace` fills only the first, and
-           the client router fills the LAST `outlet()` call's boundary (`PENDING_OUTLET`),
-           so a second outlet would mount the SSR child and the hydrated child into
-           DIFFERENT slots — a silent desync. Throw at build instead. */
-        if (parent.html.split(OUTLET_PLACEHOLDER).length - 1 !== 1) {
-            throw new Error('[abide] a layout.abide must contain exactly one {children()} outlet')
-        }
-        /* Fold the child between the outlet markers (function replacement so `$&`/`$\``
-           in the child html insert literally). */
-        const child = html
-        html = parent.html.replace(OUTLET_PLACEHOLDER, () => OPEN + child + CLOSE)
-    }
-    return {
-        /* Root boundary — the router fills `#app` by claiming/creating this same
-           boundary and mounting the outermost layer (or lone page) into it. */
-        html: OPEN + html + CLOSE,
-        awaits: renders.flatMap((render) => render.awaits),
-        state: Object.assign({}, ...renders.map((render) => render.state)),
-        resume: Object.assign({}, ...renders.map((render) => render.resume)),
-    }
-}

package/src/lib/ui/renderToStream.ts

@@ -1,128 +0,0 @@
-import { resumeSeedScript } from './resumeSeedScript.ts'
-import type { ResumeEntry } from './runtime/RESUME.ts'
-import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
-import { tryEncodeResume } from './tryEncodeResume.ts'
-
-/*
-Out-of-order SSR streaming. Yields the shell first (so the browser paints
-immediately), then one resolved fragment per STREAMING 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"><script
-type="application/json">…</script>…</abide-resolve>` that the inline swap script swaps
-into the matching `<!--abide:await:ID-->` boundary; the leading script holds 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 a streaming await *block* flushes
-its shell now and streams the value when ready. Driven by an async `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 is NOT streamed — it renders
-inline during the async render pass (depth-first, matching the client) and its value
-lands in `render().resume`. The shell already carries the resolved branch, so the
-first yield just seeds those values into the manifest; only streaming blocks flush
-out of order after it.
-*/
-// @documentation plumbing
-export async function* renderToStream(
-    render: () => SsrRender | Promise<SsrRender>,
-): AsyncGenerator<string> {
-    const { html, awaits, resume } = await render()
-    /* The shell already contains every blocking await's resolved branch (rendered
-       inline); seed their values so hydration adopts them without a refetch. */
-    yield html + resumeSeedScript(resume)
-    /* A BLOCKING await nested inside a streaming branch renders inline during `settle`
-       (after the seed above), writing its value onto this same `$resume` object — so the
-       initial seed misses it. Track which resume ids are already seeded and emit the delta
-       alongside each streamed fragment, so the client adopts the nested blocking branch
-       instead of refetching. (`resume` is the render body's live object, so late writes
-       appear here.) */
-    const seededResume = new Set<string>(Object.keys(resume))
-    const resumeDelta = (): Record<string, ResumeEntry> => {
-        const delta: Record<string, ResumeEntry> = {}
-        for (const [key, entry] of Object.entries(resume)) {
-            if (!seededResume.has(key)) {
-                seededResume.add(key)
-                delta[key] = entry
-            }
-        }
-        return delta
-    }
-    /* Streaming awaits flush their resolved fragment out of order as each settles. A
-       streaming block's async resolved/error renderer may itself register NESTED streaming
-       awaits — its `branchContent` runs `$awaits.push(...)` onto this same `awaits` array
-       during `settle`, AFTER the initial scan. So re-scan for newly-appended blocks after
-       every settle (tracking which ids are already enqueued), composing to any depth. */
-    const inflight = new Map<string, Promise<Settled>>()
-    const enqueued = new Set<string>()
-    const enqueueNew = (): void => {
-        for (const block of awaits) {
-            if (!enqueued.has(block.id)) {
-                enqueued.add(block.id)
-                inflight.set(block.id, settle(block))
-            }
-        }
-    }
-    enqueueNew()
-    while (inflight.size > 0) {
-        const resolved = await Promise.race(inflight.values())
-        inflight.delete(resolved.id)
-        enqueueNew()
-        /* An unserializable value (e.g. a cyclic media tree) streams its rendered HTML
-           with NO seed script: the inline swap script (SSR_SWAP_SCRIPT) skips
-           registration when the leading child isn't a parseable script, so hydration
-           re-runs this one branch's promise — degrading to a refetch instead of aborting
-           the whole stream. */
-        const encoded =
-            resolved.resume === undefined
-                ? undefined
-                : encodeStreamResume(resolved.resume, resolved.id)
-        yield resumeSeedScript(resumeDelta()) +
-            `<abide-resolve data-id="${resolved.id}">` +
-            (encoded === undefined ? '' : `<script type="application/json">${encoded}</script>`) +
-            `${resolved.html}</abide-resolve>`
-    }
-}
-
-type Settled = { id: string; html: string; resume: ResumeEntry | undefined }
-
-/* Awaits one streaming block's promise and renders the resolved or error branch to
-   HTML (the renderers are async so a nested `await` block composes), capturing the
-   value (serializable) for the resume manifest. Errors serialize as their message —
-   enough for the catch branch, without leaking a stack. The resolved value ships inline
-   so hydration adopts the streamed branch warm. */
-function settle(block: SsrAwait): Promise<Settled> {
-    return Promise.resolve(block.promise()).then(
-        async (value) => ({
-            id: block.id,
-            html: await block.then(value),
-            /* A standalone-unit (streamed component) boundary carries no resume value of its own —
-               its `then` already merged the child's nested awaits/resume for streaming composition. */
-            resume: block.htmlOnly === true ? undefined : { ok: true, value },
-        }),
-        async (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: await block.catch(error),
-                resume: { ok: false, error: String(error) },
-            }
-        },
-    )
-}
-
-/* ref-json for a `<script type="application/json">` data block: script content is
-   raw text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
-   literal `</script>` from closing the block early — quotes stay raw, and the escape
-   survives `decodeRefJson`'s inner JSON.parse since `<` only ever appears inside JSON
-   strings. `tryEncodeResume` handles the serialize-or-refetch policy (undefined → no
-   script → the inline swap script skips registration → hydration re-runs that one promise).
-   The inline swap script stores it via `.textContent`; `awaitBlock` decodes it. */
-function encodeStreamResume(resume: ResumeEntry, id: string): string | undefined {
-    return tryEncodeResume(resume, id)?.replace(/</g, '\\u003c')
-}

package/src/lib/ui/resumeSeedScript.ts

@@ -1,27 +0,0 @@
-import { safeJsonForScript } from '../shared/safeJsonForScript.ts'
-import type { ResumeEntry } from './runtime/RESUME.ts'
-import { tryEncodeResume } from './tryEncodeResume.ts'
-
-/* A self-contained `<script>` seeding the await-resume manifest with the blocking
-   values rendered inline on the server, so client hydration adopts each resolved
-   branch instead of re-running its promise. Empty when nothing blocking resolved.
-   Each entry is ref-json-encoded to a string (decoded at read in `awaitBlock`); the
-   id→string map runs as JS (`Object.assign`), so it's wrapped in `safeJsonForScript`
-   — escaping `<`, `-->`, and U+2028/U+2029 so an encoded value can't close the script
-   early or parse as a line terminator. Shared by the buffered (`createUiPageRenderer`)
-   and streaming (`renderToStream`) paths. */
-// @documentation plumbing
-export function resumeSeedScript(resume: Record<string, ResumeEntry>): string {
-    /* ref-json (not JSON) so a value carrying cycles or shared back-references — a
-       media tree with parent↔child links — seeds instead of being dropped. `tryEncodeResume`
-       drops just an unserializable entry (the client re-runs that one branch's promise),
-       keeping every other branch seeded rather than blanking the whole page. */
-    const encoded = Object.entries(resume).flatMap(([id, entry]) => {
-        const text = tryEncodeResume(entry, id)
-        return text === undefined ? [] : [[id, text] as const]
-    })
-    if (encoded.length === 0) {
-        return ''
-    }
-    return `<script>Object.assign((window.__abideSeeds=window.__abideSeeds||{}).resume=window.__abideSeeds.resume||{},${safeJsonForScript(Object.fromEntries(encoded))})</script>`
-}