@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/ecs/game-component.d.ts

@@ -0,0 +1,146 @@
+import type RAPIER2D from '@dimforge/rapier2d-compat';
+import type RAPIER3D from '@dimforge/rapier3d-compat';
+import type * as PIXI from 'pixi.js';
+import type * as THREE from 'three';
+import type { z } from 'zod';
+import type { SystemPhaseName } from '../core/types';
+import type { AdapterSurface, WorldInstance } from '../runtime/game';
+import type { GameContext } from '../runtime/types';
+/**
+ * Map a {@link AdapterSurface} to its native world node type (T7.2, D8 —
+ * `docs/GAME-COMPONENT-GENERALIZATION.md` §2). `react` maps to `never`: react
+ * entities host no GameComponents (they render from game state via the T7.4
+ * state bridge instead).
+ */
+export type NodeOf<K extends AdapterSurface> = K extends 'threejs' ? THREE.Object3D : K extends 'pixijs' ? PIXI.Container : never;
+/** Map a {@link AdapterSurface} to its native Rapier rigid-body type. */
+export type BodyOf<K extends AdapterSurface> = K extends 'threejs' ? RAPIER3D.RigidBody : K extends 'pixijs' ? RAPIER2D.RigidBody : never;
+/** Map a {@link AdapterSurface} to its native Rapier collider type. */
+export type ColliderOf<K extends AdapterSurface> = K extends 'threejs' ? RAPIER3D.Collider : K extends 'pixijs' ? RAPIER2D.Collider : never;
+/**
+ * Base class for game components attached to entities.
+ *
+ * Generalized (T7.2, D8 — `docs/GAME-COMPONENT-GENERALIZATION.md`) over the
+ * world kind `K` (default `'threejs'`, so every existing component — all of
+ * which extend the bare `GameComponent` — compiles and runs unchanged). The
+ * world's native node IS the entity — there is no separate entity id and no
+ * mirror/sync layer (Track A). Each component instance holds a direct
+ * reference to its node and (if any) its Rapier rigid body/collider. The
+ * ComponentManager wires these up in `attach()`.
+ *
+ * Similar to Unity's MonoBehaviour or Godot's Node scripts:
+ * - `init()` — called once after the entity is fully constructed
+ * - `update(dt, ctx)` — called every fixed timestep, in the component's phase
+ * - `dispose(ctx)` — called when the entity is destroyed
+ * - `onTriggerEnter/onTriggerExit` — called when a sensor collider overlap
+ *   starts/stops, with the other party's native node
+ *
+ * State lives on `this` (instance properties). On HMR, the engine swaps the
+ * prototype via Object.setPrototypeOf — instance state survives, method bodies
+ * update to the new code.
+ *
+ * `update` is deliberately mandatory, not optional like `init`/`dispose`
+ * (owner decision, issue #101): components are for BEHAVIOR. If your
+ * subclass's `update(dt, ctx)` body is empty, that is a signal the class may
+ * not need to be a component at all — a plain state-holder with only
+ * `init`/event methods (score/hits counters, etc.) usually belongs as a
+ * plain object or a static-scenery/UI object instead (see the "GameComponents
+ * are for things with behavior only" rule).
+ */
+/**
+ * Cross-copy brand (`Symbol.for` is process-global, so every physical copy of
+ * the engine shares ONE symbol): `x.prototype instanceof GameComponent` is
+ * FALSE when a project resolves TWO copies of the engine at once — the
+ * published `@vgai/engine/*` subpaths next to the `@engine/*` source alias,
+ * exactly what a scaffolded project's node-side scripts do (meteor-dodge
+ * dry-run friction: `validate-scenes --components` reported every field of a
+ * pristine scaffold's `SceneCamera` as unknown). Structural checks
+ * (`isGameComponentClass`) test this brand as well as `instanceof`.
+ */
+export declare const GAME_COMPONENT_BRAND: unique symbol;
+/**
+ * HMR class lineage. A true component hot-swap deliberately replaces a live
+ * instance's prototype with the newly imported class, but other already-live
+ * project modules can still hold the previous class object. Native
+ * `instanceof PreviousClass` would then become false even though the object is
+ * still the same component under the same hot-reload lineage. That broke both
+ * ordinary trigger guards (`component instanceof PlayerController`) and the
+ * canonical React-state selector (`game.queryByComponent(PlayerController)`).
+ *
+ * Keep this as class-to-class lineage rather than a string/name registry:
+ * minified classes, aliases, and two unrelated components with the same name
+ * remain distinct. The WeakMap owns no game/entity state and introduces no
+ * second identity model; it records only the exact constructor pairs the
+ * existing HMR boundary has actually swapped.
+ */
+type HmrComponentConstructor = abstract new (...args: never[]) => object;
+/** @internal Called only by ComponentManager's successful HMR swap path. */
+export declare function linkGameComponentHmrClasses(previous: HmrComponentConstructor, next: HmrComponentConstructor): void;
+export declare abstract class GameComponent<K extends AdapterSurface = 'threejs'> {
+    /** Which phase this component's update runs in. Override in subclasses. */
+    static phase: SystemPhaseName;
+    /** See {@link GAME_COMPONENT_BRAND} — inherited by every subclass. */
+    static readonly [GAME_COMPONENT_BRAND] = true;
+    /**
+     * Preserve ordinary JavaScript `instanceof` across a true HMR prototype
+     * swap. Subclasses inherit this static hook, so `value instanceof
+     * PlayerController` first performs the native prototype-chain check and,
+     * only when that fails, accepts an exact constructor lineage previously
+     * linked by ComponentManager.hotSwap(). Non-HMR values retain byte-for-byte
+     * native semantics.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+    /**
+     * Runtime-checkable declaration of which {@link AdapterSurface} this component
+     * is written for (T7.2, D8 §3 — `docs/GAME-COMPONENT-GENERALIZATION.md`).
+     * TS's `K` type parameter is erased at runtime, so this static is what the
+     * ComponentManager checks at attach time: a node whose world's kind
+     * doesn't match `declaredKind` THROWS at attach (a `GameComponent<'pixijs'>`
+     * attached to a threejs entity, or vice versa). Kind-agnostic components —
+     * written only against `node`/`this.world`, never the typed `object3D`
+     * accessor or a kind-specific field — may declare `'any'` and attach in
+     * any world components are legal in (every world except `'react'`, which
+     * always throws regardless of `declaredKind` — see the ComponentManager).
+     */
+    static declaredKind: AdapterSurface | 'any';
+    /**
+     * Optional Zod object schema for this component's authored fields. When set,
+     * scene data is validated + defaulted through `schema.parse(data)` before being
+     * assigned onto the instance. Also powers (later) the editor's schema-driven
+     * inspector and HMR defaults.
+     */
+    static schema?: z.ZodObject<z.ZodRawShape>;
+    /** The native world node. The node IS the entity. */
+    node: NodeOf<K>;
+    /** The world instance this component's entity lives in (wired at attach). */
+    world: WorldInstance;
+    /**
+     * Typed accessor, threejs roots only — kept for compatibility. On a
+     * `GameComponent` (default `K`) this types as `THREE.Object3D`, so every
+     * existing component compiles unchanged. On a non-threejs instance it
+     * THROWS a descriptive error rather than ever returning a wrong-kind node —
+     * use `this.node` (or `this.world.kind` to check first) instead.
+     */
+    get object3D(): THREE.Object3D;
+    /** The entity's native rigid body, if it has physics. */
+    rigidBody: BodyOf<K> | null;
+    /** The entity's native collider, if it has physics. */
+    collider: ColliderOf<K> | null;
+    /** Called once after the entity is fully constructed (node, physics, etc.). */
+    init?(ctx: GameContext): void | Promise<void>;
+    /** Called every fixed timestep. */
+    abstract update(dt: number, ctx: GameContext): void;
+    /** Called when the entity is destroyed or the component is removed. */
+    dispose?(ctx: GameContext): void;
+    /** Called when a sensor overlap with `other` begins. */
+    onTriggerEnter?(other: NodeOf<K>, ctx: GameContext): void;
+    /** Called when a sensor overlap with `other` ends. */
+    onTriggerExit?(other: NodeOf<K>, ctx: GameContext): void;
+}
+/** Constructor type for GameComponent subclasses (carries static phase/schema). */
+export type GameComponentClass = (new () => GameComponent) & {
+    phase?: SystemPhaseName;
+    schema?: z.ZodObject<z.ZodRawShape>;
+};
+export {};
+//# sourceMappingURL=game-component.d.ts.map

