@koiosdigital/matrx-render 0.1.0

package/dist/testing/index.d.ts

@@ -0,0 +1,22 @@
+import { a as Canvas, W as Widget, B as Bounds } from '../widget-DABrpucj.js';
+export { e as bounds } from '../widget-DABrpucj.js';
+
+/**
+ * Test utilities — port of pixlet render/testutil.go. Expected images are
+ * ASCII art with a color palette; comparison is byte-exact against the
+ * premultiplied canvas, just like the Go tests compare against image.RGBA.
+ */
+
+type Palette = Record<string, [number, number, number, number]>;
+declare const DEFAULT_PALETTE: Palette;
+declare function printImage(im: Canvas, palette?: Palette): string;
+/**
+ * Assert the canvas matches the expected ASCII art. Throws with an
+ * EXPECTED/ACTUAL dump on mismatch (Go's checkImage returns an error).
+ */
+declare function checkImage(expected: string[], actual: Canvas, palette?: Palette): void;
+/** Port of testutil.PaintWidget: canvas sized by the widget's paintBounds,
+ * painted with the given layout bounds. */
+declare function paintWidget(w: Widget, b: Bounds, frameIdx: number): Canvas;
+
+export { DEFAULT_PALETTE, type Palette, checkImage, paintWidget, printImage };

package/dist/testing/index.js

@@ -0,0 +1,76 @@
+import {
+  Canvas,
+  DrawContext,
+  bounds
+} from "../chunk-NASKU36A.js";
+
+// src/testing/index.ts
+var DEFAULT_PALETTE = {
+  r: [255, 0, 0, 255],
+  g: [0, 255, 0, 255],
+  b: [0, 0, 255, 255],
+  w: [255, 255, 255, 255],
+  ".": [0, 0, 0, 0],
+  x: [0, 0, 0, 255]
+};
+function printImage(im, palette = DEFAULT_PALETTE) {
+  const toAscii = /* @__PURE__ */ new Map();
+  for (const [ch, rgba] of Object.entries(palette)) {
+    toAscii.set(rgba.join(","), ch);
+  }
+  let out = "";
+  for (let y = 0; y < im.height; y++) {
+    for (let x = 0; x < im.width; x++) {
+      out += toAscii.get(im.at(x, y).join(",")) ?? "?";
+    }
+    out += "\n";
+  }
+  return out;
+}
+function diff(expected, actual, palette) {
+  return `EXPECTED
+${expected.join("\n")}
+ACTUAL
+${printImage(actual, palette)}`;
+}
+function checkImage(expected, actual, palette = DEFAULT_PALETTE) {
+  if (expected.length !== actual.height) {
+    throw new Error(
+      `expected ${expected.length} rows, found ${actual.height}
+` + diff(expected, actual, palette)
+    );
+  }
+  for (let y = 0; y < actual.height; y++) {
+    const row = expected[y];
+    if (row.length !== actual.width) {
+      throw new Error(
+        `row ${y}: expected ${row.length} columns, found ${actual.width}
+` + diff(expected, actual, palette)
+      );
+    }
+    for (let x = 0; x < actual.width; x++) {
+      const want = palette[row[x]];
+      const got = actual.at(x, y);
+      if (!want || want[0] !== got[0] || want[1] !== got[1] || want[2] !== got[2] || want[3] !== got[3]) {
+        throw new Error(
+          `color differs at ${x},${y}
+` + diff(expected, actual, palette)
+        );
+      }
+    }
+  }
+}
+function paintWidget(w, b, frameIdx) {
+  const pb = w.paintBounds(b, frameIdx);
+  const canvas = new Canvas(pb.w, pb.h);
+  const dc = new DrawContext(canvas);
+  w.paint(dc, b, frameIdx);
+  return canvas;
+}
+export {
+  DEFAULT_PALETTE,
+  bounds,
+  checkImage,
+  paintWidget,
+  printImage
+};

package/dist/webp-D106DLhy.d.ts

