@3driseai/3drise-viewer 0.1.28 → 0.1.30

package/dist/operations/groupFanout.d.ts

@@ -0,0 +1,96 @@
+import { type Object3D } from 'three';
+import type { EffectSpread, EffectStep, ObjectEffect } from '@3driseai/3drise-core';
+/** A row of a group's clip that goes to the children: a visual effect, or a physical one scoped 'each'. */
+export declare const isFanRow: (e: Pick<ObjectEffect, "operation" | "scope">) => boolean;
+/** An effect clip as the fan-out hands it to a child (the controller's EffectClipData). */
+export interface FanClip {
+    effects?: ObjectEffect[];
+    steps?: EffectStep[];
+    loop?: boolean;
+    yoyo?: boolean;
+}
+/** The part of a child's controller the fan-out uses. */
+export interface FanTarget {
+    addEffect(key: string, effect: Pick<ObjectEffect, 'operation' | 'params' | 'playback' | 'meshNames'>, opts?: {
+        instant?: boolean;
+        follows?: boolean;
+    }): boolean;
+    removeEffect(key: string): boolean;
+    applyClip(key: string, clip: FanClip): boolean;
+    removeClip(key: string): boolean;
+    fanLeave(keys: string[]): Promise<unknown>;
+    fanPark(keys: string[]): void;
+    fanEnter(keys: string[]): Promise<unknown>;
+}
+export declare class GroupFanout {
+    private root;
+    /** A child's controller; `create` makes one for a child that has no effects of its own. */
+    private controllerOf;
+    /** What is handed out now, by item id (own rows: their id; triggered rows: `t:<key>`; clips: `c:<key>`). */
+    private items;
+    private children;
+    private childKey;
+    private spread;
+    /** The group's own clip follows its visibility: its rows reach the children as following it too. */
+    private follows;
+    /** Pending gives / takes: `${itemId}|${childId}` → timer. */
+    private timers;
+    /** Pending visibility turns: childId → timer (and the leave promise to settle if called off). */
+    private vis;
+    constructor(root: Object3D, 
+    /** A child's controller; `create` makes one for a child that has no effects of its own. */
+    controllerOf: (root: Object3D, create: boolean) => FanTarget | undefined);
+    private get groupId();
+    private key;
+    private rowFits;
+    private fits;
+    /** Milliseconds before child `c` gets (or, `out`, loses) its turn among `reach` (the children concerned). */
+    private turn;
+    private delay;
+    private cancel;
+    private schedule;
+    /** Run every pending give / take now (the group is being hidden: the children must be in their final state). */
+    private flush;
+    /** Hand an item (as it is when the delay ends) to a child. */
+    private give;
+    private take;
+    /** Hand out a new item: each child it reaches after its delay. */
+    private putOn;
+    /** Take an item off: each child after its out delay (`inOrder`: a handover — in the in order). */
+    private takeOff;
+    /** The leaf scene objects under the group, in the spread's order. */
+    private collect;
+    /**
+     * The group's own fan rows now (its clip's visual rows and physical 'each' rows, Base and steps).
+     *   instant  scene load: everything lands at once, no cascade.
+     *   follows  the group's clip follows visibility.
+     */
+    sync(rows: ObjectEffect[], spread: EffectSpread | null | undefined, mode: 'animate' | 'instant', follows?: boolean): void;
+    addTriggered(key: string, effect: Pick<ObjectEffect, 'operation' | 'params' | 'playback'>): boolean;
+    removeTriggered(key: string): boolean;
+    hasTriggered(key: string): boolean;
+    applyClip(key: string, clip: FanClip): boolean;
+    removeClip(key: string): boolean;
+    hasClip(key: string): boolean;
+    /** The children that hold the group's own rows, and the keys of those rows on each. */
+    private holders;
+    private cancelVis;
+    /** The group is being hidden: each child plays the group's effects out on its turn. Resolves when the last has gone. */
+    leave(): Promise<unknown>;
+    /** The group is about to be shown: every child holding its effects starts from nothing. */
+    park(): void;
+    /** The group is drawn: each child gets ready and plays the group's effects in, on its turn. */
+    enter(): void;
+    /**
+     * Children joined or left (checked every few frames, and on each change). `quiet` on the first look.
+     * A child that joins gets what is on at once; one that leaves loses it at once.
+     */
+    check(quiet?: boolean): void;
+    /** Some child is still waiting for one of these items (a cascade is running). */
+    pending(itemIds: string[]): boolean;
+    /** Take everything off the children at once (the group is going away, or is no longer a group). */
+    dispose(): void;
+    /** Ids of the children now, in cascade order (tests / studio). */
+    get childIds(): string[];
+}
+//# sourceMappingURL=groupFanout.d.ts.map

