babylon.quarks-editor 0.17.9 → 0.18.0

package/dist/react/GalleryPanel.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useMemo, useRef, useState } from 'react';
 import { useVirtualizer } from '@tanstack/react-virtual';
-import { CheckCircleIcon, ChevronDownIcon, ChevronRightIcon, FolderIcon, FolderOpenIcon, SparklesIcon, } from '@heroicons/react/24/solid';
+import { CheckCircleIcon, ChevronDownIcon, ChevronRightIcon, FolderIcon, FolderOpenIcon, SparklesIcon, XMarkIcon, } from '@heroicons/react/24/solid';
 import { setGalleryDragSession } from '../core/galleryDragSession';
 import { buildGalleryTree, filterGalleryTree, flattenVisibleGalleryRows, writeGalleryDrag, } from '../core/galleryTree';
 import { iconStyle } from './icons';
@@ -15,17 +15,27 @@ function endGalleryDrag() {
     setGalleryDragSession(null);
 }
 function EffectRow(props) {
-    const { entry, depth, focused, inPreview, onFocus, onTogglePreview } = props;
+    const { entry, depth, focused, inPreview, onFocus, onTogglePreview, onRemoveFromScene } = props;
     const isLooping = entry.systems.some((system) => system.looping);
+    const parkedOnStage = entry.inScene && !inPreview;
+    const rowBackground = focused
+        ? 'rgba(120, 165, 255, 0.22)'
+        : inPreview
+            ? 'rgba(120, 165, 255, 0.1)'
+            : parkedOnStage
+                ? 'rgba(120, 165, 255, 0.04)'
+                : 'transparent';
     return (_jsxs("div", { style: {
             display: 'flex',
             alignItems: 'stretch',
             width: '100%',
             height: GALLERY_ROW_HEIGHT,
             borderBottom: `1px solid ${theme.border}`,
-            background: focused ? 'rgba(120, 165, 255, 0.22)' : inPreview ? 'rgba(120, 165, 255, 0.08)' : 'transparent',
+            background: rowBackground,
             boxSizing: 'border-box',
-        }, children: [entry.inScene ? (_jsx("button", { type: "button", className: "qe-hover", title: inPreview ? 'Remove from stage preview' : 'Preview on stage (keep playing)', style: {
+        }, children: [entry.inScene ? (_jsx("button", { type: "button", className: "qe-hover", title: inPreview
+                    ? 'Remove from stage preview — stops group playback and clears particles; effect stays on stage'
+                    : 'Add to stage preview — plays with Stage Play/Pause', style: {
                     flexShrink: 0,
                     width: 28,
                     border: 'none',
@@ -40,9 +50,9 @@ function EffectRow(props) {
                 }, onClick: (e) => {
                     e.stopPropagation();
                     onTogglePreview(entry);
-                }, children: inPreview ? _jsx(CheckCircleIcon, { style: iconStyle(14) }) : _jsx("span", { style: { width: 10, height: 10, border: `1px solid currentColor`, borderRadius: 2, boxSizing: 'border-box' } }) })) : (_jsx("span", { style: { width: 28, flexShrink: 0, borderRight: `1px solid ${theme.border}` } })), _jsxs("button", { type: "button", draggable: true, className: "qe-hover-bg", title: entry.inScene
-                    ? `${entry.path} — in scene · Ctrl+click toggles preview`
-                    : `${entry.path} — drag into viewport`, style: {
+                }, children: inPreview ? (_jsx(CheckCircleIcon, { style: iconStyle(14) })) : (_jsx("span", { style: { width: 10, height: 10, border: `1px solid currentColor`, borderRadius: 2, boxSizing: 'border-box' } })) })) : (_jsx("span", { style: { width: 28, flexShrink: 0, borderRight: `1px solid ${theme.border}` } })), _jsxs("button", { type: "button", draggable: true, className: "qe-hover-bg", title: entry.inScene
+                    ? `${entry.path} — on stage${inPreview ? ' · previewing' : ' · parked'} · Ctrl+click toggles preview`
+                    : `${entry.path} — catalog only · drag into viewport to place`, style: {
                     display: 'flex',
                     alignItems: 'center',
                     gap: 8,
@@ -53,7 +63,7 @@ function EffectRow(props) {
                     border: 'none',
                     background: 'transparent',
                     color: focused ? theme.text : theme.textDim,
-                    padding: `0 12px 0 ${8 + depth * 14}px`,
+                    padding: `0 8px 0 ${8 + depth * 14}px`,
                     fontSize: 12.5,
                     cursor: 'grab',
                     fontFamily: theme.font,
@@ -63,7 +73,28 @@ function EffectRow(props) {
                         return;
                     }
                     onFocus(entry);
-                }, onDragStart: (e) => beginGalleryDrag(e, { kind: 'effect', id: entry.root.uniqueId }), onDragEnd: endGalleryDrag, children: [_jsx("span", { style: { width: 14, flexShrink: 0, opacity: entry.inScene ? 1 : 0.35, color: entry.inScene ? theme.accent : theme.textDim, display: 'inline-flex' }, children: entry.inScene ? _jsx(SparklesIcon, { style: iconStyle(14) }) : _jsx(SparklesIcon, { style: iconStyle(14) }) }), _jsx("span", { style: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }, children: entry.name }), isLooping && (_jsx("span", { title: "Looping effect", style: { flexShrink: 0, fontSize: 11, color: theme.textDim }, children: "\u27F3" }))] })] }));
+                }, onDragStart: (e) => beginGalleryDrag(e, { kind: 'effect', id: entry.root.uniqueId }), onDragEnd: endGalleryDrag, children: [_jsx("span", { style: {
+                            width: 14,
+                            flexShrink: 0,
+                            opacity: entry.inScene ? 1 : 0.35,
+                            color: inPreview ? theme.accent : entry.inScene ? theme.text : theme.textDim,
+                            display: 'inline-flex',
+                        }, title: entry.inScene ? 'On stage' : 'Catalog only', children: _jsx(SparklesIcon, { style: iconStyle(14) }) }), _jsx("span", { style: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }, children: entry.name }), parkedOnStage && (_jsx("span", { title: "On stage but not in preview", style: { flexShrink: 0, fontSize: 10, color: theme.textDim, letterSpacing: 0.3 }, children: "parked" })), isLooping && (_jsx("span", { title: "Looping effect", style: { flexShrink: 0, fontSize: 11, color: theme.textDim }, children: "\u27F3" }))] }), entry.inScene ? (_jsx("button", { type: "button", className: "qe-hover", title: "Remove from scene \u2014 returns to catalog; drag into viewport to place again", style: {
+                    flexShrink: 0,
+                    width: 28,
+                    border: 'none',
+                    borderLeft: `1px solid ${theme.border}`,
+                    background: 'transparent',
+                    color: theme.textDim,
+                    cursor: 'pointer',
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    padding: 0,
+                }, onClick: (e) => {
+                    e.stopPropagation();
+                    onRemoveFromScene(entry);
+                }, children: _jsx(XMarkIcon, { style: iconStyle(13) }) })) : null] }));
 }
 function FolderRow(props) {
     const { node, depth, effectCount, open, onToggle } = props;
@@ -98,7 +129,7 @@ function flatRowKey(row) {
     return row.kind === 'folder' ? `folder:${row.node.path}` : `effect:${row.node.entry.root.uniqueId}`;
 }
 function VirtualGalleryTree(props) {
-    const { rows, closedFolders, focusedRoot, previewRootIds, onFocus, onTogglePreview, onToggleFolder } = props;
+    const { rows, closedFolders, focusedRoot, previewRootIds, onFocus, onTogglePreview, onRemoveFromScene, onToggleFolder } = props;
     const scrollRef = useRef(null);
     const virtualizer = useVirtualizer({
         count: rows.length,
@@ -123,12 +154,12 @@ function VirtualGalleryTree(props) {
                         width: '100%',
                         height: virtualRow.size,
                         transform: `translateY(${virtualRow.start}px)`,
-                    }, children: row.kind === 'folder' ? (_jsx(FolderRow, { node: row.node, depth: row.depth, effectCount: row.effectCount, open: open, onToggle: onToggleFolder })) : (_jsx(EffectRow, { entry: row.node.entry, depth: row.depth, focused: focusedRoot === row.node.entry.root, inPreview: previewRootIds.has(row.node.entry.root.uniqueId), onFocus: onFocus, onTogglePreview: onTogglePreview })) }, flatRowKey(row)));
+                    }, children: row.kind === 'folder' ? (_jsx(FolderRow, { node: row.node, depth: row.depth, effectCount: row.effectCount, open: open, onToggle: onToggleFolder })) : (_jsx(EffectRow, { entry: row.node.entry, depth: row.depth, focused: focusedRoot === row.node.entry.root, inPreview: previewRootIds.has(row.node.entry.root.uniqueId), onFocus: onFocus, onTogglePreview: onTogglePreview, onRemoveFromScene: onRemoveFromScene })) }, flatRowKey(row)));
             }) }) }));
 }
 /** Folder-tree catalog; import effects here and drag them into the viewport. */
 export function GalleryPanel(props) {
-    const { entries, focusedRoot, previewRootIds, loading, folderInputRef, onFocus, onTogglePreview, onImportFiles, onImportFolder, onCreateDefault } = props;
+    const { entries, focusedRoot, previewRootIds, loading, folderInputRef, onFocus, onTogglePreview, onRemoveFromScene, onImportFiles, onImportFolder, onCreateDefault } = props;
     const [query, setQuery] = useState('');
     const [closedFolders, setClosedFolders] = useState(() => new Set());
     const fileInputRef = useRef(null);
@@ -192,7 +223,7 @@ export function GalleryPanel(props) {
                                     onImportFiles(files);
                                 } })] })] }), _jsx("div", { style: { fontSize: 12, color: theme.textDim, lineHeight: 1.45 }, children: isLoading
                     ? `Loading… ${loading.done} / ${loading.total || '…'} files`
-                    : `${previewCount} previewing · ${inSceneCount} in scene · ${entries.length} total` }), _jsx("div", { style: { fontSize: 11, color: theme.textDim, lineHeight: 1.4 }, children: "Preview plays on stage \u00B7 Click = edit \u00B7 Checkbox or Ctrl+click toggles preview." }), _jsx("input", { className: "qe-hover", style: inputStyle, placeholder: "Filter by name or path\u2026", value: query, onChange: (e) => setQuery(e.target.value) }), entries.length === 0 && !isLoading ? (_jsxs("div", { style: {
+                    : `${previewCount} previewing · ${inSceneCount} on stage · ${entries.length} in catalog` }), _jsxs("div", { style: { fontSize: 11, color: theme.textDim, lineHeight: 1.45 }, children: ["\u2713 stage preview \u00B7 \u2728 on stage \u00B7 drag to place \u00B7 \u00D7 remove from stage", _jsx("br", {}), "Click = edit \u00B7 Ctrl+click = toggle preview"] }), _jsx("input", { className: "qe-hover", style: inputStyle, placeholder: "Filter by name or path\u2026", value: query, onChange: (e) => setQuery(e.target.value) }), entries.length === 0 && !isLoading ? (_jsxs("div", { style: {
                     flex: 1,
                     minHeight: 120,
                     padding: '14px 12px',
@@ -211,5 +242,5 @@ export function GalleryPanel(props) {
                     border: `1px solid ${theme.border}`,
                     borderRadius: 8,
                     background: theme.sectionBg,
-                }, children: "No matches." })) : (_jsx(VirtualGalleryTree, { rows: flatRows, closedFolders: closedFolders, focusedRoot: focusedRoot, previewRootIds: previewRootIds, onFocus: onFocus, onTogglePreview: onTogglePreview, onToggleFolder: toggleFolder }))] }));
+                }, children: "No matches." })) : (_jsx(VirtualGalleryTree, { rows: flatRows, closedFolders: closedFolders, focusedRoot: focusedRoot, previewRootIds: previewRootIds, onFocus: onFocus, onTogglePreview: onTogglePreview, onRemoveFromScene: onRemoveFromScene, onToggleFolder: toggleFolder }))] }));
 }

