@arcane-engine/runtime 0.1.0

package/src/testing/mock-renderer.ts

@@ -0,0 +1,178 @@
+/**
+ * Mock renderer for testing visual code without GPU
+ * Validates API calls and parameter types
+ */
+
+export interface MockCall {
+  api: string;
+  params: any[];
+  timestamp: number;
+}
+
+class MockRenderer {
+  private calls: MockCall[] = [];
+  private errors: string[] = [];
+
+  // Track all rendering calls
+  drawSprite(opts: any) {
+    this.calls.push({ api: "drawSprite", params: [opts], timestamp: Date.now() });
+    this.validateDrawSpriteParams(opts);
+  }
+
+  drawText(text: string, opts: any) {
+    this.calls.push({ api: "drawText", params: [text, opts], timestamp: Date.now() });
+    this.validateDrawTextParams(text, opts);
+  }
+
+  drawRect(x: any, y: any, w: any, h: any, opts?: any) {
+    this.calls.push({ api: "drawRect", params: [x, y, w, h, opts], timestamp: Date.now() });
+    this.validateDrawRectParams(x, y, w, h, opts);
+  }
+
+  // Validation methods
+  private validateDrawSpriteParams(opts: any) {
+    if (typeof opts !== "object") {
+      this.addError("drawSprite: params must be object");
+      return;
+    }
+
+    if (typeof opts.textureId !== "number") {
+      this.addError("drawSprite: textureId must be number");
+    }
+
+    this.validateNumber("drawSprite", "x", opts.x);
+    this.validateNumber("drawSprite", "y", opts.y);
+    this.validateNumber("drawSprite", "w", opts.w);
+    this.validateNumber("drawSprite", "h", opts.h);
+
+    if (opts.layer !== undefined) {
+      this.validateNumber("drawSprite", "layer", opts.layer);
+    }
+  }
+
+  private validateDrawTextParams(text: string, opts: any) {
+    if (typeof text !== "string") {
+      this.addError("drawText: text must be string");
+    }
+
+    if (typeof opts !== "object") {
+      this.addError("drawText: opts must be object");
+      return;
+    }
+
+    this.validateNumber("drawText", "x", opts.x);
+    this.validateNumber("drawText", "y", opts.y);
+    this.validateNumber("drawText", "size", opts.size);
+
+    if (opts.color) {
+      this.validateColor("drawText", opts.color);
+    }
+  }
+
+  private validateDrawRectParams(x: any, y: any, w: any, h: any, opts?: any) {
+    this.validateNumber("drawRect", "x", x);
+    this.validateNumber("drawRect", "y", y);
+    this.validateNumber("drawRect", "w", w);
+    this.validateNumber("drawRect", "h", h);
+
+    if (opts?.color) {
+      this.validateColor("drawRect", opts.color);
+    }
+  }
+
+  private validateNumber(api: string, param: string, value: any) {
+    if (typeof value !== "number") {
+      this.addError(`${api}: ${param} must be number, got ${typeof value}`);
+    } else if (isNaN(value)) {
+      this.addError(`${api}: ${param} is NaN`);
+    } else if (!isFinite(value)) {
+      this.addError(`${api}: ${param} is not finite`);
+    }
+  }
+
+  private validateColor(api: string, color: any) {
+    if (typeof color !== "object") {
+      this.addError(`${api}: color must be object`);
+      return;
+    }
+
+    const { r, g, b } = color;
+
+    if (typeof r !== "number" || r < 0 || r > 1) {
+      this.addError(`${api}: color.r must be 0.0-1.0, got ${r}`);
+    }
+    if (typeof g !== "number" || g < 0 || g > 1) {
+      this.addError(`${api}: color.g must be 0.0-1.0, got ${g}`);
+    }
+    if (typeof b !== "number" || b < 0 || b > 1) {
+      this.addError(`${api}: color.b must be 0.0-1.0, got ${b}`);
+    }
+  }
+
+  private addError(message: string) {
+    this.errors.push(message);
+  }
+
+  // Query methods for tests
+  getCalls(api?: string): MockCall[] {
+    if (api) {
+      return this.calls.filter((c) => c.api === api);
+    }
+    return this.calls;
+  }
+
+  getErrors(): string[] {
+    return this.errors;
+  }
+
+  hasErrors(): boolean {
+    return this.errors.length > 0;
+  }
+
+  reset() {
+    this.calls = [];
+    this.errors = [];
+  }
+
+  // Assert helpers for tests
+  assertNoErrors() {
+    if (this.hasErrors()) {
+      throw new Error(
+        "Rendering errors found:\n" + this.errors.map((e) => `  - ${e}`).join("\n")
+      );
+    }
+  }
+
+  assertCalled(api: string, minTimes: number = 1) {
+    const calls = this.getCalls(api);
+    if (calls.length < minTimes) {
+      throw new Error(`Expected ${api} to be called at least ${minTimes} times, got ${calls.length}`);
+    }
+  }
+
+  assertNotCalled(api: string) {
+    const calls = this.getCalls(api);
+    if (calls.length > 0) {
+      throw new Error(`Expected ${api} not to be called, but it was called ${calls.length} times`);
+    }
+  }
+}
+
+// Global mock instance
+export const mockRenderer = new MockRenderer();
+
+// Helper to install mock renderer
+export function installMockRenderer() {
+  // Replace global rendering functions with mock versions
+  (globalThis as any).drawSprite = mockRenderer.drawSprite.bind(mockRenderer);
+  (globalThis as any).drawText = mockRenderer.drawText.bind(mockRenderer);
+  (globalThis as any).drawRect = mockRenderer.drawRect.bind(mockRenderer);
+}
+
+// Helper to restore real renderer
+export function restoreRenderer() {
+  // Remove mocks (real functions will be restored on next import)
+  delete (globalThis as any).drawSprite;
+  delete (globalThis as any).drawText;
+  delete (globalThis as any).drawRect;
+}

