@vgai/engine 0.5.0 → 0.5.2

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

@@ -1,303 +0,0 @@
-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>>>;
-}, z.core.$strict>;
-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

@@ -1 +0,0 @@
-{"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;AAG/D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQU,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

@@ -1,256 +0,0 @@
-import { z } from 'zod';
-import { SceneEntitySchema } from './entity';
-import { SceneEnvironmentSchema } from './environment';
-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'),
-})
-    .strict()
-    .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

@@ -1,28 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,20 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,15 +0,0 @@
-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();