@abide/abide 0.57.1 → 0.100.0

package/src/shared/Issues.ts

@@ -0,0 +1,49 @@
+// WHAT WAS WRONG, KEYED BY WHERE. The shape a `schema` refusal carries, and therefore the
+// `data` of a `ValidationError` (15.8).
+//
+// THE EMPTY KEY IS THE WHOLE VALUE. A refusal about the object itself — "these two fields
+// contradict each other" — has no field to hang off, and inventing a name for it would put
+// a string in the record that no path can ever match. `''` is the one key that cannot
+// collide with a path, because a path is built from property names and none of them is
+// empty.
+//
+// A NON-OBJECT IS A BARE LIST for the same reason: `Issues<string>` over a scalar has
+// nowhere to key by, and `{ '': string[] }` for that case is a wrapper every reader would
+// have to unwrap.
+
+type Down = [0, 0, 1, 2, 3, 4]
+
+/**
+ * Every dot-joined path into `T`, widened to `string` past five levels.
+ *
+ * 19.5: DOT-JOINED, DEPTH-LIMITED, AND WIDENED TO `string` PAST THE LIMIT. The limit is
+ * not a style choice — a recursive path type over a self-referential shape (a tree node
+ * whose children are tree nodes) expands forever, and TypeScript answers that with
+ * "excessively deep" on the whole file rather than on the type that caused it. Five levels
+ * is past anything a form posts and short enough that the expansion stays cheap.
+ *
+ * WIDENING RATHER THAN STOPPING is what keeps the deep case usable: past the limit any
+ * string is accepted as a path, so a deeply nested refusal can still be keyed — it just
+ * stops being checked. Stopping at `never` would make those keys unspellable.
+ *
+ * AN ARRAY INDEXES BY NUMBER rather than by its `length` and its methods, which is what
+ * `keyof` over an array would otherwise hand back.
+ */
+export type Paths<T, Limit extends number = 5> = Limit extends 0
+    ? string
+    : T extends readonly (infer Item)[]
+      ? `${number}` | `${number}.${Paths<Item, Down[Limit]>}`
+      : T extends object
+        ? {
+              [Key in keyof T & string]: T[Key] extends object
+                  ? Key | `${Key}.${Paths<T[Key], Down[Limit]>}`
+                  : Key
+          }[keyof T & string]
+        : never
+
+/**
+ * A refusal's messages keyed by path, `''` for the whole value, or a bare list over a scalar.
+ */
+export type Issues<T> = T extends object
+    ? Partial<Record<Paths<T> | '', string[]>>
+    : string[]

package/src/shared/JsonValue.ts

@@ -0,0 +1,18 @@
+/**
+ * What survives a wire unchanged.
+ *
+ * The bound on everything this design keys or transports: an `Args` (11.24), a refusal's `data`
+ * (15.6), a `JsonSchema` (19.7).
+ *
+ * A LEAF, and deliberately: it is reached from both seams and from the client entry's static
+ * closure, so an import of its own would be paid on every page by anything that took the type
+ * alone. Nothing here is emitted — a type-only module costs bytes only through what it imports,
+ * which is the rule this file is keeping.
+ */
+export type JsonValue =
+    | null
+    | boolean
+    | number
+    | string
+    | JsonValue[]
+    | { [key: string]: JsonValue }

package/src/shared/LOAD_SIGNAL.ts

@@ -0,0 +1,10 @@
+/**
+ * The abort signal of the call that is starting a load, while it starts.
+ *
+ * 16.49 — THE SIGNAL OF THE CALL THAT IS STARTING A LOAD, set around the reach and read by a
+ * transport's body as it starts: the browser's wire hands it to `fetch`, so a load every caller
+ * aborted ends its request too. A leaf, because `callLoad` sets it and the wire reads it.
+ */
+export const LOAD_SIGNAL: { current: AbortSignal | undefined } = {
+    current: undefined,
+}

package/src/shared/MOUNT_META.ts

@@ -0,0 +1,6 @@
+/**
+ * The `<meta>` the server writes the app's mount into, and a browser reads it back from.
+ *
+ * 16.10, 36.11.
+ */
+export const MOUNT_META = 'abide-mount'

