@abide/abide 0.100.0 → 0.102.0

package/src/shared/routePattern.ts

@@ -1,5 +1,5 @@
-// A ROUTE LITERAL, PARSED. One grammar for two things that would otherwise drift: the directory a
-// page is filed under (`ui/pages/invoices/[id]/page.abide`) and the literal an author writes
+// A ROUTE LITERAL, PARSED. One grammar for two things that would otherwise drift: the file a
+// page is filed as (`invoices/[id]/page.abide`) and the literal an author writes
 // (`'/invoices/[id]'`). The bracket spelling is the file system's, so the address is read off the
 // tree rather than declared beside it and the two cannot disagree.
 //
@@ -7,8 +7,10 @@
 // required takes a value, optional may be left out and omits its segment with it, and rest takes
 // an array as well as a scalar.
 //
-// A LEAF: no imports, because the compiler, the client router and a server router all read it and
-// a constant crossing a seam lives where nothing pulls a graph in behind it.
+// A LEAF: nothing imported but another leaf, because the compiler, the client router and a server
+// router all read it and a constant crossing a seam lives where nothing pulls a graph in behind it.
+
+import { PUBLIC_DIRECTORY, SERVER_DIRECTORY } from './RESERVED_DIRECTORIES.ts'
 
 type SegmentKind = 'static' | 'required' | 'optional' | 'rest'
 
@@ -40,26 +42,23 @@ export function parseRoutePattern(pattern: string): Segment[] {
     return out
 }
 
-const ROUTES = 'ui/pages/'
-
 /** Whether a source is a page, a layout, an error page or a component. */
 export type FileKind = 'page' | 'layout' | 'error' | 'component'
 
 /**
  * Whether the `.abide` at `path` is a page, a layout, an error page or a component.
  *
- * AN ADDRESS RATHER THAN A NAME. Both halves are load-bearing: the file name is the address and
- * the directory is what says the address is a ROUTE rather than a component filed anywhere. One
- * test for every name (35.1 reads `layout.abide` the same way), so the directory half cannot be
- * got right for one and wrong for another — and one test for every reader: the build's routes,
- * the checker's `Routes` and the `route.params` a page is typed by.
+ * AN ADDRESS RATHER THAN A NAME. The file name says which of the three it is, and only a file
+ * whose place is an `address` (`placeOf`) is one: a `page.abide` under a `server` directory is a
+ * component.
+ * One test for every reader: the build's routes, the checker's `Routes` and the `route.params` a
+ * page is typed by.
  *
- * 23.3 — under `ui/pages/` and nowhere else: a `page.abide` filed in some other `pages/`
- * directory is a component, as it is to the `Routes` the checker declares. `path` may be relative
- * to the app or the project, or absolute.
+ * `path` 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 fileKind(path: string): FileKind {
-    if (routesAt(path) === -1) return 'component'
+    if (placeOf(path) !== 'address') return 'component'
     // The WHOLE basename: `homepage.abide` ends with `page.abide` and is a component.
     const name = path.slice(path.lastIndexOf('/') + 1)
     if (name === 'page.abide') return 'page'
@@ -67,30 +66,50 @@ export function fileKind(path: string): FileKind {
     return name === 'error.abide' ? 'error' : 'component'
 }
 
+/** Where a file sits in an app, which is what it is to every reader (`placeOf`). */
+export type Place = 'address' | 'server' | 'public' | 'dependency' | 'skipped'
+
 /**
- * The route literal a page file is filed under, read off its path below `ui/pages/`.
- *
- * `page.abide` is an address rather than a name (CLAUDE.md), so the directories above it ARE the
- * route and the file itself contributes nothing.
+ * Where the file at `path`, relative to the app's root, sits — THE ONE ANSWER every walk, fence and
+ * emit reads, so no two of them disagree about a path.
  *
- * 23.3 — BELOW THE FIRST `ui/pages/`, which is the routes directory, and not below the last `pages/`:
- * a section an app files as `ui/pages/pages/` is the address `/pages`, and cutting at the last one
- * served `ui/pages/pages/add-a-page` at `/add-a-page` and gave `/` two pages.
+ * - `dependency` — 34.28: 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` or `public` — 23.15: under that reserved directory, the nearest to the root deciding
+ *   (23.16 refuses one inside the other);
+ * - `address` — 23.14: everywhere else, its directories the segments of its route.
  */