package/src/ui/index.ts

@@ -0,0 +1,3 @@
+export type { Color, RectOptions, PanelOptions, BarOptions, LabelOptions } from "./types.ts";
+export { rgb } from "./types.ts";
+export { drawRect, drawPanel, drawBar, drawLabel } from "./primitives.ts";

package/src/ui/primitives.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, assert } from "../../runtime/testing/harness.ts";
+import { drawRect, drawPanel, drawBar, drawLabel } from "./primitives.ts";
+import { rgb } from "./types.ts";
+
+describe("rgb helper", () => {
+  it("should normalize 0-255 values to 0.0-1.0 range", () => {
+    const color = rgb(255, 128, 0);
+    assert.equal(color.r, 1.0, "r should be 1.0");
+    assert.equal(color.g, 128 / 255, "g should be ~0.502");
+    assert.equal(color.b, 0.0, "b should be 0.0");
+    assert.equal(color.a, 1.0, "a should default to 1.0");
+  });
+
+  it("should accept optional alpha parameter", () => {
+    const color = rgb(255, 0, 0, 128);
+    assert.equal(color.r, 1.0, "r should be 1.0");
+    assert.equal(color.g, 0.0, "g should be 0.0");
+    assert.equal(color.b, 0.0, "b should be 0.0");
+    assert.equal(color.a, 128 / 255, "a should be ~0.502");
+  });
+
+  it("should handle black (0, 0, 0)", () => {
+    const color = rgb(0, 0, 0);
+    assert.equal(color.r, 0.0, "r should be 0.0");
+    assert.equal(color.g, 0.0, "g should be 0.0");
+    assert.equal(color.b, 0.0, "b should be 0.0");
+    assert.equal(color.a, 1.0, "a should be 1.0");
+  });
+
+  it("should handle white (255, 255, 255)", () => {
+    const color = rgb(255, 255, 255);
+    assert.equal(color.r, 1.0, "r should be 1.0");
+    assert.equal(color.g, 1.0, "g should be 1.0");
+    assert.equal(color.b, 1.0, "b should be 1.0");
+    assert.equal(color.a, 1.0, "a should be 1.0");
+  });
+
+  it("should handle fully transparent (255, 255, 255, 0)", () => {
+    const color = rgb(255, 255, 255, 0);
+    assert.equal(color.r, 1.0, "r should be 1.0");
+    assert.equal(color.g, 1.0, "g should be 1.0");
+    assert.equal(color.b, 1.0, "b should be 1.0");
+    assert.equal(color.a, 0.0, "a should be 0.0");
+  });
+});
+
+describe("ui primitives", () => {
+  it("drawRect does not throw in headless mode", () => {
+    drawRect(10, 20, 100, 50);
+    drawRect(0, 0, 200, 100, { color: { r: 1, g: 0, b: 0, a: 1 } });
+  });
+
+  it("drawPanel does not throw in headless mode", () => {
+    drawPanel(10, 20, 200, 100);
+    drawPanel(0, 0, 300, 200, {
+      fillColor: { r: 0.1, g: 0.1, b: 0.2, a: 0.9 },
+      borderColor: { r: 0.8, g: 0.8, b: 0.8, a: 1 },
+      borderWidth: 3,
+    });
+  });
+
+  it("drawBar does not throw in headless mode", () => {
+    drawBar(10, 20, 100, 16, 0.75);
+    drawBar(0, 0, 200, 20, 1.0, {
+      fillColor: { r: 0, g: 1, b: 0, a: 1 },
+      bgColor: { r: 0.3, g: 0, b: 0, a: 1 },
+    });
+  });
+
+  it("drawBar clamps fill ratio to 0-1", () => {
+    // Should not throw with out-of-range values
+    drawBar(0, 0, 100, 10, -0.5);
+    drawBar(0, 0, 100, 10, 2.0);
+  });
+
+  it("drawBar with border does not throw in headless mode", () => {
+    drawBar(10, 20, 100, 16, 0.5, {
+      borderColor: { r: 1, g: 1, b: 1, a: 1 },
+      borderWidth: 1,
+    });
+  });
+
+  it("drawLabel does not throw in headless mode", () => {
+    drawLabel("Hello", 10, 20);
+    drawLabel("Score: 42", 100, 50, {
+      textColor: { r: 1, g: 1, b: 0, a: 1 },
+      padding: 8,
+      scale: 2,
+    });
+  });
+
+  it("drawPanel with zero border width works", () => {
+    drawPanel(0, 0, 100, 50, { borderWidth: 0 });
+  });
+
+  it("drawLabel with custom colors works", () => {
+    drawLabel("HP", 0, 0, {
+      textColor: { r: 1, g: 0, b: 0, a: 1 },
+      bgColor: { r: 0, g: 0, b: 0, a: 0.8 },
+      borderColor: { r: 0.5, g: 0.5, b: 0.5, a: 1 },
+      borderWidth: 2,
+      padding: 6,
+    });
+  });
+});

