babylon.quarks-editor 0.17.7

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to the `babylon.quarks-editor` package are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project follows the `quarks.core` 0.x version line.
+
+## [0.17.7] — 2026-07-09
+
+### Added
+
+- First npm release. Shuriken-style effect editor for `babylon.quarks`: headless edit-model
+  core (`.` export) plus an embeddable React UI (`./react` export) — hierarchy panel, stacked
+  module inspector, undo/redo, JSON import/export round-tripping through `QuarksLoader`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soullnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# babylon.quarks-editor
+
+Shuriken-style effect editor for [babylon.quarks](https://www.npmjs.com/package/babylon.quarks): a Unity-like hierarchy of particle systems with a stacked module inspector. Headless edit-model core plus embeddable React UI.
+
+[Live editor](https://soullnik.github.io/babylon.quarks-standalone/editor.html) · [Source](https://github.com/Soullnik/babylon.quarks-standalone/tree/main/packages/babylon.quarks-editor)
+
+## Install
+
+```bash
+npm install babylon.quarks-editor babylon.quarks @babylonjs/core react
+```
+
+## Usage
+
+```tsx
+import {EffectBinding, EffectHistory} from "babylon.quarks-editor";
+import {EffectEditor} from "babylon.quarks-editor/react";
+
+const binding = new EffectBinding(particleSystem);   // your babylon.quarks ParticleSystem
+const history = new EffectHistory();
+history.attach(binding);
+
+<EffectEditor binding={binding} />;
+
+// Serialize to Quarks JSON (round-trips through QuarksLoader):
+const json = binding.exportJSON("MyEffect");
+```
+
+Modules: Main, Emission (bursts), Shape (7 emitter types), Speed/Limit Speed/Force/Rotation over Lifetime, Gravity, Color over Lifetime (gradient), Size over Lifetime (curve), Noise, Sub Emitters, Texture Sheet Animation, Renderer. Multi-system hierarchy with add/remove/rename, undo/redo via `EffectHistory`.
+
+The `.` export is UI-free (edit model, serialization, value/shape/gradient helpers) — usable headless. The `./react` export ships the components; React is a peer dependency, so the same UI can mount in a standalone page or inside a [BabylonJS Editor](https://github.com/BabylonJS/Editor) plugin.
+
+## Textures & meshes (`resolveTexture` / `resolveGeometry`)
+
+The editor never loads assets itself — it defers to host-supplied callbacks so it doesn't need
+an opinion on your CDN, asset pipeline, or loader (`@babylonjs/loaders`, your own backend, etc.):
+
+- `resolveTexture(url) => Texture-like` — turns a picked URL or `data:` URI (from "Custom URL…" /
+  "Load from file…" in the Renderer module) into whatever object you assign as `system.texture`.
+- `resolveGeometry(file) => Promise<GeometryData>` — turns a picked file (from "Load from file…"
+  in the Mesh render mode's geometry dropdown) into vertex buffers: `{positions, indices?, uvs?,
+  normals?}` (typed arrays or plain number arrays).
+- `textureOptions?: {label, url}[]` / `geometryOptions?: {label, positions, indices?, uvs?,
+  normals?}[]` — preset lists shown alongside "Custom URL…" / "Load from file…".
+
+**Signature differs by entry point** — a common source of "works in the demo, throws in my
+host" bugs:
+
+- `QuarksEffectEditor.Show(...)` / `<EffectEditorHost>` call your callbacks with the live
+  `Scene` as a second argument: `resolveTexture: (url, scene) => unknown`,
+  `resolveGeometry: (file, scene) => Promise<GeometryData>`.
+- The lower-level `<EffectEditor>` (no Host wrapper) does **not** pass a scene:
+  `resolveTexture: (url) => unknown`, `resolveGeometry: (file) => Promise<GeometryData>`. If you
+  copy a `Show()`-style resolver that reads its `scene` parameter into a raw `<EffectEditor>`,
+  `scene` is `undefined` and your resolver throws.
+
+Both callbacks are optional, and omitting them doesn't crash the editor — it just hides the
+affected UI: no `resolveTexture` means the Renderer module's Texture row isn't rendered at all,
+and no `resolveGeometry` means "Load from file…" isn't offered for Mesh geometry. The catch: a
+freshly created effect (i.e. `EffectEditorHost`/`Show()` called without `effectJson`) is built
+with `texture: undefined` unless you also pass `textureOptions` + `resolveTexture`, so it's easy
+to end up with an effect that has no visible particles simply because texture loading was never
+wired up. Always pass `resolveTexture` (and `textureOptions` with at least one entry) unless you
+intend every new effect to start textureless.
+
+Reference implementation (from the standalone [`editor.html`](https://github.com/Soullnik/babylon.quarks-standalone/blob/main/examples/src/editorApp.tsx)):
+
+```ts
+resolveTexture: (url, scene) => {
+    const texture = new Texture(url, scene);
+    texture.wrapU = Texture.CLAMP_ADDRESSMODE;
+    texture.wrapV = Texture.CLAMP_ADDRESSMODE;
+    return texture;
+},
+resolveGeometry: async (file, scene) => {
+    const result = await SceneLoader.ImportMeshAsync("", "", file, scene, null, ".glb");
+    const mesh = result.meshes.find((m) => m.getVerticesData(VertexBuffer.PositionKind));
+    // ...extract positions/indices/uvs/normals from `mesh`, dispose the imported nodes, return them
+},
+```
+
+## License
+
+MIT

package/dist/core/binding.d.ts

@@ -0,0 +1,43 @@
+import type { ParticleSystem } from 'babylon.quarks';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { EffectTreeNode } from './effectTree';
+export type EditorListener = () => void;
+/**
+ * Headless edit-model over a live ParticleSystem: mutate through apply() so every
+ * change notifies subscribers (React UI, save indicators, hosts like BabylonJS Editor).
+ */
+export declare class EffectBinding {
+    /** Not `readonly` — `promoteToMain` reassigns this when the current main system is removed. */
+    system: ParticleSystem;
+    /** Systems spawned by sub-emitter behaviors; serialized as children of the root emitter. */
+    readonly subSystems: ParticleSystem[];
+    /** Loaded scene root of the whole effect (Group tree); defaults to the system's emitter. */
+    readonly root: TransformNode;
+    /** Invoked before any mutation — used by EffectHistory to capture undo snapshots. */
+    onBeforeChange?: () => void;
+    private listeners;
+    private revision;
+    constructor(system: ParticleSystem, subSystems?: ParticleSystem[], root?: TransformNode);
+    /** Editor hierarchy tree (groups + emitters) rooted at this effect's scene root. */
+    getTree(): EffectTreeNode;
+    subscribe(listener: EditorListener): () => void;
+    /** Monotonic change counter, usable as a React external-store snapshot. */
+    getRevision(): number;
+    apply(mutate: (system: ParticleSystem) => void): void;
+    addSubSystem(sub: ParticleSystem): void;
+    removeSubSystem(sub: ParticleSystem): void;
+    /**
+     * Swaps which system is "main" — used when the current `system` is about to be removed
+     * but other top-level systems remain. Being "main" vs. a sub-system is otherwise
+     * meaningless to the effect itself (both play/restart/export the same way); it only
+     * exists so there's always a designated fallback system to select.
+     */
+    promoteToMain(next: ParticleSystem): void;
+    private notify;
+    restart(): void;
+    /**
+     * Serializes the effect into the Quarks JSON envelope understood by QuarksLoader,
+     * preserving the loaded group/emitter hierarchy.
+     */
+    exportJSON(name?: string): string;
+}

package/dist/core/binding.js

@@ -0,0 +1,82 @@
+import { buildEffectTree, serializeEffectTree } from './effectTree';
+/**
+ * Headless edit-model over a live ParticleSystem: mutate through apply() so every
+ * change notifies subscribers (React UI, save indicators, hosts like BabylonJS Editor).
+ */
+export class EffectBinding {
+    constructor(system, subSystems = [], root) {
+        /** Systems spawned by sub-emitter behaviors; serialized as children of the root emitter. */
+        this.subSystems = [];
+        this.listeners = new Set();
+        this.revision = 0;
+        this.system = system;
+        this.subSystems.push(...subSystems);
+        this.root = root ?? system.emitter;
+    }
+    /** Editor hierarchy tree (groups + emitters) rooted at this effect's scene root. */
+    getTree() {
+        return buildEffectTree(this.root);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Monotonic change counter, usable as a React external-store snapshot. */
+    getRevision() {
+        return this.revision;
+    }
+    apply(mutate) {
+        this.onBeforeChange?.();
+        mutate(this.system);
+        this.notify();
+    }
+    addSubSystem(sub) {
+        this.subSystems.push(sub);
+        this.notify();
+    }
+    removeSubSystem(sub) {
+        const index = this.subSystems.indexOf(sub);
+        if (index >= 0) {
+            this.subSystems.splice(index, 1);
+        }
+        this.notify();
+    }
+    /**
+     * Swaps which system is "main" — used when the current `system` is about to be removed
+     * but other top-level systems remain. Being "main" vs. a sub-system is otherwise
+     * meaningless to the effect itself (both play/restart/export the same way); it only
+     * exists so there's always a designated fallback system to select.
+     */
+    promoteToMain(next) {
+        const index = this.subSystems.indexOf(next);
+        if (index < 0) {
+            return;
+        }
+        this.subSystems.splice(index, 1, this.system);
+        this.system = next;
+        this.notify();
+    }
+    notify() {
+        this.revision++;
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+    restart() {
+        // Replay every independent system; sub-emitter targets (onlyUsedByOther) are only
+        // reset — their parents re-drive them, so playing them directly would double-emit.
+        for (const system of [this.system, ...this.subSystems]) {
+            system.restart();
+            if (!system.onlyUsedByOther) {
+                system.play();
+            }
+        }
+    }
+    /**
+     * Serializes the effect into the Quarks JSON envelope understood by QuarksLoader,
+     * preserving the loaded group/emitter hierarchy.
+     */
+    exportJSON(name = 'effect') {
+        return serializeEffectTree(this.root, name);
+    }
+}

package/dist/core/collision.d.ts

@@ -0,0 +1,20 @@
+import { Vector3 } from 'babylon.quarks';
+/**
+ * A horizontal ground plane collider. quarks.core's ApplyCollision behavior delegates to a
+ * host-provided `PhysicsResolver` (a global singleton) and ships no collider primitive of its
+ * own, so the editor supplies this — the common "particles bounce off the floor" case.
+ *
+ * `resolve` returns true and fills the surface normal when the point is at or below the plane,
+ * which is exactly what ApplyCollision.update reflects the velocity against.
+ */
+export declare class GroundPlaneResolver {
+    y: number;
+    constructor(y?: number);
+    resolve(position: Vector3, normal: Vector3): boolean;
+}
+/**
+ * Registers (once) a shared ground-plane resolver so ApplyCollision behaviors — whether added
+ * in the inspector or deserialized from imported JSON — have something to collide against.
+ * Idempotent: an already-registered resolver is left untouched and returned.
+ */
+export declare function ensureGroundResolver(): GroundPlaneResolver;

package/dist/core/collision.js

@@ -0,0 +1,39 @@
+import { getPhysicsResolver, setPhysicsResolver } from 'babylon.quarks';
+/**
+ * A horizontal ground plane collider. quarks.core's ApplyCollision behavior delegates to a
+ * host-provided `PhysicsResolver` (a global singleton) and ships no collider primitive of its
+ * own, so the editor supplies this — the common "particles bounce off the floor" case.
+ *
+ * `resolve` returns true and fills the surface normal when the point is at or below the plane,
+ * which is exactly what ApplyCollision.update reflects the velocity against.
+ */
+export class GroundPlaneResolver {
+    constructor(y = 0) {
+        this.y = y;
+    }
+    resolve(position, normal) {
+        if (position.y <= this.y) {
+            normal.set(0, 1, 0);
+            return true;
+        }
+        return false;
+    }
+}
+/**
+ * Registers (once) a shared ground-plane resolver so ApplyCollision behaviors — whether added
+ * in the inspector or deserialized from imported JSON — have something to collide against.
+ * Idempotent: an already-registered resolver is left untouched and returned.
+ */
+export function ensureGroundResolver() {
+    const existing = getPhysicsResolver();
+    if (existing instanceof GroundPlaneResolver) {
+        return existing;
+    }
+    if (existing) {
+        // A host registered its own resolver; don't clobber it, but we can't tweak its floor.
+        return existing;
+    }
+    const resolver = new GroundPlaneResolver(0);
+    setPhysicsResolver(resolver);
+    return resolver;
+}

package/dist/core/colors.d.ts

@@ -0,0 +1,31 @@
+import { ColorOverLife, Gradient, Vector4 } from 'babylon.quarks';
+import type { Behavior } from 'babylon.quarks';
+/** One RGBA stop of the editable gradient (all channels 0..1, pos 0..1). */
+export interface GradientStop {
+    pos: number;
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export declare const DEFAULT_GRADIENT_STOPS: GradientStop[];
+export declare function buildGradient(stops: GradientStop[]): Gradient;
+export declare function buildColorOverLife(stops: GradientStop[]): ColorOverLife;
+export declare function rgbaToVector4(stop: {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}): Vector4;
+export declare function stopToCss(stop: GradientStop): string;
+export declare function stopsToCssGradient(stops: GradientStop[]): string;
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/** Reads RGBA stops back from a Gradient (union of color/alpha key positions). */
+export declare function readGradientStops(gradient: Gradient): GradientStop[];
+/** Finds a behavior of the given quarks type string (e.g. 'ColorOverLife'). */
+export declare function findBehavior<T extends Behavior>(behaviors: Behavior[], type: string): T | undefined;

package/dist/core/colors.js

@@ -0,0 +1,60 @@
+import { ColorOverLife, Gradient, Vector3, Vector4 } from 'babylon.quarks';
+export const DEFAULT_GRADIENT_STOPS = [
+    { pos: 0, r: 1, g: 0.85, b: 0.4, a: 1 },
+    { pos: 1, r: 1, g: 0.25, b: 0.05, a: 0 },
+];
+export function buildGradient(stops) {
+    const sorted = [...stops].sort((a, b) => a.pos - b.pos);
+    return new Gradient(sorted.map((s) => [new Vector3(s.r, s.g, s.b), s.pos]), sorted.map((s) => [s.a, s.pos]));
+}
+export function buildColorOverLife(stops) {
+    return new ColorOverLife(buildGradient(stops));
+}
+export function rgbaToVector4(stop) {
+    return new Vector4(stop.r, stop.g, stop.b, stop.a);
+}
+export function stopToCss(stop) {
+    const c = (v) => Math.round(v * 255);
+    return `rgba(${c(stop.r)}, ${c(stop.g)}, ${c(stop.b)}, ${stop.a.toFixed(2)})`;
+}
+export function stopsToCssGradient(stops) {
+    const sorted = [...stops].sort((a, b) => a.pos - b.pos);
+    const parts = sorted.map((s) => `${stopToCss(s)} ${(s.pos * 100).toFixed(1)}%`);
+    return `linear-gradient(90deg, ${parts.join(', ')})`;
+}
+export function hexToRgb(hex) {
+    const value = hex.replace('#', '');
+    return {
+        r: parseInt(value.slice(0, 2), 16) / 255,
+        g: parseInt(value.slice(2, 4), 16) / 255,
+        b: parseInt(value.slice(4, 6), 16) / 255,
+    };
+}
+export function rgbToHex(r, g, b) {
+    const c = (v) => Math.round(Math.min(1, Math.max(0, v)) * 255)
+        .toString(16)
+        .padStart(2, '0');
+    return `#${c(r)}${c(g)}${c(b)}`;
+}
+/** Reads RGBA stops back from a Gradient (union of color/alpha key positions). */
+export function readGradientStops(gradient) {
+    const positions = new Set();
+    for (const [, pos] of gradient.color.keys) {
+        positions.add(Math.round(pos * 1000) / 1000);
+    }
+    for (const [, pos] of gradient.alpha.keys) {
+        positions.add(Math.round(pos * 1000) / 1000);
+    }
+    const color = new Vector3();
+    return [...positions]
+        .sort((a, b) => a - b)
+        .map((pos) => {
+        gradient.color.genValue(color, pos);
+        const alpha = gradient.alpha.genValue(0, pos);
+        return { pos, r: color.x, g: color.y, b: color.z, a: alpha };
+    });
+}
+/** Finds a behavior of the given quarks type string (e.g. 'ColorOverLife'). */
+export function findBehavior(behaviors, type) {
+    return behaviors.find((b) => b.type === type);
+}

package/dist/core/effectTree.d.ts

@@ -0,0 +1,25 @@
+import type { ParticleSystem } from 'babylon.quarks';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/** A node in the editor's effect hierarchy: a Group (organizational) or a ParticleEmitter. */
+export interface EffectTreeNode {
+    node: TransformNode;
+    name: string;
+    /** Present when the node is a ParticleEmitter. */
+    system?: ParticleSystem;
+    depth: number;
+    children: EffectTreeNode[];
+}
+/** Walks a loaded root TransformNode into the editor tree (groups + emitters). */
+export declare function buildEffectTree(root: TransformNode, depth?: number): EffectTreeNode;
+/** Flattens the tree into the systems it contains, in display order. */
+export declare function collectSystems(tree: EffectTreeNode): ParticleSystem[];
+/**
+ * Serializes an effect tree into the Quarks JSON envelope understood by QuarksLoader,
+ * preserving the group/emitter hierarchy (not flattened).
+ */
+export declare function serializeEffectTree(root: TransformNode, name?: string): string;
+/**
+ * Serializes several effect roots as children of a synthetic group — used when an effect
+ * spans multiple top-level trees (e.g. a demo running several loaded effects at once).
+ */
+export declare function serializeEffectForest(roots: TransformNode[], name?: string): string;

package/dist/core/effectTree.js

@@ -0,0 +1,115 @@
+import { ParticleEmitter } from 'babylon.quarks';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { Matrix, Quaternion } from '@babylonjs/core/Maths/math.vector';
+/** Walks a loaded root TransformNode into the editor tree (groups + emitters). */
+export function buildEffectTree(root, depth = 0) {
+    const system = root instanceof ParticleEmitter ? root.system : undefined;
+    const treeNode = {
+        node: root,
+        name: root.name || (system ? 'emitter' : 'group'),
+        system,
+        depth,
+        children: [],
+    };
+    for (const child of root.getChildren()) {
+        if (child instanceof TransformNode) {
+            treeNode.children.push(buildEffectTree(child, depth + 1));
+        }
+    }
+    return treeNode;
+}
+/** Flattens the tree into the systems it contains, in display order. */
+export function collectSystems(tree) {
+    const out = [];
+    const walk = (node) => {
+        if (node.system) {
+            out.push(node.system);
+        }
+        node.children.forEach(walk);
+    };
+    walk(tree);
+    return out;
+}
+function localMatrix(node) {
+    const rotation = node.rotationQuaternion ?? Quaternion.FromEulerVector(node.rotation);
+    return Matrix.Compose(node.scaling, rotation, node.position).asArray().slice();
+}
+function serializeNode(tree, meta, fallbackUuid) {
+    // Emitter nodes must serialize with the ParticleEmitter's own `.uuid` — that is exactly
+    // what EmitSubParticleSystem.toJSON writes as its target reference, so the two match and
+    // QuarksLoader.linkReferences can re-resolve sub-emitters on reimport.
+    const uuid = tree.system
+        ? tree.node.uuid
+        : (tree.node._quarksUUID ?? fallbackUuid);
+    const children = tree.children.map((child, i) => serializeNode(child, meta, `${fallbackUuid}-${i}`));
+    const base = {
+        uuid,
+        name: tree.name,
+        layers: 1,
+        matrix: localMatrix(tree.node),
+        children: children.length > 0 ? children : undefined,
+    };
+    if (tree.system) {
+        return { ...base, type: 'ParticleEmitter', ps: tree.system.toJSON(meta, { useUrlForImage: true }) };
+    }
+    return { ...base, type: 'Group' };
+}
+/**
+ * Serializes an effect tree into the Quarks JSON envelope understood by QuarksLoader,
+ * preserving the group/emitter hierarchy (not flattened).
+ */
+export function serializeEffectTree(root, name = 'effect') {
+    const meta = { textures: {}, materials: {}, geometries: {} };
+    const object = serializeNode(buildEffectTree(root), meta, `${name}-node`);
+    return finishEnvelope(object, meta);
+}
+/**
+ * Serializes several effect roots as children of a synthetic group — used when an effect
+ * spans multiple top-level trees (e.g. a demo running several loaded effects at once).
+ */
+export function serializeEffectForest(roots, name = 'effect') {
+    if (roots.length === 1) {
+        return serializeEffectTree(roots[0], name);
+    }
+    const meta = { textures: {}, materials: {}, geometries: {} };
+    const children = roots.map((root, i) => serializeNode(buildEffectTree(root), meta, `${name}-node-${i}`));
+    const object = {
+        uuid: `${name}-root`,
+        name,
+        type: 'Group',
+        layers: 1,
+        matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+        children,
+    };
+    return finishEnvelope(object, meta);
+}
+/** Flattens accumulated meta and wraps the serialized object into the Quarks envelope. */
+function finishEnvelope(object, meta) {
+    // toJSON stashes live Texture instances and material records in meta; flatten them into
+    // the serializable images/textures/materials arrays QuarksLoader expects.
+    const images = [];
+    const textures = [];
+    for (const [uuid, tex] of Object.entries(meta.textures)) {
+        const url = tex?.url ?? tex?.name;
+        if (url) {
+            const imageUuid = `${uuid}-image`;
+            images.push({ uuid: imageUuid, url });
+            textures.push({ uuid, image: imageUuid });
+        }
+        else {
+            textures.push({ uuid });
+        }
+    }
+    const materials = Object.values(meta.materials).map((material) => {
+        const { sourceMaterial: _sourceMaterial, ...serializable } = material;
+        return serializable;
+    });
+    return JSON.stringify({
+        metadata: { version: 4.5, type: 'Object3D', generator: 'babylon.quarks-editor' },
+        geometries: Object.values(meta.geometries),
+        materials,
+        textures,
+        images,
+        object,
+    }, null, 2);
+}

package/dist/core/groups.d.ts

@@ -0,0 +1,12 @@
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/**
+ * Groups the given nodes under a new organizational TransformNode. Each node's world
+ * transform is preserved via `setParent` — grouping never moves anything visually, it only
+ * changes the hierarchy so the group can be repositioned/organized as one unit afterwards.
+ */
+export declare function groupNodes(nodes: TransformNode[], name?: string): TransformNode;
+/**
+ * Dissolves a group, reparenting its children onto the group's own parent and disposing the
+ * (now childless) group node. World transform of each child is preserved.
+ */
+export declare function ungroupNode(group: TransformNode): void;

package/dist/core/groups.js

@@ -0,0 +1,27 @@
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/**
+ * Groups the given nodes under a new organizational TransformNode. Each node's world
+ * transform is preserved via `setParent` — grouping never moves anything visually, it only
+ * changes the hierarchy so the group can be repositioned/organized as one unit afterwards.
+ */
+export function groupNodes(nodes, name = 'Group') {
+    const scene = nodes[0].getScene();
+    const group = new TransformNode(name, scene);
+    group.setParent(nodes[0].parent);
+    for (const node of nodes) {
+        node.setParent(group);
+    }
+    return group;
+}
+/**
+ * Dissolves a group, reparenting its children onto the group's own parent and disposing the
+ * (now childless) group node. World transform of each child is preserved.
+ */
+export function ungroupNode(group) {
+    const parent = group.parent;
+    const children = group.getChildren().filter((c) => c instanceof TransformNode);
+    for (const child of children) {
+        child.setParent(parent);
+    }
+    group.dispose(true, false);
+}

package/dist/core/history.d.ts

@@ -0,0 +1,25 @@
+import type { EffectBinding } from './binding';
+/**
+ * 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 declare class EffectHistory {
+    private undoStack;
+    private redoStack;
+    private lastCaptureTime;
+    private binding;
+    /** Points the history at the active binding and hooks snapshot capture. */
+    attach(binding: EffectBinding): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    clear(): void;
+    /** Pushes an undo snapshot; rapid consecutive edits are coalesced into one step. */
+    capture(): void;
+    /** Returns the previous effect state as parsed JSON, or null when nothing to undo. */
+    undo(): unknown | null;
+    /** Returns the next effect state as parsed JSON, or null when nothing to redo. */
+    redo(): unknown | null;
+}