@vgai/engine 0.5.5 → 0.5.6

package/dist/animation/xstate-animation-meta.js

@@ -0,0 +1,252 @@
+import { z } from 'zod';
+/**
+ * E1 — Zod/TypeScript metadata attached to XState state `meta.animation`
+ * (spec §11 E1, §5.6, §3.3).
+ *
+ * This module defines ONLY animation data: which clip(s) a state plays, how
+ * they loop/blend/crossfade, and (for locomotion-style states) how a 1D/2D/
+ * direct blend tree distributes weight across several clips from a live
+ * parameter. It intentionally contains **no transition vocabulary** — no
+ * `on`/`target`/`guard`/`always`/`after`/`entry`/`exit`. XState alone owns
+ * states, transitions, events, and guards (§3.3); this metadata is read-only
+ * data a binding (`xstate-animation-binding.ts`, E2) consumes to drive a
+ * `THREE.AnimationMixer` when XState enters/exits a state. Every schema below
+ * is `.strict()` specifically so that smuggling a transition-shaped key into
+ * `meta.animation` is a loud Zod "unrecognized key" error, not a silently
+ * ignored field (E1 AC: "Metadata contains no transition language").
+ *
+ * ## Native layered composition
+ *
+ * Parallel XState regions may drive independent named layers. Each layer can
+ * filter a clip to selected bone subtrees, scale its weight, and use normal
+ * override or Three's native additive blend mode. XState still owns all
+ * state/transition semantics; these fields only describe how the active
+ * state's native `AnimationAction`s are composed by the binding.
+ *
+ * ## Blend tree shape
+ *
+ * Deliberately structurally IDENTICAL to `anim-graph-types.ts`'s
+ * `BlendTreeDef` (same `type`/`parameter`/`parameterY`/`children[].clip`/
+ * `.threshold`/`.thresholdY`/`.weight` fields) so the binding can hand a
+ * parsed `AnimationBlendTree` straight to the existing, already-tested
+ * `evaluateBlendTree` (`blend-node.ts`) with zero conversion — E2 reuses that
+ * function verbatim rather than re-implementing 1D/2D/direct blend math.
+ */
+// ---------------------------------------------------------------------------
+// Blend tree children
+// ---------------------------------------------------------------------------
+const AnimationBlendChildSchema = z
+    .object({
+    clip: z.string().min(1).describe('Animation clip name this child plays'),
+    threshold: z.number().describe('1D/2D blend position on the primary parameter axis'),
+    thresholdY: z
+        .number()
+        .optional()
+        .describe('2D blend position on the secondary parameter axis (2D blend trees only)'),
+    weight: z
+        .number()
+        .min(0)
+        .optional()
+        .describe('Explicit weight for "direct" blend trees (ignored by 1D/2D)'),
+})
+    .strict();
+const AnimationBlendTree1DSchema = z
+    .object({
+    type: z.literal('1D').describe('Interpolates linearly between sorted children by threshold'),
+    parameter: z.string().min(1).describe('Context/selector value driving the blend'),
+    children: z
+        .array(AnimationBlendChildSchema)
+        .min(2, '1D blend tree needs at least 2 children to interpolate between'),
+})
+    .strict();
+const AnimationBlendTree2DSchema = z
+    .object({
+    type: z
+        .literal('2D')
+        .describe('Inverse-distance-weights children by (parameter, parameterY) position'),
+    parameter: z.string().min(1).describe('Primary axis context/selector value'),
+    parameterY: z.string().min(1).describe('Secondary axis context/selector value'),
+    children: z
+        .array(AnimationBlendChildSchema.extend({ thresholdY: z.number() }))
+        .min(1, '2D blend tree needs at least 1 child'),
+})
+    .strict();
+const AnimationBlendTreeDirectSchema = z
+    .object({
+    type: z.literal('direct').describe('Each child has an explicit weight, normalized to sum to 1'),
+    // `parameter` is unused by direct blending (evaluateBlendTree never reads
+    // it for `type: 'direct'`) but kept required+defaulted so the parsed
+    // value stays structurally assignable to `BlendTreeDef`
+    // (`anim-graph-types.ts`), which declares `parameter: string` for every
+    // blend mode — the same convention that type already uses.
+    parameter: z.string().default(''),
+    children: z
+        .array(AnimationBlendChildSchema.extend({ weight: z.number().min(0) }))
+        .min(1, 'direct blend tree needs at least 1 child'),
+})
+    .strict();
+export const AnimationBlendTreeSchema = z.discriminatedUnion('type', [
+    AnimationBlendTree1DSchema,
+    AnimationBlendTree2DSchema,
+    AnimationBlendTreeDirectSchema,
+]);
+// ---------------------------------------------------------------------------
+// Crossfade / blend-in-out metadata (shared by clip and blend-tree states)
+// ---------------------------------------------------------------------------
+const AnimationCrossfadeMetaSchema = z
+    .object({
+    duration: z
+        .number()
+        .min(0)
+        .default(0)
+        .describe('Seconds to blend from the previously active clip into this state on entry, applied via ' +
+        'native `AnimationAction.crossFadeTo`/`fadeIn` (E2). 0 = instant activation, no fade.'),
+    warp: z
+        .boolean()
+        .default(false)
+        .describe("Passed through to AnimationAction.crossFadeTo's `warp` param — linearly warps timeScale " +
+        'across the two clips during the blend so differing clip lengths line up. Default false.'),
+})
+    .strict()
+    .describe('Blend-in/out/crossfade timing for entering this state');
+const AnimationBoneMaskSchema = z
+    .object({
+    include: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe('Bone/object names whose complete descendant subtrees are retained'),
+    exclude: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe('Bone/object names whose complete descendant subtrees are removed'),
+})
+    .strict()
+    .refine((mask) => Boolean(mask.include?.length || mask.exclude?.length), {
+    message: 'boneMask needs at least one include or exclude bone name',
+})
+    .describe('Filters animation tracks by named Object3D/Bone subtrees');
+const AnimationLayerFields = {
+    layer: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Composition layer name; omitted means the single base layer'),
+    weight: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Layer weight multiplier from 0 to 1; defaults to 1'),
+    blendMode: z
+        .enum(['override', 'additive'])
+        .optional()
+        .describe('Native Three normal/override or additive action blending; defaults to override'),
+    boneMask: AnimationBoneMaskSchema.optional().describe('Optional include/exclude filter applied to every clip track in this state'),
+};
+// ---------------------------------------------------------------------------
+// Per-state animation metadata: single clip OR blend tree, plus crossfade
+// ---------------------------------------------------------------------------
+const ClipAnimationMetaSchema = z
+    .object({
+    clip: z.string().min(1).describe('Single clip to play while this XState state is active'),
+    loop: z
+        .boolean()
+        .default(true)
+        .describe('Loop the clip (THREE.LoopRepeat) vs play once (THREE.LoopOnce, clamped on last frame)'),
+    speed: z
+        .number()
+        .positive()
+        .default(1)
+        .describe('Playback speed multiplier (AnimationAction.timeScale)'),
+    crossfade: AnimationCrossfadeMetaSchema.optional(),
+    ...AnimationLayerFields,
+})
+    .strict();
+const BlendTreeAnimationMetaSchema = z
+    .object({
+    blendTree: AnimationBlendTreeSchema.describe('Multiple clips blended by a live context/selector-driven parameter'),
+    crossfade: AnimationCrossfadeMetaSchema.optional(),
+    ...AnimationLayerFields,
+})
+    .strict();
+/**
+ * The full shape of `state.meta.animation` for one XState state (spec §5.6):
+ * exactly one of a single clip or a blend tree, plus optional crossfade
+ * timing. `.strict()` on both branches is what makes authoring a transition
+ * keyword (`on`, `target`, `guard`, …) inside `meta.animation` a validation
+ * error instead of a silently-accepted second transition dialect.
+ */
+export const StateAnimationMetaSchema = z.union([
+    ClipAnimationMetaSchema,
+    BlendTreeAnimationMetaSchema,
+]);
+/** True iff a validated meta declares a single clip rather than a blend tree. */
+export function isClipAnimationMeta(meta) {
+    return 'clip' in meta;
+}
+/** True iff a validated meta declares a blend tree rather than a single clip. */
+export function isBlendTreeAnimationMeta(meta) {
+    return 'blendTree' in meta;
+}
+// ---------------------------------------------------------------------------
+// Validation entry point
+// ---------------------------------------------------------------------------
+/** Thrown by `parseStateAnimationMeta` — always names the offending state id. */
+export class AnimationMetaValidationError extends Error {
+    stateId;
+    issues;
+    constructor(message, stateId, issues) {
+        super(message);
+        this.stateId = stateId;
+        this.issues = issues;
+        this.name = 'AnimationMetaValidationError';
+    }
+}
+/**
+ * Validate one state's `meta.animation` value. Called by the E2 binding for
+ * every state a machine declares (both at bind time, up front, and — for
+ * belt-and-suspenders — again whenever a state is entered).
+ *
+ * @throws {AnimationMetaValidationError} naming the state id and every Zod
+ *   issue (path + message) — e.g. an unrecognized `on`/`target` key, a
+ *   missing `clip`, or a 1D blend tree with only one child.
+ */
+export function parseStateAnimationMeta(stateId, raw) {
+    const result = StateAnimationMetaSchema.safeParse(raw);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((issue) => `${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+            .join('; ');
+        throw new AnimationMetaValidationError(`[xstate-animation] invalid meta.animation for state "${stateId}": ${detail}`, stateId, result.error.issues);
+    }
+    return result.data;
+}
+/**
+ * Walk every state node in a machine (from its root `StateNode`, e.g.
+ * `actor.logic.root`) and validate every `meta.animation` value found.
+ * States with no `meta.animation` are skipped (not every XState state needs
+ * to drive animation). Returns one entry per animated state, in document
+ * order.
+ *
+ * @throws {AnimationMetaValidationError} on the FIRST invalid meta found —
+ *   naming the specific state id, so an agent authoring a machine gets an
+ *   actionable pointer straight to the bad state instead of a generic error.
+ */
+export function collectMachineAnimationMeta(root) {
+    const out = [];
+    const visit = (node) => {
+        if (node.meta && 'animation' in node.meta && node.meta.animation !== undefined) {
+            out.push({ stateId: node.id, meta: parseStateAnimationMeta(node.id, node.meta.animation) });
+        }
+        for (const child of Object.values(node.states ?? {}))
+            visit(child);
+    };
+    visit(root);
+    return out;
+}
+/** Every clip name referenced anywhere in a validated meta (1 for clip states, N for blend trees). */
+export function clipNamesOf(meta) {
+    return isClipAnimationMeta(meta) ? [meta.clip] : meta.blendTree.children.map((c) => c.clip);
+}

package/dist/asset-formats/camera.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export declare const CameraDescriptorSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        perspective: "perspective";
+        orthographic: "orthographic";
+    }>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    near: z.ZodOptional<z.ZodNumber>;
+    far: z.ZodOptional<z.ZodNumber>;
+    orthoSize: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CameraDescriptor = z.infer<typeof CameraDescriptorSchema>;
+//# sourceMappingURL=camera.d.ts.map

package/dist/asset-formats/camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../src/asset-formats/camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;;;;;;;iBAaA,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/asset-formats/camera.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export const CameraDescriptorSchema = z
+    .object({
+    type: z.enum(['perspective', 'orthographic']).describe('Camera projection type'),
+    fov: z.number().optional().describe('Vertical field of view in degrees (perspective only)'),
+    near: z.number().optional().describe('Near clipping plane distance'),
+    far: z.number().optional().describe('Far clipping plane distance'),
+    orthoSize: z
+        .number()
+        .optional()
+        .describe('Half-height of the orthographic frustum (orthographic only)'),
+    width: z.number().optional().describe('Render width in pixels. Defaults to viewport width'),
+    height: z.number().optional().describe('Render height in pixels. Defaults to viewport height'),
+})
+    .describe('Camera configuration');

package/dist/asset-formats/collider.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export declare const ColliderDescriptorSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        cuboid: "cuboid";
+        ball: "ball";
+        capsule: "capsule";
+        trimesh: "trimesh";
+    }>;
+    halfExtents: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    radius: z.ZodOptional<z.ZodNumber>;
+    halfHeight: z.ZodOptional<z.ZodNumber>;
+    friction: z.ZodOptional<z.ZodNumber>;
+    restitution: z.ZodOptional<z.ZodNumber>;
+    density: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    isSensor: z.ZodOptional<z.ZodBoolean>;
+    collisionGroups: z.ZodOptional<z.ZodNumber>;
+    collisionFilter: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ColliderDescriptor = z.infer<typeof ColliderDescriptorSchema>;
+//# sourceMappingURL=collider.d.ts.map

package/dist/asset-formats/collider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collider.d.ts","sourceRoot":"","sources":["../../src/asset-formats/collider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;iBA4De,CAAC;AAErD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/asset-formats/collider.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { Vec3Schema } from './tuples';
+export const ColliderDescriptorSchema = z
+    .object({
+    type: z
+        .enum(['cuboid', 'ball', 'capsule', 'trimesh'])
+        .describe("Collider shape type. T1.2: every shape scales with the entity's composed world scale " +
+        "(self × ancestors) — for trimesh this means the entity's own mesh geometry vertices " +
+        'are pre-scaled per-axis before building the Rapier trimesh, so it matches whatever ' +
+        "size ends up on screen; it does not require the collider's own dimension fields."),
+    halfExtents: Vec3Schema.optional().describe("Half-size [x, y, z] for cuboid colliders, in the ENTITY'S OWN LOCAL units. T1.2: " +
+        "scales with the entity — the actual Rapier collider is this value times the entity's " +
+        'composed world scale (self × every transformed ancestor), per axis, baked in once at ' +
+        "load time (Rapier has no live notion of an Object3D's scale)."),
+    radius: z
+        .number()
+        .optional()
+        .describe("Radius for ball and capsule colliders, in the ENTITY'S OWN LOCAL units. T1.2: scales " +
+        "with the entity's composed world scale, which MUST be uniform on the collider's round " +
+        'axes (ball: all of x/y/z; capsule: x and z) — a non-uniform scale there throws a loud ' +
+        'load error (Rapier balls/capsules cannot represent an ellipse).'),
+    halfHeight: z
+        .number()
+        .optional()
+        .describe("Half-height for capsule colliders, in the entity's own local units, along the capsule's " +
+        "axis (Y). T1.2: scales by the entity's composed world scale on that axis."),
+    friction: z.number().optional().describe('Surface friction coefficient'),
+    restitution: z
+        .number()
+        .optional()
+        .describe('Bounciness coefficient (0 = no bounce, 1 = perfect bounce)'),
+    density: z
+        .number()
+        .optional()
+        .describe('Mass density. Used to compute mass from collider volume'),
+    offset: Vec3Schema.optional().describe("Translation offset relative to body origin, in the ENTITY'S OWN LOCAL units. T1.2/R1c: " +
+        "scales with the entity's composed world scale (self × every transformed ancestor), " +
+        'per axis, the same way halfExtents/radius/halfHeight do — an unscaled offset would ' +
+        "silently drift away from the entity's visual anchor point under any non-1 scale."),
+    isSensor: z
+        .boolean()
+        .optional()
+        .describe('When true, detects overlaps without physical blocking (trigger volume)'),
+    collisionGroups: z
+        .number()
+        .optional()
+        .describe('Bitmask: collision layers this collider belongs to (max 16 bits)'),
+    collisionFilter: z
+        .number()
+        .optional()
+        .describe('Bitmask: collision layers this collider interacts with (max 16 bits)'),
+})
+    .describe('Physics collider shape and properties');

package/dist/asset-formats/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The engine's remaining authored asset formats and descriptor schemas.
+ *
+ * WO-8 deleted the `.vscn.json` scene format and everything under
+ * `engine/src/scene/`. What survived is here, and each module is here because a
+ * real runtime reader still consumes it:
+ *
+ * - `material.ts`   — the `.mat.json` shared-material format (`parseMaterialFile`)
+ *                     plus the inline material descriptor `render/material-factory.ts` reads
+ * - `instances.ts`   — the `.instances.json` transform format (`parseInstancesFile`),
+ *                     read by `render/instance-mesh.ts`
+ * - `mesh.ts`        — the geometry descriptor `render/material-factory.ts`'s `createGeometry` reads
+ * - `light.ts` / `camera.ts` — the descriptors `render/light-camera-factory.ts` reads
+ * - `collider.ts`    — the descriptor `physics/collider-dimensions.ts` and the editor's
+ *                     collider gizmos read
+ * - `particles.ts`   — the descriptor `render/particles-factory.ts` reads
+ * - `render-settings.ts` — the tone-mapping / post-processing / render-feature scopes
+ *                     `setup/setup-renderer.ts` reads
+ * - `tuples.ts`      — the shared Vec3/Quat/Transform tuples the above build on
+ *
+ * These are DESCRIPTORS, not documents: each names a slice of authored data a
+ * render/physics factory reads, and none of them is a scene. They carried a
+ * `Scene*` prefix until WO-9 task #6 renamed them to `*Descriptor` — the prefix
+ * was a leftover of the deleted `.vscn.json` format, not a statement about what
+ * they describe.
+ */
+export type { CameraDescriptor } from './camera';
+export { CameraDescriptorSchema } from './camera';
+export type { ColliderDescriptor } from './collider';
+export { ColliderDescriptorSchema } from './collider';
+export type { InstancesFile } from './instances';
+export { InstancesFileSchema } from './instances';
+export type { LightDescriptor } from './light';
+export { LightDescriptorSchema } from './light';
+export type { MaterialDescriptor, MaterialFile } from './material';
+export { MaterialDescriptorSchema, MaterialFileSchema } from './material';
+export type { MeshDescriptor } from './mesh';
+export { MeshDescriptorSchema } from './mesh';
+export { parseInstancesFile, parseMaterialFile } from './parse';
+export type { ParticlesDescriptor } from './particles';
+export { ParticlesDescriptorSchema } from './particles';
+export type { PostProcessingDescriptor, RenderEnvironment, ToneMappingDescriptor, } from './render-env';
+export { PostProcessingDescriptorSchema, RenderEnvironmentSchema, ToneMappingDescriptorSchema, } from './render-env';
+export type { Quat, Transform, Vec3 } from './tuples';
+export { QuatSchema, TransformSchema, Vec3Schema } from './tuples';
+//# sourceMappingURL=index.d.ts.map

package/dist/asset-formats/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/asset-formats/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/asset-formats/index.js

@@ -0,0 +1,36 @@
+/**
+ * The engine's remaining authored asset formats and descriptor schemas.
+ *
+ * WO-8 deleted the `.vscn.json` scene format and everything under
+ * `engine/src/scene/`. What survived is here, and each module is here because a
+ * real runtime reader still consumes it:
+ *
+ * - `material.ts`   — the `.mat.json` shared-material format (`parseMaterialFile`)
+ *                     plus the inline material descriptor `render/material-factory.ts` reads
+ * - `instances.ts`   — the `.instances.json` transform format (`parseInstancesFile`),
+ *                     read by `render/instance-mesh.ts`
+ * - `mesh.ts`        — the geometry descriptor `render/material-factory.ts`'s `createGeometry` reads
+ * - `light.ts` / `camera.ts` — the descriptors `render/light-camera-factory.ts` reads
+ * - `collider.ts`    — the descriptor `physics/collider-dimensions.ts` and the editor's
+ *                     collider gizmos read
+ * - `particles.ts`   — the descriptor `render/particles-factory.ts` reads
+ * - `render-settings.ts` — the tone-mapping / post-processing / render-feature scopes
+ *                     `setup/setup-renderer.ts` reads
+ * - `tuples.ts`      — the shared Vec3/Quat/Transform tuples the above build on
+ *
+ * These are DESCRIPTORS, not documents: each names a slice of authored data a
+ * render/physics factory reads, and none of them is a scene. They carried a
+ * `Scene*` prefix until WO-9 task #6 renamed them to `*Descriptor` — the prefix
+ * was a leftover of the deleted `.vscn.json` format, not a statement about what
+ * they describe.
+ */
+export { CameraDescriptorSchema } from './camera';
+export { ColliderDescriptorSchema } from './collider';
+export { InstancesFileSchema } from './instances';
+export { LightDescriptorSchema } from './light';
+export { MaterialDescriptorSchema, MaterialFileSchema } from './material';
+export { MeshDescriptorSchema } from './mesh';
+export { parseInstancesFile, parseMaterialFile } from './parse';
+export { ParticlesDescriptorSchema } from './particles';
+export { PostProcessingDescriptorSchema, RenderEnvironmentSchema, ToneMappingDescriptorSchema, } from './render-env';
+export { QuatSchema, TransformSchema, Vec3Schema } from './tuples';

package/dist/asset-formats/instances.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+/**
+ * `.instances.json` — a declarative, authored-data instance-transform asset
+ * (F3). Referenced by `mesh.instances` as a bare array of 10-number tuples,
+ * one per instance, each `[posX,posY,posZ, quatX,quatY,quatZ,quatW,
+ * scaleX,scaleY,scaleZ]`. The scene loader fetches+parses this file and
+ * renders it as one `THREE.InstancedMesh` (one draw call) — bulk transform
+ * data is referenced as an asset, never inlined into the referencing
+ * document (gate G4).
+ *
+ * WO-8: the document that referenced it was `.vscn.json`, and that format is
+ * deleted. `.instances.json` survives as a FETCHED-ASSET format with its own
+ * `parseInstancesFile` — nothing in the shipped tree references one today.
+ */
+export declare const InstancesFileSchema: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+export type InstancesFile = z.infer<typeof InstancesFileSchema>;
+//# sourceMappingURL=instances.d.ts.map

package/dist/asset-formats/instances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../src/asset-formats/instances.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,kKAoB7B,CAAC;AAEJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/asset-formats/instances.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/**
+ * `.instances.json` — a declarative, authored-data instance-transform asset
+ * (F3). Referenced by `mesh.instances` as a bare array of 10-number tuples,
+ * one per instance, each `[posX,posY,posZ, quatX,quatY,quatZ,quatW,
+ * scaleX,scaleY,scaleZ]`. The scene loader fetches+parses this file and
+ * renders it as one `THREE.InstancedMesh` (one draw call) — bulk transform
+ * data is referenced as an asset, never inlined into the referencing
+ * document (gate G4).
+ *
+ * WO-8: the document that referenced it was `.vscn.json`, and that format is
+ * deleted. `.instances.json` survives as a FETCHED-ASSET format with its own
+ * `parseInstancesFile` — nothing in the shipped tree references one today.
+ */
+export const InstancesFileSchema = z
+    .array(z.tuple([
+    z.number().describe('posX'),
+    z.number().describe('posY'),
+    z.number().describe('posZ'),
+    z.number().describe('quatX'),
+    z.number().describe('quatY'),
+    z.number().describe('quatZ'),
+    z.number().describe('quatW'),
+    z.number().describe('scaleX'),
+    z.number().describe('scaleY'),
+    z.number().describe('scaleZ'),
+]))
+    .describe('Instance-transform asset (.instances.json): an array of 10-number tuples ' +
+    '[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ], one per instance. ' +
+    'Referenced by a mesh via `mesh.instances` and rendered as a single THREE.InstancedMesh ' +
+    '(one draw call).');

package/dist/asset-formats/light.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export declare const LightDescriptorSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        area: "area";
+        directional: "directional";
+        point: "point";
+        spot: "spot";
+        hemisphere: "hemisphere";
+    }>;
+    color: z.ZodOptional<z.ZodString>;
+    intensity: z.ZodOptional<z.ZodNumber>;
+    groundColor: z.ZodOptional<z.ZodString>;
+    distance: z.ZodOptional<z.ZodNumber>;
+    decay: z.ZodOptional<z.ZodNumber>;
+    angle: z.ZodOptional<z.ZodNumber>;
+    penumbra: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type LightDescriptor = z.infer<typeof LightDescriptorSchema>;
+//# sourceMappingURL=light.d.ts.map

package/dist/asset-formats/light.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light.d.ts","sourceRoot":"","sources":["../../src/asset-formats/light.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4CxB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;iBAGM,CAAC;AAEzC,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/asset-formats/light.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+const LightDescriptorBase = z.object({
+    type: z.enum(['directional', 'point', 'spot', 'hemisphere', 'area']).describe('Light type'),
+    color: z.string().optional().describe('Light color as CSS hex string'),
+    intensity: z
+        .number()
+        .optional()
+        .describe('Native Three.js light intensity. Point and spot lights use candela with inverse-square ' +
+        'falloff (a value near 1 is candle-scale); area lights use nit; directional and ' +
+        'hemisphere lights use Three.js scene-light intensity units.'),
+    groundColor: z.string().optional().describe('Ground color for hemisphere lights'),
+    distance: z
+        .number()
+        .optional()
+        .describe('Maximum range of the light. 0 = infinite (point/spot only)'),
+    decay: z
+        .number()
+        .nonnegative()
+        .optional()
+        .describe('Native Three.js distance-decay exponent for point/spot lights. Default 2 gives ' +
+        'physically correct inverse-square falloff.'),
+    angle: z.number().optional().describe('Spotlight cone angle in radians (spot only)'),
+    penumbra: z.number().optional().describe('Spotlight penumbra softness 0–1 (spot only)'),
+    width: z
+        .number()
+        .optional()
+        .describe('Area light width (area only). RectAreaLight has NO shadow support and only affects ' +
+        'Standard/Physical materials — degrades loudly, not silently.'),
+    height: z
+        .number()
+        .optional()
+        .describe('Area light height (area only). RectAreaLight has NO shadow support and only affects ' +
+        'Standard/Physical materials — degrades loudly, not silently.'),
+});
+export const LightDescriptorSchema = LightDescriptorBase.refine((l) => l.type !== 'spot' || l.angle === undefined || l.angle > 0, { message: 'Spot light angle must be positive' }).describe('Light source configuration');