-export function routeOf(pagePath: string): string {
-    const at = routesAt(pagePath)
-    const tail = at === -1 ? pagePath : pagePath.slice(at + ROUTES.length)
-    const parts: string[] = []
-    for (const part of tail.split('/'))
-        if (part !== '' && !part.endsWith('.abide')) parts.push(part)
-    return `/${parts.join('/')}`
+export function placeOf(path: string): Place {
+    if (path.startsWith('../') || path.startsWith('/')) return 'dependency'
+    const parts = path.split('/')
+    // The last part is the file itself, which is never a directory.
+    for (let index = 0; index < parts.length - 1; index += 1) {
+        const part = parts[index] as string
+        if (part === 'node_modules') return 'dependency'
+        if (part.startsWith('.')) return 'skipped'
+        if (part === SERVER_DIRECTORY) return 'server'
+        if (part === PUBLIC_DIRECTORY) return 'public'
+    }
+    return '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'
 }
 
-/** Where the first `ui/pages/` in `path` begins, as whole directories, or -1. */
-function routesAt(path: string): number {
-    if (path.startsWith(ROUTES)) return 0
-    const at = path.indexOf(`/${ROUTES}`)
-    return at === -1 ? -1 : at + 1
+/**
+ * The route a file answers at — its DIRECTORY's below the root, whatever its name.
+ *
+ * 23.14 — `media/[id]/page.abide` is `/media/[id]`, and so is every other file beside it, which is
+ * what lets a directory's handlers sit in as many files as an author likes (16.2). `path` is
+ * relative to the app's root, as `fileKind`'s is.
+ */
+export function routeOf(path: string): string {
+    const parts = path.split('/')
+    parts.pop()
+    return `/${parts.filter((part) => part !== '').join('/')}`
 }
 
 /**
@@ -107,27 +126,44 @@ function routesAt(path: string): number {
  * themselves, and `/x` ranked BELOW `/[[a]]/[[b]]` for the path `/x`: a static segment beaten by
  * two optionals, which is 30.9 exactly inverted. Both were live on the scalar this replaced.
  *
- * THE SHORTER PATTERN WINS A TIE, and only an exhausted prefix can produce one: every segment the
- * two share is the same kind, so what is left is the extra segments of the longer, which can only
- * be optional or rest or the two would not match one path. `/a` admits one address and
- * `/a/[[b]]` admits two, so the shorter is the narrower claim.
+ * WHERE ONE PATTERN ENDS, ITS END RANKS AS A SEGMENT: below a static or a required one and above an
+ * optional or a rest. `/a` admits one address and `/a/[[b]]` admits two, so the shorter is the
+ * narrower claim; but `/[[lang]]` and `/[[lang]]/about` both match `/about`, the longer by a static
+ * segment where the shorter spends `about` on an optional, so there the longer is.
  */
 export function compareRoutes(a: Segment[], b: Segment[]): number {
-    const shared = a.length < b.length ? a.length : b.length
-    for (let at = 0; at < shared; at += 1) {
-        const kind =
-            specificity(b[at] as Segment) - specificity(a[at] as Segment)
+    const longest = a.length > b.length ? a.length : b.length
+    for (let at = 0; at < longest; at += 1) {
+        const kind = specificity(b[at]) - specificity(a[at])
         if (kind !== 0) return kind
     }
-    return a.length - b.length
+    return 0
 }
 
-function specificity(segment: Segment): number {
-    if (segment.kind === 'static') return 3
-    if (segment.kind === 'required') return 2
+function specificity(segment: Segment | undefined): number {
+    if (segment === undefined) return 2
+    if (segment.kind === 'static') return 4
+    if (segment.kind === 'required') return 3
     return segment.kind === 'optional' ? 1 : 0
 }
 
+/**
+ * Whether `outer` is the front of `route`: a static segment by name, a parameter by kind.
+ *
+ * 35.1, 37.2 — what a layout wraps and what a route's hooks run over: the routes at or below its
+ * own, a parameter's name aside, so `/media/[id]` covers `/media/[slug]/edit`.
+ */
+export function coversRoute(outer: Segment[], route: Segment[]): boolean {
+    if (outer.length > route.length) return false
+    for (let at = 0; at < outer.length; at += 1) {
+        const one = outer[at] as Segment
+        const two = route[at] as Segment
+        if (one.kind !== two.kind) return false
+        if (one.kind === 'static' && one.name !== two.name) return false
+    }
+    return true
+}
+
 /**
  * A route table compiled for matching: each row with its pattern parsed, most specific first.
  *

package/src/shared/rpc.ts

@@ -6,7 +6,7 @@
 // A HANDLER IS A `reactive` OR BECOMES ONE (16.1), so an `Rpc` is not a second kind of value: the
 // call hands back the handler's own `Reactive` (16.3), and every probe, trigger and failure on it is
 // the reactive core's — the `Rpc`'s own `busy`, `ready`, `refresh` and `invalidate` are the
-// handler's, passed through. What this file adds is the normalising — a plain function or a value becomes the
+// handler's, passed through. What this file adds is the normalizing — a plain function or a value becomes the
 // `reactive` it would have been (16.6) — and the method.
 //
 // A HANDLER DECLARING `middleware` IS REACHED THROUGH ITS RUNGS (16.11), in process as over the wire:
@@ -14,6 +14,7 @@
 // handler's own.
 
 import { type Failed, isFailedNamed } from './Failed.ts'
+import { filledSegments } from './filledPath.ts'
 import { GLOBAL_GETS } from './GLOBAL_GETS.ts'
 import { compose, type Middleware } from './Middleware.ts'
 import { principalRotated } from './principalRotated.ts'
@@ -23,7 +24,7 @@ import {
     type Gated,
     gateOf,
     keyOf,
-    normalised,
+    normalized,
 } from './reactive/argsContract.ts'
 import { callLoad } from './reactive/callLoad.ts'
 import {
@@ -48,7 +49,8 @@ import { MUTATION } from './reactive/MUTATION.ts'
 import { SELECTION_MEMBERS } from './reactive/SELECTION_MEMBERS.ts'
 import { isForwarder } from './reactive/scoped.ts'
 import { checkArgs } from './refuse.ts'
-import { rpcRequest } from './rpcRequest.ts'
+import { parseRoutePattern, type Segment } from './routePattern.ts'
+import { pathRefusal, rpcRequest } from './rpcRequest.ts'
 import type { Schema } from './Schema.ts'
 
 export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
@@ -131,7 +133,7 @@ export type RpcContext<Args = unknown> = { request: Request; args: () => Args }
  * The context key holding the args as sent.
  *
  * 11.26 — THE ARGS AS SENT, carried on the context under a key no rung spells, so the reach at the
- * onion's centre keys the value by them rather than by what the gate made of them.
+ * onion's center keys the value by them rather than by what the gate made of them.
  */
 const SENT: unique symbol = Symbol('abide.sent')
 
@@ -331,10 +333,10 @@ export function declare(method: Method): Declare {
                 args: argsOnce(gateOf(contract), args),
                 [SENT]: args,
             }) as RpcContext
-        // 16.32 BEHIND RUNGS — A STREAM'S CHUNKS ARE FORWARDED, not collected. The centre of the
+        // 16.32 BEHIND RUNGS — A STREAM'S CHUNKS ARE FORWARDED, not collected. The center of the
         // onion is an async function, and a `Reactive` is thenable (1.4), so handing a streaming value
         // out through it would wait out the whole run and answer the accumulation once it closed. So
-        // the centre waits only until the value settles or turns out to stream (9.6), and hands a
+        // the center waits only until the value settles or turns out to stream (9.6), and hands a
         // stream on as its chunks — a generator, which is not thenable. The value the call reaches
         // resolves to it and is a stream of its own from then (9.6), so a second call joining it
         // (1.8) reads the same accumulation. A refusal a rung answers with is the value's refusal.
@@ -369,8 +371,35 @@ export function declare(method: Method): Declare {
         // this handler and these args is then answered from what this one reached, rather than by
         // running the handler again. In a browser nothing fills the slot, so the report is one load
         // of a `null`.
+        //
+        // 15.8 — AND REFUSED AHEAD OF THE HANDLER where the args leave a parameter of its route no
+        // spelling (30.3, 30.19), as the wire refuses them: a render and the browser's call then
+        // reach the same refusal, and there is no request for the render to report. The route is
+        // parsed once per address, which is stamped after the declaration (16.10).
+        let routed: string | undefined
+        let routeSegments: Segment[] | null = null
         const call = (given?: unknown, options?: CallOptions): unknown => {
-            const args = normalised(contract, given)
+            const args = normalized(contract, given)
+            const address = rpc.address
+            if (address !== routed) {
+                routed = address
+                routeSegments =
+                    address?.includes('[') === true
+                        ? parseRoutePattern(address)
+                        : null
+            }
+            if (routeSegments !== null) {
+                try {
+                    filledSegments(
+                        routeSegments,
+                        (args ?? {}) as Record<string, unknown>,
+                        routed as string,
+                        pathRefusal,
+                    )
+                } catch (refused) {
+                    return reactive(() => refused)
+                }
+            }
             const reached = callLoad(
                 reachThrough,
                 args,
@@ -446,12 +475,17 @@ export function declare(method: Method): Declare {
         // value produced, and holds no way back to it. A keyed value is looked up without a reach,
         // so asking starts nothing (11.55).
         if (method === 'GET' && !isForwarder(value))
-            GLOBAL_GETS.set(rpc, (args: unknown): unknown =>
+            GLOBAL_GETS.set(
+                rpc,
                 keyed
-                    ? (value as { entries: Map<string, unknown> }).entries.get(
-                          keyOf(contract, args),
-                      )
-                    : value,
+                    ? {
+                          key: (args) => keyOf(contract, args),
+                          at: (key) =>
+                              (
+                                  value as { entries: Map<string, unknown> }
+                              ).entries.get(key),
+                      }
+                    : { key: () => '', at: () => value },
             )
         return rpc
     }) as Declare
@@ -467,7 +501,7 @@ export const DELETE: Declare = declare('DELETE')
 function addressOf(rpc: { address: string | undefined }): string {
     if (rpc.address === undefined)
         throw new Error(
-            'abide: this handler has no address yet. A handler is given one where it is mounted, under src/server/rpc (16.2).',
+            'abide: this handler has no address yet. A handler is given one where it is mounted, exported from a <script server> (16.2).',
         )
     return rpc.address
 }

package/src/shared/rpcRequest.ts

@@ -4,9 +4,12 @@
 // that agreement: method, URL and body, which is what makes two requests the same one.
 //
 // A `GET` or `DELETE` carries its args in the URL, in `queryText`'s spelling, and a mutation in its
-// body; 19.7 is where text becomes the declared type again.
+// body; 19.7 is where text becomes the declared type again. 16.9 — whatever the method, a parameter
+// of the handler's route rides in the path, and the server puts it back among the args (16.65).
 
+import { filledPath, parametersOf } from './filledPath.ts'
 import { queryText } from './queryText.ts'
+import { validationError } from './refuse.ts'
 import type { Method } from './rpc.ts'
 
 export type RpcRequest = {
@@ -32,10 +35,26 @@ export function argsInURL(method: Method): boolean {
 export function rpcRequest(
     method: Method,
     address: string,
-    args: Record<string, unknown> | undefined,
+    given: Record<string, unknown> | undefined,
 ): RpcRequest {
+    let args = given
     let url = address
     let body: string | undefined
+    // A route with parameters: they are written into the path and leave the args, so the query or
+    // body never carries one twice (16.66). 15.8 — one no address carries (30.3, 30.19) is refused as
+    // args a gate refused, so every caller answers it as the wire answers a 422.
+    if (address.includes('[')) {
+        const params = given ?? {}
+        url = filledPath(address, params, address, pathRefusal)
+        const inPath = parametersOf(address)
+        let rest: Record<string, unknown> | undefined
+        for (const name in params) {
+            if (inPath.has(name)) continue
+            rest ??= {}
+            rest[name] = params[name]
+        }
+        args = rest
+    }
     if (argsInURL(method)) {
         if (args !== undefined) {
             let text = queryText(args)
@@ -47,7 +66,7 @@ export function rpcRequest(
                 const bare = bareName(name)
                 text = text === '' ? bare : `${text}&${bare}`
             }
-            if (text !== '') url = `${address}?${text}`
+            if (text !== '') url = `${url}?${text}`
         }
     } else if (args !== undefined) body = JSON.stringify(args)
     // 18.14 — A COPY IS ITS OWN CACHE and keeps its own `max-age`. What it asks the server is asked
@@ -67,6 +86,11 @@ export function rpcRequest(
     return { method, url, body, init, key: `${method} ${url} ${body ?? ''}` }
 }
 
+/** 15.8 — a parameter no address carries, refused as args a gate refused. */
+export function pathRefusal(name: string, message: string): unknown {
+    return validationError<Record<string, unknown>>({ [name]: [message] })
+}
+
 /** A query member's name in the encoding `URLSearchParams` gives it, without its `=`. */
 export function bareName(name: string): string {
     return new URLSearchParams([[name, '']]).toString().slice(0, -1)

package/src/shared/url.ts

@@ -4,9 +4,9 @@
 //
 // 16.10 — RESOLVED AGAINST THE MOUNT at the call, so the same build serves at the root and below it.
 
+import { filledPath } from './filledPath.ts'
 import { mounted } from './mount.ts'
 import { queryText } from './queryText.ts'
-import { parseRoutePattern } from './routePattern.ts'
 
 type Parts<P extends string> = P extends `${infer Head}/${infer Tail}`
     ? Head | Parts<Tail>
@@ -86,29 +86,9 @@ export function url<P extends RouteLiteral>(
 ): string {
     const params = (rest[0] ?? {}) as Record<string, unknown>
     const query = rest[1]
-    let address = ''
-    for (const segment of parseRoutePattern(pattern ?? '/')) {
-        if (segment.kind === 'static') {
-            address += `/${segment.name}`
-            continue
-        }
-        const value = params[segment.name]
-        if (value === undefined || value === null || value === '') {
-            // 30.4 — an optional left out omits its segment, and so does an empty rest (30.5).
-            if (segment.kind !== 'required') continue
-            throw new Error(
-                `abide: url('${pattern}') was given no '${segment.name}', and the route requires it. RULEBOOK 30.3.`,
-            )
-        }
-        if (segment.kind === 'rest' && Array.isArray(value)) {
-            for (const each of value)
-                address += `/${encodedSegment(pattern, segment.name, each)}`
-            continue
-        }
-        address += `/${encodedSegment(pattern, segment.name, value)}`
-    }
-    if (address === '') address = '/'
-    address = mounted(address)
+    const address = mounted(
+        filledPath(pattern ?? '/', params, `url('${pattern}')`),
+    )
     // 30.6 — the query half, last, in the spelling `rpcRequest` writes.
     const search =
         query === undefined
@@ -118,23 +98,3 @@ export function url<P extends RouteLiteral>(
               : queryText(query)
     return search === '' ? address : `${address}?${search}`
 }
-
-/**
- * A param value encoded as one path segment; `.` and `..` are refused.
- *
- * 30.19 — A VALUE OF `.` OR `..` HAS NO SPELLING AS A SEGMENT: the URL parser collapses it as a
- * dot-segment, and `%2E` / `%2E%2E` with it, so the address would land on another route. Refused
- * rather than written, as a missing required segment is (30.3).
- */
-function encodedSegment(
-    pattern: string | undefined,
-    name: string,
-    value: unknown,
-): string {
-    const text = String(value)
-    if (text === '.' || text === '..')
-        throw new Error(
-            `abide: url('${pattern}') was given '${text}' for '${name}', and no address carries it as a segment — the URL parser resolves it to another route. RULEBOOK 30.19.`,
-        )
-    return encodeURIComponent(text)
-}

package/src/shared/writePath.ts

@@ -4,7 +4,7 @@ import { putOwn } from './putOwn.ts'
  * A copy of `value` with `next` written at `path`, each level down the path copied.
  *
  * 31.8 — a write through a member path COPIES DOWN THE PATH AND THEN WRITES, and the copy is not
- * optimised away. The copy is the whole point: a `Reactive` wakes its readers on IDENTITY, so
+ * optimized away. The copy is the whole point: a `Reactive` wakes its readers on IDENTITY, so
  * `user.name = 'x'` done as a mutation of the held object writes the right value and wakes nobody
  * — the page renders correctly on load and then never moves again, with nothing about it saying
  * so.

package/src/ui/LAYER_NAMES.ts

@@ -2,7 +2,7 @@
 // code that EMITS the measure to the spec that reads it, and a string typed twice is a
 // `shares()` call that throws "found no measure named" against a layer that ran.
 //
-// `.` RATHER THAN `:`. `abide:hydrate` and `abide:navigate` are WARNING channels (28.9) and these
+// `.` RATHER THAN `:`. `abide:hydrate` and `abide:navigate` are WARNING channels (28.8) and these
 // are performance entries — two namespaces that would otherwise be one grep.
 //
 // ONE NAME PER OP SOMEBODY WAITS ON, never per row. `shares()` sums every measure of a layer

package/src/ui/List.ts

@@ -18,7 +18,7 @@ export class List {
     region: Region
     rows: Row[]
     /**
-     * The async iterable last started, or null — so a re-run with the same iterable is not a new
+     * The async iterable last started, or null — so a rerun with the same iterable is not a new
      * source.
      */
     pumping: unknown
@@ -209,8 +209,8 @@ function settleList(
  * async subject writes no rows inline and the region arrives empty. The pump fills it.
  */
 function appendRows(list: List, source: AsyncIterable<unknown>): void {
-    // A RE-RUN IS NOT A NEW SOURCE. The subject is read inside a watch, so any other reactive
-    // the expression touches re-runs it with the SAME iterable — and emptying the list to pump an
+    // A RERUN IS NOT A NEW SOURCE. The subject is read inside a watch, so any other reactive
+    // the expression touches reruns it with the SAME iterable — and emptying the list to pump an
     // async generator that has already run to completion left the region blank for good.
     if (list.pumping === source) return
     // A NEW SOURCE IS A NEW LIST. What the last one appended is stopped and removed, or its

package/src/ui/MOUNTING_LEVEL.ts

@@ -0,0 +1,18 @@
+// 39.1, 39.6 — THE ROUTER'S LEVEL BEING MOUNTED, set by the router around a page's or a layout's
+// setup and markup: a component mounted inside one adds its `<head>` to that level's
+// (`contributeHead`), and one mounted later — a row a list grew by — finds none and leaves the
+// document's head alone. `unapplied` is the head the components built on the client contributed
+// while it was set, which the router applies once it is unset rather than once a component.
+export const MOUNTING_LEVEL: {
+    current:
+        | {
+              head: (() => string) | undefined
+              /** Every component head joined to the level's own, in the order they mounted. */
+              contributed: (() => string)[] | undefined
+          }
+        | undefined
+    unapplied: string
+} = {
+    current: undefined,
+    unapplied: '',
+}

package/src/ui/Mismatch.ts

@@ -1,6 +1,6 @@
 import { namedLogger } from '#shared/log.ts'
 
-/** The browser lane's hydration logger (28.9). */
+/** The browser lane's hydration logger (28.8). */
 export const HYDRATE_LOG = namedLogger('abide:hydrate')
 
 /**

package/src/ui/RawRun.ts

@@ -11,7 +11,7 @@ import { removeUntil } from './regions.ts'
  *
  * `html` IS UNDEFINED FOR A RUN THE SERVER PAINTED. What is between the anchors is what the server
  * parsed from the same value, so the first write keeps it (`setMarkup`) the way a hydrated arm keeps
- * the arm it was painted with — reading markup back out of nodes is a serialisation, and not the
+ * the arm it was painted with — reading markup back out of nodes is a serialization, and not the
  * string the server wrote.
  */
 export class RawRun {