@abide/abide 0.104.0 → 0.105.0

package/src/server/fenceServer.ts

@@ -14,15 +14,15 @@
 // BY POSITION, NOT BY PATH (23.19): a directory a file mounts places its files where the app says,
 // so a `server` directory inside it is fenced as the app's own would be, wherever the package lies.
 
-import { resolve } from 'node:path' // bun exposes no path helpers of its own
 import { SERVER_DIRECTORY } from '#shared/RESERVED_DIRECTORIES.ts'
-import { placeOf } from '#shared/routePattern.ts'
+import type { Compilation } from './abideModules.ts'
 import {
     COMPONENT_NAMESPACE,
-    type Compilation,
+    realFileOf,
     STYLE_NAMESPACE,
     TEXT_NAMESPACE,
-} from './abideModules.ts'
+} from './faceOf.ts'
+import { placeOf, positionOf } from './placement.ts'
 
 // Every namespace a browser bundle loads a file of the app's in: its modules, its components, a
 // file's text and a component's stylesheet.
@@ -38,18 +38,6 @@ export function fenceServer(
     root: string,
     mounted: Compilation['mounted'],
 ): Bun.BunPlugin {
-    // Mounted directories first: one under the root's `node_modules` is the app's at its position.
-    const directories: [string, string][] = []
-    for (const [directory, at] of Object.entries(mounted))
-        directories.push([`${resolve(root, directory)}/`, at])
-    const positionOf = (path: string): string | undefined => {
-        for (const [directory, at] of directories)
-            if (path.startsWith(directory))
-                return `${at}${path.slice(directory.length)}`
-        return path.startsWith(`${root}/`)
-            ? path.slice(root.length + 1)
-            : undefined
-    }
     // Anything with a `server` directory in its path, and `placeOf` decides by its position — a
     // load it passes on falls through to the next plugin's, or the bundler's own.
     const filter = new RegExp(`/${SERVER_DIRECTORY}/`)
@@ -58,14 +46,18 @@ export function fenceServer(
         setup(build) {
             for (const namespace of FENCED)
                 build.onLoad({ filter, namespace }, (args) => {
-                    const position = positionOf(args.path)
+                    const position = positionOf(
+                        root,
+                        mounted,
+                        realFileOf(args.path),
+                    )
                     if (
                         position === undefined ||
                         placeOf(position) !== 'server'
                     )
                         return undefined
                     throw new Error(
-                        `abide: ${position.replace(/::\w+$/, '')} is under a server directory, and the browser's bundle imports it. RULEBOOK 16.29.`,
+                        `abide: ${position} is under a server directory, and the browser's bundle imports it. RULEBOOK 16.29.`,
                     )
                 })
         },

package/src/server/index.ts

@@ -47,6 +47,9 @@ export { type Config, config } from './config.ts'
 export type { ConfigField } from './configFields.ts'
 // 42 — the app object, and 37's hooks a `<script server>` calls.
 export { type App, createApp } from './createApp.ts'
+// 41.28's run-time half: an emitted component reads it on either side of its setup, and one whose
+// setup made a call answers as a page does. Not an app's name.
+export { callsInRender } from './deferredBuilds.ts'
 // 37.1's run-time half: what a compiled server module calls around its `<script server>`, so the
 // hooks it makes are filed at its route.
 export {

package/src/server/placement.ts

@@ -0,0 +1,167 @@
+// WHERE A FILE SITS IN AN APP, AND SO WHAT IT IS — answered once per file, off the path it answers by
+// (its POSITION, 23.19), and read by every walk, fence, emit and check rather than re-derived beside
+// each. The route GRAMMAR is `routePattern`'s, which the browser's router reads too; this half is the
+// build's and the server's alone, so it stays out of the client's closure.
+
+import { resolve } from 'node:path' // bun exposes no path helpers of its own
+import { LAUNCHER_PAGE } from '#shared/LAUNCHER_FILES.ts'
+import {
+    HOLDS_SERVER,
+    RESERVED_DIRECTORIES,
+    SERVER_DIRECTORY,
+} from '#shared/RESERVED_DIRECTORIES.ts'
+
+/** Where a file sits in an app, which is what it is to every reader (`placeOf`). */
+export type Place =
+    | 'address'
+    | 'server'
+    | 'public'
+    | 'lib'
+    | 'tests'
+    | 'dependency'
+    | 'skipped'
+
+/** Whether a `.abide` is a page, a layout, an error page or a component. */
+type FileKind = 'page' | 'layout' | 'error' | 'component'
+
+/** One file placed in the app: where it is, where it answers by, and what that makes it. */
+export type Placement = {
+    /** Below the root for the app's own, and above it — `../node_modules/…` — for a dependency's. */
+    relative: string
+    /** 23.19 — the path it answers by: its own below the root, or the one its mount gives it. */
+    position: string
+    place: Place
+    /** 23.21 — what a `.abide` at `position` is; a handler file is read as a page would be. */
+    kind: FileKind
+    /** 23.14 — the route of a page, a layout or an error page, and `undefined` for a component. */
+    route: string | undefined
+    /** 37.1 — the route its hooks and private handlers are filed at. */
+    scope: string
+    /**
+     * 34.23 — a package's file, by where it LIES rather than where it answers: compiled on the app's
+     * runtime (34.26), and reported on by its package rather than the app.
+     */
+    dependency: boolean
+}
+
+/**
+ * The file at `relative` placed at `position`.
+ *
+ * 23.21 — WHERE IT SITS, THEN ITS NAME. Every `.abide` directly in an address directory is a page
+ * but a `layout.abide`, an `error.abide` and the root's `launcher.abide`; one under a fence is a
+ * component whatever it is called. 37.1 — its hooks are filed at an address's own route; under a
+ * `lib` or a `tests` directory, at the route of the directory holding it, so a component an admin
+ * page renders runs under the admin route's rungs; under a `server` or a `public` directory, for a
+ * dependency's file, and for the launcher (38.82), at the root's.
+ *
+ * `position` is RELATIVE TO THE APP'S ROOT: its directories are its route, so an absolute path would
+ * read the machine's directories as the app's.
+ */
+export function placement(relative: string, position = relative): Placement {
+    const place = placeOf(position)
+    let kind: FileKind = 'component'
+    let scope = '/'
+    if (place === 'address' && position !== LAUNCHER_PAGE) {
+        const name = position.slice(position.lastIndexOf('/') + 1)
+        kind =
+            name === 'layout.abide'
+                ? 'layout'
+                : name === 'error.abide'
+                  ? 'error'
+                  : 'page'
+        scope = routeOf(position)
+    } else if (place === 'lib' || place === 'tests') {
+        const parts = position.split('/')
+        // The fence `placeOf` named is the first one, and its name is its place.
+        scope = `/${parts.slice(0, parts.indexOf(place)).join('/')}`
+    }
+    return {
+        relative,
+        position,
+        place,
+        kind,
+        route: kind === 'component' ? undefined : routeOf(position),
+        scope,
+        dependency: placeOf(relative) === 'dependency',
+    }
+}
+
+/**
+ * Where the file at `path`, relative to the app's root, sits.
+ *
+ * - `dependency` — 34.24: a package's, outside the root or under `node_modules`, whose directories
+ *   are its package's layout and none of the app's;
+ * - `skipped` — under a dot directory, which no walk of the app enters;
+ * - `server`, `public`, `lib` or `tests` — 23.15: under that fence, the nearest to the root deciding,
+ *   save a `server` under a `lib` or a `tests`, which is `server` — the fence the browser's bundle
+ *   is checked against (16.29) is never hidden by one above it (23.16);
+ * - `address` — 23.14: everywhere else, its directories the segments of its route.
+ *
+ * The last part is the file itself, so a path ending in `/` is a directory and every part is read.
+ */
+export function placeOf(path: string): Place {
+    if (path.startsWith('../') || path.startsWith('/')) return 'dependency'
+    const parts = path.split('/')
+    // A `lib` or a `tests` met first, which a `server` below it still overrides.
+    let fence: Place | undefined
+    for (let index = 0; index < parts.length - 1; index += 1) {
+        const part = parts[index] as string
+        if (skipped(part))
+            return fence ?? (part === 'node_modules' ? 'dependency' : 'skipped')
+        if (fence !== undefined) {
+            if (part === SERVER_DIRECTORY) return 'server'
+        } else if (RESERVED_DIRECTORIES.has(part)) {
+            if (!HOLDS_SERVER.has(part)) return part as Place
+            fence = part as Place
+        }
+    }
+    return fence ?? 'address'
+}
+
+/** Whether a walk of the app passes over the entry `name`: a dot file or directory, or `node_modules`. */
+export function skipped(name: string): boolean {
+    return name.startsWith('.') || name === 'node_modules'
+}
+
+/**
+ * The route a file answers at — its path below the root without its extension.
+ *
+ * 23.14 — `media/[id].abide` and `media/getGrid.ts` are `/media/[id]` and `/media/getGrid`; an
+ * `index.abide`, a `layout.abide` and an `error.abide` are their directory's.
+ */
+export function routeOf(path: string): string {
+    const parts = path.split('/')
+    const file = parts.pop() as string
+    // The extension alone: `[...rest].abide` carries dots of its own.
+    if (!DIRECTORY_FILES.has(file)) parts.push(file.replace(EXTENSION, ''))
+    return `/${parts.filter((part) => part !== '').join('/')}`
+}
+
+const EXTENSION = /\.(?:abide|ts)$/
+
+/** 23.14, 23.18 — the names whose route is their directory's, and so a route's wherever they stand. */
+export const DIRECTORY_FILES = new Set([
+    'index.abide',
+    'layout.abide',
+    'error.abide',
+])
+
+/**
+ * The position of the file at the absolute `path`: the one a mount gives it where a directory in
+ * `mounted` holds it (23.19), its own below `root` where the root does, `undefined` otherwise.
+ *
+ * `mounted` is `Compilation.mounted`, a directory below the root to the position its files take —
+ * directory-shaped, because a module under a mounted `server` directory is placed by it too.
+ */
+export function positionOf(
+    root: string,
+    mounted: Readonly<Record<string, string>>,
+    path: string,
+): string | undefined {
+    for (const directory in mounted) {
+        const prefix = `${resolve(root, directory)}/`
+        if (path.startsWith(prefix))
+            return `${mounted[directory]}${path.slice(prefix.length)}`
+    }
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : undefined
+}

package/src/server/remote.ts

@@ -4,7 +4,8 @@
 // sent (36.6), and neither variable is read anywhere else.
 
 import { applyPatch } from '#shared/applyPatch.ts'
-import { filledPath, parametersOf } from '#shared/filledPath.ts'
+import { eventsOf } from '#shared/framing.ts'
+import { HandlerRoute } from '#shared/HandlerRoute.ts'
 import { firstMatch, partsOf } from '#shared/matchRoute.ts'
 import type { PatchOp } from '#shared/reactive/PATCH_SINKS.ts'
 import { rankRoutes } from '#shared/routePattern.ts'
@@ -59,13 +60,14 @@ export async function callHandler(
     const asked = method?.toUpperCase()
     const handler = handlerAt(handlers, address, asked)
     const args = callArgs(given)
+    const route = new HandlerRoute(address)
     const chosen = (asked ??
         (handler?.method as Method | undefined) ??
         (args === undefined ? 'GET' : 'POST')) as Method
     const request =
         args instanceof URLSearchParams
-            ? textRequest(chosen, address, args)
-            : rpcRequest(chosen, address, args)
+            ? textRequest(chosen, route, args)
+            : rpcRequest(chosen, route, args)
     const answer = await fetch(`${url}${request.url}`, {
         ...request.init,
         headers: { ...remoteHeaders(), ...request.init.headers },
@@ -129,19 +131,19 @@ function handlerAt(
  */
 function textRequest(
     method: Method,
-    route: string,
+    route: HandlerRoute,
     given: URLSearchParams,
 ): { url: string; init: RequestInit } {
-    let address = route
+    let address = route.address
     let pairs = given
-    if (route.includes('[')) {
+    if (route.segments !== undefined) {
         const params: Record<string, string> = {}
         pairs = new URLSearchParams()
-        const named = parametersOf(route)
         for (const [name, value] of given)
-            if (named.has(name)) params[name] = value
+            if (route.names.has(name)) params[name] = value
             else pairs.append(name, value)
-        address = filledPath(route, params, route)
+        // Thrown as the message it is, which the command line prints.
+        address = route.path(params, (_name, message) => new Error(message))
     }
     if (argsInURL(method))
         return { url: `${address}?${pairs}`, init: { method } }
@@ -169,12 +171,12 @@ export async function watch(
     given: string[],
     signal?: AbortSignal,
 ): Promise<number> {
-    const path = `/${address.replace(/^\//, '')}`
+    const route = new HandlerRoute(`/${address.replace(/^\//, '')}`)
     const args = callArgs(given)
     const request =
         args instanceof URLSearchParams
-            ? textRequest('GET', path, args)
-            : rpcRequest('GET', path, args)
+            ? textRequest('GET', route, args)
+            : rpcRequest('GET', route, args)
     const answer = await fetch(`${url}${request.url}`, {
         ...request.init,
         headers: {
@@ -207,33 +209,3 @@ export async function watch(
     }
     return 0
 }
-
-/** Each event of an event stream: its `event` name, `message` where it named none, and its `data`. */
-async function* eventsOf(
-    body: ReadableStream<Uint8Array>,
-): AsyncIterable<{ name: string; data: string }> {
-    const decoder = new TextDecoder()
-    let buffered = ''
-    for await (const chunk of body) {
-        buffered += decoder.decode(chunk, { stream: true })
-        for (
-            let end = buffered.indexOf('\n\n');
-            end !== -1;
-            end = buffered.indexOf('\n\n')
-        ) {
-            const block = buffered.slice(0, end)
-            buffered = buffered.slice(end + 2)
-            let name = 'message'
-            let data: string | undefined
-            for (const line of block.split('\n')) {
-                if (line.startsWith('event:')) name = line.slice(6).trim()
-                else if (line.startsWith('data:')) {
-                    const field = line.slice(5).replace(/^ /, '')
-                    data = data === undefined ? field : `${data}\n${field}`
-                }
-            }
-            // A comment alone — the stream's opener — is no event.
-            if (data !== undefined) yield { name, data }
-        }
-    }
-}

package/src/server/render.ts

@@ -6,11 +6,10 @@
 import { regionMarkup } from '#shared/anchorMarkup.ts'
 import { EARLY_CALLS } from '#shared/EARLY_CALLS.ts'
 import { headKeyOf } from '#shared/headKeyOf.ts'
-import { isReactive, isStreaming, loadOf } from '#shared/reactive/index.ts'
 import { isThenable } from '#shared/reactive/isThenable.ts'
 import type { ShareScope } from '#shared/reactive/share.ts'
 import { setUpLevels } from '#shared/setUpLevels.ts'
-import { VERSION_HEADER } from '#shared/VERSION_HEADER.ts'
+import { buildDeferred, markPainted } from './deferredBuilds.ts'
 import { currentRequestScope, type PageCall } from './requestScope.ts'
 
 /**
@@ -90,12 +89,19 @@ export async function composePage(
     })
     await new Promise((settled) => setImmediate(settled))
     const outermost = levels[0] as Rendered
-    // THE OUTERMOST HEAD FIRST: reading it builds the chain, which is what pushes the heads below.
-    // Written end to end rather than merged: `render` merges it with the shell's in one pass (39.4).
-    const head = outermost.head
+    const built = await buildDeferred(
+        currentRequestScope()?.page?.calls ?? [],
+        () => {
+            // THE OUTERMOST HEAD FIRST: reading it builds the chain, which is what pushes the heads
+            // below. Written end to end rather than merged: `render` merges it with the shell's in one
+            // pass (39.4).
+            const head = outermost.head
+            return { head: head + heads.join(''), body: outermost.body }
+        },
+    )
     return {
-        head: head + heads.join(''),
-        body: outermost.body,
+        head: built.head,
+        body: built.body,
         // 35.15 — the document's, which only the root layout writes, and it is outermost.
         document: outermost.document,
     }
@@ -317,6 +323,7 @@ export async function renderDocument(
     // makes is known, and a script in the head starts each one as the request the browser's own
     // `Rpc` would make — while the rest of the document and the bundle are still on their way.
     const calls = currentRequestScope()?.page?.calls
+    if (calls !== undefined) markPainted(calls)
     const early =
         calls !== undefined && calls.length > 0 ? earlyCallScript(calls) : ''
     // 39.4 — THE SHELL IS THE OUTERMOST CONTRIBUTOR, so its head is merged with the page's in the
@@ -335,15 +342,14 @@ export async function renderDocument(
  * The head markup that starts each of the page's calls before the bundle arrives.
  *
  * 41.20 — THE SCRIPT ITSELF: each call started with `fetch`, and its answer left under the call's
- * key in `EARLY_CALLS` for `wire` to take (41.21). A framed answer's body is left UNREAD (16.32),
- * so a streaming handler's copy takes its chunks as they land rather than after the last one.
+ * key in `EARLY_CALLS` for `wire` to take (41.21). An answer's body is left UNREAD (16.32), so a
+ * streaming handler's copy takes its chunks as they land rather than after the last one.
  * Inline because nothing else runs before the bundle has arrived, which is the wait it exists to
  * overlap.
  *
  * 41.25 — A ROW ENDING IN `1` IS A CALL THE MARKUP WAS BUILT FROM SETTLED, a refusal included, and
- * its entry is marked `painted` for hydration to wait on — a body that is not JSON read to its bytes,
- * so the wait covers it too. Read here, where the markup has just been built and only microtasks
- * have run since. 41.26 — A CALL THAT STREAMS IS NEVER MARKED: the
+ * its entry is marked `painted` for hydration to wait on — its body read to its bytes, so the wait
+ * covers it too. Marked as each pass of the markup is built (`markPainted`), not here. 41.26 — A CALL THAT STREAMS IS NEVER MARKED: the
  * browser reads its chunks as they land (16.32), so no wait for its answer makes it settled where
  * the page hydrates, and its region is 41.24's to put right.
  *
@@ -358,18 +364,20 @@ function earlyCallScript(calls: PageCall[]): string {
         | [string, string, RequestInit]
         | [string, string, RequestInit, 1]
     )[] = []
-    for (const { request, reached } of calls)
+    for (const { request, painted } of calls)
         rows.push(
-            isReactive(reached) &&
-                loadOf(reached) === undefined &&
-                !isStreaming(reached)
+            painted === true
                 ? [request.key, request.url, request.init, 1]
                 : [request.key, request.url, request.init],
         )
     return `<script type="application/json">${JSON.stringify(rows).replace(/</g, '\\u003c')}</script><script>${EARLY_CALL_RUNNER}</script>`
 }
 
-const EARLY_CALL_RUNNER = `(function(s,c){for(var i=0;i<c.length;i++)(function(k,u,n,h){var e=s[k]={painted:h,status:void 0,statusText:void 0,type:void 0,version:void 0,life:void 0,text:void 0,bytes:void 0,body:void 0};e.promise=fetch(u,n).then(function(r){e.status=r.status;e.statusText=r.statusText;e.type=r.headers.get("content-type");e.version=r.headers.get("${VERSION_HEADER}");e.life=r.headers.get("cache-control");if(r.ok&&e.type&&!/^application\\/([^;]*\\+)?json\\s*(;|$)/.test(e.type)){if(h)return r.arrayBuffer().then(function(b){e.bytes=new Uint8Array(b)});e.body=r.body;return}return r.text()}).then(function(t){if(t!==void 0)e.text=t},function(){})})(c[i][0],c[i][1],c[i][2],c[i][3])})(self.${EARLY_CALLS}||(self.${EARLY_CALLS}={}),JSON.parse(document.currentScript.previousElementSibling.textContent))`
+// THE RUNNER RECORDS, IT NEVER CLASSIFIES: the `Response`, and a painted call's body read to its end
+// — the one decision is `painted`, which the server made. `answerOf` reads the record as it reads an
+// answer it fetched, so no second reading of a content type lives in a string no typecheck reaches.
+// The shape is `EarlyCall`'s.
+export const EARLY_CALL_RUNNER = `(function(s,c){for(var i=0;i<c.length;i++)(function(k,u,n,h){var e=s[k]={painted:h,response:void 0,bytes:void 0};e.promise=fetch(u,n).then(function(r){return h?r.arrayBuffer().then(function(b){e.bytes=b;e.response=r}):e.response=r}).catch(function(){})})(c[i][0],c[i][1],c[i][2],c[i][3])})(self.${EARLY_CALLS}||(self.${EARLY_CALLS}={}),JSON.parse(document.currentScript.previousElementSibling.textContent))`
 
 /** The early-call runner's hash, as `script-src` names it. 29.9. */
 export const EARLY_CALL_HASH = `'sha256-${new Bun.CryptoHasher('sha256').update(EARLY_CALL_RUNNER).digest('base64')}'`

package/src/server/renderComponent.ts

@@ -1,4 +1,5 @@
 import { regionMarkup } from '#shared/anchorMarkup.ts'
+import { callsMadeSoFar, deferBuild, refuseDocument } from './deferredBuilds.ts'
 import type { Component, Rendered } from './render.ts'
 
 /**
@@ -25,14 +26,17 @@ export function renderComponent(
     heads: string[],
 ): string {
     if (component == null) return regionMarkup('')
+    const callsFrom = callsMadeSoFar()
     const rendered = (
         component as (props: Record<string, () => unknown>) => Rendered
     )(props)
-    // 35.16 — a document is written by the outermost component alone, and this one is placed.
-    if (rendered.document !== undefined)
-        throw new Error(
-            'abide: a component that writes <html> is placed inside another, and only the outermost component writes the document. RULEBOOK 35.16.',
-        )
+    // 41.28 — A CHILD WHOSE SETUP MADE A CALL ANSWERS AS A PAGE DOES, with a `scope` and its build
+    // left for the first read, and is built after the turn where a page is being built.
+    if ('scope' in rendered) {
+        const marker = deferBuild(rendered, heads, callsFrom)
+        if (marker !== undefined) return marker
+    }
+    refuseDocument(rendered)
     if (rendered.head !== '') heads.push(rendered.head)
     return regionMarkup(rendered.body)
 }

package/src/server/requestScope.ts

@@ -11,6 +11,7 @@
 
 import { AsyncLocalStorage } from 'node:async_hooks' // bun implements AsyncLocalStorage and has no context-carrying api of its own
 import { Cookies } from '#shared/cookies.ts'
+import type { Framed } from '#shared/framing.ts'
 import type { Params } from '#shared/matchRoute.ts'
 import type { Principal } from '#shared/principal.ts'
 import { SCOPING, type Scope } from '#shared/reactive/scoping.ts'
@@ -18,7 +19,7 @@ import type { RpcRequest } from '#shared/rpcRequest.ts'
 import type { McpSurface } from './generatedSurfaces.ts'
 
 /** The three framings a stream is answered in. 17.6. */
-export type Framing = 'jsonl' | 'sse' | 'bytes'
+export type Framing = Framed | 'bytes'
 
 /** What one request, or one `App.run`, carries across every `await` its work makes. */
 export type RequestScope = Scope & {
@@ -123,10 +124,15 @@ export type AnsweringApp = {
 }
 
 /**
- * One call a page's render made: the request the browser will make for it, and what it reached —
- * read once the markup is built, for whether it was painted settled (41.25).
+ * One call a page's render made: the request the browser will make for it, what it reached, and
+ * whether the markup was built from it settled — `undefined` until the pass that built from it
+ * ends (41.25, `markPainted`).
  */
-export type PageCall = { request: RpcRequest; reached: unknown }
+export type PageCall = {
+    request: RpcRequest
+    reached: unknown
+    painted: boolean | undefined
+}
 
 // `undefined` IS A STORE, not the absence of one: a value built outside every request runs its body
 // under it (`Cell.scope`), rather than under whichever request scheduled the drain.