@onerjs/gui-editor 8.53.5 → 8.53.6

package/dist/babylon.guiEditor.module.d.ts

@@ -2158,6 +2158,370 @@ export interface ISplitContainerProps {
  */
 export const SplitContainer: React.FC<PropsWithChildren<ISplitContainerProps>>;
 
+}
+declare module "@onerjs/gui-editor/projects/projectFile" {
+import "@onerjs/core/Loading/Plugins/babylonFileLoader";
+import { Scene } from "@onerjs/core/scene";
+import { ISerializedSmartAssetMap } from "@onerjs/core/SmartAssets/smartAssetSerializer";
+import { IOverrideEntry } from "@onerjs/gui-editor/projects/overrideEntry";
+/**
+ * ## `.babylonproj` project file format
+ *
+ * The `.babylonproj` zip on disk packages three layers:
+ * 1. **SmartAsset registry** — URL references to external assets (glb/gltf/textures
+ *    loaded via SAM). Local blob/data assets are bundled inside the zip and
+ *    extracted to fresh blob URLs on load.
+ * 2. **OverrideManager state** — declarative property overrides applied after load.
+ * 3. **Companion `.babylon`** — meshes, lights, cameras, transform nodes, and
+ *    materials that are *not* tracked by SAM (i.e. user-created scene content).
+ *    Plus a `companionBindings` side table mapping material texture slots back
+ *    to SAM-tracked textures so re-attachment works without embedding texture
+ *    bytes in the companion.
+ *
+ * ### What round-trips cleanly
+ * - SAM-tracked assets (re-fetched from their URLs or extracted from the zip)
+ * - User-created `Mesh` geometry, `Material`s (Standard/PBR/Multi/Node), and
+ *   `*Texture` slot bindings to SAM textures
+ * - `Light`s, `Camera`s, `TransformNode`s, scene/material image processing,
+ *   clear color, fog, environment intensity
+ * - Property overrides on any of the above
+ *
+ * ### Known gaps (not preserved on save/load)
+ * - `PostProcess` attachments to cameras (a post-process attaches to a *specific*
+ *   camera instance; we dispose+recreate cameras, leaving post-processes orphaned).
+ * - `AdvancedDynamicTexture` GUI controls — not in `.babylon` format.
+ * - Audio (`Sound` / `AudioEngine` state).
+ * - Particle systems with runtime state, baked vertex animations.
+ * - Complex shader-driven content like GaussianSplatting: the mesh round-trips
+ *   but its companion utility materials (`gaussianSplattingDepth`, `ProxyMaterial`)
+ *   get duplicated on each load cycle.
+ * - Skeleton animation playback state.
+ *
+ * If you hit a "the scene looks different after load" issue, it's almost
+ * certainly one of the gaps above rather than camera or mesh state drift.
+ */
+/**
+ * Reserved smart asset key for user-created objects (materials, lights, cameras)
+ * that are persisted as a companion `.babylon` file alongside the project JSON.
+ */
+export const ProjectLocalsKey = "__project_locals__";
+/**
+ * The result of serializing a project. Contains the project JSON and,
+ * if the scene has user-created objects, a companion `.babylon` blob.
+ */
+export interface IProjectBundle {
+    /** The project JSON document (assets + overrides, no embedded scene data). */
+    readonly project: ISerializedProject;
+    /**
+     * A companion `.babylon` file containing user-created objects not owned by
+     * any smart asset. Undefined if there are no such objects.
+     */
+    readonly companionBabylon?: Blob;
+}
+/**
+ * Maps each user-created material (by name) to its texture-slot bindings.
+ * A binding records "this `*Texture` slot on this material should be
+ * re-attached to the SmartAsset registered under this key" so that texture
+ * references survive a save/load round-trip without embedding the texture
+ * data inside the companion `.babylon`.
+ */
+export type CompanionTextureBindings = Record<string, Record<string, string>>;
+/**
+ * A versioned project file that composes a smart asset map with overrides.
+ * This is the unified on-disk format for persisting a complete project.
+ */
+export interface ISerializedProject {
+    /** Schema version. Must be 2 for the current version. */
+    readonly version: 2;
+    /** Smart asset key→URL mappings (from SmartAssetManager). */
+    readonly assets: ISerializedSmartAssetMap["assets"];
+    /** Property overrides (from OverrideManager). */
+    readonly overrides: IOverrideEntry[];
+    /**
+     * Optional bindings that re-attach SmartAsset-tracked textures to
+     * user-created material slots after the companion `.babylon` loads.
+     * Omitted when no user-created material references a SmartAsset texture.
+     */
+    readonly companionBindings?: CompanionTextureBindings;
+}
+/**
+ * Serializes a scene's smart asset map and override registry into a project
+ * bundle. User-created objects (materials, lights, cameras not owned by any
+ * smart asset) are serialized into a companion `.babylon` file rather than
+ * embedded in the project JSON.
+ *
+ * Both managers are looked up (and created if missing) via their respective
+ * `Get…Manager(scene)` accessors, so this function can be called on any scene.
+ *
+ * @param scene - The scene to serialize.
+ * @param baseUrl - Optional base URL for making asset paths relative.
+ * @returns A project bundle containing the JSON document and optional companion file.
+ */
+export function SerializeProject(scene: Scene, baseUrl?: string): IProjectBundle;
+/**
+ * Loads a project file from a URL, File, or pre-parsed object.
+ * Registers all asset entries on the scene's SmartAssetManager, loads all
+ * assets (including the companion `.babylon` for user-created objects), then
+ * applies all overrides via the OverrideManager.
+ *
+ * For loading the `.babylonproj` zip on-disk format, use {@link LoadProjectFileAsync}
+ * instead — it extracts the zip and then calls this function with the embedded
+ * JSON document.
+ *
+ * @param scene - The scene to populate.
+ * @param source - A URL string, File object, or pre-parsed ISerializedProject.
+ * @param rootUrl - Optional root URL for resolving relative asset paths.
+ */
+export function LoadProjectAsync(scene: Scene, source: string | File | ISerializedProject, rootUrl?: string): Promise<void>;
+/**
+ * Validates and parses a serialized project document.
+ * @param data - The raw data to validate (typically parsed JSON).
+ * @returns The validated project document.
+ * @throws If the data does not conform to the expected schema.
+ */
+export function DeserializeProject(data: unknown): ISerializedProject;
+/**
+ * Serializes a scene's project (smart assets + overrides) into a `.babylonproj`
+ * zip bundle.
+ *
+ * The zip contains:
+ * - `project.json` — the project document (assets + overrides)
+ * - `__project_locals__.babylon` — companion file for user-created objects (if any)
+ * - Bundled local asset files (blobs the user dragged in from disk)
+ *
+ * Remote URLs (http/https) are left as references and not bundled.
+ *
+ * @param scene - The scene to serialize.
+ * @returns A Blob containing the zip bundle.
+ */
+export function SaveProjectFileAsync(scene: Scene): Promise<Blob>;
+/**
+ * Loads a `.babylonproj` zip bundle into a scene. Extracts all files, creates
+ * blob URLs for bundled assets, and loads the project through SAM.
+ *
+ * @param scene - The scene to load the project into.
+ * @param zipFile - The `.babylonproj` zip file to load.
+ */
+export function LoadProjectFileAsync(scene: Scene, zipFile: File): Promise<void>;
+
+}
+declare module "@onerjs/gui-editor/projects/overrideManager" {
+import { Scene } from "@onerjs/core/scene";
+import { Observable, Observer } from "@onerjs/core/Misc/observable";
+import { IOverrideEntry, OverrideTargetType } from "@onerjs/gui-editor/projects/overrideEntry";
+/**
+ * Stateful handle for a scene's property override registry.
+ *
+ * Override behavior is exposed through module-level functions rather than
+ * class methods so callers can import only the operations they need.
+ *
+ * Overrides are property diffs applied to scene objects identified by name.
+ * They persist across reloads and are typically saved alongside a project
+ * file. The override manager is fully independent of any other scene
+ * subsystem (SmartAssetManager, loaders, etc.) — it works with any object
+ * in the scene's standard collections (meshes, materials, lights, …)
+ * regardless of how that object was created.
+ *
+ * When multiple objects share a name (e.g. two materials both called
+ * "Default" loaded from different glTFs), {@link IOverrideEntry.targetIndex}
+ * disambiguates: it stores the object's position among same-named siblings
+ * at capture time and is used to pick the correct one at apply time.
+ *
+ * @example
+ * ```typescript
+ * AddOverride(scene, {
+ *     targetType: "materials",
+ *     targetName: "canPaint",
+ *     targetIndex: 0,
+ *     propertyPath: "albedoColor",
+ *     value: [1, 0, 0],
+ * });
+ * ```
+ */
+export type OverrideManager = {
+    /**
+     * The scene this manager is attached to.
+     */
+    readonly scene: Scene;
+    /**
+     * Fires whenever the override registry or applied state changes.
+     */
+    readonly onChangedObservable: Observable<void>;
+};
+/**
+ * Returns the OverrideManager attached to the given scene, creating and
+ * attaching one if none exists.
+ * @param scene - The scene to look up or attach a manager to.
+ * @returns The existing or newly created OverrideManager.
+ */
+export function GetOverrideManager(scene: Scene): OverrideManager;
+/**
+ * Adds an observer that is notified whenever an OverrideManager is created.
+ * @param callback - The callback to invoke with each newly created manager.
+ * @returns The observer registration.
+ */
+export function AddOverrideManagerCreatedObserver(callback: (manager: OverrideManager) => void): Observer<OverrideManager>;
+/**
+ * Options for {@link AddOverride}.
+ */
+export type AddOverrideOptions = {
+    /**
+     * If the `originalValue` field is present, the override is recorded *without*
+     * re-applying it (the caller is presumed to have already mutated the entity)
+     * and the field's content is captured as the property's pre-override
+     * "original" so {@link RemoveOverride} can restore it later.
+     *
+     * Inspector-driven edits use this: by the time `onPropertyChanged` fires,
+     * the binding has already written the new value, but it still has the prior
+     * value in hand. Without this seeding path, an override created via
+     * Inspector could never be reverted (the manager would have no record of
+     * the pre-edit value).
+     *
+     * If the field is absent, the override is applied normally and the original
+     * is captured by reading the property's current value on first apply.
+     */
+    readonly originalValue?: unknown;
+};
+/**
+ * Adds an override entry and immediately applies it.
+ * If an override with the same target coordinates already exists, it is replaced.
+ *
+ * When the caller has already mutated the target (e.g. an Inspector edit),
+ * pass `{ originalValue }` containing the property's prior value — this seeds
+ * the original-value map (so {@link RemoveOverride} can restore it) and skips
+ * the redundant apply step.
+ * @param scene - The scene whose override registry to update.
+ * @param entry - The override to add.
+ * @param options - Optional behavior modifiers; see {@link AddOverrideOptions}.
+ */
+export function AddOverride(scene: Scene, entry: IOverrideEntry, options?: AddOverrideOptions): void;
+/**
+ * Removes a single override matching the given coordinates. Restores the
+ * original value if one was captured.
+ * @param scene - The scene whose override registry to update.
+ * @param targetType - The target type.
+ * @param targetName - The target object name.
+ * @param targetIndex - The target index among same-named siblings.
+ * @param propertyPath - The property path to un-override.
+ * @returns True if an override was removed.
+ */
+export function RemoveOverride(scene: Scene, targetType: OverrideTargetType, targetName: string, targetIndex: number, propertyPath: string): boolean;
+/**
+ * Returns all overrides currently registered with the scene.
+ * @param scene - The scene whose override registry to read.
+ * @returns A read-only array of override entries.
+ */
+export function GetOverrides(scene: Scene): readonly IOverrideEntry[];
+/**
+ * Removes all overrides, optionally restoring original values.
+ * @param scene - The scene whose override registry to clear.
+ * @param restoreOriginals - If true, restores all captured original values.
+ */
+export function ClearOverrides(scene: Scene, restoreOriginals?: boolean): void;
+/**
+ * Updates the target coordinates on the override matching a specific (type,
+ * old-name, old-index) so it follows an entity rename. Used by capture services
+ * to keep overrides attached to a specific object after the user renames it.
+ *
+ * Only the override at the exact `(targetType, oldName, oldIndex)` slot is
+ * updated, so other same-named siblings keep their own overrides untouched.
+ *
+ * @param scene - The scene whose override registry to update.
+ * @param targetType - The target type.
+ * @param oldName - The previous name of the renamed entity.
+ * @param oldIndex - The previous index of the renamed entity among same-named siblings.
+ * @param newName - The new name of the renamed entity.
+ * @param newIndex - The new index of the renamed entity among same-named siblings.
+ */
+export function RenameOverrideTarget(scene: Scene, targetType: OverrideTargetType, oldName: string, oldIndex: number, newName: string, newIndex: number): void;
+/**
+ * Rewrites override *values* that reference an entity by name when that entity
+ * has been renamed. Mirrors {@link RenameOverrideTarget} but operates on the
+ * `value` field rather than the `targetName` field, so overrides whose value
+ * is `"ref:oldName"` (material/light/camera references) or `"texture:oldName"`
+ * (non-SmartAsset texture references) follow the rename instead of silently
+ * pointing at a non-existent entity.
+ *
+ * SmartAsset texture references (`"samTexture:<key>"`) are unaffected because
+ * the SmartAsset key is decoupled from the texture's runtime `name` field.
+ *
+ * @param scene - The scene whose override registry to update.
+ * @param valueScheme - Which encoded-reference prefix to rewrite: `"ref"` for
+ * material/light/camera references, `"texture"` for non-SAM textures.
+ * @param oldName - The previous name embedded in the reference.
+ * @param newName - The new name embedded in the reference.
+ */
+export function RenameOverrideValueReferences(scene: Scene, valueScheme: "ref" | "texture", oldName: string, newName: string): void;
+/**
+ * Applies all overrides to their current targets in the scene.
+ *
+ * Call this after any scene mutation that might have invalidated previously
+ * applied state (asset reload, object recreation, project load). The override
+ * manager does not auto-subscribe to other scene subsystems — coordination is
+ * the caller's responsibility, which keeps the override system independent.
+ * @param scene - The scene whose overrides to apply.
+ */
+export function ApplyAllOverrides(scene: Scene): void;
+/**
+ * Serializes all overrides to a JSON-compatible array.
+ * The on-disk shape is identical to the in-memory `IOverrideEntry`.
+ * @param scene - The scene whose overrides to serialize.
+ * @returns An array of override entries (shallow copies).
+ */
+export function SerializeOverrides(scene: Scene): IOverrideEntry[];
+/**
+ * Loads overrides from a serialized array and applies them.
+ * @param scene - The scene whose override registry to populate.
+ * @param data - Array of override entries.
+ */
+export function DeserializeAndApplyOverrides(scene: Scene, data: IOverrideEntry[]): void;
+/**
+ * Disposes the manager, clearing all overrides and detaching it from its scene.
+ * Safe to call multiple times; subsequent calls are no-ops. Automatically invoked when the
+ * owning scene is disposed.
+ * @param manager - The override manager state.
+ */
+export function DisposeOverrideManager(manager: OverrideManager): void;
+
+}
+declare module "@onerjs/gui-editor/projects/overrideEntry" {
+/**
+ * Defines the shape of an override entry — a property diff applied to a
+ * scene object identified by name. Overrides target any object in the
+ * scene's standard collections (meshes, materials, lights, etc.) regardless
+ * of how that object was created.
+ */
+export interface IOverrideEntry {
+    /** The type of object to target (e.g., "meshes", "materials", "lights"). */
+    readonly targetType: OverrideTargetType;
+    /** The name of the target object. Use "" for scene-level overrides. */
+    readonly targetName: string;
+    /**
+     * Disambiguator for when multiple objects in `scene[targetType]` share the
+     * same `targetName`. The override applies to the N-th match (0-based) at
+     * apply time. When names are unique, use 0.
+     */
+    readonly targetIndex: number;
+    /** Dot-separated property path on the target (e.g., "albedoColor", "position.x"). */
+    readonly propertyPath: string;
+    /** The override value. */
+    readonly value: OverrideValue;
+}
+/**
+ * The types of scene objects that can be targeted by overrides.
+ */
+export type OverrideTargetType = "meshes" | "transformNodes" | "materials" | "textures" | "lights" | "cameras" | "animationGroups" | "scene";
+/**
+ * An override value. Supports scalars, color/vector arrays, object references,
+ * and null (used to clear a slot, e.g. removing a material assignment).
+ * - number: scalar property (e.g., intensity, alpha)
+ * - string: string property, or "ref:name" / "samTexture:key" / "texture:name" object reference
+ * - boolean: boolean property
+ * - number[]: array property mapped to Vector3, Color3, Color4, etc.
+ * - null: explicitly clear an object-typed slot
+ */
+export type OverrideValue = number | string | boolean | number[] | null;
+
 }
 declare module "@onerjs/gui-editor/nodeGraphSystem/typeLedger" {
 import { INodeContainer } from "@onerjs/gui-editor/nodeGraphSystem/interfaces/nodeContainer";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@onerjs/gui-editor",
-    "version": "8.53.5",
+    "version": "8.53.6",
     "main": "dist/babylon.guiEditor.js",
     "module": "dist/babylon.guiEditor.js",
     "esnext": "dist/babylon.guiEditor.js",
@@ -24,8 +24,8 @@
         "@types/react-dom": ">=16.0.9"
     },
     "devDependencies": {
-        "@onerjs/core": "8.53.5",
-        "@onerjs/gui": "8.53.5",
+        "@onerjs/core": "8.53.6",
+        "@onerjs/gui": "8.53.6",
         "react": "^18.2.0",
         "react-dom": "^18.2.0"
     },