package/src/shared/Middleware.ts

@@ -0,0 +1,34 @@
+// ONE RUNG OF AN ONION, and the onion. The app lane's `middleware` (37.3) and a handler's rungs
+// (16.11) are the same shape over a different `Ctx`, so they compose through the one function.
+
+export type Middleware<Ctx, Result> = (
+    next: (ctx?: Ctx) => Promise<Result>,
+    ctx: Ctx,
+) => Result | Promise<Result>
+
+/**
+ * Composes rungs around a terminal handler into one function, outermost rung first.
+ *
+ * 16.14 — COMPOSED ONCE, where the table is built, rather than folded per call. 16.15 — each link
+ * holds its rung and the link inside it, and nothing about the request it will be handed. 16.16 —
+ * a rung that never calls `next` answers in the handler's place. 16.21 — a throw is not caught
+ * here, so it leaves the whole onion rather than unwinding through the rungs outside it.
+ *
+ * `next()` with no argument hands the inner link the ctx this rung was given.
+ */
+export function compose<Ctx, Result>(
+    rungs: readonly Middleware<Ctx, Result>[],
+    terminal: (ctx: Ctx) => Promise<Result>,
+): (ctx: Ctx) => Promise<Result> {
+    let link = terminal
+    for (let at = rungs.length - 1; at >= 0; at -= 1)
+        link = linkOf(rungs[at] as Middleware<Ctx, Result>, link)
+    return link
+}
+
+function linkOf<Ctx, Result>(
+    rung: Middleware<Ctx, Result>,
+    inner: (ctx: Ctx) => Promise<Result>,
+): (ctx: Ctx) => Promise<Result> {
+    return async (ctx) => rung((given) => inner(given ?? ctx), ctx)
+}

package/src/shared/NAVIGATION_HEADER.ts

@@ -0,0 +1,7 @@
+/**
+ * The header marking a request as the client router asking whether it may navigate.
+ *
+ * 30.15 — the server answers it without rendering (30.16). A leaf because the router writes it and
+ * the server reads it.
+ */
+export const NAVIGATION_HEADER = 'abide-navigation'

package/src/shared/PRINCIPAL_HEADER.ts

@@ -0,0 +1,6 @@
+/**
+ * The header an answer carries where its handler signed the caller in or out.
+ *
+ * A leaf because the server writes it and a browser's fetch reads it.
+ */
+export const PRINCIPAL_HEADER = 'abide-principal'

package/src/shared/RPC_SERVER.ts

@@ -0,0 +1,67 @@
+/**
+ * What an `Rpc` asks of the server it runs on, as slots the server fills.
+ *
+ * Filled by `#server/installServer.ts`, and `raw` by `bootApp`: the request a rung is handed (16.11),
+ * the app a `raw` call is answered by in process (16.42), and where a call reports the value it
+ * reached, so a page's render can leave it for the browser's own call (41.13). A leaf, for
+ * `CURRENT_ROUTER`'s reason: the isomorphic `Rpc` reads these and a browser bundle must not reach
+ * what fills them.
+ */
+export const RPC_SERVER: {
+    request: () => Request
+    raw: ((request: Request) => Promise<Response>) | null
+    reached: ((rpc: object, args: unknown, value: unknown) => void) | null
+    /**
+     * `ABIDE_RPC_TIMEOUT`, the `timeout` of a handler that names none.
+     *
+     * 16.58.
+     */
+    timeout: () => number | undefined
+    /**
+     * A trigger on an `Rpc`, sent to every browser following what its pattern names.
+     *
+     * 7.10, 7.18.
+     */
+    broadcast:
+        | ((
+              rpc: object,
+              member: 'invalidate' | 'refresh',
+              pattern: unknown,
+          ) => void)
+        | null
+    /**
+     * A free trigger, sent to every followed copy carrying one of `tags`, or to every one where
+     * `tags` is `null`.
+     *
+     * 13.15.
+     */
+    swept:
+        | ((member: 'invalidate' | 'refresh', tags: string[] | null) => void)
+        | null
+    /**
+     * The `global` entry an answer came from.
+     *
+     * 18.8 — so a follower subscribed before it existed, or fed from one since evicted, is fed
+     * from this one.
+     */
+    served: ((rpc: object, serving: unknown) => void) | null
+    /**
+     * How long a handler's own body took inside its rungs.
+     *
+     * 21.20 — so the answer can tell the two apart.
+     */
+    handled: ((rpc: object, duration: number) => void) | null
+} = {
+    request: () => {
+        throw new Error(
+            'abide: a handler with middleware was called outside a request, and its rungs read the request being served. RULEBOOK 16.25.',
+        )
+    },
+    raw: null,
+    reached: null,
+    timeout: () => undefined,
+    broadcast: null,
+    swept: null,
+    served: null,
+    handled: null,
+}

