@texuli/spec 0.5.0 → 0.6.0

package/README.md

@@ -14,9 +14,14 @@ by Texuli's Kotlin Multiplatform twin. The package is framework-free: no
 DOM, no Svelte, no Node APIs and no runtime dependencies.
 
 > **Status: 0.x release.** Texuli is in development. The packages are
-> published to npm as `0.5.0`, a pre-1.0 release (1.0.0 will be the first
-> stable release). Under 0.x, a new minor (`0.6.0`) may contain breaking
-> changes, so pin the exact version or use `^0.5.0`, which accepts only 0.5.x.
+> published to npm as `0.6.0`, a pre-1.0 release (1.0.0 will be the first
+> stable release). Under 0.x, a new minor (`0.7.0`) may contain breaking
+> changes, so pin the exact version or use `^0.6.0`, which accepts only 0.6.x.
+
+> **New in `0.6.0`.** `@texuli/spec@0.6.0` carries **spec 0.6.0**: the
+> closed motion vocabulary (`@texuli/spec/motion`, below), and the new
+> `@texuli/spec/stream` subpath reads streamed blueprints. Every `0.5.0`
+> envelope migrates by stamping `spec`.
 
 > **New in `0.4.0`.** `@texuli/spec@0.4.0` carries **spec 0.4.0**: spec
 > 0.3.0 (state, bindings, closed actions, `reorder`, workflow graphs), spec
@@ -56,7 +61,7 @@ import {
   validateInstance,
 } from '@texuli/spec';
 
-SPEC_VERSION;                         // the spec version: '0.5.0' in @texuli/spec@0.5.0 ('0.4.0' in @texuli/spec@0.4.0)
+SPEC_VERSION;                         // the spec version: '0.6.0' in @texuli/spec@0.6.0
 SPEC_COMPONENT_IDS.includes('alert'); // true: the closed component vocabulary
 
 // The dialect validator: a closed subset of JSON Schema 2020-12.
@@ -88,7 +93,7 @@ import { type Schema, type SpecCatalog, validateBlueprint } from '@texuli/spec';
 import { migrateBlueprint } from '@texuli/spec/migrate';
 import { validateWorkflowGraph } from '@texuli/spec/workflow';
 
