@flighthq/scene-document 0.4.1-next.560.2e86cd6 → 0.5.1-edge.1047.858b9b6

package/README.md

@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/scene-document`. The
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/scene-document@0.4.1-next.560.2e86cd6](https://github.com/flighthq/flight/tree/2e86cd620a53121aa6c9230215f44c6c9a3bf816/packages/scene-document)
-- [License](https://github.com/flighthq/flight/blob/2e86cd620a53121aa6c9230215f44c6c9a3bf816/LICENSE.md)
+- [Source for @flighthq/scene-document@0.5.1-edge.1047.858b9b6](https://github.com/flighthq/flight/tree/858b9b601de814f6b6940cbb1ffff0916b903268/packages/scene-document)
+- [License](https://github.com/flighthq/flight/blob/858b9b601de814f6b6940cbb1ffff0916b903268/LICENSE.md)

package/dist/contract.d.ts

@@ -1,4 +1,6 @@
 export { explainFlightDocumentText, formatFlightDocumentText, parseFlightDocumentText } from './flightDocumentText';
+export { getFlightDocumentResourceDependencies } from './flightDocumentResourceDependencies';
 export { createFlightDocumentFromScene2D, createFlightDocumentScene2DMaterialization, createFlightDocumentScene2DMaterializationFromText, explainFlightDocumentRefusal, explainFlightDocumentRefusalFromText, } from './sceneDocumentScene2DMaterialization';
 export { createFlightDocumentFromScene3D, createFlightDocumentScene3DMaterialization, createFlightDocumentScene3DMaterializationFromText, explainFlightDocumentScene3DRefusal, explainFlightDocumentScene3DRefusalFromText, } from './sceneDocumentScene3DMaterialization';
+export { initializeDocumentRefusal } from './sceneDocumentRefusal';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,4BAA4B,EAC5B,oCAAoC,GACrC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,mCAAmC,EACnC,2CAA2C,GAC5C,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EAAE,qCAAqC,EAAE,MAAM,sCAAsC,CAAC;AAC7F,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,4BAA4B,EAC5B,oCAAoC,GACrC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,mCAAmC,EACnC,2CAA2C,GAC5C,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/contract.js

@@ -1,4 +1,6 @@
 export { explainFlightDocumentText, formatFlightDocumentText, parseFlightDocumentText } from './flightDocumentText';
+export { getFlightDocumentResourceDependencies } from './flightDocumentResourceDependencies';
 export { createFlightDocumentFromScene2D, createFlightDocumentScene2DMaterialization, createFlightDocumentScene2DMaterializationFromText, explainFlightDocumentRefusal, explainFlightDocumentRefusalFromText, } from './sceneDocumentScene2DMaterialization';
 export { createFlightDocumentFromScene3D, createFlightDocumentScene3DMaterialization, createFlightDocumentScene3DMaterializationFromText, explainFlightDocumentScene3DRefusal, explainFlightDocumentScene3DRefusalFromText, } from './sceneDocumentScene3DMaterialization';
+export { initializeDocumentRefusal } from './sceneDocumentRefusal';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,4BAA4B,EAC5B,oCAAoC,GACrC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,mCAAmC,EACnC,2CAA2C,GAC5C,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EAAE,qCAAqC,EAAE,MAAM,sCAAsC,CAAC;AAC7F,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,4BAA4B,EAC5B,oCAAoC,GACrC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,+BAA+B,EAC/B,0CAA0C,EAC1C,kDAAkD,EAClD,mCAAmC,EACnC,2CAA2C,GAC5C,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/flightDocumentResourceDependencies.d.ts

@@ -0,0 +1,3 @@
+import type { FlightDocument, FlightDocumentResourceDescriptor, FlightDocumentSchemaRegistry } from '@flighthq/types/contract';
+export declare function getFlightDocumentResourceDependencies(document: Readonly<FlightDocument>, schemas: Readonly<FlightDocumentSchemaRegistry>): readonly Readonly<FlightDocumentResourceDescriptor>[] | null;
+//# sourceMappingURL=flightDocumentResourceDependencies.d.ts.map

package/dist/flightDocumentResourceDependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flightDocumentResourceDependencies.d.ts","sourceRoot":"","sources":["../src/flightDocumentResourceDependencies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,gCAAgC,EAChC,4BAA4B,EAC7B,MAAM,0BAA0B,CAAC;AAKlC,wBAAgB,qCAAqC,CACnD,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAClC,OAAO,EAAE,QAAQ,CAAC,4BAA4B,CAAC,GAC9C,SAAS,QAAQ,CAAC,gCAAgC,CAAC,EAAE,GAAG,IAAI,CAK9D"}

package/dist/flightDocumentResourceDependencies.js

@@ -0,0 +1,12 @@
+import { getRegistryTableEntry } from '@flighthq/registry/contract';
+// The resource table is the document's direct dependency list. This query verifies that every declared
+// kind has an authored schema, but deliberately does not interpret fields as graph edges or resolve any
+// live resource: traversal and loading policy belong to their callers.
+export function getFlightDocumentResourceDependencies(document, schemas) {
+    for (const descriptor of document.resources) {
+        if (getRegistryTableEntry(schemas.resourceSchemas, descriptor.kind) === null)
+            return null;
+    }
+    return document.resources;
+}
+//# sourceMappingURL=flightDocumentResourceDependencies.js.map

package/dist/flightDocumentResourceDependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flightDocumentResourceDependencies.js","sourceRoot":"","sources":["../src/flightDocumentResourceDependencies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAOpE,uGAAuG;AACvG,wGAAwG;AACxG,uEAAuE;AACvE,MAAM,UAAU,qCAAqC,CACnD,QAAkC,EAClC,OAA+C;IAE/C,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC5C,IAAI,qBAAqB,CAAC,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAC5F,CAAC;IACD,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC"}

package/dist/flightDocumentText.d.ts

@@ -1,5 +1,7 @@
-import type { FlightDocument, FlightDocumentRefusalExplanation, FlightDocumentText } from '@flighthq/types/contract';
+import type { EntityConstruction, FlightDocument, FlightDocumentRefusalExplanation, FlightDocumentText } from '@flighthq/types/contract';
+import { FlightDocumentRefusalReason } from '@flighthq/types/contract';
 export declare function explainFlightDocumentText(text: FlightDocumentText): FlightDocumentRefusalExplanation | null;
 export declare function formatFlightDocumentText(document: Readonly<FlightDocument>): FlightDocumentText;
+export declare function initializeFlightDocumentRefusalExplanation(out: EntityConstruction<FlightDocumentRefusalExplanation>, actual: number | null, column: number | null, kind: string | null, limit: number | null, line: number | null, mode: string | null, offset: number | null, path: string, reason: FlightDocumentRefusalReason, resourceKey: string | null, tokenKey: string | null, version: number | null): void;
 export declare function parseFlightDocumentText(text: FlightDocumentText): FlightDocument | null;
 //# sourceMappingURL=flightDocumentText.d.ts.map

package/dist/flightDocumentText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flightDocumentText.d.ts","sourceRoot":"","sources":["../src/flightDocumentText.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EAGd,gCAAgC,EAKhC,kBAAkB,EAOnB,MAAM,0BAA0B,CAAC;AAMlC,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,kBAAkB,GAAG,gCAAgC,GAAG,IAAI,CAE3G;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAsB/F;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,GAAG,IAAI,CAEvF"}
+{"version":3,"file":"flightDocumentText.d.ts","sourceRoot":"","sources":["../src/flightDocumentText.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EASd,gCAAgC,EAKhC,kBAAkB,EASnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAoB,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAKzF,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,kBAAkB,GAAG,gCAAgC,GAAG,IAAI,CAE3G;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAsB/F;AAED,wBAAgB,0CAA0C,CACxD,GAAG,EAAE,kBAAkB,CAAC,gCAAgC,CAAC,EACzD,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,2BAA2B,EACnC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,IAAI,CAaN;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,GAAG,IAAI,CAEvF"}

package/dist/flightDocumentText.js

@@ -1,3 +1,5 @@
+import { createOrthographicProjection, createPerspectiveProjection } from '@flighthq/camera/contract';
+import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
 import { createTransform3D } from '@flighthq/geometry/contract';
 import { EntityRuntimeKey, FlightDocumentRefusalReason } from '@flighthq/types/contract';
 import { createDocumentRefusal } from './sceneDocumentRefusal';
@@ -28,6 +30,20 @@ export function formatFlightDocumentText(document) {
     }
     return text;
 }
+export function initializeFlightDocumentRefusalExplanation(out, actual, column, kind, limit, line, mode, offset, path, reason, resourceKey, tokenKey, version) {
+    out.actual = actual;
+    out.column = column;
+    out.kind = kind;
+    out.limit = limit;
+    out.line = line;
+    out.mode = mode;
+    out.offset = offset;
+    out.path = path;
+    out.reason = reason;
+    out.resourceKey = resourceKey;
+    out.tokenKey = tokenKey;
+    out.version = version;
+}
 export function parseFlightDocumentText(text) {
     return readFlightDocumentText(text).document;
 }
@@ -88,6 +104,7 @@ function appendNode(lines, node, indent) {
     const prefix = ' '.repeat(indent);
     lines.push(prefix + 'kind: ' + formatString(node.kind));
     appendFields(lines, node.fields, indent, NODE_RESERVED_FIELDS);
+    appendNodeInteractiveMetadata(lines, node, indent);
     if (node.children.length > 0) {
         lines.push(prefix + 'children:');
         for (const child of node.children)
@@ -98,12 +115,67 @@ function appendNodeSequenceItem(lines, node, indent) {
     const prefix = ' '.repeat(indent);
     lines.push(prefix + '- kind: ' + formatString(node.kind));
     appendFields(lines, node.fields, indent + 2, NODE_RESERVED_FIELDS);
+    appendNodeInteractiveMetadata(lines, node, indent + 2);
     if (node.children.length > 0) {
         lines.push(prefix + '  children:');
         for (const child of node.children)
             appendNodeSequenceItem(lines, child, indent + 4);
     }
 }
+function appendInteractiveState(lines, state, indent) {
+    const entries = getInteractiveStateEntries(state);
+    if (entries.length === 0 && state.extensions.length === 0) {
+        throw new TypeError('FlightDocument interactive state must not be empty');
+    }
+    for (const [property, value] of entries)
+        appendMappingEntry(lines, property, value, indent);
+    if (state.extensions.length === 0)
+        return;
+    lines.push(' '.repeat(indent) + 'extensions:');
+    for (const extension of state.extensions) {
+        lines.push(' '.repeat(indent + 2) + '- kind: ' + formatString(extension.kind));
+        appendFields(lines, extension.fields, indent + 4, DESCRIPTOR_RESERVED_FIELDS);
+    }
+}
+function appendNodeInteractiveMetadata(lines, node, indent) {
+    const prefix = ' '.repeat(indent);
+    if (node.interactiveStates == null) {
+        if (node.transition != null)
+            throw new TypeError('FlightDocument transition requires interactiveStates');
+        return;
+    }
+    const phases = getInteractiveStatePhases(node.interactiveStates);
+    if (phases.length === 0)
+        throw new TypeError('FlightDocument interactiveStates must not be empty');
+    lines.push(prefix + 'interactiveStates:');
+    for (const [phase, state] of phases) {
+        lines.push(prefix + '  ' + phase + ':');
+        appendInteractiveState(lines, state, indent + 4);
+    }
+    if (node.transition != null) {
+        lines.push(prefix + 'transition:');
+        lines.push(prefix + '  kind: ' + formatString(node.transition.kind));
+        appendFields(lines, node.transition.fields, indent + 2, DESCRIPTOR_RESERVED_FIELDS);
+    }
+}
+function getInteractiveStateEntries(state) {
+    const out = [];
+    for (const property of INTERACTIVE_STATE_PROPERTIES) {
+        const value = state[property];
+        if (value !== undefined)
+            out.push([property, value]);
+    }
+    return out;
+}
+function getInteractiveStatePhases(states) {
+    const out = [];
+    for (const phase of INTERACTIVE_STATE_PHASES) {
+        const state = states[phase];
+        if (state !== null)
+            out.push([phase, state]);
+    }
+    return out;
+}
 function appendObjectEntries(lines, value, indent, reserved) {
     for (const [key, entry] of Object.entries(value).sort(([left], [right]) => left.localeCompare(right))) {
         if (reserved.includes(key))
@@ -153,6 +225,60 @@ function appendScene(lines, scene) {
     }
     lines.push('    scene:');
     appendNode(lines, scene.scene, 6);
+    appendLayouts(lines, scene.layouts);
+    appendTokens(lines, scene.tokens);
+}
+function appendLayouts(lines, layouts) {
+    if (layouts.length === 0)
+        return;
+    const seenTargets = new Set();
+    lines.push('    layouts:');
+    for (const layout of layouts) {
+        const nodes = layout.tree.nodes;
+        if (nodes.length === 0)
+            throw new RangeError('FlightDocument layout tree must not be empty');
+        if (layout.targets.length !== nodes.length) {
+            throw new RangeError('FlightDocument layout targets must match its tree nodes index-for-index');
+        }
+        lines.push('      - targets:');
+        for (const target of layout.targets) {
+            if (target.length === 0)
+                throw new RangeError('FlightDocument layout target names must not be empty');
+            if (seenTargets.has(target))
+                throw new RangeError('FlightDocument layout targets must be unique per scene');
+            seenTargets.add(target);
+            lines.push('          - ' + formatString(target));
+        }
+        lines.push('        tree:');
+        lines.push('          nodes:');
+        for (let index = 0; index < nodes.length; index++)
+            appendLayoutNode(lines, nodes[index], index);
+    }
+}
+function appendLayoutNode(lines, node, index) {
+    if (node.kind.length === 0)
+        throw new RangeError('FlightDocument layout node kinds must not be empty');
+    if (!Number.isInteger(node.parentIndex) || node.parentIndex < -1 || node.parentIndex >= index) {
+        throw new RangeError('FlightDocument layout parentIndex must be -1 or precede its node');
+    }
+    lines.push('            - kind: ' + formatString(node.kind));
+    lines.push('              parentIndex: ' + String(node.parentIndex));
+    if (node.containerStyle !== null)
+        appendMappingEntry(lines, 'containerStyle', node.containerStyle, 14);
+    if (node.itemStyle !== null)
+        appendMappingEntry(lines, 'itemStyle', node.itemStyle, 14);
+}
+function appendTokens(lines, tokens) {
+    if (tokens.length === 0)
+        return;
+    lines.push('    tokens:');
+    for (const token of tokens) {
+        lines.push('      - kind: ' + formatString(token.kind));
+        lines.push('        key: ' + formatString(token.key));
+        // Mode names are sorted so a formatted document is stable, while the token ROWS keep the order
+        // they were authored in: row order is the author's, mode order is not meaningful.
+        appendFields(lines, token.values, 8, TOKEN_RESERVED_FIELDS);
+    }
 }
 function appendSequence(lines, values, indent) {
     const prefix = ' '.repeat(indent);
@@ -300,18 +426,11 @@ function readFlightDocumentText(text) {
     if (!parsed.ok) {
         return {
             document: null,
-            refusal: {
-                actual: parsed.actual,
-                column: parsed.column,
-                kind: null,
-                limit: parsed.limit,
-                line: parsed.line,
-                offset: parsed.offset,
-                path: '',
-                reason: parsed.kind,
-                resourceKey: null,
-                version: null,
-            },
+            refusal: (() => {
+                const out = allocateEntity();
+                initializeFlightDocumentRefusalExplanation(out, parsed.actual, parsed.column, null, parsed.limit, parsed.line, null, parsed.offset, '', parsed.kind, null, null, null);
+                return finishEntity(out);
+            })(),
         };
     }
     const context = { refusal: null };
@@ -409,7 +528,83 @@ function readLight(value, path, context) {
         light.node = node;
     return light;
 }
-function readNode(value, path, context) {
+function readInteractiveState(value, path, dimension, context) {
+    if (!isMapping(value) || !hasOnlyKeys(value, INTERACTIVE_STATE_KEYS))
+        return refuse(context, path);
+    const state = { extensions: [] };
+    for (const property of INTERACTIVE_STATE_PROPERTIES) {
+        const propertyValue = value[property];
+        if (propertyValue === undefined)
+            continue;
+        if (property === 'visible') {
+            if (typeof propertyValue !== 'boolean')
+                return refuse(context, appendPath(path, property));
+        }
+        else if (typeof propertyValue !== 'number' || !Number.isFinite(propertyValue)) {
+            return refuse(context, appendPath(path, property));
+        }
+        if (dimension === 'Scene3D' && INTERACTIVE_STATE_2D_PROPERTIES.includes(property)) {
+            return refuse(context, appendPath(path, property));
+        }
+        Object.assign(state, { [property]: propertyValue });
+    }
+    const extensionsRaw = value['extensions'];
+    if (extensionsRaw !== undefined) {
+        if (!Array.isArray(extensionsRaw))
+            return refuse(context, appendPath(path, 'extensions'));
+        const kinds = new Set();
+        for (let i = 0; i < extensionsRaw.length; i++) {
+            const extensionPath = `${path}.extensions[${i}]`;
+            const extension = readInteractiveStateExtension(extensionsRaw[i], extensionPath, context);
+            if (extension === null)
+                return null;
+            if (kinds.has(extension.kind)) {
+                return refuseWithReason(context, FlightDocumentRefusalReason.InteractiveStateExtensionKindDuplicate, extensionPath, extension.kind);
+            }
+            kinds.add(extension.kind);
+            state.extensions.push(extension);
+        }
+    }
+    if (getInteractiveStateEntries(state).length === 0 && state.extensions.length === 0)
+        return refuse(context, path);
+    return state;
+}
+function readInteractiveStateExtension(value, path, context) {
+    if (!isMapping(value))
+        return refuse(context, path);
+    const kind = value['kind'];
+    if (typeof kind !== 'string')
+        return refuse(context, appendPath(path, 'kind'));
+    const fields = copyFlightDocumentFields(value, DESCRIPTOR_RESERVED_FIELDS, path, context);
+    return fields === null ? null : { fields, kind };
+}
+function readInteractiveStates(value, path, dimension, context) {
+    if (!isMapping(value) || !hasOnlyKeys(value, INTERACTIVE_STATE_PHASES))
+        return refuse(context, path);
+    const states = { disabled: null, hover: null, pressed: null };
+    let count = 0;
+    for (const phase of INTERACTIVE_STATE_PHASES) {
+        const stateRaw = value[phase];
+        if (stateRaw === undefined)
+            continue;
+        const state = readInteractiveState(stateRaw, appendPath(path, phase), dimension, context);
+        if (state === null)
+            return null;
+        states[phase] = state;
+        count++;
+    }
+    return count === 0 ? refuse(context, path) : states;
+}
+function readInteractiveStateTransition(value, path, context) {
+    if (!isMapping(value))
+        return refuse(context, path);
+    const kind = value['kind'];
+    if (typeof kind !== 'string')
+        return refuse(context, appendPath(path, 'kind'));
+    const fields = copyFlightDocumentFields(value, DESCRIPTOR_RESERVED_FIELDS, path, context);
+    return fields === null ? null : { fields, kind };
+}
+function readNode(value, path, dimension, context) {
     if (!isMapping(value))
         return refuse(context, path);
     const kind = value['kind'];
@@ -421,14 +616,30 @@ function readNode(value, path, context) {
         if (!Array.isArray(childrenRaw))
             return refuse(context, appendPath(path, 'children'));
         for (let index = 0; index < childrenRaw.length; index++) {
-            const child = readNode(childrenRaw[index], `${path}.children[${index}]`, context);
+            const child = readNode(childrenRaw[index], `${path}.children[${index}]`, dimension, context);
             if (child === null)
                 return null;
             children.push(child);
         }
     }
+    const interactiveStatesRaw = value['interactiveStates'];
+    let interactiveStates = null;
+    if (interactiveStatesRaw !== undefined) {
+        interactiveStates = readInteractiveStates(interactiveStatesRaw, appendPath(path, 'interactiveStates'), dimension, context);
+        if (interactiveStates === null)
+            return null;
+    }
+    const transitionRaw = value['transition'];
+    if (transitionRaw !== undefined && interactiveStates === null)
+        return refuse(context, appendPath(path, 'transition'));
+    let transition = null;
+    if (transitionRaw !== undefined) {
+        transition = readInteractiveStateTransition(transitionRaw, appendPath(path, 'transition'), context);
+        if (transition === null)
+            return null;
+    }
     const fields = copyFlightDocumentFields(value, NODE_RESERVED_FIELDS, path, context);
-    return fields === null ? null : { children, fields, kind };
+    return fields === null ? null : { children, fields, interactiveStates, kind, transition };
 }
 function readOptionalIndex(value, path, context) {
     if (value === undefined)
@@ -451,7 +662,7 @@ function readProjection(value, path, context) {
             return refuse(context, appendPath(path, 'halfHeight'));
         if (typeof halfWidth !== 'number')
             return refuse(context, appendPath(path, 'halfWidth'));
-        return { halfHeight, halfWidth, kind };
+        return createOrthographicProjection({ halfHeight, halfWidth });
     }
     if (kind === 'perspective') {
         if (!hasOnlyKeys(value, PERSPECTIVE_PROJECTION_KEYS))
@@ -462,7 +673,7 @@ function readProjection(value, path, context) {
             return refuse(context, appendPath(path, 'aspect'));
         if (typeof fovY !== 'number')
             return refuse(context, appendPath(path, 'fovY'));
-        return { aspect, fovY, kind };
+        return createPerspectiveProjection({ aspect, fovY });
     }
     return refuse(context, appendPath(path, 'kind'));
 }
@@ -519,10 +730,16 @@ function readScene2D(mapping, path, context) {
     if (backgroundColor !== undefined && backgroundColor !== null && typeof backgroundColor !== 'number') {
         return refuse(context, appendPath(path, 'backgroundColor'));
     }
-    const scene = readNode(mapping['scene'], appendPath(path, 'scene'), context);
+    const scene = readNode(mapping['scene'], appendPath(path, 'scene'), 'Scene2D', context);
     if (scene === null)
         return null;
-    return { backgroundColor: backgroundColor ?? null, kind: 'Scene2D', scene };
+    const layouts = readLayouts(mapping['layouts'], path, context);
+    if (layouts === null)
+        return null;
+    const tokens = readTokens(mapping['tokens'], path, context);
+    if (tokens === null)
+        return null;
+    return { backgroundColor: backgroundColor ?? null, kind: 'Scene2D', layouts, scene, tokens };
 }
 function readScene3D(mapping, path, context) {
     if (!hasOnlyKeys(mapping, SCENE_3D_KEYS))
@@ -551,10 +768,134 @@ function readScene3D(mapping, path, context) {
             lights.push(light);
         }
     }
-    const scene = readNode(mapping['scene'], appendPath(path, 'scene'), context);
+    const scene = readNode(mapping['scene'], appendPath(path, 'scene'), 'Scene3D', context);
     if (scene === null)
         return null;
-    return { cameras, kind: 'Scene3D', lights, scene };
+    const layouts = readLayouts(mapping['layouts'], path, context);
+    if (layouts === null)
+        return null;
+    const tokens = readTokens(mapping['tokens'], path, context);
+    if (tokens === null)
+        return null;
+    return { cameras, kind: 'Scene3D', layouts, lights, scene, tokens };
+}
+function readLayouts(value, scenePath, context) {
+    if (value === undefined)
+        return [];
+    const layoutsPath = appendPath(scenePath, 'layouts');
+    if (!Array.isArray(value))
+        return refuse(context, layoutsPath);
+    const layouts = [];
+    const seenTargets = new Set();
+    for (let layoutIndex = 0; layoutIndex < value.length; layoutIndex++) {
+        const layoutPath = `${layoutsPath}[${layoutIndex}]`;
+        const raw = value[layoutIndex];
+        if (!isMapping(raw) || !hasOnlyKeys(raw, LAYOUT_KEYS))
+            return refuse(context, layoutPath);
+        const targetsPath = appendPath(layoutPath, 'targets');
+        const targetsRaw = raw['targets'];
+        if (!Array.isArray(targetsRaw) || targetsRaw.length === 0)
+            return refuse(context, targetsPath);
+        const targets = [];
+        for (let targetIndex = 0; targetIndex < targetsRaw.length; targetIndex++) {
+            const targetPath = `${targetsPath}[${targetIndex}]`;
+            const target = targetsRaw[targetIndex];
+            if (typeof target !== 'string' || target.length === 0 || seenTargets.has(target)) {
+                return refuse(context, targetPath);
+            }
+            seenTargets.add(target);
+            targets.push(target);
+        }
+        const treePath = appendPath(layoutPath, 'tree');
+        const treeRaw = raw['tree'];
+        if (!isMapping(treeRaw) || !hasOnlyKeys(treeRaw, LAYOUT_TREE_KEYS))
+            return refuse(context, treePath);
+        const nodesPath = appendPath(treePath, 'nodes');
+        const nodesRaw = treeRaw['nodes'];
+        if (!Array.isArray(nodesRaw) || nodesRaw.length === 0)
+            return refuse(context, nodesPath);
+        const nodes = [];
+        for (let nodeIndex = 0; nodeIndex < nodesRaw.length; nodeIndex++) {
+            const node = readLayoutNode(nodesRaw[nodeIndex], nodeIndex, `${nodesPath}[${nodeIndex}]`, context);
+            if (node === null)
+                return null;
+            nodes.push(node);
+        }
+        if (targets.length !== nodes.length)
+            return refuse(context, targetsPath);
+        layouts.push({ targets, tree: { nodes } });
+    }
+    return layouts;
+}
+function readLayoutNode(value, index, path, context) {
+    if (!isMapping(value) || !hasOnlyKeys(value, LAYOUT_NODE_KEYS))
+        return refuse(context, path);
+    const kind = value['kind'];
+    if (typeof kind !== 'string' || kind.length === 0)
+        return refuse(context, appendPath(path, 'kind'));
+    const parentIndex = value['parentIndex'];
+    if (!Number.isInteger(parentIndex) || parentIndex < -1 || parentIndex >= index) {
+        return refuse(context, appendPath(path, 'parentIndex'));
+    }
+    const containerStyle = readLayoutStyle(value['containerStyle'], appendPath(path, 'containerStyle'), context);
+    if (containerStyle === INVALID_LAYOUT_STYLE)
+        return null;
+    const itemStyle = readLayoutStyle(value['itemStyle'], appendPath(path, 'itemStyle'), context);
+    if (itemStyle === INVALID_LAYOUT_STYLE)
+        return null;
+    return { containerStyle, itemStyle, kind, parentIndex: parentIndex };
+}
+function readLayoutStyle(value, path, context) {
+    if (value === undefined || value === null)
+        return null;
+    if (!isMapping(value)) {
+        refuse(context, path);
+        return INVALID_LAYOUT_STYLE;
+    }
+    const fields = copyFlightDocumentFields(value, [], path, context);
+    return fields ?? INVALID_LAYOUT_STYLE;
+}
+function readTokens(value, path, context) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        return refuse(context, appendPath(path, 'tokens'));
+    const tokens = [];
+    const seen = new Set();
+    for (let index = 0; index < value.length; index++) {
+        const rowPath = `${path}.tokens[${index}]`;
+        const raw = value[index];
+        if (!isMapping(raw))
+            return refuse(context, rowPath);
+        const kind = raw['kind'];
+        const key = raw['key'];
+        if (typeof kind !== 'string')
+            return refuse(context, appendPath(rowPath, 'kind'));
+        if (typeof key !== 'string')
+            return refuse(context, appendPath(rowPath, 'key'));
+        if (!SAFE_PLAIN_SCALAR_PATTERN.test(key)) {
+            return refuseToken(context, FlightDocumentRefusalReason.TokenKeyInvalid, appendPath(rowPath, 'key'), key, null);
+        }
+        if (seen.has(key)) {
+            return refuseToken(context, FlightDocumentRefusalReason.TokenKeyDuplicate, appendPath(rowPath, 'key'), key, null);
+        }
+        seen.add(key);
+        const values = {};
+        for (const mode of Object.keys(raw)) {
+            if (TOKEN_RESERVED_FIELDS.includes(mode))
+                continue;
+            const modePath = appendPath(rowPath, mode);
+            if (!SAFE_PLAIN_SCALAR_PATTERN.test(mode)) {
+                return refuseToken(context, FlightDocumentRefusalReason.TokenModeInvalid, modePath, key, mode);
+            }
+            const modeValue = copyFlightDocumentValue(raw[mode], modePath, context);
+            if (modeValue === INVALID_FLIGHT_DOCUMENT_VALUE)
+                return null;
+            values[mode] = modeValue;
+        }
+        tokens.push({ key, kind, values });
+    }
+    return tokens;
 }
 function readTransform3D(value, path, context) {
     if (!isMapping(value) || !hasOnlyKeys(value, TRANSFORM_3D_KEYS))
@@ -592,6 +933,20 @@ function refuse(context, path) {
     context.refusal ??= createDocumentRefusal(FlightDocumentRefusalReason.StructureInvalid, path);
     return null;
 }
+function refuseWithReason(context, reason, path, kind) {
+    if (context.refusal === null) {
+        context.refusal = createDocumentRefusal(reason, path);
+        context.refusal.kind = kind;
+    }
+    return null;
+}
+function refuseToken(context, reason, path, tokenKey, mode) {
+    const refusal = createDocumentRefusal(reason, path);
+    refusal.mode = mode;
+    refusal.tokenKey = tokenKey;
+    context.refusal ??= refusal;
+    return null;
+}
 function refuseValue(context, reason, path) {
     context.refusal ??= createDocumentRefusal(reason, path);
     return INVALID_FLIGHT_DOCUMENT_VALUE;
@@ -600,18 +955,30 @@ function appendPath(path, key) {
     return path === '' ? key : path + '.' + key;
 }
 const INVALID_FLIGHT_DOCUMENT_VALUE = Symbol('invalid-flight-document-value');
+const INVALID_LAYOUT_STYLE = Symbol('invalid-layout-style');
 const INVALID_OPTIONAL_INDEX = Symbol('invalid-flight-document-optional-index');
 const CAMERA_KEYS = ['far', 'name', 'near', 'node', 'projection', 'transform'];
+const DESCRIPTOR_RESERVED_FIELDS = ['kind'];
 const DOCUMENT_KEYS = ['defaultScene', 'flight', 'resources', 'scenes'];
+const INTERACTIVE_STATE_2D_PROPERTIES = ['scaleX', 'scaleY', 'x', 'y'];
+const INTERACTIVE_STATE_KEYS = ['alpha', 'extensions', 'scaleX', 'scaleY', 'visible', 'x', 'y'];
+const INTERACTIVE_STATE_PHASES = ['disabled', 'hover', 'pressed'];
+const INTERACTIVE_STATE_PROPERTIES = ['alpha', 'scaleX', 'scaleY', 'visible', 'x', 'y'];
 const LIGHT_KEYS = ['descriptor', 'name', 'node', 'transform'];
-const NODE_RESERVED_FIELDS = ['children', 'kind'];
+const LAYOUT_KEYS = ['targets', 'tree'];
+const LAYOUT_NODE_KEYS = ['containerStyle', 'itemStyle', 'kind', 'parentIndex'];
+const LAYOUT_TREE_KEYS = ['nodes'];
+const NODE_RESERVED_FIELDS = ['children', 'interactiveStates', 'kind', 'transition'];
 const ORTHOGRAPHIC_PROJECTION_KEYS = ['halfHeight', 'halfWidth', 'kind'];
 const PERSPECTIVE_PROJECTION_KEYS = ['aspect', 'fovY', 'kind'];
 const QUATERNION_KEYS = ['w', 'x', 'y', 'z'];
 const RESOURCE_RESERVED_FIELDS = ['key', 'kind'];
 const SAFE_PLAIN_SCALAR_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
-const SCENE_2D_KEYS = ['backgroundColor', 'kind', 'scene'];
-const SCENE_3D_KEYS = ['cameras', 'kind', 'lights', 'scene'];
+const SCENE_2D_KEYS = ['backgroundColor', 'kind', 'layouts', 'scene', 'tokens'];
+const SCENE_3D_KEYS = ['cameras', 'kind', 'layouts', 'lights', 'scene', 'tokens'];
+// A token row flattens its mode variants beside kind and key, exactly as a resource row flattens
+// its fields, so these two names are structural and can never be authored as mode names.
+const TOKEN_RESERVED_FIELDS = ['key', 'kind'];
 const TRANSFORM_3D_KEYS = ['position', 'rotation', 'scale'];
 const VECTOR_3_KEYS = ['x', 'y', 'z'];
 //# sourceMappingURL=flightDocumentText.js.map