package/dist/ecs/game-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-component.d.ts","sourceRoot":"","sources":["../../src/ecs/game-component.ts"],"names":[],"mappings":"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"}

package/dist/ecs/game-component.js

@@ -0,0 +1,141 @@
+/**
+ * Base class for game components attached to entities.
+ *
+ * Generalized (T7.2, D8 — `docs/GAME-COMPONENT-GENERALIZATION.md`) over the
+ * world kind `K` (default `'threejs'`, so every existing component — all of
+ * which extend the bare `GameComponent` — compiles and runs unchanged). The
+ * world's native node IS the entity — there is no separate entity id and no
+ * mirror/sync layer (Track A). Each component instance holds a direct
+ * reference to its node and (if any) its Rapier rigid body/collider. The
+ * ComponentManager wires these up in `attach()`.
+ *
+ * Similar to Unity's MonoBehaviour or Godot's Node scripts:
+ * - `init()` — called once after the entity is fully constructed
+ * - `update(dt, ctx)` — called every fixed timestep, in the component's phase
+ * - `dispose(ctx)` — called when the entity is destroyed
+ * - `onTriggerEnter/onTriggerExit` — called when a sensor collider overlap
+ *   starts/stops, with the other party's native node
+ *
+ * State lives on `this` (instance properties). On HMR, the engine swaps the
+ * prototype via Object.setPrototypeOf — instance state survives, method bodies
+ * update to the new code.
+ *
+ * `update` is deliberately mandatory, not optional like `init`/`dispose`
+ * (owner decision, issue #101): components are for BEHAVIOR. If your
+ * subclass's `update(dt, ctx)` body is empty, that is a signal the class may
+ * not need to be a component at all — a plain state-holder with only
+ * `init`/event methods (score/hits counters, etc.) usually belongs as a
+ * plain object or a static-scenery/UI object instead (see the "GameComponents
+ * are for things with behavior only" rule).
+ */
+/**
+ * Cross-copy brand (`Symbol.for` is process-global, so every physical copy of
+ * the engine shares ONE symbol): `x.prototype instanceof GameComponent` is
+ * FALSE when a project resolves TWO copies of the engine at once — the
+ * published `@vgai/engine/*` subpaths next to the `@engine/*` source alias,
+ * exactly what a scaffolded project's node-side scripts do (meteor-dodge
+ * dry-run friction: `validate-scenes --components` reported every field of a
+ * pristine scaffold's `SceneCamera` as unknown). Structural checks
+ * (`isGameComponentClass`) test this brand as well as `instanceof`.
+ */
+export const GAME_COMPONENT_BRAND = Symbol.for('vgai.GameComponent');
+const hmrLineages = new WeakMap();
+/** @internal Called only by ComponentManager's successful HMR swap path. */
+export function linkGameComponentHmrClasses(previous, next) {
+    const previousLineage = hmrLineages.get(previous);
+    const nextLineage = hmrLineages.get(next);
+    const merged = new Set([previous, next]);
+    if (previousLineage) {
+        for (const member of previousLineage)
+            merged.add(member);
+    }
+    if (nextLineage) {
+        for (const member of nextLineage)
+            merged.add(member);
+    }
+    for (const member of merged)
+        hmrLineages.set(member, merged);
+}
+function classesShareHmrLineage(a, b) {
+    return a === b || hmrLineages.get(a)?.has(b) === true;
+}
+export class GameComponent {
+    /** Which phase this component's update runs in. Override in subclasses. */
+    static phase = 'gameLogic';
+    /** See {@link GAME_COMPONENT_BRAND} — inherited by every subclass. */
+    static [GAME_COMPONENT_BRAND] = true;
+    /**
+     * Preserve ordinary JavaScript `instanceof` across a true HMR prototype
+     * swap. Subclasses inherit this static hook, so `value instanceof
+     * PlayerController` first performs the native prototype-chain check and,
+     * only when that fails, accepts an exact constructor lineage previously
+     * linked by ComponentManager.hotSwap(). Non-HMR values retain byte-for-byte
+     * native semantics.
+     */
+    static [Symbol.hasInstance](value) {
+        // biome-ignore lint/complexity/noThisInStatic: Symbol.hasInstance is inherited; `this` must be the queried subclass, not the GameComponent base.
+        const expected = this;
+        const nativeMatch = Function.prototype[Symbol.hasInstance].call(expected, value);
+        if (nativeMatch)
+            return true;
+        if (value === null || (typeof value !== 'object' && typeof value !== 'function'))
+            return false;
+        const actual = value.constructor;
+        return (typeof actual === 'function' &&
+            classesShareHmrLineage(expected, actual));
+    }
+    /**
+     * Runtime-checkable declaration of which {@link AdapterSurface} this component
+     * is written for (T7.2, D8 §3 — `docs/GAME-COMPONENT-GENERALIZATION.md`).
+     * TS's `K` type parameter is erased at runtime, so this static is what the
+     * ComponentManager checks at attach time: a node whose world's kind
+     * doesn't match `declaredKind` THROWS at attach (a `GameComponent<'pixijs'>`
+     * attached to a threejs entity, or vice versa). Kind-agnostic components —
+     * written only against `node`/`this.world`, never the typed `object3D`
+     * accessor or a kind-specific field — may declare `'any'` and attach in
+     * any world components are legal in (every world except `'react'`, which
+     * always throws regardless of `declaredKind` — see the ComponentManager).
+     */
+    static declaredKind = 'threejs';
+    /**
+     * Optional Zod object schema for this component's authored fields. When set,
+     * scene data is validated + defaulted through `schema.parse(data)` before being
+     * assigned onto the instance. Also powers (later) the editor's schema-driven
+     * inspector and HMR defaults.
+     */
+    static schema;
+    /** The native world node. The node IS the entity. */
+    node;
+    /** The world instance this component's entity lives in (wired at attach). */
+    world;
+    /**
+     * Typed accessor, threejs roots only — kept for compatibility. On a
+     * `GameComponent` (default `K`) this types as `THREE.Object3D`, so every
+     * existing component compiles unchanged. On a non-threejs instance it
+     * THROWS a descriptive error rather than ever returning a wrong-kind node —
+     * use `this.node` (or `this.world.kind` to check first) instead.
+     */
+    get object3D() {
+        const kind = this.world?.kind;
+        if (kind !== undefined && kind !== 'threejs') {
+            throw new Error(`${this.constructor.name}.object3D: this component's world (kind: "${kind}") is not a ` +
+                'threejs world — `object3D` only ever returns a THREE.Object3D; use `this.node` instead.');
+        }
+        // When the world isn't wired yet (silo-attached 2D components until
+        // T7.3; bare instances), fall back to the static declaration so a
+        // GameComponent<'pixijs'> can never silently hand out its Container
+        // typed as an Object3D.
+        if (kind === undefined) {
+            const declared = this.constructor.declaredKind;
+            if (declared !== 'threejs' && declared !== 'any') {
+                throw new Error(`${this.constructor.name}.object3D: this component declares kind "${declared}" — ` +
+                    '`object3D` only ever returns a THREE.Object3D; use `this.node` instead.');
+            }
+        }
+        return this.node;
+    }
+    /** The entity's native rigid body, if it has physics. */
+    rigidBody = null;
+    /** The entity's native collider, if it has physics. */
+    collider = null;
+}