-const migrated = migrateBlueprint(blueprint); // 0.2.0 → 0.3.0 → 0.4.0 → 0.5.0; never throws
+const migrated = migrateBlueprint(blueprint); // 0.2.0 → … → 0.5.0 → 0.6.0; never throws
 const result = validateBlueprint(migrated.blueprint, {
   blueprintSchema: blueprintSchemaJson as Schema,
   catalog: componentsJson as SpecCatalog,
@@ -120,6 +125,8 @@ warning without failing.
 | `@texuli/spec/workflow` | Runtime, opt-in: workflow graph validation | `validateWorkflowGraph` (pass it in `SpecDocuments.validateWorkflowGraph`) |
 | `@texuli/spec/migrate` | Runtime, opt-in: envelope migrations | `migrateBlueprint`, `SPEC_MIGRATIONS`, `UNDECLARED_SPEC_VERSION` |
 | `@texuli/spec/surface` | Runtime: the state surface rules every validator shares (no imports) | `checkStateSurface`, `surfaceInputs`, `SPEC_CONTROL_STATE_TYPES`, `SURFACE_PLAYER_CODES`, `LIST_TEXT_PATTERN` |
+| `@texuli/spec/motion` | Runtime (new in `0.6.0`, spec `0.6.0`): the closed motion vocabulary and its check, shared by the catalog and the player ([motion.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/motion.md)) | `SPEC_MOTION_PRESETS`, `SPEC_MOTION_DURATIONS`, `SPEC_MOTION_STAGGERS`, `SPEC_MOTION_LEVELS`, `checkNodeMotion`, `checkEnvelopeMotion` |
+| `@texuli/spec/stream` | Runtime, opt-in (new in `0.6.0`): streamed blueprints ([stream.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/stream.md)) | `createJsonTokenizer`, `createBlueprintAssembler`, `createBlueprintStream`, `STREAM_NODE_ORDER` |
 | `@texuli/spec/codegen` | Build time: generation and conformance | `buildSpec`, `projectCatalog`, `checkConformance`, `checkCatalogContract`, `formatJson`, `nextSpecVersion`, `checkVersionHistory` |
 
 ## Key guarantees
@@ -148,6 +155,19 @@ warning without failing.
   component slides. The change is additive: every 0.3.0 envelope is a valid
   0.4.0 envelope, and the `0.3.0 → 0.4.0` migration only stamps `spec`. The
   deck model itself is validated by `@texuli/deck`, not by this package.
+- **Motion as data (spec 0.6.0, new in `0.6.0`).** A node may declare `motion`
+  (`enter` and `exit` presets `fade`, `rise`, `scale`, `slide-start` and
+  `slide-end`; `layout`; `stagger` and `duration` in token steps) and the
+  envelope a `motion.level` (`full`, `subtle`, `none`). Names map to the
+  motion tokens: a blueprint never carries CSS, keyframes, milliseconds or
+  code, and anything else is refused. The `0.5.0 → 0.6.0` migration only
+  stamps `spec`.
+- **Streams parse, never guess.** `@texuli/spec/stream` (new in `0.6.0`)
+  reads a blueprint split anywhere in linear time under a byte budget and a
+  depth cap, reports a node only once its shell (everything but
+  `children`) has closed, and refuses duplicate and prototype keys. It
+  judges no rule: the catalog checks each node, and the complete draft
+  goes through `validateDraft`.
 - **Structure only.** This validator checks structure. URL policy, tree
   limits and rendering live in the runtime validator of
   [`@texuli/catalog`](https://www.npmjs.com/package/@texuli/catalog). The
@@ -190,11 +210,14 @@ catalog hash, and from 0.3.0 may declare the exact spec version it was
 written for (`spec`; omitted means 0.2.0). `migrateBlueprint`
 (`@texuli/spec/migrate`) brings an
 envelope up to the current spec with pure, per-version steps
-(`src/migrations/`: `0.2.0 → 0.3.0`, `0.3.0 → 0.4.0` and `0.4.0 → 0.5.0`,
-each of which only stamps `spec`); a compatible version range is planned,
-not built. `@texuli/spec@0.5.0` carries spec `0.5.0`, which adds the
-`data-cohort-table`, `data-notification-inbox`, `data-filter-builder` and
-`time-field` catalog ids; `@texuli/spec@0.4.0` carried spec `0.4.0` (digest
+(`src/migrations/`: `0.2.0 → 0.3.0`, `0.3.0 → 0.4.0`, `0.4.0 → 0.5.0` and
+`0.5.0 → 0.6.0`, each of which only stamps `spec`); a compatible version range is planned,
+not built. `@texuli/spec@0.6.0` carries spec `0.6.0` (digest
+`37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc`), which
+adds the closed motion vocabulary (ADR-012); `@texuli/spec@0.5.0` carried
+spec `0.5.0`, which added the `data-cohort-table`,
+`data-notification-inbox`, `data-filter-builder` and `time-field` catalog
+ids, and `@texuli/spec@0.4.0` spec `0.4.0` (digest
 `fac29f542b16ddb78ab401c508e5b8346f655991c56e25aa811f4931661a8cb3`). Every
 pin is in `versions.json`.
 
@@ -211,6 +234,10 @@ conformance harness) are in
   [packages/spec](https://github.com/DailybotHQ/texuli/tree/main/packages/spec)
 - The contract in depth (the JSON Schema dialect, projections, conformance
   and versioning): [contract.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/contract.md)
+- The motion vocabulary (spec 0.6.0):
+  [motion.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/motion.md)
+- Streamed blueprints (the incremental tokenizer, the canonical order and
+  node shells; new in `0.6.0`): [stream.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/stream.md)
 - The Kotlin Multiplatform twin that consumes the generated models:
   [native/README.md](https://github.com/DailybotHQ/texuli/blob/main/native/README.md)
 - Architecture: [ARCHITECTURE.md](https://github.com/DailybotHQ/texuli/blob/main/docs/ARCHITECTURE.md)

package/dist/generated/typescript/blueprint.d.ts

@@ -47,7 +47,10 @@ export interface BlueprintEditOp {
     tree?: BlueprintNode;
 }
 export type BlueprintNodePath = readonly number[];
-/** One catalog node: id, props, children (each with an optional named slot), when, bind and on. */
+/**
+ * One catalog node: id, props, children (each with an optional named slot), when, bind, on and
+ * motion.
+ */
 export interface BlueprintNode {
     /** A catalog component id. */
     id: string;
@@ -63,6 +66,7 @@ export interface BlueprintNode {
     /** Two-way bindings: a prop the component lists as bindable → a $state binding it writes back. */
     bind?: Readonly<Record<string, BlueprintBinding>>;
     on?: BlueprintEventMap;
+    motion?: BlueprintNodeMotion;
 }
 /**
  * Shows the node when true (audit G07): the closed Condition AST of the blocks formula grammar.
@@ -185,11 +189,47 @@ export interface BlueprintReorder {
     pull?: 'move' | 'clone' | 'none';
     disabled?: boolean;
 }
+/**
+ * A closed motion preset (ADR-013): fade, rise (fade in from the block end), scale (fade and grow
+ * from 96%), slide-start or slide-end (fade in from the inline start or end, mirrored right to
+ * left). The runtime maps each to token keyframes; a blueprint never carries keyframes.
+ */
+export type BlueprintMotionPreset = 'fade' | 'rise' | 'scale' | 'slide-start' | 'slide-end';
+/** A duration token step (@texuli/tokens motion durations), never milliseconds. */
+export type BlueprintMotionDuration = 'fast' | 'base' | 'slow';
+/**
+ * The offset between the entering children of this node, in token steps: none, fast or base. The
+ * runtime caps the whole spread.
+ */
+export type BlueprintMotionStagger = 'none' | 'fast' | 'base';
+/**
+ * A motion ceiling (ADR-013): full, subtle (shorter, no travel or scale) or none (instant). The
+ * host and the reader's reduced-motion preference can only lower it.
+ */
+export type BlueprintMotionLevel = 'full' | 'subtle' | 'none';
+/**
+ * How a node moves (spec 0.6.0, ADR-012): named presets and token steps only. Nothing here is CSS,
+ * a duration in milliseconds or code. The server paints the end state, and nothing plays on
+ * hydration or under reduced motion.
+ */
+export interface BlueprintNodeMotion {
+    enter?: BlueprintMotionPreset;
+    exit?: BlueprintMotionPreset;
+    /** Animate a change of this node's position or size among its siblings (FLIP). */
+    layout?: boolean;
+    stagger?: BlueprintMotionStagger;
+    duration?: BlueprintMotionDuration;
+}
+/** The blueprint's motion settings (spec 0.6.0): the level every node motion plays at. */
+export interface BlueprintEnvelopeMotion {
+    level: BlueprintMotionLevel;
+}
 /**
  * Envelope version 1 around one catalog tree (ADR-004, audit G13). Mirrors what
  * @texuli/catalog/envelope reads; a declared status, activation or tier is display data, never
  * authority. Spec 0.4.0 (ADR-008 + PLAN_008 deck encoding) adds an optional spec version, local
- * state and a flow. Planned minor additions: the native profile and several roots.
+ * state and a flow; spec 0.6.0 (ADR-012, ADR-013) adds the closed motion vocabulary: a node motion
+ * and the envelope motion level. Planned minor additions: the native profile and several roots.
  */
 export interface BlueprintEnvelope {
     format: 'texuli-blueprint';
@@ -213,11 +253,12 @@ export interface BlueprintEnvelope {
     /**
      * The spec version the envelope was written for. Omitted means 0.2.0; migrateBlueprint stamps it.
      */
-    spec?: '0.3.0' | '0.4.0' | '0.5.0';
+    spec?: '0.3.0' | '0.4.0' | '0.5.0' | '0.6.0';
     /**
      * Local state declarations (ADR-008), at most 64. Names, counts and per-type rules are checked by
      * the validator.
      */
     state?: Readonly<Record<string, BlueprintStateDeclaration>>;
     flow?: BlueprintFlow;
+    motion?: BlueprintEnvelopeMotion;
 }

package/dist/generated/typescript/blueprint.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/blueprint.schema.json. Do not edit: run the spec generator.
-// Spec 0.5.0, digest 1ba15e8b082f68140c4b2768b8fd69c9f760e655dd117fac756f356a71525b2d
+// Spec 0.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
 export {};

package/dist/generated/typescript/catalog-schema.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/catalog.schema.json. Do not edit: run the spec generator.
-// Spec 0.5.0, digest 1ba15e8b082f68140c4b2768b8fd69c9f760e655dd117fac756f356a71525b2d
+// Spec 0.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
 export {};

package/dist/generated/typescript/diagnostics.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/diagnostics.schema.json. Do not edit: run the spec generator.
-// Spec 0.5.0, digest 1ba15e8b082f68140c4b2768b8fd69c9f760e655dd117fac756f356a71525b2d
+// Spec 0.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
 export {};

package/dist/generated/typescript/manifest.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/manifest.schema.json. Do not edit: run the spec generator.
-// Spec 0.5.0, digest 1ba15e8b082f68140c4b2768b8fd69c9f760e655dd117fac756f356a71525b2d
+// Spec 0.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
 export {};

package/dist/generated/typescript/vocabulary.js

@@ -1,5 +1,5 @@
 // Generated by @texuli/spec from catalog/components.json. Do not edit: run the spec generator.
-// Spec 0.5.0, digest 1ba15e8b082f68140c4b2768b8fd69c9f760e655dd117fac756f356a71525b2d
+// Spec 0.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
 /** The built catalog this vocabulary was projected from. */
 export const SPEC_CATALOG_HASH = '4ac7ecedd1c59d1999a9f7eea2f523c7653fececb97258a478f09253f6b6057f';
 /** Every closed component id, sorted. */

package/dist/generated/typescript/workflow.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/workflow.schema.json. Do not edit: run the spec generator.
-// Spec 0.5.0, digest 1ba15e8b082f68140c4b2768b8fd69c9f760e655dd117fac756f356a71525b2d
+// Spec 0.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
 export {};

package/dist/migrations/0.5.0-0.6.0.d.ts

@@ -0,0 +1,9 @@
+import type { SpecMigration } from './types.js';
+/**
+ * 0.5.0 → 0.6.0 is additive (PLAN_010 T-motion-spec, ADR-012 and ADR-013):
+ * nodes gain an optional closed `motion` (enter and exit presets, `layout`,
+ * `stagger` and `duration` in token steps) and the envelope an optional
+ * `motion.level`. Every 0.5.0 envelope is a valid 0.6.0 envelope, so the
+ * step only stamps `spec`.
+ */
+export declare const migration050to060: SpecMigration;

package/dist/migrations/0.5.0-0.6.0.js

@@ -0,0 +1,12 @@
+/**
+ * 0.5.0 → 0.6.0 is additive (PLAN_010 T-motion-spec, ADR-012 and ADR-013):
+ * nodes gain an optional closed `motion` (enter and exit presets, `layout`,
+ * `stagger` and `duration` in token steps) and the envelope an optional
+ * `motion.level`. Every 0.5.0 envelope is a valid 0.6.0 envelope, so the
+ * step only stamps `spec`.
+ */
+export const migration050to060 = Object.freeze({
+    from: '0.5.0',
+    to: '0.6.0',
+    migrate: (envelope) => ({ ...envelope, spec: '0.6.0' }),
+});

package/dist/migrations/index.js

@@ -3,6 +3,7 @@ import { SPEC_VERSION } from "../version.js";
 import { migration020to030 } from "./0.2.0-0.3.0.js";
 import { migration030to040 } from "./0.3.0-0.4.0.js";
 import { migration040to050 } from "./0.4.0-0.5.0.js";
+import { migration050to060 } from "./0.5.0-0.6.0.js";
 /** The version an envelope without `spec` was written for. */
 export const UNDECLARED_SPEC_VERSION = '0.2.0';
 /** Every step, in order; each `to` is the next step's `from`. */
@@ -10,6 +11,7 @@ export const SPEC_MIGRATIONS = Object.freeze([
     migration020to030,
     migration030to040,
     migration040to050,
+    migration050to060,
 ]);
 /**
  * Bring a blueprint envelope up to `target` (the current spec by default)

package/dist/motion.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@texuli/spec/motion` — the closed motion vocabulary of spec 0.6.0
+ * (ADR-012, ADR-013) in code, mirrored from `schemas/blueprint.schema.json`
+ * (`tests/spec.test.ts` asserts they stay equal), and the one structural
+ * check every runtime shares: `@texuli/catalog` refuses with it, and
+ * `@texuli/player` paints only what it accepted.
+ *
+ * Agents name presets and token steps. Nothing here is CSS, keyframes, a
+ * duration in milliseconds or code. No imports at runtime.
+ */
+import type { BlueprintEnvelopeMotion, BlueprintMotionDuration, BlueprintMotionLevel, BlueprintMotionPreset, BlueprintMotionStagger, BlueprintNodeMotion } from './generated/typescript/blueprint.js';
+export type { BlueprintEnvelopeMotion, BlueprintMotionDuration, BlueprintMotionLevel, BlueprintMotionPreset, BlueprintMotionStagger, BlueprintNodeMotion, };
+/** Enter and exit presets (`$defs.motionPreset`). */
+export declare const SPEC_MOTION_PRESETS: readonly BlueprintMotionPreset[];
+/** Duration token steps (`$defs.motionDuration`); `base` when omitted. */
+export declare const SPEC_MOTION_DURATIONS: readonly BlueprintMotionDuration[];
+/** Stagger token steps between entering children (`$defs.motionStagger`). */
+export declare const SPEC_MOTION_STAGGERS: readonly BlueprintMotionStagger[];
+/** Motion ceilings (`$defs.motionLevel`), highest first. */
+export declare const SPEC_MOTION_LEVELS: readonly BlueprintMotionLevel[];
+/** The fields a node `motion` takes (`$defs.nodeMotion`). */
+export declare const SPEC_NODE_MOTION_FIELDS: readonly string[];
+export type SpecMotionCheck<T> = {
+    ok: true;
+    motion: Readonly<T>;
+}
+/** `path` is relative to the motion value (`""`, `.enter` …). */
+ | {
+    ok: false;
+    path: string;
+    message: string;
+};
+/**
+ * Check a node `motion` against the closed vocabulary. Returns a frozen
+ * copy with only the known fields, or the first refusal. Linear in the
+ * number of keys, and it stops at the first unknown one.
+ */
+export declare function checkNodeMotion(value: unknown): SpecMotionCheck<BlueprintNodeMotion>;
+/** Check an envelope `motion` (`{ level }`). Returns a frozen copy, or the first refusal. */
+export declare function checkEnvelopeMotion(value: unknown): SpecMotionCheck<BlueprintEnvelopeMotion>;

package/dist/motion.js

@@ -0,0 +1,133 @@
+/**
+ * `@texuli/spec/motion` — the closed motion vocabulary of spec 0.6.0
+ * (ADR-012, ADR-013) in code, mirrored from `schemas/blueprint.schema.json`
+ * (`tests/spec.test.ts` asserts they stay equal), and the one structural
+ * check every runtime shares: `@texuli/catalog` refuses with it, and
+ * `@texuli/player` paints only what it accepted.
+ *
+ * Agents name presets and token steps. Nothing here is CSS, keyframes, a
+ * duration in milliseconds or code. No imports at runtime.
+ */
+/** Enter and exit presets (`$defs.motionPreset`). */
+export const SPEC_MOTION_PRESETS = Object.freeze([
+    'fade',
+    'rise',
+    'scale',
+    'slide-start',
+    'slide-end',
+]);
+/** Duration token steps (`$defs.motionDuration`); `base` when omitted. */
+export const SPEC_MOTION_DURATIONS = Object.freeze([
+    'fast',
+    'base',
+    'slow',
+]);
+/** Stagger token steps between entering children (`$defs.motionStagger`). */
+export const SPEC_MOTION_STAGGERS = Object.freeze([
+    'none',
+    'fast',
+    'base',
+]);
+/** Motion ceilings (`$defs.motionLevel`), highest first. */
+export const SPEC_MOTION_LEVELS = Object.freeze([
+    'full',
+    'subtle',
+    'none',
+]);
+/** The fields a node `motion` takes (`$defs.nodeMotion`). */
+export const SPEC_NODE_MOTION_FIELDS = Object.freeze([
+    'enter',
+    'exit',
+    'layout',
+    'stagger',
+    'duration',
+]);
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** A short, single-line label for a refused value: never the value itself in full. */
+function describe(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value.slice(0, 24));
+    if (Array.isArray(value))
+        return 'an array';
+    return value === null ? 'null' : typeof value;
+}
+function oneOf(value, allowed, field) {
+    if (typeof value === 'string' && allowed.includes(value)) {
+        return { ok: true, value: value };
+    }
+    return {
+        ok: false,
+        path: `.${field}`,
+        message: `"${field}" must be one of ${allowed.join(', ')} (got ${describe(value)}).`,
+    };
+}
+/**
+ * Check a node `motion` against the closed vocabulary. Returns a frozen
+ * copy with only the known fields, or the first refusal. Linear in the
+ * number of keys, and it stops at the first unknown one.
+ */
+export function checkNodeMotion(value) {
+    if (!isRecord(value)) {
+        return { ok: false, path: '', message: `"motion" must be an object (got ${describe(value)}).` };
+    }
+    const out = {};
+    for (const key of Object.keys(value)) {
+        if (!SPEC_NODE_MOTION_FIELDS.includes(key)) {
+            return {
+                ok: false,
+                path: `.${key.slice(0, 32)}`,
+                message: `"motion" takes only ${SPEC_NODE_MOTION_FIELDS.join(', ')}; no CSS, keyframes or code.`,
+            };
+        }
+        const entry = value[key];
+        if (key === 'layout') {
+            if (typeof entry !== 'boolean') {
+                return {
+                    ok: false,
+                    path: '.layout',
+                    message: `"layout" must be a boolean (got ${describe(entry)}).`,
+                };
+            }
+            out.layout = entry;
+            continue;
+        }
+        if (key === 'enter' || key === 'exit') {
+            const checked = oneOf(entry, SPEC_MOTION_PRESETS, key);
+            if (!checked.ok)
+                return checked;
+            out[key] = checked.value;
+        }
+        else if (key === 'stagger') {
+            const checked = oneOf(entry, SPEC_MOTION_STAGGERS, key);
+            if (!checked.ok)
+                return checked;
+            out.stagger = checked.value;
+        }
+        else {
+            const checked = oneOf(entry, SPEC_MOTION_DURATIONS, key);
+            if (!checked.ok)
+                return checked;
+            out.duration = checked.value;
+        }
+    }
+    return { ok: true, motion: Object.freeze(out) };
+}
+/** Check an envelope `motion` (`{ level }`). Returns a frozen copy, or the first refusal. */
+export function checkEnvelopeMotion(value) {
+    if (!isRecord(value)) {
+        return { ok: false, path: '', message: `"motion" must be an object (got ${describe(value)}).` };
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== 'level') {
+            return {
+                ok: false,
+                path: `.${key.slice(0, 32)}`,
+                message: 'The envelope "motion" takes only "level".',
+            };
+        }
+    }
+    const level = oneOf(value.level, SPEC_MOTION_LEVELS, 'level');
+    if (!level.ok)
+        return level;
+    return { ok: true, motion: Object.freeze({ level: level.value }) };
+}

package/dist/stream/assembler.d.ts

@@ -0,0 +1,101 @@
+import { type JsonTokenizerOptions, type StreamError } from './tokenizer.js';
+/**
+ * The partial-blueprint assembler (ADR-014): builds the value the tokenizer
+ * reads and reports, for every catalog node, when its **shell** is final.
+ * Streamed nodes put `children` last (`key`, `id`, `slot`, `props`, `when`,
+ * `bind`, `on`, `children`), so a node's shell (every member but `children`)
+ * is final once `children` starts, or once the node closes without it.
+ * Envelopes put `state` and `flow` before the tree, so the envelope header
+ * is final once `tree` starts. A member after `children` (or after `tree`)
+ * is a `stream-order` issue: the node it lands in is held until the final
+ * verdict. The assembler judges no rule itself; the catalog checks each
+ * shell and `validateDraft` judges the whole value.
+ */
+/** Members a streamed node may have, in the canonical order (`children` last). */
+export declare const STREAM_NODE_ORDER: readonly string[];
+/** A node's members except `children`. Values are the assembled ones (not copies). */
+export type StreamNodeShell = Readonly<Record<string, unknown>>;
+export type BlueprintStreamEvent = 
+/** An envelope's members before its tree (`final` once the tree starts; again for a late member). */
+{
+    type: 'header';
+    header: Readonly<Record<string, unknown>>;
+    offset: number;
+}
+/** A node object opened. Its shell is not final yet. */
+ | {
+    type: 'node-start';
+    path: string;
+    parent: string | null;
+    index: number;
+    /** `true` for an element of an array (children, or an array of roots). */
+    inArray: boolean;
+    offset: number;
+}
+/** A node's `id` member closed (for a skeleton of the right family). */
+ | {
+    type: 'node-id';
+    path: string;
+    id: unknown;
+    offset: number;
+}
+/** A node's shell is final: every member but `children` arrived. */
+ | {
+    type: 'node';
+    path: string;
+    /** The node's stable stream id: its `key` when it has a string one, else its path. */
+    streamId: string;
+    parent: string | null;
+    index: number;
+    shell: StreamNodeShell;
+    /** `children` started (more nodes follow under this one). */
+    hasChildren: boolean;
+    /** `true` for an element of an array (children, or an array of roots). */
+    inArray: boolean;
+    offset: number;
+}
+/** A node object closed: all its children arrived. */
+ | {
+    type: 'node-end';
+    path: string;
+    offset: number;
+}
+/** A member after `children` (node) or after the tree (envelope, path `$`). */
+ | {
+    type: 'stream-order';
+    path: string;
+    key: string;
+    offset: number;
+}
+/** The whole value arrived and the stream ended cleanly. */
+ | {
+    type: 'complete';
+    value: unknown;
+    offset: number;
+}
+/** The stream stopped: nothing more is reported. */
+ | {
+    type: 'error';
+    error: StreamError;
+};
+export interface BlueprintAssemblerOptions extends JsonTokenizerOptions {
+    /**
+     * Root members that hold the tree. Default `['tree']` (the blueprint
+     * envelope). A host that also streams another wrapper (the player's
+     * local-state wrapper uses `blueprint`) adds its member here.
+     */
+    treeMembers?: readonly string[];
+}
+export interface BlueprintAssembler {
+    /** Feed a chunk; returns what it completed. */
+    write(chunk: string): BlueprintStreamEvent[];
+    /** No more input. Returns `complete` or the `truncated` error. */
+    end(): BlueprintStreamEvent[];
+    /** Stop with an `aborted` or `connection` error (a dropped stream). */
+    abort(code?: 'aborted' | 'connection', message?: string): BlueprintStreamEvent[];
+    readonly bytes: number;
+    readonly error: StreamError | null;
+    /** The value assembled so far (containers still open are partial). */
+    readonly value: unknown;
+}
+export declare function createBlueprintAssembler(options?: BlueprintAssemblerOptions): BlueprintAssembler;