package/dist/react/TimelinePanel.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { BatchedRenderer } from 'babylon.quarks';
 import type { Scene } from '@babylonjs/core/scene';
 import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import type { EffectBinding } from '../core/binding';
@@ -9,6 +10,7 @@ export interface TimelinePanelProps {
     selectedNode: TransformNode | null;
     onSelectNode: (node: TransformNode | null) => void;
     scene: Scene;
+    renderer: BatchedRenderer;
     playbackRef: React.MutableRefObject<PlaybackState>;
     playheadRef: React.RefObject<HTMLDivElement>;
     counterRef: React.RefObject<HTMLSpanElement>;

package/dist/react/TimelinePanel.js

@@ -3,7 +3,7 @@ import React, { useMemo, useRef, useState } from 'react';
 import { ArrowPathIcon, ForwardIcon, PauseIcon, PlayIcon, RectangleGroupIcon, } from '@heroicons/react/24/solid';
 import { clearFocusFinished, getFocusElapsed, isFocusFinished, markFocusFinished, setFocusElapsed, } from '../core/playback';
 import { groupNodes } from '../core/groups';
-import { scrubFocusTo } from '../core/scrub';
+import { pauseFocus, playFocus, scrubFocusTo, scrubFocusToSettled } from '../core/scrub';
 import { computeTimelineRows, computeTimelineSpan } from '../core/timeline';
 import { TimelineTrackRow } from './TimelineTrackRow';
 import { iconStyle } from './icons';
@@ -29,7 +29,7 @@ function pickTickInterval(pxPerSecond) {
  * apply only to the focused effect without stopping other previews.
  */
 export function TimelinePanel(props) {
-    const { binding, selectedNode, onSelectNode, scene, playbackRef, playheadRef, counterRef, stagePlaying, setStagePlaying, speed, setSpeed, playbackEnabled = true } = props;
+    const { binding, selectedNode, onSelectNode, scene, renderer, playbackRef, playheadRef, counterRef, stagePlaying, setStagePlaying, speed, setSpeed, playbackEnabled = true } = props;
     const [bodyWidthPx, setBodyWidthPx] = useState(600);
     const [collapsedGroups, setCollapsedGroups] = useState(() => new Set());
     const [hiddenSystems, setHiddenSystems] = useState(() => new Set());
@@ -106,12 +106,19 @@ export function TimelinePanel(props) {
             if (anyLooping) {
                 shown = timelineSpan > 0 ? elapsed % timelineSpan : 0;
             }
-            else if (elapsed >= timelineSpan || isFocusFinished(state, focusRootId)) {
+            else if (isFocusFinished(state, focusRootId)) {
+                // Park at real simulation time — core may finish before the ruler's worst-case span.
+                shown = elapsed;
+            }
+            else if (elapsed >= timelineSpan) {
                 shown = timelineSpan;
-                const justFinishedPlaying = !state.scrubbing && state.stagePlaying && prevElapsedRef.current < timelineSpan && elapsed >= timelineSpan;
+                const justFinishedPlaying = !state.scrubbing && state.stagePlaying && prevElapsedRef.current < timelineSpan;
                 if (justFinishedPlaying) {
+                    scrubFocusToSettled(binding, renderer, timelineSpan);
                     markFocusFinished(state, focusRootId);
                     setFocusElapsed(state, focusRootId, timelineSpan);
+                    pauseFocus(binding);
+                    scene.render();
                 }
             }
             prevElapsedRef.current = elapsed;
@@ -122,7 +129,7 @@ export function TimelinePanel(props) {
         };
         raf = requestAnimationFrame(tick);
         return () => cancelAnimationFrame(raf);
-    }, [pxPerSecond, timelineSpan, anyLooping, playbackRef, playheadRef, focusRootId, playbackEnabled]);
+    }, [pxPerSecond, timelineSpan, anyLooping, playbackRef, playheadRef, focusRootId, playbackEnabled, binding, scene, renderer]);
     const visibleRows = useMemo(() => {
         let hideUntilDepth = null;
         const visible = rows.filter((row) => {
@@ -156,17 +163,24 @@ export function TimelinePanel(props) {
         return Math.min(timelineSpan, Math.max(0, x / pxPerSecond));
     };
     const applyScrub = (time) => {
-        scrubFocusTo(binding, time);
         const state = playbackRef.current;
-        setFocusElapsed(state, focusRootId, time);
-        if (time < timelineSpan) {
-            clearFocusFinished(state, focusRootId);
-        }
-        else if (!anyLooping) {
+        const atEnd = !anyLooping && time >= timelineSpan;
+        const shown = atEnd ? timelineSpan : time;
+        if (atEnd) {
+            scrubFocusToSettled(binding, renderer, timelineSpan);
             markFocusFinished(state, focusRootId);
+            pauseFocus(binding);
         }
+        else {
+            scrubFocusTo(binding, renderer, time);
+            clearFocusFinished(state, focusRootId);
+            if (stagePlaying) {
+                playFocus(binding);
+            }
+        }
+        setFocusElapsed(state, focusRootId, shown);
         if (playheadRef.current) {
-            playheadRef.current.style.left = `${LABEL_WIDTH + TIMELINE_INSET + time * pxPerSecond}px`;
+            playheadRef.current.style.left = `${LABEL_WIDTH + TIMELINE_INSET + shown * pxPerSecond}px`;
         }
         scene.render();
     };
@@ -182,10 +196,13 @@ export function TimelinePanel(props) {
         }
     };
     const restartFocus = () => {
-        scrubFocusTo(binding, 0);
+        scrubFocusTo(binding, renderer, 0);
         const state = playbackRef.current;
         setFocusElapsed(state, focusRootId, 0);
         clearFocusFinished(state, focusRootId);
+        if (stagePlaying) {
+            playFocus(binding);
+        }
         if (playheadRef.current) {
             playheadRef.current.style.left = `${LABEL_WIDTH + TIMELINE_INSET}px`;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babylon.quarks-editor",
-  "version": "0.17.9",
+  "version": "0.18.0",
   "description": "Shuriken-style effect editor for babylon.quarks: headless edit-model core + React module-stack UI",
   "type": "module",
   "main": "./dist/index.js",

package/src/core/galleryPlayback.ts

@@ -1,4 +1,5 @@
 import type {GalleryEntry} from './loadEffectGallery';
+import {QuarksUtil} from 'babylon.quarks';
 
 function isPreviewEntry(entry: GalleryEntry, previewRootIds: ReadonlySet<number>): boolean {
     return entry.inScene && previewRootIds.has(entry.root.uniqueId);
@@ -8,7 +9,8 @@ function isPreviewEntry(entry: GalleryEntry, previewRootIds: ReadonlySet<number>
 export function applyGalleryPlayback(
     entries: GalleryEntry[],
     previewRootIds: ReadonlySet<number>,
-    transportPlaying: boolean
+    transportPlaying: boolean,
+    focusFinishedRootIds: ReadonlySet<number> = new Set()
 ): void {
     for (const entry of entries) {
         for (const system of entry.systems) {
@@ -24,6 +26,9 @@ export function applyGalleryPlayback(
         if (!isPreviewEntry(entry, previewRootIds)) {
             continue;
         }
+        if (focusFinishedRootIds.has(entry.root.uniqueId)) {
+            continue;
+        }
         for (const system of entry.systems) {
             system.play();
         }
@@ -53,3 +58,33 @@ export function countGalleryParticles(entries: GalleryEntry[], previewRootIds: R
     }
     return count;
 }
+
+/**
+ * Pauses one-shot preview effects whose particle systems report `isFinished()`.
+ * Returns true when any entry was paused (caller should refresh renderer batches).
+ */
+export function pauseFinishedPreviews(
+    entries: GalleryEntry[],
+    previewRootIds: ReadonlySet<number>,
+    focusFinishedRootIds: ReadonlySet<number> = new Set()
+): boolean {
+    let pausedAny = false;
+    for (const entry of entries) {
+        if (!isPreviewEntry(entry, previewRootIds)) {
+            continue;
+        }
+        if (focusFinishedRootIds.has(entry.root.uniqueId)) {
+            continue;
+        }
+        if (!QuarksUtil.isEffectFinished(entry.root)) {
+            continue;
+        }
+        for (const system of entry.systems) {
+            if (!system.paused) {
+                system.pause();
+                pausedAny = true;
+            }
+        }
+    }
+    return pausedAny;
+}

package/src/core/galleryScene.ts

@@ -1,9 +1,19 @@
 import {Vector3} from '@babylonjs/core/Maths/math.vector';
 import type {Scene} from '@babylonjs/core/scene';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import type {BatchedRenderer} from 'babylon.quarks';
 import type {GalleryEntry} from './loadEffectGallery';
 import {DEFAULT_GALLERY_SPACING, galleryGridPosition} from './galleryLayout';
 
+/** Clears live particles and freezes simulation for one placed catalog entry. */
+export function clearGalleryEntrySimulation(entry: GalleryEntry, renderer: BatchedRenderer): void {
+    for (const system of entry.systems) {
+        system.restart();
+        system.pause();
+    }
+    renderer.refreshBatches();
+}
+
 /** Parents a catalog entry into the live scene and registers its systems with the renderer. */
 export function placeGalleryEntryInScene(
     entry: GalleryEntry,
@@ -37,6 +47,30 @@ export function placeGalleryEntriesAt(
     });
 }
 
+/**
+ * Unregisters a placed effect from the renderer and returns it to the hidden catalog.
+ * Systems stay alive for inspector editing; drag into the viewport to place again.
+ */
+export function removeGalleryEntryFromScene(
+    entry: GalleryEntry,
+    renderer: BatchedRenderer,
+    catalogRoot: TransformNode
+): void {
+    if (!entry.inScene) {
+        return;
+    }
+
+    clearGalleryEntrySimulation(entry, renderer);
+
+    for (const system of entry.systems) {
+        renderer.deleteSystem(system);
+    }
+
+    entry.root.parent = catalogRoot;
+    entry.root.setEnabled(false);
+    entry.inScene = false;
+}
+
 /** Raycasts the editor ground plane from canvas/client coordinates. */
 export function pickGroundPosition(scene: Scene, clientX: number, clientY: number): Vector3 {
     const canvas = scene.getEngine().getRenderingCanvas();

package/src/core/renderDebug.ts

@@ -0,0 +1,46 @@
+import type {BatchedRenderer} from 'babylon.quarks';
+
+const STORAGE_KEY = 'quarksDebugRender';
+
+/** Whether GPU/particle mismatch logging is enabled (localStorage quarksDebugRender=1). */
+export function isRenderDebugEnabled(): boolean {
+    try {
+        return typeof localStorage !== 'undefined' && localStorage.getItem(STORAGE_KEY) === '1';
+    } catch {
+        return false;
+    }
+}
+
+let lastMismatchKey = '';
+
+/**
+ * Logs when live particle count is zero but a batch still reports GPU instances.
+ * Enable with: localStorage.setItem('quarksDebugRender', '1')
+ */
+export function logRenderMismatch(renderer: BatchedRenderer, liveParticleCount: number): void {
+    if (!isRenderDebugEnabled()) {
+        return;
+    }
+    const stats = renderer.getBatchRenderStats();
+    const instanceCount = stats.reduce((sum, row) => sum + row.instanceCount, 0);
+    const batchParticleCount = stats.reduce((sum, row) => sum + row.particleCount, 0);
+    if (liveParticleCount !== 0 && instanceCount === liveParticleCount) {
+        lastMismatchKey = '';
+        return;
+    }
+    if (liveParticleCount === 0 && instanceCount === 0 && batchParticleCount === 0) {
+        lastMismatchKey = '';
+        return;
+    }
+    const key = `${liveParticleCount}|${instanceCount}|${batchParticleCount}|${stats.map((row) => `${row.batchIndex}:${row.instanceCount}/${row.particleCount}`).join(';')}`;
+    if (key === lastMismatchKey) {
+        return;
+    }
+    lastMismatchKey = key;
+    console.warn('[quarks render debug] particle vs GPU instance mismatch', {
+        liveParticleCount,
+        batchParticleCount,
+        instanceCount,
+        batches: stats,
+    });
+}

package/src/core/scrub.ts

@@ -7,17 +7,32 @@ function bindingSystems(binding: EffectBinding): ParticleSystem[] {
     return [binding.system, ...binding.subSystems];
 }
 
+/** Unpauses every system in the focused effect. */
+export function playFocus(binding: EffectBinding): void {
+    for (const system of bindingSystems(binding)) {
+        system.play();
+    }
+}
+
+/** Freezes the focused effect at its current simulation state. */
+export function pauseFocus(binding: EffectBinding): void {
+    for (const system of bindingSystems(binding)) {
+        system.pause();
+    }
+}
+
 /**
  * Scrub only the focused effect's systems — does not advance other preview effects
  * via the shared BatchedRenderer.update loop.
  */
-export function scrubFocusTo(binding: EffectBinding, time: number): void {
+export function scrubFocusTo(binding: EffectBinding, renderer: BatchedRenderer, time: number): void {
     const systems = bindingSystems(binding);
     for (const system of systems) {
         system.restart();
         system.play();
     }
     if (time <= 0) {
+        renderer.refreshBatches();
         return;
     }
     const fixedStep = time > WIDE_STEP_THRESHOLD ? 1 / 30 : 1 / 60;
@@ -33,6 +48,33 @@ export function scrubFocusTo(binding: EffectBinding, time: number): void {
             system.update(remainder);
         }
     }
+    renderer.refreshBatches();
+}
+
+/**
+ * Scrub to `time`, then keep simulating the focused effect until every particle has died.
+ * Used when parking a one-shot at the timeline end so burst tails do not linger on screen.
+ */
+export function scrubFocusToSettled(binding: EffectBinding, renderer: BatchedRenderer, time: number): void {
+    scrubFocusTo(binding, renderer, time);
+    const systems = bindingSystems(binding);
+    const step = 1 / 60;
+    const maxExtra = 2;
+    let extra = 0;
+    while (extra < maxExtra) {
+        let alive = 0;
+        for (const system of systems) {
+            alive += system.particleNum;
+        }
+        if (alive === 0) {
+            break;
+        }
+        for (const system of systems) {
+            system.update(step);
+        }
+        extra += step;
+    }
+    renderer.refreshBatches();
 }
 
 /**
@@ -46,6 +88,7 @@ export function scrubFocusTo(binding: EffectBinding, time: number): void {
 export function scrubTo(binding: EffectBinding, renderer: BatchedRenderer, time: number): void {
     binding.restart();
     if (time <= 0) {
+        renderer.refreshBatches();
         return;
     }
     const fixedStep = time > WIDE_STEP_THRESHOLD ? 1 / 30 : 1 / 60;

package/src/core/timeline.ts

@@ -83,8 +83,36 @@ export function computeTimelineRows(binding: EffectBinding): TimelineRow[] {
     return rows;
 }
 
+/** Upper bound on startLife for timeline span (burst/one-shot tail). */
+function estimateMaxStartLife(system: ParticleSystem): number {
+    const life = system.startLife;
+    if (life instanceof ConstantValue) {
+        return Math.max(0, life.value);
+    }
+    if (life instanceof IntervalValue) {
+        return Math.max(life.a, life.b);
+    }
+    return 1;
+}
+
+/** When emission is burst-only, the effect window ends at the last burst time, not full duration. */
+function estimateEmissionEnd(system: ParticleSystem): number {
+    const rate =
+        system.emissionOverTime instanceof ConstantValue ? system.emissionOverTime.value : null;
+    const perMeter =
+        system.emissionOverDistance instanceof ConstantValue ? system.emissionOverDistance.value : null;
+    if ((rate != null && rate > 0) || (perMeter != null && perMeter > 0)) {
+        return system.duration;
+    }
+    if (system.emissionBursts.length === 0) {
+        return system.duration;
+    }
+    return Math.max(...system.emissionBursts.map((burst) => burst.time));
+}
+
 /**
- * Overall timeline ruler span — emission window per track (`startOffset + duration`).
+ * Overall timeline ruler span — worst-case visual tail per track (max startLife, last burst).
+ * Actual playback often ends earlier when interval lives sample short or tracks finish out of phase.
  */
 export function computeTimelineSpan(rows: TimelineRow[]): number {
     let span = 0;
@@ -92,7 +120,7 @@ export function computeTimelineSpan(rows: TimelineRow[]): number {
         if (row.kind !== 'track') {
             continue;
         }
-        span = Math.max(span, row.startOffset + row.duration);
+        span = Math.max(span, row.startOffset + estimateEmissionEnd(row.system) + estimateMaxStartLife(row.system));
     }
     return Math.max(span, MIN_TIMELINE_SPAN);
 }