package/src/shared/Raw.ts

@@ -0,0 +1,90 @@
+import { RAW_CLOSE, RAW_OPEN } from './ANCHORS.ts'
+
+/**
+ * The brand `raw` hands back: markup a slot writes unescaped.
+ *
+ * 32.24 — the value `raw` hands back, and the brand a slot reads to know not to escape it. In
+ * #shared because both sides render: the server writes the markup and a client swapping a `{#if}`
+ * branch re-renders that region, so one brand has to be readable from both.
+ *
+ * A CLASS RATHER THAN A TAGGED RECORD, for what the READ costs. `value instanceof Raw` lands on
+ * the per-slot escape path, and for the string or number every other slot carries it is rejected
+ * on the operand's type before any prototype is walked — one branch, no property load. A probe
+ * (`value.__raw === true`) is a dynamic property access on that same path, which is what
+ * CLAUDE.md's hot-path rule refuses; a `Symbol` key is the same access spelled differently, and
+ * it is also megamorphic here, the slot seeing a different hidden class on every row.
+ *
+ * WHAT IT COSTS IS UNDER THE NOISE FLOOR, and that is measured rather than asserted: two arms of
+ * `escapeText` differing only in this line, 200,000 calls a sample on a clean 46-character slot,
+ * reported 1.13x then 0.90x over two runs of one process and 1.13x then 0.93x over a second
+ * process. THE ARMS SWAP PLACES, which is the answer — the whole call is ~15 ns and the same arm
+ * moves 8% between its own runs.
+ *
+ * STRINGIFIED AT THE BRAND rather than at the slot, so the escape path's fast return is one
+ * field read and the shape is fixed at construction.
+ */
+export class Raw {
+    html: string
+
+    constructor(html: string) {
+        this.html = html
+    }
+}
+
+/**
+ * A slot value as text: a `Raw`'s html, and nothing for an absent value.
+ *
+ * `String(value)` on a `Raw` is `[object Object]`.
+ */
+export function textOf(value: unknown): string {
+    if (value instanceof Raw) return value.html
+    return value == null ? '' : String(value)
+}
+
+/**
+ * Brands a value's text as markup to render unescaped.
+ *
+ * 32.2, 32.25 — the one mechanism. `{raw(x)}` lowers to this call and an imported `raw` IS this
+ * call, so a value branded in a `<script>` and a value branded in a slot are the same object.
+ */
+export function raw(value: unknown): Raw {
+    return new Raw(textOf(value))
+}
+
+/**
+ * Whether a value is the brand.
+ *
+ * For the places that have to ask rather than just read it: a run the browser builds or binds is
+ * a text node unless one of its values is `Raw` (`emitClient`).
+ */
+export function isRaw(value: unknown): value is Raw {
+    return value instanceof Raw
+}
+
+/**
+ * How many `Raw` parts the text escaper has ever written.
+ *
+ * The one thing a run's markup cannot say about itself once it is a string. `escapeText` counts a
+ * `Raw` as it hands its html back, so a run read the count before its parts were escaped and
+ * compares after: moved means a part was markup, and the run is anchored (`markupRun`). A counter
+ * rather than a flag because a flag has to be reset, and a reset inside a part's own evaluation
+ * would hide the part before it.
+ *
+ * NEVER RESET, and what that lets through is stated: a part whose EVALUATION escaped a `Raw` it did
+ * not return anchors a run that holds text. The client reads that as a run holding markup whose
+ * value is text, and its first write puts the text node back — one node, never a wrong page.
+ */
+export const RAW_WRITES = { count: 0 }
+
+/**
+ * A run's markup, wrapped in the `RAW_OPEN` / `RAW_CLOSE` anchors when a `Raw` part was written since `before`.
+ *
+ * 32.30 — A RUN HOLDING MARKUP IS ANCHORED, and one holding text is written as it always was. What
+ * the server writes and what a browser parses for a row or an arm, so the walk that finds a run
+ * (`runHere`) reads the same thing either way.
+ */
+export function markupRun(before: number, markup: string): string {
+    return RAW_WRITES.count === before
+        ? markup
+        : `<!--${RAW_OPEN}-->${markup}<!--${RAW_CLOSE}-->`
+}