package/src/ui/primitives.ts

@@ -0,0 +1,260 @@
+import type { Color, RectOptions, PanelOptions, BarOptions, LabelOptions } from "./types.ts";
+import { drawSprite } from "../rendering/sprites.ts";
+import { createSolidTexture } from "../rendering/texture.ts";
+import { drawText, measureText } from "../rendering/text.ts";
+import { getCamera } from "../rendering/camera.ts";
+
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_draw_sprite === "function";
+
+const hasViewportOp =
+  typeof (globalThis as any).Deno?.core?.ops?.op_get_viewport_size === "function";
+
+function getViewportSize(): [number, number] {
+  if (!hasViewportOp) return [800, 600];
+  const [w, h] = (globalThis as any).Deno.core.ops.op_get_viewport_size();
+  return [w, h];
+}
+
+/** Cache solid textures by color key to avoid re-creating them every frame. */
+const textureCache = new Map<string, number>();
+
+function getColorTexture(color: Color): number {
+  const key = `${color.r}_${color.g}_${color.b}_${color.a}`;
+  let tex = textureCache.get(key);
+  if (tex !== undefined) return tex;
+  tex = createSolidTexture(
+    key,
+    Math.round(color.r * 255),
+    Math.round(color.g * 255),
+    Math.round(color.b * 255),
+    Math.round(color.a * 255),
+  );
+  textureCache.set(key, tex);
+  return tex;
+}
+
+/** Default colors. */
+const WHITE: Color = { r: 1, g: 1, b: 1, a: 1 };
+const DARK: Color = { r: 0.1, g: 0.1, b: 0.15, a: 0.9 };
+const GRAY: Color = { r: 0.5, g: 0.5, b: 0.5, a: 1 };
+const GREEN: Color = { r: 0.2, g: 0.8, b: 0.2, a: 1 };
+const RED: Color = { r: 0.3, g: 0.1, b: 0.1, a: 0.8 };
+
+function toWorld(
+  sx: number,
+  sy: number,
+  sw: number,
+  sh: number,
+  screenSpace: boolean,
+): { x: number; y: number; w: number; h: number } {
+  if (!screenSpace) return { x: sx, y: sy, w: sw, h: sh };
+  const cam = getCamera();
+  const [vpW, vpH] = getViewportSize();
+  return {
+    x: sx / cam.zoom + cam.x - vpW / (2 * cam.zoom),
+    y: sy / cam.zoom + cam.y - vpH / (2 * cam.zoom),
+    w: sw / cam.zoom,
+    h: sh / cam.zoom,
+  };
+}
+
+/**
+ * Draw a filled rectangle.
+ * No-op in headless mode.
+ */
+export function drawRect(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  options?: RectOptions,
+): void {
+  if (!hasRenderOps) return;
+  const color = options?.color ?? WHITE;
+  const layer = options?.layer ?? 90;
+  const ss = options?.screenSpace ?? false;
+  const tex = getColorTexture(color);
+  const pos = toWorld(x, y, w, h, ss);
+  const posX = pos.x;
+  const posY = pos.y;
+  const posW = pos.w;
+  const posH = pos.h;
+  drawSprite({ textureId: tex, x: posX, y: posY, w: posW, h: posH, layer });
+}
+
+/**
+ * Draw a panel with border and fill.
+ * Uses 5 sprites: 4 border edges + 1 fill.
+ * No-op in headless mode.
+ */
+export function drawPanel(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  options?: PanelOptions,
+): void {
+  if (!hasRenderOps) return;
+  const fillColor = options?.fillColor ?? DARK;
+  const borderColor = options?.borderColor ?? GRAY;
+  const bw = options?.borderWidth ?? 2;
+  const layer = options?.layer ?? 90;
+  const ss = options?.screenSpace ?? false;
+
+  const fillTex = getColorTexture(fillColor);
+  const borderTex = getColorTexture(borderColor);
+
+  // Fill (inset by border width)
+  const fill = toWorld(x + bw, y + bw, w - 2 * bw, h - 2 * bw, ss);
+  const fillX = fill.x;
+  const fillY = fill.y;
+  const fillW = fill.w;
+  const fillH = fill.h;
+  drawSprite({ textureId: fillTex, x: fillX, y: fillY, w: fillW, h: fillH, layer });
+
+  // Top border
+  const top = toWorld(x, y, w, bw, ss);
+  const topX = top.x;
+  const topY = top.y;
+  const topW = top.w;
+  const topH = top.h;
+  drawSprite({ textureId: borderTex, x: topX, y: topY, w: topW, h: topH, layer: layer + 1 });
+
+  // Bottom border
+  const bot = toWorld(x, y + h - bw, w, bw, ss);
+  const botX = bot.x;
+  const botY = bot.y;
+  const botW = bot.w;
+  const botH = bot.h;
+  drawSprite({ textureId: borderTex, x: botX, y: botY, w: botW, h: botH, layer: layer + 1 });
+
+  // Left border
+  const left = toWorld(x, y + bw, bw, h - 2 * bw, ss);
+  const leftX = left.x;
+  const leftY = left.y;
+  const leftW = left.w;
+  const leftH = left.h;
+  drawSprite({ textureId: borderTex, x: leftX, y: leftY, w: leftW, h: leftH, layer: layer + 1 });
+
+  // Right border
+  const right = toWorld(x + w - bw, y + bw, bw, h - 2 * bw, ss);
+  const rightX = right.x;
+  const rightY = right.y;
+  const rightW = right.w;
+  const rightH = right.h;
+  drawSprite({ textureId: borderTex, x: rightX, y: rightY, w: rightW, h: rightH, layer: layer + 1 });
+}
+
+/**
+ * Draw a progress/health bar.
+ * fillRatio is 0.0 to 1.0 (clamped).
+ * No-op in headless mode.
+ */
+export function drawBar(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  fillRatio: number,
+  options?: BarOptions,
+): void {
+  if (!hasRenderOps) return;
+  const ratio = Math.max(0, Math.min(1, fillRatio));
+  const bgColor = options?.bgColor ?? RED;
+  const fillColor = options?.fillColor ?? GREEN;
+  const borderColor = options?.borderColor;
+  const bw = options?.borderWidth ?? 0;
+  const layer = options?.layer ?? 90;
+  const ss = options?.screenSpace ?? false;
+
+  // Background
+  const bg = toWorld(x, y, w, h, ss);
+  const bgTex = getColorTexture(bgColor);
+  const bgX = bg.x;
+  const bgY = bg.y;
+  const bgW = bg.w;
+  const bgH = bg.h;
+  drawSprite({ textureId: bgTex, x: bgX, y: bgY, w: bgW, h: bgH, layer });
+
+  // Fill (inset by border if present)
+  const inset = bw;
+  const fillW = (w - 2 * inset) * ratio;
+  if (fillW > 0) {
+    const fill = toWorld(x + inset, y + inset, fillW, h - 2 * inset, ss);
+    const fillTex = getColorTexture(fillColor);
+    const fillX = fill.x;
+    const fillY = fill.y;
+    const fillW2 = fill.w;
+    const fillH = fill.h;
+    drawSprite({ textureId: fillTex, x: fillX, y: fillY, w: fillW2, h: fillH, layer: layer + 1 });
+  }
+
+  // Optional border
+  if (borderColor && bw > 0) {
+    const borderTex = getColorTexture(borderColor);
+    const top = toWorld(x, y, w, bw, ss);
+    const topX = top.x;
+    const topY = top.y;
+    const topW = top.w;
+    const topH = top.h;
+    drawSprite({ textureId: borderTex, x: topX, y: topY, w: topW, h: topH, layer: layer + 2 });
+    const bot = toWorld(x, y + h - bw, w, bw, ss);
+    const botX = bot.x;
+    const botY = bot.y;
+    const botW = bot.w;
+    const botH = bot.h;
+    drawSprite({ textureId: borderTex, x: botX, y: botY, w: botW, h: botH, layer: layer + 2 });
+    const left = toWorld(x, y + bw, bw, h - 2 * bw, ss);
+    const leftX = left.x;
+    const leftY = left.y;
+    const leftW = left.w;
+    const leftH = left.h;
+    drawSprite({ textureId: borderTex, x: leftX, y: leftY, w: leftW, h: leftH, layer: layer + 2 });
+    const right = toWorld(x + w - bw, y + bw, bw, h - 2 * bw, ss);
+    const rightX = right.x;
+    const rightY = right.y;
+    const rightW = right.w;
+    const rightH = right.h;
+    drawSprite({ textureId: borderTex, x: rightX, y: rightY, w: rightW, h: rightH, layer: layer + 2 });
+  }
+}
+
+/**
+ * Draw a text label with optional background panel.
+ * No-op in headless mode.
+ */
+export function drawLabel(
+  text: string,
+  x: number,
+  y: number,
+  options?: LabelOptions,
+): void {
+  if (!hasRenderOps) return;
+  const padding = options?.padding ?? 4;
+  const scale = options?.scale ?? 1;
+  const layer = options?.layer ?? 90;
+  const ss = options?.screenSpace ?? false;
+
+  const measurement = measureText(text, { scale });
+  const panelW = measurement.width + padding * 2;
+  const panelH = measurement.height + padding * 2;
+
+  // Background panel
+  drawPanel(x, y, panelW, panelH, {
+    fillColor: options?.bgColor ?? DARK,
+    borderColor: options?.borderColor ?? GRAY,
+    borderWidth: options?.borderWidth ?? 1,
+    layer,
+    screenSpace: ss,
+  });
+
+  // Text
+  drawText(text, x + padding, y + padding, {
+    scale,
+    tint: options?.textColor ?? WHITE,
+    layer: layer + 3,
+    screenSpace: ss,
+  });
+}

