@3driseai/3drise-core 1.0.18 → 1.0.20

package/dist/autoAnimate/composer.js

@@ -0,0 +1,251 @@
+// =============================================================================
+// generateAnimation — scene profile + template + style → clips and a sequence.
+// =============================================================================
+//
+// Templates:
+//   intro    Reveal (hero enters, camera pulls in) → Ensemble (groups cascade in,
+//            the rest follow, lights) → Showcase (camera swings around the hero,
+//            the hero pulses). Ends on the authored scene. Plays once (hold).
+//   ambient  One looping step: everything breathes / floats / sways and returns to
+//            rest, the camera swings out and back — seamless at the loop seam.
+//
+// Rules enforced here (see claude/auto-animate-plan.md): continuity through a
+// ledger; group coherence (same recipe, ease, duration, ±7% amplitude, cascade in
+// spatial order with a fixed total stagger); scale-relative magnitudes; ground;
+// camera speed limit; return to rest; beat grid (0.25 s); no parent + child on the
+// same object chain; saved objects only; a later entrance is staged at its start
+// pose from the first frame (so nothing pops in before its turn).
+//
+import { toActionKey, uniqueActionKey } from '../utils/actionKeys.js';
+import { analyzeScene } from './sceneAnalyzer.js';
+import { createRng } from './rng.js';
+import { chooseEnter, environmentPaths, Ledger, planAmbient, planCameraDolly, planCameraOrbit, planEnter, planLightEnter, round, STYLES, } from './recipes.js';
+import { validateGenerated } from './validator.js';
+const LENGTH_MUL = { short: 0.8, medium: 1, long: 1.3 };
+const BEAT = 0.25;
+const snap = (t, min = BEAT) => Math.max(min, Math.round(t / BEAT) * BEAT);
+const defaultId = (prefix) => `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+const getAtPath = (obj, path) => path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+export function generateAnimation(input, options) {
+    const profile = options.profile ?? analyzeScene(input, options.analyze);
+    const makeId = options.makeId ?? defaultId;
+    const seed = options.seed ?? Math.floor(Math.random() * 2 ** 31);
+    const rng = createRng(seed);
+    const style = STYLES[options.style] ?? STYLES.calm;
+    const driver = options.driver ?? 'time';
+    const objectsById = new Map((input.objects ?? []).map((o) => [o.id, o]));
+    const authored = (state, path) => {
+        const src = state === 'camera' ? input.camera
+            : state === 'sky' ? input.sky
+                : state === 'clouds' ? input.clouds
+                    : state === 'ocean' ? input.ocean
+                        : state === 'terrain' ? input.terrain
+                            : objectsById.get(state);
+        const v = getAtPath(src, path);
+        return v === undefined ? undefined : (Array.isArray(v) ? [...v] : v);
+    };
+    const ctx = { profile, rng, style, ledger: new Ledger(authored), makeId, driven: driver !== 'time' };
+    const taken = new Set(options.takenKeys ?? []);
+    const keyFor = (name) => {
+        const k = uniqueActionKey(toActionKey(name), taken);
+        taken.add(k);
+        return k;
+    };
+    const clips = [];
+    const steps = [];
+    const lenMul = LENGTH_MUL[options.length] ?? 1;
+    const dur = (base) => snap(base * style.durationMul * lenMul);
+    // --- helpers ------------------------------------------------------------------------
+    const key = (t, value, ease) => ({ id: makeId('k'), t: round(t), value, ...(ease ? { ease } : {}) });
+    const track = (state, path, keys) => ({ id: makeId('tr'), state, path, keys });
+    const enterTracks = (moves, t0, d) => moves.map(m => track(m.state, m.path, [key(t0, m.away, m.ease), key(t0 + d, m.rest)]));
+    const addClip = (name, tracks, duration, description) => {
+        if (!tracks.length)
+            return null;
+        const clip = {
+            id: makeId('clip'), name: `Auto · ${name}`, key: keyFor(`auto ${name}`), description,
+            duration: round(duration, 3), fps: 30, loop: false, yoyo: false, endMode: 'hold', tracks,
+        };
+        clips.push(clip);
+        ctx.ledger.commit(tracks);
+        return clip;
+    };
+    const addStep = (list) => {
+        const ok = list.filter((c) => !!c);
+        if (ok.length)
+            steps.push({ id: makeId('step'), clips: ok.map(c => ({ id: makeId('sc'), clipId: c.id, delay: 0, speed: 1 })) });
+        return ok.length ? Math.max(...ok.map(c => c.duration)) : 0;
+    };
+    // --- who moves ----------------------------------------------------------------------------
+    const byId = new Map(profile.objects.map(p => [p.id, p]));
+    const ancestors = (p) => {
+        const out = [];
+        let cur = p.parentId ? byId.get(p.parentId) : undefined;
+        while (cur && out.length < 64) {
+            out.push(cur.id);
+            cur = cur.parentId ? byId.get(cur.parentId) : undefined;
+        }
+        return out;
+    };
+    const hero = profile.heroId ? byId.get(profile.heroId) ?? null : null;
+    const animated = new Set();
+    /** A new object may move unless it or one of its ancestors / descendants already does. */
+    const canAnimate = (p) => p.saved && p.visible && !animated.has(p.id) && !ancestors(p).some(a => animated.has(a)) &&
+        ![...animated].some(id => ancestors(byId.get(id)).includes(p.id));
+    if (hero && hero.saved)
+        animated.add(hero.id);
+    const groups = [];
+    for (const g of profile.groups) {
+        const members = g.memberIds.map(id => byId.get(id)).filter(m => m.role !== 'hero');
+        const free = members.filter(canAnimate);
+        if (free.length < 2)
+            continue;
+        free.forEach(m => animated.add(m.id));
+        const order = (rng.next() < 0.5 ? g.order : g.radialOrder).filter(id => free.some(m => m.id === id));
+        const first = byId.get(order[0]);
+        const label = g.kind === 'parent' ? byId.get(g.parentId)?.name ?? 'Group' : `${first.name.replace(/[\s_\-.#]*\d+\s*$/, '') || first.name}s`;
+        groups.push({ group: g, name: label, members: order.map(id => byId.get(id)) });
+    }
+    const standalone = profile.objects
+        .filter(p => (p.role === 'standalone' || p.role === 'member') && canAnimate(p))
+        .sort((a, b) => a.bounds.center[0] - b.bounds.center[0]);
+    standalone.forEach(p => animated.add(p.id));
+    const lights = profile.objects.filter(p => p.role === 'light' && p.saved && p.capabilities.config.includes('intensity'));
+    const center = hero ? hero.bounds.center : profile.bounds.center;
+    // =========================================================================================
+    if (options.template === 'ambient') {
+        const T = dur(4);
+        const phaseSpan = T * 0.5;
+        const stepClips = [];
+        const ambientTracks = (p, name, amp, phase) => {
+            const plan = planAmbient(name, p, amp, ctx);
+            if (!plan)
+                return [];
+            return [track(p.id, plan.path, plan.points.map(([f, v], i) => key(phase + f * T, v, i < plan.points.length - 1 ? style.ambientEase : undefined)))];
+        };
+        if (hero && animated.has(hero.id)) {
+            stepClips.push(addClip(hero.name, [...ambientTracks(hero, 'float', 1, 0), ...ambientTracks(hero, 'glow', 1, 0)], T, 'Hero: float and glow'));
+        }
+        for (const g of groups) {
+            const name = rng.pick(['float', 'sway', 'breathe']);
+            const n = g.members.length;
+            const tracks = g.members.flatMap((m, i) => ambientTracks(m, name, rng.jitter(0.07), snap((phaseSpan * i) / Math.max(1, n), 0)));
+            stepClips.push(addClip(g.name, tracks, T + phaseSpan, `${name}, a wave across the group`));
+        }
+        if (standalone.length) {
+            const n = standalone.length;
+            const tracks = standalone.flatMap((m, i) => ambientTracks(m, 'float', rng.jitter(0.07) * 0.7, snap((phaseSpan * i) / Math.max(1, n), 0)));
+            stepClips.push(addClip('Others', tracks, T + phaseSpan, 'Gentle float'));
+        }
+        if (lights.length) {
+            stepClips.push(addClip('Lights', lights.flatMap(l => ambientTracks(l, 'swell', rng.jitter(0.07), 0)), T, 'Light swell'));
+        }
+        const L = Math.max(T, ...stepClips.filter(Boolean).map(c => c.duration));
+        stepClips.push(addClip('Camera', planCameraOrbit(ctx, center, L, rng.next() < 0.5 ? 1 : -1), L, 'Swing out and back'));
+        const envTracks = environmentPaths(ctx).map(e => {
+            const v = Number(ctx.ledger.get(e.state, e.path));
+            const peak = round(Math.min(e.max, Math.max(e.min, v + e.delta / 2)));
+            return track(e.state, e.path, [key(0, v, 'easeInOutSine'), key(L / 2, peak, 'easeInOutSine'), key(L, v)]);
+        });
+        stepClips.push(addClip('Atmosphere', envTracks, L, 'Slow environment drift'));
+        addStep(stepClips);
+    }
+    else {
+        // ---------------------------------------------------------------- intro
+        const D = dur(1.2);
+        const envs = environmentPaths(ctx);
+        // Plan every entrance first: their start poses are staged from the first frame.
+        const heroMoves = hero && animated.has(hero.id) ? chooseEnter(hero, 1, ctx).moves : [];
+        const groupPlans = groups.map(g => {
+            // One recipe for the whole group: the first of the style that works for every member.
+            const names = [...style.enters, 'pop'];
+            const name = names.find(nm => g.members.every(m => planEnter(nm, m, 1, ctx))) ?? 'pop';
+            const amps = g.members.map(() => rng.jitter(0.07));
+            return { ...g, moves: g.members.map((m, i) => planEnter(name, m, amps[i], ctx) ?? []), recipe: name };
+        });
+        const standaloneMoves = standalone.map(p => chooseEnter(p, 0.8 * rng.jitter(0.07), ctx).moves);
+        const lightMoves = style.name === 'cinematic' ? lights.flatMap(l => planLightEnter(l, ctx)) : [];
+        // Step 1 — Reveal
+        const later = [...groupPlans.flatMap(g => g.moves.flat()), ...standaloneMoves.flat(), ...lightMoves];
+        const step1 = [];
+        step1.push(addClip('Staging', later.map(m => track(m.state, m.path, [key(0, m.away)])), BEAT, 'Start poses of what enters later'));
+        if (heroMoves.length)
+            step1.push(addClip(`${hero.name} enters`, enterTracks(heroMoves, 0, D), D, 'Hero entrance'));
+        const dolly = planCameraDolly(ctx, 1);
+        const Dc = dur(1.6);
+        if (dolly)
+            step1.push(addClip('Camera in', [track('camera', dolly.path, [key(0, dolly.away, style.name === 'cinematic' ? 'easeInOutCubic' : 'easeOutCubic'), key(Dc, dolly.rest)])], Dc, 'Pull in to the authored view'));
+        const L1 = Math.max(D, Dc);
+        // Step 2 — Ensemble
+        const step2 = [];
+        for (const g of groupPlans) {
+            const n = g.members.length;
+            const S = snap(Math.min(1.4, Math.max(0.4, 0.18 * n)) * style.durationMul, 0);
+            const tracks = g.moves.flatMap((moves, i) => enterTracks(moves, n > 1 ? round((S * i) / (n - 1)) : 0, D));
+            step2.push(addClip(`${g.name} enter`, tracks, D + S, `${g.recipe}, cascading`));
+        }
+        if (standalone.length) {
+            const n = standalone.length;
+            const S = snap(Math.min(1.2, Math.max(0.3, 0.15 * n)) * style.durationMul, 0);
+            step2.push(addClip('Others enter', standaloneMoves.flatMap((moves, i) => enterTracks(moves, n > 1 ? round((S * i) / (n - 1)) : 0, D)), D + S));
+        }
+        if (lightMoves.length)
+            step2.push(addClip('Lights on', enterTracks(lightMoves, 0, D * 1.5), D * 1.5));
+        const L2 = step2.filter(Boolean).length ? Math.max(...step2.filter(Boolean).map(c => c.duration)) : 0;
+        // Step 3 — Showcase
+        const Do = dur(4);
+        const step3 = [];
+        step3.push(addClip('Camera orbit', planCameraOrbit(ctx, center, Do, rng.next() < 0.5 ? 1 : -1), Do, 'Swing around and back'));
+        if (hero && animated.has(hero.id)) {
+            const accent = planAmbient(hero.capabilities.emissive ? 'glow' : 'breathe', hero, 1, ctx);
+            if (accent) {
+                const T = Math.min(Do, dur(1.6));
+                step3.push(addClip(`${hero.name} accent`, [track(hero.id, accent.path, accent.points.map(([f, v], i) => key(round((Do - T) / 2 + f * T), v, i < accent.points.length - 1 ? style.ambientEase : undefined)))], Do));
+            }
+        }
+        // Atmosphere: one continuous slow move across the steps (rest − δ → rest).
+        const lengths = [L1, L2, Do];
+        const total = lengths.reduce((a, b) => a + b, 0);
+        const envClip = (stepIndex) => {
+            const L = lengths[stepIndex];
+            if (!L || !envs.length)
+                return null;
+            const before = lengths.slice(0, stepIndex).reduce((a, b) => a + b, 0);
+            const tracks = envs.map(e => {
+                const rest = Number(ctx.ledger.get(e.state, e.path));
+                // rest here is where the previous slice left it; the full move ends at the authored value
+                const authoredV = Number(authored(e.state, e.path));
+                const start = Math.min(e.max, Math.max(e.min, authoredV - e.delta));
+                const at = (t) => round(start + (authoredV - start) * (t / total));
+                return track(e.state, e.path, [key(0, stepIndex === 0 ? at(0) : rest, 'linear'), key(L, at(before + L))]);
+            });
+            return addClip(`Atmosphere ${stepIndex + 1}`, tracks, L, 'Slow environment layer');
+        };
+        step1.push(envClip(0));
+        addStep(step1);
+        if (L2) {
+            step2.push(envClip(1));
+            addStep(step2);
+        }
+        step3.push(envClip(2));
+        addStep(step3);
+    }
+    const name = `Auto · ${options.template === 'ambient' ? 'Ambient loop' : 'Intro'} (${style.name})`;
+    const sequence = {
+        id: makeId('seq'),
+        name,
+        key: keyFor(name),
+        description: `Generated from the scene (seed ${seed}).`,
+        steps,
+        cues: [],
+        loop: options.template === 'ambient' && driver === 'time',
+        yoyo: false,
+        reverse: false,
+        endMode: 'hold',
+        driver,
+        driverSettings: { sensitivity: 1, smoothing: 0.25, invert: false },
+        autoplay: options.autoplay ?? false,
+    };
+    const issues = validateGenerated(clips, sequence, { driven: ctx.driven });
+    return { clips, sequence, profile, issues };
+}

package/dist/autoAnimate/describeScene.d.ts

@@ -0,0 +1,105 @@
+import type { AnalyzeOptions, SceneInput } from './types';
+export type PropKind = 'vec3' | 'number' | 'color' | 'boolean' | 'select' | 'string';
+export interface PropContext {
+    path: string;
+    kind: PropKind;
+    /** Authored value. */
+    value?: unknown;
+    min?: number;
+    max?: number;
+    options?: string[];
+}
+export interface ElementContext {
+    tracks: PropContext[];
+    patch: PropContext[];
+}
+export interface ObjectContext extends ElementContext {
+    id: string;
+    name: string;
+    type: string;
+    /** config.type (light / particles / effect / grid kind, shape name). */
+    subType?: string;
+    role: string;
+    /** Has a real (saved) id — only saved objects can be referenced by animations. */
+    saved: boolean;
+    visible: boolean;
+    groupId?: string;
+    parentId?: string;
+    childIds?: string[];
+    /** Authored local transform. */
+    position: number[];
+    rotation: number[];
+    scale: number[];
+    /** World bounds. */
+    center: number[];
+    size: number[];
+    fadeable: boolean;
+    material?: {
+        type?: string;
+        variant?: string;
+        color?: string;
+    };
+}
+export type EnvironmentKey = 'sky' | 'clouds' | 'ocean' | 'terrain';
+export interface EnvironmentContext extends ElementContext {
+    /** The element exists in the scene (configured), on or off. */
+    present: boolean;
+    on: boolean;
+    /** deckType / waterType / terrainType. */
+    kind?: string;
+    preset?: string;
+    /** Ocean: 'world' | 'object'… */
+    host?: string;
+    /** Clouds: the high ice layer. */
+    cirrus?: {
+        on: boolean;
+        preset?: string;
+    };
+}
+export interface SceneAnalysis {
+    version: 2;
+    scene: {
+        scale: number;
+        ground: number;
+        center: number[];
+        size: number[];
+        heroId: string | null;
+        countsByType: Record<string, number>;
+    };
+    camera: ElementContext & {
+        position: number[];
+        target: number[];
+        fov: number;
+        distance: number;
+        /** Visible area on the ground plane (y = 0), 0 when no camera is mounted. */
+        viewport: {
+            visibleWidth: number;
+            visibleHeight: number;
+        };
+    };
+    environment: Record<EnvironmentKey, EnvironmentContext>;
+    background: {
+        hdri: string | null;
+    };
+    groups: Array<{
+        id: string;
+        kind: string;
+        axis: string;
+        order: string[];
+        radialOrder: string[];
+    }>;
+    objects: ObjectContext[];
+}
+export interface DescribeSceneInput extends SceneInput {
+    /** HDR background settings (`name` is the preset). */
+    hdr?: any;
+}
+export interface DescribeOptions extends AnalyzeOptions {
+    /** Visible area on the ground plane (viewer camera), when mounted. */
+    viewport?: {
+        visibleWidth: number;
+        visibleHeight: number;
+    } | null;
+}
+export declare function describeScene(input: DescribeSceneInput, options?: DescribeOptions): SceneAnalysis;
+//# sourceMappingURL=describeScene.d.ts.map

package/dist/autoAnimate/describeScene.d.ts.map

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

package/dist/autoAnimate/describeScene.js

@@ -0,0 +1,165 @@
+// =============================================================================
+// describeScene — the ONE description of the scene every AI request carries.
+// =============================================================================
+//
+// analyzeScene (layout, roles, groups, hero) + the property registry (every
+// element's keyable tracks and settable properties, with current values and
+// bounds) in one compact, rounded shape. The client sends it as the request's
+// `scene`; the aiAgent mirrors these types (utils/v2/sceneAnalysis.ts — keep them
+// in step).
+//
+//   scene        scale / ground / bounds / hero / counts — size every magnitude by `scale`
+//   camera       pose, viewport at ground, keyable paths
+//   environment  sky / clouds / ocean / terrain: present? on? kind / preset, and — when
+//                on — current values as tracks (keyable) + patch (action-only)
+//   background   HDRI preset name
+//   groups       cascade orders
+//   objects      EVERY object (each consumer filters): role, saved, visible, hierarchy,
+//                transform, world bounds, material, and
+//                  tracks  what a clip can key (getTrackSpecs) with value / range
+//                  patch   config / environment properties only an instant change can set
+//
+// Pure like analyzeScene: live bounds and the viewport are injected by the caller.
+// Model nodes are left out (node animation has its own path).
+//
+import { analyzeScene } from './sceneAnalyzer.js';
+import { describeProperties, getTrackSpecs } from '../properties/registry.js';
+// --- helpers --------------------------------------------------------------------
+const r = (n) => {
+    const v = Number(n);
+    return Number.isFinite(v) ? Math.round(v * 1000) / 1000 : 0;
+};
+const rv = (v) => (v ?? []).map(r);
+const roundValue = (v) => (Array.isArray(v) ? v.map(r) : typeof v === 'number' ? r(v) : v);
+/** Registry kinds the AI can write; strings, vec2 and textures are not offered. */
+const PROP_KINDS = new Set(['vec3', 'number', 'color', 'boolean', 'select']);
+/** Families whose set-only properties go out as patch (transform / material / edges / shadow are not offered). */
+const PATCH_DOMAINS = new Set(['light', 'particles', 'effect', 'grid', 'rain', 'clouds', 'config', 'sky', 'cirrus', 'ocean', 'terrain']);
+const toProp = (p) => {
+    if (!PROP_KINDS.has(p.kind))
+        return null;
+    const out = { path: p.key, kind: p.kind, value: roundValue(p.value) };
+    if (p.min !== undefined)
+        out.min = p.min;
+    if (p.max !== undefined)
+        out.max = p.max;
+    if (p.options?.length)
+        out.options = p.options.map(o => o.value);
+    return out;
+};
+/** tracks = what a clip keys (with values and bounds); patch = the element's other settable properties. */
+function elementProps(element, settings) {
+    const described = new Map(describeProperties(element, settings).map(p => [p.key, p]));
+    const trackPaths = getTrackSpecs(element, settings).map(s => s.key);
+    const keyed = new Set(trackPaths);
+    const tracks = [];
+    for (const path of trackPaths) {
+        const p = described.get(path);
+        const prop = p && toProp(p);
+        if (prop)
+            tracks.push(prop);
+    }
+    const patch = [];
+    for (const p of described.values()) {
+        if (keyed.has(p.key) || !PATCH_DOMAINS.has(p.domain))
+            continue;
+        const prop = toProp(p);
+        if (prop)
+            patch.push(prop);
+    }
+    return { tracks, patch };
+}
+/** One environment element: always its identity; values only when it is on (they are what an animation / change can touch). */
+function environmentOf(key, settings, on) {
+    const cfg = key === 'sky' ? settings : settings?.config;
+    const present = key === 'sky' ? !!settings
+        : key === 'ocean' ? !!(cfg && typeof cfg === 'object' && cfg.waveModel)
+            : !!(cfg && typeof cfg === 'object');
+    const kind = key === 'clouds' ? cfg?.deckType : key === 'ocean' ? cfg?.waterType : key === 'terrain' ? cfg?.terrainType : undefined;
+    const values = on ? elementProps(key, settings) : { tracks: [], patch: [] };
+    return {
+        present,
+        on,
+        ...(kind ? { kind } : {}),
+        ...(cfg?.preset ? { preset: cfg.preset } : {}),
+        ...(key === 'ocean' && cfg?.host ? { host: cfg.host } : {}),
+        ...(key === 'clouds' && settings?.cirrus ? { cirrus: { on: settings.cirrus.enabled !== false, ...(settings.cirrus.preset ? { preset: settings.cirrus.preset } : {}) } } : {}),
+        ...values,
+    };
+}
+function materialOf(obj) {
+    const ms = obj?.materialSettings;
+    if (!ms?.materialType && !ms?.color)
+        return undefined;
+    return {
+        ...(ms.materialType ? { type: ms.materialType } : {}),
+        ...(ms.materialVariant ? { variant: ms.materialVariant } : {}),
+        ...(typeof ms.color === 'string' ? { color: ms.color } : {}),
+    };
+}
+// --- main ---------------------------------------------------------------------------
+export function describeScene(input, options = {}) {
+    // Live bounds, no model nodes.
+    const profile = analyzeScene(input, { measure: options.measure });
+    const byId = new Map((input.objects ?? []).filter((o) => o && typeof o.id === 'string').map((o) => [o.id, o]));
+    const objects = [];
+    for (const p of profile.objects) {
+        const obj = byId.get(p.id);
+        if (!obj)
+            continue;
+        const material = materialOf(obj);
+        objects.push({
+            id: p.id,
+            name: p.name,
+            type: p.type,
+            ...(obj.config?.type ? { subType: obj.config.type } : {}),
+            role: p.role,
+            saved: p.saved,
+            visible: p.visible,
+            ...(p.groupId ? { groupId: p.groupId } : {}),
+            ...(p.parentId ? { parentId: p.parentId } : {}),
+            ...(p.childIds.length ? { childIds: p.childIds } : {}),
+            position: rv(p.position),
+            rotation: rv(p.rotation),
+            scale: rv(p.scale),
+            center: rv(p.bounds.center),
+            size: rv(p.bounds.size),
+            fadeable: p.capabilities.fadeable,
+            ...(material ? { material } : {}),
+            ...elementProps('object', obj),
+        });
+    }
+    const countsByType = {};
+    Object.entries(profile.countsByType).forEach(([k, v]) => { if (v)
+        countsByType[k] = v; });
+    const vp = options.viewport;
+    return {
+        version: 2,
+        scene: {
+            scale: r(profile.scale),
+            ground: r(profile.ground),
+            center: rv(profile.bounds.center),
+            size: rv(profile.bounds.size),
+            heroId: profile.heroId,
+            countsByType,
+        },
+        camera: {
+            position: rv(profile.camera.position),
+            target: rv(profile.camera.target),
+            fov: r(profile.camera.fov),
+            distance: r(profile.camera.distance),
+            viewport: vp ? { visibleWidth: r(vp.visibleWidth), visibleHeight: r(vp.visibleHeight) } : { visibleWidth: 0, visibleHeight: 0 },
+            tracks: elementProps('camera', input.camera ?? {}).tracks,
+            patch: [],
+        },
+        environment: {
+            sky: environmentOf('sky', input.sky, profile.environment.sky),
+            clouds: environmentOf('clouds', input.clouds, profile.environment.clouds),
+            ocean: environmentOf('ocean', input.ocean, profile.environment.ocean),
+            terrain: environmentOf('terrain', input.terrain, profile.environment.terrain),
+        },
+        background: { hdri: input.hdr?.name ?? null },
+        groups: profile.groups.map(g => ({ id: g.id, kind: g.kind, axis: g.axis, order: g.order, radialOrder: g.radialOrder })),
+        objects,
+    };
+}

package/dist/autoAnimate/draft.d.ts

@@ -0,0 +1,59 @@
+import type { V3 } from './types';
+export type DraftEase = 'linear' | 'step' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeOutElastic' | 'easeOutBounce';
+export type DraftValue = number | V3 | number[] | string | boolean;
+export interface DraftKey {
+    id: string;
+    t: number;
+    value: DraftValue;
+    ease?: DraftEase;
+}
+export interface DraftTrack {
+    id: string;
+    state: string;
+    node?: string;
+    path: string;
+    keys: DraftKey[];
+}
+export interface DraftClip {
+    id: string;
+    name: string;
+    key: string;
+    description?: string;
+    duration: number;
+    fps: number;
+    loop: boolean;
+    yoyo: boolean;
+    endMode: 'hold' | 'restore';
+    tracks: DraftTrack[];
+}
+export interface DraftStepClip {
+    id: string;
+    clipId: string;
+    delay: number;
+    speed: number;
+}
+export interface DraftSequence {
+    id: string;
+    name: string;
+    key: string;
+    description?: string;
+    steps: Array<{
+        id: string;
+        clips: DraftStepClip[];
+    }>;
+    cues: [];
+    loop: boolean;
+    yoyo: boolean;
+    reverse: boolean;
+    endMode: 'hold' | 'restore';
+    driver: 'time' | 'mouseWheel' | 'mouseX' | 'mouseY';
+    driverSettings: {
+        sensitivity: number;
+        smoothing: number;
+        invert: boolean;
+    };
+    autoplay: boolean;
+}
+/** Eases that feel wrong when an input scrubs them backwards (wheel / mouse drivers). */
+export declare const OVERSHOOT_EASES: Set<DraftEase>;
+//# sourceMappingURL=draft.d.ts.map

package/dist/autoAnimate/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../../src/autoAnimate/draft.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,MAAM,SAAS,GACf,QAAQ,GAAG,MAAM,GACjB,YAAY,GAAG,aAAa,GAAG,eAAe,GAC9C,aAAa,GAAG,cAAc,GAAG,gBAAgB,GACjD,aAAa,GAAG,cAAc,GAAG,gBAAgB,GACjD,YAAY,GAAG,aAAa,GAAG,eAAe,GAC9C,YAAY,GAAG,aAAa,GAAG,eAAe,GAC9C,YAAY,GAAG,aAAa,GAAG,eAAe,GAC9C,gBAAgB,GAAG,eAAe,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnE,MAAM,WAAW,QAAQ;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE;AACxF,MAAM,WAAW,UAAU;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE;AACxG,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC5D,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACzF,MAAM,EAAE,UAAU,EAAE,CAAC;CACxB;AACD,MAAM,WAAW,aAAa;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAC3F,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC5D,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC,CAAC;IACrD,IAAI,EAAE,EAAE,CAAC;IACT,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5E,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,cAAc,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED,yFAAyF;AACzF,eAAO,MAAM,eAAe,gBAAwG,CAAC"}

package/dist/autoAnimate/draft.js

@@ -0,0 +1,2 @@
+/** Eases that feel wrong when an input scrubs them backwards (wheel / mouse drivers). */
+export const OVERSHOOT_EASES = new Set(['easeInBack', 'easeOutBack', 'easeInOutBack', 'easeOutElastic', 'easeOutBounce']);

package/dist/autoAnimate/index.d.ts

@@ -0,0 +1,14 @@
+export * from './types';
+export { analyzeScene, baseName } from './sceneAnalyzer';
+export { makeBounds, boundsAround, unionBounds } from './bounds';
+export { generateAnimation } from './composer';
+export type { GenerateOptions, GenerateResult, AutoTemplate, LengthName } from './composer';
+export { validateGenerated } from './validator';
+export type { GenerationIssue } from './validator';
+export { STYLES } from './recipes';
+export type { StyleName, EnterName, AmbientName } from './recipes';
+export type { DraftClip, DraftSequence, DraftTrack, DraftKey, DraftEase, DraftValue } from './draft';
+export { createRng } from './rng';
+export { describeScene } from './describeScene';
+export type { SceneAnalysis, DescribeSceneInput, DescribeOptions, PropKind, PropContext, ElementContext, ObjectContext, EnvironmentKey, EnvironmentContext, } from './describeScene';
+//# sourceMappingURL=index.d.ts.map

package/dist/autoAnimate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/autoAnimate/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrG,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EACR,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EACzF,aAAa,EAAE,cAAc,EAAE,kBAAkB,GACpD,MAAM,iBAAiB,CAAC"}

package/dist/autoAnimate/index.js

@@ -0,0 +1,9 @@
+// Auto-animate: scene analysis (→ recipes → composer → validator). See claude/auto-animate-plan.md.
+export * from './types.js';
+export { analyzeScene, baseName } from './sceneAnalyzer.js';
+export { makeBounds, boundsAround, unionBounds } from './bounds.js';
+export { generateAnimation } from './composer.js';
+export { validateGenerated } from './validator.js';
+export { STYLES } from './recipes.js';
+export { createRng } from './rng.js';
+export { describeScene } from './describeScene.js';