package/dist/ecs/hmr-swap-report.d.ts

@@ -0,0 +1,53 @@
+/**
+ * HMR swap-miss report — T5.4 (docs/BACKBONE-TASKS.md's Track 5 table:
+ * "Deterministic HMR: registry-keyed hotSwap (not `constructor.name`), schema
+ * re-parse on swap, loud swap-miss warnings"). `ComponentManager.hotSwap` keys
+ * live instances by the `componentRegistry` name recorded on them at attach
+ * (see `component-manager.ts`'s `attach`/`hotSwap`), NOT the live
+ * `constructor.name` — fragile under minification, class renames, or two
+ * classes sharing one name. This module is the structured, greppable
+ * `console.warn` a swap-miss warrants, mirrored on the established
+ * prefix + JSON-payload pattern (`packages/editor/src/achieved-tier.ts`'s
+ * `TIER_SHORTFALL_PREFIX`, `packages/editor/src/authoring/overlay-report.ts`'s
+ * `OVERLAY_REPORT_PREFIX`) — kept dependency-free (no `window`/editor-console
+ * import) so it stays importable from a headless engine/runtime context,
+ * same discipline as those two files.
+ *
+ * Two independent miss reasons, per the BACKBONE-TASKS detail note:
+ *   - `'no-live-instance'` — the incoming hot update's key (the
+ *     `componentRegistry` name the recompiled module was re-exported under)
+ *     matches no currently-attached instance's recorded registry key (nor,
+ *     for an instance attached WITHOUT a registry key — an ad-hoc,
+ *     code-attached component — its `constructor.name`). This is the
+ *     "renamed class → loud miss" case: a class rename changes the export
+ *     key a hot update arrives under, so no live instance is found under the
+ *     NEW key — the OLD prototype is simply left in place (never silently
+ *     dropped, never crashed).
+ *   - `'schema-reparse-failed'` — at least one matched instance's swap
+ *     succeeded (prototype replaced), but re-validating its authored props
+ *     against the NEW class's `static schema` threw; that instance's fields
+ *     are left exactly as they were (last-good props), never partially or
+ *     invalidly overwritten.
+ */
+/** Greppable prefix shared by every swap-miss log line this module produces. */
+export declare const HMR_SWAP_MISS_PREFIX = "hmr-swap-miss";
+export type HmrSwapMissReport = {
+    key: string;
+    reason: 'no-live-instance';
+} | {
+    key: string;
+    reason: 'schema-reparse-failed';
+    error: string;
+};
+/**
+ * The one shared message shape — greppable on the prefix, JSON-parseable on
+ * the trailing payload (the LAST `{...}` in the string — the human-readable
+ * `detail` clause never itself contains a brace, even for the
+ * `'schema-reparse-failed'` reason, whose full Zod error text — itself a
+ * JSON-issues blob, braces included — is carried only in `report.error`
+ * inside that trailing payload, never inlined into `detail`).
+ */
+export declare function formatHmrSwapMissMessage(report: HmrSwapMissReport): string;
+/** Emit the ONE structured `console.warn` a swap-miss warrants — never a silent no-op. */
+export declare function logHmrSwapMiss(report: HmrSwapMissReport): void;
+//# sourceMappingURL=hmr-swap-report.d.ts.map

