@flighthq/scene-document 0.5.1-next.903.f434bc2 → 0.5.1-next.905.5fbf787

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.5.1-next.903.f434bc2](https://github.com/flighthq/flight/tree/f434bc233778d75aeea61995df3a8cfaec459a85/packages/scene-document)
-- [License](https://github.com/flighthq/flight/blob/f434bc233778d75aeea61995df3a8cfaec459a85/LICENSE.md)
+- [Source for @flighthq/scene-document@0.5.1-next.905.5fbf787](https://github.com/flighthq/flight/tree/5fbf7874064c384307542d68b4dcb6a895ff0dcf/packages/scene-document)
+- [License](https://github.com/flighthq/flight/blob/5fbf7874064c384307542d68b4dcb6a895ff0dcf/LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/scene-document",
-  "version": "0.5.1-next.903.f434bc2",
+  "version": "0.5.1-next.905.5fbf787",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,15 +38,15 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/camera": "0.5.1-next.903.f434bc2",
-    "@flighthq/entity": "0.5.1-next.903.f434bc2",
-    "@flighthq/geometry": "0.5.1-next.903.f434bc2",
-    "@flighthq/lighting": "0.5.1-next.903.f434bc2",
-    "@flighthq/node": "0.5.1-next.903.f434bc2",
-    "@flighthq/registry": "0.5.1-next.903.f434bc2",
-    "@flighthq/scene2d": "0.5.1-next.903.f434bc2",
-    "@flighthq/scene3d": "0.5.1-next.903.f434bc2",
-    "@flighthq/types": "0.5.1-next.903.f434bc2"
+    "@flighthq/camera": "0.5.1-next.905.5fbf787",
+    "@flighthq/entity": "0.5.1-next.905.5fbf787",
+    "@flighthq/geometry": "0.5.1-next.905.5fbf787",
+    "@flighthq/lighting": "0.5.1-next.905.5fbf787",
+    "@flighthq/node": "0.5.1-next.905.5fbf787",
+    "@flighthq/registry": "0.5.1-next.905.5fbf787",
+    "@flighthq/scene2d": "0.5.1-next.905.5fbf787",
+    "@flighthq/scene3d": "0.5.1-next.905.5fbf787",
+    "@flighthq/types": "0.5.1-next.905.5fbf787"
   },
   "devDependencies": {
     "@flighthq/camera": "*",

package/src/flightDocumentText.test.ts

@@ -3,7 +3,12 @@ import { createAmbientLight } from '@flighthq/lighting/contract';
 import type { FlightDocument } from '@flighthq/types/contract';
 import { FlightDocumentRefusalReason } from '@flighthq/types/contract';
 
-import { explainFlightDocumentText, formatFlightDocumentText, parseFlightDocumentText } from './flightDocumentText';
+import {
+  explainFlightDocumentText,
+  formatFlightDocumentText,
+  initializeFlightDocumentRefusalExplanation,
+  parseFlightDocumentText,
+} from './flightDocumentText';
 import { parseSceneDocumentYamlSubset } from './sceneDocumentYamlSubset';
 
 describe('explainFlightDocumentText', () => {
@@ -265,6 +270,11 @@ describe('formatFlightDocumentText', () => {
   });
 });
 
+describe('initializeFlightDocumentRefusalExplanation', () => {
+  it('is the construction initializer of createFlightDocumentRefusalExplanation', () => {
+    expect(typeof initializeFlightDocumentRefusalExplanation).toBe('function');
+  });
+});
 describe('parseFlightDocumentText', () => {
   it('parses mixed dimensions over one shared resource table', () => {
     const document = parseFlightDocumentText(

package/src/sceneDocumentRefusal.test.ts

@@ -18,6 +18,7 @@ import {
   checkUnregisteredNodeKindsFromRaw,
   createDocumentRefusal,
   createSceneRefusal,
+  initializeDocumentRefusal,
 } from './sceneDocumentRefusal';
 
 describe('checkFlightDocumentFields', () => {
@@ -225,3 +226,8 @@ function createTestSchemas(registeredKind: string): FlightDocumentSchemaRegistry
     shapeCommandSchemas: createKeyedTable('flight-document.shape-command', 'none'),
   };
 }
+describe('initializeDocumentRefusal', () => {
+  it('is the construction initializer of createDocumentRefusal', () => {
+    expect(typeof initializeDocumentRefusal).toBe('function');
+  });
+});

package/src/sceneDocumentScene2DMaterialization.test.ts

@@ -31,6 +31,8 @@ import {
   createFlightDocumentScene2DMaterializationFromText,
   explainFlightDocumentRefusal,
   explainFlightDocumentRefusalFromText,
+  initializeFlightDocumentFromScene2D,
+  initializeFlightDocumentScene2DMaterialization,
 } from './sceneDocumentScene2DMaterialization';
 
 describe('createFlightDocumentFromScene2D', () => {
@@ -574,6 +576,109 @@ describe('formatFlightDocumentText', () => {
   });
 });
 
+describe('initializeFlightDocumentFromScene2D', () => {
+  it('is the construction initializer of createFlightDocumentFromScene2D', () => {
+    expect(typeof initializeFlightDocumentFromScene2D).toBe('function');
+  });
+});
+
+describe('initializeFlightDocumentScene2DMaterialization', () => {
+  it('is the construction initializer of createFlightDocumentScene2DMaterialization', () => {
+    expect(typeof initializeFlightDocumentScene2DMaterialization).toBe('function');
+  });
+});
+
+function createTestDocument(
+  scene: FlightDocumentScene,
+  resources: FlightDocumentResourceDescriptor[] = [],
+): FlightDocument {
+  return { defaultScene: 0, resources, scenes: [scene], version: 1 };
+}
+
+function singleTargetLayout(target: string) {
+  return {
+    targets: [target],
+    tree: { nodes: [{ containerStyle: null, itemStyle: null, kind: 'acme.Leaf', parentIndex: -1 }] },
+  };
+}
+
+function createTestSchemas(): FlightDocumentSchemaRegistry {
+  const displayObjectSchema: FlightDocumentNodeSchema = {
+    createNode: (fields: Readonly<FlightDocumentFields>, _resources: FlightDocumentResourceLookup) => {
+      const obj = createDisplayObject();
+      applyTransformFields(obj, fields);
+      return obj;
+    },
+    fields: TRANSFORM_FIELD_SCHEMAS,
+    kind: DisplayObjectKind,
+    writeNodeFields: (out: FlightDocumentFields, source: Readonly<NodeAny>) => {
+      writeTransformFields(out, source as Node2D);
+      return true;
+    },
+  };
+
+  const spriteSchema: FlightDocumentNodeSchema = {
+    createNode: (fields: Readonly<FlightDocumentFields>, _resources: FlightDocumentResourceLookup) => {
+      const sprite = createSprite();
+      applyTransformFields(sprite, fields);
+      return sprite;
+    },
+    fields: TRANSFORM_FIELD_SCHEMAS,
+    kind: SpriteKind,
+    writeNodeFields: (out: FlightDocumentFields, source: Readonly<NodeAny>) => {
+      writeTransformFields(out, source as Node2D);
+      return true;
+    },
+  };
+
+  let nodeSchemas = createKeyedTable<FlightDocumentNodeSchema>('flight-document.node', 'none');
+  nodeSchemas = withRegistryTableEntry(nodeSchemas, DisplayObjectKind, displayObjectSchema);
+  nodeSchemas = withRegistryTableEntry(nodeSchemas, SpriteKind, spriteSchema);
+
+  return {
+    interactiveStateExtensionSchemas: createKeyedTable('flight-document.interactive-state-extension', 'none'),
+    interactiveStateTransitionSchemas: createKeyedTable('flight-document.interactive-state-transition', 'none'),
+    nodeSchemas,
+    resourceSchemas: createKeyedTable('flight-document.resource', 'none'),
+    shapeCommandSchemas: createKeyedTable('flight-document.shape-command', 'none'),
+  };
+}
+
+function applyTransformFields(target: Node2D, fields: Readonly<FlightDocumentFields>): void {
+  if (typeof fields['name'] === 'string') target.name = fields['name'];
+  if (typeof fields['x'] === 'number') target.x = fields['x'];
+  if (typeof fields['y'] === 'number') target.y = fields['y'];
+  if (typeof fields['scaleX'] === 'number') target.scaleX = fields['scaleX'];
+  if (typeof fields['scaleY'] === 'number') target.scaleY = fields['scaleY'];
+  if (typeof fields['rotation'] === 'number') target.rotation = fields['rotation'];
+  if (typeof fields['alpha'] === 'number') target.alpha = fields['alpha'];
+}
+
+function writeTransformFields(out: FlightDocumentFields, source: Readonly<Node2D>): void {
+  if (source.name !== null) out['name'] = source.name;
+  if (source.x !== 0) out['x'] = source.x;
+  if (source.y !== 0) out['y'] = source.y;
+  if (source.scaleX !== 1) out['scaleX'] = source.scaleX;
+  if (source.scaleY !== 1) out['scaleY'] = source.scaleY;
+  if (source.rotation !== 0) out['rotation'] = source.rotation;
+  if (source.alpha !== 1) out['alpha'] = source.alpha;
+}
+
+const TRANSFORM_FIELD_SCHEMAS = [
+  {
+    defaultValue: undefined,
+    name: 'name',
+    required: false,
+    validate: (v: unknown) => typeof v === 'string' || v === null,
+  },
+  { defaultValue: 0, name: 'x', required: false, validate: (v: unknown) => typeof v === 'number' },
+  { defaultValue: 0, name: 'y', required: false, validate: (v: unknown) => typeof v === 'number' },
+  { defaultValue: 1, name: 'scaleX', required: false, validate: (v: unknown) => typeof v === 'number' },
+  { defaultValue: 1, name: 'scaleY', required: false, validate: (v: unknown) => typeof v === 'number' },
+  { defaultValue: 0, name: 'rotation', required: false, validate: (v: unknown) => typeof v === 'number' },
+  { defaultValue: 1, name: 'alpha', required: false, validate: (v: unknown) => typeof v === 'number' },
+] as const;
+
 describe('model-to-text explain parity', () => {
   it.each<{
     document: Readonly<FlightDocument>;
@@ -623,6 +728,22 @@ describe('model-to-text explain parity', () => {
   });
 });
 
+function rootDocument2D(kind: string, fields: Record<string, unknown>): FlightDocument {
+  return {
+    defaultScene: 0,
+    resources: [],
+    scenes: [
+      {
+        backgroundColor: null,
+        kind: 'Scene2D',
+        layouts: [],
+        scene: { children: [], fields, kind },
+        tokens: [],
+      },
+    ],
+    version: 1,
+  } as unknown as FlightDocument;
+}
 describe('Scene2D interactive-state materialization', () => {
   it('returns inert bindings for the exact root and nested live nodes', () => {
     const document = rootDocument2D(DisplayObjectKind, { alpha: 0.5 });
@@ -714,97 +835,6 @@ describe('Scene2D interactive-state materialization', () => {
   });
 });
 
-function createTestDocument(
-  scene: FlightDocumentScene,
-  resources: FlightDocumentResourceDescriptor[] = [],
-): FlightDocument {
-  return { defaultScene: 0, resources, scenes: [scene], version: 1 };
-}
-
-function singleTargetLayout(target: string) {
-  return {
-    targets: [target],
-    tree: { nodes: [{ containerStyle: null, itemStyle: null, kind: 'acme.Leaf', parentIndex: -1 }] },
-  };
-}
-
-function createTestSchemas(): FlightDocumentSchemaRegistry {
-  const displayObjectSchema: FlightDocumentNodeSchema = {
-    createNode: (fields: Readonly<FlightDocumentFields>, _resources: FlightDocumentResourceLookup) => {
-      const obj = createDisplayObject();
-      applyTransformFields(obj, fields);
-      return obj;
-    },
-    fields: TRANSFORM_FIELD_SCHEMAS,
-    kind: DisplayObjectKind,
-    writeNodeFields: (out: FlightDocumentFields, source: Readonly<NodeAny>) => {
-      writeTransformFields(out, source as Node2D);
-      return true;
-    },
-  };
-
-  const spriteSchema: FlightDocumentNodeSchema = {
-    createNode: (fields: Readonly<FlightDocumentFields>, _resources: FlightDocumentResourceLookup) => {
-      const sprite = createSprite();
-      applyTransformFields(sprite, fields);
-      return sprite;
-    },
-    fields: TRANSFORM_FIELD_SCHEMAS,
-    kind: SpriteKind,
-    writeNodeFields: (out: FlightDocumentFields, source: Readonly<NodeAny>) => {
-      writeTransformFields(out, source as Node2D);
-      return true;
-    },
-  };
-
-  let nodeSchemas = createKeyedTable<FlightDocumentNodeSchema>('flight-document.node', 'none');
-  nodeSchemas = withRegistryTableEntry(nodeSchemas, DisplayObjectKind, displayObjectSchema);
-  nodeSchemas = withRegistryTableEntry(nodeSchemas, SpriteKind, spriteSchema);
-
-  return {
-    interactiveStateExtensionSchemas: createKeyedTable('flight-document.interactive-state-extension', 'none'),
-    interactiveStateTransitionSchemas: createKeyedTable('flight-document.interactive-state-transition', 'none'),
-    nodeSchemas,
-    resourceSchemas: createKeyedTable('flight-document.resource', 'none'),
-    shapeCommandSchemas: createKeyedTable('flight-document.shape-command', 'none'),
-  };
-}
-
-function applyTransformFields(target: Node2D, fields: Readonly<FlightDocumentFields>): void {
-  if (typeof fields['name'] === 'string') target.name = fields['name'];
-  if (typeof fields['x'] === 'number') target.x = fields['x'];
-  if (typeof fields['y'] === 'number') target.y = fields['y'];
-  if (typeof fields['scaleX'] === 'number') target.scaleX = fields['scaleX'];
-  if (typeof fields['scaleY'] === 'number') target.scaleY = fields['scaleY'];
-  if (typeof fields['rotation'] === 'number') target.rotation = fields['rotation'];
-  if (typeof fields['alpha'] === 'number') target.alpha = fields['alpha'];
-}
-
-function writeTransformFields(out: FlightDocumentFields, source: Readonly<Node2D>): void {
-  if (source.name !== null) out['name'] = source.name;
-  if (source.x !== 0) out['x'] = source.x;
-  if (source.y !== 0) out['y'] = source.y;
-  if (source.scaleX !== 1) out['scaleX'] = source.scaleX;
-  if (source.scaleY !== 1) out['scaleY'] = source.scaleY;
-  if (source.rotation !== 0) out['rotation'] = source.rotation;
-  if (source.alpha !== 1) out['alpha'] = source.alpha;
-}
-
-const TRANSFORM_FIELD_SCHEMAS = [
-  {
-    defaultValue: undefined,
-    name: 'name',
-    required: false,
-    validate: (v: unknown) => typeof v === 'string' || v === null,
-  },
-  { defaultValue: 0, name: 'x', required: false, validate: (v: unknown) => typeof v === 'number' },
-  { defaultValue: 0, name: 'y', required: false, validate: (v: unknown) => typeof v === 'number' },
-  { defaultValue: 1, name: 'scaleX', required: false, validate: (v: unknown) => typeof v === 'number' },
-  { defaultValue: 1, name: 'scaleY', required: false, validate: (v: unknown) => typeof v === 'number' },
-  { defaultValue: 0, name: 'rotation', required: false, validate: (v: unknown) => typeof v === 'number' },
-  { defaultValue: 1, name: 'alpha', required: false, validate: (v: unknown) => typeof v === 'number' },
-] as const;
-
 // ★ ROOT-NODE FIDELITY. The writer captures the root's kind and fields (`writeNode(source.root, …)`), but
 // the reader built a fresh container with `createScene2D()` and materialized only `scene.children` — so
 // everything authored ON the root was silently dropped. Write preserved what read discarded, which makes
@@ -879,20 +909,3 @@ describe('Scene2D root fidelity', () => {
     expect(resourceKeys).toEqual([]);
   });
 });
-
-function rootDocument2D(kind: string, fields: Record<string, unknown>): FlightDocument {
-  return {
-    defaultScene: 0,
-    resources: [],
-    scenes: [
-      {
-        backgroundColor: null,
-        kind: 'Scene2D',
-        layouts: [],
-        scene: { children: [], fields, kind },
-        tokens: [],
-      },
-    ],
-    version: 1,
-  } as unknown as FlightDocument;
-}

package/src/sceneDocumentScene3DMaterialization.test.ts

@@ -43,6 +43,8 @@ import {
   createFlightDocumentScene3DMaterializationFromText,
   explainFlightDocumentScene3DRefusal,
   explainFlightDocumentScene3DRefusalFromText,
+  initializeFlightDocumentFromScene3D,
+  initializeFlightDocumentScene3DMaterialization,
 } from './sceneDocumentScene3DMaterialization';
 
 describe('createFlightDocumentFromScene3D', () => {
@@ -548,6 +550,18 @@ describe('explainFlightDocumentScene3DRefusalFromText', () => {
   });
 });
 
+describe('initializeFlightDocumentFromScene3D', () => {
+  it('is the construction initializer of createFlightDocumentFromScene3D', () => {
+    expect(typeof initializeFlightDocumentFromScene3D).toBe('function');
+  });
+});
+
+describe('initializeFlightDocumentScene3DMaterialization', () => {
+  it('is the construction initializer of createFlightDocumentScene3DMaterialization', () => {
+    expect(typeof initializeFlightDocumentScene3DMaterialization).toBe('function');
+  });
+});
+
 describe('model-to-text explain parity', () => {
   // Keep the table annotated so every fixture is checked against the container schema rather than inferred
   // only from its own literal.
@@ -763,68 +777,6 @@ describe('Scene3D layout materialization', () => {
   });
 });
 
-// ★ ROOT-NODE FIDELITY, 3D half. Same defect as 2D: the reader built a fresh container and materialized
-// only the authored root's children, so the root's own kind and fields were dropped while the writer
-// captured them.
-describe('Scene3D root fidelity', () => {
-  it('preserves the authored root kind', () => {
-    const schemas = createTestSchemas();
-    const document = rootDocument3D(Node3DKind, {}, schemas);
-    const materialization = createFlightDocumentScene3DMaterialization(document, schemas);
-    expect(materialization).not.toBeNull();
-    expect(materialization!.scene.root.kind).toBe(Node3DKind);
-  });
-
-  it('preserves fields authored on the root', () => {
-    const schemas = createTestSchemas();
-    const document = rootDocument3D(Node3DKind, { name: 'authored-root' }, schemas);
-    const materialization = createFlightDocumentScene3DMaterialization(document, schemas);
-    expect(materialization).not.toBeNull();
-    expect(materialization!.scene.root.name).toBe('authored-root');
-  });
-
-  it('refuses a registered root whose kind belongs to the other dimension', () => {
-    const schemas = createTestSchemas();
-    schemas.nodeSchemas = withRegistryTableEntry(schemas.nodeSchemas, DisplayObjectKind, {
-      createNode: () => createDisplayObject() as unknown as NodeAny,
-      fields: [],
-      kind: DisplayObjectKind,
-      writeNodeFields: () => true,
-    });
-    const document = rootDocument3D(DisplayObjectKind, {}, schemas);
-    expect(createFlightDocumentScene3DMaterialization(document, schemas)).toBeNull();
-    expect(explainFlightDocumentScene3DRefusal(document, schemas)).toMatchObject({
-      reason: FlightDocumentRefusalReason.RootKindMismatch,
-    });
-  });
-
-  it('passes a genuinely empty resource map to a root-dimension probe', () => {
-    const schemas = createTestSchemas();
-    let resourceKeys: string[] | null = null;
-    schemas.nodeSchemas = withRegistryTableEntry(schemas.nodeSchemas, DisplayObjectKind, {
-      createNode: (_fields, resources) => {
-        resourceKeys = Object.keys(resources);
-        return createDisplayObject() as unknown as NodeAny;
-      },
-      fields: [],
-      kind: DisplayObjectKind,
-      writeNodeFields: () => true,
-    });
-
-    explainFlightDocumentScene3DRefusal(rootDocument3D(DisplayObjectKind, {}, schemas), schemas);
-
-    expect(resourceKeys).toEqual([]);
-  });
-});
-
-describe('Scene3DDocumentCamera', () => {
-  it('has no direction field', () => {
-    expectTypeOf<keyof Scene3DDocumentCamera>().toEqualTypeOf<
-      'far' | 'name' | 'near' | 'node' | 'projection' | 'transform'
-    >();
-  });
-});
-
 function createTestDocument(
   scene: FlightDocumentScene,
   resources: FlightDocumentResourceDescriptor[] = [],
@@ -876,9 +828,57 @@ function createTestSchemas(): FlightDocumentSchemaRegistry {
   };
 }
 
-describe('Scene3DDocumentLight', () => {
-  it('has no direction field', () => {
-    expectTypeOf<keyof Scene3DDocumentLight>().toEqualTypeOf<'descriptor' | 'name' | 'node' | 'transform'>();
+// ★ ROOT-NODE FIDELITY, 3D half. Same defect as 2D: the reader built a fresh container and materialized
+// only the authored root's children, so the root's own kind and fields were dropped while the writer
+// captured them.
+describe('Scene3D root fidelity', () => {
+  it('preserves the authored root kind', () => {
+    const schemas = createTestSchemas();
+    const document = rootDocument3D(Node3DKind, {}, schemas);
+    const materialization = createFlightDocumentScene3DMaterialization(document, schemas);
+    expect(materialization).not.toBeNull();
+    expect(materialization!.scene.root.kind).toBe(Node3DKind);
+  });
+
+  it('preserves fields authored on the root', () => {
+    const schemas = createTestSchemas();
+    const document = rootDocument3D(Node3DKind, { name: 'authored-root' }, schemas);
+    const materialization = createFlightDocumentScene3DMaterialization(document, schemas);
+    expect(materialization).not.toBeNull();
+    expect(materialization!.scene.root.name).toBe('authored-root');
+  });
+
+  it('refuses a registered root whose kind belongs to the other dimension', () => {
+    const schemas = createTestSchemas();
+    schemas.nodeSchemas = withRegistryTableEntry(schemas.nodeSchemas, DisplayObjectKind, {
+      createNode: () => createDisplayObject() as unknown as NodeAny,
+      fields: [],
+      kind: DisplayObjectKind,
+      writeNodeFields: () => true,
+    });
+    const document = rootDocument3D(DisplayObjectKind, {}, schemas);
+    expect(createFlightDocumentScene3DMaterialization(document, schemas)).toBeNull();
+    expect(explainFlightDocumentScene3DRefusal(document, schemas)).toMatchObject({
+      reason: FlightDocumentRefusalReason.RootKindMismatch,
+    });
+  });
+
+  it('passes a genuinely empty resource map to a root-dimension probe', () => {
+    const schemas = createTestSchemas();
+    let resourceKeys: string[] | null = null;
+    schemas.nodeSchemas = withRegistryTableEntry(schemas.nodeSchemas, DisplayObjectKind, {
+      createNode: (_fields, resources) => {
+        resourceKeys = Object.keys(resources);
+        return createDisplayObject() as unknown as NodeAny;
+      },
+      fields: [],
+      kind: DisplayObjectKind,
+      writeNodeFields: () => true,
+    });
+
+    explainFlightDocumentScene3DRefusal(rootDocument3D(DisplayObjectKind, {}, schemas), schemas);
+
+    expect(resourceKeys).toEqual([]);
   });
 });
 
@@ -933,3 +933,16 @@ function getScene3DLights(source: Readonly<Scene3DLightsLike>): Readonly<Light>[
   }
   return lights;
 }
+describe('Scene3DDocumentCamera', () => {
+  it('has no direction field', () => {
+    expectTypeOf<keyof Scene3DDocumentCamera>().toEqualTypeOf<
+      'far' | 'name' | 'near' | 'node' | 'projection' | 'transform'
+    >();
+  });
+});
+
+describe('Scene3DDocumentLight', () => {
+  it('has no direction field', () => {
+    expectTypeOf<keyof Scene3DDocumentLight>().toEqualTypeOf<'descriptor' | 'name' | 'node' | 'transform'>();
+  });
+});