freshcoat 0.1.0

package/src/compile-scene.d.ts

@@ -0,0 +1,24 @@
+import type { Node } from "./node.js";
+import type { TextEngine } from "./text-engine.js";
+import type { MeasureText } from "./text-types.js";
+import type { Command, FontRequest, FontVMetrics, FrameFinish } from "./types.js";
+export type CompileSceneOptions = {
+    width: number;
+    height: number;
+    textEngine?: TextEngine;
+    measure?: MeasureText;
+    leadingTrim?: boolean;
+    fontMetrics?: Record<string, FontVMetrics>;
+    fonts?: FontRequest[];
+    images?: string[];
+    finish?: FrameFinish;
+    prepared?: boolean;
+    scale?: number;
+    supersample?: number;
+};
+export declare function prepareScene(root: Node, opts: Pick<CompileSceneOptions, "textEngine" | "measure" | "fontMetrics">): Node;
+export declare function compileScene(root: Node, opts: CompileSceneOptions): Command[];
+export declare function sceneAssets(node: Node): {
+    fonts: FontRequest[];
+    images: string[];
+};

package/src/compile-scene.js

@@ -0,0 +1,325 @@
+// compileScene — the PURE compile: a Node tree → the flat Command IR the painter
+// walks. No runtime, no painter, no pixels — painting is the separate
+// env.paint(commands, ck) step.
+//
+// Geometric lowering (rect / ellipse→path / path / image / bitmap / group) plus
+// text: a text node's glyphs are baked here via the injected TextEngine
+// (bakeText), or taken verbatim from a pre-baked `layout`.
+// When a `measure`/`textEngine` is supplied, `layout` (auto-layout) groups are
+// resolved to absolute geometry first; otherwise nodes must carry absolute
+// pos/size. freshcoat owns text *shaping* (the TextEngine) but knows nothing
+// about templates — the caller delivers final resolved values on the nodes.
+import { bakeText, resolveLeadingTrim, textClipOutset } from "./bake-text.js";
+import { metricsLookup, resolveAutoLineHeights } from "./line-height.js";
+import { resolveLayout } from "./resolve-layout.js";
+// Everything that has to happen to a tree before it can be lowered: AUTO line
+// heights become the font's own line box, then `layout` groups resolve to
+// absolute geometry. compileScene runs this itself; a caller that needs the
+// absolute tree first (to measure a layer as rendered, or to rewrite it) runs it
+// here and compiles with `prepared: true`.
+//
+// AUTO line heights resolve BEFORE layout: they change how tall a wrapped
+// paragraph is, so resolving them after measuring would size every hug box to
+// the wrong height.
+export function prepareScene(root, opts) {
+    const measure = opts.measure ?? opts.textEngine?.measureText;
+    const authored = resolveAutoLineHeights(root, metricsLookup(opts.fontMetrics, opts.textEngine?.metricsFor));
+    return measure ? resolveLayout(authored, { measure }) : authored;
+}
+export function compileScene(root, opts) {
+    const scene = opts.prepared ? root : prepareScene(root, opts);
+    // A 1× export leaves `scale` off the command entirely — the density is an
+    // opt-in, and an absent field keeps the stream identical to what it was before
+    // export scaling existed.
+    const scale = opts.scale ?? 1;
+    const supersample = opts.supersample ?? 1;
+    const commands = [
+        {
+            op: "createCanvas",
+            width: opts.width,
+            height: opts.height,
+            ...(scale !== 1 ? { scale } : {}),
+            ...(supersample !== 1 ? { supersample } : {}),
+        },
+    ];
+    // `fonts` and `images` override INDEPENDENTLY: whichever is omitted is still
+    // derived from the walk. Treating them as one all-or-nothing switch silently
+    // blanked the other list, so a caller declaring only extra font families lost
+    // every image src and the painter drew placeholders instead.
+    const images = new Set();
+    const fonts = new Set();
+    collectAssets(scene, images, fonts);
+    const fontRequests = opts.fonts ?? [...fonts].map((family) => ({ family }));
+    const imageSrcs = opts.images ?? [...images];
+    if (fontRequests.length > 0) {
+        commands.push({ op: "loadFonts", requests: fontRequests });
+    }
+    if (imageSrcs.length > 0) {
+        commands.push({ op: "loadImages", srcs: imageSrcs });
+    }
+    const ctx = {
+        textEngine: opts.textEngine,
+        leadingTrim: opts.leadingTrim,
+        fontMetrics: opts.fontMetrics,
+        // Text is baked in design units, but its line advances snap to whole
+        // pixels — of the surface it will be painted on, not of the design box.
+        deviceScale: scale,
+    };
+    commands.push(lower(scene, ctx));
+    // The finish runs on the composited frame, so it goes last.
+    if (opts.finish && hasFinishOp(opts.finish)) {
+        commands.push({ op: "finishFrame", finish: opts.finish });
+    }
+    return commands;
+}
+// True when a finish actually asks for something — an all-undefined finish is a
+// no-op and shouldn't emit a command (or spin up the post-pass).
+function hasFinishOp(f) {
+    return (f.whiteClamp !== undefined ||
+        f.blackExtract !== undefined ||
+        (typeof f.dither === "number" ? f.dither > 0 : (f.dither?.amount ?? 0) > 0));
+}
+// The fonts and images a scene references — the same walk compileScene runs for
+// its own setup commands, exposed for callers that must declare a frame's assets
+// up front (coatfile's CompiledFrame, the worker's raw render source). Those
+// callers hand the result back as `fonts`/`images`, which are OVERRIDES: an empty
+// list means "load nothing", not "nothing found", so a second walk that drifted
+// would silently render text in no font at all.
+export function sceneAssets(node) {
+    const images = new Set();
+    const fonts = new Set();
+    collectAssets(node, images, fonts);
+    return {
+        fonts: [...fonts].map((family) => ({ family })),
+        images: [...images],
+    };
+}
+function collectAssets(node, images, fonts) {
+    switch (node.kind) {
+        case "image":
+            images.add(node.src);
+            break;
+        case "text":
+            fonts.add(node.font.family);
+            break;
+        case "group":
+            for (const child of node.children)
+                collectAssets(child, images, fonts);
+            break;
+        case "mask":
+            collectAssets(node.mask, images, fonts);
+            for (const child of node.children)
+                collectAssets(child, images, fonts);
+            break;
+    }
+}
+function lower(node, ctx) {
+    const base = {
+        id: node.id,
+        pos: node.pos ?? { x: 0, y: 0 },
+        size: node.size ?? { width: 0, height: 0 },
+        rotation: node.rotation,
+        opacity: node.opacity,
+        blendMode: node.blendMode,
+        shadow: node.shadow,
+        blur: node.blur,
+        adjust: node.adjust,
+    };
+    switch (node.kind) {
+        case "rect":
+            return {
+                ...base,
+                op: "drawRect",
+                fills: node.fills,
+                stroke: node.stroke,
+                cornerRadius: node.cornerRadius,
+                cornerSmoothing: node.cornerSmoothing,
+            };
+        case "ellipse":
+            return {
+                ...base,
+                op: "drawPath",
+                d: ellipseSvg(base.size),
+                fills: node.fills,
+                stroke: node.stroke,
+            };
+        case "path":
+            return {
+                ...base,
+                op: "drawPath",
+                d: node.d,
+                fills: node.fills,
+                stroke: node.stroke,
+                ...(node.viewBox ? { viewBox: node.viewBox } : {}),
+                ...(node.fillRule ? { fillRule: node.fillRule } : {}),
+            };
+        case "image":
+            return {
+                ...base,
+                op: "drawImage",
+                src: node.src,
+                fit: node.fit,
+                stroke: node.stroke,
+                clip: node.mask,
+            };
+        case "group":
+            return {
+                ...base,
+                op: "drawGroup",
+                clip: groupClip(node),
+                children: [
+                    ...groupBackground(node, base),
+                    ...node.children.map((c) => lower(c, ctx)),
+                ],
+            };
+        case "mask":
+            return lowerMask(node, base, ctx);
+        case "text":
+            return lowerText(node, base, ctx);
+        case "bitmap":
+            return {
+                ...base,
+                op: "drawBitmap",
+                pixels: node.pixels,
+                pixelWidth: node.pixelWidth,
+                pixelHeight: node.pixelHeight,
+                ...(node.role ? { role: node.role } : {}),
+            };
+    }
+}
+function lowerText(node, base, ctx) {
+    // Pre-baked layout wins (the caller already shaped it); otherwise bake now
+    // via the injected engine. Only when neither is present is it an error.
+    const layout = node.layout ??
+        (ctx.textEngine
+            ? bakeText(node, {
+                textEngine: ctx.textEngine,
+                leadingTrim: ctx.leadingTrim,
+                fontMetrics: ctx.fontMetrics,
+                deviceScale: ctx.deviceScale,
+            })
+            : undefined);
+    if (!layout) {
+        throw new Error("compileScene: text node has no pre-baked `layout` and no `textEngine` was supplied to bake it");
+    }
+    // fit:"clip" clips overflow to the box, but glyphs legitimately overshoot it
+    // (descenders/ascenders); outset the clip so visible glyphs stay whole.
+    const clip = node.fit === "clip"
+        ? {
+            kind: "rect",
+            outset: textClipOutset(node.font, resolveLeadingTrim(node, ctx.leadingTrim), ctx.fontMetrics),
+        }
+        : undefined;
+    return {
+        ...base,
+        op: "drawText",
+        clip,
+        layout,
+        color: node.color ?? "#000000",
+        fill: node.fill,
+    };
+}
+// A mask node lowers by what its mask IS: a single opaque shape → a drawGroup
+// whose clip is the shape (one cheap clipPath, at the mask shape's box); any
+// other mask → a drawMasked command the painter composites via an offscreen
+// coverage layer.
+//
+// `invert` and `channel` disqualify the fast path whatever the shape is. A
+// clipPath keeps what the geometry covers, which is the alpha channel,
+// uninverted: there is no inverse clip, and an OPAQUE shape's luminance coverage
+// is its colour rather than its geometry (a black rect masks everything out
+// under `luminance` and nothing out under a clip).
+function lowerMask(node, base, ctx) {
+    const children = node.children.map((c) => lower(c, ctx));
+    const shape = node.invert || node.channel === "luminance" ? null : fastClip(node.mask);
+    if (shape) {
+        // The clip is built at the mask SHAPE's box; the mask node's own transform
+        // (opacity/blend/blur/shadow/rotation) still wraps the masked content.
+        return {
+            ...base,
+            pos: node.mask.pos ?? { x: 0, y: 0 },
+            size: node.mask.size ?? { width: 0, height: 0 },
+            op: "drawGroup",
+            clip: shape,
+            children,
+        };
+    }
+    return {
+        ...base,
+        op: "drawMasked",
+        mask: lower(node.mask, ctx),
+        children,
+        channel: node.channel,
+        invert: node.invert,
+    };
+}
+// The conservative fast-path predicate: a mask that is a single opaque vector
+// shape (rect/ellipse, no transform effects, no gradient/partial-alpha fill,
+// uniform corner radius) maps to a ShapeMask clipPath. Everything else (paths,
+// per-corner radii, images, text, groups, any opacity/blur/blend/rotation on
+// the mask) returns null → the offscreen path. It reads the MASK only; the mask
+// node's own `invert`/`channel` are the caller's to check.
+function fastClip(mask) {
+    if (mask.rotation ||
+        (mask.opacity !== undefined && mask.opacity < 1) ||
+        mask.blur ||
+        (mask.blendMode && mask.blendMode !== "normal") ||
+        mask.shadow)
+        return null;
+    if (mask.kind === "ellipse")
+        return solidOrNone(mask.fills) ? { kind: "ellipse" } : null;
+    if (mask.kind === "rect") {
+        if (!solidOrNone(mask.fills))
+            return null;
+        const cr = mask.cornerRadius;
+        if (Array.isArray(cr))
+            return null; // per-corner → offscreen
+        if (mask.cornerSmoothing && typeof cr === "number" && cr > 0)
+            return { kind: "squircle", radius: cr };
+        if (typeof cr === "number" && cr > 0)
+            return { kind: "rounded-rect", radius: cr };
+        return { kind: "rect" };
+    }
+    return null;
+}
+function solidOrNone(fills) {
+    return !fills || (fills.length === 1 && fills[0].kind === "solid");
+}
+// A group's self-clip: clip children to its box, honoring its corner radius.
+// Per-corner radii and corner smoothing on the clip are a later refinement.
+// A filled group's background, as an ordinary rect drawn first.
+//
+// Lowering it rather than teaching the painter about group fills keeps one
+// implementation of fills, gradients, corner radii and smoothing — the rect's,
+// which the parity suites already cover. The group's own composite effects
+// (shadow, opacity, blur, adjust) stay on the group, so the fill is inside the
+// layer they apply to and the shadow is cast by the filled box.
+function groupBackground(node, base) {
+    if (!node.fills?.length)
+        return [];
+    return [
+        {
+            op: "drawRect",
+            pos: base.pos,
+            size: base.size,
+            fills: node.fills,
+            cornerRadius: node.cornerRadius,
+            cornerSmoothing: node.cornerSmoothing,
+        },
+    ];
+}
+function groupClip(node) {
+    if (!node.clip)
+        return undefined;
+    const r = typeof node.cornerRadius === "number" ? node.cornerRadius : 0;
+    return r > 0 ? { kind: "rounded-rect", radius: r } : { kind: "rect" };
+}
+// Box-relative ellipse as an SVG path (two half-arcs), positioned at the node's
+// pos by the painter. CanvasKit's Path.MakeFromSVGString handles arcs — the same
+// path shape the painter already uses for circle/ellipse clips.
+function ellipseSvg(size) {
+    const rx = size.width / 2;
+    const ry = size.height / 2;
+    const cy = ry;
+    return `M 0 ${cy} A ${rx} ${ry} 0 1 0 ${size.width} ${cy} A ${rx} ${ry} 0 1 0 0 ${cy} Z`;
+}

