@koiosdigital/matrx-render 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,654 @@
+import { C as Color16, a as Canvas, W as Widget, b as Color, B as Bounds, D as DrawContext } from './widget-DABrpucj.js';
+export { c as BLACK, T as TRANSPARENT, d as WHITE, e as bounds, f as color16, m as maxFrameCount, g as modInt, p as parseColor } from './widget-DABrpucj.js';
+import { WidgetSpec, RootSpec } from '@koiosdigital/matrx-sdk';
+export { D as DEFAULT_SCREEN_DELAY_MILLIS, F as FrameEncoder, I as Image, W as WebpDecoder, e as encodeWebp, s as setWebpDecoder } from './webp-D106DLhy.js';
+
+/**
+ * BDF bitmap-font parser — a line-for-line port of zachomedia/go-bdf
+ * (the parser pixlet uses), including its quirks, because Text rendering
+ * parity depends on them:
+ *
+ *  - Metrics come from FONT_ASCENT / FONT_DESCENT properties.
+ *  - Glyph advance is DWIDTH's x component; BBX gives the bitmap size and
+ *    the lower-left offset (LowerPoint).
+ *  - Bitmap rows are hex, MSB-first across bytes; BPP defaults to 1 and each
+ *    pixel scales to 0..255 (binary for BPP=1).
+ *  - Character code → rune mapping: go-bdf consults a charmap for
+ *    ISO8859-1/2/9/15 registries, but BDF files quote the registry value
+ *    (`CHARSET_REGISTRY "ISO10646"`), and go-bdf's lookup key includes those
+ *    quotes — so the lookup never matches for any bundled font and the
+ *    mapping is codepoint identity. (For ISO8859-1, the charmap *is* the
+ *    identity anyway.) We implement identity, which is byte-identical for
+ *    all twelve bundled fonts.
+ *  - DEFAULT_CHAR: missing runes fall back to this glyph; if the property is
+ *    absent the fallback code is 0 (go-bdf initializes 32, then always
+ *    overwrites it after the property scan).
+ */
+interface Glyph {
+    name: string;
+    /** Character code (codepoint identity — see module docs). */
+    code: number;
+    /** DWIDTH x — horizontal advance in pixels. */
+    advanceX: number;
+    /** BBX width/height. */
+    w: number;
+    h: number;
+    /** BBX lower-left offset (lx, ly). */
+    lx: number;
+    ly: number;
+    /** Alpha bitmap, w*h bytes, row-major, 0..255 (binary for BPP=1). */
+    bitmap: Uint8Array;
+}
+interface BdfFont {
+    name: string;
+    ascent: number;
+    descent: number;
+    capHeight: number;
+    xHeight: number;
+    /** DEFAULT_CHAR code; 0 when the property is absent. */
+    defaultCode: number;
+    glyphs: Map<number, Glyph>;
+}
+/** go-bdf lookup(): exact glyph, else DEFAULT_CHAR's glyph, else null. */
+declare function lookupGlyph(font: BdfFont, code: number): Glyph | null;
+declare function parseBdf(text: string): BdfFont;
+
+/**
+ * Font registry + text measurement/rasterization.
+ * Mirrors pixlet render/fonts.go (GetFont, lazy parse + cache) and the
+ * font.Drawer semantics that gg's MeasureString/drawString build on.
+ */
+
+declare function getFontList(): string[];
+declare function getFont(name: string): BdfFont;
+/**
+ * Sum of glyph advances in pixels. Mirrors font.Drawer.MeasureString via
+ * gg.MeasureString: kerning is always 0 for BDF faces; code points missing
+ * from the font (after DEFAULT_CHAR fallback) are skipped without advance.
+ * BDF advances are integral, so the 26.6 fixed-point floor is exact.
+ */
+declare function measureString(font: BdfFont, s: string): number;
+declare function renderText(font: BdfFont, content: string, color: Color16, height: number, offset: number): Canvas;
+
+/**
+ * Minimal deterministic PNG encoder (8-bit RGBA, zlib stored blocks).
+ * Zero dependencies so it runs identically in Node, Workers, and tests.
+ * Output is not size-optimized — it exists for golden fixtures, previews,
+ * and the CLI, not for production delivery (production output is WebP).
+ */
+
+/**
+ * Encode a canvas as PNG. The canvas holds premultiplied RGBA; PNG wants
+ * straight alpha, so we un-premultiply exactly like Go's image/png does for
+ * image.RGBA input (NRGBAModel conversion: v = v16 * 0xffff / a16, >> 8).
+ */
+declare function encodePng(canvas: Canvas): Uint8Array;
+
+/**
+ * Hydration: `WidgetSpec` JSON (produced by app isolates via @koiosdigital/matrx-sdk
+ * builders) → paintable widget instances, plus the top-level render entry
+ * point. This is the host side of the D1 boundary: the isolate returns a
+ * serializable tree; layout/rasterization happen here.
+ */
+
+/** Hydrate a (non-root) widget spec and run all pending init()s. */
+declare function buildWidget(spec: WidgetSpec): Promise<Widget>;
+interface RenderResult {
+    frames: Canvas[];
+    /** Frame delay in milliseconds (Root.delay). */
+    delay: number;
+    /** Expiration time in seconds (Root.maxAge). */
+    maxAge: number;
+    showFullAnimation: boolean;
+}
+/**
+ * Render a root spec to frames. Canvas dimensions come from the render call
+ * (device-provided), not the app — handoff §10.
+ */
+declare function renderRoot(spec: RootSpec, opts?: {
+    width?: number;
+    height?: number;
+    maxFrameCount?: number;
+    solidBackground?: boolean;
+}): Promise<RenderResult>;
+
+/** Box — port of pixlet render/box.go. */
+
+declare class Box implements Widget {
+    child: Widget | null;
+    width: number;
+    height: number;
+    padding: number;
+    color: Color | null;
+    constructor(props?: {
+        child?: Widget | null;
+        width?: number;
+        height?: number;
+        padding?: number;
+        color?: Color | null;
+    });
+    paintBounds(b: Bounds, _frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+    frameCount(): number;
+}
+
+/**
+ * Vector — port of pixlet render/vector.go: the shared layout engine behind
+ * Row and Column. Ported line-for-line, including the child-measurement
+ * overflow breaks, residual-space distribution, and the space_between
+ * `offset = -1` residual trick. Integer divisions use Math.trunc to match
+ * Go's truncating division (cross offsets can go negative when a child is
+ * taller than the clamped vector).
+ */
+
+type MainAlign = "start" | "end" | "center" | "space_between" | "space_evenly" | "space_around" | "";
+type CrossAlign = "start" | "center" | "end" | "";
+declare class Vector implements Widget {
+    children: Widget[];
+    mainAlign: MainAlign;
+    crossAlign: CrossAlign;
+    expanded: boolean;
+    vertical: boolean;
+    constructor(props: {
+        children: Widget[];
+        mainAlign?: MainAlign;
+        crossAlign?: CrossAlign;
+        expanded?: boolean;
+        vertical?: boolean;
+    });
+    paintBounds(b: Bounds, frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+    frameCount(): number;
+}
+/** Row — port of pixlet render/row.go (a horizontal Vector). */
+declare class Row extends Vector {
+    constructor(props: {
+        children: Widget[];
+        mainAlign?: MainAlign;
+        crossAlign?: CrossAlign;
+        expanded?: boolean;
+    });
+}
+/** Column — port of pixlet render/column.go (a vertical Vector). */
+declare class Column extends Vector {
+    constructor(props: {
+        children: Widget[];
+        mainAlign?: MainAlign;
+        crossAlign?: CrossAlign;
+        expanded?: boolean;
+    });
+}
+
+/** Stack — port of pixlet render/stack.go. Children painted in order, later on top. */
+
+declare class Stack implements Widget {
+    children: Widget[];
+    constructor(props: {
+        children: Widget[];
+    });
+    paintBounds(b: Bounds, frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+    frameCount(): number;
+}
+
+/** Padding — port of pixlet render/padding.go, including the negative-pad
+ * positioning hack and the clip/translate ordering. */
+
+interface Insets {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+declare class Padding implements Widget {
+    child: Widget;
+    pad: Insets;
+    expanded: boolean;
+    color: Color | null;
+    constructor(props: {
+        child: Widget;
+        pad?: Insets;
+        expanded?: boolean;
+        color?: Color | null;
+    });
+    paintBounds(b: Bounds, frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+    frameCount(): number;
+}
+
+/** Text — port of pixlet render/text.go: single line, prerendered at init. */
+
+declare const DEFAULT_FONT_FACE = "tb-8";
+declare class Text implements Widget {
+    content: string;
+    font: string;
+    height: number;
+    offset: number;
+    color: Color | null;
+    private img;
+    constructor(props: {
+        content: string;
+        font?: string;
+        height?: number;
+        offset?: number;
+        color?: Color | null;
+    });
+    init(): void;
+    private image;
+    size(): [number, number];
+    paintBounds(_b: Bounds, _frameIdx: number): Bounds;
+    paint(dc: DrawContext, _b: Bounds, _frameIdx: number): void;
+    frameCount(): number;
+}
+
+/**
+ * Root — port of pixlet render/root.go.
+ *
+ * Divergence from the fork (documented): the Go fork falls back to mutable
+ * package globals for dimensions (pre-thread-safety compat). Here dimensions
+ * are instance-only, defaulting to 64×32 — the behavior fork commit 665d55b
+ * was moving toward.
+ */
+
+declare const DEFAULT_FRAME_WIDTH = 64;
+declare const DEFAULT_FRAME_HEIGHT = 32;
+declare const DEFAULT_MAX_FRAME_COUNT = 2000;
+declare class Root {
+    child: Widget;
+    /** Frame delay in milliseconds. */
+    delay: number;
+    /** Expiration time in seconds. */
+    maxAge: number;
+    showFullAnimation: boolean;
+    /** Canvas dimensions; 0 → defaults. */
+    width: number;
+    height: number;
+    constructor(props: {
+        child: Widget;
+        delay?: number;
+        maxAge?: number;
+        showFullAnimation?: boolean;
+        width?: number;
+        height?: number;
+    });
+    /** Render all frames. Mirrors Root.Paint (sequentially — no goroutines). */
+    paint(opts?: {
+        solidBackground?: boolean;
+        maxFrameCount?: number;
+    }): Canvas[];
+}
+
+/** Animation — port of pixlet render/animation.go: each child is one frame. */
+
+declare class Animation implements Widget {
+    children: Widget[];
+    constructor(props: {
+        children: Widget[];
+    });
+    frameCount(): number;
+    paintBounds(b: Bounds, frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+}
+
+/**
+ * Sequence — port of pixlet render/sequence.go (Koios fork, including the
+ * `duration` loop extension): children rendered one after another, each for
+ * its own frame count.
+ */
+
+declare class Sequence implements Widget {
+    children: Widget[];
+    /** Total duration in frames (0 = play once, >0 = loop children to fill). */
+    duration: number;
+    constructor(props: {
+        children: Widget[];
+        duration?: number;
+    });
+    /** Natural frame count of one complete pass through all children. */
+    baseCycleFrameCount(): number;
+    frameCount(): number;
+    private resolveFrameIdx;
+    paintBounds(b: Bounds, frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+}
+
+/**
+ * Marquee — port of pixlet render/marquee.go (Koios fork: delay, endDelay,
+ * loop). Frame-count formulas are reproduced exactly (handoff §5).
+ *
+ * Ported quirk: frameCount() measures the child against the *default*
+ * 64×32 frame dimensions (the fork does this for thread safety), while
+ * paint() measures against the actual bounds. Keep it that way for parity.
+ */
+
+declare class Marquee implements Widget {
+    child: Widget;
+    width: number;
+    height: number;
+    offsetStart: number;
+    offsetEnd: number;
+    scrollDirection: string;
+    align: string;
+    delay: number;
+    endDelay: number;
+    loop: boolean;
+    constructor(props: {
+        child: Widget;
+        width?: number;
+        height?: number;
+        offsetStart?: number;
+        offsetEnd?: number;
+        scrollDirection?: string;
+        align?: string;
+        delay?: number;
+        endDelay?: number;
+        loop?: boolean;
+    });
+    private isVertical;
+    paintBounds(b: Bounds, _frameIdx: number): Bounds;
+    frameCount(): number;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+    private paintLoop;
+}
+
+/**
+ * Easing curves — port of pixlet render/animation/curve.go.
+ */
+type Curve = (t: number) => number;
+declare const linearCurve: Curve;
+/**
+ * Cubic bezier easing, solved by bisection exactly like the Go code
+ * (epsilon 0.0001 on the x axis). The Go loop is unbounded; we cap the
+ * iteration count as a safety net — at 64 halvings the interval is far below
+ * any float64 epsilon, so a convergent input (monotone x, i.e. a,c ∈ [0,1])
+ * terminates identically to Go long before the cap.
+ */
+declare function cubicBezierCurve(a: number, b: number, c: number, d: number): Curve;
+declare const easeIn: Curve;
+declare const easeOut: Curve;
+declare const easeInOut: Curve;
+/** Port of animation.ParseCurve. */
+declare function parseCurve(str: string): Curve;
+
+/**
+ * Transforms and their interpolation — port of pixlet
+ * render/animation/{transform,translate,scale,rotate,rounding,util,vector}.go.
+ */
+
+declare function rescale(fromMin: number, fromMax: number, toMin: number, toMax: number, v: number): number;
+declare function lerp(from: number, to: number, t: number): number;
+type RoundingMode = "round" | "floor" | "ceil" | "none";
+declare function applyRounding(mode: RoundingMode, v: number): number;
+type Transform = {
+    kind: "translate";
+    x: number;
+    y: number;
+} | {
+    kind: "scale";
+    x: number;
+    y: number;
+} | {
+    kind: "rotate";
+    angle: number;
+};
+/**
+ * Pairwise interpolation of transform lists; lists of unequal length are
+ * extended with per-kind defaults. Mismatched kinds at the same position
+ * would require matrix-level interpolation, which pixlet does not support —
+ * returns ok=false, and no transforms are applied.
+ */
+declare function interpolateTransforms(lhs: Transform[], rhs: Transform[], progress: number): {
+    transforms: Transform[];
+    ok: boolean;
+};
+
+/**
+ * Keyframes, origin, direction, fill mode — port of pixlet
+ * render/animation/{keyframe,origin,direction,fill_mode,transformation}.go
+ * (the keyframe-processing half of transformation.go lives here).
+ */
+
+interface Keyframe {
+    /** Point in time, 0.0 .. 1.0. */
+    percentage: number;
+    transforms: Transform[];
+    curve: Curve;
+}
+/**
+ * Sort keyframes (stable) and add 0%/100% keyframes if missing.
+ * See https://www.w3.org/TR/css-animations-1/#keyframes
+ */
+declare function processKeyframes(arr: Keyframe[]): Keyframe[];
+/**
+ * Find the adjacent keyframes for a progress value. Returns null when the
+ * value is out of range (including NaN progress from a zero-length
+ * animation, which flows through comparisons exactly like in Go) — the
+ * caller then applies no transforms.
+ */
+declare function findKeyframes(arr: Keyframe[], p: number): [Keyframe, Keyframe] | null;
+interface Origin {
+    x: number;
+    y: number;
+}
+declare const DEFAULT_ORIGIN: Origin;
+type DirectionMode = "normal" | "reverse" | "alternate" | "alternate_reverse";
+type FillMode = "forwards" | "backwards";
+
+/**
+ * Transformation — port of pixlet render/animation/transformation.go:
+ * CSS-like keyframe animation of translate/scale/rotate on a child widget.
+ */
+
+declare class Transformation implements Widget {
+    child: Widget;
+    keyframes: Keyframe[];
+    duration: number;
+    delay: number;
+    width: number;
+    height: number;
+    origin: Origin;
+    direction: DirectionMode;
+    fillMode: FillMode;
+    rounding: RoundingMode;
+    waitForChild: boolean;
+    constructor(props: {
+        child: Widget;
+        keyframes: Keyframe[];
+        duration: number;
+        delay?: number;
+        width?: number;
+        height?: number;
+        origin?: Origin;
+        direction?: DirectionMode;
+        fillMode?: FillMode;
+        rounding?: RoundingMode;
+        waitForChild?: boolean;
+    });
+    init(): void;
+    frameCount(): number;
+    paintBounds(b: Bounds, _frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+}
+
+/**
+ * WrappedText — port of pixlet render/wrappedtext.go + gg's wordWrap and
+ * DrawStringWrapped line placement. Lines are rasterized with the shared
+ * text pipeline and blitted at the exact positions gg's anchored draw
+ * produces (fixed-point dot quantization → floor at .5 offsets).
+ */
+
+/** Port of gg wordWrap. */
+declare function wordWrap(font: BdfFont, s: string, width: number): string[];
+declare class WrappedText implements Widget {
+    content: string;
+    font: string;
+    height: number;
+    width: number;
+    lineSpacing: number;
+    color: Color | null;
+    align: string;
+    private face;
+    constructor(props: {
+        content: string;
+        font?: string;
+        height?: number;
+        width?: number;
+        lineSpacing?: number;
+        color?: Color | null;
+        align?: string;
+    });
+    init(): void;
+    private fontFace;
+    paintBounds(b: Bounds, _frameIdx: number): Bounds;
+    paint(dc: DrawContext, b: Bounds, frameIdx: number): void;
+    frameCount(): number;
+}
+
+/** Circle — port of pixlet render/circle.go. */
+
+declare class Circle implements Widget {
+    child: Widget | null;
+    color: Color;
+    diameter: number;
+    constructor(props: {
+        child?: Widget | null;
+        color: Color;
+        diameter: number;
+    });
+    paintBounds(_b: Bounds, _frameIdx: number): Bounds;
+    paint(dc: DrawContext, _b: Bounds, frameIdx: number): void;
+    frameCount(): number;
+}
+
+/** PieChart — port of pixlet render/pie_chart.go. */
+
+declare class PieChart implements Widget {
+    colors: Color[];
+    weights: number[];
+    diameter: number;
+    constructor(props: {
+        colors: Color[];
+        weights: number[];
+        diameter: number;
+    });
+    paintBounds(_b: Bounds, _frameIdx: number): Bounds;
+    paint(dc: DrawContext, _b: Bounds, _frameIdx: number): void;
+    frameCount(): number;
+}
+
+/** PolyLine — port of pixlet render/paths.go (Bresenham line enumeration). */
+interface PathPoint {
+    x: number;
+    y: number;
+}
+declare class PolyLine {
+    vertices: PathPoint[];
+    private path;
+    constructor(vertices: PathPoint[]);
+    length(): number;
+    point(i: number): [number, number];
+    private compute;
+    private addLineSegment;
+}
+
+/**
+ * Plot — port of pixlet render/plot.go: XY line/scatter chart drawn with
+ * raw pixel stores along a Bresenham polyline. NaN in xLim/yLim means
+ * "infer from data", exactly like the Go NaN sentinels.
+ *
+ * Ported quirk: the scatter branch pokes untransformed coordinates (the Go
+ * code skips TransformPoint there) — keep it for parity.
+ */
+
+declare const DEFAULT_PLOT_COLOR: Color;
+/** Surface fill gets line color dampened by this factor. */
+declare const FILL_DAMP_FACTOR = 85;
+declare class Plot implements Widget {
+    data: [number, number][];
+    width: number;
+    height: number;
+    color: Color | null;
+    colorInverted: Color | null;
+    xLim: [number, number];
+    yLim: [number, number];
+    fill: boolean;
+    chartType: string;
+    fillColor: Color | null;
+    fillColorInverted: Color | null;
+    private invThreshold;
+    constructor(props: {
+        data: [number, number][];
+        width: number;
+        height: number;
+        color?: Color | null;
+        colorInverted?: Color | null;
+        xLim?: [number, number];
+        yLim?: [number, number];
+        fill?: boolean;
+        chartType?: string;
+        fillColor?: Color | null;
+        fillColorInverted?: Color | null;
+    });
+    /** Port of plot.go computeLimits. */
+    computeLimits(): [number, number, number, number];
+    /** Port of plot.go translatePoints (also computes invThreshold). */
+    translatePoints(): PathPoint[];
+    paintBounds(_b: Bounds, _frameIdx: number): Bounds;
+    paint(dc: DrawContext, _b: Bounds, _frameIdx: number): void;
+    frameCount(): number;
+}
+
+/**
+ * PNG decoder (pure TS + fflate inflate). Supports the formats that matter
+ * for pixel-art app assets: bit depths 1/2/4/8, color types gray, RGB,
+ * palette (incl. tRNS), gray+alpha, RGBA; filters 0–4. 16-bit channels and
+ * Adam7 interlacing are rejected with a clear error.
+ *
+ * Output is straight (non-premultiplied) RGBA, like Go's image.Decode
+ * producing NRGBA — premultiplication happens when frames are converted to
+ * Canvas.
+ */
+interface DecodedImage {
+    width: number;
+    height: number;
+    /** Straight RGBA. */
+    rgba: Uint8Array;
+}
+declare function isPng(data: Uint8Array): boolean;
+declare function decodePng(data: Uint8Array): DecodedImage;
+
+/**
+ * GIF decoder (pure TS): header/LSD/GCT parsing, LZW, per-frame rects,
+ * local palettes, transparency, interlacing, disposal + delays. Produces
+ * raw frame data; frame *composition* (Go's Image.InitFromGIF quirks
+ * included) lives in the Image widget.
+ */
+declare const enum GifDisposal {
+    None = 0,// includes "unspecified"
+    DoNotDispose = 1,
+    Background = 2,
+    Previous = 3
+}
+interface GifFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Palette indices, width*height. */
+    indices: Uint8Array;
+    /** RGB triples. */
+    palette: Uint8Array;
+    transparentIndex: number | null;
+    disposal: GifDisposal;
+    /** Delay in 1/100s (GIF native units, like Go's gif.GIF.Delay). */
+    delayCS: number;
+}
+interface DecodedGif {
+    width: number;
+    height: number;
+    frames: GifFrame[];
+}
+declare function isGif(data: Uint8Array): boolean;
+declare function decodeGif(data: Uint8Array): DecodedGif;
+
+export { Animation, type BdfFont, Bounds, Box, Canvas, Circle, Color, Color16, Column, type CrossAlign, type Curve, DEFAULT_FONT_FACE, DEFAULT_FRAME_HEIGHT, DEFAULT_FRAME_WIDTH, DEFAULT_MAX_FRAME_COUNT, DEFAULT_ORIGIN, DEFAULT_PLOT_COLOR, type DirectionMode, DrawContext, FILL_DAMP_FACTOR, type FillMode, type Glyph, type Insets, type Keyframe, type MainAlign, Marquee, type Origin, Padding, type PathPoint, PieChart, Plot, PolyLine, type RenderResult, Root, type RoundingMode, Row, Sequence, Stack, Text, type Transform, Transformation, Vector, Widget, WrappedText, applyRounding, buildWidget, cubicBezierCurve, decodeGif, decodePng, easeIn, easeInOut, easeOut, encodePng, findKeyframes, getFont, getFontList, interpolateTransforms, isGif, isPng, lerp, linearCurve, lookupGlyph, measureString, parseBdf, parseCurve, processKeyframes, renderRoot, renderText, rescale, wordWrap };