ohzi-core 13.2.2 → 14.0.0

package/src/dev_bridge/SceneEditor.ts

@@ -0,0 +1,288 @@
+import type { InspectableObject, InspectableVector } from './SceneInspector';
+
+const PRECISION = 10000;
+
+export interface NodeSelector
+{
+  uuid?: unknown;
+  name?: unknown;
+}
+
+// Changes arrive off the dev-bridge wire, so every value is validated.
+export interface NodeChanges
+{
+  position?: unknown;
+  rotation?: unknown;
+  scale?: unknown;
+  visible?: unknown;
+}
+
+export interface NodeDetail
+{
+  uuid: string;
+  name: string;
+  type: string;
+  parent: string | null;
+  children: number;
+  visible: boolean;
+  position: number[];
+  rotation: number[];
+  scale: number[];
+  material?: string;
+  vertices?: number;
+  changed?: string[];
+}
+
+// Finds and mutates individual scene nodes. Mutation returns the resulting
+// state rather than an acknowledgement, so the caller never has to guess
+// whether a change took.
+class SceneEditor
+{
+  get(root: InspectableObject, selector: NodeSelector): NodeDetail
+  {
+    const found = this.require(root, selector);
+
+    return this.describe(found.node, found.parent);
+  }
+
+  set(root: InspectableObject, selector: NodeSelector, changes: NodeChanges): NodeDetail
+  {
+    const found = this.require(root, selector);
+    const changed: string[] = [];
+
+    if (this.apply_vector(found.node.position, changes.position))
+    {
+      changed.push('position');
+    }
+
+    if (this.apply_vector(found.node.rotation, changes.rotation))
+    {
+      changed.push('rotation');
+    }
+
+    if (this.apply_vector(found.node.scale, changes.scale))
+    {
+      changed.push('scale');
+    }
+
+    if (typeof changes.visible === 'boolean')
+    {
+      found.node.visible = changes.visible;
+      changed.push('visible');
+    }
+
+    const detail = this.describe(found.node, found.parent);
+    detail.changed = changed;
+
+    return detail;
+  }
+
+  private require(root: InspectableObject, selector: NodeSelector): { node: InspectableObject; parent: InspectableObject | null }
+  {
+    if (typeof root !== 'object' || root === null)
+    {
+      throw this.error('not_found', 'No scene is set. SceneManager.current is empty.');
+    }
+
+    const uuid = typeof selector.uuid === 'string' ? selector.uuid : null;
+    const name = typeof selector.name === 'string' ? selector.name : null;
+
+    if (uuid === null && name === null)
+    {
+      throw this.error('not_found', 'Pass a uuid or a name to identify the object.');
+    }
+
+    const found = this.find(root, null, uuid, name);
+
+    if (found === null)
+    {
+      const label = uuid === null ? `name '${name === null ? '' : name}'` : `uuid '${uuid}'`;
+
+      throw this.error('not_found', `No object matching ${label} in the current scene.`);
+    }
+
+    return found;
+  }
+
+  // uuid wins when both are supplied: it is unique, names are not.
+  private find(
+    node: InspectableObject,
+    parent: InspectableObject | null,
+    uuid: string | null,
+    name: string | null
+  ): { node: InspectableObject; parent: InspectableObject | null } | null
+  {
+    const matches = uuid !== null
+      ? node.uuid === uuid
+      : node.name === name;
+
+    if (matches)
+    {
+      return { node, parent };
+    }
+
+    const children = Array.isArray(node.children) ? node.children : [];
+
+    for (const child of children)
+    {
+      const found = this.find(child, node, uuid, name);
+
+      if (found !== null)
+      {
+        return found;
+      }
+    }
+
+    return null;
+  }
+
+  private apply_vector(target: InspectableVector | undefined, values: unknown): boolean
+  {
+    if (typeof target !== 'object' || target === null || !Array.isArray(values))
+    {
+      return false;
+    }
+
+    const axes: Array<keyof InspectableVector> = ['x', 'y', 'z'];
+    // Array.isArray narrows to any[]; restate it as unknown[] so each element
+    // has to be checked rather than trusted.
+    const supplied = values as unknown[];
+    let applied = false;
+
+    for (let i = 0; i < axes.length; i++)
+    {
+      const value = supplied[i];
+
+      // Anything non-numeric is skipped rather than coerced, so a bad payload
+      // cannot silently move an object to NaN.
+      if (typeof value === 'number' && Number.isFinite(value))
+      {
+        target[axes[i]] = value;
+        applied = true;
+      }
+    }
+
+    return applied;
+  }
+
+  private describe(node: InspectableObject, parent: InspectableObject | null): NodeDetail
+  {
+    const detail: NodeDetail = {
+      uuid: typeof node.uuid === 'string' ? node.uuid : '(no uuid)',
+      name: typeof node.name === 'string' ? node.name : '',
+      type: typeof node.type === 'string' ? node.type : 'Object3D',
+      parent: this.parent_label(parent),
+      children: Array.isArray(node.children) ? node.children.length : 0,
+      visible: node.visible !== false,
+      position: this.vector(node.position, 0),
+      rotation: this.vector(node.rotation, 0),
+      scale: this.vector(node.scale, 1)
+    };
+
+    const material = this.material_type(node.material);
+
+    if (material !== null)
+    {
+      detail.material = material;
+    }
+
+    const vertices = this.vertices(node.geometry);
+
+    if (vertices !== null)
+    {
+      detail.vertices = vertices;
+    }
+
+    return detail;
+  }
+
+  // Prefers a readable name, falls back to uuid, so the caller can always
+  // identify the parent it was told about.
+  private parent_label(parent: InspectableObject | null): string | null
+  {
+    if (parent === null)
+    {
+      return null;
+    }
+
+    if (typeof parent.name === 'string' && parent.name.length > 0)
+    {
+      return parent.name;
+    }
+
+    return typeof parent.uuid === 'string' ? parent.uuid : null;
+  }
+
+  private material_type(material: unknown): string | null
+  {
+    if (Array.isArray(material))
+    {
+      return `${material.length} materials`;
+    }
+
+    if (typeof material === 'object' && material !== null)
+    {
+      const type = (material as { type?: unknown }).type;
+
+      return typeof type === 'string' ? type : 'Material';
+    }
+
+    return null;
+  }
+
+  private vertices(geometry: unknown): number | null
+  {
+    if (typeof geometry !== 'object' || geometry === null)
+    {
+      return null;
+    }
+
+    const attributes = (geometry as { attributes?: unknown }).attributes;
+
+    if (typeof attributes !== 'object' || attributes === null)
+    {
+      return null;
+    }
+
+    const position = (attributes as { position?: unknown }).position;
+
+    if (typeof position !== 'object' || position === null)
+    {
+      return null;
+    }
+
+    const count = (position as { count?: unknown }).count;
+
+    return typeof count === 'number' ? count : null;
+  }
+
+  private vector(source: InspectableVector | undefined, fallback: number): number[]
+  {
+    if (typeof source !== 'object' || source === null)
+    {
+      return [fallback, fallback, fallback];
+    }
+
+    return [this.round(source.x, fallback), this.round(source.y, fallback), this.round(source.z, fallback)];
+  }
+
+  private round(value: unknown, fallback: number): number
+  {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+    {
+      return fallback;
+    }
+
+    return Math.round(value * PRECISION) / PRECISION;
+  }
+
+  private error(code: string, message: string): Error
+  {
+    const error: Error & { code?: string } = new Error(message);
+    error.code = code;
+
+    return error;
+  }
+}
+
+export { SceneEditor };