package/src/css.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedFill } from "./types.js";
+export type ColorResolver = (raw: string) => string;
+export declare function oklchToHex(l: number, c: number, h: number): string;
+export declare function parseCssColor(raw: string, fallback?: string): string;
+export declare function parseLinearGradient(value: string, resolveColor?: ColorResolver): ResolvedFill | null;

package/src/css.js

@@ -0,0 +1,153 @@
+const CSS_NAMED = {
+    transparent: "#00000000",
+    white: "#ffffff",
+    black: "#000000",
+};
+const clamp01 = (x) => Math.min(1, Math.max(0, x));
+function toHexByte(x) {
+    return Math.round(clamp01(x) * 255)
+        .toString(16)
+        .padStart(2, "0");
+}
+// oklch(L C H) → sRGB hex. L is 0..1 (or a %), C is chroma, H is degrees.
+// OKLCh → OKLab → linear sRGB → gamma-encoded sRGB.
+export function oklchToHex(l, c, h) {
+    const hr = (h * Math.PI) / 180;
+    const a = c * Math.cos(hr);
+    const b = c * Math.sin(hr);
+    const l_ = l + 0.3963377774 * a + 0.2158037573 * b;
+    const m_ = l - 0.1055613458 * a - 0.0638541728 * b;
+    const s_ = l - 0.0894841775 * a - 1.291485548 * b;
+    const lc = l_ * l_ * l_;
+    const mc = m_ * m_ * m_;
+    const sc = s_ * s_ * s_;
+    const lr = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
+    const lg = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
+    const lb = -0.0041960863 * lc - 0.7034186147 * mc + 1.707614701 * sc;
+    const enc = (x) => x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055;
+    return `#${toHexByte(enc(lr))}${toHexByte(enc(lg))}${toHexByte(enc(lb))}`;
+}
+function parseOklch(value) {
+    const inner = value.slice(value.indexOf("(") + 1, value.lastIndexOf(")"));
+    const parts = inner
+        .replace(/\//g, " ") // drop any `/ alpha`
+        .split(/[\s,]+/)
+        .filter(Boolean);
+    if (parts.length < 3)
+        return null;
+    const l = parts[0].endsWith("%")
+        ? parseFloat(parts[0]) / 100
+        : parseFloat(parts[0]);
+    const c = parseFloat(parts[1]);
+    const h = parseFloat(parts[2]);
+    if ([l, c, h].some(Number.isNaN))
+        return null;
+    return oklchToHex(l, c, h);
+}
+function expandHex(value) {
+    const hex = value.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+        return `#${[...hex].map((ch) => ch + ch).join("")}`;
+    }
+    return value;
+}
+function parseRgb(value) {
+    const inner = value.slice(value.indexOf("(") + 1, value.lastIndexOf(")"));
+    const parts = inner.split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 3)
+        return null;
+    const toByte = (p) => p.endsWith("%") ? (parseFloat(p) / 100) * 255 : parseFloat(p);
+    const [r, g, b] = parts.map(toByte);
+    if ([r, g, b].some(Number.isNaN))
+        return null;
+    return `#${toHexByte(r / 255)}${toHexByte(g / 255)}${toHexByte(b / 255)}`;
+}
+// A CSS color string (hex / rgb()/rgba() / oklch() / a named color) → `#rrggbb`.
+// Unknown/unparseable values (including `var(...)` — resolve those before calling,
+// or use parseLinearGradient's resolver hook) yield `fallback`.
+export function parseCssColor(raw, fallback = "#000000") {
+    const value = raw.trim();
+    if (!value)
+        return fallback;
+    if (value.startsWith("#"))
+        return expandHex(value).toLowerCase();
+    if (value.startsWith("oklch"))
+        return parseOklch(value) ?? fallback;
+    if (value.startsWith("rgb"))
+        return parseRgb(value) ?? fallback;
+    return CSS_NAMED[value.toLowerCase()] ?? fallback;
+}
+// Split on top-level commas only (colors like rgb(…) carry their own commas).
+function splitTopLevel(input) {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth--;
+        else if (ch === "," && depth === 0) {
+            out.push(input.slice(start, i));
+            start = i + 1;
+        }
+    }
+    out.push(input.slice(start));
+    return out.map((s) => s.trim()).filter(Boolean);
+}
+const ANGLE_KEYWORDS = {
+    "to top": 0,
+    "to right": 90,
+    "to bottom": 180,
+    "to left": 270,
+};
+// CSS gradient angle → normalized endpoints in the [0,1] bbox. 0deg = to top,
+// 90deg = to right, 180deg = to bottom.
+function angleToEndpoints(angle) {
+    const rad = (angle * Math.PI) / 180;
+    const dx = Math.sin(rad) / 2;
+    const dy = -Math.cos(rad) / 2;
+    return {
+        from: { x: 0.5 - dx, y: 0.5 - dy },
+        to: { x: 0.5 + dx, y: 0.5 + dy },
+    };
+}
+// Parse a CSS `linear-gradient(...)` into a freshcoat linear fill. Angles (`Ndeg`
+// or `to <side>`, default 180) and per-stop positions (`<color> <pos>%`, else
+// evenly spaced) are honored; stop colors resolve through `resolveColor` (default
+// parseCssColor), so callers can inject `var(--token)` resolution. Returns null
+// for anything that isn't a linear-gradient (radial/conic → caller's fallback).
+export function parseLinearGradient(value, resolveColor = (c) => parseCssColor(c)) {
+    const trimmed = value.trim();
+    const open = trimmed.indexOf("(");
+    if (!trimmed.startsWith("linear-gradient") || open < 0)
+        return null;
+    const inner = trimmed.slice(open + 1, trimmed.lastIndexOf(")"));
+    const parts = splitTopLevel(inner);
+    if (parts.length < 2)
+        return null;
+    let angle = 180;
+    let stopParts = parts;
+    const first = parts[0].toLowerCase();
+    if (/deg\s*$/.test(first)) {
+        angle = parseFloat(first);
+        stopParts = parts.slice(1);
+    }
+    else if (first in ANGLE_KEYWORDS) {
+        angle = ANGLE_KEYWORDS[first];
+        stopParts = parts.slice(1);
+    }
+    if (stopParts.length < 2)
+        return null;
+    const stops = stopParts.map((part, i) => {
+        const m = part.match(/^(.*?)(?:\s+(-?[\d.]+)%)?$/);
+        const colorRaw = (m?.[1] ?? part).trim();
+        const posRaw = m?.[2];
+        const offset = posRaw !== undefined
+            ? parseFloat(posRaw) / 100
+            : i / (stopParts.length - 1);
+        return { offset, color: resolveColor(colorRaw) };
+    });
+    return { kind: "linear", stops, ...angleToEndpoints(angle) };
+}