@@ -0,0 +1,84 @@
+import { W as Widget, B as Bounds, D as DrawContext, a as Canvas } from './widget-DABrpucj.js';
+
+/**
+ * Image — port of pixlet render/image.go. Decodes PNG / animated GIF /
+ * WebP (via an injected decoder), scales with nearest-neighbor when
+ * width/height are set (aspect preserved when only one is given), and for
+ * animated GIFs replays Go Image.InitFromGIF's frame-composition logic —
+ * including its disposal-method quirks — exactly.
+ *
+ * JPEG and SVG are not supported yet (M3); they fail with a clear error.
+ */
+
+/** Optional WebP decoder (WASM), injected by the host/runtime. */
+type WebpDecoder = (data: Uint8Array) => Promise<{
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+}>;
+declare function setWebpDecoder(decoder: WebpDecoder | null): void;
+declare class Image implements Widget {
+    /** Binary image data. */
+    src: Uint8Array;
+    width: number;
+    height: number;
+    /** (Read-only) frame delay in ms, for animated GIFs. */
+    delay: number;
+    private imgs;
+    constructor(props: {
+        src: Uint8Array;
+        width?: number;
+        height?: number;
+    });
+    private initFromGif;
+    init(): Promise<void>;
+    private frame;
+    size(): [number, number];
+    paintBounds(_b: Bounds, frameIdx: number): Bounds;
+    paint(dc: DrawContext, _b: Bounds, frameIdx: number): void;
+    frameCount(): number;
+}
+
+/**
+ * Animated WebP encoding — the TS counterpart of pixlet encode/webp.go +
+ * encode/encode.go.
+ *
+ * Per-frame bitstream encoding is delegated to an injected `FrameEncoder`
+ * (WASM libwebp — see webp-jsquash.ts); this module owns the deterministic
+ * parts: frame-duration policy (delay + maxDuration cap, ported from
+ * EncodeWebP) and the animation container mux (VP8X/ANIM/ANMF assembly,
+ * the moral equivalent of libwebp's WebPAnimEncoderAssemble with
+ * kmin=kmax=0 — every frame an independent keyframe, no blending).
+ *
+ * Determinism: container assembly is pure; frame bitstreams are
+ * deterministic for a pinned libwebp build + settings (handoff §8 — fold
+ * the encoder version into the cache key at the render-plane layer).
+ */
+
+/** Encodes one straight-RGBA frame to a complete (still) WebP file. */
+type FrameEncoder = (rgba: Uint8Array, width: number, height: number) => Promise<Uint8Array>;
+/** encode.go DefaultScreenDelayMillis. */
+declare const DEFAULT_SCREEN_DELAY_MILLIS = 50;
+interface EncodeWebpOptions {
+    encoder: FrameEncoder;
+    /**
+     * Frame delay in ms (Root.delay). Values <= 0 fall back to the default
+     * 50ms, mirroring encode.go ScreensFromRoots.
+     */
+    delayMs?: number;
+    /**
+     * Cap on total animation duration in ms; 0 disables the cap. Frame
+     * durations are truncated and trailing frames dropped, mirroring
+     * EncodeWebP's remainingDuration loop.
+     */
+    maxDurationMs?: number;
+    /** ANIM loop count; 0 = loop forever (libwebp default). */
+    loopCount?: number;
+}
+/**
+ * Encode frames to an animated WebP. Returns an empty array for zero frames
+ * (EncodeWebP returns []byte{}).
+ */
+declare function encodeWebp(frames: Canvas[], opts: EncodeWebpOptions): Promise<Uint8Array>;
+
+export { DEFAULT_SCREEN_DELAY_MILLIS as D, type FrameEncoder as F, Image as I, type WebpDecoder as W, encodeWebp as e, setWebpDecoder as s };

