ohzi-core 13.2.2 → 14.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ohzi-core",
-  "version": "13.2.2",
+  "version": "14.0.0",
   "description": "OHZI Interactive Core Library",
   "type": "module",
   "source": "src/index.ts",
@@ -21,6 +21,8 @@
     "build": "rollup -c",
     "create-tag": "node tasks/app/create_tag.mjs",
     "fix-syntax": "npx eslint src --fix || echo 'Done.'",
+    "test": "vitest run",
+    "test-watch": "vitest",
     "generate-types": "npx -p typescript tsc",
     "upload": "yarn build && npm publish && yarn create-tag",
     "create-view": "node ./tasks/create_view/create_view.mjs",
@@ -46,12 +48,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "three": "0.182.0"
+    "three": "0.183.0"
   },
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/node": "^25.0.3",
-    "@types/three": "0.182.0",
+    "@types/three": "0.183.0",
     "@typescript-eslint/eslint-plugin": "^8.18.2",
     "@typescript-eslint/parser": "^8.18.2",
     "eslint": "^8.57.0",
@@ -62,6 +64,7 @@
     "rollup-plugin-terser": "^7.0.2",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.18.2"
+    "typescript-eslint": "^8.18.2",
+    "vitest": "^4.1.11"
   }
 }

package/src/camera_controller/CameraController.ts

@@ -185,13 +185,15 @@ export class CameraController
     return this.normalized_zoom < 0.2;
   }
 
-  set_rotation(tilt: number, orientation: number, azimuth = 0)
+  // Arguments are nullish-checked, not falsy-checked: a falsy check discards a
+  // value of 0, which made it impossible to return any angle to zero.
+  set_rotation(tilt?: number, orientation?: number, azimuth?: number)
   {
     this.old_orientation = this.current_orientation;
 
-    this.current_tilt = tilt || this.current_tilt;
-    this.current_orientation = orientation || this.current_orientation;
-    this.current_azimuth = azimuth || this.current_azimuth;
+    this.current_tilt = tilt ?? this.current_tilt;
+    this.current_orientation = orientation ?? this.current_orientation;
+    this.current_azimuth = azimuth ?? this.current_azimuth;
 
     this.set_quaternion(this.build_rotation(this.current_tilt, this.current_orientation)); //, this.current_azimuth
   }

package/src/dev_bridge/CameraBridge.ts

