babylon.quarks-editor 0.17.7

package/dist/core/history.js

@@ -0,0 +1,69 @@
+const COALESCE_MS = 400;
+const MAX_DEPTH = 50;
+/**
+ * Snapshot-based undo/redo over serialized effect JSON. Owned by the host (not the
+ * binding) so history survives rebinding when a restore rebuilds the systems.
+ *
+ * Wire-up: call attach() whenever a binding is (re)mounted; on undo()/redo() feed the
+ * returned JSON back through the host's import path and attach the new binding.
+ */
+export class EffectHistory {
+    constructor() {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.lastCaptureTime = 0;
+        this.binding = null;
+    }
+    /** Points the history at the active binding and hooks snapshot capture. */
+    attach(binding) {
+        this.binding = binding;
+        binding.onBeforeChange = () => this.capture();
+    }
+    get canUndo() {
+        return this.undoStack.length > 0;
+    }
+    get canRedo() {
+        return this.redoStack.length > 0;
+    }
+    clear() {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.lastCaptureTime = 0;
+    }
+    /** Pushes an undo snapshot; rapid consecutive edits are coalesced into one step. */
+    capture() {
+        if (!this.binding) {
+            return;
+        }
+        const now = Date.now();
+        if (now - this.lastCaptureTime < COALESCE_MS && this.undoStack.length > 0) {
+            return;
+        }
+        this.lastCaptureTime = now;
+        this.undoStack.push(this.binding.exportJSON());
+        if (this.undoStack.length > MAX_DEPTH) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+    }
+    /** Returns the previous effect state as parsed JSON, or null when nothing to undo. */
+    undo() {
+        if (!this.binding || this.undoStack.length === 0) {
+            return null;
+        }
+        const snapshot = this.undoStack.pop();
+        this.redoStack.push(this.binding.exportJSON());
+        this.lastCaptureTime = 0;
+        return JSON.parse(snapshot);
+    }
+    /** Returns the next effect state as parsed JSON, or null when nothing to redo. */
+    redo() {
+        if (!this.binding || this.redoStack.length === 0) {
+            return null;
+        }
+        const snapshot = this.redoStack.pop();
+        this.undoStack.push(this.binding.exportJSON());
+        this.lastCaptureTime = 0;
+        return JSON.parse(snapshot);
+    }
+}

package/dist/core/loadEffect.d.ts

@@ -0,0 +1,8 @@
+import type { BatchedRenderer, ParticleSystem } from 'babylon.quarks';
+import type { Scene } from '@babylonjs/core/scene';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/** Parses a Quarks JSON export, registers all systems with the renderer and starts playback. */
+export declare function loadEffectFromJson(scene: Scene, renderer: BatchedRenderer, json: unknown, baseUrl?: string): {
+    root: TransformNode;
+    systems: ParticleSystem[];
+};

package/dist/core/loadEffect.js

