@3driseai/3drise-core 1.0.18 → 1.0.20

package/dist/autoAnimate/recipes.d.ts

@@ -0,0 +1,87 @@
+import type { DraftEase, DraftTrack, DraftValue } from './draft';
+import type { Rng } from './rng';
+import type { ObjectProfile, SceneProfile, V3 } from './types';
+export type StyleName = 'calm' | 'energetic' | 'cinematic';
+export interface StyleSpec {
+    name: StyleName;
+    durationMul: number;
+    amplitudeMul: number;
+    /** Entrance recipes to pick from, in preference order. */
+    enters: EnterName[];
+    enterEase: DraftEase;
+    popEase: DraftEase;
+    dropEase: DraftEase;
+    ambientEase: DraftEase;
+    /** Camera orbit swing, degrees. */
+    orbitDeg: number;
+}
+export declare const STYLES: Record<StyleName, StyleSpec>;
+export declare class Ledger {
+    private authored;
+    private values;
+    constructor(authored: (state: string, path: string) => DraftValue | undefined);
+    get(state: string, path: string): DraftValue | undefined;
+    set(state: string, path: string, value: DraftValue): void;
+    /** Record every track's last value (after placing a clip). */
+    commit(tracks: DraftTrack[]): void;
+}
+export interface RecipeContext {
+    profile: SceneProfile;
+    rng: Rng;
+    style: StyleSpec;
+    ledger: Ledger;
+    makeId: (prefix: string) => string;
+    /** Wheel / mouse driven: no overshoot eases. */
+    driven: boolean;
+}
+/** One property's move for an entrance: from `away` to `rest`. */
+export interface EnterMove {
+    state: string;
+    path: string;
+    away: DraftValue;
+    rest: DraftValue;
+    ease: DraftEase;
+}
+export type EnterName = 'rise' | 'drop' | 'pop' | 'spin' | 'fade';
+export declare const round: (n: number, d?: number) => number;
+/**
+ * Plan an entrance. Returns null when it can't work here (a rise with no room above
+ * the ground, a fade on an opaque material) — the caller tries the next one.
+ */
+export declare function planEnter(name: EnterName, p: ObjectProfile, amp: number, ctx: RecipeContext): EnterMove[] | null;
+/** The first entrance of the style that works for this object (pop always does). */
+export declare function chooseEnter(p: ObjectProfile, amp: number, ctx: RecipeContext, prefer?: EnterName): {
+    name: EnterName;
+    moves: EnterMove[];
+};
+/** A light "switches on": intensity from ~0 to its authored value. */
+export declare function planLightEnter(p: ObjectProfile, ctx: RecipeContext): EnterMove[];
+export type AmbientName = 'float' | 'sway' | 'breathe' | 'glow' | 'swell';
+/** Keys (relative to t0, over T) of an out-and-back move; null when not applicable. */
+export declare function planAmbient(name: AmbientName, p: ObjectProfile, amp: number, ctx: RecipeContext): {
+    path: string;
+    points: Array<[number, DraftValue]>;
+} | null;
+/** Pull back from further away into the authored pose. */
+export declare function planCameraDolly(ctx: RecipeContext, amp: number): {
+    path: string;
+    away: DraftValue;
+    rest: DraftValue;
+} | null;
+/**
+ * Swing around a centre and back (0 → ±A → 0 on a sine, so it starts and ends at
+ * rest and its speed is continuous). The swing is limited so the peak angular
+ * speed stays under MAX_CAMERA_DEG_PER_S. Returns sampled position keys (a chord
+ * between two far keys would cut inside the arc) and, when the camera looks
+ * elsewhere, a target track that turns to the centre and back.
+ */
+export declare function planCameraOrbit(ctx: RecipeContext, center: V3, duration: number, direction: 1 | -1): DraftTrack[];
+/** The slow layer: sky elevation and cloud coverage, when those are on. */
+export declare function environmentPaths(ctx: RecipeContext): Array<{
+    state: string;
+    path: string;
+    delta: number;
+    min: number;
+    max: number;
+}>;
+//# sourceMappingURL=recipes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../../src/autoAnimate/recipes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,SAAS,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;IACpB,WAAW,EAAE,SAAS,CAAC;IACvB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,CAa/C,CAAC;AAMF,qBAAa,MAAM;IAEH,OAAO,CAAC,QAAQ;IAD5B,OAAO,CAAC,MAAM,CAAiC;gBAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS;IACrF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIxD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAGzD,8DAA8D;IAC9D,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI;CAMrC;AAED,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAE/G,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAKlE,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,EAAE,UAAK,WAAsC,CAAC;AAW7E;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,SAAS,EAAE,GAAG,IAAI,CA+ChH;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAQ1I;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,GAAG,SAAS,EAAE,CAIhF;AAMD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1E,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;CAAE,GAAG,IAAI,CAkC9J;AAQD,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAM5H;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,EAAE,CA8BjH;AAMD,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAOpI"}

