@texuli/spec 0.2.0 → 0.4.0

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

@@ -1,10 +1,14 @@
 /** The built catalog this vocabulary was projected from. */
-export declare const SPEC_CATALOG_HASH = "b073e30b4c8b1a30b3ef3ccb372e552d2d88e584616b74591c6c32923b471376";
+export declare const SPEC_CATALOG_HASH = "8a449985d45c7bfd1dc2285f3513dfd6ca0e3e38260c0a541fdb7b17e9213006";
 /** Every closed component id, sorted. */
-export declare const SPEC_COMPONENT_IDS: readonly ["alert", "alert-dialog", "analytics-grid", "app-nav", "badge", "banner", "blocks-code", "blocks-data", "blocks-diagram", "blocks-embed", "blocks-interactive", "blocks-map", "blocks-media", "blocks-structure", "blocks-text", "breadcrumb", "button", "button-group", "callout", "card", "charts-area", "charts-bar", "charts-bubble", "charts-bullet", "charts-canvas-renderer", "charts-cartesian", "charts-combo", "charts-donut", "charts-funnel", "charts-gauge", "charts-geo-map", "charts-geo-point-map", "charts-heatmap", "charts-line", "charts-network", "charts-pie", "charts-progress-ring", "charts-sankey", "charts-scatter", "charts-sparkline", "charts-stacked-bar", "charts-sunburst", "charts-treemap", "checkbox", "chip", "code", "combobox", "command-palette", "content-layout", "context-menu", "context-menu-trigger", "deck-slide", "description", "detail-panel", "dialog", "drawer", "dropdown-menu", "dropdown-menu-content", "dropdown-menu-item", "dropdown-menu-trigger", "empty-state", "error-state", "field", "field-error", "form", "hover-card", "hover-card-content", "icon-button", "inline-text", "input", "input-group", "kbd", "kpi", "label", "layout-auth-split", "layout-blog", "layout-card", "layout-chrome", "layout-dashboard-grid", "layout-deck", "layout-doc", "layout-docs", "layout-drawer", "layout-dual-sidebar", "layout-editorial", "layout-grid", "layout-host", "layout-landing", "layout-marketing", "layout-page", "layout-pricing", "layout-settings", "layout-sidebar", "layout-top-nav", "layout-wizard", "media-composition-canvas", "media-composition-svg", "media-image", "menubar", "menubar-trigger", "multi-select", "nav-icon", "navigation-menu", "pagination", "popover", "popover-content", "radio", "radio-group", "responsive-modal", "screen-outlet", "select", "select-content", "select-group", "select-item", "select-label", "select-portal", "select-separator", "select-trigger", "select-value", "select-viewport", "sheet", "sidebar", "split-view", "stat", "stepper", "switch", "table", "tag", "text-counter", "textarea", "timeline", "toaster", "tooltip"];
+export declare const SPEC_COMPONENT_IDS: readonly ["action-form", "alert", "alert-dialog", "analytics-grid", "app-nav", "badge", "banner", "blocks-code", "blocks-data", "blocks-diagram", "blocks-embed", "blocks-interactive", "blocks-map", "blocks-media", "blocks-structure", "blocks-text", "breadcrumb", "button", "button-group", "callout", "card", "charts-area", "charts-bar", "charts-bubble", "charts-bullet", "charts-canvas-renderer", "charts-cartesian", "charts-combo", "charts-donut", "charts-funnel", "charts-gauge", "charts-geo-map", "charts-geo-point-map", "charts-heatmap", "charts-line", "charts-network", "charts-pie", "charts-progress-ring", "charts-sankey", "charts-scatter", "charts-sparkline", "charts-stacked-bar", "charts-sunburst", "charts-treemap", "chat-message", "chat-thread", "checkbox", "chip", "code", "combobox", "command-palette", "content-layout", "context-menu", "context-menu-trigger", "control-choice", "control-filter", "control-slider", "control-toggle", "data-board", "data-calendar", "data-files", "data-grid", "data-map", "data-timeline", "data-tree-view", "deck-slide", "description", "detail-panel", "dialog", "drawer", "dropdown-menu", "dropdown-menu-content", "dropdown-menu-item", "dropdown-menu-trigger", "empty-state", "error-state", "field", "field-error", "flow-action", "flow-view", "form", "form-field", "form-submit", "host-region", "hover-card", "hover-card-content", "icon-button", "inline-text", "input", "input-group", "kbd", "kpi", "label", "layout-auth-split", "layout-blog", "layout-card", "layout-chrome", "layout-dashboard-grid", "layout-deck", "layout-doc", "layout-docs", "layout-drawer", "layout-dual-sidebar", "layout-editorial", "layout-grid", "layout-host", "layout-landing", "layout-marketing", "layout-page", "layout-pricing", "layout-row", "layout-settings", "layout-sidebar", "layout-split", "layout-stack", "layout-tile", "layout-top-nav", "layout-wizard", "media-composition-canvas", "media-composition-svg", "media-image", "menubar", "menubar-trigger", "multi-select", "nav-icon", "navigation-menu", "pagination", "popover", "popover-content", "radio", "radio-group", "responsive-modal", "screen-outlet", "select", "select-content", "select-group", "select-item", "select-label", "select-portal", "select-separator", "select-trigger", "select-value", "select-viewport", "sheet", "sidebar", "sortable-list", "split-view", "stat", "stepper", "switch", "table", "tag", "text-counter", "textarea", "timeline", "toaster", "tooltip", "workflow-graph"];
 export type SpecComponentId = (typeof SPEC_COMPONENT_IDS)[number];
 /** The props a blueprint may set on each component (platform extensions left out). */
 export interface SpecComponentProps {
+    'action-form': {
+        action: string;
+        label: string;
+    };
     alert: {
         actionHref?: string;
         actionLabel?: string;
@@ -365,6 +369,15 @@ export interface SpecComponentProps {
         title: string;
         width?: number;
     };
+    'chat-message': {
+        at?: string;
+        author: string;
+        role: 'user' | 'agent' | 'system';
+        text?: string;
+    };
+    'chat-thread': {
+        label?: string;
+    };
     checkbox: {
         checked?: boolean;
         defaultChecked?: boolean;
@@ -434,12 +447,82 @@ export interface SpecComponentProps {
     'context-menu-trigger': {
         disabled?: boolean;
     };
+    'control-choice': {
+        label: string;
+        state: string;
+    };
+    'control-filter': {
+        label: string;
+        placeholder?: string;
+        state: string;
+    };
+    'control-slider': {
+        label: string;
+        state: string;
+        step?: number;
+    };
+    'control-toggle': {
+        label: string;
+        state: string;
+    };
+    'data-board': {
+        columns: readonly unknown[];
+        density?: 'comfortable' | 'compact';
+        items: readonly unknown[];
+        label: string;
+        lanes?: readonly unknown[];
+    };
+    'data-calendar': {
+        anchor?: string;
+        events: readonly unknown[];
+        label: string;
+        locale?: string;
+        readOnly?: boolean;
+        timeZone?: string;
+        view?: 'month' | 'week' | 'day' | 'agenda';
+    };
+    'data-files': {
+        density?: 'comfortable' | 'compact';
+        entries: readonly unknown[];
+        label: string;
+        layout?: 'grid' | 'list';
+    };
+    'data-grid': {
+        caption: string;
+        columns: readonly unknown[];
+        density?: 'compact' | 'default' | 'comfortable';
+        rows: readonly unknown[];
+        searchable?: boolean;
+        selectable?: boolean;
+    };
+    'data-map': {
+        label: string;
+        listPlacement?: 'side' | 'below';
+        markers: readonly unknown[];
+    };
+    'data-timeline': {
+        dependencies?: readonly unknown[];
+        label: string;
+        locale?: string;
+        tasks: readonly unknown[];
+        zoom?: 'day' | 'week' | 'month' | 'quarter';
+    };
+    'data-tree-view': {
+        checkboxes?: boolean;
+        density?: 'comfortable' | 'compact';
+        items: readonly unknown[];
+        label: string;
+    };
     'deck-slide': {
+        component?: Readonly<Record<string, unknown>>;
+        layout?: string;
         master?: 'title' | 'section' | 'content' | 'two-column' | 'media-left' | 'media-right' | 'quote' | 'closing';
         notes?: string;
+        props?: Readonly<Record<string, unknown>>;
         slideId: string;
+        steps?: readonly unknown[];
         title?: string;
-        transition?: 'none' | 'fade' | 'fade-up';
+        transition?: 'none' | 'fade' | 'fade-up' | 'slide' | 'zoom' | 'morph';
     };
     description: Record<string, never>;
     'detail-panel': {
@@ -506,11 +589,40 @@ export interface SpecComponentProps {
     'field-error': {
         show?: boolean;
     };
+    'flow-action': {
+        event: string;
+        label: string;
+    };
+    'flow-view': {
+        label?: string;
+        name: string;
+    };
     form: {
         errors?: Readonly<Record<string, unknown>>;
         layout?: 'stack' | 'grid';
         noValidate?: boolean;
     };
+    'form-field': {
+        autocomplete?: 'off' | 'name' | 'given-name' | 'family-name' | 'nickname' | 'email' | 'tel' | 'organization' | 'organization-title' | 'street-address' | 'address-level1' | 'address-level2' | 'postal-code' | 'country-name' | 'language' | 'url';
+        kind?: 'text' | 'email' | 'tel' | 'number' | 'multiline';
+        label: string;
+        max?: number;
+        maxLength?: number;
+        min?: number;
+        minLength?: number;
+        name: string;
+        pattern?: 'email' | 'phone' | 'postal-code' | 'digits' | 'slug';
+        placeholder?: string;
+        required?: boolean;
+        state: string;
+    };
+    'form-submit': {
+        label: string;
+    };
+    'host-region': {
+        label: string;
+        name: string;
+    };
     'hover-card': {
         open?: boolean;
     };
@@ -600,13 +712,17 @@ export interface SpecComponentProps {
         storageKey?: string;
     };
     'layout-deck': {
-        aspect?: '16:9' | '4:3' | '1:1';
+        aspect?: '16:9' | '4:3' | '9:16' | '1:1';
         description?: string;
         locale?: string;
         masters?: readonly unknown[];
+        motion?: 'full' | 'subtle' | 'none';
+        navigation?: Readonly<Record<string, unknown>>;
+        outline?: Readonly<Record<string, unknown>>;
         settings?: Readonly<Record<string, unknown>>;
         slides?: readonly unknown[];
         title?: string;
+        transition?: 'none' | 'fade' | 'fade-up' | 'slide' | 'zoom' | 'morph';
     };
     'layout-doc': {
         title?: string;
@@ -671,6 +787,11 @@ export interface SpecComponentProps {
         plans?: readonly unknown[];
         title?: string;
     };
+    'layout-row': {
+        align?: 'start' | 'center' | 'end' | 'stretch';
+        gap?: 'none' | 'small' | 'medium' | 'large';
+        wrap?: boolean;
+    };
     'layout-settings': {
         active?: string;
         backLabel?: string;
@@ -689,6 +810,18 @@ export interface SpecComponentProps {
         skipLabel?: string;
         storageKey?: string;
     };
+    'layout-split': {
+        gap?: 'none' | 'small' | 'medium' | 'large';
+        ratio?: '1:1' | '1:2' | '2:1' | '1:3' | '3:1';
+    };
+    'layout-stack': {
+        gap?: 'none' | 'small' | 'medium' | 'large';
+    };
+    'layout-tile': {
+        rowSpan?: number;
+        span?: number;
+        title?: string;
+    };
     'layout-top-nav': {
         closeLabel?: string;
         menuLabel?: string;
@@ -767,6 +900,7 @@ export interface SpecComponentProps {
         variant?: 'outline' | 'soft';
     };
     'nav-icon': {
+        icon: string;
         label?: string;
     };
     'navigation-menu': {
@@ -874,16 +1008,24 @@ export interface SpecComponentProps {
         sections?: readonly unknown[];
         variant?: 'default' | 'inset';
     };
+    'sortable-list': {
+        itemDetail?: string;
+        itemLabel?: string;
+        label: string;
+        reorder: Readonly<Record<string, unknown>>;
+    };
     'split-view': {
         detailActive?: boolean;
         detailLabel?: string;
         listLabel?: string;
     };
     stat: {
+        delta?: string;
         hint?: string;
         label: string;
         positive?: 'up' | 'down';
         trend?: 'up' | 'down' | 'neutral';
+        value: string;
         variant?: 'elevated' | 'flat';
     };
     stepper: {
@@ -969,4 +1111,10 @@ export interface SpecComponentProps {
         side?: 'top' | 'right' | 'bottom' | 'left';
         sideOffset?: number;
     };
+    'workflow-graph': {
+        flow?: 'LR' | 'TB';
+        graph: Readonly<Record<string, unknown>>;
+        label: string;
+        mode?: 'view' | 'edit';
+    };
 }

package/dist/generated/typescript/vocabulary.js

@@ -1,9 +1,10 @@
 // Generated by @texuli/spec from catalog/components.json. Do not edit: run the spec generator.
-// Spec 0.2.0, digest d9eccaba1826e7d87648a4a33787d873245592dda843607a10b2c68a77f1806f
+// Spec 0.4.0, digest fac29f542b16ddb78ab401c508e5b8346f655991c56e25aa811f4931661a8cb3
 /** The built catalog this vocabulary was projected from. */
-export const SPEC_CATALOG_HASH = 'b073e30b4c8b1a30b3ef3ccb372e552d2d88e584616b74591c6c32923b471376';
+export const SPEC_CATALOG_HASH = '8a449985d45c7bfd1dc2285f3513dfd6ca0e3e38260c0a541fdb7b17e9213006';
 /** Every closed component id, sorted. */
 export const SPEC_COMPONENT_IDS = [
+    'action-form',
     'alert',
     'alert-dialog',
     'analytics-grid',
@@ -47,6 +48,8 @@ export const SPEC_COMPONENT_IDS = [
     'charts-stacked-bar',
     'charts-sunburst',
     'charts-treemap',
+    'chat-message',
+    'chat-thread',
     'checkbox',
     'chip',
     'code',
@@ -55,6 +58,17 @@ export const SPEC_COMPONENT_IDS = [
     'content-layout',
     'context-menu',
     'context-menu-trigger',
+    'control-choice',
+    'control-filter',
+    'control-slider',
+    'control-toggle',
+    'data-board',
+    'data-calendar',
+    'data-files',
+    'data-grid',
+    'data-map',
+    'data-timeline',
+    'data-tree-view',
     'deck-slide',
     'description',
     'detail-panel',
@@ -68,7 +82,12 @@ export const SPEC_COMPONENT_IDS = [
     'error-state',
     'field',
     'field-error',
+    'flow-action',
+    'flow-view',
     'form',
+    'form-field',
+    'form-submit',
+    'host-region',
     'hover-card',
     'hover-card-content',
     'icon-button',
@@ -95,8 +114,12 @@ export const SPEC_COMPONENT_IDS = [
     'layout-marketing',
     'layout-page',
     'layout-pricing',
+    'layout-row',
     'layout-settings',
     'layout-sidebar',
+    'layout-split',
+    'layout-stack',
+    'layout-tile',
     'layout-top-nav',
     'layout-wizard',
     'media-composition-canvas',
@@ -126,6 +149,7 @@ export const SPEC_COMPONENT_IDS = [
     'select-viewport',
     'sheet',
     'sidebar',
+    'sortable-list',
     'split-view',
     'stat',
     'stepper',
@@ -137,4 +161,5 @@ export const SPEC_COMPONENT_IDS = [
     'timeline',
     'toaster',
     'tooltip',
+    'workflow-graph',
 ];

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

@@ -0,0 +1,84 @@
+export type WorkflowId = string;
+/** Display text: no control characters and no bidirectional overrides or isolates. */
+export type WorkflowLabel = string;
+export type WorkflowCoordinate = number;
+export interface WorkflowPosition {
+    x: WorkflowCoordinate;
+    y: WorkflowCoordinate;
+}
+export interface WorkflowSize {
+    width: number;
+    height: number;
+}
+export interface WorkflowPort {
+    id: WorkflowId;
+    direction: 'in' | 'out';
+    label?: WorkflowLabel;
+    /** Ports with a kind connect only to ports of the same kind. */
+    kind?: string;
+    /** Whether the port takes more than one edge. */
+    multiple?: boolean;
+}
+export interface WorkflowField {
+    name: string;
+    label?: WorkflowLabel;
+    kind: 'string' | 'number' | 'boolean' | 'enum';
+    required?: boolean;
+    enumValues?: readonly string[];
+    /** For string fields; 2000 when omitted. */
+    maxLength?: number;
+}
+export interface WorkflowNodeType {
+    id: WorkflowId;
+    label: WorkflowLabel;
+    category?: WorkflowLabel;
+    ports: readonly WorkflowPort[];
+    fields?: readonly WorkflowField[];
+}
+export interface WorkflowNode {
+    id: WorkflowId;
+    type: WorkflowId;
+    label: WorkflowLabel;
+    position: WorkflowPosition;
+    size?: WorkflowSize;
+    group?: WorkflowId;
+    /** Field values by field name: scalars of the field kind. */
+    data?: Readonly<Record<string, unknown>>;
+    locked?: boolean;
+}
+export interface WorkflowEndpoint {
+    node: WorkflowId;
+    port: WorkflowId;
+}
+export interface WorkflowEdge {
+    id: WorkflowId;
+    from: WorkflowEndpoint;
+    to: WorkflowEndpoint;
+    label?: WorkflowLabel;
+}
+export interface WorkflowGroup {
+    id: WorkflowId;
+    label: WorkflowLabel;
+    position?: WorkflowPosition;
+    size?: WorkflowSize;
+}
+export interface WorkflowViewport {
+    x: WorkflowCoordinate;
+    y: WorkflowCoordinate;
+    zoom: number;
+}
+/**
+ * A workflow graph as data (ADR-008): closed node types with typed ports and fields, nodes, edges
+ * between declared ports, optional groups and a cycle policy. At most 500 nodes and 2,000 edges.
+ * Ids, references, field values, port directions and cycles are checked by validateWorkflowGraph.
+ */
+export interface WorkflowGraph {
+    version: 1;
+    nodeTypes: readonly WorkflowNodeType[];
+    nodes: readonly WorkflowNode[];
+    edges: readonly WorkflowEdge[];
+    groups?: readonly WorkflowGroup[];
+    /** forbid makes the graph acyclic (a self-loop counts); omitted means allow. */
+    cycles?: 'allow' | 'forbid';
+    viewport?: WorkflowViewport;
+}

package/dist/generated/typescript/workflow.js

@@ -0,0 +1,3 @@
+// Generated by @texuli/spec from schemas/workflow.schema.json. Do not edit: run the spec generator.
+// Spec 0.4.0, digest fac29f542b16ddb78ab401c508e5b8346f655991c56e25aa811f4931661a8cb3
+export {};

package/dist/index.d.ts

@@ -1,17 +1,25 @@
 /**
  * `@texuli/spec` — the schema-first blueprint contract (spec/Compose design
  * B1), runtime half: the generated types and vocabulary, the dialect
- * validator, the target-neutral blueprint validator and deterministic
- * hashing. Build-time generation and the conformance harness live in
- * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
+ * validator, the target-neutral blueprint validator, the 0.3.0 interaction
+ * contract (bindings, closed actions, events) and deterministic hashing.
+ * Opt-in subpaths keep the root small: `@texuli/spec/workflow` (the workflow
+ * graph validator, passed in `SpecDocuments.validateWorkflowGraph`) and
+ * `@texuli/spec/migrate` (envelope migrations). Build-time generation and the
+ * conformance harness live in `@texuli/spec/codegen`. Framework-free: no DOM,
+ * no Svelte and no Node APIs.
  */
 export type * from './generated/typescript/blueprint.js';
 export type * from './generated/typescript/catalog-schema.js';
 export type * from './generated/typescript/diagnostics.js';
 export type * from './generated/typescript/manifest.js';
 export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, type SpecComponentId, type SpecComponentProps, } from './generated/typescript/vocabulary.js';
+export type * from './generated/typescript/workflow.js';
 export { canonicalJson, sha256 } from './canonical.js';
 export { CAPABILITIES, type Capability, type SpecPropKind, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from './catalog.js';
-export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, type DialectType, type Schema, type SchemaIssue, validateInstance, } from './dialect.js';
-export { type SpecDocuments, validateBlueprint, validateTree, } from './validate.js';
+export { ACTION_FIELDS, contractRoot, DATA_BINDING_KEY, SPEC_ACTION_OPS, SPEC_EVENT_NAMES, SPEC_LIMITS, SPEC_PATTERNS, SPEC_PROP_REFS, SPEC_STATE_TYPES, type SpecActionOp, type SpecStateType, STATE_BINDING_KEY, STATE_FIELDS, toDialectSchema, } from './contract.js';
+export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, type DialectHooks, type DialectType, type Schema, type SchemaIssue, validateInstance, } from './dialect.js';
+export type { SpecMigration, SpecMigrationResult } from './migrations/types.js';
+export { checkStateSurface, LIST_TEXT_PATTERN, SPEC_CONTROL_STATE_TYPES, SURFACE_PLAYER_CODES, type SurfaceCode, type SurfaceInputs, type SurfaceIssue, surfaceInputs, } from './surface.js';
+export { type SpecDocuments, type SpecFlowInfo, type SpecStateVariable, type TreeOptions, validateBlueprint, validateTree, type WorkflowGraphValidator, } from './validate.js';
 export { SPEC_VERSION } from './version.js';

package/dist/index.js

@@ -1,13 +1,19 @@
 /**
  * `@texuli/spec` — the schema-first blueprint contract (spec/Compose design
  * B1), runtime half: the generated types and vocabulary, the dialect
- * validator, the target-neutral blueprint validator and deterministic
- * hashing. Build-time generation and the conformance harness live in
- * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
+ * validator, the target-neutral blueprint validator, the 0.3.0 interaction
+ * contract (bindings, closed actions, events) and deterministic hashing.
+ * Opt-in subpaths keep the root small: `@texuli/spec/workflow` (the workflow
+ * graph validator, passed in `SpecDocuments.validateWorkflowGraph`) and
+ * `@texuli/spec/migrate` (envelope migrations). Build-time generation and the
+ * conformance harness live in `@texuli/spec/codegen`. Framework-free: no DOM,
+ * no Svelte and no Node APIs.
  */
 export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, } from "./generated/typescript/vocabulary.js";
 export { canonicalJson, sha256 } from "./canonical.js";
 export { CAPABILITIES, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from "./catalog.js";
+export { ACTION_FIELDS, contractRoot, DATA_BINDING_KEY, SPEC_ACTION_OPS, SPEC_EVENT_NAMES, SPEC_LIMITS, SPEC_PATTERNS, SPEC_PROP_REFS, SPEC_STATE_TYPES, STATE_BINDING_KEY, STATE_FIELDS, toDialectSchema, } from "./contract.js";
 export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, validateInstance, } from "./dialect.js";
+export { checkStateSurface, LIST_TEXT_PATTERN, SPEC_CONTROL_STATE_TYPES, SURFACE_PLAYER_CODES, surfaceInputs, } from "./surface.js";
 export { validateBlueprint, validateTree, } from "./validate.js";
 export { SPEC_VERSION } from "./version.js";

package/dist/migrations/0.2.0-0.3.0.d.ts

@@ -0,0 +1,7 @@
+import type { SpecMigration } from './types.js';
+/**
+ * 0.2.0 → 0.3.0 is additive (ADR-008): every 0.2.0 envelope is a valid
+ * 0.3.0 envelope, so the step only stamps `spec`. Object spread keeps a
+ * parsed `__proto__` key as an own property, so validation still refuses it.
+ */
+export declare const migration020to030: SpecMigration;

package/dist/migrations/0.2.0-0.3.0.js

@@ -0,0 +1,10 @@
+/**
+ * 0.2.0 → 0.3.0 is additive (ADR-008): every 0.2.0 envelope is a valid
+ * 0.3.0 envelope, so the step only stamps `spec`. Object spread keeps a
+ * parsed `__proto__` key as an own property, so validation still refuses it.
+ */
+export const migration020to030 = Object.freeze({
+    from: '0.2.0',
+    to: '0.3.0',
+    migrate: (envelope) => ({ ...envelope, spec: '0.3.0' }),
+});

package/dist/migrations/0.3.0-0.4.0.d.ts

@@ -0,0 +1,9 @@
+import type { SpecMigration } from './types.js';
+/**
+ * 0.3.0 → 0.4.0 is additive (PLAN_008 T-catalog-player / ADR-009 deck encoding):
+ * layout-deck and deck-slide gain optional model-v2 props (aspect 9:16,
+ * transitions slide/zoom/morph, motion, navigation, outline, layout, background,
+ * steps, component). Every 0.3.0 envelope is a valid 0.4.0 envelope, so the
+ * step only stamps `spec`.
+ */
+export declare const migration030to040: SpecMigration;

package/dist/migrations/0.3.0-0.4.0.js

@@ -0,0 +1,12 @@
+/**
+ * 0.3.0 → 0.4.0 is additive (PLAN_008 T-catalog-player / ADR-009 deck encoding):
+ * layout-deck and deck-slide gain optional model-v2 props (aspect 9:16,
+ * transitions slide/zoom/morph, motion, navigation, outline, layout, background,
+ * steps, component). Every 0.3.0 envelope is a valid 0.4.0 envelope, so the
+ * step only stamps `spec`.
+ */
+export const migration030to040 = Object.freeze({
+    from: '0.3.0',
+    to: '0.4.0',
+    migrate: (envelope) => ({ ...envelope, spec: '0.4.0' }),
+});

package/dist/migrations/index.d.ts

@@ -0,0 +1,15 @@
+import type { SpecMigration, SpecMigrationResult } from './types.js';
+export type { SpecMigration, SpecMigrationResult };
+/** The version an envelope without `spec` was written for. */
+export declare const UNDECLARED_SPEC_VERSION = "0.2.0";
+/** Every step, in order; each `to` is the next step's `from`. */
+export declare const SPEC_MIGRATIONS: readonly SpecMigration[];
+/**
+ * Bring a blueprint envelope up to `target` (the current spec by default)
+ * before validation. Never throws and never mutates its input: a value that
+ * is not an envelope, or one declaring a version no chain starts from, passes
+ * through with no step applied (validation then refuses an unknown `spec`).
+ * Only the envelope's `spec` field changes, so the tree, status, provenance
+ * and activation digest stay as they were. Idempotent.
+ */
+export declare function migrateBlueprint(input: unknown, target?: string): SpecMigrationResult;

package/dist/migrations/index.js

@@ -0,0 +1,53 @@
+import { isRecord } from "../dialect.js";
+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";
+/** 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`. */
+export const SPEC_MIGRATIONS = Object.freeze([
+    migration020to030,
+    migration030to040,
+]);
+/**
+ * Bring a blueprint envelope up to `target` (the current spec by default)
+ * before validation. Never throws and never mutates its input: a value that
+ * is not an envelope, or one declaring a version no chain starts from, passes
+ * through with no step applied (validation then refuses an unknown `spec`).
+ * Only the envelope's `spec` field changes, so the tree, status, provenance
+ * and activation digest stay as they were. Idempotent.
+ */
+export function migrateBlueprint(input, target = SPEC_VERSION) {
+    if (!isRecord(input)) {
+        return {
+            blueprint: input,
+            from: UNDECLARED_SPEC_VERSION,
+            to: UNDECLARED_SPEC_VERSION,
+            applied: [],
+        };
+    }
+    const declared = Object.hasOwn(input, 'spec') ? input.spec : UNDECLARED_SPEC_VERSION;
+    if (typeof declared !== 'string') {
+        return {
+            blueprint: input,
+            from: UNDECLARED_SPEC_VERSION,
+            to: UNDECLARED_SPEC_VERSION,
+            applied: [],
+        };
+    }
+    let blueprint = input;
+    let current = declared;
+    const applied = [];
+    for (let step = 0; step < SPEC_MIGRATIONS.length && current !== target; step += 1) {
+        const migration = SPEC_MIGRATIONS.find((m) => m.from === current);
+        if (!migration)
+            break;
+        blueprint = migration.migrate(blueprint);
+        applied.push(`${migration.from}->${migration.to}`);
+        current = migration.to;
+    }
+    if (current !== target) {
+        return { blueprint: input, from: declared, to: declared, applied: [] };
+    }
+    return { blueprint, from: declared, to: current, applied };
+}

package/dist/migrations/types.d.ts

@@ -0,0 +1,14 @@
+/** One pure step between two adjacent spec versions. */
+export interface SpecMigration {
+    readonly from: string;
+    readonly to: string;
+    /** Pure: never mutates its input; unchanged subtrees may be shared. */
+    migrate(envelope: Readonly<Record<string, unknown>>): Record<string, unknown>;
+}
+/** What {@link migrateBlueprint} did: the result and the steps applied (`"0.2.0->0.3.0"`). */
+export interface SpecMigrationResult {
+    blueprint: unknown;
+    from: string;
+    to: string;
+    applied: readonly string[];
+}

package/dist/migrations/types.js

@@ -0,0 +1 @@
+export {};