package/src/shared/Schema.ts

@@ -0,0 +1,229 @@
+// THE TWO FORMS A SHAPE MAY BE DECLARED IN, and one place that runs them. RULEBOOK 4.3
+// puts a schema first on every way in, so this is reached from a write, a publish, a body's
+// production (11.46) and an adoption (11.47) alike — one statement of what "the schema
+// refused" means, rather than four that drift apart.
+//
+// 19.2 IS WHAT MAKES THE FORMS ONE THING: a `Schema` returns what it ACCEPTS. Not a
+// boolean, not a report — the value, so the pipeline downstream of it (4.4, `transform`)
+// receives something already checked and already typed. A form that could only answer
+// yes/no would leave the value untyped on the other side.
+//
+// 19.6 IS THE OTHER HALF: coercion belongs to the pipeline and is never asked of a schema.
+// Together they are what lets 19.3 be enforced at all — see `runSchema`.
+
+import type { Issues } from './Issues.ts'
+import { issuesOf } from './issuesOf.ts'
+import { note } from './note.ts'
+import { isThenable } from './reactive/isThenable.ts'
+import { untracked } from './reactive/tracking.ts'
+
+/**
+ * What a Standard Schema's `validate` answers: the value, or its issues.
+ *
+ * The Standard Schema contract, declared here rather than depended on: it is an interface
+ * a library implements, so an import would put a package in this seam's graph to gain a
+ * shape that is fifteen lines. CLAUDE.md prices an import edge by the module it lands on,
+ * and this one lands on every page.
+ *
+ * NOT EXPORTED. `StandardSchemaV1` is the name a library implements and the one an app
+ * annotates with; this is the shape of what its `validate` answers, and exporting it would
+ * put a second name on the barrel that nothing resolves through — public surface by
+ * accident rather than by decision.
+ */
+type StandardResult<Output> =
+    | { readonly value: Output; readonly issues?: undefined }
+    | {
+          readonly issues: readonly {
+              readonly message: string
+              /**
+               * Where the issue stands: property keys, or `{ key }` steps.
+               *
+               * `| undefined` IS THE SPEC'S, and with `exactOptionalPropertyTypes` it is not
+               * implied by the `?`: without it no library that spells the spec's own type —
+               * zod among them — is a `Schema` at all.
+               */
+              readonly path?:
+                  | readonly (PropertyKey | { readonly key: PropertyKey })[]
+                  | undefined
+          }[]
+      }
+
+export type StandardSchemaV1<Output = unknown> = {
+    readonly '~standard': {
+        readonly version: 1
+        readonly vendor: string
+        readonly validate: (
+            value: unknown,
+        ) => StandardResult<Output> | PromiseLike<StandardResult<Output>>
+    }
+}
+
+/**
+ * A shape a value is checked against: a function returning what it accepts, or a Standard Schema.
+ *
+ * A JSON Schema document is the Standard form once `jsonSchema` wraps it — see that module for
+ * why the document does not stand here on its own.
+ */
+export type Schema<T> = ((value: unknown) => T) | StandardSchemaV1<T>
+
+/**
+ * What running a schema found: the accepted value, or its issues by path.
+ *
+ * ISSUES RATHER THAN A REFUSAL, and that is what keeps this module out of a cycle: a
+ * `validationError` is built by `refuse`, `refuse` runs a schema (15.11), and the two
+ * importing each other is an edge a bundler has to break. What a schema knows is WHAT WAS
+ * WRONG AND WHERE; turning that into a named refusal at 422 (15.8) is the caller's, and
+ * the caller is the one place that knows whether this was a write, a publish or a body.
+ */
+export type Checked = { value: unknown; issues: Issues<Found> | null }
+
+function accepted(value: unknown): Checked {
+    return { value, issues: null }
+}
+
+/**
+ * The `T` a schema's issues are typed against: any record, or any value that is not one.
+ *
+ * A UNION OF BOTH ARMS rather than `unknown`: `Issues<T>` decides by a `T` the runtime no longer
+ * has, and `unknown` is not an object, so `Issues<unknown>` types every record as a list. Over
+ * this union it distributes to the record or the bare list — which of the two a refusal holds
+ * is `issuesOf`'s, decided by the value refused.
+ */
+export type Found = Record<string, unknown> | string | number | boolean | null
+
+function refusedAs(found: Record<string, string[]>, value: unknown): Checked {
+    return { value: undefined, issues: issuesOf(found, value) as Issues<Found> }
+}
+
+/**
+ * A throw from a schema, as the `''` issue entry.
+ *
+ * 19.4: the plain-function form throws what it refuses, and the throw becomes the `''`
+ * entry — the key for "about the value itself", which is all a bare throw can say. Over a
+ * value that is not an object the entry IS the issues: `Issues<T>` is the bare list there.
+ */
+function fromThrow(thrown: unknown, value: unknown): Checked {
+    const said =
+        thrown instanceof Error
+            ? thrown.message
+            : typeof thrown === 'string'
+              ? thrown
+              : 'was refused'
+    // EVERY THROW BECOMES THE `''` ENTRY, a `Failed` included — 19.4 says so without
+    // carving one out, and the carve-out was worth trying and dropping: a schema that
+    // throws a named refusal reads as though the name should survive, but then a `schema`
+    // and a `transform` refuse in two different shapes and 4.4's pipeline has two kinds of
+    // stop in it. A `transform` is where a named refusal belongs (4.6).
+    return refusedAs({ '': [said] }, value)
+}
+
+/** A Standard Schema issue's path as a dotted key — 19.5's `''` where it has none. */
+function pathOf(
+    path: readonly (PropertyKey | { readonly key: PropertyKey })[] | undefined,
+): string {
+    if (path === undefined || path.length === 0) return ''
+    const parts: string[] = []
+    for (const step of path) {
+        const key =
+            step !== null && typeof step === 'object' && 'key' in step
+                ? step.key
+                : step
+        parts.push(String(key))
+    }
+    return parts.join('.')
+}
+
+/**
+ * Runs a schema of either form, untracked, and reports what it accepted or found.
+ *
+ * 4.7 — A SCHEMA RUNS UNTRACKED, and the clearing is HERE because running one is what the clause
+ * is about. Held in the two callers `Reactive.ts` owns, `refuse.named`'s gate and `Keyed`'s
+ * argument gate ran tracked: a refusal built inside an effect subscribed that effect to whatever
+ * its schema read, and the read was spliced into the body's cursor-ordered `sources` besides.
+ */
+export function runSchema(schema: unknown, value: unknown): Checked {
+    return untracked(runSchemaTracked, schema, value)
+}
+
+function runSchemaTracked(schema: unknown, value: unknown): Checked {
+    if (typeof schema === 'function') {
+        let returned: unknown
+        try {
+            returned = (schema as (value: unknown) => unknown)(value)
+        } catch (thrown) {
+            return fromThrow(thrown, value)
+        }
+        // 19.3: A PREDICATE IS NOT A `Schema`, and this is where it is caught rather than
+        // in the type — `Schema<boolean>` and a predicate are the same function type, so
+        // no annotation can separate them. What separates them at runtime is 19.2 plus
+        // 19.6: a schema returns what it ACCEPTS and never coerces, so a function handed a
+        // non-boolean and answering a boolean has answered a QUESTION about the value
+        // rather than returning it. A real `Schema<boolean>` only ever sees booleans.
+        if (typeof returned === 'boolean' && typeof value !== 'boolean')
+            throw new Error(
+                'A predicate is not a Schema: it answered true/false where the value was expected. A Schema returns what it accepts (RULEBOOK 19.2) and throws what it refuses (19.4).',
+            )
+        return accepted(returned)
+    }
+
+    if (schema !== null && typeof schema === 'object') {
+        const standard = (schema as Partial<StandardSchemaV1>)['~standard']
+        if (standard !== undefined) return runStandard(standard, value)
+    }
+
+    // 19.14: A BARE DOCUMENT IS REFUSED, never accepted. Accepting would be a declared constraint
+    // that silently does not apply — `validateJson`'s own header calls that the one failure a
+    // validation layer must not have — and the sentence reaches the author the way every other
+    // bad schema does, on the `''` entry.
+    return fromThrow(
+        new Error(
+            'A JSON Schema document is not a Schema on its own: wrap it as `jsonSchema(document)`, which brings the validator that reads it (RULEBOOK 19.14).',
+        ),
+        value,
+    )
+}
+
+function runStandard(
+    standard: StandardSchemaV1['~standard'],
+    value: unknown,
+): Checked {
+    let result: StandardResult<unknown> | PromiseLike<StandardResult<unknown>>
+    try {
+        result = standard.validate(value)
+    } catch (thrown) {
+        return fromThrow(thrown, value)
+    }
+    // 19.12: AN ASYNC SCHEMA IS REFUSED, and this is a decision rather than a gap. The
+    // machinery to await one exists and is not the obstacle — `absorb` already turns a
+    // write into a load (4.2), captures a `generation` and resumes the pipeline when the
+    // promise settles, so a second suspension point here would reuse it.
+    //
+    // WHAT IT WOULD COST IS THE MEANING OF A SYNCHRONOUS WRITE. `s.set(5); s()` answers 5
+    // today; behind an async gate it answers the value it held, because nothing has landed
+    // — and it would answer that way because of a GATE rather than because the app passed a
+    // load. `busy` moves with it: a settled write flips `loading` for a microtask, so a
+    // `{#if s.busy()}` spinner flickers on every keystroke of a bound input. Making a write
+    // asynchronous is the app's to ask for by passing a promise, not a schema's to impose.
+    // The `try` above covers the CALL, not what came back: an adapter answering `undefined` or
+    // `null` threw a TypeError off the `.then` probe, out of `runSchema` and into whatever called
+    // `s.set` — the one thing every other arm here turns into a refusal instead.
+    if (result === null || typeof result !== 'object')
+        return fromThrow(
+            new Error(
+                `The schema from "${standard.vendor}" answered ${result === null ? 'null' : typeof result}. A Standard Schema must answer a result object.`,
+            ),
+            value,
+        )
+    if (isThenable(result))
+        throw new Error(
+            `The schema from "${standard.vendor}" answered asynchronously. A Schema must be synchronous (RULEBOOK 19.12): validate what is already settled, or make the write a load by passing a promise.`,
+        )
+    const settled = result as StandardResult<unknown>
+    if (settled.issues === undefined) return accepted(settled.value)
+    // A path is built from the offending KEY, which for a record schema is the caller's — `note`
+    // is why `constructor` and `__proto__` land as members rather than as the prototype's.
+    const found: Record<string, string[]> = {}
+    for (const issue of settled.issues)
+        note(found, pathOf(issue.path), issue.message)
+    return refusedAs(found, value)
+}