package/dist/ecs/hmr-swap-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr-swap-report.d.ts","sourceRoot":"","sources":["../../src/ecs/hmr-swap-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,MAAM,MAAM,iBAAiB,GACzB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC3C;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAW1E;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAG9D"}

package/dist/ecs/hmr-swap-report.js

@@ -0,0 +1,55 @@
+/**
+ * HMR swap-miss report — T5.4 (docs/BACKBONE-TASKS.md's Track 5 table:
+ * "Deterministic HMR: registry-keyed hotSwap (not `constructor.name`), schema
+ * re-parse on swap, loud swap-miss warnings"). `ComponentManager.hotSwap` keys
+ * live instances by the `componentRegistry` name recorded on them at attach
+ * (see `component-manager.ts`'s `attach`/`hotSwap`), NOT the live
+ * `constructor.name` — fragile under minification, class renames, or two
+ * classes sharing one name. This module is the structured, greppable
+ * `console.warn` a swap-miss warrants, mirrored on the established
+ * prefix + JSON-payload pattern (`packages/editor/src/achieved-tier.ts`'s
+ * `TIER_SHORTFALL_PREFIX`, `packages/editor/src/authoring/overlay-report.ts`'s
+ * `OVERLAY_REPORT_PREFIX`) — kept dependency-free (no `window`/editor-console
+ * import) so it stays importable from a headless engine/runtime context,
+ * same discipline as those two files.
+ *
+ * Two independent miss reasons, per the BACKBONE-TASKS detail note:
+ *   - `'no-live-instance'` — the incoming hot update's key (the
+ *     `componentRegistry` name the recompiled module was re-exported under)
+ *     matches no currently-attached instance's recorded registry key (nor,
+ *     for an instance attached WITHOUT a registry key — an ad-hoc,
+ *     code-attached component — its `constructor.name`). This is the
+ *     "renamed class → loud miss" case: a class rename changes the export
+ *     key a hot update arrives under, so no live instance is found under the
+ *     NEW key — the OLD prototype is simply left in place (never silently
+ *     dropped, never crashed).
+ *   - `'schema-reparse-failed'` — at least one matched instance's swap
+ *     succeeded (prototype replaced), but re-validating its authored props
+ *     against the NEW class's `static schema` threw; that instance's fields
+ *     are left exactly as they were (last-good props), never partially or
+ *     invalidly overwritten.
+ */
+/** Greppable prefix shared by every swap-miss log line this module produces. */
+export const HMR_SWAP_MISS_PREFIX = 'hmr-swap-miss';
+/**
+ * The one shared message shape — greppable on the prefix, JSON-parseable on
+ * the trailing payload (the LAST `{...}` in the string — the human-readable
+ * `detail` clause never itself contains a brace, even for the
+ * `'schema-reparse-failed'` reason, whose full Zod error text — itself a
+ * JSON-issues blob, braces included — is carried only in `report.error`
+ * inside that trailing payload, never inlined into `detail`).
+ */
+export function formatHmrSwapMissMessage(report) {
+    const detail = report.reason === 'no-live-instance'
+        ? `no live instance's registry key (or, for an ad-hoc/unregistered instance, its class name) ` +
+            `matches "${report.key}" — the hot update had nothing to swap (old class, if any, left in place)`
+        : `schema re-parse failed for "${report.key}" after swap — keeping the instance's last-good ` +
+            `props (Zod error in the trailing payload's "error" field)`;
+    return (`${HMR_SWAP_MISS_PREFIX} ${detail} (T5.4, docs/BACKBONE-TASKS.md). ` +
+        `${HMR_SWAP_MISS_PREFIX} ${JSON.stringify(report)}`);
+}
+/** Emit the ONE structured `console.warn` a swap-miss warrants — never a silent no-op. */
+export function logHmrSwapMiss(report) {
+    // biome-ignore lint/suspicious/noConsole: structured, greppable swap-miss warning (T5.4) — mirrors achieved-tier.ts/overlay-report.ts's deliberate direct console.warn
+    console.warn(formatHmrSwapMissMessage(report));
+}