@@ -0,0 +1,87 @@
+import { ParticleEmitter, QuarksLoader, QuarksUtil } from 'babylon.quarks';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/** `ParticleEmitter`'s constructor default (see babylon.quarks/src/ParticleEmitter.ts) — the
+ * name every emitter gets when the source JSON didn't give it one of its own. */
+const DEFAULT_EMITTER_NAME = 'particleEmitter';
+function hasMeaningfulName(node) {
+    return !!node.name && node.name !== DEFAULT_EMITTER_NAME;
+}
+function groupChildren(node) {
+    return node.getChildren().filter((c) => c instanceof TransformNode);
+}
+/** Reparents `only` onto `parent`, transferring the outgoing node's name if `only` doesn't
+ * already have a meaningful one of its own, then disposes the now-empty wrapper. World
+ * transform is preserved via `setParent`. */
+function collapseInto(wrapper, only, parent) {
+    if (!hasMeaningfulName(only) && hasMeaningfulName(wrapper)) {
+        only.name = wrapper.name;
+    }
+    only.setParent(parent);
+    wrapper.dispose(true, false);
+}
+/**
+ * Collapses redundant organizational groups left over by importers — Unity's
+ * one-GameObject-per-component convention turns every visual layer into its own Group, so a
+ * single particle system becomes "Sparks" > unnamed emitter, and a component quarks doesn't
+ * understand (e.g. a Light) becomes an empty Group with nothing under it. Recurses
+ * bottom-up so nested wrapper chains collapse all the way down. The tree root itself is
+ * handled separately by `promoteIfSingleChildRoot`, since collapsing it means returning a
+ * different node as the effect's root.
+ */
+function flattenRedundantGroups(node) {
+    for (const child of node.getChildren()) {
+        if (child instanceof TransformNode) {
+            flattenRedundantGroups(child);
+        }
+    }
+    if (node instanceof ParticleEmitter || !node.parent) {
+        return;
+    }
+    const children = groupChildren(node);
+    if (children.length === 0) {
+        node.dispose(true, false);
+        return;
+    }
+    if (children.length !== 1) {
+        return;
+    }
+    const only = children[0];
+    if (only instanceof ParticleEmitter && only.getChildren().length > 0) {
+        return;
+    }
+    collapseInto(node, only, node.parent);
+}
+/** If the tree root itself only ever wraps a single child (after `flattenRedundantGroups`
+ * has settled everything below it), that wrapper adds a tree level with nothing to organize —
+ * promote the child to be the new root instead. Loops in case that child is, in turn, also a
+ * single-child wrapper. */
+function promoteIfSingleChildRoot(root) {
+    let current = root;
+    while (!(current instanceof ParticleEmitter)) {
+        const children = groupChildren(current);
+        if (children.length !== 1) {
+            break;
+        }
+        const only = children[0];
+        const parent = current.parent;
+        collapseInto(current, only, parent);
+        current = only;
+    }
+    return current;
+}
+/** Parses a Quarks JSON export, registers all systems with the renderer and starts playback. */
+export function loadEffectFromJson(scene, renderer, json, baseUrl = '') {
+    const loader = new QuarksLoader(scene, { baseUrl });
+    let root = loader.parse(json, baseUrl);
+    flattenRedundantGroups(root);
+    root = promoteIfSingleChildRoot(root);
+    const systems = [];
+    QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
+        const system = emitter.system;
+        renderer.addSystem(system);
+        systems.push(system);
+    });
+    QuarksUtil.restart(root);
+    QuarksUtil.play(root);
+    return { root, systems };
+}

package/dist/core/scrub.d.ts

@@ -0,0 +1,11 @@
+import type { BatchedRenderer } from 'babylon.quarks';
+import type { EffectBinding } from './binding';
+/**
+ * Approximate timeline scrub: replays every system from t=0 up to `time` using the existing
+ * simulation loop. Not frame-exact (spawn/burst randomization is unseeded), but reuses
+ * `EffectBinding.restart()` and `BatchedRenderer.update()` verbatim — no new engine primitive.
+ *
+ * `ParticleSystem.update()` clamps its own `delta` to 0.1s per call, so a single big step
+ * can't reach `time` directly; must step through in small increments instead.
+ */
+export declare function scrubTo(binding: EffectBinding, renderer: BatchedRenderer, time: number): void;

package/dist/core/scrub.js

@@ -0,0 +1,24 @@
+const WIDE_STEP_THRESHOLD = 8;
+/**
+ * Approximate timeline scrub: replays every system from t=0 up to `time` using the existing
+ * simulation loop. Not frame-exact (spawn/burst randomization is unseeded), but reuses
+ * `EffectBinding.restart()` and `BatchedRenderer.update()` verbatim — no new engine primitive.
+ *
+ * `ParticleSystem.update()` clamps its own `delta` to 0.1s per call, so a single big step
+ * can't reach `time` directly; must step through in small increments instead.
+ */
+export function scrubTo(binding, renderer, time) {
+    binding.restart();
+    if (time <= 0) {
+        return;
+    }
+    const fixedStep = time > WIDE_STEP_THRESHOLD ? 1 / 30 : 1 / 60;
+    const steps = Math.floor(time / fixedStep);
+    for (let i = 0; i < steps; i++) {
+        renderer.update(fixedStep);
+    }
+    const remainder = time - steps * fixedStep;
+    if (remainder > 0) {
+        renderer.update(remainder);
+    }
+}