package/dist/autoAnimate/recipes.js

@@ -0,0 +1,224 @@
+export const STYLES = {
+    calm: {
+        name: 'calm', durationMul: 1.35, amplitudeMul: 0.7, enters: ['rise', 'fade', 'pop'],
+        enterEase: 'easeOutCubic', popEase: 'easeOutCubic', dropEase: 'easeOutCubic', ambientEase: 'easeInOutSine', orbitDeg: 18,
+    },
+    energetic: {
+        name: 'energetic', durationMul: 0.75, amplitudeMul: 1.2, enters: ['pop', 'drop', 'rise'],
+        enterEase: 'easeOutQuart', popEase: 'easeOutBack', dropEase: 'easeOutBounce', ambientEase: 'easeInOutQuad', orbitDeg: 30,
+    },
+    cinematic: {
+        name: 'cinematic', durationMul: 1.2, amplitudeMul: 1, enters: ['spin', 'rise', 'fade'],
+        enterEase: 'easeOutExpo', popEase: 'easeOutCubic', dropEase: 'easeOutCubic', ambientEase: 'easeInOutSine', orbitDeg: 35,
+    },
+};
+// ---------------------------------------------------------------------------------------
+// Ledger — the current value of every (state, path): authored until a track moves it.
+// ---------------------------------------------------------------------------------------
+export class Ledger {
+    authored;
+    values = new Map();
+    constructor(authored) {
+        this.authored = authored;
+    }
+    get(state, path) {
+        const k = `${state}|${path}`;
+        return this.values.has(k) ? this.values.get(k) : this.authored(state, path);
+    }
+    set(state, path, value) {
+        this.values.set(`${state}|${path}`, value);
+    }
+    /** Record every track's last value (after placing a clip). */
+    commit(tracks) {
+        for (const t of tracks) {
+            const last = t.keys[t.keys.length - 1];
+            if (last)
+                this.set(t.state, t.path, last.value);
+        }
+    }
+}
+const asV3 = (v, fallback) => Array.isArray(v) && v.length >= 3 ? [Number(v[0]), Number(v[1]), Number(v[2])] : fallback;
+const r3 = (v) => [round(v[0]), round(v[1]), round(v[2])];
+export const round = (n, d = 4) => Math.round(n * 10 ** d) / 10 ** d;
+const safeEase = (ctx, ease, fallback = 'easeOutCubic') => ctx.driven && ['easeInBack', 'easeOutBack', 'easeInOutBack', 'easeOutElastic', 'easeOutBounce'].includes(ease) ? fallback : ease;
+const height = (p) => Math.max(p.bounds.size[1], p.bounds.radius * 0.5, 1e-3);
+// ---------------------------------------------------------------------------------------
+// Entrances (end at the authored values)
+// ---------------------------------------------------------------------------------------
+/**
+ * Plan an entrance. Returns null when it can't work here (a rise with no room above
+ * the ground, a fade on an opaque material) — the caller tries the next one.
+ */
+export function planEnter(name, p, amp, ctx) {
+    const id = p.id;
+    const pos = asV3(ctx.ledger.get(id, 'meshSettings.position'), p.position);
+    const rot = asV3(ctx.ledger.get(id, 'meshSettings.rotation'), p.rotation);
+    const scl = asV3(ctx.ledger.get(id, 'meshSettings.scale'), p.scale);
+    const s = ctx.style;
+    const moves = [];
+    const fade = () => {
+        if (!p.capabilities.fadeable)
+            return null;
+        const rest = Number(ctx.ledger.get(id, 'materialSettings.opacity') ?? 1);
+        return { state: id, path: 'materialSettings.opacity', away: 0, rest, ease: 'easeOutQuad' };
+    };
+    switch (name) {
+        case 'rise': {
+            // From below, but never under the ground.
+            let d = 0.35 * height(p) * amp;
+            const room = p.bounds.min[1] - ctx.profile.ground;
+            if (!p.parentId)
+                d = Math.min(d, Math.max(0, room));
+            if (d < 0.1 * height(p) * amp)
+                return null;
+            const local = d / p.parentScale[1];
+            moves.push({ state: id, path: 'meshSettings.position', away: r3([pos[0], pos[1] - local, pos[2]]), rest: pos, ease: s.enterEase });
+            const f = fade();
+            if (f)
+                moves.push(f);
+            return moves;
+        }
+        case 'drop': {
+            const local = (0.6 * height(p) * amp) / p.parentScale[1];
+            moves.push({ state: id, path: 'meshSettings.position', away: r3([pos[0], pos[1] + local, pos[2]]), rest: pos, ease: safeEase(ctx, s.dropEase) });
+            return moves;
+        }
+        case 'pop': {
+            moves.push({ state: id, path: 'meshSettings.scale', away: r3([scl[0] * 0.001, scl[1] * 0.001, scl[2] * 0.001]), rest: scl, ease: safeEase(ctx, s.popEase) });
+            return moves;
+        }
+        case 'spin': {
+            // A quarter turn into place, growing from 60%.
+            moves.push({ state: id, path: 'meshSettings.rotation', away: r3([rot[0], rot[1] - (Math.PI / 2) * Math.min(1.2, amp), rot[2]]), rest: rot, ease: s.enterEase });
+            moves.push({ state: id, path: 'meshSettings.scale', away: r3([scl[0] * 0.6, scl[1] * 0.6, scl[2] * 0.6]), rest: scl, ease: s.enterEase });
+            return moves;
+        }
+        case 'fade': {
+            const f = fade();
+            return f ? [f] : null;
+        }
+    }
+    return null;
+}
+/** The first entrance of the style that works for this object (pop always does). */
+export function chooseEnter(p, amp, ctx, prefer) {
+    const order = [...(prefer ? [prefer] : []), ...ctx.style.enters, 'pop'];
+    for (const name of order) {
+        if (p.type === 'light')
+            break;
+        const moves = planEnter(name, p, amp, ctx);
+        if (moves?.length)
+            return { name, moves };
+    }
+    return { name: 'pop', moves: planEnter('pop', p, amp, ctx) ?? [] };
+}
+/** A light "switches on": intensity from ~0 to its authored value. */
+export function planLightEnter(p, ctx) {
+    if (!p.capabilities.config.includes('intensity'))
+        return [];
+    const rest = Number(ctx.ledger.get(p.id, 'config.intensity') ?? 1);
+    return [{ state: p.id, path: 'config.intensity', away: round(rest * 0.05), rest, ease: 'easeInOutSine' }];
+}
+/** Keys (relative to t0, over T) of an out-and-back move; null when not applicable. */
+export function planAmbient(name, p, amp, ctx) {
+    const id = p.id;
+    const e = amp * ctx.style.amplitudeMul;
+    switch (name) {
+        case 'float': {
+            const pos = asV3(ctx.ledger.get(id, 'meshSettings.position'), p.position);
+            const up = (0.06 * height(p) * e) / p.parentScale[1];
+            return { path: 'meshSettings.position', points: [[0, pos], [0.5, r3([pos[0], pos[1] + up, pos[2]])], [1, pos]] };
+        }
+        case 'sway': {
+            const rot = asV3(ctx.ledger.get(id, 'meshSettings.rotation'), p.rotation);
+            const a = 0.06 * e;
+            return {
+                path: 'meshSettings.rotation',
+                points: [[0, rot], [0.25, r3([rot[0], rot[1], rot[2] + a])], [0.5, rot], [0.75, r3([rot[0], rot[1], rot[2] - a])], [1, rot]],
+            };
+        }
+        case 'breathe': {
+            const scl = asV3(ctx.ledger.get(id, 'meshSettings.scale'), p.scale);
+            const k = 1 + 0.04 * e;
+            return { path: 'meshSettings.scale', points: [[0, scl], [0.5, r3([scl[0] * k, scl[1] * k, scl[2] * k])], [1, scl]] };
+        }
+        case 'glow': {
+            if (!p.capabilities.emissive)
+                return null;
+            const rest = Number(ctx.ledger.get(id, 'materialSettings.emissiveIntensity') ?? 0);
+            return { path: 'materialSettings.emissiveIntensity', points: [[0, rest], [0.5, round(rest + Math.max(0.6, rest * 0.8) * e)], [1, rest]] };
+        }
+        case 'swell': {
+            if (!p.capabilities.config.includes('intensity'))
+                return null;
+            const rest = Number(ctx.ledger.get(id, 'config.intensity') ?? 1);
+            return { path: 'config.intensity', points: [[0, rest], [0.5, round(rest * (1 + 0.25 * e))], [1, rest]] };
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------------------
+// Camera
+// ---------------------------------------------------------------------------------------
+const MAX_CAMERA_DEG_PER_S = 60;
+/** Pull back from further away into the authored pose. */
+export function planCameraDolly(ctx, amp) {
+    const pos = asV3(ctx.ledger.get('camera', 'position'), ctx.profile.camera.position);
+    const target = asV3(ctx.ledger.get('camera', 'controls.target'), ctx.profile.camera.target);
+    const k = 1 + 0.35 * amp * ctx.style.amplitudeMul;
+    const away = r3([target[0] + (pos[0] - target[0]) * k, target[1] + (pos[1] - target[1]) * k, target[2] + (pos[2] - target[2]) * k]);
+    return { path: 'position', away, rest: pos };
+}
+/**
+ * Swing around a centre and back (0 → ±A → 0 on a sine, so it starts and ends at
+ * rest and its speed is continuous). The swing is limited so the peak angular
+ * speed stays under MAX_CAMERA_DEG_PER_S. Returns sampled position keys (a chord
+ * between two far keys would cut inside the arc) and, when the camera looks
+ * elsewhere, a target track that turns to the centre and back.
+ */
+export function planCameraOrbit(ctx, center, duration, direction) {
+    const pos = asV3(ctx.ledger.get('camera', 'position'), ctx.profile.camera.position);
+    const target = asV3(ctx.ledger.get('camera', 'controls.target'), ctx.profile.camera.target);
+    const dx = pos[0] - center[0];
+    const dz = pos[2] - center[2];
+    const radius = Math.hypot(dx, dz);
+    if (radius < 1e-3 || duration <= 0)
+        return [];
+    const a0 = Math.atan2(dz, dx);
+    const maxDeg = (MAX_CAMERA_DEG_PER_S * duration) / Math.PI; // peak of A·π/D
+    const A = (Math.min(ctx.style.orbitDeg, maxDeg) * Math.PI) / 180 * direction;
+    const n = Math.max(8, Math.ceil(duration / 0.25));
+    const keys = Array.from({ length: n + 1 }, (_, i) => {
+        const t = (duration * i) / n;
+        const a = a0 + A * Math.sin((Math.PI * t) / duration);
+        return { id: ctx.makeId('k'), t: round(t), value: r3([center[0] + radius * Math.cos(a), pos[1], center[2] + radius * Math.sin(a)]), ease: 'linear' };
+    });
+    const tracks = [{ id: ctx.makeId('tr'), state: 'camera', path: 'position', keys }];
+    const off = Math.hypot(target[0] - center[0], target[1] - center[1], target[2] - center[2]);
+    if (off > ctx.profile.scale * 0.05) {
+        tracks.push({
+            id: ctx.makeId('tr'), state: 'camera', path: 'controls.target',
+            keys: [
+                { id: ctx.makeId('k'), t: 0, value: target, ease: 'easeInOutCubic' },
+                { id: ctx.makeId('k'), t: round(duration * 0.25), value: r3(center), ease: 'linear' },
+                { id: ctx.makeId('k'), t: round(duration * 0.75), value: r3(center), ease: 'easeInOutCubic' },
+                { id: ctx.makeId('k'), t: round(duration), value: target },
+            ],
+        });
+    }
+    return tracks;
+}
+// ---------------------------------------------------------------------------------------
+// Environment
+// ---------------------------------------------------------------------------------------
+/** The slow layer: sky elevation and cloud coverage, when those are on. */
+export function environmentPaths(ctx) {
+    const env = ctx.profile.environment;
+    const out = [];
+    const a = ctx.style.amplitudeMul;
+    if (env.sky && typeof ctx.ledger.get('sky', 'elevation') === 'number')
+        out.push({ state: 'sky', path: 'elevation', delta: 6 * a, min: -5, max: 90 });
+    if (env.clouds && typeof ctx.ledger.get('clouds', 'config.coverage') === 'number')
+        out.push({ state: 'clouds', path: 'config.coverage', delta: 0.1 * a, min: 0, max: 1 });
+    return out;
+}

package/dist/autoAnimate/rng.d.ts

@@ -0,0 +1,10 @@
+/** Seeded PRNG (mulberry32): the same seed gives the same animation (Shuffle = a new seed). */
+export interface Rng {
+    next(): number;
+    range(min: number, max: number): number;
+    /** 1 ± amount — delicate per-member variation. */
+    jitter(amount: number): number;
+    pick<T>(list: readonly T[]): T;
+}
+export declare function createRng(seed: number): Rng;
+//# sourceMappingURL=rng.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/autoAnimate/rng.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,WAAW,GAAG;IAChB,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACxC,kDAAkD;IAClD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;CAClC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAe3C"}

package/dist/autoAnimate/rng.js

@@ -0,0 +1,16 @@
+export function createRng(seed) {
+    let a = (seed >>> 0) || 0x9e3779b9;
+    const next = () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    return {
+        next,
+        range: (min, max) => min + (max - min) * next(),
+        jitter: (amount) => 1 + (next() * 2 - 1) * amount,
+        pick: (list) => list[Math.floor(next() * list.length) % list.length],
+    };
+}

package/dist/autoAnimate/sceneAnalyzer.d.ts

@@ -0,0 +1,7 @@
+import { makeBounds } from './bounds';
+import type { AnalyzeOptions, SceneInput, SceneProfile } from './types';
+/** "Chair 2", "chair_copy", "Chair (3)" → "chair". */
+export declare const baseName: (name: string) => string;
+export declare function analyzeScene(input: SceneInput, options?: AnalyzeOptions): SceneProfile;
+export { makeBounds };
+//# sourceMappingURL=sceneAnalyzer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sceneAnalyzer.d.ts","sourceRoot":"","sources":["../../src/autoAnimate/sceneAnalyzer.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAwC,UAAU,EAAe,MAAM,UAAU,CAAC;AACzF,OAAO,KAAK,EACR,cAAc,EACa,UAAU,EAAE,YAAY,EACtD,MAAM,SAAS,CAAC;AAsBjB,sDAAsD;AACtD,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,MAMzB,CAAC;AAgHhB,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,cAAmB,GAAG,YAAY,CA4I1F;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/autoAnimate/sceneAnalyzer.js

@@ -0,0 +1,291 @@
+// =============================================================================
+// analyzeScene — what's in the scene, from an animator's point of view.
+// =============================================================================
+//
+// Pure: reads plain settings (objects, camera, environment). Scene access is
+// injected — `measure(id)` gives real world bounds from the live scene (viewer);
+// without it bounds are estimated from the authored transform (a unit box scaled),
+// which is enough for layout and roles, and works server-side (aiAgent).
+//
+// Produces a SceneProfile:
+//   environment    which of sky / clouds / ocean / terrain are on, sea level
+//   camera         pose, target, distance
+//   objects        type, hierarchy, world bounds, role, group, capabilities
+//   groups         siblings of a group object; clusters of alike top-level
+//                  objects (same base name, or same type + size + close together),
+//                  with cascade orders (along the main axis, and radial)
+//   hero           the object the scene is about
+//   bounds/ground/scale   the content's extent — every magnitude is scaled by `scale`
+//
+import { Euler, Matrix4, Quaternion, Vector3 } from 'three';
+import { getAnimatableProperties } from '../utils/getAnimatableProperties.js';
+import { isUuid } from '../utils/idUtils.js';
+import { boundsAround, distance, EMPTY_BOUNDS, makeBounds, unionBounds } from './bounds.js';
+/** Never the hero, never grouped: they are the stage, not the actors. */
+const BACKGROUND_TYPES = new Set(['grid', 'space', 'environment', 'effect', 'path']);
+/** Can be the hero. */
+const HERO_TYPES = new Set(['mesh', 'model', 'text', 'custom_primitive', 'gallery', 'group']);
+/** Estimated half-extent of an unmeasured object of scale 1. */
+const UNIT_HALF = { light: 0.15, text: 0.5 };
+const MATERIAL_SKIP = new Set(['wireframe', 'transparent', 'flatShading', 'materialName', 'name']);
+const vec3 = (v, fallback) => Array.isArray(v) && v.length >= 3 && v.every((n) => Number.isFinite(Number(n)))
+    ? [Number(v[0]), Number(v[1]), Number(v[2])]
+    : fallback;
+const isKeyable = (v) => typeof v === 'number' ||
+    typeof v === 'boolean' ||
+    (typeof v === 'string' && /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(v)) ||
+    (Array.isArray(v) && v.length === 3 && v.every(n => typeof n === 'number'));
+/** "Chair 2", "chair_copy", "Chair (3)" → "chair". */
+export const baseName = (name) => (name || '').toLowerCase()
+    .replace(/\(\d+\)/g, '')
+    .replace(/\b(copy|clone)\b/g, '')
+    .replace(/[\s_\-.#]*\d+\s*$/g, '')
+    .replace(/[\s_\-.#]+$/g, '')
+    .trim();
+function capabilitiesOf(obj, nodes) {
+    const type = obj.type;
+    const material = type === 'light' || type === 'group'
+        ? []
+        : getAnimatableProperties(obj, 'material')
+            .map(p => p.value)
+            .filter(k => !MATERIAL_SKIP.has(k) && isKeyable(obj.materialSettings?.[k]));
+    const edgesOn = obj.edgesSettings && obj.edgesSettings.enabled !== false && obj.edgesSettings.materialSettings;
+    const edges = edgesOn
+        ? getAnimatableProperties(obj, 'edges')
+            .map(p => p.value)
+            .filter(k => k !== 'tubeRadius' && k !== 'cubeSize' && isKeyable(obj.edgesSettings.materialSettings[k]))
+        : [];
+    const config = [
+        ...getAnimatableProperties(obj, 'light'),
+        ...getAnimatableProperties(obj, 'particles'),
+    ].map(p => p.value);
+    return {
+        transform: type !== 'environment',
+        material,
+        edges,
+        config,
+        nodes,
+        fadeable: material.includes('opacity') && obj.materialSettings?.transparent === true,
+        emissive: material.includes('emissiveIntensity'),
+    };
+}
+/** World matrix of an object from the authored transforms up its parent chain. */
+function worldMatrix(id, byId, cache, guard = 0) {
+    const hit = cache.get(id);
+    if (hit)
+        return hit;
+    const obj = byId.get(id);
+    const m = new Matrix4();
+    if (obj) {
+        const ms = obj.meshSettings ?? {};
+        const r = vec3(ms.rotation, [0, 0, 0]);
+        m.compose(new Vector3(...vec3(ms.position, [0, 0, 0])), new Quaternion().setFromEuler(new Euler(r[0], r[1], r[2])), new Vector3(...vec3(ms.scale, [1, 1, 1])));
+        if (obj.parentId && byId.has(obj.parentId) && guard < 64) {
+            m.premultiply(worldMatrix(obj.parentId, byId, cache, guard + 1));
+        }
+    }
+    cache.set(id, m);
+    return m;
+}
+function worldScale(id, byId, cache) {
+    const s = new Vector3();
+    worldMatrix(id, byId, cache).decompose(new Vector3(), new Quaternion(), s);
+    return [Math.abs(s.x) || 1, Math.abs(s.y) || 1, Math.abs(s.z) || 1];
+}
+function estimateBounds(obj, world) {
+    const pos = new Vector3();
+    const quat = new Quaternion();
+    const scl = new Vector3();
+    world.decompose(pos, quat, scl);
+    const h = UNIT_HALF[obj.type] ?? 0.5;
+    return boundsAround([pos.x, pos.y, pos.z], [Math.abs(scl.x) * h, Math.abs(scl.y) * h, Math.abs(scl.z) * h]);
+}
+function environmentOf(input) {
+    const ocean = !!input.ocean?.config?.enabled;
+    const seaLevel = Number(input.ocean?.config?.seaLevel);
+    return {
+        sky: !!input.sky?.visible,
+        clouds: !!(input.clouds?.config?.enabled || input.clouds?.cirrus?.enabled),
+        ocean,
+        terrain: !!input.terrain?.config?.enabled,
+        seaLevel: ocean && Number.isFinite(seaLevel) ? seaLevel : null,
+    };
+}
+function cameraOf(input) {
+    const position = vec3(input.camera?.position, [0, 2, 8]);
+    const target = vec3(input.camera?.controls?.target, [0, 0, 0]);
+    const fov = Number(input.camera?.fov) || 50;
+    return { position, target, fov, distance: distance(position, target) };
+}
+/** Axis with the largest spread of the given centres. */
+function mainAxis(centers) {
+    const spread = [0, 1, 2].map(i => Math.max(...centers.map(c => c[i])) - Math.min(...centers.map(c => c[i])));
+    const i = spread.indexOf(Math.max(...spread));
+    return ['x', 'y', 'z'][i];
+}
+function makeGroup(id, kind, parentId, members) {
+    const bounds = unionBounds(members.map(m => m.bounds)) ?? EMPTY_BOUNDS;
+    const axis = mainAxis(members.map(m => m.bounds.center));
+    const ai = { x: 0, y: 1, z: 2 }[axis];
+    return {
+        id,
+        kind,
+        parentId,
+        memberIds: members.map(m => m.id),
+        axis,
+        order: [...members].sort((a, b) => a.bounds.center[ai] - b.bounds.center[ai]).map(m => m.id),
+        radialOrder: [...members]
+            .sort((a, b) => distance(a.bounds.center, bounds.center) - distance(b.bounds.center, bounds.center))
+            .map(m => m.id),
+        bounds,
+        uniformType: members.every(m => m.type === members[0].type),
+    };
+}
+export function analyzeScene(input, options = {}) {
+    const raw = (input.objects ?? []).filter((o) => o && typeof o.id === 'string');
+    const byId = new Map(raw.map((o) => [o.id, o]));
+    const matrices = new Map();
+    const environment = environmentOf(input);
+    const camera = cameraOf(input);
+    // --- objects (bounds, hierarchy, capabilities) ------------------------------------
+    const children = new Map();
+    raw.forEach((o) => {
+        if (o.parentId && byId.has(o.parentId)) {
+            const list = children.get(o.parentId) ?? [];
+            list.push(o.id);
+            children.set(o.parentId, list);
+        }
+    });
+    const depthOf = (id, guard = 0) => {
+        const p = byId.get(id)?.parentId;
+        return p && byId.has(p) && guard < 64 ? 1 + depthOf(p, guard + 1) : 0;
+    };
+    const objects = raw.map((o) => {
+        const measured = options.measure?.(o.id) ?? null;
+        const ms = o.meshSettings ?? {};
+        return {
+            id: o.id,
+            name: ms.name || o.name || o.type,
+            type: o.type,
+            parentId: o.parentId && byId.has(o.parentId) ? o.parentId : null,
+            childIds: children.get(o.id) ?? [],
+            depth: depthOf(o.id),
+            visible: ms.visible !== false,
+            saved: isUuid(o.id),
+            position: vec3(ms.position, [0, 0, 0]),
+            rotation: vec3(ms.rotation, [0, 0, 0]),
+            scale: vec3(ms.scale, [1, 1, 1]),
+            parentScale: o.parentId && byId.has(o.parentId) ? worldScale(o.parentId, byId, matrices) : [1, 1, 1],
+            bounds: measured ?? estimateBounds(o, worldMatrix(o.id, byId, matrices)),
+            measured: !!measured,
+            role: 'standalone',
+            groupId: null,
+            capabilities: capabilitiesOf(o, o.type === 'model' ? options.nodesOf?.(o.id) ?? [] : []),
+            heroScore: 0,
+        };
+    });
+    const profileById = new Map(objects.map(p => [p.id, p]));
+    // An unmeasured container is as big as what it holds.
+    for (const p of [...objects].sort((a, b) => b.depth - a.depth)) {
+        if (p.measured || !p.childIds.length)
+            continue;
+        const kids = unionBounds(p.childIds.map(id => profileById.get(id).bounds));
+        if (kids)
+            p.bounds = kids;
+    }
+    // --- content extent -------------------------------------------------------------------
+    const actorsFirstPass = objects.filter(p => p.visible && p.type !== 'light' && !BACKGROUND_TYPES.has(p.type));
+    const roughContent = unionBounds(actorsFirstPass.map(p => p.bounds)) ?? boundsAround(camera.target, [1, 1, 1]);
+    // Huge flat things (floors, backdrops) are background too.
+    const isBackdrop = (p) => {
+        const sorted = [...p.bounds.size].sort((a, b) => a - b);
+        const flat = sorted[0] < sorted[2] * 0.05;
+        return flat && p.bounds.radius > roughContent.radius * 0.6 && !p.childIds.length;
+    };
+    // --- roles (light / background / container) ------------------------------------------
+    for (const p of objects) {
+        if (p.type === 'light')
+            p.role = 'light';
+        else if (BACKGROUND_TYPES.has(p.type) || !p.visible || (actorsFirstPass.length > 1 && isBackdrop(p)))
+            p.role = 'background';
+        else if (p.childIds.length)
+            p.role = 'container';
+    }
+    const actors = objects.filter(p => p.role !== 'light' && p.role !== 'background');
+    const bounds = unionBounds(actors.map(p => p.bounds)) ?? roughContent;
+    const scale = Math.max(0.5, bounds.radius);
+    const ground = Math.min(bounds.min[1], environment.seaLevel ?? Infinity);
+    // --- groups ---------------------------------------------------------------------------
+    const groups = [];
+    // 1. children of one group object
+    for (const p of objects) {
+        const kids = p.childIds.map(id => profileById.get(id)).filter(k => k.role !== 'light' && k.role !== 'background');
+        if (kids.length < 2)
+            continue;
+        const g = makeGroup(`parent:${p.id}`, 'parent', p.id, kids);
+        groups.push(g);
+        kids.forEach(k => { k.groupId = g.id; });
+    }
+    // 2. clusters of alike top-level objects: same base name, or same type + size + close
+    const loose = actors.filter(p => !p.parentId && !p.groupId && p.role !== 'container');
+    const parent = new Map(loose.map(p => [p.id, p.id]));
+    const find = (id) => (parent.get(id) === id ? id : find(parent.get(id)));
+    const join = (a, b) => { parent.set(find(a), find(b)); };
+    for (let i = 0; i < loose.length; i++) {
+        for (let j = i + 1; j < loose.length; j++) {
+            const a = loose[i];
+            const b = loose[j];
+            if (a.type !== b.type)
+                continue;
+            const sameName = baseName(a.name) !== '' && baseName(a.name) === baseName(b.name);
+            const ra = Math.max(a.bounds.radius, 1e-3);
+            const rb = Math.max(b.bounds.radius, 1e-3);
+            const alikeSize = Math.max(ra, rb) / Math.min(ra, rb) <= 1.6;
+            const close = distance(a.bounds.center, b.bounds.center) <= 3 * Math.max(ra, rb);
+            if (sameName || (alikeSize && close))
+                join(a.id, b.id);
+        }
+    }
+    const clusters = new Map();
+    loose.forEach(p => {
+        const root = find(p.id);
+        clusters.set(root, [...(clusters.get(root) ?? []), p]);
+    });
+    for (const [root, members] of clusters) {
+        if (members.length < 2)
+            continue;
+        const g = makeGroup(`cluster:${root}`, 'cluster', null, members);
+        groups.push(g);
+        members.forEach(m => { m.groupId = g.id; });
+    }
+    for (const p of objects)
+        if (p.groupId && p.role === 'standalone')
+            p.role = 'member';
+    // --- hero -------------------------------------------------------------------------------
+    const forward = new Vector3(...camera.target).sub(new Vector3(...camera.position)).normalize();
+    const maxRadius = Math.max(...actors.map(p => p.bounds.radius), 1e-3);
+    let heroId = null;
+    let best = 0;
+    for (const p of actors) {
+        // Top-level things only: a part of a group object is not "the scene".
+        if (!HERO_TYPES.has(p.type) || p.parentId)
+            continue;
+        const size = p.bounds.radius / maxRadius;
+        const centrality = 1 - Math.min(1, distance(p.bounds.center, camera.target) / Math.max(scale, 1e-3));
+        const toObj = new Vector3(...p.bounds.center).sub(new Vector3(...camera.position)).normalize();
+        const facing = Math.max(0, forward.dot(toObj));
+        const typeBonus = p.type === 'model' ? 0.1 : p.type === 'group' ? 0.05 : 0;
+        const inCluster = p.groupId?.startsWith('cluster:') ? 0.6 : 1; // one chair among six isn't the hero
+        p.heroScore = (0.45 * size + 0.3 * centrality + 0.25 * facing + typeBonus) * inCluster;
+        if (p.heroScore > best) {
+            best = p.heroScore;
+            heroId = p.id;
+        }
+    }
+    if (heroId)
+        profileById.get(heroId).role = 'hero';
+    const countsByType = {};
+    objects.forEach(p => { countsByType[p.type] = (countsByType[p.type] ?? 0) + 1; });
+    return { objects, groups, heroId, environment, camera, bounds, ground, scale, countsByType };
+}
+export { makeBounds };