@flighthq/scene-document 0.4.1-next.37.ff47e13 → 0.4.1-next.515.b0834fe

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'),
+  };
+}

package/src/sceneDocumentScene2DMaterialization.test.ts

@@ -1,13 +1,15 @@
 import { addNodeChild, getNodeChildren } from '@flighthq/node/contract';
 import { createKeyedTable, withRegistryTableEntry } from '@flighthq/registry/contract';
 import { createDisplayObject, createScene2D, createSprite } from '@flighthq/scene2d/contract';
-import { DisplayObjectKind, FlightDocumentRefusalReason, SpriteKind } from '@flighthq/types/contract';
+import { createNode3D } from '@flighthq/scene3d/contract';
+import { DisplayObjectKind, FlightDocumentRefusalReason, Node3DKind, SpriteKind } from '@flighthq/types/contract';
 import type {
   FlightDocument,
   FlightDocumentFields,
   FlightDocumentNodeSchema,
+  FlightDocumentResourceDescriptor,
   FlightDocumentResourceLookup,
-  FlightDocumentScene2D,
+  FlightDocumentScene,
   FlightDocumentScene2DMaterialization,
   FlightDocumentSchemaRegistry,
   Node2D,
@@ -15,13 +17,13 @@ import type {
 } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
+import { formatFlightDocumentText } from './flightDocumentText';
 import {
   createFlightDocumentFromScene2D,
   createFlightDocumentScene2DMaterialization,
   createFlightDocumentScene2DMaterializationFromText,
   explainFlightDocumentRefusal,
   explainFlightDocumentRefusalFromText,
-  serializeFlightDocument,
 } from './sceneDocumentScene2DMaterialization';
 
 describe('createFlightDocumentFromScene2D', () => {
@@ -29,7 +31,6 @@ describe('createFlightDocumentFromScene2D', () => {
     const scene = createScene2D();
     const document = createFlightDocumentFromScene2D(scene, createTestSchemas());
     expect(document.kind).toBe('Scene2D');
-    expect(document.version).toBe(1);
     expect(document.scene.children).toHaveLength(0);
   });
 
@@ -81,13 +82,11 @@ describe('createFlightDocumentFromScene2D', () => {
 
 describe('createFlightDocumentScene2DMaterialization', () => {
   it('materializes an empty Scene2D from a minimal model', () => {
-    const document: FlightDocumentScene2D = {
+    const document = createTestDocument({
       backgroundColor: null,
       kind: 'Scene2D',
-      resources: [],
       scene: { children: [], fields: {}, kind: DisplayObjectKind },
-      version: 1,
-    };
+    });
     const result = createFlightDocumentScene2DMaterialization(document, createTestSchemas());
     expect(result).not.toBeNull();
     const materialization = result as FlightDocumentScene2DMaterialization;
@@ -96,10 +95,9 @@ describe('createFlightDocumentScene2DMaterialization', () => {
   });
 
   it('materializes a tree with nested children', () => {
-    const document: FlightDocumentScene2D = {
+    const document = createTestDocument({
       backgroundColor: null,
       kind: 'Scene2D',
-      resources: [],
       scene: {
         children: [
           {
@@ -111,8 +109,7 @@ describe('createFlightDocumentScene2DMaterialization', () => {
         fields: {},
         kind: DisplayObjectKind,
       },
-      version: 1,
-    };
+    });
     const schemas = createTestSchemas();
     const result = createFlightDocumentScene2DMaterialization(document, schemas);
     expect(result).not.toBeNull();
@@ -126,26 +123,25 @@ describe('createFlightDocumentScene2DMaterialization', () => {
   });
 
   it('returns null for a Scene3D document', () => {
-    const document = {
+    const document = createTestDocument({
       cameras: [],
       kind: 'Scene3D',
       lights: [],
-      resources: [],
       scene: { children: [], fields: {}, kind: 'Node3D' },
-      version: 1,
-    } as FlightDocument;
+    });
     const result = createFlightDocumentScene2DMaterialization(document, createTestSchemas());
     expect(result).toBeNull();
   });
 
   it('returns null for an unsupported version', () => {
     const document = {
-      backgroundColor: null,
-      kind: 'Scene2D',
-      resources: [],
-      scene: { children: [], fields: {}, kind: DisplayObjectKind },
+      ...createTestDocument({
+        backgroundColor: null,
+        kind: 'Scene2D',
+        scene: { children: [], fields: {}, kind: DisplayObjectKind },
+      }),
       version: 99,
-    } as unknown as FlightDocumentScene2D;
+    } as unknown as FlightDocument;
     const result = createFlightDocumentScene2DMaterialization(document, createTestSchemas());
     expect(result).toBeNull();
   });
@@ -155,12 +151,14 @@ describe('createFlightDocumentScene2DMaterializationFromText', () => {
   it('materializes a Scene2D from YAML text', () => {
     const yaml = [
       'flight: 1',
-      'kind: Scene2D',
-      'scene:',
-      '  kind: DisplayObject',
-      '  children:',
-      '    - kind: Sprite',
-      '      name: bg',
+      'defaultScene: 0',
+      'scenes:',
+      '  - kind: Scene2D',
+      '    scene:',
+      '      kind: DisplayObject',
+      '      children:',
+      '        - kind: Sprite',
+      '          name: bg',
     ].join('\n');
     const schemas = createTestSchemas();
     const result = createFlightDocumentScene2DMaterializationFromText(yaml, schemas);
@@ -170,7 +168,14 @@ describe('createFlightDocumentScene2DMaterializationFromText', () => {
   });
 
   it('returns null for a Scene3D YAML document', () => {
-    const yaml = ['flight: 1', 'kind: Scene3D', 'scene:', '  kind: Node3D'].join('\n');
+    const yaml = [
+      'flight: 1',
+      'defaultScene: 0',
+      'scenes:',
+      '  - kind: Scene3D',
+      '    scene:',
+      '      kind: Node3D',
+    ].join('\n');
     const result = createFlightDocumentScene2DMaterializationFromText(yaml, createTestSchemas());
     expect(result).toBeNull();
   });
@@ -184,43 +189,40 @@ describe('createFlightDocumentScene2DMaterializationFromText', () => {
 
 describe('explainFlightDocumentRefusal', () => {
   it('explains a dimension mismatch', () => {
-    const document = {
+    const document = createTestDocument({
       cameras: [],
       kind: 'Scene3D',
       lights: [],
-      resources: [],
       scene: { children: [], fields: {}, kind: 'Node3D' },
-      version: 1,
-    } as FlightDocument;
-    const explanation = explainFlightDocumentRefusal(document, 'Scene2D');
+    });
+    const explanation = explainFlightDocumentRefusal(document, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.StructureInvalid);
-    expect(explanation!.path).toBe('kind');
+    expect(explanation!.path).toBe('scenes[0].kind');
   });
 
   it('explains an unsupported version', () => {
     const document = {
-      backgroundColor: null,
-      kind: 'Scene2D',
-      resources: [],
-      scene: { children: [], fields: {}, kind: DisplayObjectKind },
+      ...createTestDocument({
+        backgroundColor: null,
+        kind: 'Scene2D',
+        scene: { children: [], fields: {}, kind: DisplayObjectKind },
+      }),
       version: 99,
-    } as unknown as FlightDocumentScene2D;
-    const explanation = explainFlightDocumentRefusal(document, 'Scene2D');
+    } as unknown as FlightDocument;
+    const explanation = explainFlightDocumentRefusal(document, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.VersionUnsupported);
     expect(explanation!.version).toBe(99);
   });
 
   it('returns null when the document is valid', () => {
-    const document: FlightDocumentScene2D = {
+    const document = createTestDocument({
       backgroundColor: null,
       kind: 'Scene2D',
-      resources: [],
       scene: { children: [], fields: {}, kind: DisplayObjectKind },
-      version: 1,
-    };
-    const explanation = explainFlightDocumentRefusal(document, 'Scene2D');
+    });
+    const explanation = explainFlightDocumentRefusal(document, 'Scene2D', createTestSchemas());
     expect(explanation).toBeNull();
   });
 });
@@ -228,7 +230,7 @@ describe('explainFlightDocumentRefusal', () => {
 describe('explainFlightDocumentRefusalFromText', () => {
   it('explains an anchor refusal with parser position', () => {
     const yaml = 'flight: 1\nkind: Scene2D\nanchor: &ref value\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.AnchorUnsupported);
     expect(explanation!.line).toBeGreaterThan(0);
@@ -238,21 +240,21 @@ describe('explainFlightDocumentRefusalFromText', () => {
 
   it('explains an alias refusal', () => {
     const yaml = 'flight: 1\nkind: Scene2D\nref: *alias\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.AliasUnsupported);
   });
 
   it('explains a tag refusal', () => {
     const yaml = 'flight: 1\nkind: Scene2D\ntyped: !custom value\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.TagUnsupported);
   });
 
   it('explains a document separator refusal', () => {
     const yaml = 'flight: 1\n---\nkind: Scene2D\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.DocumentSeparatorUnsupported);
   });
@@ -260,7 +262,7 @@ describe('explainFlightDocumentRefusalFromText', () => {
   it('explains a key limit refusal with limit and actual', () => {
     const longKey = 'k'.repeat(300);
     const yaml = 'flight: 1\nkind: Scene2D\n' + longKey + ': value\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.KeyCodeUnitsLimitExceeded);
     expect(explanation!.limit).toBe(256);
@@ -271,14 +273,14 @@ describe('explainFlightDocumentRefusalFromText', () => {
   });
 
   it('returns null for valid Scene2D text', () => {
-    const yaml = 'flight: 1\nkind: Scene2D\nscene:\n  kind: DisplayObject\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const yaml = 'flight: 1\ndefaultScene: 0\nscenes:\n  - kind: Scene2D\n    scene:\n      kind: DisplayObject\n';
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).toBeNull();
   });
 
   it('explains an unsupported version in valid YAML', () => {
-    const yaml = 'flight: 99\nkind: Scene2D\nscene:\n  kind: DisplayObject\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const yaml = 'flight: 99\ndefaultScene: 0\nscenes:\n  - kind: Scene2D\n    scene:\n      kind: DisplayObject\n';
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.VersionUnsupported);
     expect(explanation!.path).toBe('version');
@@ -286,20 +288,20 @@ describe('explainFlightDocumentRefusalFromText', () => {
   });
 
   it('explains a dimension mismatch in valid YAML', () => {
-    const yaml = 'flight: 1\nkind: Scene3D\nscene:\n  kind: Node3D\n';
-    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D');
+    const yaml = 'flight: 1\ndefaultScene: 0\nscenes:\n  - kind: Scene3D\n    scene:\n      kind: Node3D\n';
+    const explanation = explainFlightDocumentRefusalFromText(yaml, 'Scene2D', createTestSchemas());
     expect(explanation).not.toBeNull();
     expect(explanation!.reason).toBe(FlightDocumentRefusalReason.StructureInvalid);
-    expect(explanation!.path).toBe('kind');
+    expect(explanation!.path).toBe('scenes[0].kind');
   });
 });
 
-describe('serializeFlightDocument', () => {
+describe('formatFlightDocumentText', () => {
   it('round-trips a minimal Scene2D through model and text', () => {
     const scene = createScene2D();
     const schemas = createTestSchemas();
-    const document = createFlightDocumentFromScene2D(scene, schemas);
-    const text = serializeFlightDocument(document);
+    const document = createTestDocument(createFlightDocumentFromScene2D(scene, schemas));
+    const text = formatFlightDocumentText(document);
     expect(typeof text).toBe('string');
     expect(text).toContain('flight: 1');
     expect(text).toContain('kind: Scene2D');
@@ -312,13 +314,65 @@ describe('serializeFlightDocument', () => {
     sprite.y = 100;
     addNodeChild(scene.root, sprite);
     const schemas = createTestSchemas();
-    const document = createFlightDocumentFromScene2D(scene, schemas);
-    const text = serializeFlightDocument(document);
+    const document = createTestDocument(createFlightDocumentFromScene2D(scene, schemas));
+    const text = formatFlightDocumentText(document);
     const reparsed = createFlightDocumentScene2DMaterializationFromText(text, schemas);
     expect(reparsed).not.toBeNull();
   });
 });
 
+describe('model-to-text explain parity', () => {
+  it.each<{
+    document: Readonly<FlightDocument>;
+    expectedPath: string;
+    expectedReason: FlightDocumentRefusalReason;
+    label: string;
+  }>([
+    {
+      label: 'wrong dimension (scene 0)',
+      document: createTestDocument({
+        cameras: [],
+        kind: 'Scene3D',
+        lights: [],
+        scene: { children: [], fields: {}, kind: 'Node3D' },
+      }),
+      expectedReason: FlightDocumentRefusalReason.StructureInvalid,
+      expectedPath: 'scenes[0].kind',
+    },
+    {
+      label: 'unregistered node kind (scene 0)',
+      document: createTestDocument({
+        backgroundColor: null,
+        kind: 'Scene2D',
+        scene: {
+          children: [{ children: [], fields: {}, kind: 'acme.Unknown' }],
+          fields: {},
+          kind: DisplayObjectKind,
+        },
+      }),
+      expectedReason: FlightDocumentRefusalReason.NodeKindUnregistered,
+      expectedPath: 'scenes[0].scene.children[0]',
+    },
+  ])('model and text explain agree on $label', ({ document, expectedPath, expectedReason }) => {
+    const modelResult = explainFlightDocumentRefusal(document, 'Scene2D', createTestSchemas());
+    const text = formatFlightDocumentText(document);
+    const textResult = explainFlightDocumentRefusalFromText(text, 'Scene2D', createTestSchemas());
+    expect(modelResult).not.toBeNull();
+    expect(textResult).not.toBeNull();
+    expect(textResult!.reason).toBe(modelResult!.reason);
+    expect(textResult!.path).toBe(modelResult!.path);
+    expect(modelResult!.reason).toBe(expectedReason);
+    expect(modelResult!.path).toBe(expectedPath);
+  });
+});
+
+function createTestDocument(
+  scene: FlightDocumentScene,
+  resources: FlightDocumentResourceDescriptor[] = [],
+): FlightDocument {
+  return { defaultScene: 0, resources, scenes: [scene], version: 1 };
+}
+
 function createTestSchemas(): FlightDocumentSchemaRegistry {
   const displayObjectSchema: FlightDocumentNodeSchema = {
     createNode: (fields: Readonly<FlightDocumentFields>, _resources: FlightDocumentResourceLookup) => {
@@ -393,3 +447,75 @@ const TRANSFORM_FIELD_SCHEMAS = [
   { 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
+// the round trip lossy in a way no per-child test could see.
+describe('Scene2D root fidelity', () => {
+  it('preserves the authored root kind', () => {
+    const document = rootDocument2D(SpriteKind, {});
+    const materialization = createFlightDocumentScene2DMaterialization(document, createTestSchemas());
+    expect(materialization).not.toBeNull();
+    expect(materialization!.scene.root.kind).toBe(SpriteKind);
+  });
+
+  it('preserves fields authored on the root', () => {
+    const document = rootDocument2D(DisplayObjectKind, { x: 100, y: 200 });
+    const materialization = createFlightDocumentScene2DMaterialization(document, createTestSchemas());
+    expect(materialization).not.toBeNull();
+    const root = materialization!.scene.root as unknown as { x: number; y: number };
+    expect(root.x).toBe(100);
+    expect(root.y).toBe(200);
+  });
+
+  it('round-trips a root with authored fields without losing them', () => {
+    const schemas = createTestSchemas();
+    const scene = createScene2D();
+    (scene.root as unknown as { x: number; y: number }).x = 7;
+    (scene.root as unknown as { x: number; y: number }).y = 9;
+
+    const document = createFlightDocumentFromScene2D(scene, schemas);
+    const wrapped = { defaultScene: 0, resources: [], scenes: [document], version: 1 } as unknown as FlightDocument;
+    const back = createFlightDocumentScene2DMaterialization(wrapped, schemas);
+
+    expect(back).not.toBeNull();
+    const root = back!.scene.root as unknown as { x: number; y: number };
+    expect(root.x).toBe(7);
+    expect(root.y).toBe(9);
+  });
+
+  // ★ A REGISTERED kind of the WRONG DIMENSION is the interesting refusal: it is not an unregistered kind,
+  // so the unregistered-kind check passes it through, and it then builds a Node3D as a 2D scene root.
+  it('refuses a registered root whose kind belongs to the other dimension', () => {
+    // The kind must be REGISTERED for this to be the case under test — an unregistered kind is caught one
+    // check earlier, and that is a different refusal with a different remedy.
+    const schemas = createTestSchemas();
+    schemas.nodeSchemas = withRegistryTableEntry(schemas.nodeSchemas, Node3DKind, {
+      createNode: () => createNode3D() as unknown as NodeAny,
+      fields: [],
+      kind: Node3DKind,
+      writeNodeFields: () => true,
+    });
+    const document = rootDocument2D(Node3DKind, {});
+    expect(createFlightDocumentScene2DMaterialization(document, schemas)).toBeNull();
+    expect(explainFlightDocumentRefusal(document, 'Scene2D', schemas)).toMatchObject({
+      reason: FlightDocumentRefusalReason.RootKindMismatch,
+    });
+  });
+});
+
+function rootDocument2D(kind: string, fields: Record<string, unknown>): FlightDocument {
+  return {
+    defaultScene: 0,
+    resources: [],
+    scenes: [
+      {
+        backgroundColor: null,
+        kind: 'Scene2D',
+        scene: { children: [], fields, kind },
+      },
+    ],
+    version: 1,
+  } as unknown as FlightDocument;
+}