package/src/ui/types.ts

@@ -0,0 +1,57 @@
+/** RGBA color with 0-1 float components (matching sprite tint). */
+export type Color = {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+};
+
+/**
+ * Create a Color from 0-255 RGB(A) values, auto-normalized to 0.0-1.0 range.
+ *
+ * @example
+ * rgb(255, 128, 0)        // Orange, fully opaque
+ * rgb(255, 0, 0, 128)     // Red, 50% transparent
+ */
+export function rgb(r: number, g: number, b: number, a: number = 255): Color {
+  return {
+    r: r / 255.0,
+    g: g / 255.0,
+    b: b / 255.0,
+    a: a / 255.0,
+  };
+}
+
+export type RectOptions = {
+  color?: Color;
+  layer?: number;
+  screenSpace?: boolean;
+};
+
+export type PanelOptions = {
+  fillColor?: Color;
+  borderColor?: Color;
+  borderWidth?: number;
+  layer?: number;
+  screenSpace?: boolean;
+};
+
+export type BarOptions = {
+  fillColor?: Color;
+  bgColor?: Color;
+  borderColor?: Color;
+  borderWidth?: number;
+  layer?: number;
+  screenSpace?: boolean;
+};
+
+export type LabelOptions = {
+  textColor?: Color;
+  bgColor?: Color;
+  borderColor?: Color;
+  borderWidth?: number;
+  padding?: number;
+  scale?: number;
+  layer?: number;
+  screenSpace?: boolean;
+};