package/dist/core/shapes.d.ts

@@ -0,0 +1,31 @@
+import type { EmitterShape } from 'babylon.quarks';
+import { EmitterMode } from 'babylon.quarks';
+import type { Mesh } from '@babylonjs/core/Meshes/mesh';
+export type ShapeType = 'point' | 'sphere' | 'hemisphere' | 'cone' | 'circle' | 'donut' | 'rectangle' | 'grid' | 'mesh_surface';
+export declare const SHAPE_TYPES: Array<{
+    value: ShapeType;
+    label: string;
+}>;
+export interface ShapeParams {
+    radius: number;
+    arc: number;
+    thickness: number;
+    angle: number;
+    donutRadius: number;
+    width: number;
+    height: number;
+    mode: EmitterMode;
+    spread: number;
+    column: number;
+    row: number;
+    mesh?: Mesh;
+}
+export declare const DEFAULT_SHAPE_PARAMS: ShapeParams;
+export declare function getShapeType(shape: EmitterShape): ShapeType;
+export declare function readShapeParams(shape: EmitterShape): ShapeParams;
+/** Which parameters are relevant per shape type (drives the UI). `mesh_surface`'s mesh
+ * reference isn't a NumberField, so it's handled separately by the Shape module. */
+export declare const SHAPE_PARAM_KEYS: {
+    [K in ShapeType]: Array<keyof ShapeParams>;
+};
+export declare function createShape(type: ShapeType, params: ShapeParams): EmitterShape;

package/dist/core/shapes.js

@@ -0,0 +1,98 @@
+import { CircleEmitter, ConeEmitter, DonutEmitter, GridEmitter, HemisphereEmitter, MeshSurfaceEmitter, PointEmitter, RectangleEmitter, SphereEmitter, } from 'babylon.quarks';
+import { EmitterMode } from 'babylon.quarks';
+export const SHAPE_TYPES = [
+    { value: 'cone', label: 'Cone' },
+    { value: 'sphere', label: 'Sphere' },
+    { value: 'hemisphere', label: 'Hemisphere' },
+    { value: 'circle', label: 'Circle' },
+    { value: 'donut', label: 'Donut' },
+    { value: 'rectangle', label: 'Rectangle' },
+    { value: 'grid', label: 'Grid' },
+    { value: 'mesh_surface', label: 'Mesh surface' },
+    { value: 'point', label: 'Point' },
+];
+export const DEFAULT_SHAPE_PARAMS = {
+    radius: 0.3,
+    arc: Math.PI * 2,
+    thickness: 1,
+    angle: 0.5,
+    donutRadius: 0.1,
+    width: 1,
+    height: 1,
+    mode: EmitterMode.Random,
+    spread: 0,
+    column: 10,
+    row: 10,
+    mesh: undefined,
+};
+export function getShapeType(shape) {
+    const type = shape.type ?? 'point';
+    return (SHAPE_TYPES.some((s) => s.value === type) ? type : 'point');
+}
+export function readShapeParams(shape) {
+    const anyShape = shape;
+    const num = (key, fallback) => (typeof anyShape[key] === 'number' ? anyShape[key] : fallback);
+    return {
+        radius: num('radius', DEFAULT_SHAPE_PARAMS.radius),
+        mode: num('mode', DEFAULT_SHAPE_PARAMS.mode),
+        spread: num('spread', DEFAULT_SHAPE_PARAMS.spread),
+        arc: num('arc', DEFAULT_SHAPE_PARAMS.arc),
+        thickness: num('thickness', DEFAULT_SHAPE_PARAMS.thickness),
+        angle: num('angle', DEFAULT_SHAPE_PARAMS.angle),
+        donutRadius: num('donutRadius', DEFAULT_SHAPE_PARAMS.donutRadius),
+        width: num('width', DEFAULT_SHAPE_PARAMS.width),
+        height: num('height', DEFAULT_SHAPE_PARAMS.height),
+        column: num('column', DEFAULT_SHAPE_PARAMS.column),
+        row: num('row', DEFAULT_SHAPE_PARAMS.row),
+        mesh: anyShape.mesh,
+    };
+}
+/** Which parameters are relevant per shape type (drives the UI). `mesh_surface`'s mesh
+ * reference isn't a NumberField, so it's handled separately by the Shape module. */
+export const SHAPE_PARAM_KEYS = {
+    point: [],
+    sphere: ['radius', 'arc', 'thickness'],
+    hemisphere: ['radius', 'arc', 'thickness'],
+    cone: ['radius', 'arc', 'thickness', 'angle'],
+    circle: ['radius', 'arc', 'thickness'],
+    donut: ['radius', 'arc', 'thickness', 'donutRadius'],
+    rectangle: ['width', 'height'],
+    grid: ['width', 'height', 'column', 'row'],
+    mesh_surface: [],
+};
+export function createShape(type, params) {
+    switch (type) {
+        case 'point':
+            return new PointEmitter();
+        case 'sphere':
+            return new SphereEmitter({ radius: params.radius, arc: params.arc, thickness: params.thickness, mode: params.mode, spread: params.spread });
+        case 'hemisphere':
+            return new HemisphereEmitter({ radius: params.radius, arc: params.arc, thickness: params.thickness, mode: params.mode, spread: params.spread });
+        case 'cone':
+            return new ConeEmitter({
+                radius: params.radius,
+                arc: params.arc,
+                thickness: params.thickness,
+                angle: params.angle,
+                mode: params.mode,
+                spread: params.spread,
+            });
+        case 'circle':
+            return new CircleEmitter({ radius: params.radius, arc: params.arc, thickness: params.thickness, mode: params.mode, spread: params.spread });
+        case 'donut':
+            return new DonutEmitter({
+                radius: params.radius,
+                arc: params.arc,
+                thickness: params.thickness,
+                donutRadius: params.donutRadius,
+                mode: params.mode,
+                spread: params.spread,
+            });
+        case 'rectangle':
+            return new RectangleEmitter({ width: params.width, height: params.height, mode: params.mode, spread: params.spread });
+        case 'grid':
+            return new GridEmitter({ width: params.width, height: params.height, column: params.column, row: params.row });
+        case 'mesh_surface':
+            return new MeshSurfaceEmitter(params.mesh);
+    }
+}

