@vgai/engine 0.2.0 → 0.3.0

package/dist/scene/schema/scene-file.d.ts

@@ -0,0 +1,304 @@
+import { z } from 'zod';
+import { type SceneEntity } from './entity';
+export declare const SceneFileSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    name: z.ZodString;
+    environment: z.ZodOptional<z.ZodObject<{
+        background: z.ZodOptional<z.ZodString>;
+        ambient: z.ZodOptional<z.ZodObject<{
+            color: z.ZodString;
+            intensity: z.ZodNumber;
+        }, z.core.$strip>>;
+        fog: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<{
+                linear: "linear";
+                exponential: "exponential";
+            }>;
+            color: z.ZodString;
+            near: z.ZodOptional<z.ZodNumber>;
+            far: z.ZodOptional<z.ZodNumber>;
+            density: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        skybox: z.ZodOptional<z.ZodString>;
+        envMapIntensity: z.ZodOptional<z.ZodNumber>;
+        toneMapping: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                linear: "linear";
+                reinhard: "reinhard";
+                cineon: "cineon";
+                aces: "aces";
+                agx: "agx";
+            }>>;
+            exposure: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        postProcessing: z.ZodOptional<z.ZodObject<{
+            bloom: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                intensity: z.ZodOptional<z.ZodNumber>;
+                luminanceThreshold: z.ZodOptional<z.ZodNumber>;
+                luminanceSmoothing: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            vignette: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                darkness: z.ZodOptional<z.ZodNumber>;
+                offset: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            brightnessContrast: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                brightness: z.ZodOptional<z.ZodNumber>;
+                contrast: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            hueSaturation: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                hue: z.ZodOptional<z.ZodNumber>;
+                saturation: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            sepia: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                intensity: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            colorDepth: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                bits: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            chromaticAberration: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                offsetX: z.ZodOptional<z.ZodNumber>;
+                offsetY: z.ZodOptional<z.ZodNumber>;
+                radialModulation: z.ZodOptional<z.ZodBoolean>;
+                modulationOffset: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            lensDistortion: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                distortionX: z.ZodOptional<z.ZodNumber>;
+                distortionY: z.ZodOptional<z.ZodNumber>;
+                focalLengthX: z.ZodOptional<z.ZodNumber>;
+                focalLengthY: z.ZodOptional<z.ZodNumber>;
+                skew: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            depthOfField: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                worldFocusDistance: z.ZodOptional<z.ZodNumber>;
+                worldFocusRange: z.ZodOptional<z.ZodNumber>;
+                bokehScale: z.ZodOptional<z.ZodNumber>;
+                focalLength: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            tiltShift: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                offset: z.ZodOptional<z.ZodNumber>;
+                rotation: z.ZodOptional<z.ZodNumber>;
+                focusArea: z.ZodOptional<z.ZodNumber>;
+                feather: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            noise: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                premultiply: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            scanline: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                density: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            dotScreen: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                angle: z.ZodOptional<z.ZodNumber>;
+                scale: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            grid: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                scale: z.ZodOptional<z.ZodNumber>;
+                lineWidth: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            pixelation: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                granularity: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            glitch: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                delayX: z.ZodOptional<z.ZodNumber>;
+                delayY: z.ZodOptional<z.ZodNumber>;
+                durationX: z.ZodOptional<z.ZodNumber>;
+                durationY: z.ZodOptional<z.ZodNumber>;
+                strengthX: z.ZodOptional<z.ZodNumber>;
+                strengthY: z.ZodOptional<z.ZodNumber>;
+                columns: z.ZodOptional<z.ZodNumber>;
+                ratio: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            shockWave: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                speed: z.ZodOptional<z.ZodNumber>;
+                maxRadius: z.ZodOptional<z.ZodNumber>;
+                waveSize: z.ZodOptional<z.ZodNumber>;
+                amplitude: z.ZodOptional<z.ZodNumber>;
+                positionX: z.ZodOptional<z.ZodNumber>;
+                positionY: z.ZodOptional<z.ZodNumber>;
+                positionZ: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            smaa: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                preset: z.ZodOptional<z.ZodEnum<{
+                    low: "low";
+                    medium: "medium";
+                    high: "high";
+                    ultra: "ultra";
+                }>>;
+            }, z.core.$strip>>;
+            ssao: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                radius: z.ZodOptional<z.ZodNumber>;
+                intensity: z.ZodOptional<z.ZodNumber>;
+                bias: z.ZodOptional<z.ZodNumber>;
+                samples: z.ZodOptional<z.ZodNumber>;
+                rings: z.ZodOptional<z.ZodNumber>;
+                fade: z.ZodOptional<z.ZodNumber>;
+                color: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            n8ao: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                aoSamples: z.ZodOptional<z.ZodNumber>;
+                aoRadius: z.ZodOptional<z.ZodNumber>;
+                intensity: z.ZodOptional<z.ZodNumber>;
+                denoiseSamples: z.ZodOptional<z.ZodNumber>;
+                denoiseRadius: z.ZodOptional<z.ZodNumber>;
+                distanceFalloff: z.ZodOptional<z.ZodNumber>;
+                screenSpaceRadius: z.ZodOptional<z.ZodBoolean>;
+                color: z.ZodOptional<z.ZodString>;
+                halfRes: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            godRays: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                sourceEntity: z.ZodOptional<z.ZodString>;
+                density: z.ZodOptional<z.ZodNumber>;
+                decay: z.ZodOptional<z.ZodNumber>;
+                weight: z.ZodOptional<z.ZodNumber>;
+                exposure: z.ZodOptional<z.ZodNumber>;
+                samples: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            outline: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                edgeStrength: z.ZodOptional<z.ZodNumber>;
+                pulseSpeed: z.ZodOptional<z.ZodNumber>;
+                visibleEdgeColor: z.ZodOptional<z.ZodString>;
+                hiddenEdgeColor: z.ZodOptional<z.ZodString>;
+                xRay: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            ssr: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                intensity: z.ZodOptional<z.ZodNumber>;
+                exponent: z.ZodOptional<z.ZodNumber>;
+                distance: z.ZodOptional<z.ZodNumber>;
+                thickness: z.ZodOptional<z.ZodNumber>;
+                maxRoughness: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            ssgi: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                intensity: z.ZodOptional<z.ZodNumber>;
+                distance: z.ZodOptional<z.ZodNumber>;
+                thickness: z.ZodOptional<z.ZodNumber>;
+                maxRoughness: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            motionBlur: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+                intensity: z.ZodOptional<z.ZodNumber>;
+                jitter: z.ZodOptional<z.ZodNumber>;
+                samples: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        navigation: z.ZodOptional<z.ZodObject<{
+            cellSize: z.ZodOptional<z.ZodNumber>;
+            cellHeight: z.ZodOptional<z.ZodNumber>;
+            walkableSlopeAngle: z.ZodOptional<z.ZodNumber>;
+            walkableHeight: z.ZodOptional<z.ZodNumber>;
+            walkableClimb: z.ZodOptional<z.ZodNumber>;
+            walkableRadius: z.ZodOptional<z.ZodNumber>;
+            maxEdgeLen: z.ZodOptional<z.ZodNumber>;
+            maxSimplificationError: z.ZodOptional<z.ZodNumber>;
+            minRegionArea: z.ZodOptional<z.ZodNumber>;
+            mergeRegionArea: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        physics: z.ZodOptional<z.ZodObject<{
+            collisionLayers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        rendering: z.ZodOptional<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    }, z.core.$strip>>;
+    entities: z.ZodArray<z.ZodType<SceneEntity, unknown, z.core.$ZodTypeInternals<SceneEntity, unknown>>>;
+    ui: z.ZodOptional<z.ZodArray<z.ZodType<import("./ui").UIRoot, unknown, z.core.$ZodTypeInternals<import("./ui").UIRoot, unknown>>>>;
+}, z.core.$strip>;
+export type SceneFile = z.infer<typeof SceneFileSchema>;
+export declare const PrefabFileSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    name: z.ZodString;
+    root: z.ZodType<SceneEntity, unknown, z.core.$ZodTypeInternals<SceneEntity, unknown>>;
+}, z.core.$strip>;
+export type PrefabFile = z.infer<typeof PrefabFileSchema>;
+/**
+ * Merge a prefab root definition with an instance's overrides.
+ *
+ * Per-field merge rules (exactly as implemented below):
+ *
+ * - transform: instance wins entirely if set, else the prefab root's transform
+ *   (placement is per-instance; transforms are not blended field-by-field).
+ * - name: instance always wins.
+ * - id: instance wins if set (each instance has its own id); else prefab's.
+ * - prefab: stripped from the result so spawnEntity recursion terminates.
+ *
+ * - Sections — `mesh`, `light`, `camera`, `animation`, `audio`, `particles`,
+ *   `spline`, `render`: SHALLOW merge per section. If the instance sets the
+ *   section, its top-level fields override the prefab root's same-named
+ *   fields ({ ...prefabSection, ...instanceSection }); fields the instance
+ *   omits fall through to the prefab. Nested objects are replaced, not
+ *   deep-merged. If only the prefab has the section it is kept as-is.
+ *   (CB4: `spline` is included here; CB5: see metadata below; T1.10: `render`
+ *   is now included — an instance's per-entity render overrides are honored
+ *   and merged the same way as `mesh`/`material`.)
+ *
+ *   NOTE (T1.10 audit): `mesh.instancerParams`/`mesh.generatorParams` and
+ *   `animation.parameters`/`animation.clipAliases` are keyed dict maps nested
+ *   one level down, and `particles` nests discriminated-union shapes/behaviors
+ *   arrays. These have the same "shallow replace" defect as `material`/
+ *   `physics` did, but no single well-defined field-merge semantics (dict keys
+ *   authors may legitimately want fully replaced; discriminated unions can't
+ *   be safely field-merged across different variants). Left as wholesale
+ *   per-section replace; flagged here rather than silently "fixed" with a
+ *   guess. Revisit if this causes real authoring pain.
+ *
+ * - `material`: shallow merge at the top level, PLUS deep-merge of the four
+ *   nested physical-material feature groups (`clearcoat`, `transmission`,
+ *   `sheen`, `iridescence`) so an instance overriding e.g. `clearcoat.clearcoat`
+ *   preserves the prefab's `clearcoat.clearcoatRoughness` (T1.10 — previously
+ *   these nested groups were wholesale-replaced like any other shallow field).
+ *
+ * - `physics`: shallow merge at the top level (`bodyType`, `mass`), PLUS
+ *   deep-merge of the nested `collider` object so a partial instance collider
+ *   override (e.g. just `isSensor`) preserves the prefab's `type` and other
+ *   collider fields instead of dropping them (T1.10 AC).
+ *
+ * - `shadow`: shallow merge at the top level, PLUS deep-merge of the nested
+ *   `camera` (shadow-camera frustum bounds) object, for the same reason as
+ *   `physics.collider` (T1.10 audit — same defect, same fix).
+ *
+ * - components: DEEP merge, keyed by component name. The union of component
+ *   names is taken; for each, instance fields override prefab fields
+ *   ({ ...prefabComp, ...instanceComp }).
+ *
+ * - joints: REPLACE — if the instance sets joints, its array wins wholesale
+ *   (arrays are not field-mergeable); else the prefab's joints are kept.
+ * - children: APPEND — prefab children first, then instance-only children.
+ *
+ * - Instance-level metadata `visible`, `materialRef`, `tags`, `locked`,
+ *   `navigation`, `pivot`: instance wins if explicitly set, otherwise the
+ *   prefab root's value is inherited. (CB5: spline + these metadata fields are
+ *   now instance-wins; previously dropped.)
+ *
+ * - Re-validation (T1.10): the merged entity is re-parsed through
+ *   `SceneEntitySchema` before being returned. This is what makes the
+ *   material/materialRef mutual-exclusion refine fire on the MERGED result —
+ *   previously a prefab's inline `material` plus an instance's `materialRef`
+ *   (or vice versa) silently combined into an entity carrying both, bypassing
+ *   the refine entirely (it only ever saw the pre-merge, individually-valid
+ *   halves). A merge that produces an invalid entity now throws, naming the
+ *   offending prefab path + instance name.
+ */
+export declare function mergePrefabInstance(prefabRoot: SceneEntity, instance: SceneEntity): SceneEntity;
+//# sourceMappingURL=scene-file.d.ts.map

