@texuli/spec 0.6.0 → 0.7.0

package/README.md

@@ -14,9 +14,16 @@ 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.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.
+> published to npm as `0.7.0`, a pre-1.0 release (1.0.0 will be the first
+> stable release). Under 0.x, a new minor (`0.8.0`) may contain breaking
+> changes, so pin the exact version or use `^0.7.0`, which accepts only 0.7.x.
+
+> **New in `0.7.0`.** `@texuli/spec@0.7.0` carries **spec 0.7.0**, which adds
+> an optional node `key` (unique in the tree), the agent-emittable
+> `document` id with its `$defs.document` shape, the `patchDocument` edit
+> op with a bounded RFC 6902 patch, and the pinned
+> `schemas/document.schema.json`. Every `0.6.0` envelope migrates by
+> stamping `spec`.
 
 > **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
@@ -61,7 +68,7 @@ import {
   validateInstance,
 } from '@texuli/spec';
 
-SPEC_VERSION;                         // the spec version: '0.6.0' in @texuli/spec@0.6.0
+SPEC_VERSION;                         // the spec version: '0.7.0' in @texuli/spec@0.7.0
 SPEC_COMPONENT_IDS.includes('alert'); // true: the closed component vocabulary
 
 // The dialect validator: a closed subset of JSON Schema 2020-12.
@@ -93,7 +100,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.5.0 → 0.6.0; never throws
+const migrated = migrateBlueprint(blueprint); // 0.2.0 → … → 0.6.0 → 0.7.0; never throws
 const result = validateBlueprint(migrated.blueprint, {
   blueprintSchema: blueprintSchemaJson as Schema,
   catalog: componentsJson as SpecCatalog,
@@ -114,7 +121,8 @@ refused state or flow declaration), `unknown-state` (a binding or action
 names no declared variable), `binding` (a malformed, misplaced, read-only or
 ill-fitting binding), `action` (an action with the wrong fields or target),
 `unknown-event` (an `on` key the component does not fire) and `workflow` (a
-workflow graph rule). Deprecated components and props add a `deprecated`
+workflow graph rule), and, from spec 0.7.0, `duplicate-key` (a node key used
+twice in the tree). Deprecated components and props add a `deprecated`
 warning without failing.
 
 ## What's inside
@@ -162,6 +170,12 @@ warning without failing.
   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`.
+- **Documents as data (spec 0.7.0, new in `0.7.0`).** A
+  `document` node's `doc` must have the document shape (`$defs.document`);
+  the document's own vocabulary and URL policy are checked by
+  `@texuli/document` through `@texuli/catalog`'s `validateDraft`. Agents
+  edit documents with `patchDocument` (at most 1,000 RFC 6902 operations),
+  addressed by node `key`.
 - **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
@@ -210,9 +224,12 @@ 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`, `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
+(`src/migrations/`: `0.2.0 → 0.3.0`, `0.3.0 → 0.4.0`, `0.4.0 → 0.5.0`,
+`0.5.0 → 0.6.0` and `0.6.0 → 0.7.0`, each of which only stamps `spec`); a
+compatible version range is planned, not built. `@texuli/spec@0.7.0`
+carries spec `0.7.0` (digest
+`43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2`), which
+adds node keys and documents; `@texuli/spec@0.6.0` carried 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`,

package/dist/build.d.ts

@@ -3,6 +3,14 @@ import { SPEC_VERSION } from './version.js';
 export { SPEC_VERSION };
 /** Where normative files live inside the package. */
 export declare const NORMATIVE_DIRS: readonly ["schemas/", "catalog/", "fixtures/"];
