ohzi-core 13.3.0 → 15.0.0

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 };

package/src/dev_bridge/CommandDispatcher.ts

@@ -0,0 +1,114 @@
+import type { Command, Reply } from './protocol';
+
+// `unknown` already absorbs Promise<unknown>; run() normalises both via Promise.resolve.
+export type CommandHandler = (args: Record<string, unknown>) => unknown;
+export type HandlerTiming = 'immediate' | 'frame_end';
+
+interface Registration
+{
+  timing: HandlerTiming;
+  handler: CommandHandler;
+}
+
+interface QueuedCommand
+{
+  id: string;
+  args: Record<string, unknown>;
+  handler: CommandHandler;
+}
+
+class CommandDispatcher
+{
+  handlers: Record<string, Registration>;
+  queue: QueuedCommand[];
+
+  private reply: (reply: Reply) => void;
+
+  constructor(reply: (reply: Reply) => void)
+  {
+    this.reply = reply;
+    this.handlers = {};
+    this.queue = [];
+  }
+
+  register(cmd: string, timing: HandlerTiming, handler: CommandHandler)
+  {
+    this.handlers[cmd] = { timing, handler };
+  }
+
+  handle(command: Command)
+  {
+    const registration = this.handlers[command.cmd];
+    const args = command.args === undefined ? {} : command.args;
+
+    if (registration === undefined)
+    {
+      this.reply({
+        id: command.id,
+        ok: false,
+        error: { code: 'unknown_command', message: `Unknown command '${command.cmd}'` }
+      });
+
+      return;
+    }
+
+    if (registration.timing === 'frame_end')
+    {
+      this.queue.push({ id: command.id, args, handler: registration.handler });
+      return;
+    }
+
+    this.run(command.id, args, registration.handler);
+  }
+
+  // Called from MainApplication.on_frame_end() so rendering and mutation
+  // never happen part-way through a frame.
+  drain()
+  {
+    const queued = this.queue;
+    this.queue = [];
+
+    for (const command of queued)
+    {
+      this.run(command.id, command.args, command.handler);
+    }
+  }
+
+  private run(id: string, args: Record<string, unknown>, handler: CommandHandler)
+  {
+    try
+    {
+      Promise.resolve(handler(args))
+        .then((result) => this.reply({ id, ok: true, result }))
+        .catch((error) => this.reply({ id, ok: false, error: this.to_error(error) }));
+    }
+    catch (error)
+    {
+      this.reply({ id, ok: false, error: this.to_error(error) });
+    }
+  }
+
+  private to_error(error: unknown): { code: string; message: string }
+  {
+    const code = (error as { code?: string })?.code;
+    const message = (error as { message?: string })?.message;
+
+    return {
+      code: code === undefined ? 'handler_failed' : code,
+      message: typeof message === 'string' ? message : this.describe(error)
+    };
+  }
+
+  // Avoids '[object Object]' reaching the developer for a thrown non-Error.
+  private describe(error: unknown): string
+  {
+    if (typeof error === 'string')
+    {
+      return error;
+    }
+
+    return `Handler failed with a non-Error value of type ${typeof error}`;
+  }
+}
+
+export { CommandDispatcher };

package/src/dev_bridge/ConsoleBuffer.ts