package/dist/widget-DABrpucj.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Colors. Mirrors `pixlet/render/colors.go` (ParseColor) and Go's
+ * `color.NRGBA` — straight (non-premultiplied) 8-bit RGBA.
+ */
+/** Straight-alpha 8-bit color, like Go color.NRGBA. */
+interface Color {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+declare const WHITE: Color;
+declare const BLACK: Color;
+declare const TRANSPARENT: Color;
+/**
+ * Parse `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` (leading `#` optional — one is
+ * stripped, mirroring Go strings.TrimPrefix). Port of render.ParseColor.
+ */
+declare function parseColor(scol: string): Color;
+/**
+ * 16-bit premultiplied color, i.e. what Go's `color.NRGBA.RGBA()` returns.
+ * All blend math runs on these, mirroring Go exactly:
+ *   v16 = (v8 * 0x101 * a8) / 0xff   (integer division)
+ */
+interface Color16 {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+declare function color16(c: Color): Color16;
+
+/**
+ * Canvas — an RGBA pixel buffer with premultiplied alpha, mirroring Go's
+ * `image.RGBA` (which is what gg renders into). 4 bytes per pixel, row-major.
+ */
+
+declare class Canvas {
+    readonly width: number;
+    readonly height: number;
+    /** Premultiplied RGBA, length = width * height * 4. */
+    readonly pix: Uint8Array;
+    constructor(width: number, height: number);
+    /**
+     * Fill every pixel with `c`, ignoring any clip — mirrors gg.Clear()
+     * (draw.Src over the whole image). Used by Root for solid backgrounds.
+     */
+    clear(c: Color): void;
+    /** Premultiplied RGBA of pixel (x, y). Out of bounds returns zeros. */
+    at(x: number, y: number): [number, number, number, number];
+}
+
+/**
+ * Analytic polygon-coverage rasterization for affine-transformed rectangles
+ * (Transformation with scale/rotate, and eventually Circle/Plot paths).
+ *
+ * Parity note: pixlet rasterizes through freetype/raster, whose span
+ * accumulation produces near-exact area coverage. We compute exact per-pixel
+ * polygon area (Sutherland–Hodgman clip against each pixel square). Results
+ * are integer-identical for axis-aligned integer rectangles and within the
+ * project's perceptual-tolerance bar (§14, "locked") for AA edges. Integer
+ * translations never reach this path — they use the exact fast paths.
+ */
+interface Pt {
+    x: number;
+    y: number;
+}
+
+/**
+ * DrawContext — the subset of tidbyt/gg's Context that pixlet's widgets use:
+ * Push/Pop, Translate/Scale/Rotate (+ *About variants), SetColor,
+ * DrawRectangle+Fill, DrawRectangle+Clip, DrawImage.
+ *
+ * Two rendering regimes, chosen per-operation:
+ *
+ *  - Integer translation (all of pixlet's static widgets): exact fast paths
+ *    whose integer blend math mirrors freetype/gg byte-for-byte. This is the
+ *    regime the ported pixlet unit tests pin down.
+ *  - General affine (Transformation's scale/rotate): rectangles become
+ *    convex quads filled via analytic polygon coverage; images are
+ *    inverse-mapped with bilinear sampling (x/image/draw-style). Perceptual
+ *    parity per the locked bar (§14) — byte-exact freetype span replication
+ *    is deliberately out of scope.
+ *
+ * The clip is a full-canvas alpha mask (like gg's `mask *image.Alpha`).
+ * Intersection is per-pixel multiplication — gg.Clip()'s DrawMask(Over onto
+ * empty) composition. Push/Pop snapshot {matrix, color, mask}; masks are
+ * immutable once installed, so snapshots share them.
+ */
+
+declare class DrawContext {
+    readonly canvas: Canvas;
+    private st;
+    private stack;
+    constructor(canvas: Canvas);
+    push(): void;
+    pop(): void;
+    translate(dx: number, dy: number): void;
+    scale(sx: number, sy: number): void;
+    /** Anticlockwise rotation about the origin, radians. */
+    rotate(angle: number): void;
+    scaleAbout(sx: number, sy: number, x: number, y: number): void;
+    rotateAbout(angle: number, x: number, y: number): void;
+    setColor(c: Color): void;
+    /** Transformed corners of rect (x,y,w,h), in path order. */
+    private rectQuad;
+    /**
+     * gg DrawRectangle(x,y,w,h) + Fill().
+     * A negative width/height rectangle is a reversed-winding path covering
+     * [x+w, x] × [y+h, y]; the non-zero winding rule still fills it.
+     */
+    fillRect(x: number, y: number, w: number, h: number): void;
+    /**
+     * gg DrawRectangle(x,y,w,h) + Clip(): intersect the clip region with the
+     * given rectangle (in current-transform space).
+     */
+    clipRect(x: number, y: number, w: number, h: number): void;
+    /**
+     * gg SetPixel: sets the pixel to the current color, converting like Go's
+     * image.RGBA.Set (NRGBA → premultiplied). Note: like gg, this *ignores*
+     * the clip mask and compositing — it is a raw store. Plot depends on it.
+     */
+    setPixel(x: number, y: number): void;
+    /** Apply the current matrix to a point (gg TransformPoint). */
+    transformPoint(x: number, y: number): Pt;
+    /**
+     * Fill an arbitrary polygon given in local (pre-transform) coordinates
+     * with the current color — the gg path-Fill equivalent for non-rect
+     * shapes (Circle, PieChart). Coverage-based AA, honors the clip mask.
+     */
+    fillPolygon(localPts: Pt[]): void;
+    /** gg DrawImage(src, x, y) with the current transform and clip. */
+    drawCanvas(src: Canvas, x: number, y: number): void;
+}
+
+/**
+ * Bounds is the (width, height) of a layout rectangle.
+ *
+ * Pixlet passes Go `image.Rectangle` values constructed as
+ * `image.Rect(0, 0, w, h)` throughout layout, and widgets only ever consume
+ * `Dx()`/`Dy()`. Go canonicalizes rectangles — negative extents swap min/max —
+ * so `Dx()`/`Dy()` come out as the *absolute value*. Pixlet relies on this:
+ * e.g. `Padding.PaintBounds` computes `bounds.Dx()-Left-Right`, which can go
+ * negative and silently becomes positive again (see TestPadding "small
+ * bounds": a 4×4 bound with pad l1/t2/r3/b4 measures the child against 0×2).
+ *
+ * `bounds()` mirrors that behavior exactly. Do not "fix" it — parity with the
+ * Go renderer depends on it.
+ */
+interface Bounds {
+    readonly w: number;
+    readonly h: number;
+}
+/** Mirror of Go `image.Rect(0, 0, w, h)` → `(Dx(), Dy())`. */
+declare function bounds(w: number, h: number): Bounds;
+
+/** Widget contract. Mirrors pixlet render/widget.go. */
+
+interface Widget {
+    /** Bounds of the area that will actually be drawn to when paint() is called. */
+    paintBounds(bounds: Bounds, frameIdx: number): Bounds;
+    paint(dc: DrawContext, bounds: Bounds, frameIdx: number): void;
+    frameCount(): number;
+    /** Widgets can require initialization (Text, Image, WrappedText). */
+    init?(): void | Promise<void>;
+    /** WidgetStaticSize: inherent size known before painting. */
+    size?(): [number, number];
+}
+/** Computes a (mod m), non-negative. */
+declare function modInt(a: number, m: number): number;
+/** Maximum frame count of a slice of widgets (minimum 1). */
+declare function maxFrameCount(widgets: Widget[]): number;
+
+export { type Bounds as B, type Color16 as C, DrawContext as D, TRANSPARENT as T, type Widget as W, Canvas as a, type Color as b, BLACK as c, WHITE as d, bounds as e, color16 as f, modInt as g, maxFrameCount as m, parseColor as p };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@koiosdigital/matrx-render",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./testing": "./dist/testing/index.js",
+    "./webp-jsquash": "./dist/encode/webp-jsquash.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@jsquash/webp": "^1.5.0",
+    "fflate": "^0.8.3",
+    "@koiosdigital/matrx-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koiosdigital/matrx-render.git",
+    "directory": "packages/render"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "gen:fonts": "node scripts/gen-fonts.mjs",
+    "build:dist": "tsup src/index.ts src/testing/index.ts src/encode/webp-jsquash.ts --format esm --dts --clean --out-dir dist"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}