package/dist/core/systems.d.ts

@@ -0,0 +1,25 @@
+import { ParticleSystem } from 'babylon.quarks';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { EffectBinding } from './binding';
+export interface ChildSystemOptions {
+    name?: string;
+    /** One-shot burst (sub-emitter target) instead of a looping stream. */
+    oneShot?: boolean;
+    /** Attach point override — defaults to `parent.emitter`. Lets a new system land as a
+     * sibling under a group node instead of nesting under an existing system. */
+    parentNode?: TransformNode;
+}
+/**
+ * Creates a child system sharing the parent's scene/texture/blending, parented to the
+ * parent emitter (or `options.parentNode` when given) — the Unity pattern where an effect is
+ * a hierarchy of systems and groups.
+ */
+export declare function createChildSystem(parent: ParticleSystem, options?: ChildSystemOptions): ParticleSystem;
+/**
+ * Strips EmitSubParticleSystem behaviors that point at any of the removed systems, so
+ * deleting a sub-emitter target never leaves a dangling reference (which crashes the next
+ * update with `reading 'duration'` on the disposed emitter).
+ */
+export declare function unlinkSubEmitterReferences(systems: ParticleSystem[], removed: ParticleSystem[]): void;
+/** Disposes the given systems, first unlinking any sub-emitter behaviors that target them. */
+export declare function removeSystems(binding: EffectBinding, targets: ParticleSystem[], onSelect: (system: ParticleSystem) => void): void;

package/dist/core/systems.js

