@ccheever/exact-ibex-runtime 0.1.0

package/src/camera/processor.worker.ts

@@ -0,0 +1,194 @@
+/**
+ * Camera frame processor worker.
+ *
+ * The worker evaluates the user-supplied processor function source once and
+ * then executes it for each frame with a minimal `Frame` facade that matches
+ * the RFC shape closely enough for web camera labs and automated tests.
+ */
+
+type CameraPreviewMode = "native" | "processed";
+type CameraResizeMode = "cover" | "contain" | "stretch";
+
+interface FrameMessage {
+  type: "frame";
+  id: number;
+  inputBuffer: ArrayBuffer;
+  width: number;
+  height: number;
+  timestamp: number;
+  previewMode: CameraPreviewMode;
+  resizeMode: CameraResizeMode;
+  mirror: boolean;
+  targetWidth: number;
+  targetHeight: number;
+  isCaptureFrame: boolean;
+}
+
+let processorFn: ((frame: unknown) => unknown) | null = null;
+let currentCallIndex = 0;
+const fpsMemory = new Map<string, { timestamp: number; value: unknown }>();
+
+function computeDrawRect(
+  sourceWidth: number,
+  sourceHeight: number,
+  targetWidth: number,
+  targetHeight: number,
+  resizeMode: CameraResizeMode,
+) {
+  if (
+    resizeMode === "stretch" ||
+    sourceWidth <= 0 ||
+    sourceHeight <= 0 ||
+    targetWidth <= 0 ||
+    targetHeight <= 0
+  ) {
+    return { x: 0, y: 0, width: targetWidth, height: targetHeight };
+  }
+
+  const sourceAspect = sourceWidth / sourceHeight;
+  const targetAspect = targetWidth / targetHeight;
+  const cover = resizeMode === "cover";
+  const sourceIsWider = sourceAspect > targetAspect;
+
+  if (cover ? sourceIsWider : !sourceIsWider) {
+    const height = targetHeight;
+    const width = height * sourceAspect;
+    return {
+      x: (targetWidth - width) / 2,
+      y: 0,
+      width,
+      height,
+    };
+  }
+
+  const width = targetWidth;
+  const height = width / sourceAspect;
+  return {
+    x: 0,
+    y: (targetHeight - height) / 2,
+    width,
+    height,
+  };
+}
+
+function sensorToViewRect(
+  rect: { x: number; y: number; width: number; height: number },
+  message: FrameMessage,
+) {
+  const drawRect = computeDrawRect(
+    message.width,
+    message.height,
+    message.targetWidth,
+    message.targetHeight,
+    message.resizeMode,
+  );
+  const mapped = {
+    x: drawRect.x + (rect.x / message.width) * drawRect.width,
+    y: drawRect.y + (rect.y / message.height) * drawRect.height,
+    width: (rect.width / message.width) * drawRect.width,
+    height: (rect.height / message.height) * drawRect.height,
+  };
+
+  if (message.mirror) {
+    mapped.x = message.targetWidth - (mapped.x + mapped.width);
+  }
+
+  return {
+    x: mapped.x / message.targetWidth,
+    y: mapped.y / message.targetHeight,
+    width: mapped.width / message.targetWidth,
+    height: mapped.height / message.targetHeight,
+  };
+}
+
+function runAtTargetFps(targetFps: number, fn: () => unknown): unknown {
+  const key = `${targetFps}:${currentCallIndex++}`;
+  const last = fpsMemory.get(key);
+  const frameBudget = 1000 / Math.max(1, targetFps);
+  const now = Date.now();
+  if (last && now - last.timestamp < frameBudget) {
+    return last.value;
+  }
+  const value = fn();
+  fpsMemory.set(key, { timestamp: now, value });
+  return value;
+}
+
+function installRuntimeGlobals(): void {
+  (globalThis as typeof globalThis & {
+    runAtTargetFps?: typeof runAtTargetFps;
+  }).runAtTargetFps = runAtTargetFps;
+}
+
+installRuntimeGlobals();
+
+self.onmessage = (event: MessageEvent) => {
+  const payload = event.data as
+    | { type: "init"; source: string }
+    | FrameMessage;
+
+  if (payload.type === "init") {
+    try {
+      // We intentionally evaluate the source in the worker so that processor
+      // execution stays off the main thread. The source comes from application
+      // code running in the same bundle, not from remote input.
+      processorFn = (0, eval)(`(${payload.source})`) as (frame: unknown) => unknown;
+    } catch (error) {
+      console.error("[CameraWorker] Failed to compile processor:", error);
+      processorFn = null;
+    }
+    return;
+  }
+
+  if (!processorFn) {
+    return;
+  }
+
+  try {
+    currentCallIndex = 0;
+    const input = payload.inputBuffer;
+    const writable =
+      payload.previewMode === "processed" || payload.isCaptureFrame
+        ? input.slice(0)
+        : null;
+
+    const frame = {
+      width: payload.width,
+      height: payload.height,
+      timestamp: payload.timestamp,
+      orientation: payload.width >= payload.height ? "landscape-left" : "portrait",
+      isCaptureFrame: payload.isCaptureFrame,
+      pixelFormat: "bgra",
+      rawPixelFormat: "bgra",
+      toArrayBuffer() {
+        return input;
+      },
+      toWritableBuffer() {
+        return writable;
+      },
+      sensorToView(rect: { x: number; y: number; width: number; height: number }) {
+        return sensorToViewRect(rect, payload);
+      },
+      getDepthData() {
+        return null;
+      },
+    };
+
+    const result = processorFn(frame);
+    self.postMessage(
+      {
+        type: "result",
+        id: payload.id,
+        result,
+        outputBuffer: writable ?? undefined,
+      },
+      writable ? [writable] : [],
+    );
+  } catch (error) {
+    self.postMessage({
+      type: "error",
+      id: payload.id,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+};

package/src/camera/scene.ts

@@ -0,0 +1,195 @@
+export interface SceneRectLike {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface SceneBarcodeLike {
+  type: string;
+  data: string;
+  bounds: SceneRectLike;
+}
+
+export interface SceneFaceLike {
+  bounds: SceneRectLike;
+}
+
+export interface SceneTextLike {
+  value: string;
+  bounds: SceneRectLike;
+}
+
+export interface SceneObjectLike {
+  label: string;
+  bounds: SceneRectLike;
+  confidence: number;
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function clampSceneRect(rect: SceneRectLike): SceneRectLike {
+  const x = clamp01(rect.x);
+  const y = clamp01(rect.y);
+  const right = clamp01(rect.x + Math.max(0, rect.width));
+  const bottom = clamp01(rect.y + Math.max(0, rect.height));
+  return {
+    x,
+    y,
+    width: Math.max(0, right - x),
+    height: Math.max(0, bottom - y),
+  };
+}
+
+function sceneRectArea(rect: SceneRectLike): number {
+  return Math.max(0, rect.width) * Math.max(0, rect.height);
+}
+
+function unionSceneRects(rects: SceneRectLike[]): SceneRectLike {
+  const clamped = rects.map(clampSceneRect);
+  const minX = Math.min(...clamped.map((rect) => rect.x));
+  const minY = Math.min(...clamped.map((rect) => rect.y));
+  const maxX = Math.max(...clamped.map((rect) => rect.x + rect.width));
+  const maxY = Math.max(...clamped.map((rect) => rect.y + rect.height));
+  return clampSceneRect({
+    x: minX,
+    y: minY,
+    width: maxX - minX,
+    height: maxY - minY,
+  });
+}
+
+function sceneRectIntersectionArea(a: SceneRectLike, b: SceneRectLike): number {
+  const left = Math.max(a.x, b.x);
+  const top = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return Math.max(0, right - left) * Math.max(0, bottom - top);
+}
+
+function sceneRectIou(a: SceneRectLike, b: SceneRectLike): number {
+  const intersection = sceneRectIntersectionArea(a, b);
+  if (intersection === 0) {
+    return 0;
+  }
+  const union = sceneRectArea(a) + sceneRectArea(b) - intersection;
+  return union <= 0 ? 0 : intersection / union;
+}
+
+function sceneRectOverlapRatio(a: SceneRectLike, b: SceneRectLike): number {
+  const intersection = sceneRectIntersectionArea(a, b);
+  if (intersection === 0) {
+    return 0;
+  }
+  const smallerArea = Math.min(sceneRectArea(a), sceneRectArea(b));
+  return smallerArea <= 0 ? 0 : intersection / smallerArea;
+}
+
+function mergeSceneObjects(candidates: SceneObjectLike[]): SceneObjectLike[] {
+  const merged: SceneObjectLike[] = [];
+  // Normalize and sort first so downstream merges keep the highest-confidence
+  // label/bounds pair when multiple detectors describe the same real-world
+  // subject (for example OCR + rectangle detection both finding a document).
+  const sorted = candidates
+    .map((candidate) => ({
+      ...candidate,
+      bounds: clampSceneRect(candidate.bounds),
+      confidence: clamp01(candidate.confidence),
+    }))
+    .filter((candidate) => sceneRectArea(candidate.bounds) > 0)
+    .sort((left, right) => right.confidence - left.confidence);
+
+  for (const candidate of sorted) {
+    const existing = merged.find((entry) => {
+      if (entry.label !== candidate.label) {
+        return false;
+      }
+      return (
+        sceneRectIou(entry.bounds, candidate.bounds) >= 0.4 ||
+        sceneRectOverlapRatio(entry.bounds, candidate.bounds) >= 0.8
+      );
+    });
+    if (existing) {
+      existing.bounds = unionSceneRects([existing.bounds, candidate.bounds]);
+      existing.confidence = Math.max(existing.confidence, candidate.confidence);
+      continue;
+    }
+    merged.push(candidate);
+  }
+
+  return merged;
+}
+
+function buildDocumentCandidatesFromText(text: SceneTextLike[]): SceneObjectLike[] {
+  const candidates = text.filter((entry) => entry.value.trim().length > 0);
+  if (candidates.length === 0) {
+    return [];
+  }
+
+  const rects = candidates.map((entry) => clampSceneRect(entry.bounds));
+  const union = unionSceneRects(rects);
+  const totalArea = rects.reduce((sum, rect) => sum + sceneRectArea(rect), 0);
+  // Treat dense or large text blocks as a document-like region. Small, isolated
+  // snippets stay labeled as plain text so agent consumers can distinguish a
+  // button label from a full sheet of paper.
+  const looksLikeDocument =
+    candidates.length > 1 || union.width >= 0.35 || union.height >= 0.28 || totalArea >= 0.08;
+
+  if (looksLikeDocument) {
+    return [
+      {
+        label: "document",
+        bounds: union,
+        confidence: candidates.length > 1 ? 0.72 : 0.64,
+      },
+    ];
+  }
+
+  return candidates.map((entry) => ({
+    label: "text",
+    bounds: clampSceneRect(entry.bounds),
+    confidence: 0.58,
+  }));
+}
+
+export function deriveSceneObjectsFromSignals(input: {
+  barcodes?: SceneBarcodeLike[] | null;
+  faces?: SceneFaceLike[] | null;
+  text?: SceneTextLike[] | null;
+  documentBounds?: SceneRectLike[] | null;
+}): SceneObjectLike[] {
+  const candidates: SceneObjectLike[] = [];
+
+  // The public `objects` surface is intentionally derived from the detector
+  // signals we already have. That keeps the API useful on platforms that lack
+  // a dedicated generic object detector while still reporting bounded subjects
+  // like people, documents, and barcodes in a stable way.
+  for (const barcode of input.barcodes ?? []) {
+    candidates.push({
+      label: "barcode",
+      bounds: barcode.bounds,
+      confidence: 0.94,
+    });
+  }
+
+  for (const face of input.faces ?? []) {
+    candidates.push({
+      label: "person",
+      bounds: face.bounds,
+      confidence: 0.86,
+    });
+  }
+
+  for (const bounds of input.documentBounds ?? []) {
+    candidates.push({
+      label: "document",
+      bounds,
+      confidence: 0.7,
+    });
+  }
+
+  candidates.push(...buildDocumentCandidatesFromText(input.text ?? []));
+  return mergeSceneObjects(candidates);
+}

package/src/clipboard/Clipboard.ts

@@ -0,0 +1,129 @@
+/**
+ * Clipboard - Web Clipboard API implementation for Ibex runtime
+ *
+ * Provides async read/write access to the system clipboard.
+ * By default, stores data in memory. When native bridge functions
+ * (__exactClipboardRead / __exactClipboardWrite) are available,
+ * they are used for actual system clipboard access.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Clipboard
+ * @see https://w3c.github.io/clipboard-apis/#clipboard-interface
+ */
+
+import { ClipboardItem } from './ClipboardItem';
+
+/**
+ * The Clipboard interface provides read and write access to the contents
+ * of the system clipboard, allowing cut, copy, and paste operations in
+ * web applications.
+ *
+ * This implementation falls back to in-memory storage when native clipboard
+ * access is not available. Native bridge functions can be plugged in via:
+ * - globalThis.__exactClipboardRead: () => string
+ * - globalThis.__exactClipboardWrite: (text: string) => void
+ */
+export class Clipboard {
+  /** In-memory fallback for clipboard text. */
+  #text: string = '';
+
+  /** In-memory fallback for clipboard items. */
+  #items: ClipboardItem[] = [];
+
+  /**
+   * Read text from the clipboard.
+   *
+   * Uses the native bridge if available (__exactClipboardRead),
+   * otherwise returns from in-memory storage.
+   *
+   * @returns A Promise resolving to the clipboard text content.
+   */
+  async readText(): Promise<string> {
+    const g = globalThis as any;
+    if (typeof g.__exactClipboardRead === 'function') {
+      return String(g.__exactClipboardRead());
+    }
+    return this.#text;
+  }
+
+  /**
+   * Write text to the clipboard.
+   *
+   * Uses the native bridge if available (__exactClipboardWrite),
+   * otherwise stores in memory.
+   *
+   * @param text - The text to write to the clipboard.
+   */
+  async writeText(text: string): Promise<void> {
+    const g = globalThis as any;
+    if (typeof g.__exactClipboardWrite === 'function') {
+      g.__exactClipboardWrite(String(text));
+    }
+    this.#text = String(text);
+    // Also update the items to keep them in sync
+    this.#items = [
+      new ClipboardItem({ 'text/plain': text }),
+    ];
+  }
+
+  /**
+   * Read structured data from the clipboard as ClipboardItem[].
+   *
+   * For now, returns items from the in-memory store. If only text was
+   * written, wraps it as a ClipboardItem with 'text/plain' type.
+   *
+   * @returns A Promise resolving to an array of ClipboardItems.
+   */
+  async read(): Promise<ClipboardItem[]> {
+    // If native bridge is available, read text and wrap it
+    const g = globalThis as any;
+    if (typeof g.__exactClipboardRead === 'function') {
+      const text = String(g.__exactClipboardRead());
+      if (text) {
+        return [new ClipboardItem({ 'text/plain': text })];
+      }
+      return [];
+    }
+
+    // Return a copy of the stored items
+    return [...this.#items];
+  }
+
+  /**
+   * Write structured data to the clipboard.
+   *
+   * Stores the items in memory. If any item contains 'text/plain',
+   * also updates the text representation for readText() compatibility.
+   *
+   * @param items - An array of ClipboardItems to write.
+   */
+  async write(items: ClipboardItem[]): Promise<void> {
+    if (!Array.isArray(items)) {
+      throw new TypeError('Clipboard.write: argument must be an array of ClipboardItems');
+    }
+
+    this.#items = [...items];
+
+    // Sync text representation from the first text/plain item
+    for (const item of items) {
+      if (item.types.includes('text/plain')) {
+        try {
+          const blob = await item.getType('text/plain');
+          this.#text = await blob.text();
+
+          // Also write to native if available
+          const g = globalThis as any;
+          if (typeof g.__exactClipboardWrite === 'function') {
+            g.__exactClipboardWrite(this.#text);
+          }
+        } catch {
+          // Ignore errors extracting text
+        }
+        break;
+      }
+    }
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'Clipboard';
+  }
+}

package/src/clipboard/ClipboardItem.ts

@@ -0,0 +1,97 @@
+/**
+ * ClipboardItem - Web Clipboard API ClipboardItem implementation
+ *
+ * Represents a single item on the clipboard, potentially with multiple
+ * representations (e.g., text/plain and text/html for the same content).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/ClipboardItem
+ * @see https://w3c.github.io/clipboard-apis/#clipboarditem
+ */
+
+/**
+ * A ClipboardItem represents data that can be placed on or read from
+ * the system clipboard. Each item can have multiple MIME-typed representations.
+ */
+export class ClipboardItem {
+  readonly #items: Map<string, Blob | string | Promise<Blob | string>>;
+  readonly #types: readonly string[];
+
+  /**
+   * Create a new ClipboardItem.
+   *
+   * @param items - A record mapping MIME types to their data. Values can be
+   *   Blob, string, or Promise resolving to either.
+   * @param options - Optional settings (presentationStyle, etc.) - reserved for future use.
+   */
+  constructor(
+    items: Record<string, Blob | string | Promise<Blob | string>>,
+    _options?: { presentationStyle?: 'unspecified' | 'inline' | 'attachment' },
+  ) {
+    if (!items || typeof items !== 'object') {
+      throw new TypeError('ClipboardItem constructor: items must be an object');
+    }
+
+    const keys = Object.keys(items);
+    if (keys.length === 0) {
+      throw new TypeError('ClipboardItem constructor: items must not be empty');
+    }
+
+    this.#items = new Map();
+    for (let i = 0; i < keys.length; i++) {
+      const type = keys[i];
+      this.#items.set(type, items[type]);
+    }
+    this.#types = Object.freeze([...keys]);
+  }
+
+  /**
+   * The MIME types available for this clipboard item.
+   */
+  get types(): readonly string[] {
+    return this.#types;
+  }
+
+  /**
+   * Retrieve the data for a specific MIME type as a Blob.
+   *
+   * @param type - The MIME type to retrieve.
+   * @returns A Promise resolving to a Blob containing the data.
+   * @throws DOMException with name "NotFoundError" if the type is not available.
+   */
+  async getType(type: string): Promise<Blob> {
+    const data = this.#items.get(type);
+    if (data === undefined) {
+      throw new DOMException(
+        `ClipboardItem.getType: type '${type}' not found`,
+        'NotFoundError',
+      );
+    }
+
+    const resolved = await data;
+
+    if (typeof resolved === 'string') {
+      return new Blob([resolved], { type });
+    }
+
+    if (resolved instanceof Blob) {
+      return resolved;
+    }
+
+    throw new TypeError(
+      `ClipboardItem.getType: unexpected data type for '${type}'`,
+    );
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'ClipboardItem';
+  }
+}
+
+// DOMException polyfill for this module
+class DOMException extends Error {
+  readonly code: number = 0;
+  constructor(message: string, name: string) {
+    super(message);
+    this.name = name;
+  }
+}

package/src/clipboard/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Web Clipboard API module exports
+ */
+
+export { Clipboard } from './Clipboard';
+export { ClipboardItem } from './ClipboardItem';

package/src/clone/index.ts

@@ -0,0 +1 @@
+export { structuredClone, type StructuredSerializeOptions } from './structuredClone';