package/src/shared/UNEXPECTED.ts

@@ -0,0 +1,11 @@
+/**
+ * Where the isomorphic core hands an unexpected error to `onError`, as a slot the server fills.
+ *
+ * 12.6 — filled by `#server/installServer.ts` with the `onError` hooks and nothing else: the core warns on
+ * its own namespace, so the lifecycle log is not written a second time. A leaf, for `RPC_SERVER`'s
+ * reason: the reactive core reports through it and a browser bundle must not reach what fills it.
+ * `null` in a browser, which has no `onError`.
+ */
+export const UNEXPECTED: { report: ((error: unknown) => void) | null } = {
+    report: null,
+}

package/src/shared/URL_ATTRIBUTES.ts

@@ -0,0 +1,19 @@
+/**
+ * The attributes a URL is written into, whose values are scheme-checked.
+ *
+ * 32.20 — THE ATTRIBUTES A URL IS WRITTEN INTO, which a value is scheme-checked on its way into —
+ * by name in the compiler, and through a spread at run time. A leaf, because both seams read it.
+ */
+export const URL_ATTRIBUTES: ReadonlySet<string> = new Set([
+    'href',
+    'xlink:href',
+    'src',
+    'action',
+    'formaction',
+    'poster',
+    'cite',
+    'ping',
+    'data',
+    'manifest',
+    'background',
+])