@@ -0,0 +1,76 @@
+import { ConeEmitter, ConstantColor, ConstantValue, IntervalValue, ParticleSystem, RenderMode, Vector4, } from 'babylon.quarks';
+/**
+ * Creates a child system sharing the parent's scene/texture/blending, parented to the
+ * parent emitter (or `options.parentNode` when given) — the Unity pattern where an effect is
+ * a hierarchy of systems and groups.
+ */
+export function createChildSystem(parent, options = {}) {
+    const oneShot = options.oneShot ?? false;
+    const child = new ParticleSystem({
+        scene: parent.emitter.getScene(),
+        duration: oneShot ? 1 : parent.duration,
+        looping: !oneShot,
+        startLife: new IntervalValue(0.3, oneShot ? 0.6 : 1.2),
+        startSpeed: new IntervalValue(1, 3),
+        startSize: new IntervalValue(0.05, 0.2),
+        startColor: new ConstantColor(new Vector4(1, 0.9, 0.6, 1)),
+        emissionOverTime: new ConstantValue(oneShot ? 0 : 30),
+        emissionBursts: oneShot ? [{ time: 0, count: new ConstantValue(8), cycle: 1, interval: 0.01, probability: 1 }] : [],
+        shape: new ConeEmitter({ radius: 0.1, angle: Math.PI / 3 }),
+        renderMode: RenderMode.BillBoard,
+        texture: parent.texture ?? undefined,
+        transparent: true,
+        blendMode: parent.blending,
+        worldSpace: true,
+    });
+    child.emitter.name = options.name ?? (oneShot ? 'sub-emitter' : 'child-system');
+    if (oneShot) {
+        child.onlyUsedByOther = true;
+    }
+    child.emitter.parent = options.parentNode ?? parent.emitter;
+    return child;
+}
+/**
+ * Strips EmitSubParticleSystem behaviors that point at any of the removed systems, so
+ * deleting a sub-emitter target never leaves a dangling reference (which crashes the next
+ * update with `reading 'duration'` on the disposed emitter).
+ */
+export function unlinkSubEmitterReferences(systems, removed) {
+    const removedEmitters = new Set(removed.map((system) => system.emitter));
+    for (const system of systems) {
+        const behaviors = system.behaviors;
+        for (let i = behaviors.length - 1; i >= 0; i--) {
+            const behavior = behaviors[i];
+            if (behavior.type === 'EmitSubParticleSystem' && removedEmitters.has(behavior.subParticleSystem)) {
+                behaviors.splice(i, 1);
+            }
+        }
+    }
+}
+/** Disposes the given systems, first unlinking any sub-emitter behaviors that target them. */
+export function removeSystems(binding, targets, onSelect) {
+    // binding.system is "removable" too as long as some other top-level system can take over
+    // as the new main — being main vs. sub is an internal bookkeeping detail, not something
+    // that should make one arbitrary track un-deletable in the UI.
+    if (targets.includes(binding.system)) {
+        const replacement = binding.subSystems.find((s) => !targets.includes(s) && !s.onlyUsedByOther);
+        if (replacement) {
+            binding.promoteToMain(replacement);
+        }
+    }
+    const removable = targets.filter((system) => binding.subSystems.includes(system));
+    if (removable.length === 0) {
+        return;
+    }
+    binding.apply(() => {
+        unlinkSubEmitterReferences([binding.system, ...binding.subSystems], removable);
+        for (const system of removable) {
+            system._renderer?.deleteSystem(system);
+            system.dispose();
+        }
+    });
+    for (const system of removable) {
+        binding.removeSubSystem(system);
+    }
+    onSelect(binding.system);
+}

package/dist/core/textureExport.d.ts

@@ -0,0 +1,9 @@
+import type { Texture } from '@babylonjs/core/Materials/Textures/texture';
+/**
+ * Ensures a texture's `.url` can be reloaded in a different Scene/Engine, baking its live
+ * GPU pixels into a real base64 PNG data URI when it currently only carries Babylon's
+ * internal placeholder url (see isPortableUrl). No-ops for textures that already have a
+ * fetchable or real `data:` url. Call before serializing a scene that will be reloaded
+ * elsewhere — e.g. the demo viewer's "Open in editor" handoff, which navigates to a new page.
+ */
+export declare function ensurePortableTextureUrl(texture: Texture): Promise<void>;

package/dist/core/textureExport.js

