@flighthq/scene-document 0.4.1-edge.37.ff47e13 → 0.4.1-next.109.0f3397e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/scene-document",
-  "version": "0.4.1-edge.37.ff47e13",
+  "version": "0.4.1-next.109.0f3397e",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,14 +38,14 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/camera": "0.4.1-edge.37.ff47e13",
-    "@flighthq/geometry": "0.4.1-edge.37.ff47e13",
-    "@flighthq/lighting": "0.4.1-edge.37.ff47e13",
-    "@flighthq/node": "0.4.1-edge.37.ff47e13",
-    "@flighthq/registry": "0.4.1-edge.37.ff47e13",
-    "@flighthq/scene2d": "0.4.1-edge.37.ff47e13",
-    "@flighthq/scene3d": "0.4.1-edge.37.ff47e13",
-    "@flighthq/types": "0.4.1-edge.37.ff47e13"
+    "@flighthq/camera": "0.4.1-next.109.0f3397e",
+    "@flighthq/geometry": "0.4.1-next.109.0f3397e",
+    "@flighthq/lighting": "0.4.1-next.109.0f3397e",
+    "@flighthq/node": "0.4.1-next.109.0f3397e",
+    "@flighthq/registry": "0.4.1-next.109.0f3397e",
+    "@flighthq/scene2d": "0.4.1-next.109.0f3397e",
+    "@flighthq/scene3d": "0.4.1-next.109.0f3397e",
+    "@flighthq/types": "0.4.1-next.109.0f3397e"
   },
   "devDependencies": {
     "@flighthq/camera": "*",

package/src/flightDocumentText.test.ts

@@ -0,0 +1,179 @@
+import { createTransform3D } from '@flighthq/geometry/contract';
+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 { parseSceneDocumentYamlSubset } from './sceneDocumentYamlSubset';
+
+describe('explainFlightDocumentText', () => {
+  it('names an empty scenes collection independently', () => {
+    const explanation = explainFlightDocumentText('flight: 1\ndefaultScene: 0\nscenes:\n');
+
+    expect(explanation).toMatchObject({
+      path: 'scenes',
+      reason: FlightDocumentRefusalReason.ScenesEmpty,
+    });
+  });
+
+  it('names an out-of-range default scene without clamping it', () => {
+    const explanation = explainFlightDocumentText(
+      ['flight: 1', 'defaultScene: 1', 'scenes:', '  - kind: Scene2D', '    scene:', '      kind: DisplayObject'].join(
+        '\n',
+      ),
+    );
+
+    expect(explanation).toMatchObject({
+      actual: 1,
+      limit: 0,
+      path: 'defaultScene',
+      reason: FlightDocumentRefusalReason.DefaultSceneOutOfRange,
+    });
+  });
+
+  it('qualifies a structural refusal with the nonzero scene index', () => {
+    const explanation = explainFlightDocumentText(
+      [
+        'flight: 1',
+        'defaultScene: 0',
+        'scenes:',
+        '  - kind: Scene2D',
+        '    scene:',
+        '      kind: DisplayObject',
+        '  - kind: Scene3D',
+        '    scene:',
+        '      children:',
+        '        - kind: Node3D',
+      ].join('\n'),
+    );
+
+    expect(explanation).toMatchObject({
+      path: 'scenes[1].scene.kind',
+      reason: FlightDocumentRefusalReason.StructureInvalid,
+    });
+  });
+
+  it('preserves a typed YAML-subset refusal with source position', () => {
+    const explanation = explainFlightDocumentText('flight: 1\nanchor: &root value\n');
+
+    expect(explanation).toMatchObject({
+      reason: FlightDocumentRefusalReason.AnchorUnsupported,
+    });
+    expect(explanation?.line).toBe(2);
+    expect(explanation?.column).toBeGreaterThan(0);
+  });
+});
+
+describe('formatFlightDocumentText', () => {
+  it('emits only the accepted YAML subset and round-trips a mixed-scene container', () => {
+    const cameraTransform = createTransform3D();
+    cameraTransform.position.z = 8;
+    const lightTransform = createTransform3D();
+    lightTransform.position.y = 4;
+    const document: FlightDocument = {
+      defaultScene: 1,
+      resources: [{ fields: { source: 'shared image.png' }, key: 'shared', kind: 'Texture' }],
+      scenes: [
+        {
+          backgroundColor: 0x112233ff,
+          kind: 'Scene2D',
+          scene: {
+            children: [
+              {
+                children: [],
+                fields: { metadata: { enabled: true }, tags: ['hud', 'shared'], texture: 'shared' },
+                kind: 'Sprite',
+              },
+            ],
+            fields: {},
+            kind: 'DisplayObject',
+          },
+        },
+        {
+          cameras: [
+            {
+              far: 1000,
+              name: 'main camera',
+              near: 0.1,
+              projection: { aspect: 16 / 9, fovY: 1, kind: 'perspective' },
+              transform: cameraTransform,
+            },
+          ],
+          kind: 'Scene3D',
+          lights: [{ descriptor: createAmbientLight({ intensity: 0.4 }), transform: lightTransform }],
+          scene: { children: [], fields: {}, kind: 'Node3D' },
+        },
+      ],
+      version: 1,
+    };
+
+    const text = formatFlightDocumentText(document);
+    expect(parseSceneDocumentYamlSubset(text).ok).toBe(true);
+    expect(text).not.toContain('[');
+    expect(text).not.toContain('&');
+
+    const reparsed = parseFlightDocumentText(text);
+    expect(reparsed).not.toBeNull();
+    expect(reparsed?.defaultScene).toBe(1);
+    expect(reparsed?.resources).toEqual(document.resources);
+    expect(reparsed?.scenes.map((scene) => scene.kind)).toEqual(['Scene2D', 'Scene3D']);
+    expect(reparsed?.scenes[0].scene.children[0]?.fields).toEqual(document.scenes[0].scene.children[0]?.fields);
+    const scene3D = reparsed?.scenes[1];
+    expect(scene3D?.kind).toBe('Scene3D');
+    if (scene3D?.kind !== 'Scene3D') throw new Error('expected Scene3D fixture');
+    expect(scene3D.cameras[0]?.name).toBe('main camera');
+    expect(scene3D.cameras[0]?.transform.position.z).toBe(8);
+    expect(scene3D.lights[0]?.descriptor.kind).toBe('AmbientLight');
+    expect(Reflect.get(scene3D.lights[0]?.descriptor ?? {}, 'intensity')).toBe(0.4);
+  });
+});
+
+describe('parseFlightDocumentText', () => {
+  it('parses mixed dimensions over one shared resource table', () => {
+    const document = parseFlightDocumentText(
+      [
+        'flight: 1',
+        'defaultScene: 1',
+        'resources:',
+        '  - kind: Texture',
+        '    key: shared',
+        '    source: shared.png',
+        'scenes:',
+        '  - kind: Scene2D',
+        '    backgroundColor: 287454207',
+        '    scene:',
+        '      kind: DisplayObject',
+        '      children:',
+        '        - kind: Sprite',
+        '          texture: shared',
+        '  - kind: Scene3D',
+        '    scene:',
+        '      kind: Node3D',
+        '      children:',
+        '        - kind: Mesh',
+        '          texture: shared',
+      ].join('\n'),
+    );
+
+    expect(document).not.toBeNull();
+    expect(document?.defaultScene).toBe(1);
+    expect(document?.resources).toEqual([{ fields: { source: 'shared.png' }, key: 'shared', kind: 'Texture' }]);
+    expect(document?.scenes.map((scene) => scene.kind)).toEqual(['Scene2D', 'Scene3D']);
+    expect(document?.scenes[0].scene.children[0]?.fields['texture']).toBe('shared');
+    expect(document?.scenes[1].scene.children[0]?.fields['texture']).toBe('shared');
+  });
+
+  it('returns null whenever the explain seam reports a structural refusal', () => {
+    const text = [
+      'flight: 1',
+      'defaultScene: 2',
+      'scenes:',
+      '  - kind: Scene2D',
+      '    scene:',
+      '      kind: DisplayObject',
+    ].join('\n');
+
+    expect(parseFlightDocumentText(text)).toBeNull();
+    expect(explainFlightDocumentText(text)?.reason).toBe(FlightDocumentRefusalReason.DefaultSceneOutOfRange);
+  });
+});

package/src/sceneDocumentMaterializationSelection.test.ts

@@ -0,0 +1,56 @@
+import type { FlightDocument } from '@flighthq/types/contract';
+import { DisplayObjectKind, FlightDocumentRefusalReason, Node3DKind } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { selectFlightDocumentScene } from './sceneDocumentMaterializationSelection';
+
+describe('selectFlightDocumentScene', () => {
+  it('selects the default or requested scene when its dimension matches', () => {
+    const document = createDocument();
+
+    expect(selectFlightDocumentScene(document, 'Scene3D')).toMatchObject({
+      refusal: null,
+      scene: document.scenes[1],
+      sceneIndex: 1,
+    });
+    expect(selectFlightDocumentScene(document, 'Scene2D', 0)).toMatchObject({
+      refusal: null,
+      scene: document.scenes[0],
+      sceneIndex: 0,
+    });
+  });
+
+  it('refuses invalid containers and mismatched dimensions', () => {
+    const emptyDocument = { ...createDocument(), scenes: [] } as unknown as FlightDocument;
+
+    expect(selectFlightDocumentScene(emptyDocument, 'Scene2D')).toMatchObject({
+      refusal: { path: 'scenes', reason: FlightDocumentRefusalReason.ScenesEmpty },
+      scene: null,
+    });
+    expect(selectFlightDocumentScene(createDocument(), 'Scene2D')).toMatchObject({
+      refusal: { path: 'scenes[1].kind', reason: FlightDocumentRefusalReason.StructureInvalid },
+      scene: null,
+    });
+  });
+});
+
+function createDocument(): FlightDocument {
+  return {
+    defaultScene: 1,
+    resources: [],
+    scenes: [
+      {
+        backgroundColor: null,
+        kind: 'Scene2D',
+        scene: { children: [], fields: {}, kind: DisplayObjectKind },
+      },
+      {
+        cameras: [],
+        kind: 'Scene3D',
+        lights: [],
+        scene: { children: [], fields: {}, kind: Node3DKind },
+      },
+    ],
+    version: 1,
+  };
+}

package/src/sceneDocumentMultiSceneMaterialization.test.ts

@@ -0,0 +1,209 @@
+import { createTransform3D } from '@flighthq/geometry/contract';
+import { createAmbientLight } from '@flighthq/lighting/contract';
+import { createKeyedTable, withRegistryTableEntry } from '@flighthq/registry/contract';
+import { createDisplayObject } from '@flighthq/scene2d/contract';
+import { createNode3D } from '@flighthq/scene3d/contract';
+import type {
+  FlightDocument,
+  FlightDocumentFields,
+  FlightDocumentNodeSchema,
+  FlightDocumentResourceLookup,
+  FlightDocumentResourceResolver,
+  FlightDocumentResourceResolverRegistry,
+  FlightDocumentSchemaRegistry,
+  NodeAny,
+} from '@flighthq/types/contract';
+import { DisplayObjectKind, FlightDocumentRefusalReason, Node3DKind } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { formatFlightDocumentText } from './flightDocumentText';
+import {
+  createFlightDocumentScene2DMaterialization,
+  createFlightDocumentScene2DMaterializationFromText,
+  explainFlightDocumentRefusal,
+  explainFlightDocumentRefusalFromText,
+} from './sceneDocumentScene2DMaterialization';
+import {
+  createFlightDocumentScene3DMaterialization,
+  createFlightDocumentScene3DMaterializationFromText,
+  explainFlightDocumentScene3DRefusal,
+} from './sceneDocumentScene3DMaterialization';
+
+const TestScene2DNodeKind = 'TestScene2DNode';
+const TestScene3DNodeKind = 'TestScene3DNode';
+
+describe('multi-scene materialization selection', () => {
+  it('uses defaultScene by default and can materialize another entry by index', () => {
+    const seenResources: unknown[] = [];
+    const schemas = createTestSchemas(seenResources);
+    const sharedResource = {};
+    const resolvers = createTestResolvers(sharedResource);
+    const document = createMixedDocument();
+
+    const selected3D = createFlightDocumentScene3DMaterialization(document, schemas, resolvers);
+    const selectedAs2D = createFlightDocumentScene2DMaterialization(document, schemas, resolvers);
+    const perScene2D = createFlightDocumentScene2DMaterialization(document, schemas, resolvers, 0);
+    const wrongPerScene3D = createFlightDocumentScene3DMaterialization(document, schemas, resolvers, 0);
+
+    expect(selected3D).not.toBeNull();
+    expect(selectedAs2D).toBeNull();
+    expect(perScene2D).not.toBeNull();
+    expect(wrongPerScene3D).toBeNull();
+    expect(seenResources).toEqual([sharedResource, sharedResource]);
+    expect(seenResources[0]).toBe(seenResources[1]);
+  });
+
+  it('preserves selected and explicit-index semantics through the text conveniences', () => {
+    const seenResources: unknown[] = [];
+    const schemas = createTestSchemas(seenResources);
+    const sharedResource = {};
+    const resolvers = createTestResolvers(sharedResource);
+    const text = formatFlightDocumentText(createMixedDocument());
+
+    expect(createFlightDocumentScene3DMaterializationFromText(text, schemas, resolvers)).not.toBeNull();
+    expect(createFlightDocumentScene2DMaterializationFromText(text, schemas, resolvers)).toBeNull();
+    expect(createFlightDocumentScene2DMaterializationFromText(text, schemas, resolvers, 0)).not.toBeNull();
+    expect(explainFlightDocumentRefusalFromText(text, 'Scene2D', schemas, 1)).toMatchObject({
+      path: 'scenes[1].kind',
+      reason: FlightDocumentRefusalReason.StructureInvalid,
+    });
+    expect(seenResources).toEqual([sharedResource, sharedResource]);
+  });
+
+  it('rejects an empty scene container through both dimension entrypoints', () => {
+    const document = { defaultScene: 0, resources: [], scenes: [], version: 1 } as unknown as FlightDocument;
+    const schemas = createTestSchemas([]);
+
+    expect(createFlightDocumentScene2DMaterialization(document, schemas)).toBeNull();
+    expect(createFlightDocumentScene3DMaterialization(document, schemas)).toBeNull();
+    expect(explainFlightDocumentRefusal(document, 'Scene2D', schemas)).toMatchObject({
+      path: 'scenes',
+      reason: FlightDocumentRefusalReason.ScenesEmpty,
+    });
+    expect(explainFlightDocumentScene3DRefusal(document, schemas)).toMatchObject({
+      path: 'scenes',
+      reason: FlightDocumentRefusalReason.ScenesEmpty,
+    });
+  });
+
+  it('rejects an invalid defaultScene instead of clamping it even for an explicit scene request', () => {
+    const document: FlightDocument = { ...createMixedDocument(), defaultScene: 2 };
+    const schemas = createTestSchemas([]);
+
+    expect(createFlightDocumentScene2DMaterialization(document, schemas, undefined, 0)).toBeNull();
+    expect(explainFlightDocumentRefusal(document, 'Scene2D', schemas, 0)).toMatchObject({
+      actual: 2,
+      path: 'defaultScene',
+      reason: FlightDocumentRefusalReason.DefaultSceneOutOfRange,
+    });
+  });
+
+  it('qualifies nested and dimension-specific refusals with the requested scene index', () => {
+    const document = createMixedDocument();
+    const schemas = createTestSchemas([]);
+
+    expect(explainFlightDocumentRefusal(document, 'Scene2D', schemas, 1)).toMatchObject({
+      path: 'scenes[1].kind',
+      reason: FlightDocumentRefusalReason.StructureInvalid,
+    });
+
+    const scene = document.scenes[1];
+    if (scene.kind !== 'Scene3D') throw new Error('fixture scene 1 must be Scene3D');
+    scene.scene.children = [{ children: [], fields: {}, kind: 'acme.Unknown' }];
+
+    expect(explainFlightDocumentScene3DRefusal(document, schemas, 1)).toMatchObject({
+      kind: 'acme.Unknown',
+      path: 'scenes[1].scene.children[0]',
+      reason: FlightDocumentRefusalReason.NodeKindUnregistered,
+    });
+
+    scene.scene.children = [];
+    scene.lights = [
+      { descriptor: createAmbientLight(), transform: createTransform3D() },
+      { descriptor: createAmbientLight(), transform: createTransform3D() },
+    ];
+    expect(explainFlightDocumentScene3DRefusal(document, schemas, 1)).toMatchObject({
+      path: 'scenes[1].lights',
+      reason: FlightDocumentRefusalReason.DuplicateAmbientLight,
+    });
+  });
+});
+
+function createMixedDocument(): FlightDocument {
+  return {
+    defaultScene: 1,
+    resources: [{ fields: {}, key: 'shared', kind: 'TestResource' }],
+    scenes: [
+      {
+        backgroundColor: null,
+        kind: 'Scene2D',
+        scene: {
+          children: [{ children: [], fields: {}, kind: TestScene2DNodeKind }],
+          fields: {},
+          kind: DisplayObjectKind,
+        },
+      },
+      {
+        cameras: [],
+        kind: 'Scene3D',
+        lights: [],
+        scene: {
+          children: [{ children: [], fields: {}, kind: TestScene3DNodeKind }],
+          fields: {},
+          kind: Node3DKind,
+        },
+      },
+    ],
+    version: 1,
+  };
+}
+
+function createTestResolvers(sharedResource: unknown): FlightDocumentResourceResolverRegistry {
+  let resolvers = createKeyedTable<FlightDocumentResourceResolver>('flight-document.resolver', 'none');
+  resolvers = withRegistryTableEntry(resolvers, 'TestResource', () => sharedResource);
+  return { resolvers };
+}
+
+function createTestSchemas(seenResources: unknown[]): FlightDocumentSchemaRegistry {
+  const createSchema = (
+    kind: string,
+    createNode: (resources: FlightDocumentResourceLookup) => NodeAny,
+  ): FlightDocumentNodeSchema => ({
+    createNode: (_fields, resources) => createNode(resources),
+    fields: [],
+    kind,
+    writeNodeFields: (_out: FlightDocumentFields, _source: Readonly<NodeAny>) => true,
+  });
+  let nodeSchemas = createKeyedTable<FlightDocumentNodeSchema>('flight-document.node', 'none');
+  nodeSchemas = withRegistryTableEntry(
+    nodeSchemas,
+    DisplayObjectKind,
+    createSchema(DisplayObjectKind, () => createDisplayObject()),
+  );
+  nodeSchemas = withRegistryTableEntry(
+    nodeSchemas,
+    TestScene2DNodeKind,
+    createSchema(TestScene2DNodeKind, (resources) => {
+      seenResources.push(resources['shared']);
+      return createDisplayObject();
+    }),
+  );
+  nodeSchemas = withRegistryTableEntry(
+    nodeSchemas,
+    Node3DKind,
+    createSchema(Node3DKind, () => createNode3D()),
+  );
+  nodeSchemas = withRegistryTableEntry(
+    nodeSchemas,
+    TestScene3DNodeKind,
+    createSchema(TestScene3DNodeKind, (resources) => {
+      seenResources.push(resources['shared']);
+      return createNode3D();
+    }),
+  );
+  return {
+    nodeSchemas,
+    resourceSchemas: createKeyedTable('flight-document.resource', 'none'),
+    shapeCommandSchemas: createKeyedTable('flight-document.shape-command', 'none'),
+  };
+}

package/src/sceneDocumentRefusal.test.ts

@@ -0,0 +1,143 @@
+import { createKeyedTable, withRegistryTableEntry } from '@flighthq/registry/contract';
+import type {
+  FlightDocumentFields,
+  FlightDocumentNode,
+  FlightDocumentNodeSchema,
+  FlightDocumentResourceLookup,
+  FlightDocumentSchemaRegistry,
+  NodeAny,
+} from '@flighthq/types/contract';
+import { FlightDocumentRefusalReason } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import {
+  checkUnregisteredNodeKinds,
+  checkUnregisteredNodeKindsFromRaw,
+  createDocumentRefusal,
+  createSceneRefusal,
+} from './sceneDocumentRefusal';
+
+describe('checkUnregisteredNodeKinds', () => {
+  it('returns null when all kinds are registered', () => {
+    const schemas = createTestSchemas('TestKind');
+    const node: FlightDocumentNode = { children: [], fields: {}, kind: 'TestKind' };
+    expect(checkUnregisteredNodeKinds(node, schemas, 0, 'scene')).toBeNull();
+  });
+
+  it('returns refusal naming the unregistered kind', () => {
+    const schemas = createTestSchemas('TestKind');
+    const node: FlightDocumentNode = { children: [], fields: {}, kind: 'acme.Missing' };
+    const refusal = checkUnregisteredNodeKinds(node, schemas, 0, 'scene');
+    expect(refusal).not.toBeNull();
+    expect(refusal!.reason).toBe(FlightDocumentRefusalReason.NodeKindUnregistered);
+    expect(refusal!.kind).toBe('acme.Missing');
+    expect(refusal!.path).toBe('scenes[0].scene');
+  });
+
+  it('walks children and qualifies nested path', () => {
+    const schemas = createTestSchemas('TestKind');
+    const node: FlightDocumentNode = {
+      children: [
+        {
+          children: [{ children: [], fields: {}, kind: 'acme.Deep' }],
+          fields: {},
+          kind: 'TestKind',
+        },
+      ],
+      fields: {},
+      kind: 'TestKind',
+    };
+    const refusal = checkUnregisteredNodeKinds(node, schemas, 0, 'scene');
+    expect(refusal).not.toBeNull();
+    expect(refusal!.path).toBe('scenes[0].scene.children[0].children[0]');
+    expect(refusal!.kind).toBe('acme.Deep');
+  });
+});
+
+describe('checkUnregisteredNodeKindsFromRaw', () => {
+  it('returns null for non-object value', () => {
+    const schemas = createTestSchemas('TestKind');
+    expect(checkUnregisteredNodeKindsFromRaw(null, schemas, 0, 'scene')).toBeNull();
+    expect(checkUnregisteredNodeKindsFromRaw(42, schemas, 0, 'scene')).toBeNull();
+  });
+
+  it('returns refusal for unregistered kind in raw object', () => {
+    const schemas = createTestSchemas('TestKind');
+    const raw = { children: [], kind: 'acme.Unknown' };
+    const refusal = checkUnregisteredNodeKindsFromRaw(raw, schemas, 0, 'scene');
+    expect(refusal).not.toBeNull();
+    expect(refusal!.reason).toBe(FlightDocumentRefusalReason.NodeKindUnregistered);
+    expect(refusal!.kind).toBe('acme.Unknown');
+  });
+
+  it('walks raw children recursively', () => {
+    const schemas = createTestSchemas('TestKind');
+    const raw = {
+      children: [{ children: [], kind: 'acme.Nested' }],
+      kind: 'TestKind',
+    };
+    const refusal = checkUnregisteredNodeKindsFromRaw(raw, schemas, 0, 'scene');
+    expect(refusal).not.toBeNull();
+    expect(refusal!.path).toBe('scenes[0].scene.children[0]');
+    expect(refusal!.kind).toBe('acme.Nested');
+  });
+});
+
+describe('createDocumentRefusal', () => {
+  it('produces a refusal with the given path', () => {
+    const refusal = createDocumentRefusal(FlightDocumentRefusalReason.VersionUnsupported, 'version');
+    expect(refusal.reason).toBe(FlightDocumentRefusalReason.VersionUnsupported);
+    expect(refusal.path).toBe('version');
+  });
+
+  it('nulls all optional fields', () => {
+    const refusal = createDocumentRefusal(FlightDocumentRefusalReason.StructureInvalid, '');
+    expect(refusal.actual).toBeNull();
+    expect(refusal.column).toBeNull();
+    expect(refusal.kind).toBeNull();
+    expect(refusal.limit).toBeNull();
+    expect(refusal.line).toBeNull();
+    expect(refusal.offset).toBeNull();
+    expect(refusal.resourceKey).toBeNull();
+    expect(refusal.version).toBeNull();
+  });
+});
+
+describe('createSceneRefusal', () => {
+  it('qualifies path with scene index', () => {
+    const refusal = createSceneRefusal(FlightDocumentRefusalReason.DuplicateAmbientLight, 0, 'lights');
+    expect(refusal.path).toBe('scenes[0].lights');
+  });
+
+  it('qualifies with non-zero scene index', () => {
+    const refusal = createSceneRefusal(FlightDocumentRefusalReason.DuplicateDirectionalLight, 2, 'lights');
+    expect(refusal.path).toBe('scenes[2].lights');
+  });
+
+  it('omits trailing dot for empty inner path', () => {
+    const refusal = createSceneRefusal(FlightDocumentRefusalReason.StructureInvalid, 1, '');
+    expect(refusal.path).toBe('scenes[1]');
+  });
+
+  it('carries the reason through', () => {
+    const refusal = createSceneRefusal(FlightDocumentRefusalReason.StructureInvalid, 0, 'kind');
+    expect(refusal.reason).toBe(FlightDocumentRefusalReason.StructureInvalid);
+    expect(refusal.path).toBe('scenes[0].kind');
+  });
+});
+
+function createTestSchemas(registeredKind: string): FlightDocumentSchemaRegistry {
+  const schema: FlightDocumentNodeSchema = {
+    createNode: (_fields: Readonly<FlightDocumentFields>, _resources: FlightDocumentResourceLookup) => null,
+    fields: [],
+    kind: registeredKind,
+    writeNodeFields: (_out: FlightDocumentFields, _source: Readonly<NodeAny>) => true,
+  };
+  let nodeSchemas = createKeyedTable<FlightDocumentNodeSchema>('flight-document.node', 'none');
+  nodeSchemas = withRegistryTableEntry(nodeSchemas, registeredKind, schema);
+  return {
+    nodeSchemas,
+    resourceSchemas: createKeyedTable('flight-document.resource', 'none'),
+    shapeCommandSchemas: createKeyedTable('flight-document.shape-command', 'none'),
+  };
+}