package/src/shared/VERSION_HEADER.ts

@@ -0,0 +1,6 @@
+/**
+ * The header a `GET`'s answer names its version in: the standard `ETag`, the version quoted.
+ *
+ * 18.5 — the server writes it and a browser's wire reads it, the early-call script included.
+ */
+export const VERSION_HEADER = 'etag'

package/src/shared/WORK.ts

@@ -0,0 +1,37 @@
+/**
+ * The three work counters the measurement lane reads, and the record they are published on.
+ *
+ * A leaf — no imports of its own — because both seams increment it and `harness/measure` reads it
+ * off `globalThis` rather than importing it: that lane may have no abide in its graph at all
+ * (44.1), so the two halves cannot share a declaration and the key is spelled on both sides.
+ *
+ * WHY ALL THREE OR NONE. `armCase()` zeroes every field it reads, so a field abide declares and
+ * never increments is created at 0 and read back at 0 — and every gate asserting it passes
+ * against a counter that was never wired (44.21). Publishing two of three is worse than
+ * publishing none, because the third looks measured.
+ *
+ * WHAT IT COSTS is one integer increment on the propagation walk and one per effect run, and it
+ * is UNDER THE NOISE FLOOR rather than priced: two runs of `bun run bench:reactive` put the
+ * largest consistent signal at +3.0% then +4.9% on fan-out-to-1000, against +0.0% then +7.1% on
+ * `read a settled value`, which has no counter anywhere near it. The floor is wider than every
+ * signal, so this is a trade taken deliberately and NOT a number — read it that way before
+ * widening the set.
+ */
+export const WORK = {
+    /**
+     * Effect body runs.
+     *
+     * A reader that woke when nothing it reads changed still reads the right value, which is why
+     * this is asserted and the value is not.
+     */
+    wakes: 0,
+    /** Compiled reactive slots that ran — incremented by the client runtime, not by the core. */
+    bindingRuns: 0,
+    /** Nodes visited by one propagation walk. */
+    descents: 0,
+}
+
+// The name is spelled here and again in `harness/measure`'s own leaf. Two copies on purpose: the
+// lane checks the SHAPE at the read rather than sharing a type, so a rename breaks a test rather
+// than silently publishing to a key nothing looks at.
+;(globalThis as unknown as Record<string, unknown>).__ABIDE_WORK__ = WORK

package/src/shared/anchorMarkup.ts

@@ -0,0 +1,15 @@
+import { REGION_CLOSE, REGION_OPEN } from './ANCHORS.ts'
+
+// The markup an anchor is WRITTEN as, for the server and the compiler. Never imported from the
+// client's closure: the browser reads an anchor as a comment's data and builds one with
+// `createComment`, so the comment syntax is only ever needed where markup is a string.
+
+/** An anchor's comment, from its data. */
+export function anchorMarkup(data: string): string {
+    return `<!--${data}-->`
+}
+
+/** `body` between a region's pair — a page (41.9), a component invocation (32.17). */
+export function regionMarkup(body: string): string {
+    return `${anchorMarkup(REGION_OPEN)}${body}${anchorMarkup(REGION_CLOSE)}`
+}