@@ -0,0 +1,58 @@
+const bakedUrls = new WeakMap();
+/**
+ * Babylon's glTF loader gives embedded (base64-in-buffer) images a placeholder `data:` url
+ * (e.g. `data:leave.glb#image0`) that only works as an in-memory cache key paired with the
+ * pixel buffer it loaded alongside — it has no real payload, so a fresh Scene/Engine (e.g.
+ * after "Open in editor" navigates to a new page) can't refetch or reconstruct it from that
+ * string. Real data URIs always carry a comma-delimited payload; this placeholder never does.
+ */
+function isPortableUrl(url) {
+    if (!url) {
+        return false;
+    }
+    return !url.startsWith('data:') || url.includes(',');
+}
+/**
+ * Ensures a texture's `.url` can be reloaded in a different Scene/Engine, baking its live
+ * GPU pixels into a real base64 PNG data URI when it currently only carries Babylon's
+ * internal placeholder url (see isPortableUrl). No-ops for textures that already have a
+ * fetchable or real `data:` url. Call before serializing a scene that will be reloaded
+ * elsewhere — e.g. the demo viewer's "Open in editor" handoff, which navigates to a new page.
+ */
+export async function ensurePortableTextureUrl(texture) {
+    if (isPortableUrl(texture.url)) {
+        return;
+    }
+    const cached = bakedUrls.get(texture);
+    if (cached) {
+        texture.url = cached;
+        return;
+    }
+    const dataUrl = await bakeTextureToDataUrl(texture);
+    if (dataUrl) {
+        bakedUrls.set(texture, dataUrl);
+        texture.url = dataUrl;
+    }
+}
+async function bakeTextureToDataUrl(texture) {
+    const size = texture.getSize();
+    if (!size.width || !size.height) {
+        return undefined;
+    }
+    const pixels = await texture.readPixels();
+    if (!(pixels instanceof Uint8Array || pixels instanceof Uint8ClampedArray)) {
+        return undefined;
+    }
+    const canvas = document.createElement('canvas');
+    canvas.width = size.width;
+    canvas.height = size.height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        return undefined;
+    }
+    // Copy (rather than wrap) so the result is backed by a plain ArrayBuffer — ImageData
+    // rejects the SharedArrayBuffer-compatible view type `readPixels` may hand back.
+    const bytes = new Uint8ClampedArray(pixels);
+    ctx.putImageData(new ImageData(bytes, size.width, size.height), 0, 0);
+    return canvas.toDataURL('image/png');
+}

package/dist/core/timeline.d.ts

@@ -0,0 +1,35 @@
+import type { ParticleSystem } from 'babylon.quarks';
+import type { FunctionValueGenerator, ValueGenerator } from 'babylon.quarks';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { EffectBinding } from './binding';
+export type TimelineRow = {
+    kind: 'group';
+    node: TransformNode;
+    name: string;
+    depth: number;
+} | {
+    kind: 'track';
+    node: TransformNode;
+    system: ParticleSystem;
+    name: string;
+    depth: number;
+    isRoot: boolean;
+    removable: boolean;
+    startOffset: number;
+    startOffsetVariable: boolean;
+    duration: number;
+    looping: boolean;
+};
+/**
+ * Reads a representative start-delay value for display without invoking the generator's
+ * stateful `genValue` (IntervalValue caches its sampled slot on first call and returns NaN
+ * on a later call with a fresh memory array, so it can't be safely re-read on every render).
+ */
+export declare function computeStartOffset(gen: ValueGenerator | FunctionValueGenerator): {
+    value: number;
+    startOffsetVariable: boolean;
+};
+/** Flattens the effect's group/emitter tree into display rows, preserving tree-walk order. */
+export declare function computeTimelineRows(binding: EffectBinding): TimelineRow[];
+/** Overall visible timeline span: the furthest track extent, floored at a sane minimum. */
+export declare function computeTimelineSpan(rows: TimelineRow[]): number;

package/dist/core/timeline.js

