@3driseai/3drise-viewer 0.1.28 → 0.1.29

package/dist/operations/objectEffects.js

@@ -1,8 +1,10 @@
 import { findNodesByName } from '@3driseai/3drise-core';
+import { GroupFanout, isFanRow } from './groupFanout.js';
 import { getOperation, resolveParams } from './registry.js';
-import { applyOperation, forceRevert, runOf } from './runtime.js';
-/** An operation can be an object effect. */
-export const isObjectOperation = (def) => !!def && def.usableIn.includes('object') && !!def.revert;
+import { applyOperation, forceRevert, registerAddedEffects, runOf, warmOperation } from './runtime.js';
+import { periodicEase } from './catalogue/physicalHeld.js';
+/** An operation can be an object effect (one-shots too: they have no way back, and play with loop). */
+export const isObjectOperation = (def) => !!def && def.usableIn.includes('object');
 /**
  * The effects that actually run: on, known, usable on objects, one per operation,
  * and one of each stack (the first wins).
@@ -27,17 +29,133 @@ export function runningObjectEffects(effects) {
     }
     return out;
 }
-/** An object effect's parameters: defaults, its overrides, then what object effects force. */
-export const objectEffectParams = (def, effect) => ({ ...resolveParams(def, effect.params), ...(def.objectParams ?? {}) });
+export function effectPresence(def, effect, follows, inStep = false) {
+    if (!follows)
+        return 'decorate';
+    // a step's effect is a look that takes turns: only Base effects are entrances / exits
+    if (def.presence === 'vanish')
+        return inStep ? 'decorate' : 'vanish';
+    // Disappear is the user's choice: on, the effect takes the object away — an entrance and an exit
+    const spec = def.params?.disappear;
+    if (spec) {
+        const v = { ...(def.objectParams ?? {}), ...(effect.params ?? {}) }.disappear ?? spec.default;
+        if (v === true)
+            return inStep ? 'decorate' : 'vanish';
+    }
+    return def.presence === 'paint' ? 'paint' : 'decorate';
+}
+/** An object effect's parameters: the operation's defaults, the object defaults, then its own values. */
+export const objectEffectParams = (def, effect, follows = false, inStep = false) => ({
+    // an object effect starts from the operation's object defaults (objectParams: a hologram that stays),
+    // and the user's own values go on top — so `disappear` is theirs to switch on
+    ...resolveParams(def, { ...(def.objectParams ?? {}), ...(effect.params ?? {}) }),
+    // a take-over that follows visibility draws the object only where it has painted it
+    ...(effectPresence(def, effect, follows, inStep) === 'paint' ? { __reveal: true } : {}),
+});
+/** An effect's playback with the defaults filled in. */
+export const playbackOf = (effect) => ({
+    autoplay: effect.playback?.autoplay !== false,
+    reverse: !!effect.playback?.reverse,
+    loop: !!effect.playback?.loop,
+    yoyo: !!effect.playback?.yoyo,
+});
+const playbackKey = (pb) => `${+pb.autoplay}${+pb.reverse}${+pb.loop}${+pb.yoyo}`;
+/** What makes a row "another effect" when it changes: its playback, and how it follows visibility. */
+const rowKey = (def, e, follows, inStep) => playbackKey(playbackOf(e)) + (follows ? 'v' : '') + (def ? effectPresence(def, e, follows, inStep) : '');
+/** An object's effects controller; `create` makes one for an object that has no effects of its own yet. */
+export function objectEffectsControllerFor(root, create = false) {
+    return controllers.get(root) ?? (create ? new ObjectEffectsController(root) : undefined);
+}
+// effects added by interactions and actions are run by the object's controller (see runtime.runEffect)
+registerAddedEffects({
+    add: (root, key, effect) => !!objectEffectsControllerFor(root, true)?.addEffect(key, effect),
+    remove: (root, key) => !!controllers.get(root)?.removeEffect(key),
+    has: (root, key) => !!controllers.get(root)?.hasEffect(key),
+    applyClip: (root, key, clip, parts) => !!objectEffectsControllerFor(root, true)?.applyClip(key, clip, parts),
+    removeClip: (root, key) => !!controllers.get(root)?.removeClip(key),
+    hasClip: (root, key) => !!controllers.get(root)?.hasClip(key),
+});
+/** The step of an object's effect steps that is on now (-1: none) — for the editor. */
+export function currentEffectStep(root) {
+    return (root && controllers.get(root)?.step) ?? -1;
+}
+/** An object's own effect clip follows its visibility (`visible`) and has an effect that is on. */
+export const clipFollowsVisibility = (clip) => !!clip?.visible && (!!clip.effects?.some(e => e?.enabled) || !!clip.steps?.some(s => s?.effects?.some(e => e && e.enabled !== false)));
+/**
+ * The object was shown or hidden: its visibility effects play in, or play out.
+ * Returns a promise (null = nothing to wait for) that resolves
+ *   shown   when the effects are ready and the object is drawn (its entrance is starting)
+ *   hidden  when they have played out and the object is no longer drawn
+ * The controller sets the group's `visible` itself at those two moments.
+ */
+export function setObjectEffectsVisible(root, visible) {
+    return (root && controllers.get(root)?.setVisible(visible)) || null;
+}
+/** Plays in once and holds — what an object effect does with no playback set. */
+const isPlain = (pb) => !pb.reverse && !pb.loop && !pb.yoyo;
+/** The controller of each object that has effects, by its group — for playing an effect from outside. */
+const controllers = new WeakMap();
+/**
+ * Play one of an object's effects from its start, with its playback settings
+ * (the editor's ▶; an effect with autoplay off starts this way). False when the
+ * object or the effect is not there.
+ */
+export function playObjectEffect(root, effectId) {
+    return !!root && !!controllers.get(root)?.play(effectId);
+}
 const namesKey = (e) => (e.meshNames ?? []).join('|');