package/dist/scene/schema/scene-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-file.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/scene-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,UAAU,CAAC;AAI/D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAaU,CAAC;AAEvC,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,gBAAgB;;;;iBAMY,CAAC;AAE1C,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AA8D1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,WAAW,CA+B/F"}

package/dist/scene/schema/scene-file.js

@@ -0,0 +1,262 @@
+import { z } from 'zod';
+import { SceneEntitySchema } from './entity';
+import { SceneEnvironmentSchema } from './environment';
+import { UIRootSchema } from './ui';
+export const SceneFileSchema = z
+    .object({
+    version: z.number().describe('Scene file format version'),
+    name: z.string().describe('Scene display name'),
+    environment: SceneEnvironmentSchema.optional().describe('Scene-level environment settings'),
+    entities: z.array(SceneEntitySchema).describe('Top-level entities in the scene'),
+    // UI roots (HUD/menus) attached to the scene graph as data. Optional and
+    // additive — pre-UI scenes (no `ui` field) load unchanged (A4 versioning).
+    ui: z
+        .array(UIRootSchema)
+        .optional()
+        .describe('React UI roots (canvases) attached to the scene graph (A1)'),
+})
+    .describe('Scene file (.vscn.json)');
+export const PrefabFileSchema = z
+    .object({
+    version: z.number().describe('Prefab file format version'),
+    name: z.string().describe('Prefab display name'),
+    root: SceneEntitySchema.describe('Root entity of the prefab'),
+})
+    .describe('Prefab file (.prefab.json)');
+/**
+ * Shallow-merge a section, but deep-merge specific named nested sub-objects
+ * within it (e.g. `physics.collider`, `material.clearcoat`). A partial
+ * instance override of a nested sub-object would otherwise wholesale-replace
+ * it and drop the prefab's other fields in that sub-object (e.g. an instance
+ * overriding one collider field would silently lose the prefab's `type`).
+ */
+function mergeSectionDeepNested(prefabSection, instanceSection, nestedKeys) {
+    if (instanceSection === undefined)
+        return prefabSection;
+    if (prefabSection === undefined)
+        return instanceSection;
+    const merged = { ...prefabSection, ...instanceSection };
+    for (const key of nestedKeys) {
+        const p = prefabSection[key];
+        const i = instanceSection[key];
+        if (i !== undefined &&
+            p !== undefined &&
+            typeof i === 'object' &&
+            typeof p === 'object' &&
+            !Array.isArray(i) &&
+            !Array.isArray(p)) {
+            merged[key] = { ...p, ...i };
+        }
+    }
+    return merged;
+}
+/**
+ * Sections whose nested sub-object needs deep merging (T1.10) — see the
+ * `mergePrefabInstance` docstring for the reasoning behind each.
+ */
+const DEEP_NESTED_SECTIONS = [
+    { key: 'physics', nestedKeys: ['collider'] },
+    { key: 'material', nestedKeys: ['clearcoat', 'transmission', 'sheen', 'iridescence'] },
+    { key: 'shadow', nestedKeys: ['camera'] },
+];
+/**
+ * Re-validate a merged entity through `SceneEntitySchema` (T1.10). This is
+ * the gate that catches a prefab's inline `material` combined with an
+ * instance's `materialRef` (or vice versa) — each half is individually valid,
+ * so only the MERGED entity can trip the material/materialRef
+ * mutual-exclusion refine. Throws naming the offending prefab path + instance
+ * so a bad scene file points straight at the offender.
+ */
+function validateMergedEntity(merged, instance) {
+    const validated = SceneEntitySchema.safeParse(merged);
+    if (validated.success)
+        return validated.data;
+    const issues = validated.error.issues.map((issue) => issue.message).join('; ');
+    const prefabPath = instance.prefab ?? '<unknown prefab>';
+    throw new Error(`Prefab merge produced an invalid entity — prefab "${prefabPath}", instance "${instance.name}": ${issues}`);
+}
+/**
+ * Merge a prefab root definition with an instance's overrides.
+ *
+ * Per-field merge rules (exactly as implemented below):
+ *
+ * - transform: instance wins entirely if set, else the prefab root's transform
+ *   (placement is per-instance; transforms are not blended field-by-field).
+ * - name: instance always wins.
+ * - id: instance wins if set (each instance has its own id); else prefab's.
+ * - prefab: stripped from the result so spawnEntity recursion terminates.
+ *
+ * - Sections — `mesh`, `light`, `camera`, `animation`, `audio`, `particles`,
+ *   `spline`, `render`: SHALLOW merge per section. If the instance sets the
+ *   section, its top-level fields override the prefab root's same-named
+ *   fields ({ ...prefabSection, ...instanceSection }); fields the instance
+ *   omits fall through to the prefab. Nested objects are replaced, not
+ *   deep-merged. If only the prefab has the section it is kept as-is.
+ *   (CB4: `spline` is included here; CB5: see metadata below; T1.10: `render`
+ *   is now included — an instance's per-entity render overrides are honored
+ *   and merged the same way as `mesh`/`material`.)
+ *
+ *   NOTE (T1.10 audit): `mesh.instancerParams`/`mesh.generatorParams` and
+ *   `animation.parameters`/`animation.clipAliases` are keyed dict maps nested
+ *   one level down, and `particles` nests discriminated-union shapes/behaviors
+ *   arrays. These have the same "shallow replace" defect as `material`/
+ *   `physics` did, but no single well-defined field-merge semantics (dict keys
+ *   authors may legitimately want fully replaced; discriminated unions can't
+ *   be safely field-merged across different variants). Left as wholesale
+ *   per-section replace; flagged here rather than silently "fixed" with a
+ *   guess. Revisit if this causes real authoring pain.
+ *
+ * - `material`: shallow merge at the top level, PLUS deep-merge of the four
+ *   nested physical-material feature groups (`clearcoat`, `transmission`,
+ *   `sheen`, `iridescence`) so an instance overriding e.g. `clearcoat.clearcoat`
+ *   preserves the prefab's `clearcoat.clearcoatRoughness` (T1.10 — previously
+ *   these nested groups were wholesale-replaced like any other shallow field).
+ *
+ * - `physics`: shallow merge at the top level (`bodyType`, `mass`), PLUS
+ *   deep-merge of the nested `collider` object so a partial instance collider
+ *   override (e.g. just `isSensor`) preserves the prefab's `type` and other
+ *   collider fields instead of dropping them (T1.10 AC).
+ *
+ * - `shadow`: shallow merge at the top level, PLUS deep-merge of the nested
+ *   `camera` (shadow-camera frustum bounds) object, for the same reason as
+ *   `physics.collider` (T1.10 audit — same defect, same fix).
+ *
+ * - components: DEEP merge, keyed by component name. The union of component
+ *   names is taken; for each, instance fields override prefab fields
+ *   ({ ...prefabComp, ...instanceComp }).
+ *
+ * - joints: REPLACE — if the instance sets joints, its array wins wholesale
+ *   (arrays are not field-mergeable); else the prefab's joints are kept.
+ * - children: APPEND — prefab children first, then instance-only children.
+ *
+ * - Instance-level metadata `visible`, `materialRef`, `tags`, `locked`,
+ *   `navigation`, `pivot`: instance wins if explicitly set, otherwise the
+ *   prefab root's value is inherited. (CB5: spline + these metadata fields are
+ *   now instance-wins; previously dropped.)
+ *
+ * - Re-validation (T1.10): the merged entity is re-parsed through
+ *   `SceneEntitySchema` before being returned. This is what makes the
+ *   material/materialRef mutual-exclusion refine fire on the MERGED result —
+ *   previously a prefab's inline `material` plus an instance's `materialRef`
+ *   (or vice versa) silently combined into an entity carrying both, bypassing
+ *   the refine entirely (it only ever saw the pre-merge, individually-valid
+ *   halves). A merge that produces an invalid entity now throws, naming the
+ *   offending prefab path + instance name.
+ */
+export function mergePrefabInstance(prefabRoot, instance) {
+    const merged = {
+        ...prefabRoot,
+        name: instance.name,
+    };
+    // Handle optional fields explicitly to satisfy exactOptionalPropertyTypes
+    const resolvedTransform = instance.transform ?? prefabRoot.transform;
+    if (resolvedTransform)
+        merged.transform = resolvedTransform;
+    if (instance.id)
+        merged.id = instance.id;
+    // Strip prefab field so spawnEntity won't recurse infinitely
+    delete merged.prefab;
+    applyInstanceMetadata(merged, prefabRoot, instance);
+    applyDeepNestedSections(merged, prefabRoot, instance);
+    applyShallowSections(merged, prefabRoot, instance);
+    const components = mergeComponents(prefabRoot, instance);
+    if (components !== undefined)
+        merged.components = components;
+    // Joints: instance wins (array, not shallow-mergeable)
+    if (instance.joints !== undefined) {
+        merged.joints = instance.joints;
+    }
+    const children = mergeChildren(prefabRoot, instance);
+    if (children !== undefined)
+        merged.children = children;
+    // Re-validate the merged result (T1.10) — see `validateMergedEntity` above.
+    return validateMergedEntity(merged, instance);
+}
+/**
+ * Visibility + instance-level metadata (`materialRef`, `tags`, `locked`,
+ * `navigation`, `pivot`): instance wins if explicitly set, otherwise the
+ * prefab root's value (already present on `merged` via the initial spread in
+ * `mergePrefabInstance`) is kept.
+ */
+function applyInstanceMetadata(merged, prefabRoot, instance) {
+    if (instance.visible !== undefined)
+        merged.visible = instance.visible;
+    if (instance.materialRef !== undefined)
+        merged.materialRef = instance.materialRef;
+    if (instance.tags !== undefined)
+        merged.tags = instance.tags;
+    if (instance.locked !== undefined)
+        merged.locked = instance.locked;
+    if (instance.navigation !== undefined)
+        merged.navigation = instance.navigation;
+    if (instance.pivot !== undefined) {
+        merged.pivot = instance.pivot;
+    }
+    else if (prefabRoot.pivot !== undefined) {
+        merged.pivot = prefabRoot.pivot;
+    }
+}
+/**
+ * Sections whose nested sub-object needs deep (not shallow) merging — see the
+ * `mergePrefabInstance` docstring for the reasoning behind each.
+ */
+function applyDeepNestedSections(merged, prefabRoot, instance) {
+    for (const { key, nestedKeys } of DEEP_NESTED_SECTIONS) {
+        const result = mergeSectionDeepNested(
+        // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+        prefabRoot[key], 
+        // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+        instance[key], nestedKeys);
+        // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+        if (result !== undefined)
+            merged[key] = result;
+    }
+}
+/** Sections shallow-merged whole (material/physics/shadow handled separately above). */
+const SHALLOW_SECTIONS = [
+    'mesh',
+    'light',
+    'camera',
+    'animation',
+    'audio',
+    'particles',
+    'spline',
+    'render',
+];
+/**
+ * Shallow merge per remaining section — instance fields override within the
+ * section ({ ...prefabSection, ...instanceSection }); if only the prefab has
+ * the section it is kept as-is.
+ */
+function applyShallowSections(merged, prefabRoot, instance) {
+    for (const key of SHALLOW_SECTIONS) {
+        if (instance[key] === undefined)
+            continue;
+        // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+        merged[key] =
+            prefabRoot[key] !== undefined
+                ? // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+                    { ...prefabRoot[key], ...instance[key] }
+                : instance[key];
+    }
+}
+/** Deep merge `components`, keyed by component name (instance fields win per-component). */
+function mergeComponents(prefabRoot, instance) {
+    if (!instance.components && !prefabRoot.components)
+        return undefined;
+    const base = prefabRoot.components ?? {};
+    const over = instance.components ?? {};
+    const result = {};
+    for (const comp of new Set([...Object.keys(base), ...Object.keys(over)])) {
+        result[comp] = { ...base[comp], ...over[comp] };
+    }
+    return result;
+}
+/** Children: prefab children first, then instance-only children appended. */
+function mergeChildren(prefabRoot, instance) {
+    const prefabChildren = prefabRoot.children ?? [];
+    const instanceChildren = instance.children ?? [];
+    if (prefabChildren.length === 0 && instanceChildren.length === 0)
+        return undefined;
+    return [...prefabChildren, ...instanceChildren];
+}

package/dist/scene/schema/shadow.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export declare const SceneShadowSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    mapSize: z.ZodOptional<z.ZodNumber>;
+    camera: z.ZodOptional<z.ZodObject<{
+        left: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        top: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    radius: z.ZodOptional<z.ZodNumber>;
+    bias: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Partial schema for prefab instance overrides (enabled not required). */
+export declare const SceneShadowOverrideSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    mapSize: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    camera: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        left: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        top: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    radius: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    bias: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type SceneShadow = z.infer<typeof SceneShadowSchema>;
+//# sourceMappingURL=shadow.d.ts.map

package/dist/scene/schema/shadow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/shadow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAgBa,CAAC;AAE5C,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB;;;;;;;;;;;iBAA8B,CAAC;AAErE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/scene/schema/shadow.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export const SceneShadowSchema = z
+    .object({
+    enabled: z.boolean().describe('Whether this light casts shadows'),
+    mapSize: z.number().optional().describe('Shadow map resolution in pixels (e.g. 1024, 2048)'),
+    camera: z
+        .object({
+        left: z.number().optional().describe('Left bound of shadow camera frustum'),
+        right: z.number().optional().describe('Right bound of shadow camera frustum'),
+        top: z.number().optional().describe('Top bound of shadow camera frustum'),
+        bottom: z.number().optional().describe('Bottom bound of shadow camera frustum'),
+    })
+        .optional()
+        .describe('Shadow camera frustum bounds (directional lights)'),
+    radius: z.number().optional().describe('Shadow map blur radius for soft shadows'),
+    bias: z.number().optional().describe('Shadow bias to reduce shadow acne artifacts'),
+})
+    .describe('Shadow casting configuration');
+/** Partial schema for prefab instance overrides (enabled not required). */
+export const SceneShadowOverrideSchema = SceneShadowSchema.partial();

package/dist/scene/schema/spline.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export declare const SceneSplineSchema: z.ZodObject<{
+    curveType: z.ZodEnum<{
+        centripetal: "centripetal";
+        chordal: "chordal";
+        catmullrom: "catmullrom";
+    }>;
+    points: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    closed: z.ZodOptional<z.ZodBoolean>;
+    tension: z.ZodOptional<z.ZodNumber>;
+    resolution: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SceneSpline = z.infer<typeof SceneSplineSchema>;
+export declare const SceneSplineOverrideSchema: z.ZodObject<{
+    curveType: z.ZodOptional<z.ZodEnum<{
+        centripetal: "centripetal";
+        chordal: "chordal";
+        catmullrom: "catmullrom";
+    }>>;
+    points: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>>;
+    closed: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    tension: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    resolution: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+//# sourceMappingURL=spline.d.ts.map

package/dist/scene/schema/spline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/spline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,iBAAiB;;;;;;;;;;iBAa5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,yBAAyB;;;;;;;;;;iBAA8B,CAAC"}

package/dist/scene/schema/spline.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { Vec3Schema } from './tuples';
+export const SceneSplineSchema = z.object({
+    curveType: z
+        .enum(['centripetal', 'chordal', 'catmullrom'])
+        .describe('CatmullRomCurve3 parameterization type. Matches Three.js curveType parameter'),
+    points: z.array(Vec3Schema).min(2).describe('Control point positions in local space'),
+    closed: z.boolean().optional().describe('Whether the spline forms a closed loop'),
+    tension: z
+        .number()
+        .optional()
+        .describe('Curve tension (default 0.5). Only used when curveType is catmullrom; ignored for centripetal and chordal'),
+    resolution: z.number().optional().describe('Number of line segments for rendering the curve'),
+});
+export const SceneSplineOverrideSchema = SceneSplineSchema.partial();