@@ -0,0 +1,286 @@
+const DEFAULT_CAPACITY = 200;
+const MAX_MESSAGE_LENGTH = 2000;
+
+export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error';
+
+const LEVELS: ConsoleLevel[] = ['log', 'info', 'warn', 'error'];
+
+export interface ConsoleEntry
+{
+  seq: number;
+  level: ConsoleLevel;
+  message: string;
+  at: number;
+}
+
+export interface ConsoleLike
+{
+  log: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+export interface ErrorSource
+{
+  addEventListener(type: string, listener: (event: unknown) => void): void;
+  removeEventListener(type: string, listener: (event: unknown) => void): void;
+}
+
+// Read options arrive off the dev-bridge wire and are therefore untrusted.
+export interface ConsoleReadOptions
+{
+  level?: unknown;
+  limit?: unknown;
+  since?: unknown;
+}
+
+export interface ConsoleReadResult
+{
+  entries: ConsoleEntry[];
+  dropped: number;
+  total: number;
+  capacity: number;
+}
+
+// A bounded log of console output and uncaught failures, so the bridge can
+// report what a screenshot cannot show. Injected console and error source keep
+// this testable outside a browser.
+class ConsoleBuffer
+{
+  private capacity: number;
+  private entries: ConsoleEntry[];
+  private seq: number;
+  private dropped: number;
+  private clock: () => number;
+
+  private target: ConsoleLike | null;
+  private source: ErrorSource | null;
+  private originals: Partial<Record<ConsoleLevel, (...args: unknown[]) => void>>;
+  private on_error: ((event: unknown) => void) | null;
+  private on_rejection: ((event: unknown) => void) | null;
+
+  constructor(capacity: number = DEFAULT_CAPACITY, clock: () => number = () => Date.now())
+  {
+    this.capacity = capacity > 0 ? Math.floor(capacity) : DEFAULT_CAPACITY;
+    this.entries = [];
+    this.seq = 0;
+    this.dropped = 0;
+    this.clock = clock;
+    this.target = null;
+    this.source = null;
+    this.originals = {};
+    this.on_error = null;
+    this.on_rejection = null;
+  }
+
+  install(target: ConsoleLike, source?: ErrorSource)
+  {
+    this.dispose();
+    this.target = target;
+
+    for (const level of LEVELS)
+    {
+      // Explicitly typed: indexing with a union then calling .bind() widens to
+      // any, which the lint rules reject.
+      const original: (...args: unknown[]) => void = target[level];
+      this.originals[level] = original;
+
+      target[level] = (...args: unknown[]) =>
+      {
+        this.push(level, this.format(args));
+        original.apply(target, args);
+      };
+    }
+
+    if (source !== undefined)
+    {
+      this.source = source;
+
+      this.on_error = (event) => this.push('error', this.event_message(event));
+      this.on_rejection = (event) => this.push('error', `Unhandled rejection: ${this.event_reason(event)}`);
+
+      source.addEventListener('error', this.on_error);
+      source.addEventListener('unhandledrejection', this.on_rejection);
+    }
+  }
+
+  dispose()
+  {
+    const target = this.target;
+
+    if (target !== null)
+    {
+      for (const level of LEVELS)
+      {
+        const original = this.originals[level];
+
+        if (original !== undefined)
+        {
+          target[level] = original;
+        }
+      }
+    }
+
+    const source = this.source;
+
+    if (source !== null)
+    {
+      if (this.on_error !== null)
+      {
+        source.removeEventListener('error', this.on_error);
+      }
+
+      if (this.on_rejection !== null)
+      {
+        source.removeEventListener('unhandledrejection', this.on_rejection);
+      }
+    }
+
+    this.originals = {};
+    this.target = null;
+    this.source = null;
+    this.on_error = null;
+    this.on_rejection = null;
+  }
+
+  read(options: ConsoleReadOptions): ConsoleReadResult
+  {
+    const level = typeof options.level === 'string' ? options.level : null;
+    const since = typeof options.since === 'number' ? options.since : 0;
+    const limit = typeof options.limit === 'number' && options.limit > 0 ? Math.floor(options.limit) : 0;
+
+    let entries = this.entries.filter((entry) => entry.seq > since);
+
+    if (level !== null)
+    {
+      entries = entries.filter((entry) => entry.level === level);
+    }
+
+    if (limit > 0 && entries.length > limit)
+    {
+      entries = entries.slice(entries.length - limit);
+    }
+
+    return { entries, dropped: this.dropped, total: this.seq, capacity: this.capacity };
+  }
+
+  private push(level: ConsoleLevel, message: string)
+  {
+    this.seq++;
+    this.entries.push({ seq: this.seq, level, message, at: this.clock() });
+
+    while (this.entries.length > this.capacity)
+    {
+      this.entries.shift();
+      this.dropped++;
+    }
+  }
+
+  private format(args: unknown[]): string
+  {
+    const message = args.map((arg) => this.describe(arg)).join(' ');
+
+    if (message.length <= MAX_MESSAGE_LENGTH)
+    {
+      return message;
+    }
+
+    const overflow = message.length - MAX_MESSAGE_LENGTH;
+
+    return `${message.slice(0, MAX_MESSAGE_LENGTH)} ... [truncated ${overflow} chars]`;
+  }
+
+  // Deliberately exhaustive: a log line rendered as '[object Object]' is worse
+  // than no log line at all.
+  private describe(value: unknown): string
+  {
+    if (typeof value === 'string')
+    {
+      return value;
+    }
+
+    if (value === null)
+    {
+      return 'null';
+    }
+
+    if (value === undefined)
+    {
+      return 'undefined';
+    }
+
+    if (typeof value === 'number' || typeof value === 'boolean')
+    {
+      return String(value);
+    }
+
+    if (typeof value === 'function')
+    {
+      return '[function]';
+    }
+
+    if (typeof value === 'symbol')
+    {
+      return '[symbol]';
+    }
+
+    if (typeof value === 'bigint')
+    {
+      return `${value.toString()}n`;
+    }
+
+    if (value instanceof Error)
+    {
+      return `${value.name}: ${value.message}`;
+    }
+
+    try
+    {
+      const json = JSON.stringify(value);
+
+      return json === undefined ? '[unserialisable]' : json;
+    }
+    catch
+    {
+      return '[unserialisable]';
+    }
+  }
+
+  private event_message(event: unknown): string
+  {
+    if (typeof event === 'object' && event !== null)
+    {
+      const record = event as Record<string, unknown>;
+
+      if (typeof record.message === 'string')
+      {
+        return record.message;
+      }
+
+      if (record.error !== undefined)
+      {
+        return this.describe(record.error);
+      }
+    }
+
+    return this.describe(event);
+  }
+
+  private event_reason(event: unknown): string
+  {
+    if (typeof event === 'object' && event !== null)
+    {
+      const record = event as Record<string, unknown>;
+
+      if (record.reason !== undefined)
+      {
+        return this.describe(record.reason);
+      }
+    }
+
+    return this.describe(event);
+  }
+}
+
+export { ConsoleBuffer };