+const seconds = (v, fallback) => (Number.isFinite(Number(v)) && Number(v) >= 0 ? Number(v) : fallback);
+export const STEP_IN = 1;
+export const STEP_HOLD = 1;
+/** What makes a step sequence "another sequence" (it restarts): its structure and timing — not the effects' own values. */
+const stepsKeyOf = (cfg) => (cfg?.steps?.length
+    ? JSON.stringify([!!cfg.loop, !!cfg.yoyo, cfg.steps.map(s => [s.id, s.in, s.hold, !!s.playOut, (s.effects ?? []).map(e => [e.id, e.operation, e.enabled !== false, namesKey(e)])])])
+    : '');
+/** A step's effect as a row of the running list: a look takes the step's `in` as its duration, a motion runs while the step is on. */
+function stepRow(step, e, on, prefix = '', parts) {
+    const def = getOperation(e.operation);
+    const look = !!def?.revert && !def.periodic;
+    return {
+        id: `${prefix}${step.id}:${e.id}`, operation: e.operation, enabled: on && e.enabled !== false, meshNames: parts?.length ? parts : e.meshNames,
+        params: look ? { ...(e.params ?? {}), duration: seconds(step.in, STEP_IN) } : e.params,
+        ...(look ? {} : { playback: { loop: true } }),
+        ...(e.scope ? { scope: e.scope } : {}),
+    };
+}
 export class ObjectEffectsController {
     root;
     running = new Map(); // effect id →
+    /** Effects playing out (removed / switched off): their op → when they are gone. */
+    leaving = new Set();
     effects = [];
     refreshing = null;
     disposed = false;
+    /** The object is shown — visibility effects wait while it is not. */
+    shown = true;
+    /** The object is on screen: it stays drawn while its effects play out, and is not yet drawn while they get ready. */
+    drawn = true;
+    visRun = 0;
+    /** The object's own list (always on) and its steps; `effects` is what runs: the two laid together. */
+    own = { key: '', prefix: '', effects: [], cfg: null, stepsKey: '', index: 0, dir: 1, run: 0 };
+    /** Clips applied from outside (key → run), in the order they were applied. */
+    clips = new Map();
+    /** The object's own steps wait while an applied clip has steps. */
+    ownPaused = false;
+    /** Effects added by interactions / actions (key → row; disabled while it plays out). */
+    added = new Map();
+    /** The object's own rows (Base and steps) as last composed: id → it is a step's. */
+    ownRows = new Map();
+    /** A group: its visual effects and physical 'each' effects go to the children (see ./groupFanout.ts). */
+    fan = null;
+    spread = {};
+    /** Added effects that follow visibility: a group's effects on this child, when the group's follow it. */
+    addedFollows = new Set();
     constructor(root) {
         this.root = root;
+        controllers.set(root, this);
+        // a group never draws an effect itself: its visual / 'each' effects — its own, and those triggered on it — go to its children
+        if (root.userData?.objectType === 'group')
+            this.fan = new GroupFanout(root, (r, create) => objectEffectsControllerFor(r, create));
     }
     /** The object's targets for an effect: the object, or its named nodes. */
     targetsOf(e) {
@@ -53,11 +171,29 @@ export class ObjectEffectsController {
             applyOperation(def, t, params, this.root, { bare: true });
     }
     off(r, instant) {
+        if (r.cycle) {
+            r.cycle.cancelled = true;
+            r.cycle.wake?.();
+        }
+        r.cycle = undefined;
+        r.phase = undefined;
+        if (r.wipe) {
+            r.wipe.cancelled = true;
+            r.wipe = undefined;
+        }
         const def = getOperation(r.op);
-        if (!def)
+        if (!def || !r.started)
             return;
+        // a one-shot has no way back: at once = stop its move where it is and put the object back
+        if (!def.revert) {
+            if (instant)
+                for (const t of r.targets)
+                    def.cancel?.(t);
+            return;
+        }
         // with its own parameters — it may have gone on at once (load / edit), but goes off with its transition
-        const params = instant ? { ...r.params, duration: 0 } : r.params;
+        // (a take-over switched off on an object that stays: it gives the object back, it does not take it away)
+        const params = instant ? { ...r.params, duration: 0 } : r.kind === 'paint' ? { ...r.params, __reveal: false } : r.params;
         for (const t of r.targets)
             forceRevert(def, t, params);
     }
@@ -65,34 +201,955 @@ export class ObjectEffectsController {
      * Bring what runs in line with `effects`.
      *   animate  switching an effect on / off plays its transition (studio, actions)
      *   instant  everything lands in its end state at once (scene load)
-     * A changed parameter always lands at once.
+     * A changed parameter always lands at once. A row switched to another
+     * operation clears the old one at once, then plays the new one in from the
+     * original object.
      */
-    sync(effects, mode) {
+    sync(effects, mode, steps, parts, follows = false, group) {
         if (this.disposed)
             return;
+        // a group (`group` = its spread): the rows that go to the children are handed out by syncList
+        if (group) {
+            this.fan ??= new GroupFanout(this.root, (r, create) => objectEffectsControllerFor(r, create));
+            this.spread = group;
+        }
+        else if (this.fan && this.root.userData?.objectType !== 'group') {
+            this.fan.dispose();
+            this.fan = null;
+        }
+        const c = this.own;
+        c.effects = effects ?? [];
+        c.follows = follows;
+        c.parts = parts?.length ? parts : undefined;
+        const key = stepsKeyOf(steps);
+        c.cfg = key ? steps : null;
+        if (key !== c.stepsKey) { // another sequence: from its first step
+            c.stepsKey = key;
+            c.index = 0;
+            c.dir = 1;
+            if (!this.ownPaused)
+                this.scheduleStep(c);
+        }
+        this.syncList(this.compose(), mode);
+    }
+    /** A clip's rows: the step that is on, its always-on effects, and the steps that wait (listed, off). */
+    rowsOf(c) {
+        const on = [], waiting = [];
+        const stepsOn = !c.off && !(c === this.own && this.ownPaused);
+        c.cfg?.steps.forEach((s, i) => {
+            for (const e of s.effects ?? []) {
+                const row = stepRow(s, e, stepsOn && i === c.index, c.prefix, c.parts);
+                (row.enabled ? on : waiting).push(row);
+            }
+        });
+        const base = c.prefix || c.parts || c.off
+            ? c.effects.map(e => ({ ...e, id: `${c.prefix}${e.id}`, enabled: !!e.enabled && !c.off, ...(c.parts ? { meshNames: c.parts } : {}) }))
+            : c.effects;
+        if (c === this.own) {
+            this.ownRows = new Map();
+            for (const e of [...on, ...waiting])
+                this.ownRows.set(e.id, true);
+            for (const e of base)
+                this.ownRows.set(e.id, false);
+        }
+        return { on, base, waiting };
+    }
+    /** A row follows the object's visibility (one of its own, with `visible` on) · it is a step's. */
+    visOf(id) {
+        // a group's effect on this child, following the group's visibility (see fanLeave / fanEnter)
+        if (this.addedFollows.has(id))
+            return [true, false];
+        const inStep = this.ownRows.get(id);
+        return [!!this.own.follows && inStep !== undefined, !!inStep];
+    }
+    /**
+     * The running list, top first (the first of two that clash wins): added effects, applied clips
+     * (newest first; in each, the step that is on, then its always-on effects), the object's own clip,
+     * then everything that waits or is playing out.
+     */
+    compose() {
+        const own = this.rowsOf(this.own);
+        if (!this.added.size && !this.clips.size)
+            return own.on.length || own.waiting.length ? [...own.on, ...own.base, ...own.waiting] : own.base;
+        const top = [], rest = [];
+        for (const e of [...this.added.values()].reverse())
+            (e.enabled ? top : rest).push(e);
+        for (const c of [...this.clips.values()].reverse()) {
+            const r = this.rowsOf(c);
+            if (c.off)
+                rest.push(...r.on, ...r.base, ...r.waiting);
+            else {
+                top.push(...r.on, ...r.base);
+                rest.push(...r.waiting);
+            }
+        }
+        return [...top, ...own.on, ...own.base, ...own.waiting, ...rest];
+    }
+    /**
+     * Put an effect on the object on top of its own (an interaction, an action). `key` names it for
+     * removeEffect. Already on: a one-shot plays again, anything else is left as it is.
+     */
+    addEffect(key, effect, opts) {
+        const def = getOperation(effect.operation);
+        if (this.disposed || !isObjectOperation(def))
+            return false;
+        // a group: an effect triggered on it that goes to the children is handed out (staggered)
+        if (this.fan && isFanRow(effect))
+            return this.fan.addTriggered(key, effect);
+        const id = `+${key}`;
+        const follows = !!opts?.follows;
+        if (follows !== this.addedFollows.has(id)) {
+            if (follows)
+                this.addedFollows.add(id);
+            else
+                this.addedFollows.delete(id);
+            this.added.delete(key); // following visibility or not makes it another effect
+        }
+        const cur = this.added.get(key);
+        const { autoplay: _a, ...pb } = effect.playback ?? {};
+        // a motion added with no playback runs until it is reverted
+        const playback = Object.keys(pb).length ? pb : def.periodic ? { loop: true } : undefined;
+        const row = { id, operation: effect.operation, enabled: true, meshNames: effect.meshNames, params: effect.params, ...(playback ? { playback } : {}) };
+        if (cur?.enabled && cur.operation === effect.operation) {
+            // the same values: a one-shot plays again, anything else is left as it is; new values land at once
+            if (JSON.stringify([cur.params ?? null, cur.playback ?? null, cur.meshNames ?? null]) === JSON.stringify([row.params ?? null, row.playback ?? null, row.meshNames ?? null])) {
+                if (!def.revert && this.running.has(id))
+                    this.play(id);
+                return true;
+            }
+        }
+        this.added.set(key, row);
+        // instant: put on in its held state (a group's effects reaching a child on scene load / as it joins)
+        this.syncList(this.compose(), opts?.instant ? 'instant' : 'direct');
+        return true;
+    }
+    /** Take an added effect off: it plays out (or what is below it takes over again). */
+    removeEffect(key) {
+        if (this.fan?.hasTriggered(key))
+            return this.fan.removeTriggered(key);
+        const cur = this.added.get(key);
+        if (this.disposed || !cur?.enabled)
+            return false;
+        const off = { ...cur, enabled: false };
+        this.added.set(key, off);
+        this.syncList(this.compose(), 'direct');
+        // it stays listed (off) until it has really gone, so a later sync does not cut its out short
+        const l = [...this.leaving].find(x => x.id === cur.id);
+        void (l?.done ?? Promise.resolve()).then(() => { if (this.added.get(key) === off)
+            this.added.delete(key); });
+        return true;
+    }
+    hasEffect(key) { return !!this.added.get(key)?.enabled || !!this.fan?.hasTriggered(key); }
+    /** The object's own steps wait while an applied clip has steps; afterwards they start again from the first. */
+    refreshPause() {
+        const paused = [...this.clips.values()].some(c => !c.off && !!c.cfg);
+        if (paused === this.ownPaused)
+            return;
+        this.ownPaused = paused;
+        const c = this.own;
+        clearTimeout(c.timer);
+        c.run++;
+        if (!paused) {
+            c.index = 0;
+            c.dir = 1;
+            this.scheduleStep(c);
+        }
+    }
+    /**
+     * Apply a whole effect clip over the object's own (an interaction, an action). `key` names this
+     * application for removeClip; `parts` narrows it to nodes of the model. Already on: left as it is.
+     */
+    applyClip(key, clip, parts) {
+        if (this.disposed)
+            return false;
+        if (this.fan) {
+            // a group: the clip's visual / 'each' effects go to the children (staggered), the rest runs on the group
+            const pick = (fan) => {
+                const keep = (e) => !!e && isFanRow(e) === fan;
+                const steps = (clip.steps ?? []).map(s => ({ ...s, effects: (s.effects ?? []).filter(keep) })).filter(s => s.effects.length);
+                return { ...clip, effects: (clip.effects ?? []).filter(keep), steps };
+            };
+            const kids = pick(true), mine = pick(false);
+            const handed = kids.effects.length || kids.steps.length ? this.fan.applyClip(key, kids) : false;
+            if (!mine.effects.length && !mine.steps.length)
+                return handed;
+            clip = mine;
+        }
+        const cur = this.clips.get(key);
+        if (cur && !cur.off)
+            return true;
+        if (cur) {
+            clearTimeout(cur.timer);
+            cur.run++;
+        }
+        // a triggered clip has no autoplay of its own and never follows visibility: it plays when it is applied
+        const effects = (clip.effects ?? []).filter(e => e && isObjectOperation(getOperation(e.operation))).map(e => {
+            const { autoplay: _a, ...pb } = e.playback ?? {};
+            const { playback: _p, meshNames: _m, ...row } = e;
+            return { ...row, ...(Object.keys(pb).length ? { playback: pb } : {}) };
+        });
+        const steps = (clip.steps ?? []).filter(s => s?.effects?.length);
+        const cfg = steps.length ? { steps, loop: clip.loop, yoyo: clip.yoyo } : null;
+        const c = { key, prefix: `~${key}:`, effects, cfg, stepsKey: stepsKeyOf(cfg), index: 0, dir: 1, run: (cur?.run ?? 0) + 1, parts: parts?.length ? parts : undefined };
+        this.clips.delete(key); // newest last
+        this.clips.set(key, c);
+        this.refreshPause();
+        this.scheduleStep(c);
+        this.syncList(this.compose(), 'direct');
+        return true;
+    }
+    /** Take an applied clip off: its effects play out, and what it had taken over comes back. */
+    removeClip(key) {
+        const handed = !this.disposed && !!this.fan?.removeClip(key);
+        const c = this.clips.get(key);
+        if (this.disposed || !c || c.off)
+            return handed;
+        c.off = true;
+        clearTimeout(c.timer);
+        c.run++;
+        this.refreshPause();
+        this.syncList(this.compose(), 'direct');
+        const gone = [...this.leaving].filter(x => x.id.startsWith(c.prefix)).map(x => x.done);
+        void Promise.all(gone).then(() => { if (this.clips.get(key) === c && c.off)
+            this.clips.delete(key); });
+        return true;
+    }
+    hasClip(key) { const c = this.clips.get(key); return (!!c && !c.off) || !!this.fan?.hasClip(key); }
+    /**
+     * A clip's current step's clock: its hold starts when its looks have really played in (they first
+     * wait for the outgoing step, and the first time for their shaders), so a slow start never eats a step.
+     */
+    scheduleStep(c) {
+        clearTimeout(c.timer);
+        const run = ++c.run;
+        const s = c.cfg?.steps[c.index];
+        if (!s)
+            return;
+        if (!this.shown)
+            return; // hidden: the steps wait for the object to be shown
+        const pause = (ms) => new Promise(res => { c.timer = setTimeout(res, ms); });
+        const live = () => !this.disposed && run === c.run;
+        void (async () => {
+            await pause(0); // after the sync that put the step on
+            const ids = (s.effects ?? []).map(e => `${c.prefix}${s.id}:${e.id}`);
+            const looks = () => ids.map(id => this.running.get(id)).filter((r) => { const d = r && getOperation(r.op); return !!r && !!d?.revert && !d.periodic; });
+            for (let waited = 0; live() && waited < 15000 && looks().some(r => !r.started); waited += 50)
+                await pause(50);
+            if (!live())
+                return;
+            await Promise.all(looks().map(r => this.done(r)));
+            if (!live())
+                return;
+            // a group: the step's effects reach the children one after another — the hold starts when the last child's looks are on
+            const fan = c === this.own ? this.fan : null;
+            if (fan && (s.effects ?? []).some(e => e && isFanRow(e))) {
+                // wait until the last child has been given the step's effects, then for its looks to play in
+                for (let waited = 0; live() && waited < 30000 && fan.pending(ids); waited += 50)
+                    await pause(50);
+                if (!live())
+                    return;
+                await pause(seconds(s.in, STEP_IN) * 1000);
+                if (!live())
+                    return;
+            }
+            await pause(seconds(s.hold, STEP_HOLD) * 1000);
+            if (live())
+                this.nextStep(c);
+        })();
+    }
+    nextStep(c) {
+        const cfg = c.cfg;
+        if (!cfg || this.disposed || c.off)
+            return;
+        const n = cfg.steps.length;
+        let i = c.index + c.dir;
+        if (cfg.yoyo) { // there and back through the steps
+            if (n < 2)
+                return;
+            if (i >= n) {
+                c.dir = -1;
+                i = n - 2;
+            }
+            else if (i < 0) {
+                if (!cfg.loop)
+                    return;
+                c.dir = 1;
+                i = 1;
+            }
+        }
+        else if (i >= n) {
+            if (!cfg.loop || n < 2)
+                return; // stays on its last step
+            i = 0;
+        }
+        const leaving = cfg.steps[c.index];
+        c.index = i;
+        // direct: the next step plays in over the outgoing one; a step that plays out goes first, and the next waits for it
+        this.syncList(this.compose(), leaving?.playOut ? 'animate' : 'direct');
+        this.scheduleStep(c);
+    }
+    /** The step of the object's own clip that is on (-1: no steps, or they wait for an applied clip). */
+    get step() { return this.own.cfg && !this.ownPaused ? this.own.index : -1; }
+    syncList(effects, mode) {
+        if (this.disposed)
+            return;
+        if (this.fan) {
+            // a group: its own rows that go to the children (visual, physical 'each' — Base and steps) are handed out
+            const fanRows = [], rest = [];
+            for (const e of effects ?? [])
+                (e && this.ownRows.has(e.id) && isFanRow(e) ? fanRows : rest).push(e);
+            effects = rest;
+            this.fan.sync(fanRows, this.spread, mode === 'instant' ? 'instant' : 'animate', !!this.own.follows);
+        }
         this.effects = effects ?? [];
         if (this.refreshing)
             return; // the refresh puts the latest list back when it is done
         const next = runningObjectEffects(effects);
         const byId = new Map(next.map(e => [e.id, e]));
+        const clearing = new Map(); // switched row → its old effect gone
+        const wiped = []; // direct handover: outgoing take-overs
+        // an effect that goes on under another row (the same effect, from above or below it): op → its targets
+        const comingOn = new Map();
+        for (const e of next)
+            if (!this.running.has(e.id))
+                comingOn.set(e.operation, namesKey(e));
+        const incoming = [];
+        const listed = new Set(this.effects.map(e => e?.id));
+        // removed while it was playing out: finish it at once
+        for (const l of this.leaving) {
+            if (listed.has(l.id))
+                continue;
+            this.off(l.r, true);
+            l.done = Promise.all(l.r.targets.map(t => runOf(l.r.op, t)));
+            void l.done.then(() => this.leaving.delete(l));
+        }
         for (const [id, r] of this.running) {
             const e = byId.get(id);
-            if (e && e.operation === r.op && namesKey(e) === r.targetsKey)
+            if (e && e.operation === r.op && namesKey(e) === r.targetsKey && rowKey(getOperation(e.operation), e, ...this.visOf(e.id)) === r.playbackKey)
                 continue;
-            this.off(r, mode === 'instant');
+            if (e) {
+                // switched (another operation, or another playback): the old effect goes at once (no out transition under the new one's in)
+                if (r.started) {
+                    this.off(r, true);
+                    clearing.set(id, Promise.all(r.targets.map(t => runOf(r.op, t))));
+                }
+                else if (r.waitFor) {
+                    clearing.set(id, r.waitFor); // switched again before it started: still wait for the first
+                }
+            }
+            else {
+                // switched off plays out; a row removed from the list is cleared at once
+                const gone = mode === 'instant' || !listed.has(id);
+                if (mode !== 'instant' && r.started && comingOn.get(r.op) === r.targetsKey) {
+                    // the same effect carries on under another row: it is handed over as it stands (the new row's values take over)
+                    this.cancelCycle(r);
+                    r.phase = undefined;
+                    if (r.wipe) {
+                        r.wipe.cancelled = true;
+                        r.wipe = undefined;
+                    }
+                    this.running.delete(id);
+                    continue;
+                }
+                // a direct handover: a held take-over stays on until the incoming one has wiped it (paired below)
+                if (!gone && mode === 'direct' && r.started && !r.cycle && !r.stopping && getOperation(r.op)?.field)
+                    wiped.push([id, r]);
+                else
+                    this.playOut(id, r, gone, mode === 'instant');
+            }
             this.running.delete(id);
         }
         for (const e of next) {
             const def = getOperation(e.operation);
-            const params = objectEffectParams(def, e);
+            const [follows, inStep] = this.visOf(e.id);
+            const params = objectEffectParams(def, e, follows, inStep);
             const paramsKey = JSON.stringify(params);
             const r = this.running.get(e.id);
             if (r && r.paramsKey === paramsKey)
                 continue;
-            const targets = r?.targets ?? this.targetsOf(e);
-            this.on(def, targets, r || mode === 'instant' ? { ...params, duration: 0 } : params);
-            this.running.set(e.id, { op: def.value, targets, targetsKey: namesKey(e), params, paramsKey });
+            if (r && !r.started) {
+                r.params = params;
+                r.paramsKey = paramsKey;
+                continue;
+            } // starts with the latest
+            const playback = playbackOf(e);
+            if (r?.cycle) {
+                // a parameter changed under a running cycle: its next pass picks it up;
+                // a periodic motion is on the whole time, so it takes it now
+                r.params = params;
+                r.paramsKey = paramsKey;
+                if (def.periodic)
+                    this.on(def, r.targets, { ...params, __backward: !!r.cycle.back, duration: 0 });
+                continue;
+            }
+            const entry = { op: def.value, targets: r?.targets ?? this.targetsOf(e), targetsKey: namesKey(e), params, paramsKey, started: false, playback, playbackKey: rowKey(def, e, follows, inStep), kind: effectPresence(def, e, follows, inStep), follows, inStep };
+            this.running.set(e.id, entry);
+            const instant = !!r || mode === 'instant';
+            if (!r)
+                incoming.push([def, entry]);
+            // start from the original: after the effect this row replaces, and after others still playing out
+            // (the same operation coming back on just turns its own out transition around).
+            // A direct handover does not wait: the new look plays in over the old one.
+            const waits = mode === 'direct' ? [] : [...this.leaving].filter(l => l.op !== def.value).map(l => l.done);
+            const cleared = clearing.get(e.id);
+            if (cleared)
+                waits.push(cleared);
+            const wait = waits.length && !instant ? Promise.all(waits) : cleared;
+            if (!wait) {
+                this.start(def, entry, instant);
+                continue;
+            }
+            entry.waitFor = wait;
+            void wait.then(() => {
+                if (this.disposed || this.running.get(e.id) !== entry || entry.waitFor !== wait)
+                    return; // removed, switched or played meanwhile
+                this.start(def, entry, instant);
+            });
+        }
+        // pair each outgoing take-over with the incoming one that wipes it (a surface take-over first)
+        const by = incoming.find(([d]) => d.field && d.stack) ?? incoming.find(([d]) => d.field);
+        for (const [id, r] of wiped) {
+            if (by && by[0].value !== r.op)
+                this.wipe(id, r, by[0], by[1]);
+            else
+                this.playOut(id, r, false, false);
+        }
+    }
+    /** Take a row that left the list off: at once (`gone`), or with its out transition — then it is tracked until it has gone. */
+    playOut(id, r, gone, untracked) {
+        this.off(r, gone);
+        if (!r.started || untracked)
+            return;
+        const l = { id, r, op: r.op, done: Promise.all(r.targets.map(t => runOf(r.op, t))) };
+        this.leaving.add(l);
+        void l.done.then(() => this.leaving.delete(l));
+    }
+    /**
+     * A direct handover: `r` (a held take-over) stays on while `inc` plays in, and is wiped by
+     * inc's front — its field takes inc's direction / scale / sweep, its `clear` follows inc's
+     * progress every frame. When inc is fully on, r is taken off at once (nothing of it shows any more).
+     */
+    wipe(id, r, incDef, inc) {
+        const def = getOperation(r.op);
+        const token = (r.wipe = { cancelled: false });
+        const saved = new Map();
+        let resolve;
+        const l = { id, r, op: r.op, done: new Promise(res => { resolve = res; }) };
+        this.leaving.add(l);
+        void l.done.then(() => this.leaving.delete(l));
+        const restore = () => saved.forEach((v, f) => { f.direction.value = v.direction; f.scale.value = v.scale; f.sweep.value.copy(v.sweep); f.clear.value = 0; });
+        const next = (fn) => (typeof requestAnimationFrame === 'function' ? requestAnimationFrame(() => fn()) : setTimeout(fn, 16));
+        const t0 = Date.now();
+        const tick = () => {
+            if (token.cancelled || this.disposed) {
+                resolve();
+                return;
+            } // taken off some other way (off() did it)
+            const live = [...this.running.values()].includes(inc);
+            if (!live) { // the incoming look left first: play out the old way
+                r.wipe = undefined;
+                restore();
+                for (const t of r.targets)
+                    forceRevert(def, t, r.params);
+                void Promise.all(r.targets.map(t => runOf(r.op, t))).then(resolve);
+                return;
+            }
+            let done = inc.started;
+            r.targets.forEach((t, i) => {
+                const fo = def.field(t), fi = incDef.field(inc.targets[i] ?? inc.targets[0]);
+                if (!fo || !fi) {
+                    if (!fo)
+                        return;
+                    done = done && !!fi;
+                    return;
+                }
+                if (!saved.has(fo))
+                    saved.set(fo, { direction: fo.direction.value, scale: fo.scale.value, sweep: fo.sweep.value.clone() });
+                fo.direction.value = fi.direction.value;
+                fo.scale.value = fi.scale.value;
+                fo.sweep.value.copy(fi.sweep.value);
+                fo.clearEdge.value = fi.edgeWidth.value;
+                fo.clear.value = Math.min(1, Math.max(0, fi.progress.value));
+                if (fi.progress.value < 0.999)
+                    done = false;
+            });
+            if (!done && Date.now() - t0 < 60000) {
+                next(tick);
+                return;
+            }
+            r.wipe = undefined; // all of it is wiped: off, at once
+            for (const t of r.targets)
+                forceRevert(def, t, { ...r.params, duration: 0 });
+            void Promise.all(r.targets.map(t => runOf(r.op, t))).then(resolve);
+        };
+        tick();
+    }
+    /** Whether the object is shown when the controller starts (before the first sync). */
+    setShown(shown) { this.shown = shown; this.drawn = shown; }
+    /** See setObjectEffectsVisible. */
+    setVisible(visible) {
+        if (this.disposed || visible === this.shown)
+            return null;
+        const c = this.own;
+        const steps = !!c.follows && !!c.cfg;
+        if (steps && !visible) {
+            clearTimeout(c.timer);
+            c.run++;
+        } // hidden: the steps stop (the step that is on plays out below)
+        if (steps && visible && !this.drawn) {
+            // shown from hidden: the steps start again from the first, staged while the object is still hidden
+            c.index = 0;
+            c.dir = 1;
+            this.syncList(this.compose(), 'instant');
+        }
+        // Effects that don't follow visibility (an own clip without it, added effects, applied clips) stop
+        // at once while the object is hidden — nothing runs on a hidden object, and nothing may show it
+        // again (a physical exit's way back puts the object on) — and come back on at once when it is shown.
+        const loose = [...this.running].filter(([, r]) => !r.follows && getOperation(r.op));
+        const looseClips = [c, ...this.clips.values()].filter(x => !!x.cfg && !x.off && !(x === c && steps));
+        const following = [...this.running].some(([, r]) => r.follows && getOperation(r.op));
+        if (!visible) {
+            for (const x of looseClips) {
+                clearTimeout(x.timer);
+                x.run++;
+            }
+            for (const [, r] of loose)
+                this.clear(r);
+            if (loose.length && !following)
+                this.root.visible = false; // a cleared exit put the object back on
         }
+        this.shown = visible;
+        if (visible && (loose.length || looseClips.length)) {
+            for (const x of looseClips) {
+                x.index = 0;
+                x.dir = 1;
+            }
+            if (looseClips.length)
+                this.syncList(this.compose(), 'instant');
+            for (const [id, r] of loose) {
+                const def = getOperation(r.op);
+                if (def && this.running.get(id) === r && !r.started && !r.waitFor)
+                    this.start(def, r, true);
+            }
+            for (const x of looseClips)
+                if (!(x === c && this.ownPaused))
+                    this.scheduleStep(x);
+        }
+        const run = ++this.visRun;
+        const rows = [...this.running].filter(([, r]) => r.follows && getOperation(r.op));
+        // shown: the step that is on gets its clock once its effects are playing in (from the first step, or where it turned round)
+        const clock = () => { if (steps && visible && !this.ownPaused && !this.disposed && run === this.visRun)
+            this.scheduleStep(c); };
+        // a group whose effects follow visibility: hidden → its children play them out one after another and the
+        // group goes after the last; shown → the children start from nothing and play them in one after another
+        const fan = this.fan && c.follows ? this.fan : null;
+        if (fan && !visible) {
+            const outs = [fan.leave()];
+            if (rows.length) {
+                const p = this.leaveAll(rows, run, false);
+                if (p)
+                    outs.push(p);
+            }
+            return Promise.all(outs).then(() => {
+                if (this.disposed || run !== this.visRun)
+                    return; // shown again meanwhile
+                this.root.visible = false;
+                this.drawn = false;
+            });
+        }
+        if (fan && visible)
+            fan.park();
+        if (!rows.length) {
+            this.drawn = visible;
+            clock();
+            if (fan && visible)
+                fan.enter();
+            return null;
+        } // nothing follows it on the root: the renderer shows / hides
+        if (!visible)
+            return this.leaveAll(rows, run);
+        const entering = this.enterAll(rows, run);
+        void entering.then(() => { clock(); if (fan && !this.disposed && run === this.visRun)
+            fan.enter(); });
+        return entering;
+    }
+    // ---- a group's effects on this child, following the group's visibility (driven by the group's GroupFanout) ----
+    addedRows(keys) {
+        return keys.map(k => [`+${k}`, this.running.get(`+${k}`)])
+            .filter((x) => !!x[1] && !!getOperation(x[1].op));
+    }
+    /** The group is being hidden: this child plays the group's effects out, then is no longer drawn. */
+    fanLeave(keys) {
+        const rows = this.addedRows(keys);
+        if (this.disposed || !rows.length)
+            return Promise.resolve();
+        return this.leaveAll(rows, ++this.visRun) ?? Promise.resolve();
+    }
+    /** The group is about to be shown: this child starts from nothing (undrawn, the group's effects at their start). */
+    fanPark(keys) {
+        const rows = this.addedRows(keys);
+        if (this.disposed || !rows.length)
+            return;
+        ++this.visRun;
+        for (const [, r] of rows)
+            this.clear(r);
+        this.root.visible = false;
+        this.drawn = false;
+    }
+    /** Its turn after the group was shown: the group's effects get ready, the child is drawn, they play in. */
+    fanEnter(keys) {
+        const rows = this.addedRows(keys);
+        if (this.disposed || !rows.length) {
+            if (!this.disposed && !this.drawn) {
+                this.root.visible = true;
+                this.drawn = true;
+            }
+            return Promise.resolve();
+        }
+        return this.enterAll(rows, ++this.visRun);
+    }
+    cancelCycle(r) {
+        if (r.cycle) {
+            r.cycle.cancelled = true;
+            r.cycle.wake?.();
+            r.cycle = undefined;
+        }
+    }
+    /** Take an effect off at once and leave its row waiting. */
+    clear(r) {
+        this.off(r, true);
+        r.started = false;
+        r.stopping = undefined;
+        r.waitFor = undefined;
+    }
+    /** The object is shown: get every effect ready while it is still undrawn, draw it, play them in. */
+    async enterAll(rows, run) {
+        // shown again while its effects were still playing out: it is still drawn, they turn round where they are
+        const turn = this.drawn;
+        if (!turn) {
+            await Promise.all(rows.map(([, r]) => this.prepare(r)));
+            if (this.disposed || run !== this.visRun)
+                return; // hidden again meanwhile (leaveAll cleared it)
+        }
+        this.root.visible = true;
+        this.drawn = true;
+        // add-ons (trails) first: they are fully on when the entrances start moving the object
+        const first = [...rows].sort(([, a], [, b]) => Number(!!getOperation(b.op)?.addOn) - Number(!!getOperation(a.op)?.addOn));
+        for (const [id, r] of first)
+            if (this.running.get(id) === r)
+                this.enter(id, r, turn);
+    }
+    /** Before the object is drawn: compile the effect and put its start state on. */
+    prepare(r) {
+        const def = getOperation(r.op);
+        r.waitFor = undefined;
+        r.stopping = undefined;
+        if (r.kind === 'vanish') { // it starts gone
+            r.started = true;
+            r.phase = {};
+            this.on(def, r.targets, { ...r.params, duration: 0 });
+            return this.done(r);
+        }
+        if (def.channel !== 'visual' || !def.revert)
+            return Promise.resolve();
+        r.started = true; // staged at its start (a paint effect: nothing drawn yet)
+        return Promise.all(r.targets.map(t => warmOperation(def, t, r.params, this.root, { bare: true })));
+    }
+    enter(id, r, turn) {
+        const def = getOperation(r.op);
+        r.stopping = undefined;
+        if (def.addOn && def.revert) { // on at once: it draws the entrance from its first frame
+            this.cancelCycle(r);
+            r.started = true;
+            this.on(def, r.targets, { ...r.params, duration: 0 });
+            return;
+        }
+        if (r.kind === 'paint') {
+            this.cancelCycle(r);
+            r.started = true;
+            this.on(def, r.targets, r.params); // from where it stands: its start, or part-way out
+            return;
+        }
+        if (r.kind === 'vanish') {
+            if (r.started)
+                this.comeBack(def, r);
+            else
+                this.entrance(def, r);
+            return;
+        }
+        if (turn) {
+            // a plain look turns round from where it is; anything else plays again from its start
+            if (r.started && def.revert && !def.periodic && isPlain(r.playback))
+                this.on(def, r.targets, r.params);
+            else
+                this.play(id);
+            return;
+        }
+        r.started = false; // staged at its start: it plays from there
+        this.start(def, r, false, true);
+    }
+    /** A paint / vanish effect's entrance on an object that is already drawn (added, switched on, ▶). */
+    entrance(def, r) {
+        r.started = true;
+        // the object is drawn: a take-over plays in over it (it paints the object in only when the object is being shown)
+        if (r.kind === 'paint') {
+            this.on(def, r.targets, { ...r.params, __reveal: false });
+            return;
+        }
+        const phase = (r.phase = {});
+        this.on(def, r.targets, { ...r.params, duration: 0 }); // gone…
+        void this.done(r).then(() => { if (!this.disposed && r.phase === phase)
+            this.comeBack(def, r); }); // …and back
+    }
+    /** A vanish effect plays back from gone (or from part-way); then the object is at rest, with nothing on it. */
+    comeBack(def, r) {
+        const phase = (r.phase = {});
+        r.started = true;
+        for (const t of r.targets)
+            forceRevert(def, t, r.params);
+        void this.done(r).then(() => { if (r.phase === phase) {
+            r.phase = undefined;
+            r.started = false;
+        } });
+    }
+    /** The object is hidden: play every effect out, then stop drawing it. */
+    /** `hide`: stop drawing the object at the end (a group hides itself after its children instead). */
+    leaveAll(rows, run, hide = true) {
+        if (!this.drawn) { // it was still getting ready to be shown
+            for (const [, r] of rows)
+                this.clear(r);
+            if (hide)
+                this.root.visible = false;
+            return null;
+        }
+        // add-ons (trails) stay on through the exits and go off once the object is gone
+        const isAddOn = (r) => !!getOperation(r.op)?.addOn;
+        const outs = rows.filter(([, r]) => !isAddOn(r)).map(([id, r]) => this.leave(id, r));
+        return Promise.all(outs).then(() => {
+            if (this.disposed || run !== this.visRun)
+                return; // shown again meanwhile
+            // while hidden nothing is on, so the next show starts clean — and in the same tick the object goes
+            for (const [id, r] of rows)
+                if (this.running.get(id) === r && !isAddOn(r))
+                    this.clear(r);
+            if (hide) {
+                this.root.visible = false;
+                this.drawn = false;
+            }
+            for (const [id, r] of rows) {
+                if (this.running.get(id) !== r || !isAddOn(r))
+                    continue;
+                // it fades out and lets what is in flight finish (it lives in the scene, not on the hidden object)
+                const out = this.leave(id, r);
+                void Promise.resolve(out).then(() => {
+                    if (!this.disposed && run === this.visRun && this.running.get(id) === r)
+                        this.clear(r);
+                });
+            }
+        });
+    }
+    leave(id, r) {
+        const def = getOperation(r.op);
+        r.waitFor = undefined;
+        if (r.kind === 'vanish') { // from rest, or from part-way in: it plays to gone
+            r.started = true;
+            r.phase = {};
+            this.on(def, r.targets, r.params);
+            return this.done(r);
+        }
+        if (!r.started)
+            return null;
+        if (r.kind === 'paint') { // retreats with the reveal on: nothing is left behind it
+            this.cancelCycle(r);
+            for (const t of r.targets)
+                forceRevert(def, t, r.params);
+            return this.done(r);
+        }
+        if (!def.revert) { // a one-shot: its move once more, the other way
+            this.cancelCycle(r);
+            this.on(def, r.targets, { ...r.params, __backward: !r.playback.reverse });
+            return this.done(r);
+        }
+        this.stop(id);
+        return r.stopping ?? null;
+    }
+    /** `force`: play it even with autoplay off (it was asked for). */
+    start(def, r, instant, force = false) {
+        r.waitFor = undefined;
+        if (!this.shown)
+            return; // the object is hidden: nothing runs until it is shown
+        if (r.follows && r.kind !== 'decorate') {
+            // shown at load / a changed value: a take-over is simply on, a vanish effect has nothing on
+            if (instant) {
+                if (r.kind === 'paint') {
+                    r.started = true;
+                    this.on(def, r.targets, { ...r.params, duration: 0 });
+                }
+            }
+            else
+                this.entrance(def, r); // added, switched on, ▶: its entrance
+            return;
+        }
+        if (!r.playback.autoplay && !force)
+            return; // waits at its start for play()
+        r.started = true;
+        if (def.periodic) {
+            void this.periodic(def, r, instant);
+            return;
+        }
+        if (isPlain(r.playback)) {
+            this.on(def, r.targets, instant ? { ...r.params, duration: 0 } : r.params);
+            return;
+        }
+        void this.cycle(def, r);
+    }
+    done(r) { return Promise.all(r.targets.map(t => runOf(r.op, t))); }
+    /**
+     * A periodic motion (float, sway…): on for one pass, then it settles — or on for good with Loop.
+     * Reverse runs its clock backwards; yoyo turns the clock round after each pass.
+     */
+    async periodic(def, r, instant) {
+        const token = { cancelled: false, back: r.playback.reverse };
+        r.cycle = token;
+        const { loop, yoyo } = r.playback;
+        const wait = (seconds) => new Promise((resolve) => {
+            const end = () => { clearTimeout(id); token.wake = undefined; resolve(); };
+            const id = setTimeout(end, Math.max(16, seconds * 1000));
+            token.wake = end;
+        });
+        /** The part of a pass at full strength (the rest is building up and settling). */
+        const moving = () => { const d = Number(r.params.duration); return Math.max(0, d - 2 * periodicEase(d)); };
+        const turnOn = (atOnce) => this.on(def, r.targets, { ...r.params, __backward: !!token.back, ...(atOnce ? { duration: 0 } : {}) });
+        turnOn(instant);
+        await this.done(r);
+        if (token.cancelled)
+            return;
+        if (loop && !yoyo)
+            return; // stays on until it is switched off (r.cycle stays: it is running)
+        for (;;) {
+            await wait(moving());
+            if (token.cancelled)
+                return;
+            if (!yoyo && !loop)
+                break;
+            token.back = !token.back; // yoyo: the same motion, backwards
+            turnOn(true);
+            if (!loop) {
+                await wait(moving());
+                if (token.cancelled)
+                    return;
+                break;
+            }
+        }
+        for (const t of r.targets)
+            forceRevert(def, t, r.params);
+        await this.done(r);
+        if (r.cycle === token)
+            r.cycle = undefined;
+    }
+    /** Loop / yoyo / reverse, sequenced from apply (forward) and revert (backward). Reads r.params each pass. */
+    async cycle(def, r) {
+        const token = { cancelled: false };
+        r.cycle = token;
+        const { reverse, loop, yoyo } = r.playback;
+        const at = (dur0) => (dur0 ? { ...r.params, duration: 0 } : r.params);
+        // A one-shot (no revert: jelly, flip, spin) starts and ends at rest, so standing at either end is
+        // nothing to do, and its way back is the same move played backwards in time (`__backward`).
+        const oneShot = !def.revert;
+        const forward = async (dur0 = false) => {
+            if (oneShot && dur0)
+                return;
+            this.on(def, r.targets, at(dur0));
+            await this.done(r);
+        };
+        const backward = async (dur0 = false) => {
+            if (oneShot && dur0)
+                return;
+            if (oneShot)
+                this.on(def, r.targets, { ...r.params, __backward: true });
+            else
+                for (const t of r.targets)
+                    forceRevert(def, t, at(dur0));
+            await this.done(r);
+        };
+        // a pass: start → end (or end → start when reversed); `first` is the direction of its first leg
+        const first = reverse ? backward : forward;
+        const second = reverse ? forward : backward;
+        if (reverse) {
+            await forward(true);
+            if (token.cancelled)
+                return;
+        } // stand at the end
+        for (;;) {
+            // a pass never takes less than a frame (a zero duration must not spin)
+            const frame = new Promise(res => setTimeout(res, 16));
+            await first();
+            await frame;
+            if (token.cancelled)
+                return;
+            if (yoyo) {
+                await second();
+                if (token.cancelled)
+                    return;
+            }
+            if (!loop)
+                break;
+            if (!yoyo) {
+                await second(true);
+                if (token.cancelled)
+                    return;
+            } // jump back to the pass's start
+        }
+        if (r.cycle === token)
+            r.cycle = undefined;
+    }
+    /** Play an effect out and leave it waiting (it stays in the list, ready to play again). */
+    stop(effectId) {
+        const r = this.running.get(effectId);
+        const def = r && getOperation(r.op);
+        if (!r || !def || this.disposed || this.refreshing)
+            return false;
+        r.waitFor = undefined; // a play that was about to start is called off
+        if (!r.started || r.stopping)
+            return true;
+        if (!def.revert) { // a one-shot: stop its move, back at once
+            if (r.cycle) {
+                r.cycle.cancelled = true;
+                r.cycle.wake?.();
+                r.cycle = undefined;
+            }
+            for (const t of r.targets)
+                def.cancel?.(t);
+            r.started = false;
+            return true;
+        }
+        this.off(r, false);
+        const done = this.done(r);
+        r.stopping = done;
+        void done.then(() => { if (r.stopping === done) {
+            r.stopping = undefined;
+            r.started = false;
+        } });
+        return true;
+    }
+    /** Play an effect from its start (see playObjectEffect). */
+    play(effectId) {
+        const r = this.running.get(effectId);
+        const def = r && getOperation(r.op);
+        if (!r || !def || this.disposed || this.refreshing)
+            return false;
+        r.stopping = undefined;
+        const wasOn = r.started;
+        this.off(r, true); // cancels a running cycle, clears at once
+        const cleared = wasOn ? this.done(r) : Promise.resolve();
+        r.started = false;
+        r.waitFor = cleared;
+        void cleared.then(() => {
+            if (this.disposed || this.running.get(effectId) !== r || r.waitFor !== cleared)
+                return;
+            this.start(def, r, false, true);
+        });
+        return true;
     }
     /**
      * The object's meshes or materials were replaced: take every effect off the
@@ -107,14 +1164,29 @@ export class ObjectEffectsController {
         const done = Promise.all(list.flatMap(r => r.targets.map(t => runOf(r.op, t))));
         this.refreshing = done.then(() => {
             this.refreshing = null;
-            this.sync(this.effects, 'instant');
+            this.syncList(this.compose(), 'instant');
         });
         return this.refreshing;
     }
     /** Take everything off at once (the object is going away). */
+    /** A group: children joined or left (the effects hook checks every few frames). */
+    checkFanout() { this.fan?.check(); }
+    /** Ids of a group's children in cascade order (tests / studio). */
+    get fanChildren() { return this.fan?.childIds ?? []; }
     dispose() {
+        this.fan?.dispose();
+        this.fan = null;
+        for (const c of [this.own, ...this.clips.values()]) {
+            clearTimeout(c.timer);
+            c.run++;
+        }
+        this.clips.clear();
+        this.added.clear();
+        if (controllers.get(this.root) === this)
+            controllers.delete(this.root);
         this.running.forEach(r => this.off(r, true));
         this.running.clear();
+        this.leaving.clear();
         this.disposed = true;
     }
     /** Ids of the effects running now (tests / studio). */
@@ -129,7 +1201,9 @@ export function surfaceSignature(root) {
     root.traverse((c) => {
         if (!c.isMesh || c.userData?.__opFxHelper)
             return;
-        const mats = Array.isArray(c.material) ? c.material : [c.material];
+        // an effect that swaps in its own copies while it plays (shatter) leaves the real material here
+        const own = c.userData?.__opFxOwnMaterial ?? c.material;
+        const mats = Array.isArray(own) ? own : [own];
         parts.push(c.uuid + ':' + mats.map((m) => m?.uuid ?? '').join(','));
     });
     return parts.join(';');