babylon.quarks-editor 0.27.0 → 0.28.0

package/dist/react/theme.js

@@ -1,15 +1,27 @@
+/** The editor's colours and font, for hosts that style their own panels to match. */
 export const theme = {
+    /** Background of the side panels and docks. */
     panelBg: 'linear-gradient(180deg, rgba(12, 18, 38, 0.92), rgba(6, 10, 22, 0.94))',
+    /** Background of an inspector module or a framed list. */
     sectionBg: 'rgba(10, 16, 34, 0.6)',
+    /** Borders and separators. */
     border: '#2a365f',
+    /** The border of a selected or switched-on control. */
     borderActive: '#4f6fbe',
+    /** Body text. */
     text: '#eef3ff',
+    /** Labels and secondary text. */
     textDim: '#b7c6ea',
+    /** Highlights, such as a Save button with something to save. */
     accent: '#9eb9ff',
+    /** Background of inputs. */
     inputBg: 'rgba(7, 11, 22, 0.82)',
+    /** The line of curve editors. */
     curveStroke: '#78a5ff',
+    /** The editor's font stack. */
     font: 'Inter, Segoe UI, Roboto, sans-serif',
 };
+/** Style of a text or number input. */
 export const inputStyle = {
     background: theme.inputBg,
     border: `1px solid ${theme.border}`,
@@ -22,6 +34,7 @@ export const inputStyle = {
     boxSizing: 'border-box',
     fontFamily: theme.font,
 };
+/** Style of an inspector row: a label column, then the controls. */
 export const rowStyle = {
     display: 'grid',
     gridTemplateColumns: '110px 1fr',
@@ -29,6 +42,7 @@ export const rowStyle = {
     gap: 8,
     marginTop: 6,
 };
+/** Style of an inspector row's label. */
 export const labelStyle = {
     color: theme.textDim,
     fontSize: 12,
@@ -36,6 +50,7 @@ export const labelStyle = {
     overflow: 'hidden',
     textOverflow: 'ellipsis',
 };
+/** Style of a button. */
 export const buttonStyle = {
     border: `1px solid #4563ad`,
     background: 'rgba(28, 48, 98, 0.55)',

package/dist/session.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The editor's headless session: scene, camera, gizmos, history, scene entries, assets, prefab
+ * mode and project save/load, without React. It builds the whole viewport (grid, gizmos, markers),
+ * so it has its own entry point and the UI-free `babylon.quarks-editor` entry stays light.
+ *
+ * @packageDocumentation
+ */
+export { createEditorSession } from './core/editorSession.js';
+export type { EditorFrameStats, EditorProject, EditorSession, EditorSessionOptions, EditorSessionView, EffectEditorHostHandle, PrefabInfo, } from './core/editorSession.js';

package/dist/session.js

@@ -0,0 +1,8 @@
+/**
+ * The editor's headless session: scene, camera, gizmos, history, scene entries, assets, prefab
+ * mode and project save/load, without React. It builds the whole viewport (grid, gizmos, markers),
+ * so it has its own entry point and the UI-free `babylon.quarks-editor` entry stays light.
+ *
+ * @packageDocumentation
+ */
+export { createEditorSession } from './core/editorSession.js';

package/package.json

@@ -1,19 +1,24 @@
 {
     "name": "babylon.quarks-editor",
-    "version": "0.27.0",
+    "version": "0.28.0",
     "description": "Shuriken-style effect editor for babylon.quarks: headless edit-model core + React module-stack UI",
     "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "exports": {
         ".": {
-            "import": "./dist/index.js",
-            "types": "./dist/index.d.ts"
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./session": {
+            "types": "./dist/session.d.ts",
+            "import": "./dist/session.js"
         },
         "./react": {
-            "import": "./dist/react/index.js",
-            "types": "./dist/react/index.d.ts"
-        }
+            "types": "./dist/react/index.d.ts",
+            "import": "./dist/react/index.js"
+        },
+        "./package.json": "./package.json"
     },
     "files": [
         "dist",
@@ -25,7 +30,8 @@
     "scripts": {
         "clean": "rimraf dist",
         "build": "npm run clean && tsc -p tsconfig.json",
-        "test": "jest"
+        "test": "jest",
+        "docs:check": "typedoc --out node_modules/.cache/typedoc-check"
     },
     "repository": {
         "type": "git",
@@ -51,11 +57,11 @@
     },
     "homepage": "https://github.com/Soullnik/babylon.quarks-standalone#readme",
     "peerDependencies": {
-        "@babylonjs/core": ">=9.0.0",
-        "@babylonjs/materials": ">=9.0.0",
+        "@babylonjs/core": "^9.0.0",
+        "@babylonjs/materials": "^9.0.0",
         "@heroicons/react": ">=2.0.0",
         "@tanstack/react-virtual": ">=3.0.0",
-        "babylon.quarks": "~0.27.0",
+        "babylon.quarks": "~0.28.0",
         "react": ">=18",
         "react-dom": ">=18"
     },
@@ -69,6 +75,6 @@
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
         "rimraf": "^6.0.0",
-        "typescript": "^5.9.3"
+        "typescript": "^6.0.3"
     }
 }

package/src/core/assetTree.ts

@@ -85,7 +85,20 @@ export function searchAssets(assets: EffectAsset[], query: string): EffectAsset[
 
 export const ASSET_DRAG_MIME = 'application/x-quarks-asset-drop';
 
-export type AssetDragPayload = {kind: 'asset'; id: number} | {kind: 'folder'; path: string};
+/** What is dragged out of the Assets panel: one asset, or every asset under a folder. */
+export type AssetDragPayload =
+    | {
+          /** One asset. */
+          kind: 'asset';
+          /** The asset's id. */
+          id: number;
+      }
+    | {
+          /** A folder. */
+          kind: 'folder';
+          /** The folder's path; every asset under it is dragged. */
+          path: string;
+      };
 
 export function writeAssetDrag(dataTransfer: DataTransfer, payload: AssetDragPayload): void {
     dataTransfer.setData(ASSET_DRAG_MIME, JSON.stringify(payload));

package/src/core/assets.ts

@@ -7,7 +7,9 @@ import {QuarksLoader} from 'babylon.quarks';
  * fresh, independent copy (see `instantiateSceneEntry`).
  */
 export interface EffectAsset {
+    /** The asset's id in this session; scene entries made from it keep it. */
     id: number;
+    /** The asset's display name, its file name without `.json`. */
     name: string;
     /** Relative path inside the imported folder (preserves subfolders). */
     path: string;
@@ -17,10 +19,15 @@ export interface EffectAsset {
     missingFiles: string[];
 }
 
+/** How far an asset import got. */
 export interface AssetLoadProgress {
+    /** JSON files read so far. */
     done: number;
+    /** JSON files in the import. */
     total: number;
+    /** Effects found so far. */
     loaded: number;
+    /** Files that could not be read. */
     failed: number;
 }
 
@@ -75,6 +82,13 @@ function readAsDataUrl(file: File): Promise<string> {
     });
 }
 
+/** An object with fields of unknown types, as an imported file's JSON may hold anywhere. */
+type JSONRecord = {[key: string]: unknown};
+
+function isRecord(value: unknown): value is JSONRecord {
+    return value !== null && typeof value === 'object';
+}
+
 /** True for a Quarks effect envelope with at least one particle emitter. */
 export function isEffectJson(json: unknown): boolean {
     const object = (json as {object?: unknown} | null)?.object;
@@ -166,7 +180,7 @@ function createFileResolver(effectPath: string, index: ImportedFileIndex, missin
  * {@link QuarksLoader.resolveLinkedResources}, so the effect loads (and later exports) as a
  * self-contained effect. Returns the references that could not be found among the files.
  */
-async function inlineExternalFiles(json: any, effectPath: string, index: ImportedFileIndex): Promise<string[]> {
+async function inlineExternalFiles(json: unknown, effectPath: string, index: ImportedFileIndex): Promise<string[]> {
     const missing: string[] = [];
     // baseUrl is the effect file path so resolveRelativePath can walk from its folder; the
     // File resolver ignores HTTP join and looks up files by path/name instead.
@@ -263,22 +277,23 @@ export function assetIconUrl(asset: EffectAsset): string | null {
     if (cached !== undefined) {
         return cached;
     }
-    const json = asset.json as any;
-    const findMaterial = (node: any): string | undefined => {
-        if (!node || typeof node !== 'object') return undefined;
-        if (node.type === 'ParticleEmitter' && node.ps?.material) return node.ps.material;
+    const json = isRecord(asset.json) ? asset.json : {};
+    const findMaterial = (node: unknown): unknown => {
+        if (!isRecord(node)) return undefined;
+        if (node.type === 'ParticleEmitter' && isRecord(node.ps) && node.ps.material) return node.ps.material;
         for (const child of Array.isArray(node.children) ? node.children : []) {
             const found = findMaterial(child);
             if (found) return found;
         }
         return undefined;
     };
-    const byUuid = (list: unknown, uuid: unknown) =>
-        (Array.isArray(list) ? list : []).find((item: any) => item?.uuid === uuid) as any;
+    const byUuid = (list: unknown, uuid: unknown): JSONRecord | undefined =>
+        (Array.isArray(list) ? list : []).find((item: unknown) => isRecord(item) && item.uuid === uuid);
 
-    const material = byUuid(json?.materials, findMaterial(json?.object));
-    const texture = byUuid(json?.textures, material?.map ?? material?.texture);
-    const image = byUuid(json?.images, texture?.image) ?? (Array.isArray(json?.images) ? json.images[0] : undefined);
+    const material = byUuid(json.materials, findMaterial(json.object));
+    const texture = byUuid(json.textures, material?.map ?? material?.texture);
+    const firstImage: unknown = Array.isArray(json.images) ? json.images[0] : undefined;
+    const image = byUuid(json.images, texture?.image) ?? (isRecord(firstImage) ? firstImage : undefined);
     const url = typeof image?.url === 'string' && image.url ? image.url : null;
     iconCache.set(asset, url);
     return url;

package/src/core/binding.ts

@@ -3,6 +3,7 @@ import type {ParticleSystem} from 'babylon.quarks';
 import type {EffectTreeNode} from './effectTree.js';
 import {buildEffectTree, serializeEffectTree} from './effectTree.js';
 
+/** Called after every change made through an {@link EffectBinding}. */
 export type EditorListener = () => void;
 
 /**
@@ -32,6 +33,7 @@ export class EffectBinding {
         return buildEffectTree(this.root);
     }
 
+    /** Calls `listener` after every change; returns the call that stops it. */
     subscribe(listener: EditorListener): () => void {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -42,17 +44,23 @@ export class EffectBinding {
         return this.revision;
     }
 
+    /**
+     * Changes the main system through `mutate`: takes an undo snapshot first, then notifies
+     * subscribers. Every inspector edit goes through here.
+     */
     apply(mutate: (system: ParticleSystem) => void): void {
         this.onBeforeChange?.();
         mutate(this.system);
         this.notify();
     }
 
+    /** Adds a system to the effect's sub systems. */
     addSubSystem(sub: ParticleSystem): void {
         this.subSystems.push(sub);
         this.notify();
     }
 
+    /** Removes a system from the effect's sub systems; a system it does not have is ignored. */
     removeSubSystem(sub: ParticleSystem): void {
         const index = this.subSystems.indexOf(sub);
         if (index >= 0) {
@@ -92,6 +100,7 @@ export class EffectBinding {
         }
     }
 
+    /** Restarts every system of the effect from time 0. */
     restart(): void {
         // onlyUsedByOther systems skip self-emission in update(); play() only unpauses sim.
         for (const system of [this.system, ...this.subSystems]) {

package/src/core/collision.ts

@@ -8,8 +8,12 @@ import {Vector3, getPhysicsResolver, setPhysicsResolver} from 'babylon.quarks';
  * which is exactly what ApplyCollision.update reflects the velocity against.
  */
 export class GroundPlaneResolver {
+    /** @param y - Height of the ground plane. */
     constructor(public y = 0) {}
 
+    /**
+     * True when `position` is at or below the plane, with the plane's normal written to `normal`.
+     */
     resolve(position: Vector3, normal: Vector3): boolean {
         if (position.y <= this.y) {
             normal.set(0, 1, 0);

package/src/core/colors.ts

@@ -3,18 +3,25 @@ import {ColorOverLife, Gradient, Vector3, Vector4} from 'babylon.quarks';
 
 /** One RGBA stop of the editable gradient (all channels 0..1, pos 0..1). */
 export interface GradientStop {
+    /** Where the stop sits over the particle's life, 0..1. */
     pos: number;
+    /** Red, 0..1. */
     r: number;
+    /** Green, 0..1. */
     g: number;
+    /** Blue, 0..1. */
     b: number;
+    /** Alpha, 0..1. */
     a: number;
 }
 
+/** The gradient a new Color over Lifetime starts with: warm yellow fading out through red. */
 export const DEFAULT_GRADIENT_STOPS: GradientStop[] = [
     {pos: 0, r: 1, g: 0.85, b: 0.4, a: 1},
     {pos: 1, r: 1, g: 0.25, b: 0.05, a: 0},
 ];
 
+/** A quarks gradient through `stops`, sorted by position; colour and alpha share the stops. */
 export function buildGradient(stops: GradientStop[]): Gradient {
     const sorted = [...stops].sort((a, b) => a.pos - b.pos);
     return new Gradient(
@@ -23,26 +30,38 @@ export function buildGradient(stops: GradientStop[]): Gradient {
     );
 }
 
+/** A Color over Lifetime behavior through `stops`. */
 export function buildColorOverLife(stops: GradientStop[]): ColorOverLife {
     return new ColorOverLife(buildGradient(stops));
 }
 
+/** An RGBA colour as a quarks `Vector4`. */
 export function rgbaToVector4(stop: {r: number; g: number; b: number; a: number}): Vector4 {
     return new Vector4(stop.r, stop.g, stop.b, stop.a);
 }
 
+/** A stop's colour as CSS `rgba()`. */
 export function stopToCss(stop: GradientStop): string {
     const c = (v: number) => Math.round(v * 255);
     return `rgba(${c(stop.r)}, ${c(stop.g)}, ${c(stop.b)}, ${stop.a.toFixed(2)})`;
 }
 
+/** The stops as a left-to-right CSS `linear-gradient`, for a gradient preview. */
 export function stopsToCssGradient(stops: GradientStop[]): string {
     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: string): {r: number; g: number; b: number} {
+/** A `#rrggbb` colour as channels 0..1. */
+export function hexToRgb(hex: string): {
+    /** Red, 0..1. */
+    r: number;
+    /** Green, 0..1. */
+    g: number;
+    /** Blue, 0..1. */
+    b: number;
+} {
     const value = hex.replace('#', '');
     return {
         r: parseInt(value.slice(0, 2), 16) / 255,
@@ -51,6 +70,7 @@ export function hexToRgb(hex: string): {r: number; g: number; b: number} {
     };
 }
 
+/** Channels 0..1, clamped, as a `#rrggbb` colour. */
 export function rgbToHex(r: number, g: number, b: number): string {
     const c = (v: number) =>
         Math.round(Math.min(1, Math.max(0, v)) * 255)

package/src/core/defaultEffect.ts

@@ -1,3 +1,4 @@
+import type {Texture} from '@babylonjs/core/Materials/Textures/texture.js';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode.js';
 import type {Scene} from '@babylonjs/core/scene.js';
 import {
@@ -14,14 +15,14 @@ import {DEFAULT_GRADIENT_STOPS, buildGradient} from './colors.js';
 import {uniqueEntryName, type SceneEntry} from './sceneEntries.js';
 
 export interface CreateSceneDefaultOptions {
-    resolveTexture?: (url: string, scene: Scene) => unknown;
+    resolveTexture?: (url: string, scene: Scene) => Texture | null | undefined;
     textureUrl?: string;
 }
 
 /** Creates a simple cone burst preset for new editor effects. */
 export function createDefaultEffect(
     scene: Scene,
-    resolveTexture?: (url: string, scene: Scene) => unknown,
+    resolveTexture?: (url: string, scene: Scene) => Texture | null | undefined,
     textureUrl?: string
 ): ParticleSystem {
     const system = new ParticleSystem({
@@ -35,7 +36,7 @@ export function createDefaultEffect(
         emissionOverTime: new ConstantValue(80),
         shape: new ConeEmitter({radius: 0.3, angle: 0.25}),
         renderMode: RenderMode.BillBoard,
-        texture: (textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined) as never,
+        texture: textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined,
         transparent: true,
         blendMode: 1,
     });