package/dist/operations/groupFanout.d.ts.map

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

package/dist/operations/groupFanout.js

@@ -0,0 +1,365 @@
+// =============================================================================
+// GroupFanout — a group's effects reach its children (see claude/group-effects-plan.md).
+// =============================================================================
+//
+// A group never draws an effect itself. Its visual effects, and its physical effects scoped
+// 'each', are handed to each child's own effects controller as ADDED effects (`addEffect`,
+// the path interactions and actions use) — so the child's rule applies unchanged: the added
+// effect wins on what it touches, the child's own effects carry on with the rest and come
+// back afterwards. Physical effects scoped 'group' (the default) stay on the group root and
+// move the whole group as one piece; they never come here.
+//
+//   children  the leaf scene objects under the group (object roots that are not groups,
+//             through nested groups). Visual effects go only to children that take them
+//             (userData.visualFx); physical 'each' effects go to every leaf.
+//   spread    the stagger: `order` (tree · x · y · z · radial · random, seeded by the group id),
+//             `total` (seconds from the first child to the last — a fixed total, so 3 or 40
+//             children take the same time; 0 = together), `out` (reverse: last in, first out).
+//             Each effect is ranked among the children it reaches (no gaps for the others).
+//   on / off  each child after its delay; switched on again while its out cascade runs, the
+//             pending removals are called off (each child turns round where it is).
+//   steps     a step change hands over child by child in the in order (old off, new on at the
+//             same moment, the new one first: on each child the incoming take-over sweeps over
+//             the outgoing one).
+//   edits     a changed parameter lands on every child at once (no cascade).
+//   join      a child that joins the group gets the effects that are on at once; one that
+//             leaves has them taken off at once.
+//   visible   the group's clip follows visibility: hidden → each child plays the group's effects
+//             out (its turn in the out order) and is no longer drawn; the group goes after the
+//             last. Shown → the children start from nothing and play them in one after another.
+//   triggered an effect or a saved clip triggered on the group (interaction, action, cue) goes to
+//             the children the same way (`addTriggered` / `applyClip`); it never follows visibility.
+//
+import { Box3, Matrix4, Vector3 } from 'three';
+import { DEFAULT_EFFECT_SPREAD } from '@3driseai/3drise-core';
+import { getOperation } from './registry.js';
+import { mulberry32 } from './catalogue/surfaceSample.js';
+/** A row of a group's clip that goes to the children: a visual effect, or a physical one scoped 'each'. */
+export const isFanRow = (e) => getOperation(e.operation)?.channel !== 'transform' || e.scope === 'each';
+const hash = (s) => { let h = 2166136261; for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+} return h >>> 0; };
+const rowSig = (e) => JSON.stringify([e.operation, e.params ?? null, e.playback ?? null]);
+const clipRows = (c) => [...(c.effects ?? []), ...(c.steps ?? []).flatMap(s => s.effects ?? [])].filter(Boolean);
+export class GroupFanout {
+    root;
+    controllerOf;
+    /** What is handed out now, by item id (own rows: their id; triggered rows: `t:<key>`; clips: `c:<key>`). */
+    items = new Map();
+    children = [];
+    childKey = '';
+    spread = DEFAULT_EFFECT_SPREAD;
+    /** The group's own clip follows its visibility: its rows reach the children as following it too. */
+    follows = false;
+    /** Pending gives / takes: `${itemId}|${childId}` → timer. */
+    timers = new Map();
+    /** Pending visibility turns: childId → timer (and the leave promise to settle if called off). */
+    vis = new Map();
+    constructor(root, 
+    /** A child's controller; `create` makes one for a child that has no effects of its own. */
+    controllerOf) {
+        this.root = root;
+        this.controllerOf = controllerOf;
+    }
+    get groupId() { return String(this.root.userData?.id ?? this.root.uuid); }
+    key(itemId) { return `grp:${this.groupId}:${itemId}`; }
+    rowFits(row, c) { return c.visual || getOperation(row.operation)?.channel === 'transform'; }
+    fits(item, c) { return item.kind === 'row' ? this.rowFits(item.row, c) : clipRows(item.clip).some(r => this.rowFits(r, c)); }
+    /** Milliseconds before child `c` gets (or, `out`, loses) its turn among `reach` (the children concerned). */
+    turn(reach, c, out) {
+        const n = reach.length, total = Number(this.spread.total);
+        const rank = reach.indexOf(c);
+        if (n < 2 || rank < 0 || !(total > 0))
+            return 0;
+        const r = out && this.spread.out === 'reverse' ? n - 1 - rank : rank;
+        return (total * 1000 * r) / (n - 1);
+    }
+    delay(item, c, out) { return this.turn(this.children.filter(x => this.fits(item, x)), c, out); }
+    cancel(itemId, childId) {
+        const k = `${itemId}|${childId}`;
+        const t = this.timers.get(k);
+        if (t) {
+            clearTimeout(t.t);
+            this.timers.delete(k);
+        }
+    }
+    schedule(itemId, c, ms, fn) {
+        this.cancel(itemId, c.id);
+        if (ms <= 0) {
+            fn();
+            return;
+        }
+        const k = `${itemId}|${c.id}`;
+        this.timers.set(k, { t: setTimeout(() => { this.timers.delete(k); fn(); }, ms), fn });
+    }
+    /** Run every pending give / take now (the group is being hidden: the children must be in their final state). */
+    flush() {
+        const pending = [...this.timers.entries()];
+        this.timers.clear();
+        for (const [, p] of pending) {
+            clearTimeout(p.t);
+            p.fn();
+        }
+    }
+    /** Hand an item (as it is when the delay ends) to a child. */
+    give(itemId, c, instant = false) {
+        const item = this.items.get(itemId);
+        if (!item || !this.fits(item, c))
+            return;
+        const ctl = this.controllerOf(c.root, true);
+        if (!ctl)
+            return;
+        if (item.kind === 'row') {
+            const { operation, params, playback } = item.row;
+            ctl.addEffect(this.key(itemId), { operation, params, playback }, { instant, follows: item.own && this.follows });
+        }
+        else {
+            // only what this child can take
+            const keep = (e) => !!e && this.rowFits(e, c);
+            const steps = (item.clip.steps ?? []).map(s => ({ ...s, effects: (s.effects ?? []).filter(keep) })).filter(s => s.effects.length);
+            ctl.applyClip(this.key(itemId), { ...item.clip, effects: (item.clip.effects ?? []).filter(keep), steps });
+        }
+    }
+    take(itemId, kind, c) {
+        const ctl = this.controllerOf(c.root, false);
+        if (!ctl)
+            return;
+        if (kind === 'row')
+            ctl.removeEffect(this.key(itemId));
+        else
+            ctl.removeClip(this.key(itemId));
+    }
+    /** Hand out a new item: each child it reaches after its delay. */
+    putOn(itemId, item, instant) {
+        this.items.set(itemId, item);
+        for (const c of this.children) {
+            if (this.fits(item, c))
+                this.schedule(itemId, c, instant ? 0 : this.delay(item, c, false), () => this.give(itemId, c, instant));
+            else
+                this.cancel(itemId, c.id);
+        }
+    }
+    /** Take an item off: each child after its out delay (`inOrder`: a handover — in the in order). */
+    takeOff(itemId, instant, inOrder = false) {
+        const item = this.items.get(itemId);
+        if (!item)
+            return false;
+        this.items.delete(itemId);
+        for (const c of this.children)
+            this.schedule(itemId, c, instant ? 0 : this.delay(item, c, !inOrder), () => this.take(itemId, item.kind, c));
+        return true;
+    }
+    /** The leaf scene objects under the group, in the spread's order. */
+    collect() {
+        const out = [];
+        this.root.traverse(o => {
+            if (o === this.root)
+                return;
+            const ud = o.userData;
+            if (!ud?.id || !ud.objectType || ud.objectType === 'group')
+                return;
+            out.push({ id: String(ud.id), root: o, visual: !!ud.visualFx });
+        });
+        const order = this.spread.order;
+        if (order !== 'tree' && out.length > 1) {
+            if (order === 'random') {
+                const rnd = mulberry32(hash(this.groupId));
+                const keyed = out.map(c => ({ c, k: rnd() }));
+                keyed.sort((a, b) => a.k - b.k);
+                out.splice(0, out.length, ...keyed.map(x => x.c));
+            }
+            else {
+                this.root.updateWorldMatrix(true, true);
+                const inv = new Matrix4().copy(this.root.matrixWorld).invert();
+                const box = new Box3();
+                const centre = (o) => {
+                    box.setFromObject(o);
+                    const v = box.isEmpty() ? o.getWorldPosition(new Vector3()) : box.getCenter(new Vector3());
+                    return v.applyMatrix4(inv);
+                };
+                const at = new Map(out.map(c => [c, centre(c.root)]));
+                if (order === 'radial') {
+                    const mid = new Vector3();
+                    at.forEach(v => mid.add(v));
+                    mid.divideScalar(at.size);
+                    out.sort((a, b) => at.get(a).distanceTo(mid) - at.get(b).distanceTo(mid));
+                }
+                else {
+                    out.sort((a, b) => at.get(a)[order] - at.get(b)[order]);
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * The group's own fan rows now (its clip's visual rows and physical 'each' rows, Base and steps).
+     *   instant  scene load: everything lands at once, no cascade.
+     *   follows  the group's clip follows visibility.
+     */
+    sync(rows, spread, mode, follows = false) {
+        this.spread = { ...DEFAULT_EFFECT_SPREAD, ...(spread ?? {}) };
+        this.check(true);
+        const instant = mode === 'instant';
+        if (follows !== this.follows) {
+            // following visibility or not makes the children's copies other effects: hand them out again
+            this.follows = follows;
+            for (const [id, item] of this.items)
+                if (item.kind === 'row' && item.own)
+                    for (const c of this.children)
+                        if (!this.timers.has(`${id}|${c.id}`))
+                            this.give(id, c, true);
+        }
+        const next = new Map(rows.filter(r => r?.enabled && getOperation(r.operation)).map(r => [r.id, r]));
+        const own = [...this.items].filter(([, i]) => i.kind === 'row' && i.own);
+        const handover = [...next.keys()].some(id => !this.items.has(id));
+        for (const [id, row] of next) {
+            const cur = this.items.get(id);
+            if (!cur || cur.kind !== 'row') {
+                this.putOn(id, { kind: 'row', row, own: true }, instant);
+                continue;
+            }
+            this.items.set(id, { kind: 'row', row, own: true });
+            // an edit lands at once on every child that has it; one still waiting gets the new values when its turn comes
+            if (rowSig(cur.row) !== rowSig(row))
+                for (const c of this.children)
+                    if (!this.timers.has(`${id}|${c.id}`))
+                        this.give(id, c, true);
+        }
+        // switched off / removed: each child loses it after its out delay — but when other rows come on in the
+        // same sync (a step handing over), in the IN order, so each child swaps at its moment — and AFTER the
+        // incoming one is given (same delay, scheduled first), so the incoming take-over sweeps over the outgoing one
+        for (const [id] of own)
+            if (!next.has(id))
+                this.takeOff(id, instant, handover);
+    }
+    // ---- triggered on the group (interactions, actions, cues) ----
+    addTriggered(key, effect) {
+        this.check(true);
+        const id = `t:${key}`;
+        const row = { id, operation: effect.operation, enabled: true, params: effect.params, playback: effect.playback };
+        const cur = this.items.get(id);
+        if (cur?.kind === 'row' && rowSig(cur.row) === rowSig(row) && !getOperation(row.operation)?.revert) {
+            // a one-shot triggered again plays again, child by child
+            this.putOn(id, { kind: 'row', row, own: false }, false);
+            return true;
+        }
+        if (cur?.kind === 'row') {
+            this.items.set(id, { kind: 'row', row, own: false });
+            for (const c of this.children)
+                if (!this.timers.has(`${id}|${c.id}`))
+                    this.give(id, c, true);
+            return true;
+        }
+        this.putOn(id, { kind: 'row', row, own: false }, false);
+        return true;
+    }
+    removeTriggered(key) { return this.takeOff(`t:${key}`, false); }
+    hasTriggered(key) { return this.items.has(`t:${key}`); }
+    applyClip(key, clip) {
+        this.check(true);
+        const id = `c:${key}`;
+        if (this.items.has(id))
+            return true;
+        this.putOn(id, { kind: 'clip', clip }, false);
+        return true;
+    }
+    removeClip(key) { return this.takeOff(`c:${key}`, false); }
+    hasClip(key) { return this.items.has(`c:${key}`); }
+    // ---- the group's visibility (its clip follows it) ----
+    /** The children that hold the group's own rows, and the keys of those rows on each. */
+    holders() {
+        const own = [...this.items].filter(([, i]) => i.kind === 'row' && i.own);
+        return this.children.map(c => ({ c, keys: own.filter(([, i]) => this.fits(i, c)).map(([id]) => this.key(id)) })).filter(h => h.keys.length);
+    }
+    cancelVis() {
+        this.vis.forEach(v => { clearTimeout(v.t); v.done?.(); });
+        this.vis.clear();
+    }
+    /** The group is being hidden: each child plays the group's effects out on its turn. Resolves when the last has gone. */
+    leave() {
+        this.cancelVis();
+        this.flush();
+        const hs = this.holders();
+        const reach = hs.map(h => h.c);
+        return Promise.all(hs.map(({ c, keys }) => new Promise(resolve => {
+            const go = () => { this.vis.delete(c.id); void Promise.resolve(this.controllerOf(c.root, false)?.fanLeave(keys)).then(() => resolve(), () => resolve()); };
+            const ms = this.turn(reach, c, true);
+            if (ms <= 0) {
+                go();
+                return;
+            }
+            this.vis.set(c.id, { t: setTimeout(go, ms), done: resolve });
+        })));
+    }
+    /** The group is about to be shown: every child holding its effects starts from nothing. */
+    park() {
+        this.cancelVis();
+        this.flush();
+        for (const { c, keys } of this.holders())
+            this.controllerOf(c.root, false)?.fanPark(keys);
+    }
+    /** The group is drawn: each child gets ready and plays the group's effects in, on its turn. */
+    enter() {
+        this.cancelVis();
+        const hs = this.holders();
+        const reach = hs.map(h => h.c);
+        for (const { c, keys } of hs) {
+            const go = () => { this.vis.delete(c.id); void this.controllerOf(c.root, false)?.fanEnter(keys); };
+            const ms = this.turn(reach, c, false);
+            if (ms <= 0)
+                go();
+            else
+                this.vis.set(c.id, { t: setTimeout(go, ms) });
+        }
+    }
+    /**
+     * Children joined or left (checked every few frames, and on each change). `quiet` on the first look.
+     * A child that joins gets what is on at once; one that leaves loses it at once.
+     */
+    check(quiet = false) {
+        const list = this.collect();
+        const key = list.map(c => c.id).join('|');
+        if (key === this.childKey) {
+            this.children = list;
+            return;
+        }
+        const before = new Map(this.children.map(c => [c.id, c]));
+        const now = new Set(list.map(c => c.id));
+        if (!quiet || this.childKey) {
+            for (const [id, c] of before)
+                if (!now.has(id))
+                    for (const [itemId, item] of this.items) {
+                        this.cancel(itemId, id);
+                        this.take(itemId, item.kind, c);
+                    }
+            for (const c of list)
+                if (!before.has(c.id))
+                    for (const itemId of this.items.keys())
+                        this.give(itemId, c, true);
+        }
+        this.children = list;
+        this.childKey = key;
+    }
+    /** Some child is still waiting for one of these items (a cascade is running). */
+    pending(itemIds) {
+        for (const k of this.timers.keys())
+            if (itemIds.includes(k.slice(0, k.lastIndexOf('|'))))
+                return true;
+        return false;
+    }
+    /** Take everything off the children at once (the group is going away, or is no longer a group). */
+    dispose() {
+        this.timers.forEach(p => clearTimeout(p.t));
+        this.timers.clear();
+        this.cancelVis();
+        for (const [itemId, item] of this.items)
+            for (const c of this.children)
+                this.take(itemId, item.kind, c);
+        this.items.clear();
+        this.children = [];
+        this.childKey = '';
+    }
+    /** Ids of the children now, in cascade order (tests / studio). */
+    get childIds() { return this.children.map(c => c.id); }
+}

package/dist/operations/groups.d.ts

@@ -0,0 +1,20 @@
+import type { OperationChannel, OperationName } from '@3driseai/3drise-core';
+import type { OperationDefinition } from './types';
+export interface OperationGroup {
+    id: string;
+    channel: OperationChannel;
+    label: string;
+    /** One line under the group title in the gallery. */
+    description: string;
+    operations: OperationName[];
+}
+export declare const OPERATION_GROUPS: OperationGroup[];
+/**
+ * `ops` (one channel's operations, already filtered for the context) split into the
+ * gallery's groups, in gallery order. Empty groups are dropped; ungrouped ones go under "More".
+ */
+export declare function groupOperations(ops: OperationDefinition[]): Array<{
+    group: Omit<OperationGroup, 'operations'>;
+    operations: OperationDefinition[];
+}>;
+//# sourceMappingURL=groups.d.ts.map

package/dist/operations/groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../src/operations/groups.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,aAAa,EAAE,CAAC;CAC/B;AAED,eAAO,MAAM,gBAAgB,EAAE,cAAc,EA8C5C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;IAAC,UAAU,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC,CAYnJ"}

package/dist/operations/groups.js

@@ -0,0 +1,66 @@
+export const OPERATION_GROUPS = [
+    {
+        id: 'exits', channel: 'transform', label: 'Enter & exit',
+        description: 'Take the object out of the scene and bring it back',
+        operations: ['swirl', 'blastOff', 'vortexDrain', 'leafFall', 'pop', 'driftUp', 'slingshot', 'warp', 'knockAway', 'turnAway', 'flyBy', 'whoosh', 'slam'],
+    },
+    {
+        id: 'moves', channel: 'transform', label: 'Moves',
+        description: 'One move, then back to rest',
+        operations: ['jelly', 'flip', 'spin', 'grow', 'moveToFront'],
+    },
+    {
+        id: 'motion', channel: 'transform', label: 'Ongoing motion',
+        description: 'Keeps moving while it is on',
+        operations: ['float', 'sway', 'bounce', 'wobble', 'pulse', 'shake', 'rotate'],
+    },
+    {
+        id: 'transform-away', channel: 'visual', label: 'Transform away',
+        description: 'Turn the object into something else as it leaves',
+        operations: ['dissolve', 'emberAsh', 'shatter', 'sandErosion', 'curlSmoke', 'inkBloom', 'flock', 'liquidMetal', 'voxelize', 'unweave', 'petalPeel', 'particleSwarm', 'teleport', 'portal', 'hologram', 'lidarScan', 'print3d', 'silkDrape'],
+    },
+    {
+        id: 'surfaces', channel: 'visual', label: 'Surfaces',
+        description: 'Change what the object is made of',
+        operations: ['metalize', 'frost', 'petrify', 'heatCracks', 'kintsugi', 'rainBeads', 'ivy'],
+    },
+    {
+        id: 'light', channel: 'visual', label: 'Light',
+        description: 'Light the object up',
+        operations: ['glow', 'rimLight'],
+    },
+    {
+        id: 'trails', channel: 'visual', label: 'Trails',
+        description: 'Left behind wherever the object moves — add one to any physical effect; they combine',
+        operations: ['afterimageTrail', 'longExposureTrail', 'chromaticEchoTrail', 'streaksTrail', 'smokeTrail', 'ashTrail', 'sandTrail', 'hologramTrail', 'voxelTrail', 'shatterTrail', 'inkTrail', 'frostTrail', 'wireframeTrail', 'bubblesTrail'],
+    },
+    {
+        id: 'show-hide', channel: 'visual', label: 'Show & hide',
+        description: 'Plain fades, switches and images',
+        operations: ['fade', 'visibility', 'displayImage'],
+    },
+    {
+        id: 'camera', channel: 'camera', label: 'Camera moves',
+        description: 'Move or turn the camera to the target',
+        operations: ['zoom', 'frame', 'focus', 'orbit'],
+    },
+];
+/**
+ * `ops` (one channel's operations, already filtered for the context) split into the
+ * gallery's groups, in gallery order. Empty groups are dropped; ungrouped ones go under "More".
+ */
+export function groupOperations(ops) {
+    const byName = new Map(ops.map(o => [o.value, o]));
+    const seen = new Set();
+    const out = [];
+    for (const g of OPERATION_GROUPS) {
+        const list = g.operations.map(n => byName.get(n)).filter((o) => !!o);
+        list.forEach(o => seen.add(o.value));
+        if (list.length)
+            out.push({ group: { id: g.id, channel: g.channel, label: g.label, description: g.description }, operations: list });
+    }
+    const rest = ops.filter(o => !seen.has(o.value));
+    if (rest.length)
+        out.push({ group: { id: 'more', channel: rest[0].channel, label: 'More', description: '' }, operations: rest });
+    return out;
+}

package/dist/operations/index.d.ts

@@ -1,7 +1,10 @@
 export * from './types';
 export { OPERATIONS, getOperation, operationsFor, resolveParams, channelOf } from './registry';
-export { runEffect, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime';
+export { OPERATION_GROUPS, groupOperations, type OperationGroup } from './groups';
+export { runEffect, runEffectClip, setEffectClipTemplates, getEffectClipTemplate, effectClipFromAsset, EFFECT_CLIP_ASSET, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime';
 export { useOperationsRuntime } from './useOperationsRuntime';
-export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature } from './objectEffects';
+export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature, playObjectEffect, playbackOf, clipFollowsVisibility, setObjectEffectsVisible, currentEffectStep } from './objectEffects';
 export { useObjectEffectLayers } from './useObjectEffectLayers';
+export { usePresentedVisibility } from './usePresentedVisibility';
+export { captureFrameImage } from './clipPreview';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EACH,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,oBAAoB,EACtF,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,GACnJ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACzI,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAClF,OAAO,EACH,SAAS,EAAE,aAAa,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAC5L,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,GACnJ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1O,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/operations/index.js

@@ -1,6 +1,9 @@
 export * from './types.js';
 export { OPERATIONS, getOperation, operationsFor, resolveParams, channelOf } from './registry.js';
-export { runEffect, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime.js';
+export { OPERATION_GROUPS, groupOperations } from './groups.js';
+export { runEffect, runEffectClip, setEffectClipTemplates, getEffectClipTemplate, effectClipFromAsset, EFFECT_CLIP_ASSET, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime.js';
 export { useOperationsRuntime } from './useOperationsRuntime.js';
-export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature } from './objectEffects.js';
+export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature, playObjectEffect, playbackOf, clipFollowsVisibility, setObjectEffectsVisible, currentEffectStep } from './objectEffects.js';
 export { useObjectEffectLayers } from './useObjectEffectLayers.js';
+export { usePresentedVisibility } from './usePresentedVisibility.js';
+export { captureFrameImage } from './clipPreview.js';