@@ -0,0 +1,69 @@
+import { ConstantValue, IntervalValue } from 'babylon.quarks';
+const MIN_TIMELINE_SPAN = 4;
+/**
+ * Reads a representative start-delay value for display without invoking the generator's
+ * stateful `genValue` (IntervalValue caches its sampled slot on first call and returns NaN
+ * on a later call with a fresh memory array, so it can't be safely re-read on every render).
+ */
+export function computeStartOffset(gen) {
+    if (gen instanceof ConstantValue) {
+        return { value: gen.value, startOffsetVariable: false };
+    }
+    if (gen instanceof IntervalValue) {
+        return { value: Math.min(gen.a, gen.b), startOffsetVariable: false };
+    }
+    return { value: 0, startOffsetVariable: true };
+}
+/**
+ * Whether a track can be removed. Sub-systems always can; the designated "main" system can
+ * too as long as another top-level system remains to take over that role — being main vs.
+ * sub is an internal bookkeeping detail (see EffectBinding.promoteToMain), not something that
+ * should make one arbitrary track permanently un-deletable in the UI.
+ */
+function isRemovable(binding, system) {
+    if (binding.subSystems.includes(system)) {
+        return true;
+    }
+    if (system === binding.system) {
+        return binding.subSystems.some((s) => !s.onlyUsedByOther);
+    }
+    return false;
+}
+/** Flattens the effect's group/emitter tree into display rows, preserving tree-walk order. */
+export function computeTimelineRows(binding) {
+    const rows = [];
+    const walk = (node) => {
+        if (node.system) {
+            const { value, startOffsetVariable } = computeStartOffset(node.system.startDelay);
+            rows.push({
+                kind: 'track',
+                node: node.node,
+                system: node.system,
+                name: node.name,
+                depth: node.depth,
+                isRoot: node.node === binding.root,
+                removable: isRemovable(binding, node.system),
+                startOffset: value,
+                startOffsetVariable,
+                duration: node.system.duration,
+                looping: node.system.looping,
+            });
+        }
+        else {
+            rows.push({ kind: 'group', node: node.node, name: node.name, depth: node.depth });
+        }
+        node.children.forEach(walk);
+    };
+    walk(binding.getTree());
+    return rows;
+}
+/** Overall visible timeline span: the furthest track extent, floored at a sane minimum. */
+export function computeTimelineSpan(rows) {
+    let span = 0;
+    for (const row of rows) {
+        if (row.kind === 'track') {
+            span = Math.max(span, row.startOffset + row.duration);
+        }
+    }
+    return Math.max(span, MIN_TIMELINE_SPAN);
+}

package/dist/core/values.d.ts

@@ -0,0 +1,31 @@
+import { PiecewiseBezier } from 'babylon.quarks';
+import type { FunctionValueGenerator, ValueGenerator } from 'babylon.quarks';
+export type ScalarGenerator = ValueGenerator | FunctionValueGenerator;
+export type ScalarMode = 'constant' | 'random' | 'curve';
+/** Editable snapshot of a scalar value generator. */
+export interface ScalarValueState {
+    mode: ScalarMode;
+    /** Constant value (mode: constant). */
+    value: number;
+    /** Random range (mode: random). */
+    min: number;
+    max: number;
+    /** Cubic bezier control values over normalized lifetime (mode: curve). */
+    curve: [number, number, number, number];
+}
+export declare function readScalar(generator: ScalarGenerator | undefined): ScalarValueState;
+export declare function buildScalar(state: ScalarValueState): ScalarGenerator;
+/** One segment of a piecewise bezier curve: start x (0..1) + four control values. */
+export interface CurvePiece {
+    start: number;
+    p: [number, number, number, number];
+}
+/** Reads pieces from a PiecewiseBezier (or synthesizes one segment for other generators). */
+export declare function readPieces(generator: ScalarGenerator | undefined): CurvePiece[];
+export declare function buildCurve(pieces: CurvePiece[]): PiecewiseBezier;
+/** Splits the piece containing x into two exact halves using Bezier.split. */
+export declare function splitPieces(pieces: CurvePiece[], x: number): CurvePiece[];
+/** Removes the boundary at pieces[index].start by merging with the previous piece. */
+export declare function mergePieces(pieces: CurvePiece[], index: number): CurvePiece[];
+/** Samples a cubic bezier defined by four control values at normalized t. */
+export declare function sampleCurve(curve: [number, number, number, number], t: number): number;