@3driseai/3drise-viewer 0.1.28 → 0.1.29

package/dist/animationsV2/sequenceUtils.d.ts

@@ -1,4 +1,5 @@
-import type { AnimationClip, AnimationSequence, SequenceCue, StepClip } from './types';
+import type { AnimationClip, AnimationSequence, SequenceCue, StepClip, TimelineCue } from './types';
+import type { SceneCommand } from '@3driseai/3drise-core';
 export interface ScheduledClip {
     /** `${stepClip.id}` — stable across re-resolves of the same sequence. */
     id: string;
@@ -13,6 +14,8 @@ export interface ScheduledClip {
 }
 export interface ScheduledCue {
     cue: SequenceCue;
+    /** The lane it is on (cueSubject). */
+    subject: string;
     stepIndex: number;
     /** Sequence seconds. */
     time: number;
@@ -32,8 +35,33 @@ export type ClipLookup = ReadonlyMap<string, AnimationClip> | ((id: string) => A
 export declare const clipMap: (clips: readonly AnimationClip[]) => Map<string, AnimationClip>;
 /** Step clips whose clip is missing (deleted, not loaded) are skipped. */
 export declare function resolveSequence(seq: AnimationSequence, clips: ClipLookup): SequenceSchedule;
-/** Every cued action's state at sequence time T: on when its last cue at or before T is 'apply'. */
-export declare function cueStatesAt(schedule: SequenceSchedule, T: number): Map<string, boolean>;
+/** What a cue acts on. */
+export declare const cueCommand: (cue: Partial<TimelineCue> | null | undefined) => SceneCommand | null;
+/** The lane key of a cue: one lane per action, effect clip use or effect. */
+export declare function commandSubject(c: SceneCommand | null): string;
+export declare const cueSubject: (cue: Partial<SequenceCue>) => string;
+/** Every state lane's state at time T: on when its last apply / revert cue at or before T is 'apply'. */
+export declare function cueStatesAt(schedule: {
+    cues: Array<{
+        cue: TimelineCue;
+        subject: string;
+        time: number;
+    }>;
+}, T: number): Map<string, boolean>;
+/**
+ * 'fire' cues the playhead crossed moving forward from `prev` to `now` (prev < time <= now).
+ * `wrap`: a forward loop wrapped past the end (prev → total, then 0 → now).
+ */
+export declare function firedBetween<T extends {
+    cue: TimelineCue;
+    time: number;
+}>(cues: T[], prev: number, now: number, wrapTotal?: number): T[];
+/** A clip's cues on its own clock (seconds, clamped to the clip), sorted. */
+export declare function clipCueSchedule(clip: AnimationClip): Array<{
+    cue: TimelineCue;
+    subject: string;
+    time: number;
+}>;
 /**
  * Where sequence time T sits, as a cue anchor: the step it falls in (a boundary
  * belongs to the step that starts there) and the offset into it.
@@ -42,8 +70,15 @@ export declare function anchorAt(seq: AnimationSequence, schedule: SequenceSched
     stepId: string;
     at: number;
 } | null;
-/** On / off spans of one action along the sequence (for drawing). */
-export declare function cueSpans(schedule: SequenceSchedule, actionId: string): Array<{
+/** On / off spans of one lane along the timeline (for drawing). */
+export declare function cueSpans(schedule: {
+    cues: Array<{
+        cue: TimelineCue;
+        subject: string;
+        time: number;
+    }>;
+    duration: number;
+}, subject: string): Array<{
     from: number;
     to: number;
 }>;
@@ -64,7 +99,10 @@ export declare function findCueConflicts(seq: AnimationSequence, clips: ClipLook
         patch: any;
     }>;
 } | undefined): CueConflict[];
-export declare function newCue(actionId: string, stepId: string, at: number, mode?: SequenceCue['mode']): SequenceCue;
+/** A sequence cue at `at` seconds into a step. */
+export declare function newCue(command: SceneCommand, stepId: string, at: number, mode?: SequenceCue['mode']): SequenceCue;
+/** A clip cue at `at` seconds. */
+export declare function newClipCue(command: SceneCommand, at: number, mode?: TimelineCue['mode']): TimelineCue;
 /** Clip-local time (seconds, 0..clip.duration) of an entry at sequence time T. */
 export declare function entryLocalTime(entry: ScheduledClip, T: number): number;
 /**

package/dist/animationsV2/sequenceUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sequenceUtils.d.ts","sourceRoot":"","sources":["../../src/animationsV2/sequenceUtils.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIvF,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,aAAa,CAAC;IACpB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,WAAW,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxC,uFAAuF;IACvF,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC,CAAC;AAK1G,eAAO,MAAM,OAAO,GAAI,OAAO,SAAS,aAAa,EAAE,KAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAC/C,CAAC;AAKrC,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,UAAU,GAAG,gBAAgB,CA+B3F;AAID,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAOvF;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAM7H;AAED,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAU1G;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,WAAW,CAAC;IACjB,mEAAmE;IACnE,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AASD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK;IAAE,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,SAAS,GACxF,WAAW,EAAE,CAmBf;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE,WAAW,CAAC,MAAM,CAAW,GAAG,WAAW,CAErH;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAGtE;AAID,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,MAAM,EAAE,QAAQ,CAAC;IACjB,+BAA+B;IAC/B,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,UAAU,GAAG,YAAY,EAAE,CAuC/F;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAIrF;AAID,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAMxE;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAEpD;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAkBlG"}
+{"version":3,"file":"sequenceUtils.d.ts","sourceRoot":"","sources":["../../src/animationsV2/sequenceUtils.ts"],"names":[],"mappings":"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"}

package/dist/animationsV2/sequenceUtils.js

@@ -31,23 +31,61 @@ export function resolveSequence(seq, clips) {
         if (stepIndex === undefined)
             return;
         const time = Math.min(cursor, steps[stepIndex].start + safeDelay(cue.at));
-        cues.push({ cue, stepIndex, time });
+        cues.push({ cue, subject: cueSubject(cue), stepIndex, time });
     });
     cues.sort((a, b) => a.time - b.time); // stable: authored order breaks ties
     return { entries, steps, cues, duration: cursor };
 }
-// --- cues (actions) ----------------------------------------------------------------
-/** Every cued action's state at sequence time T: on when its last cue at or before T is 'apply'. */
+// --- cues -------------------------------------------------------------------------
+/** What a cue acts on. */
+export const cueCommand = (cue) => (cue?.command && typeof cue.command === 'object' ? cue.command : null);
+/** The lane key of a cue: one lane per action, effect clip use or effect. */
+export function commandSubject(c) {
+    if (!c)
+        return '';
+    if (c.kind === 'action')
+        return `action:${c.ref}`;
+    if (c.kind === 'effectClip')
+        return `effectClip:${c.use?.id}`;
+    if (c.kind === 'effect')
+        return `effect:${c.effect?.id}`;
+    return `${c.kind}:${c.ref ?? c.id}`;
+}
+export const cueSubject = (cue) => commandSubject(cueCommand(cue));
+/** Every state lane's state at time T: on when its last apply / revert cue at or before T is 'apply'. */
 export function cueStatesAt(schedule, T) {
     const out = new Map();
     for (const c of schedule.cues) {
-        if (!out.has(c.cue.actionId))
-            out.set(c.cue.actionId, false);
+        if (c.cue.mode === 'fire')
+            continue;
+        if (!out.has(c.subject))
+            out.set(c.subject, false);
         if (c.time <= T + 1e-9)
-            out.set(c.cue.actionId, c.cue.mode === 'apply');
+            out.set(c.subject, c.cue.mode === 'apply');
     }
     return out;
 }
+/**
+ * 'fire' cues the playhead crossed moving forward from `prev` to `now` (prev < time <= now).
+ * `wrap`: a forward loop wrapped past the end (prev → total, then 0 → now).
+ */
+export function firedBetween(cues, prev, now, wrapTotal) {
+    const fire = cues.filter(c => c.cue.mode === 'fire');
+    if (!fire.length)
+        return [];
+    if (wrapTotal !== undefined)
+        return fire.filter(c => (c.time > prev && c.time <= wrapTotal + 1e-9) || c.time <= now + 1e-9);
+    if (now <= prev)
+        return [];
+    return fire.filter(c => c.time > prev + 1e-9 && c.time <= now + 1e-9);
+}
+/** A clip's cues on its own clock (seconds, clamped to the clip), sorted. */
+export function clipCueSchedule(clip) {
+    return (clip.cues ?? [])
+        .filter(c => cueCommand(c))
+        .map(cue => ({ cue, subject: cueSubject(cue), time: Math.min(clip.duration, Math.max(0, Number(cue.at) || 0)) }))
+        .sort((a, b) => a.time - b.time);
+}
 /**
  * Where sequence time T sits, as a cue anchor: the step it falls in (a boundary
  * belongs to the step that starts there) and the offset into it.
@@ -61,12 +99,12 @@ export function anchorAt(seq, schedule, T) {
     const start = schedule.steps[index]?.start ?? 0;
     return { stepId: seq.steps[index].id, at: Math.max(0, T - start) };
 }
-/** On / off spans of one action along the sequence (for drawing). */
-export function cueSpans(schedule, actionId) {
+/** On / off spans of one lane along the timeline (for drawing). */
+export function cueSpans(schedule, subject) {
     const spans = [];
     let onAt = null;
     for (const c of schedule.cues) {
-        if (c.cue.actionId !== actionId)
+        if (c.subject !== subject)
             continue;
         if (c.cue.mode === 'apply' && onAt === null)
             onAt = c.time;
@@ -96,7 +134,10 @@ export function findCueConflicts(seq, clips, getAction) {
     for (const sc of schedule.cues) {
         if (sc.cue.mode !== 'apply')
             continue;
-        const action = getAction(sc.cue.actionId);
+        const cmd = cueCommand(sc.cue);
+        if (cmd?.kind !== 'action')
+            continue;
+        const action = getAction(cmd.ref);
         if (!action?.targets?.length)
             continue;
         const entries = schedule.entries.filter(e => e.stepIndex === sc.stepIndex);
@@ -114,8 +155,13 @@ export function findCueConflicts(seq, clips, getAction) {
     }
     return out;
 }
-export function newCue(actionId, stepId, at, mode = 'apply') {
-    return { id: uid('cue'), actionId, stepId, at: Math.max(0, at), mode };
+/** A sequence cue at `at` seconds into a step. */
+export function newCue(command, stepId, at, mode = 'apply') {
+    return { id: uid('cue'), command, stepId, at: Math.max(0, at), mode };
+}
+/** A clip cue at `at` seconds. */
+export function newClipCue(command, at, mode = 'apply') {
+    return { id: uid('cue'), command, at: Math.max(0, at), mode };
 }
 /** Clip-local time (seconds, 0..clip.duration) of an entry at sequence time T. */
 export function entryLocalTime(entry, T) {

package/dist/animationsV2/types.d.ts

@@ -1,4 +1,5 @@
 /** Easing of the segment leaving a key. Names match core's easingUtils, plus 'step'. */
+import type { SceneCommand } from '@3driseai/3drise-core';
 export type EaseName = 'linear' | 'step' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeOutElastic' | 'easeOutBounce';
 export type KeyValue = number | number[] | string | boolean;
 export interface Keyframe {
@@ -41,6 +42,8 @@ export interface AnimationClip {
     /** When a non-looping clip finishes: keep the last values, or return to authored. */
     endMode: 'hold' | 'restore';
     tracks: Track[];
+    /** Effects, effect clips and actions switched / fired along the clip (TimelineCue). */
+    cues?: TimelineCue[];
     /** Unsaved changes (save bookkeeping, never sent). */
     isDirty?: boolean;
 }
@@ -60,22 +63,29 @@ export interface SequenceStep {
     clips: StepClip[];
 }
 /**
- * An action switched at a moment of the sequence. Anchored to a step (not absolute
- * time), so retiming clips or reordering steps keeps it on the moment it was put on.
+ * Something switched or fired at a moment of a timeline (a clip, or a sequence step).
+ * `command` is what it acts on: an effect, an effect clip or an action — a timeline
+ * can't start a timeline (triggers engine). All cues on one subject (same action, same
+ * effect clip use, same effect) form one lane.
  *
- * Cues are STATE, not events: at sequence time T an action is on when its last cue
- * at or before T is 'apply' (off when 'revert', or when it has no cue yet). So
- * scrubbing, reverse, yoyo, loop and input drivers all land on the same scene.
+ *   'apply' / 'revert'  STATE: at time T the subject is on when its last cue at or before T
+ *                       is 'apply' — scrubbing, reverse, yoyo, loop and input drivers all land
+ *                       on the same scene.
+ *   'fire'              EVENT (one-shot effects): fires once when the playhead moves FORWARD
+ *                       across it; nothing on a backward crossing; jumps (seek, play from the
+ *                       start) never fire what they skip.
  */
-export interface SequenceCue {
+export interface TimelineCue {
     id: string;
-    /** ActionSequence id. */
-    actionId: string;
+    command: SceneCommand;
+    mode: 'apply' | 'revert' | 'fire';
+    /** Seconds: from the clip start, or into its step (sequences). */
+    at: number;
+}
+/** A cue anchored to a step, so retiming clips or reordering steps keeps it on its moment. */
+export interface SequenceCue extends TimelineCue {
     /** Step it is anchored to. */
     stepId: string;
-    /** Seconds after that step starts (>= 0). */
-    at: number;
-    mode: 'apply' | 'revert';
 }
 /** What moves a sequence's clock: time (it plays), or an input that scrubs it. */
 export type SequenceDriver = 'time' | 'mouseWheel' | 'mouseX' | 'mouseY';
@@ -95,7 +105,7 @@ export interface AnimationSequence {
     description?: string;
     /** Run in order. */
     steps: SequenceStep[];
-    /** Actions switched on / off along the sequence. */
+    /** Effects, effect clips and actions switched / fired along the sequence. */
     cues: SequenceCue[];
     /** Whole-sequence playback. */
     loop: boolean;

package/dist/animationsV2/types.d.ts.map

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

package/dist/api/sceneHandle.d.ts

@@ -1,4 +1,5 @@
-import type { ActionSequence } from '@3driseai/3drise-core';
+import type { ActionSequence, SceneCommand } from '@3driseai/3drise-core';
+import { type RunCommandResult } from '../triggers';
 import type { AnimationClip, AnimationSequence } from '../animationsV2/types';
 export interface SceneActionInfo {
     id: string;
@@ -56,6 +57,25 @@ export interface ScenePlayback<Info> {
     seek(ref: string, progress: number): boolean;
     isPlaying(ref: string): boolean;
 }
+/** A value a control can write: a number, a switch, a string (colour `#rrggbb`, a choice) or a vector. */
+export type SceneValue = number | boolean | string | number[];
+/** Write live properties of the scene — what a slider or colour picker does. */
+export interface SceneValues {
+    /**
+     * Write one property now. `target` is `sky` | `camera` | `clouds` | `ocean` | `terrain`, or an
+     * object ref (key, id or exact name), with `/NodeName` to address a part of a model. `path` is a
+     * settings path as clip tracks use it (`materialSettings.opacity`, `meshSettings.position.y`,
+     * `config.intensity`, `sky:elevation`; for a model node: `position`, `rotation.y`, `material.color`).
+     * A `.x` / `.y` / `.z` suffix writes one component of a vector. Nothing is saved: this is the
+     * live scene, like an animation frame, and a page reload puts it back. False when the target or
+     * path is not writable (see `check`).
+     */
+    set(target: string, path: string, value: SceneValue): boolean;
+    /** The value now: what was last written, else the authored value (action patches included). */
+    get(target: string, path: string): SceneValue | undefined;
+    /** Why `set` would fail, or undefined when it can write this path. */
+    check(target: string, path: string): string | undefined;
+}
 export type SceneHandleEventType = 'actionApplied' | 'actionReverted' | 'animationStart' | 'animationEnd' | 'animationLoop';
 export interface SceneHandleEvent {
     type: SceneHandleEventType;
@@ -86,13 +106,27 @@ export interface SceneHandle {
         /** Current position, 0–1 along its own direction. */
         getProgress(ref: string): number;
     };
+    /** Live property writes (sliders, colour pickers). */
+    values: SceneValues;
     /** Subscribe to this project's action / clip / sequence events. Returns the unsubscribe. */
     on(type: SceneHandleEventType, listener: (event: SceneHandleEvent) => void): () => void;
+    /**
+     * Run any command — the same shape interactions, actions and cues store (core SceneCommand):
+     * `{ id, kind: 'effect' | 'effectClip' | 'action' | 'animationClip' | 'animationSequence', … }`.
+     * Goes through the triggers engine like everything else (queued until the scene is ready).
+     */
+    run(command: SceneCommand): RunCommandResult;
 }
 export interface SceneHandleSource {
     actions: ActionSequence[];
     clips: AnimationClip[];
     sequences: AnimationSequence[];
+    /** The project's objects, to resolve a `values` target by key, id or name. */
+    objects?: Array<{
+        id: string;
+        name?: string;
+        key?: string;
+    }>;
 }
 /**
  * Build a handle over one project's actions, clips and sequences. `getSource` is

package/dist/api/sceneHandle.d.ts.map

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

package/dist/api/sceneHandle.js

@@ -20,6 +20,7 @@
 //
 import { SceneActions } from '@3driseai/3drise-core';
 import ClipsRuntime from '../animationsV2/ClipsRuntime.js';
+import { runCommand } from '../triggers/index.js';
 import { clipMap, resolveSequence } from '../animationsV2/sequenceUtils.js';
 function resolve(items, ref, kind) {
     if (!ref)
@@ -53,6 +54,14 @@ export function createSceneHandle(getSource) {
     const findClip = (ref) => resolve(clips(), ref, 'clip');
     const findSequence = (ref) => resolve(sequences(), ref, 'sequence');
     const sequenceDuration = (s) => resolveSequence(s, clipsById()).duration;
+    // Triggers go through the engine (queued until the scene is ready), with code as their source.
+    const catalog = {
+        action: (id) => actions().find(a => a.id === id),
+        clip: (id) => clips().find(c => c.id === id),
+        sequence: (id) => sequences().find(s => s.id === id),
+        clips: () => clipsById(),
+    };
+    const code = (item) => ({ source: { host: 'code', id: item.key || item.id }, chain: [], catalog });
     const clipControls = {
         list: () => clips().map(c => ({
             id: c.id, key: c.key, name: c.name, description: c.description,
@@ -63,18 +72,18 @@ export function createSceneHandle(getSource) {
             const c = findClip(ref);
             if (!c)
                 return false;
-            ClipsRuntime.play(c, {
-                speed: options.speed,
-                reverse: options.reverse,
-                from: options.from !== undefined ? clamp01(options.from) * c.duration : undefined,
-            });
+            runCommand({ id: `code:${c.id}`, kind: 'animationClip', ref: c.id, command: 'play', options: {
+                    speed: options.speed,
+                    reverse: options.reverse,
+                    from: options.from !== undefined ? clamp01(options.from) * c.duration : undefined,
+                } }, code(c));
             return true;
         },
         pause(ref) {
             const c = findClip(ref);
             if (!c)
                 return false;
-            ClipsRuntime.pause(c.id);
+            runCommand({ id: `code:${c.id}`, kind: 'animationClip', ref: c.id, command: 'pause' }, code(c));
             return true;
         },
         resume(ref) {
@@ -88,7 +97,7 @@ export function createSceneHandle(getSource) {
             const c = findClip(ref);
             if (!c)
                 return false;
-            ClipsRuntime.stop(c.id);
+            runCommand({ id: `code:${c.id}`, kind: 'animationClip', ref: c.id, command: 'stop' }, code(c));
             return true;
         },
         seek(ref, progress) {
@@ -115,18 +124,18 @@ export function createSceneHandle(getSource) {
             const s = findSequence(ref);
             if (!s)
                 return false;
-            ClipsRuntime.playSequence(s, clipsById(), {
-                speed: options.speed,
-                reverse: options.reverse,
-                from: options.from !== undefined ? clamp01(options.from) * sequenceDuration(s) : undefined,
-            });
+            runCommand({ id: `code:${s.id}`, kind: 'animationSequence', ref: s.id, command: 'play', options: {
+                    speed: options.speed,
+                    reverse: options.reverse,
+                    from: options.from !== undefined ? clamp01(options.from) * sequenceDuration(s) : undefined,
+                } }, code(s));
             return true;
         },
         pause(ref) {
             const s = findSequence(ref);
             if (!s)
                 return false;
-            ClipsRuntime.pauseSequence(s.id);
+            runCommand({ id: `code:${s.id}`, kind: 'animationSequence', ref: s.id, command: 'pause' }, code(s));
             return true;
         },
         resume(ref) {
@@ -140,7 +149,7 @@ export function createSceneHandle(getSource) {
             const s = findSequence(ref);
             if (!s)
                 return false;
-            ClipsRuntime.stopSequence(s.id);
+            runCommand({ id: `code:${s.id}`, kind: 'animationSequence', ref: s.id, command: 'stop' }, code(s));
             return true;
         },
         seek(ref, progress) {
@@ -172,7 +181,65 @@ export function createSceneHandle(getSource) {
             return s ? ClipsRuntime.getSequenceProgress(s.id) : 0;
         },
     };
+    // ----- values ----------------------------------------------------------------------
+    const ENVIRONMENT = ['camera', 'sky', 'clouds', 'ocean', 'terrain'];
+    const COMPONENT = { x: 0, y: 1, z: 2 };
+    /** `engine/Door` -> { state: <object id>, node: 'Door' }; quiet when it is unknown (this runs on a poll). */
+    function target(ref) {
+        const slash = ref.indexOf('/');
+        const base = slash < 0 ? ref : ref.slice(0, slash);
+        const node = slash < 0 ? undefined : ref.slice(slash + 1);
+        if (ENVIRONMENT.includes(base))
+            return node ? undefined : { state: base };
+        const list = getSource().objects ?? [];
+        const o = list.find(i => i.key === base) ?? list.find(i => i.id === base) ?? list.find(i => i.name === base);
+        return o ? { state: o.id, node } : undefined;
+    }
+    /** `meshSettings.position.y` -> the vector's path and the component, when the value there is a vector. */
+    function component(state, node, path) {
+        const m = /^(.*)\.([xyz])$/.exec(path);
+        if (!m)
+            return undefined;
+        const current = ClipsRuntime.getLiveValue(state, m[1], node);
+        return Array.isArray(current) ? { base: m[1], index: COMPONENT[m[2]] } : undefined;
+    }
+    const values = {
+        check(ref, path) {
+            const t = target(ref);
+            if (!t)
+                return `no target "${ref}". Use sky, camera, clouds, ocean, terrain or an object${ref.includes('/') ? ' (and sky/camera/… take no node)' : ''}.`;
+            const c = t.node ? undefined : component(t.state, t.node, path);
+            if (!t.node && !ClipsRuntime.canSetLiveValue(t.state, c ? c.base : path))
+                return `"${path}" cannot be written live on ${ref}.`;
+            return undefined;
+        },
+        set(ref, path, value) {
+            const t = target(ref);
+            if (!t)
+                return false;
+            const c = component(t.state, t.node, path);
+            if (c) {
+                const current = ClipsRuntime.getLiveValue(t.state, c.base, t.node);
+                if (typeof value !== 'number')
+                    return false;
+                const next = current.slice();
+                next[c.index] = value;
+                return ClipsRuntime.setLiveValue(t.state, c.base, next, t.node);
+            }
+            return ClipsRuntime.setLiveValue(t.state, path, value, t.node);
+        },
+        get(ref, path) {
+            const t = target(ref);
+            if (!t)
+                return undefined;
+            const c = component(t.state, t.node, path);
+            if (c)
+                return ClipsRuntime.getLiveValue(t.state, c.base, t.node)[c.index];
+            return ClipsRuntime.getLiveValue(t.state, path, t.node);
+        },
+    };
     return {
+        values,
         actions: {
             list: () => actions().map(a => ({
                 id: a.id,
@@ -185,19 +252,22 @@ export function createSceneHandle(getSource) {
                 const a = findAction(ref);
                 if (!a)
                     return false;
-                SceneActions.applyAction(a);
+                runCommand({ id: `code:${a.id}`, kind: 'action', ref: a.id, command: 'apply' }, code(a));
                 return true;
             },
             revert(ref) {
                 const a = findAction(ref);
                 if (!a)
                     return false;
-                SceneActions.revertAction(a);
+                runCommand({ id: `code:${a.id}`, kind: 'action', ref: a.id, command: 'revert' }, code(a));
                 return true;
             },
             toggle(ref) {
                 const a = findAction(ref);
-                return a ? SceneActions.toggleAction(a) : false;
+                if (!a)
+                    return false;
+                runCommand({ id: `code:${a.id}`, kind: 'action', ref: a.id, command: 'toggle' }, code(a));
+                return SceneActions.isActionApplied(a.id);
             },
             isApplied(ref) {
                 const a = findAction(ref);
@@ -211,6 +281,7 @@ export function createSceneHandle(getSource) {
         },
         clips: clipControls,
         sequences: sequenceControls,
+        run: (command) => runCommand(command, { source: { host: 'code', id: 'run' }, chain: [], catalog }),
         on(type, listener) {
             if (type === 'actionApplied' || type === 'actionReverted') {
                 return SceneActions.onEvent((e) => {

package/dist/components/AdvancedGrid.d.ts

@@ -11,11 +11,7 @@ export interface AdvancedGridProps extends ObjectReadyProps {
     /** Pointer bindings on this grid's config knobs (mouseMove.grid). */
     mouseMove?: MouseMoveDomain;
 }
-/**
- * MyGridConfig — the single source of truth for a grid instance.
- * Colors are hex strings so they round-trip cleanly through the controller
- * and any preset/serialization layer.
- */
+/** MyGridConfig defaults: the core registry entry (DEFAULT_GRIDS.advancedGrid), never a copy. */
 export declare const defaultMyGridConfig: MyGridConfig;
 export declare function AdvancedGrid({ config, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }: AdvancedGridProps): import("react").JSX.Element;
 export default AdvancedGrid;

package/dist/components/AdvancedGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AdvancedGrid.d.ts","sourceRoot":"","sources":["../../src/components/AdvancedGrid.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE7F,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACvD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAKD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAyBjC,CAAC;AAWF,wBAAgB,YAAY,CAAC,EAAE,MAA4B,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,iBAAiB,+BA+CrJ;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"AdvancedGrid.d.ts","sourceRoot":"","sources":["../../src/components/AdvancedGrid.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE7F,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACvD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAKD,iGAAiG;AACjG,eAAO,MAAM,mBAAmB,EAA4C,YAAY,CAAC;AAWzF,wBAAgB,YAAY,CAAC,EAAE,MAA4B,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,iBAAiB,+BA+CrJ;AAED,eAAe,YAAY,CAAC"}