@abide/abide 0.123.2 → 0.124.0

package/src/shared/rpc.ts

@@ -14,7 +14,7 @@
 // handler's own.
 
 import { DERIVED_ARGS } from './DERIVED_ARGS.ts'
-import { type Failed, isFailedNamed } from './Failed.ts'
+import { type Failed, isFailed, isFailedNamed } from './Failed.ts'
 import { GLOBAL_GETS } from './GLOBAL_GETS.ts'
 import { HandlerRoute } from './HandlerRoute.ts'
 import { IN_PROCESS_ORIGIN } from './IN_PROCESS_ORIGIN.ts'
@@ -23,18 +23,18 @@ import { compose, type Rung } from './Middleware.ts'
 import { outbox, type QueuedCall, sendingFor } from './outbox.ts'
 import { principalRotated } from './principalRotated.ts'
 import {
+    acceptedArgs,
     contractOf,
     type Gated,
     gateOf,
+    type HeldToAnnotation,
     keyOf,
-    normalized,
 } from './reactive/argsContract.ts'
 import { callLoad } from './reactive/callLoad.ts'
 import {
     type AdoptedFailures,
     type AdoptedProduced,
     type ChunkOf,
-    chunksOfStream,
     handlerValue,
     isKeyed,
     type Kept,
@@ -45,14 +45,17 @@ import {
     type Refusals,
     type Shaping,
     STREAMING,
-    streamingOrSettled,
     type Streams,
 } from './reactive/index.ts'
 import { MUTATION } from './reactive/MUTATION.ts'
-import { dropAnswered } from './reactive/Reactive.ts'
+import {
+    chunksOfStream,
+    dropAnswered,
+    streamingOrSettled,
+} from './reactive/producer.ts'
 import { builtHere, isForwarder } from './reactive/scoped.ts'
 import { SELECTION_MEMBERS } from './reactive/SELECTION_MEMBERS.ts'
-import { checkArgs, validationError } from './refuse.ts'
+import { checkArgs } from './refuse.ts'
 import { RPC_SERVER } from './RPC_SERVER.ts'
 import { rpcRequest } from './rpcRequest.ts'
 import type { Schema } from './Schema.ts'
@@ -162,16 +165,6 @@ type Derived<Member, Whole = Member> = Member extends
           : never
       : never
 
-/**
- * 19.9 — the issues an `Rpc`'s args leave against the schema its annotation derives, `null` where
- * they hold: `undefined` until the module its handler is loaded through stamps it (`derivedArgs`),
- * and so in a browser always. A function rather than the schema, so this seam never carries the
- * validator (19.13).
- */
-export type HeldToAnnotation = {
-    [DERIVED_ARGS]: ((args: unknown) => Issues<unknown> | null) | undefined
-}
-
 /** Which generated surfaces carry a handler (20.1). */
 export type Clients = {
     ui?: boolean
@@ -453,12 +446,14 @@ export function declare(method: Method): Declare {
             return route
         }
         const call = (given?: unknown, options?: CallOptions): unknown => {
-            const args = normalized(contract, given)
-            // 15.8, 19.9 — AND HELD TO ITS ANNOTATION, where the build derived a schema off it: a
-            // type an in-process caller wrote holds nothing at run time (`as never`, a value off
-            // JSON), so the call is refused as the wire refuses it rather than handed to the body.
-            const issues = rpc[DERIVED_ARGS]?.(args) ?? null
-            if (issues !== null) return reactive(() => validationError(issues))
+            // 15.8, 19.9 — the args every way of calling the handler is held to.
+            let args: unknown
+            try {
+                args = acceptedArgs(rpc, given)
+            } catch (refused) {
+                if (!isFailed(refused)) throw refused
+                return reactive(() => refused)
+            }
             const route =
                 rpc.address === undefined ? undefined : routeAt(rpc.address)
             if (route?.segments !== undefined) {
@@ -539,14 +534,15 @@ export function declare(method: Method): Declare {
         }) satisfies Gated<unknown>
         const members = rpc as unknown as Record<string, unknown>
         // 7.10, 7.18 — A TRIGGER ON A SERVER REACHES EVERY BROWSER HOLDING WHAT IT NAMES, through the
-        // mux (18.3). `null` in a browser, where the trigger is the copy's own.
+        // mux (18.3). None follow in a browser, where the trigger is the copy's own.
         for (const name of SELECTION_MEMBERS) {
             if (name === 'busy') continue
             members[name] =
                 name === 'invalidate' || name === 'refresh'
                     ? (pattern?: unknown): unknown => {
                           const done = faceHere()[name](pattern)
-                          RPC_SERVER.broadcast?.(rpc, name, pattern)
+                          for (const followers of RPC_SERVER.following)
+                              followers.broadcast(rpc, name, pattern)
                           return done
                       }
                     : (pattern?: unknown): unknown => faceHere()[name](pattern)

package/src/shared/validateJson.ts

@@ -14,10 +14,9 @@
 // generated document carries them.
 
 import { isRecord } from './isRecord.ts'
+import { issuesOf, note } from './issueReport.ts'
 import type { Issues } from './Issues.ts'
-import { issuesOf } from './issuesOf.ts'
 import type { JsonValue } from './JsonValue.ts'
-import { note } from './note.ts'
 
 type Node = { [key: string]: JsonValue }
 

package/src/shared/writePath.ts

@@ -93,3 +93,32 @@ function copyOf(value: unknown, step: string | number): Level {
         return (typeof step === 'number' ? [] : {}) as unknown as Level
     return { ...(value as object) }
 }
+
+/**
+ * What `mutate` hands back, called on a copy of the array at `path` that `target` then holds.
+ *
+ * 31.9 — A MUTATOR IS A WRITE THROUGH ITS RECEIVER'S PATH. `tags.push(t)` run on the held array
+ * grows it in place, so the identity a reader wakes on never moves (31.8's failure, spelled as a
+ * call). The compiler lifts a call here only where the receiver's TYPE is an array, so a class's
+ * own `push` stays a call on the class. A level that is not plain data on the way (31.14), or a
+ * receiver that is not an array when the call runs, takes the call in place, waking nobody.
+ */
+export function mutatePath<Result>(
+    target: { (): unknown; set(value: unknown): unknown },
+    path: readonly (string | number)[],
+    mutate: (receiver: never) => Result,
+): Result {
+    const value = target()
+    let receiver = value
+    let plain = true
+    for (const step of path) {
+        plain &&= isPlain(receiver)
+        receiver = (receiver as Level | null | undefined)?.[step]
+    }
+    if (!plain) return mutate(receiver as never)
+    if (!Array.isArray(receiver)) return mutate(receiver as never)
+    const copy = receiver.slice()
+    const result = mutate(copy as never)
+    target.set(writePath(value, path, copy))
+    return result
+}

package/src/ui/ArmRegion.ts

@@ -88,10 +88,7 @@ export class ArmRegion {
 
     swap(next: unknown): void {
         const region = this.region
-        const filling =
-            this.at !== undefined ||
-            isEmptyRegion(region) ||
-            this.paintedOther(next)
+        const filling = this.fills(next)
         const arm = this.armOf(next)
         const scope = this.scope
         if (filling) {
@@ -102,6 +99,15 @@ export class ArmRegion {
         this.at = next
     }
 
+    /** Whether swapping in `next` fills the region rather than hydrating what the server painted. */
+    fills(next: unknown): boolean {
+        return (
+            this.at !== undefined ||
+            isEmptyRegion(this.region) ||
+            this.paintedOther(next)
+        )
+    }
+
     armOf(next: unknown): Arm {
         return (this.arms[next as number] as ArmMakers[number])(undefined)
     }

package/src/ui/Level.ts

@@ -1,7 +1,7 @@
 import {
     currentShare,
+    enterShare,
     leaveShare,
-    resumeShare,
     type ShareScope,
 } from '#shared/reactive/share.ts'
 import { untracked } from '#shared/reactive/tracking.ts'
@@ -14,18 +14,14 @@ import type { Scope } from './Scope.ts'
 /**
  * ONE LEVEL OF A ROUTED CHAIN — a layout or the page — and the head it contributes (39.1, 39.14).
  *
- * 41.11 — the router holds these rather than letting each level own the one below it, which is
- * what makes a shared layout something it can KEEP: a scope stopped from above takes its children
- * with it, and a layout that survives a navigation must not take the page it was holding a moment
- * ago. The module standing here is the router's `chain` at the same index.
+ * 41.11 — a `LevelChain` holds these rather than letting each level own the one below it.
  *
  * ON EVERY PAGE'S STATIC CLOSURE, because `contributeHead` is on the runtime barrel — so it knows
- * nothing of the router, and the router knows it only through `levels`.
+ * the chain it stands in only as what reconciles the head, and nothing of the router.
  */
 export class Level {
-    /** The chain this level stands in, and where: a live head yields to every level below it. */
-    levels: Level[]
-    at: number
+    /** The chain this level stands in: a live head yields to every level below it. */
+    chain: { reconcile(): void }
     scope: Scope | undefined = undefined
     /**
      * Where this level's `<slot/>` is, learned when the level below it mounted there, and
@@ -64,9 +60,8 @@ export class Level {
      */
     contributed = new Set<HeadContribution>()
 
-    constructor(levels: Level[], at: number) {
-        this.levels = levels
-        this.at = at
+    constructor(chain: { reconcile(): void }) {
+        this.chain = chain
     }
 
     /** Left by the level's mount (`emitClient`), painted or not. */
@@ -85,7 +80,7 @@ export class Level {
 
     /** Reconciles the document head from the chain this level stands in (`reconcileHead`). */
     reconcile(): void {
-        Level.reconcile(this.levels)
+        this.chain.reconcile()
     }
 
     /**
@@ -94,11 +89,11 @@ export class Level {
      * a head read here is followed by its own watch, not by whatever wrote.
      */
     static reconcile(levels: Level[]): void {
-        reconcileHead(untracked(Level.chain, levels, undefined))
+        reconcileHead(untracked(Level.contributors, levels, undefined))
     }
 
     /** Every contributor in `levels` and the head it reads now, outermost first. */
-    static chain(
+    static contributors(
         levels: Level[],
         _?: undefined,
     ): [who: object, text: string][] {
@@ -146,11 +141,7 @@ export class Level {
     mount<Result>(run: () => Result): Result {
         // 39.1 — THE LEVEL RIDES THE SHARE SCOPE, so a component finds it as it finds a shared key,
         // whether it mounts now or in an arm or a row after (`contributeHead`).
-        const back = resumeShare({
-            parent: currentShare(),
-            values: new Map(),
-            level: this,
-        })
+        const back = enterShare(this)
         this.unapplied = false
         let unapplied: boolean
         let result: Result

package/src/ui/LevelChain.ts

@@ -0,0 +1,272 @@
+import type { Params } from '#shared/matchRoute.ts'
+import type { ShareScope } from '#shared/reactive/share.ts'
+import { route } from '#shared/route.ts'
+import { setUpLevels } from '#shared/setUpLevels.ts'
+
+import { LAYER_MOUNT } from './LAYER_NAMES.ts'
+import { Level } from './Level.ts'
+import { beginLayer, endLayer } from './measureLayer.ts'
+import { fillRegion, type Region } from './regions.ts'
+import type { Scope, Stoppable } from './Scope.ts'
+
+/**
+ * A page's client mount, called against the region the router owns.
+ *
+ * The same default export a page already has — the router is a CALLER of a page exactly as a page
+ * is a caller of a component, which is why nothing about the emitted module changes to be routable.
+ */
+export type PageMount = (
+    root: Region,
+    props?: Record<string, unknown>,
+    // 39.6 — A LEVEL'S HEAD IS ITS OWN MOUNT'S TO APPLY, from inside the instance its slots read
+    // (`emitClient`), so the router hands the module a region and says it is the router by handing
+    // it the level it stands at — a file invoked as a component too is mounted without it, and
+    // applies no head a row. 39.14 — the level is where the mount leaves its head for the router
+    // to read when it withdraws.
+    routed?: Level,
+) => Scope
+
+export type PageModule = { default: PageMount }
+
+/**
+ * The routed chain standing in the document — its layouts outermost first and the page last — and
+ * the head they contribute (39.1, 39.14).
+ *
+ * 41.11 — THE CHAIN HOLDS ITS LEVELS rather than each level owning the one below it, which is what
+ * makes a shared layout something a navigation can KEEP: a scope stopped from above takes its
+ * children with it, and a layout that survives a navigation must not take the page it was holding.
+ *
+ * 39.14 — EVERY WAY A LEVEL LEAVES IS BRACKETED HERE: the head reconciled while the leaving levels
+ * still read what is on screen, so what the server painted for them is adopted as theirs, and again
+ * once they are gone — and a leaving level's contributions are cleared before its scope stops, or
+ * each component's `HeadContribution.stop` would withdraw and reconcile on its own.
+ */
+export class LevelChain {
+    /** The region the outermost level mounts into. */
+    private readonly root: Region
+    private readonly levels: Level[]
+    /**
+     * The modules the address resolved to, one per level.
+     *
+     * A kept layout's `<slot/>` mounts from it whenever its region opens — read at that moment
+     * rather than captured when the layout mounted, or a slot reopened after a navigation put back
+     * the page the reader had left.
+     */
+    private modules: PageModule[]
+
+    constructor(root: Region) {
+        this.root = root
+        this.levels = []
+        this.modules = []
+    }
+
+    /** How many levels stand. */
+    get depth(): number {
+        return this.levels.length
+    }
+
+    /** The scope of the level at `at` — negative counts from the page — or `undefined`. */
+    scopeAt(at: number): Scope | undefined {
+        return this.levels.at(at)?.scope
+    }
+
+    /** Reconciles the document head from every level standing (`Level.reconcile`). */
+    reconcile(): void {
+        Level.reconcile(this.levels)
+    }
+
+    /**
+     * How many levels of `arriving` are already standing.
+     *
+     * Layouts only: a page reached here is another route's, the same route's being followed instead
+     * (30.23). EVERY STANDING LEVEL IS COMPARED, the page included: a page is never a layout, so it
+     * cannot match one, and a layout whose slot is closed stands with nothing below it.
+     *
+     * By the MOUNT rather than by the loader or the module record: the table holds an arrow per
+     * row, so two routes under one layout name the same file through two different functions, and a
+     * table written by hand may answer with a fresh record each call.
+     */
+    sharedWith(arriving: PageModule[]): number {
+        const layouts = arriving.length - 1
+        let shared = 0
+        while (
+            shared < layouts &&
+            shared < this.levels.length &&
+            (this.modules[shared] as PageModule).default ===
+                (arriving[shared] as PageModule).default
+        )
+            shared += 1
+        return shared
+    }
+
+    /**
+     * Mounts `modules` from the top into the root region the server painted. No head is reconciled:
+     * a painted level's mount hydrates, and the head is the one the server wrote.
+     */
+    hydrate(modules: PageModule[]): void {
+        this.modules = modules
+        this.mountMeasured(0, this.root)
+    }
+
+    /**
+     * Keeps the first `kept` levels and mounts `modules` below them, reconciling the head around it.
+     *
+     * `between` runs once the leaving levels have stopped and their region is emptied, and before
+     * the arriving ones are set up — the address written and `route` moved, which a setup reads.
+     *
+     * The arriving part goes into the root where nothing is kept, and into the deepest kept layout's
+     * slot where something is — NOWHERE where that slot's region is closed: the slot mounts it off
+     * `modules` when it opens, and not into a region no longer in the document.
+     */
+    replace(kept: number, modules: PageModule[], between: () => void): void {
+        this.reconcile()
+        this.stopFrom(kept)
+        const into =
+            kept === 0 ? this.root : (this.levels[kept - 1] as Level).slot
+        // EMPTIED THROUGH THE PRIMITIVE EVERY OTHER REGION IS, which carries the 41.10 refusal for a
+        // region no longer in a document that a hand-written walk swallows.
+        if (into !== undefined) fillRegion(into)
+        between()
+        this.modules = modules
+        // 39.6 — each arriving level applies its own head as it mounts into its emptied region; a
+        // kept layout is not mounted again, so neither is its head.
+        if (into !== undefined) this.mountMeasured(kept, into)
+        // 39.14 — what the leaving levels keyed and the arriving ones did not goes back to the
+        // nearest kept layout's, else leaves; their keyless nodes leave with them (39.16).
+        this.reconcile()
+    }
+
+    /**
+     * AT THE TOP OF THE CHAIN, NOT INSIDE `mountFrom`: it recurses one level per layout, and
+     * `shares()` SUMS every measure of a name inside the op — so a pair inside the recursion would
+     * count the innermost level once per level above it.
+     */
+    private mountMeasured(from: number, into: Region): void {
+        beginLayer(LAYER_MOUNT)
+        try {
+            this.mountFrom(from, into)
+        } finally {
+            endLayer(LAYER_MOUNT)
+        }
+    }
+
+    /**
+     * Stops every level from `at` down, inside out, and drops them.
+     *
+     * Stopped from the INSIDE OUT, so a layout's disposers run after the page's — the order a
+     * scope's own teardown already has, and the one an author reading two `watch` cleanups in
+     * two files would expect.
+     */
+    private stopFrom(at: number): void {
+        for (let index = this.levels.length - 1; index >= at; index -= 1) {
+            const level = this.levels[index] as Level
+            // OUT OF THE CHAIN BEFORE IT STOPS, so a slot stop it fires on the way finds it gone
+            // (`release`) and leaves the head to whoever stopped it.
+            this.levels.length = index
+            // The level's head leaves whole, so none of its components withdraws its own.
+            level.contributed.clear()
+            level.scope?.stop()
+        }
+    }
+
+    /**
+     * Mounts the chain from level `at` into `region`, each level handed the next as `children`.
+     *
+     * 35.1 — each level is handed the one below it as `children` (32.18), so a layout puts the page
+     * in its `<slot/>` with the same mechanism a caller writing markup between two tags uses — and
+     * the chain learns where that slot is on the way past, which is what lets it swap the page
+     * there later without the layout knowing.
+     *
+     * THE CHILD'S SCOPE IS THE CHAIN'S, not the layout's, so a kept layout cannot stop the page
+     * arriving under it. What `mount` hands the layout is a stop for WHATEVER STANDS IN THE SLOT
+     * when the slot's region leaves — a `<slot/>` inside a closed `{#if}` — rather than for the
+     * page that happened to be mounted first. And the slot mounts from `modules`, so a slot that
+     * opens again mounts the page the address resolves to now.
+     */
+    private mountFrom(at: number, region: Region): void {
+        setUpLevels(
+            at,
+            this.modules.length,
+            this.levels[at - 1]?.share,
+            ROUTE_PROPS,
+            (below, props) => this.setUp(below, region, props),
+        )
+        this.markUp(at, region)
+    }
+
+    /**
+     * Runs level `at`'s setup over `props`, leaving its markup on the level for `markUp`, and
+     * answers the share scope the setup left.
+     */
+    private setUp(
+        at: number,
+        region: Region,
+        props: Record<string, (() => unknown) | undefined>,
+    ): ShareScope | null {
+        const module = this.modules[at] as PageModule
+        const level = new Level(this)
+        this.levels[at] = level
+        if (at < this.modules.length - 1)
+            props.children = () => ({
+                // NO BUILD, because the level below carries its own (32.17): a module a route
+                // reaches fills the region it is mounted against when that region is empty, so
+                // the build and the mount are one call rather than two.
+                build: undefined,
+                mount: (slot: Region): Stoppable => {
+                    // The level below as `mountFrom` set it up, the first time its slot opens; a
+                    // slot opening again sets it up afresh.
+                    const pending = this.levels[at + 1]?.markup !== undefined
+                    if (!pending) this.release(level, at)
+                    level.slot = slot
+                    if (pending) this.markUp(at + 1, slot)
+                    else this.mountFrom(at + 1, slot)
+                    return { stop: () => this.release(level, at) }
+                },
+            })
+        // The region a level's markup lands in is its slot above, known only once that markup
+        // runs; a module mounted by the chain leaves its markup rather than using this one.
+        // A deferred level answers the scope its setup made, so the watches that setup opened are
+        // stopped with the level even where its markup never runs — a slot that never opens.
+        level.scope = level.mount(() => module.default(region, props, level))
+        return level.share
+    }
+
+    /** Runs the markup level `at`'s setup left, into `region`. */
+    private markUp(at: number, region: Region): void {
+        const level = this.levels[at] as Level
+        const markup = level.markup
+        if (markup === undefined) return
+        level.markup = undefined
+        level.scope = level.mount(() => markup(region))
+    }
+
+    /**
+     * Stops what stands below `level` and forgets its slot.
+     *
+     * A no-op once the level itself has been replaced, which is how a stop handed to a layout that
+     * has since left does nothing.
+     */
+    private release(level: Level, at: number): void {
+        if (this.levels[at] !== level) return
+        level.slot = undefined
+        // 39.14, 39.16 — THE LEVELS BELOW LEAVE WITH THE SLOT'S REGION, and their head with them.
+        this.reconcile()
+        this.stopFrom(at + 1)
+        this.reconcile()
+    }
+}
+
+/**
+ * The props a routed page or layout is set up over, `children` aside: `params` as a live accessor.
+ *
+ * 33.4 — A PROP IS AN ACCESSOR. A page is mounted as any other component is, so its one prop is
+ * passed the way `renderComponent` passes a child's and the way `answerRequest` paints one: a
+ * function per key. Passed as the plain record it lowered to `params()` on a value that was not
+ * one, so every page with a `[param]` in its address hydrated dead — with its server markup
+ * already on screen, which is what kept it quiet.
+ *
+ * 33.5 — AND A LIVE ONE: `params` reads `route.params`, which every navigation writes. A layout
+ * kept across `/users/1` -> `/users/2` is not mounted again, so an accessor over the params it was
+ * mounted with went on answering user 1.
+ */
+const ROUTE_PROPS = { params: (): Params => route.params() }