+/**
+ * Normative schemas that are pinned by digest but are not in the dialect and
+ * generate nothing: they are exported by a higher-layer engine and kept here
+ * so the contract pins the exact version agents write against. Spec 0.7.0
+ * pins `@texuli/document`'s JSON Schema export (ADR-011); a freshness test in
+ * `@texuli/catalog` keeps it equal to `documentJsonSchema()`.
+ */
+export declare const EXTERNAL_SCHEMAS: readonly string[];
 /** The schema documents, their generated names and output files. */
 export declare const SCHEMA_UNITS: readonly [{
     readonly name: "blueprint";

package/dist/build.js

@@ -7,6 +7,14 @@ import { SPEC_VERSION } from "./version.js";
 export { SPEC_VERSION };
 /** Where normative files live inside the package. */
 export const NORMATIVE_DIRS = ['schemas/', 'catalog/', 'fixtures/'];
+/**
+ * Normative schemas that are pinned by digest but are not in the dialect and
+ * generate nothing: they are exported by a higher-layer engine and kept here
+ * so the contract pins the exact version agents write against. Spec 0.7.0
+ * pins `@texuli/document`'s JSON Schema export (ADR-011); a freshness test in
+ * `@texuli/catalog` keeps it equal to `documentJsonSchema()`.
+ */
+export const EXTERNAL_SCHEMAS = Object.freeze(['schemas/document.schema.json']);
 /** The schema documents, their generated names and output files. */
 export const SCHEMA_UNITS = [
     { name: 'blueprint', prefix: 'Blueprint', ts: 'blueprint.ts', kt: 'Blueprint.kt' },

package/dist/codegen/index.d.ts

@@ -4,7 +4,7 @@
  * projection, the committed-file JSON format and the conformance harness.
  * Pure functions: callers read and write the files.
  */
-export { buildSpec, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, type SpecBuild, TS_OUT, } from '../build.js';
+export { buildSpec, EXTERNAL_SCHEMAS, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, type SpecBuild, TS_OUT, } from '../build.js';
 export { prettyJson } from '../canonical.js';
 export { type BuiltCatalogLike, projectCatalog } from '../catalog.js';
 export { type ConformanceIssue, checkCatalogContract, checkConformance, deprecationExpired, } from '../conformance.js';

package/dist/codegen/index.js

@@ -4,7 +4,7 @@
  * projection, the committed-file JSON format and the conformance harness.
  * Pure functions: callers read and write the files.
  */
-export { buildSpec, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, TS_OUT, } from "../build.js";
+export { buildSpec, EXTERNAL_SCHEMAS, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, TS_OUT, } from "../build.js";
 export { prettyJson } from "../canonical.js";
 export { projectCatalog } from "../catalog.js";
 export { checkCatalogContract, checkConformance, deprecationExpired, } from "../conformance.js";

package/dist/conformance.d.ts

@@ -9,7 +9,7 @@ export interface ConformanceIssue {
  * Run the spec's conformance harness (spec/Compose design §7.1 and §7.3)
  * over the normative files and the committed outputs (`manifest.json`,
  * `generated-manifest.json` and every generated file):
- * - every schema stays in the dialect;
+ * - every schema stays in the dialect (except the pinned `EXTERNAL_SCHEMAS`);
  * - `catalog/components.json` and `catalog/capabilities.json` are valid;
  * - the manifest digests match the normative files;
  * - regenerating gives byte-identical TypeScript and Kotlin, with no file

package/dist/conformance.js

@@ -1,4 +1,4 @@
-import { buildSpec } from "./build.js";
+import { buildSpec, EXTERNAL_SCHEMAS } from "./build.js";
 import { CAPABILITIES } from "./catalog.js";
 import { checkPropSchema, defCollisions } from "./contract.js";
 import { checkSchemaDocument, isRecord, validateInstance } from "./dialect.js";
@@ -9,7 +9,7 @@ import { validateWorkflowGraph } from "./workflow.js";
  * Run the spec's conformance harness (spec/Compose design §7.1 and §7.3)
  * over the normative files and the committed outputs (`manifest.json`,
  * `generated-manifest.json` and every generated file):
- * - every schema stays in the dialect;
+ * - every schema stays in the dialect (except the pinned `EXTERNAL_SCHEMAS`);
  * - `catalog/components.json` and `catalog/capabilities.json` are valid;
  * - the manifest digests match the normative files;
  * - regenerating gives byte-identical TypeScript and Kotlin, with no file
@@ -26,7 +26,8 @@ export function checkConformance(normative, committed) {
     const issues = [];
     const json = (path) => JSON.parse(normative[path] ?? 'null');
     const schemas = {};
-    for (const path of Object.keys(normative).filter((p) => p.startsWith('schemas/'))) {
+    const dialectSchemas = Object.keys(normative).filter((p) => p.startsWith('schemas/') && !EXTERNAL_SCHEMAS.includes(p));
+    for (const path of dialectSchemas) {
         const schema = json(path);
         schemas[path] = schema;
         for (const issue of checkSchemaDocument(schema)) {

package/dist/contract.d.ts

@@ -21,7 +21,7 @@ export type SpecActionOp = (typeof SPEC_ACTION_OPS)[number];
 export declare const SPEC_EVENT_NAMES: readonly ["press", "change", "select", "submit", "dismiss", "move"];
 export type SpecEventName = (typeof SPEC_EVENT_NAMES)[number];
 /** The `$ref` targets a catalog property schema may name. */
-export declare const SPEC_PROP_REFS: readonly ["binding", "reorder", "action", "eventMap", "condition", "workflowGraph"];
+export declare const SPEC_PROP_REFS: readonly ["binding", "reorder", "action", "eventMap", "condition", "workflowGraph", "document"];
 /** The fields each action op takes (besides `op`) and the ones it needs. */
 export declare const ACTION_FIELDS: Readonly<Record<SpecActionOp, {
     readonly allowed: readonly string[];
@@ -54,6 +54,10 @@ export declare const SPEC_LIMITS: Readonly<{
     workflowStringLength: 2000;
     /** Deepest prop value walked for nested bindings. */
     propDepth: 32;
+    /** Top-level blocks a `document` node's doc may hold (`$defs.document.blocks`). */
+    documentBlocks: 2000;
+    /** Operations one `patchDocument` patch may carry (`$defs.documentPatch`, ADR-011). */
+    documentPatchOps: 1000;
 }>;
 /** The name patterns, as the schemas write them. */
 export declare const SPEC_PATTERNS: Readonly<{
@@ -62,6 +66,8 @@ export declare const SPEC_PATTERNS: Readonly<{
     flowName: "^[a-z][a-z0-9-]{0,31}$";
     intentName: "^[A-Za-z][A-Za-z0-9_-]{0,63}$";
     itemKey: "^[A-Za-z0-9._:-]{1,64}$";
+    /** A node's stable instance id (spec 0.7.0, ADR-014), unique in its tree. */
+    nodeKey: "^[A-Za-z0-9._:-]{1,64}$";
     groupName: "^[a-z][a-z0-9-]{0,31}$";
     workflowId: "^[A-Za-z0-9._:-]{1,64}$";
     workflowFieldName: "^[a-z][A-Za-z0-9_]{0,31}$";
@@ -88,6 +94,7 @@ export declare const SPEC_REGEX: Readonly<{
     dataName: RegExp;
     intentName: RegExp;
     itemKey: RegExp;
+    nodeKey: RegExp;
     listText: RegExp;
 }>;
 /**

package/dist/contract.js

@@ -32,6 +32,7 @@ export const SPEC_PROP_REFS = [
     'eventMap',
     'condition',
     'workflowGraph',
+    'document',
 ];
 /** The fields each action op takes (besides `op`) and the ones it needs. */
 export const ACTION_FIELDS = Object.freeze({
@@ -76,6 +77,10 @@ export const SPEC_LIMITS = Object.freeze({
     workflowStringLength: 2000,
     /** Deepest prop value walked for nested bindings. */
     propDepth: 32,
+    /** Top-level blocks a `document` node's doc may hold (`$defs.document.blocks`). */
+    documentBlocks: 2000,
+    /** Operations one `patchDocument` patch may carry (`$defs.documentPatch`, ADR-011). */
+    documentPatchOps: 1000,
 });
 /** The name patterns, as the schemas write them. */
 export const SPEC_PATTERNS = Object.freeze({
@@ -84,6 +89,8 @@ export const SPEC_PATTERNS = Object.freeze({
     flowName: '^[a-z][a-z0-9-]{0,31}$',
     intentName: '^[A-Za-z][A-Za-z0-9_-]{0,63}$',
     itemKey: '^[A-Za-z0-9._:-]{1,64}$',
+    /** A node's stable instance id (spec 0.7.0, ADR-014), unique in its tree. */
+    nodeKey: '^[A-Za-z0-9._:-]{1,64}$',
     groupName: '^[a-z][a-z0-9-]{0,31}$',
     workflowId: '^[A-Za-z0-9._:-]{1,64}$',
     workflowFieldName: '^[a-z][A-Za-z0-9_]{0,31}$',
@@ -110,6 +117,7 @@ export const SPEC_REGEX = Object.freeze({
     dataName: new RegExp(SPEC_PATTERNS.dataName, 'u'),
     intentName: new RegExp(SPEC_PATTERNS.intentName, 'u'),
     itemKey: new RegExp(SPEC_PATTERNS.itemKey, 'u'),
+    nodeKey: new RegExp(SPEC_PATTERNS.nodeKey, 'u'),
     listText: new RegExp(SPEC_PATTERNS.listText, 'u'),
 });
 /**

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

@@ -34,10 +34,15 @@ export interface BlueprintProvenanceEntry {
     kind: 'apply' | 'undo' | 'redo';
     ops: readonly BlueprintEditOp[];
 }
-/** One edit op. The fields each op kind takes are checked by the edit parser. */
+/**
+ * One edit op. The fields each op kind takes are checked by the edit parser. From spec 0.7.0,
+ * patchDocument applies a bounded RFC 6902 patch to the doc of a document node it addresses by path
+ * or by key.
+ */
 export interface BlueprintEditOp {
-    op: 'insert' | 'remove' | 'move' | 'setProp' | 'unsetProp' | 'replace' | 'replaceAll';
+    op: 'insert' | 'remove' | 'move' | 'setProp' | 'unsetProp' | 'replace' | 'replaceAll' | 'patchDocument';
     path?: BlueprintNodePath;
+    key?: BlueprintNodeKey;
     parent?: BlueprintNodePath;
     index?: number;
     name?: string;
@@ -45,13 +50,15 @@ export interface BlueprintEditOp {
     value?: unknown;
     node?: BlueprintNode;
     tree?: BlueprintNode;
+    patch?: BlueprintDocumentPatch;
 }
 export type BlueprintNodePath = readonly number[];
 /**
- * One catalog node: id, props, children (each with an optional named slot), when, bind, on and
- * motion.
+ * One catalog node: an optional key (spec 0.7.0), id, props, children (each with an optional named
+ * slot), when, bind, on and motion.
  */
 export interface BlueprintNode {
+    key?: BlueprintNodeKey;
     /** A catalog component id. */
     id: string;
     /** Props checked against the component's catalog entry. */
@@ -114,6 +121,11 @@ export type BlueprintFlowName = string;
 export type BlueprintIntentName = string;
 /** The id of one item in a list variable. */
 export type BlueprintItemKey = string;
+/**
+ * A node's stable instance id (spec 0.7.0, ADR-012 and ADR-014): unique in its tree. Streaming,
+ * live updates and edit ops address a node by its key, else by its path.
+ */
+export type BlueprintNodeKey = string;
 /** A reorder group name. */
 export type BlueprintGroupName = string;
 /**
@@ -224,12 +236,52 @@ export interface BlueprintNodeMotion {
 export interface BlueprintEnvelopeMotion {
     level: BlueprintMotionLevel;
 }
+/**
+ * A Texuli document (spec 0.7.0, ADR-011): the format, version, metadata, page settings, block list
+ * and annotations of @texuli/document. This contract checks the envelope of the document only; the
+ * closed block vocabulary, text safety, the URL policy and the caps are checked by
+ * @texuli/document/schema (schemas/document.schema.json) inside the runtime validator,
+ * @texuli/catalog's validateDraft, at the host's tier.
+ */
+export interface BlueprintDocument {
+    format: 'texuli-document';
+    formatVersion: 1;
+    /** Title (required), description, locale, direction, authors, tags and dates. */
+    meta: Readonly<Record<string, unknown>>;
+    /** Page size, orientation, margins, header and footer for paged output. */
+    page?: Readonly<Record<string, unknown>>;
+    /**
+     * The block list: paragraph, heading, code, list, quote, divider, media, callout, toggle,
+     * columns, page-link, block (a @texuli/blocks block) and embed (a one-node catalog component, a
+     * deck, a sheet or a canvas).
+     */
+    blocks: readonly Readonly<Record<string, unknown>>[];
+    /** Comment threads, suggestions and named versions, kept apart from content. */
+    annotations?: Readonly<Record<string, unknown>>;
+}
+/**
+ * One RFC 6902 operation on a document. Paths are RFC 6901 pointers into the document;
+ * @texuli/document/ops refuses prototype paths and malformed escapes, applies the patch all or none
+ * and validates the result.
+ */
+export interface BlueprintDocumentPatchOperation {
+    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    path: string;
+    from?: string;
+    /** Any plain JSON value (add, replace and test). */
+    value?: unknown;
+}
+/** A bounded RFC 6902 patch (ADR-011): at most 1,000 operations; test operations are encouraged. */
+export type BlueprintDocumentPatch = readonly BlueprintDocumentPatchOperation[];
 /**
  * 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; 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.
+ * and the envelope motion level; spec 0.7.0 (ADR-011, ADR-012, ADR-014) adds an optional node key
+ * (a stable instance id, unique in the tree), the document shape a `document` node carries and the
+ * patchDocument edit op with its bounded RFC 6902 patch. Planned minor additions: the native
+ * profile and several roots.
  */
 export interface BlueprintEnvelope {
     format: 'texuli-blueprint';
@@ -253,7 +305,7 @@ 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' | '0.6.0';
+    spec?: '0.3.0' | '0.4.0' | '0.5.0' | '0.6.0' | '0.7.0';
     /**
      * Local state declarations (ADR-008), at most 64. Names, counts and per-type rules are checked by
      * the validator.

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.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
+// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
 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.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
+// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
 export {};

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

@@ -4,7 +4,7 @@ export interface SpecDiagnostic {
     message: string;
     id?: string;
 }
-export type SpecDiagnosticCode = 'schema' | 'unknown-id' | 'unknown-prop' | 'prop-type' | 'enum-value' | 'missing-required' | 'extension-prop' | 'catalog-mismatch' | 'unsupported-profile' | 'unknown-slot' | 'state' | 'unknown-state' | 'binding' | 'action' | 'unknown-event' | 'workflow';
+export type SpecDiagnosticCode = 'schema' | 'unknown-id' | 'unknown-prop' | 'prop-type' | 'enum-value' | 'missing-required' | 'extension-prop' | 'catalog-mismatch' | 'unsupported-profile' | 'unknown-slot' | 'state' | 'unknown-state' | 'binding' | 'action' | 'unknown-event' | 'workflow' | 'duplicate-key';
 export interface SpecWarning {
     code: SpecWarningCode;
     path: string;

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.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
+// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
 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.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
+// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
 export {};

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

@@ -1,7 +1,7 @@
 /** The built catalog this vocabulary was projected from. */
-export declare const SPEC_CATALOG_HASH = "4ac7ecedd1c59d1999a9f7eea2f523c7653fececb97258a478f09253f6b6057f";
+export declare const SPEC_CATALOG_HASH = "c6bd7047eba3e1f32e9ed74097c390a58416cf4260267c8958e0ea70821abf35";
 /** Every closed component id, sorted. */
-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-cohort-table", "data-files", "data-filter-builder", "data-grid", "data-map", "data-notification-inbox", "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", "time-field", "timeline", "toaster", "tooltip", "workflow-graph"];
+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-cohort-table", "data-files", "data-filter-builder", "data-grid", "data-map", "data-notification-inbox", "data-timeline", "data-tree-view", "deck-slide", "description", "detail-panel", "dialog", "document", "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", "time-field", "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 {
@@ -567,6 +567,11 @@ export interface SpecComponentProps {
         size?: 'sm' | 'md' | 'lg' | 'xl';
         title: string;
     };
+    document: {
+        doc: Readonly<Record<string, unknown>>;
+        label?: string;
+        outline?: boolean;
+    };
     drawer: {
         closeOnEscape?: boolean;
         dismissOutside?: boolean;

package/dist/generated/typescript/vocabulary.js

@@ -1,7 +1,7 @@
 // Generated by @texuli/spec from catalog/components.json. Do not edit: run the spec generator.
-// Spec 0.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
+// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
 /** The built catalog this vocabulary was projected from. */
-export const SPEC_CATALOG_HASH = '4ac7ecedd1c59d1999a9f7eea2f523c7653fececb97258a478f09253f6b6057f';
+export const SPEC_CATALOG_HASH = 'c6bd7047eba3e1f32e9ed74097c390a58416cf4260267c8958e0ea70821abf35';
 /** Every closed component id, sorted. */
 export const SPEC_COMPONENT_IDS = [
     'action-form',
@@ -76,6 +76,7 @@ export const SPEC_COMPONENT_IDS = [
     'description',
     'detail-panel',
     'dialog',
+    'document',
     'drawer',
     'dropdown-menu',
     'dropdown-menu-content',

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.6.0, digest 37141b85b9ab9f02af849a62a9c97ba729d6c5c2705130290bcdf45b308ea4cc
+// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
 export {};

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

@@ -0,0 +1,10 @@
+import type { SpecMigration } from './types.js';
+/**
+ * 0.6.0 → 0.7.0 is additive (PLAN_010 T-doc-agents, ADR-011, ADR-012 and
+ * ADR-014): nodes gain an optional `key` (a stable instance id, unique in
+ * the tree), the catalog gains the `document` id whose `doc` prop carries a
+ * Texuli document, and edit ops gain `patchDocument` (a bounded RFC 6902
+ * patch) and key addressing. Every 0.6.0 envelope is a valid 0.7.0
+ * envelope, so the step only stamps `spec`.
+ */
+export declare const migration060to070: SpecMigration;

package/dist/migrations/0.6.0-0.7.0.js

@@ -0,0 +1,13 @@
+/**
+ * 0.6.0 → 0.7.0 is additive (PLAN_010 T-doc-agents, ADR-011, ADR-012 and
+ * ADR-014): nodes gain an optional `key` (a stable instance id, unique in
+ * the tree), the catalog gains the `document` id whose `doc` prop carries a
+ * Texuli document, and edit ops gain `patchDocument` (a bounded RFC 6902
+ * patch) and key addressing. Every 0.6.0 envelope is a valid 0.7.0
+ * envelope, so the step only stamps `spec`.
+ */
+export const migration060to070 = Object.freeze({
+    from: '0.6.0',
+    to: '0.7.0',
+    migrate: (envelope) => ({ ...envelope, spec: '0.7.0' }),
+});

package/dist/migrations/index.js

@@ -4,6 +4,7 @@ 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";
+import { migration060to070 } from "./0.6.0-0.7.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`. */
@@ -12,6 +13,7 @@ export const SPEC_MIGRATIONS = Object.freeze([
     migration030to040,
     migration040to050,
     migration050to060,
+    migration060to070,
 ]);
 /**
  * Bring a blueprint envelope up to `target` (the current spec by default)

package/dist/validate.js

@@ -275,9 +275,22 @@ export function validateTree(tree, catalog, options = {}) {
     const flow = options.flow ?? null;
     const root = options.root ?? { $defs: {} };
     const warn = (warning) => options.warnings?.push(warning);
+    // Spec 0.7.0 (ADR-014): a node key is unique in its tree; the schema checks its pattern.
+    const keys = new Set();
     const visit = (node, path, depth, parent, insideForm) => {
         if (!isRecord(node) || typeof node.id !== 'string' || depth > MAX_TREE_DEPTH)
             return;
+        if (typeof node.key === 'string' && SPEC_REGEX.nodeKey.test(node.key)) {
+            if (keys.has(node.key)) {
+                out.push({
+                    code: 'duplicate-key',
+                    path: `${path}.key`,
+                    id: node.id,
+                    message: `The key "${node.key.slice(0, 64)}" is already used in this tree.`,
+                });
+            }
+            keys.add(node.key);
+        }
         checkSlot(node.slot, parent, node.id, path, out);
         const component = byId.get(node.id);
         const context = reportInto({

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The semantic version of the spec documents in this package. */
-export declare const SPEC_VERSION = "0.6.0";
+export declare const SPEC_VERSION = "0.7.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** The semantic version of the spec documents in this package. */
-export const SPEC_VERSION = '0.6.0';
+export const SPEC_VERSION = '0.7.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texuli/spec",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The schema-first blueprint contract: JSON schemas, the catalog vocabulary, deterministic TypeScript and Kotlin projections, and the conformance harness.",
   "keywords": [
     "svelte",