package/src/decode.d.ts

@@ -0,0 +1,22 @@
+import type { ImageNode } from "./node.js";
+export type DecodedPixels = {
+    data: Uint8Array;
+    width: number;
+    height: number;
+};
+export type DecodeOptions = {
+    maxDim?: number;
+};
+export type ImageSampleOptions = {
+    maxDim?: number;
+};
+export type ImageBytesLoader = (src: string) => Promise<Uint8Array>;
+export type PixelRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export declare function drawImageToPixels(ck: unknown, img: any, outW: number, outH: number, src: PixelRect, dest: PixelRect): DecodedPixels | null;
+export declare function sampleImageNode(ck: unknown, node: ImageNode, loadImageBytes: ImageBytesLoader, opts?: ImageSampleOptions): Promise<DecodedPixels | null>;
+export declare function decodePixels(ck: unknown, bytes: Uint8Array, opts?: DecodeOptions): DecodedPixels | null;

package/src/decode.js

@@ -0,0 +1,112 @@
+// decodePixels — decode encoded image bytes to a raw RGBA buffer via CanvasKit.
+// freshcoat owns image decoding (it already does it to paint), so this is the
+// primitive a consumer that only needs PIXELS (e.g. image analysis) calls, instead
+// of standing up its own rasterizer. Takes the caller's CanvasKit instance; imports
+// no WASM itself, so it stays in the light barrel.
+import { fitRect } from "./paint-helpers.js";
+// Read RGBA out of an Image or Canvas. Returns null when CanvasKit can't read back
+// (an unsupported ImageInfo, a lost context) — readPixels can return null, so the
+// caller must not assume a buffer.
+function readRGBA(
+// biome-ignore lint/suspicious/noExplicitAny: ck is the untyped WASM instance
+c, 
+// biome-ignore lint/suspicious/noExplicitAny: an Image or Canvas handle from it
+source, width, height) {
+    const info = {
+        width,
+        height,
+        colorType: c.ColorType.RGBA_8888,
+        alphaType: c.AlphaType.Unpremul,
+        colorSpace: c.ColorSpace.SRGB,
+    };
+    const px = source.readPixels(0, 0, info, undefined, width * 4);
+    // Copy out of the WASM heap so the result owns its buffer.
+    return px ? px.slice() : null;
+}
+// Draw an image's `src` rect into an `outW`×`outH` surface at `dest` (Mitchell
+// cubic) and read the result back as RGBA. Owns the surface + paint lifecycle
+// (freed even on throw) and returns null if the surface or readback fails. Shared
+// by the downscale path here and by consumers that render a cropped/fitted image
+// for analysis.
+export function drawImageToPixels(ck, 
+// biome-ignore lint/suspicious/noExplicitAny: CanvasKit Image, untyped
+img, outW, outH, src, dest) {
+    // biome-ignore lint/suspicious/noExplicitAny: ck is the untyped WASM instance
+    const c = ck;
+    const surface = c.MakeSurface(outW, outH);
+    if (!surface)
+        return null;
+    const paint = new c.Paint();
+    try {
+        const canvas = surface.getCanvas();
+        canvas.clear(c.TRANSPARENT);
+        canvas.drawImageRectCubic(img, c.XYWHRect(src.x, src.y, src.w, src.h), c.XYWHRect(dest.x, dest.y, dest.w, dest.h), 1 / 3, 1 / 3, paint);
+        surface.flush();
+        const data = readRGBA(c, canvas, outW, outH);
+        return data ? { data, width: outW, height: outH } : null;
+    }
+    finally {
+        paint.delete();
+        surface.delete();
+    }
+}
+// Decode and rasterize an ImageNode exactly as the painter draws it: its resolved
+// box and object-fit crop determine the pixels returned, rather than the source
+// file alone. This is the reusable bridge for consumers such as print analysis;
+// it keeps CanvasKit decoding and fit math in freshcoat instead of duplicating
+// them in every caller.
+export async function sampleImageNode(ck, node, loadImageBytes, opts) {
+    // biome-ignore lint/suspicious/noExplicitAny: ck is the untyped WASM instance
+    const c = ck;
+    const img = c.MakeImageFromEncoded(await loadImageBytes(node.src));
+    if (!img)
+        return null;
+    try {
+        const boxW = node.size?.width ?? img.width();
+        const boxH = node.size?.height ?? img.height();
+        const maxDim = opts?.maxDim;
+        const scale = maxDim ? Math.min(1, maxDim / Math.max(boxW, boxH)) : 1;
+        const width = Math.max(1, Math.round(boxW * scale));
+        const height = Math.max(1, Math.round(boxH * scale));
+        // Tile repeats the full source; its distribution is therefore the source's,
+        // and rendering it as fill gives analysis the same pixels without allocating
+        // a potentially enormous repeated surface.
+        const fit = node.fit === "tile" ? "fill" : node.fit;
+        const r = fitRect(img.width(), img.height(), 0, 0, width, height, fit);
+        return drawImageToPixels(c, img, width, height, { x: r.sx, y: r.sy, w: r.sw, h: r.sh }, { x: r.dx, y: r.dy, w: r.dw, h: r.dh });
+    }
+    finally {
+        img.delete();
+    }
+}
+// Decode `bytes` (PNG/JPEG/WebP/GIF — whatever CanvasKit's codecs handle) to RGBA.
+// Returns null if the bytes can't be decoded (or read back). With `maxDim`, the
+// image is downscaled (Mitchell cubic) so the longest side is at most that many.
+export function decodePixels(ck, bytes, opts) {
+    // biome-ignore lint/suspicious/noExplicitAny: ck is the untyped WASM instance
+    const c = ck;
+    const img = c.MakeImageFromEncoded(bytes);
+    if (!img)
+        return null;
+    try {
+        const iw = img.width();
+        const ih = img.height();
+        const maxDim = opts?.maxDim;
+        const scale = maxDim ? Math.min(1, maxDim / Math.max(iw, ih)) : 1;
+        if (scale >= 1) {
+            const data = readRGBA(c, img, iw, ih);
+            return data ? { data, width: iw, height: ih } : null;
+        }
+        const w = Math.max(1, Math.round(iw * scale));
+        const h = Math.max(1, Math.round(ih * scale));
+        const out = drawImageToPixels(c, img, w, h, { x: 0, y: 0, w: iw, h: ih }, { x: 0, y: 0, w, h });
+        if (out)
+            return out;
+        // No surface / failed readback — fall back to a full-res read.
+        const data = readRGBA(c, img, iw, ih);
+        return data ? { data, width: iw, height: ih } : null;
+    }
+    finally {
+        img.delete();
+    }
+}

package/src/export-scale.d.ts

@@ -0,0 +1,25 @@
+import type { Size } from "./types.js";
+export type ExportConstraint = {
+    kind: "scale";
+    value: number;
+} | {
+    kind: "width";
+    value: number;
+} | {
+    kind: "height";
+    value: number;
+};
+export type ExportSetting = {
+    constraint?: ExportConstraint;
+    suffix?: string;
+    supersample?: number;
+};
+export declare const MAX_EXPORT_DIMENSION = 8192;
+export declare function resolveExportScale(constraint: ExportConstraint | undefined, size: Size, opts?: {
+    maxDimension?: number;
+}): number;
+export declare const MAX_SUPERSAMPLE = 4;
+export declare function resolveSupersample(supersample: number | undefined, size: Size, scale: number, opts?: {
+    maxDimension?: number;
+}): number;
+export declare function exportPixelSize(size: Size, scale: number): Size;