package/dist/humanoid/bake.operation.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Package-contributed Project Command for baking the procedural humanoid into
+ * ordinary project assets. The editor discovers this module through
+ * @vgai/engine's package.json; the editor itself contains no humanoid branch.
+ */
+import { z } from 'zod';
+declare const InputSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    params: z.ZodDefault<z.ZodObject<{
+        height: z.ZodOptional<z.ZodNumber>;
+        legLength: z.ZodDefault<z.ZodNumber>;
+        armLength: z.ZodDefault<z.ZodNumber>;
+        torsoLength: z.ZodDefault<z.ZodNumber>;
+        shoulderWidth: z.ZodDefault<z.ZodNumber>;
+        hipWidth: z.ZodDefault<z.ZodNumber>;
+        headSize: z.ZodDefault<z.ZodNumber>;
+        limbThickness: z.ZodDefault<z.ZodNumber>;
+        torsoGirth: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    clipSource: z.ZodOptional<z.ZodString>;
+    clipNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const OutputFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    bytes: z.ZodNumber;
+    mediaType: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        prefab: "prefab";
+        asset: "asset";
+        provenance: "provenance";
+        other: "other";
+    }>>;
+}, z.core.$strip>;
+interface OutputWriter {
+    write(files: ReadonlyArray<{
+        path: string;
+        content: string | Uint8Array;
+        mediaType?: string;
+        role?: 'asset' | 'prefab' | 'provenance' | 'other';
+    }>, options?: {
+        dryRun?: boolean;
+    }): Promise<{
+        files: z.infer<typeof OutputFileSchema>[];
+        totalBytes: number;
+        dryRun: boolean;
+    }>;
+}
+interface ProjectOperationContext {
+    projectRoot?: string;
+    projectOutputs?: OutputWriter;
+    signal?: AbortSignal;
+}
+export declare const operation: {
+    name: string;
+    summary: string;
+    description: string;
+    input: z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        params: z.ZodDefault<z.ZodObject<{
+            height: z.ZodOptional<z.ZodNumber>;
+            legLength: z.ZodDefault<z.ZodNumber>;
+            armLength: z.ZodDefault<z.ZodNumber>;
+            torsoLength: z.ZodDefault<z.ZodNumber>;
+            shoulderWidth: z.ZodDefault<z.ZodNumber>;
+            hipWidth: z.ZodDefault<z.ZodNumber>;
+            headSize: z.ZodDefault<z.ZodNumber>;
+            limbThickness: z.ZodDefault<z.ZodNumber>;
+            torsoGirth: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        clipSource: z.ZodOptional<z.ZodString>;
+        clipNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        dryRun: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    result: z.ZodObject<{
+        model: z.ZodString;
+        prefab: z.ZodString;
+        provenance: z.ZodString;
+        vertexCount: z.ZodNumber;
+        clips: z.ZodArray<z.ZodString>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            bytes: z.ZodNumber;
+            mediaType: z.ZodOptional<z.ZodString>;
+            role: z.ZodOptional<z.ZodEnum<{
+                prefab: "prefab";
+                asset: "asset";
+                provenance: "provenance";
+                other: "other";
+            }>>;
+        }, z.core.$strip>>;
+        totalBytes: z.ZodNumber;
+        dryRun: z.ZodBoolean;
+    }, z.core.$strip>;
+    errors: never[];
+    requires: {
+        project: boolean;
+    };
+    host: "node";
+    mutates: boolean;
+    supportsDryRun: boolean;
+    longRunning: boolean;
+    permission: {
+        risk: "write";
+        summary: string;
+    };
+    impl(input: z.infer<typeof InputSchema>, ctx: ProjectOperationContext): Promise<{
+        files: z.infer<typeof OutputFileSchema>[];
+        totalBytes: number;
+        dryRun: boolean;
+        model: string;
+        prefab: string;
+        provenance: string;
+        vertexCount: number;
+        clips: string[];
+    }>;
+};
+export {};
+//# sourceMappingURL=bake.operation.d.ts.map

package/dist/humanoid/bake.operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bake.operation.d.ts","sourceRoot":"","sources":["../../src/humanoid/bake.operation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;iBA0Bf,CAAC;AAEH,QAAA,MAAM,gBAAgB;;;;;;;;;;iBAKpB,CAAC;AAaH,UAAU,YAAY;IACpB,KAAK,CACH,KAAK,EAAE,aAAa,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;QAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;KACpD,CAAC,EACF,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC7B,OAAO,CAAC;QACT,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,EAAE,CAAC;QAC1C,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,UAAU,uBAAuB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,YAAY,CAAC;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAwGD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAuBF,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,OAAO,uBAAuB;eAzIlE,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,EAAE;oBAC7B,MAAM;gBACV,OAAO;;;;;;;CA8MlB,CAAC"}