package/src/dev_bridge/SceneInspector.ts

@@ -0,0 +1,388 @@
+const DEFAULT_DEPTH = 4;
+const DEFAULT_MAX_NODES = 200;
+const PRECISION = 10000;
+
+export interface InspectableVector
+{
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface InspectableObject
+{
+  uuid?: string;
+  name?: string;
+  type?: string;
+  visible?: boolean;
+  position?: InspectableVector;
+  rotation?: InspectableVector;
+  scale?: InspectableVector;
+  children?: InspectableObject[];
+  material?: unknown;
+  geometry?: unknown;
+}
+
+export interface SceneNode
+{
+  uuid: string;
+  name: string;
+  type: string;
+  position: number[];
+  rotation?: number[];
+  scale?: number[];
+  visible?: boolean;
+  material?: string;
+  vertices?: number;
+  children?: SceneNode[];
+  truncated?: string;
+}
+
+// Options arrive off the dev-bridge wire and are therefore untrusted.
+export interface InspectOptions
+{
+  depth?: unknown;
+  max_nodes?: unknown;
+  filter?: unknown;
+}
+
+export interface SceneInspectionResult
+{
+  root: SceneNode | null;
+  counts: { total: number; meshes: number; returned: number };
+  truncated: boolean;
+  notes: string[];
+}
+
+interface Budget
+{
+  used: number;
+  depth_cut: boolean;
+  node_cut: boolean;
+}
+
+// Serialises a Three.js scene graph under a hard budget. A production scene has
+// thousands of nodes; an uncapped traversal would consume an entire context
+// window, so depth and node count are always bounded and what was dropped is
+// always reported.
+class SceneInspector
+{
+  inspect(root: InspectableObject, options: InspectOptions): SceneInspectionResult
+  {
+    if (typeof root !== 'object' || root === null)
+    {
+      return {
+        root: null,
+        counts: { total: 0, meshes: 0, returned: 0 },
+        truncated: false,
+        notes: ['No scene is set. SceneManager.current is empty.']
+      };
+    }
+
+    const depth = this.positive(options.depth, DEFAULT_DEPTH);
+    const max_nodes = this.positive(options.max_nodes, DEFAULT_MAX_NODES);
+    const filter = typeof options.filter === 'string' && options.filter.length > 0
+      ? options.filter.toLowerCase()
+      : null;
+
+    const notes: string[] = [];
+    const counts = this.count(root);
+
+    let keep: Set<InspectableObject> | null = null;
+
+    if (filter !== null)
+    {
+      keep = new Set<InspectableObject>();
+      this.mark(root, filter, keep);
+
+      if (keep.size === 0)
+      {
+        notes.push(`no nodes matched the filter '${filter}'`);
+        keep = new Set<InspectableObject>([root]);
+      }
+    }
+
+    const budget: Budget = { used: 0, depth_cut: false, node_cut: false };
+    const serialised = this.serialise(root, 0, depth, max_nodes, keep, budget);
+
+    if (budget.node_cut)
+    {
+      notes.push(`stopped at max_nodes=${max_nodes}; ${counts.total - budget.used} of ${counts.total} nodes not returned`);
+    }
+
+    if (budget.depth_cut)
+    {
+      notes.push(`stopped at depth=${depth}; deeper nodes not returned`);
+    }
+
+    return {
+      root: serialised,
+      counts: { total: counts.total, meshes: counts.meshes, returned: budget.used },
+      truncated: budget.node_cut || budget.depth_cut,
+      notes
+    };
+  }
+
+  private serialise(
+    source: InspectableObject,
+    level: number,
+    depth: number,
+    max_nodes: number,
+    keep: Set<InspectableObject> | null,
+    budget: Budget
+  ): SceneNode | null
+  {
+    if (keep !== null && !keep.has(source))
+    {
+      return null;
+    }
+
+    if (budget.used >= max_nodes)
+    {
+      budget.node_cut = true;
+      return null;
+    }
+
+    budget.used++;
+
+    const node: SceneNode = {
+      uuid: typeof source.uuid === 'string' ? source.uuid : '(no uuid)',
+      name: typeof source.name === 'string' ? source.name : '',
+      type: typeof source.type === 'string' ? source.type : 'Object3D',
+      position: this.vector(source.position, 0)
+    };
+
+    // Defaults are omitted so the payload carries only what differs.
+    const rotation = this.vector(source.rotation, 0);
+    const scale = this.vector(source.scale, 1);
+
+    if (!this.is_uniform(rotation, 0))
+    {
+      node.rotation = rotation;
+    }
+
+    if (!this.is_uniform(scale, 1))
+    {
+      node.scale = scale;
+    }
+
+    if (source.visible === false)
+    {
+      node.visible = false;
+    }
+
+    const material = this.describe_material(source.material);
+
+    if (material !== null)
+    {
+      node.material = material;
+    }
+
+    const vertices = this.count_vertices(source.geometry);
+
+    if (vertices !== null)
+    {
+      node.vertices = vertices;
+    }
+
+    const children = Array.isArray(source.children) ? source.children : [];
+
+    if (children.length === 0)
+    {
+      return node;
+    }
+
+    if (level + 1 > depth)
+    {
+      budget.depth_cut = true;
+      node.truncated = `${children.length} children hidden (depth limit ${depth})`;
+
+      return node;
+    }
+
+    const serialised: SceneNode[] = [];
+    let hidden = 0;
+
+    for (const child of children)
+    {
+      const child_node = this.serialise(child, level + 1, depth, max_nodes, keep, budget);
+
+      if (child_node === null)
+      {
+        hidden++;
+        continue;
+      }
+
+      serialised.push(child_node);
+    }
+
+    if (serialised.length > 0)
+    {
+      node.children = serialised;
+    }
+
+    // Only meaningful when nothing was filtered out on purpose.
+    if (hidden > 0 && keep === null)
+    {
+      node.truncated = `${hidden} children hidden (max_nodes ${max_nodes})`;
+    }
+
+    return node;
+  }
+
+  private count(root: InspectableObject): { total: number; meshes: number }
+  {
+    let total = 0;
+    let meshes = 0;
+
+    const stack: InspectableObject[] = [root];
+
+    while (stack.length > 0)
+    {
+      const current = stack.pop();
+
+      if (typeof current !== 'object' || current === null)
+      {
+        continue;
+      }
+
+      total++;
+
+      if (current.type === 'Mesh')
+      {
+        meshes++;
+      }
+
+      const children = Array.isArray(current.children) ? current.children : [];
+
+      for (const child of children)
+      {
+        stack.push(child);
+      }
+    }
+
+    return { total, meshes };
+  }
+
+  // A node is kept when it matches, or when any descendant matches, so the
+  // path to a match stays visible.
+  private mark(source: InspectableObject, filter: string, keep: Set<InspectableObject>): boolean
+  {
+    const name = typeof source.name === 'string' ? source.name.toLowerCase() : '';
+    const type = typeof source.type === 'string' ? source.type.toLowerCase() : '';
+
+    let matched = name.includes(filter) || type.includes(filter);
+
+    const children = Array.isArray(source.children) ? source.children : [];
+
+    for (const child of children)
+    {
+      if (this.mark(child, filter, keep))
+      {
+        matched = true;
+      }
+    }
+
+    if (matched)
+    {
+      keep.add(source);
+    }
+
+    return matched;
+  }
+
+  private describe_material(material: unknown): string | null
+  {
+    if (Array.isArray(material))
+    {
+      const types = material.map((entry) => this.material_type(entry));
+
+      return `${material.length} materials: ${types.join(', ')}`;
+    }
+
+    if (typeof material === 'object' && material !== null)
+    {
+      return this.material_type(material);
+    }
+
+    return null;
+  }
+
+  private material_type(material: unknown): string
+  {
+    if (typeof material === 'object' && material !== null)
+    {
+      const type = (material as { type?: unknown }).type;
+
+      if (typeof type === 'string')
+      {
+        return type;
+      }
+    }
+
+    return 'Material';
+  }
+
+  private count_vertices(geometry: unknown): number | null
+  {
+    if (typeof geometry !== 'object' || geometry === null)
+    {
+      return null;
+    }
+
+    const attributes = (geometry as { attributes?: unknown }).attributes;
+
+    if (typeof attributes !== 'object' || attributes === null)
+    {
+      return null;
+    }
+
+    const position = (attributes as { position?: unknown }).position;
+
+    if (typeof position !== 'object' || position === null)
+    {
+      return null;
+    }
+
+    const count = (position as { count?: unknown }).count;
+
+    return typeof count === 'number' ? count : null;
+  }
+
+  private vector(source: InspectableVector | undefined, fallback: number): number[]
+  {
+    if (typeof source !== 'object' || source === null)
+    {
+      return [fallback, fallback, fallback];
+    }
+
+    return [this.round(source.x, fallback), this.round(source.y, fallback), this.round(source.z, fallback)];
+  }
+
+  private round(value: unknown, fallback: number): number
+  {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+    {
+      return fallback;
+    }
+
+    return Math.round(value * PRECISION) / PRECISION;
+  }
+
+  private is_uniform(values: number[], expected: number): boolean
+  {
+    return values.every((value) => value === expected);
+  }
+
+  private positive(value: unknown, fallback: number): number
+  {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 1)
+    {
+      return fallback;
+    }
+
+    return Math.floor(value);
+  }
+}
+
+export { SceneInspector };