@@ -0,0 +1,363 @@
+import type { InspectableObject } from './SceneInspector';
+
+const PRECISION = 10000;
+
+export interface OrbitalController
+{
+  current_tilt: number;
+  current_orientation: number;
+  current_azimuth: number;
+  normalized_zoom: number;
+  min_zoom: number;
+  max_zoom: number;
+  reference_position: { x: number; y: number; z: number };
+  get_current_tilt(): number;
+  get_current_orientation(): number;
+  get_current_azimuth(): number;
+  set_normalized_zoom(zoom: number): void;
+  set_rotation(tilt?: number, orientation?: number, azimuth?: number): void;
+  focus_on_bounding_box(box: unknown, scale?: number): void;
+}
+
+export interface BridgeCamera
+{
+  position: { x: number; y: number; z: number };
+  fov?: number;
+  near?: number;
+  far?: number;
+  clear_color?: { getHexString?: () => string };
+  clear_alpha?: number;
+  updateProjectionMatrix?: () => void;
+}
+
+export interface ControllerState
+{
+  tilt: number;
+  orientation: number;
+  azimuth: number;
+  zoom: number;
+  min_zoom: number;
+  max_zoom: number;
+  target: number[];
+}
+
+export interface CameraState
+{
+  position: number[];
+  fov: number | null;
+  near: number | null;
+  far: number | null;
+  clear_color: string | null;
+  clear_alpha: number | null;
+  controller: ControllerState | null;
+  changed?: string[];
+}
+
+// Changes arrive off the dev-bridge wire and are therefore untrusted.
+export interface CameraChanges
+{
+  tilt?: unknown;
+  orientation?: unknown;
+  azimuth?: unknown;
+  zoom?: unknown;
+  fov?: unknown;
+  target?: unknown;
+  position?: unknown;
+}
+
+export interface FrameRequest
+{
+  uuid?: unknown;
+  name?: unknown;
+  scale?: unknown;
+}
+
+// Speaks the CameraController's own idiom. The controller is orbital, driven by
+// tilt, orientation, azimuth and a normalised zoom in degrees, and it rewrites
+// the camera transform every update. Assigning camera.position directly while a
+// controller is active would simply be overwritten on the next frame.
+class CameraBridge
+{
+  get(camera: BridgeCamera, controller: OrbitalController | null): CameraState
+  {
+    return this.describe(this.require_camera(camera), controller);
+  }
+
+  set(camera: BridgeCamera, controller: OrbitalController | null, changes: CameraChanges): CameraState
+  {
+    const target_camera = this.require_camera(camera);
+    const changed: string[] = [];
+
+    if (controller !== null)
+    {
+      this.apply_orbit(controller, changes, changed);
+    }
+
+    this.apply_position(target_camera, controller, changes, changed);
+    this.apply_fov(target_camera, changes, changed);
+
+    const state = this.describe(target_camera, controller);
+    state.changed = changed;
+
+    return state;
+  }
+
+  frame(
+    camera: BridgeCamera,
+    controller: OrbitalController | null,
+    root: InspectableObject,
+    request: FrameRequest,
+    make_bounds: (object: InspectableObject) => unknown
+  ): CameraState
+  {
+    const target_camera = this.require_camera(camera);
+
+    if (controller === null)
+    {
+      throw this.error('no_controller', 'The active scene has no camera_controller, so framing is unavailable.');
+    }
+
+    const uuid = typeof request.uuid === 'string' ? request.uuid : null;
+    const name = typeof request.name === 'string' ? request.name : null;
+
+    if (uuid === null && name === null)
+    {
+      throw this.error('not_found', 'Pass a uuid or a name to identify the object to frame.');
+    }
+
+    const found = this.find(root, 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.`);
+    }
+
+    const scale = typeof request.scale === 'number' && Number.isFinite(request.scale) ? request.scale : 1;
+
+    controller.focus_on_bounding_box(make_bounds(found), scale);
+
+    const state = this.describe(target_camera, controller);
+    state.changed = ['framed'];
+
+    return state;
+  }
+
+  // Angles go through set_rotation, which is nullish-checked, so an omitted
+  // value keeps the current angle and an explicit 0 is applied. It also records
+  // old_orientation, which assigning the fields directly would skip.
+  private apply_orbit(controller: OrbitalController, changes: CameraChanges, changed: string[]): void
+  {
+    const tilt = this.number(changes.tilt);
+    const orientation = this.number(changes.orientation);
+    const azimuth = this.number(changes.azimuth);
+
+    if (tilt !== null || orientation !== null || azimuth !== null)
+    {
+      if (tilt !== null)
+      {
+        changed.push('tilt');
+      }
+
+      if (orientation !== null)
+      {
+        changed.push('orientation');
+      }
+
+      if (azimuth !== null)
+      {
+        changed.push('azimuth');
+      }
+
+      controller.set_rotation(
+        tilt === null ? undefined : tilt,
+        orientation === null ? undefined : orientation,
+        azimuth === null ? undefined : azimuth
+      );
+    }
+
+    const zoom = this.number(changes.zoom);
+
+    if (zoom !== null)
+    {
+      controller.set_normalized_zoom(zoom);
+      changed.push('zoom');
+    }
+
+    const target = this.triple(changes.target);
+
+    if (target !== null)
+    {
+      controller.reference_position.x = target[0];
+      controller.reference_position.y = target[1];
+      controller.reference_position.z = target[2];
+      changed.push('target');
+    }
+  }
+
+  private apply_position(
+    camera: BridgeCamera,
+    controller: OrbitalController | null,
+    changes: CameraChanges,
+    changed: string[]
+  ): void
+  {
+    const position = this.triple(changes.position);
+
+    if (position === null)
+    {
+      return;
+    }
+
+    if (controller !== null)
+    {
+      throw this.error(
+        'controller_owns_camera',
+        'A CameraController is driving this camera and would overwrite a raw position on the next frame. Use tilt, orientation, azimuth, zoom and target instead.'
+      );
+    }
+
+    camera.position.x = position[0];
+    camera.position.y = position[1];
+    camera.position.z = position[2];
+    changed.push('position');
+  }
+
+  private apply_fov(camera: BridgeCamera, changes: CameraChanges, changed: string[]): void
+  {
+    const fov = this.number(changes.fov);
+
+    if (fov === null)
+    {
+      return;
+    }
+
+    camera.fov = fov;
+    changed.push('fov');
+
+    if (typeof camera.updateProjectionMatrix === 'function')
+    {
+      camera.updateProjectionMatrix();
+    }
+  }
+
+  private describe(camera: BridgeCamera, controller: OrbitalController | null): CameraState
+  {
+    return {
+      position: [this.round(camera.position.x), this.round(camera.position.y), this.round(camera.position.z)],
+      fov: typeof camera.fov === 'number' ? camera.fov : null,
+      near: typeof camera.near === 'number' ? camera.near : null,
+      far: typeof camera.far === 'number' ? camera.far : null,
+      clear_color: this.hex(camera.clear_color),
+      clear_alpha: typeof camera.clear_alpha === 'number' ? camera.clear_alpha : null,
+      controller: controller === null ? null : {
+        tilt: controller.get_current_tilt(),
+        orientation: controller.get_current_orientation(),
+        azimuth: controller.get_current_azimuth(),
+        zoom: controller.normalized_zoom,
+        min_zoom: controller.min_zoom,
+        max_zoom: controller.max_zoom,
+        target: [
+          this.round(controller.reference_position.x),
+          this.round(controller.reference_position.y),
+          this.round(controller.reference_position.z)
+        ]
+      }
+    };
+  }
+
+  private find(node: InspectableObject, uuid: string | null, name: string | null): InspectableObject | null
+  {
+    const matches = uuid !== null ? node.uuid === uuid : node.name === name;
+
+    if (matches)
+    {
+      return node;
+    }
+
+    const children = Array.isArray(node.children) ? node.children : [];
+
+    for (const child of children)
+    {
+      const found = this.find(child, uuid, name);
+
+      if (found !== null)
+      {
+        return found;
+      }
+    }
+
+    return null;
+  }
+
+  private require_camera(camera: BridgeCamera): BridgeCamera
+  {
+    if (typeof camera !== 'object' || camera === null || typeof camera.position !== 'object')
+    {
+      throw this.error('no_camera', 'No camera is active. CameraManager.current is not set yet.');
+    }
+
+    return camera;
+  }
+
+  private hex(color: { getHexString?: () => string } | undefined): string | null
+  {
+    if (typeof color !== 'object' || color === null || typeof color.getHexString !== 'function')
+    {
+      return null;
+    }
+
+    return `#${color.getHexString()}`;
+  }
+
+  private number(value: unknown): number | null
+  {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+  }
+
+  private triple(value: unknown): number[] | null
+  {
+    if (!Array.isArray(value))
+    {
+      return null;
+    }
+
+    const supplied = value as unknown[];
+    const out: number[] = [];
+
+    for (let i = 0; i < 3; i++)
+    {
+      const entry = this.number(supplied[i]);
+
+      if (entry === null)
+      {
+        return null;
+      }
+
+      out.push(entry);
+    }
+
+    return out;
+  }
+
+  private round(value: unknown): number
+  {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+    {
+      return 0;
+    }
+
+    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 { CameraBridge };

package/src/dev_bridge/CaptureService.ts

@@ -0,0 +1,256 @@
+const MAX_DIMENSION = 8192;
+const BASE64_CHUNK_SIZE = 8192;
+
+// A retina canvas reports physical pixels, so a fast capture is 4x the pixels
+// the developer is actually looking at. Every one of those bytes is base64'd
+// into the model's context, so cap the long edge unless asked otherwise.
+const DEFAULT_MAX_FAST_SIZE = 1280;
+
+export interface CaptureCanvas
+{
+  width: number;
+  height: number;
+  toBlob(callback: (blob: Blob | null) => void, type?: string): void;
+}
+
+export interface ScratchContext
+{
+  drawImage(source: unknown, x: number, y: number, width: number, height: number): void;
+}
+
+export interface ScratchCanvas
+{
+  width: number;
+  height: number;
+  getContext(type: '2d'): ScratchContext | null;
+  toBlob(callback: (blob: Blob | null) => void, type?: string): void;
+}
+
+export interface CaptureGraphics
+{
+  canvas: CaptureCanvas;
+  take_screenshot(callback: (blob: Blob | null) => void, width?: number, height?: number): void;
+}
+
+// Values arrive straight off the dev-bridge wire, so they are untrusted and
+// every field is validated before use.
+export interface CaptureOptions
+{
+  mode?: unknown;
+  width?: unknown;
+  height?: unknown;
+  max_size?: unknown;
+}
+
+export interface CaptureResult
+{
+  mode: 'fast' | 'hires';
+  mime_type: string;
+  width: number;
+  height: number;
+  bytes: number;
+  data: string;
+  scaled_from?: { width: number; height: number };
+}
+
+// Holds no OHZI singletons: the consumer injects the graphics surface and a
+// camera predicate, so this stays testable without a WebGPU context.
+class CaptureService
+{
+  private graphics: CaptureGraphics;
+  private has_camera: () => boolean;
+  private create_canvas: () => ScratchCanvas;
+
+  constructor(
+    graphics: CaptureGraphics,
+    has_camera: () => boolean,
+    create_canvas: () => ScratchCanvas = () => document.createElement('canvas') as unknown as ScratchCanvas
+  )
+  {
+    this.graphics = graphics;
+    this.has_camera = has_camera;
+    this.create_canvas = create_canvas;
+  }
+
+  async capture(options: CaptureOptions): Promise<CaptureResult>
+  {
+    if (options.mode === 'hires')
+    {
+      return this.capture_hires(options);
+    }
+
+    return this.capture_fast(options);
+  }
+
+  // Reads the live canvas. Valid because the renderer is created with
+  // preserveDrawingBuffer: true, so the backbuffer still holds the last frame.
+  private async capture_fast(options: CaptureOptions): Promise<CaptureResult>
+  {
+    const canvas = this.graphics.canvas;
+    const target = this.scaled_size(canvas.width, canvas.height, options.max_size);
+
+    if (target !== null)
+    {
+      const scratch = this.draw_scaled(canvas, target.width, target.height);
+
+      if (scratch !== null)
+      {
+        const scaled_blob = await this.request_blob((callback) => scratch.toBlob(callback, 'image/png'));
+        const scaled = await this.build_result('fast', target.width, target.height, scaled_blob);
+
+        scaled.scaled_from = { width: canvas.width, height: canvas.height };
+
+        return scaled;
+      }
+    }
+
+    const blob = await this.request_blob((callback) => canvas.toBlob(callback, 'image/png'));
+
+    return this.build_result('fast', canvas.width, canvas.height, blob);
+  }
+
+  // Returns null when no downscale should happen: an explicit opt-out, or a
+  // canvas already within the cap. Never upscales.
+  private scaled_size(width: number, height: number, max_size: unknown): { width: number; height: number } | null
+  {
+    const cap = typeof max_size === 'number' ? max_size : DEFAULT_MAX_FAST_SIZE;
+
+    if (!Number.isFinite(cap) || cap <= 0)
+    {
+      return null;
+    }
+
+    const long_edge = Math.max(width, height);
+
+    if (long_edge <= cap)
+    {
+      return null;
+    }
+
+    const ratio = cap / long_edge;
+
+    return {
+      width: Math.max(1, Math.round(width * ratio)),
+      height: Math.max(1, Math.round(height * ratio))
+    };
+  }
+
+  // Returns null if no 2D context is available, in which case the caller falls
+  // back to a native capture. A large image beats no image.
+  private draw_scaled(source: unknown, width: number, height: number): ScratchCanvas | null
+  {
+    const scratch = this.create_canvas();
+
+    scratch.width = width;
+    scratch.height = height;
+
+    const context = scratch.getContext('2d');
+
+    if (context === null)
+    {
+      return null;
+    }
+
+    context.drawImage(source, 0, 0, width, height);
+
+    return scratch;
+  }
+
+  private async capture_hires(options: CaptureOptions): Promise<CaptureResult>
+  {
+    // Graphics.take_screenshot dereferences CameraManager.current directly and
+    // would throw a TypeError, so refuse with a code the caller can act on.
+    if (!this.has_camera())
+    {
+      throw this.error('no_camera', 'A hires capture needs an active camera; CameraManager.current is not set yet.');
+    }
+
+    const canvas = this.graphics.canvas;
+    const width = this.dimension(options.width, canvas.width);
+    const height = this.dimension(options.height, canvas.height);
+
+    const blob = await this.request_blob((callback) => this.graphics.take_screenshot(callback, width, height));
+
+    return this.build_result('hires', width, height, blob);
+  }
+
+  private dimension(value: unknown, fallback: number): number
+  {
+    if (typeof value === 'number')
+    {
+      return this.clamp(value);
+    }
+
+    return this.clamp(fallback);
+  }
+
+  // take_screenshot renders ceil(w/1024) * ceil(h/1024) tiles, so an unbounded
+  // size would stall the frame for a very long time.
+  private clamp(value: number): number
+  {
+    if (!Number.isFinite(value) || value < 1)
+    {
+      return 1;
+    }
+
+    return Math.min(Math.floor(value), MAX_DIMENSION);
+  }
+
+  private request_blob(request: (callback: (blob: Blob | null) => void) => void): Promise<Blob>
+  {
+    return new Promise((resolve, reject) =>
+    {
+      request((blob) =>
+      {
+        if (blob === null)
+        {
+          reject(this.error('capture_failed', 'The canvas produced no image data.'));
+          return;
+        }
+
+        resolve(blob);
+      });
+    });
+  }
+
+  private async build_result(mode: 'fast' | 'hires', width: number, height: number, blob: Blob): Promise<CaptureResult>
+  {
+    const buffer = await blob.arrayBuffer();
+    const bytes = new Uint8Array(buffer);
+
+    return {
+      mode,
+      // Graphics asks toBlob for the malformed type 'image/png;base64;', which
+      // browsers fall back to PNG for. Report what the bytes actually are.
+      mime_type: 'image/png',
+      width,
+      height,
+      bytes: bytes.length,
+      data: this.to_base64(bytes)
+    };
+  }
+
+  private to_base64(bytes: Uint8Array): string
+  {
+    let binary = '';
+
+    // Chunked: spreading a full-resolution capture into String.fromCharCode
+    // overflows the call stack.
+    for (let i = 0; i < bytes.length; i += BASE64_CHUNK_SIZE)
+    {
+      binary += String.fromCharCode(...bytes.subarray(i, i + BASE64_CHUNK_SIZE));
+    }
+
+    return btoa(binary);
+  }
+
+  private error(code: string, message: string): Error
+  {
+    const error: Error & { code?: string } = new Error(message);
+    error.code = code;
+
+    return error;
+  }
+}
+
+export { CaptureService };