freshcoat 0.1.0

package/src/export-scale.js

@@ -0,0 +1,74 @@
+// Longest axis an export may reach. A raster surface is width·height·4 bytes, so
+// an unbounded scale on a large design is an out-of-memory, not a slow render.
+// Past this the scale is lowered to fit rather than throwing — a softer export
+// beats no export, and the effective scale comes back from resolveExportScale for
+// a caller that wants to notice.
+export const MAX_EXPORT_DIMENSION = 8192;
+// The device-pixel multiplier an export constraint asks for on a design of `size`,
+// lowered so neither axis crosses `maxDimension`. A missing/degenerate constraint
+// is 1×.
+export function resolveExportScale(constraint, size, opts) {
+    const requested = requestedScale(constraint, size);
+    if (!Number.isFinite(requested) || requested <= 0)
+        return 1;
+    const longest = Math.max(size.width, size.height);
+    if (longest <= 0)
+        return requested;
+    const ceiling = (opts?.maxDimension ?? MAX_EXPORT_DIMENSION) / longest;
+    return Math.min(requested, ceiling);
+}
+function requestedScale(constraint, size) {
+    if (!constraint)
+        return 1;
+    switch (constraint.kind) {
+        case "scale":
+            return constraint.value;
+        case "width":
+            return size.width > 0 ? constraint.value / size.width : 1;
+        case "height":
+            return size.height > 0 ? constraint.value / size.height : 1;
+    }
+}
+// How many times denser than the export a scene may be RENDERED before being
+// reduced to the export size. Past this the extra samples stop buying visible
+// quality and only cost fill rate — 4× the density is already 16× the pixels.
+export const MAX_SUPERSAMPLE = 4;
+// The supersample factor an export may actually use: the scene is rendered at
+// `scale × supersample` and reduced to `scale` before it is finished or encoded,
+// so the output keeps its 1× pixel count while every edge is resolved from
+// several samples instead of one. This is the knob for a FIXED output size — a
+// caller that can afford more pixels should raise `scale` instead and get the
+// same detail at the larger size for a quarter of the fill.
+//
+// Bounded twice: by MAX_SUPERSAMPLE, and by the same `maxDimension` ceiling the
+// export scale answers to — the render surface is the one that has to be
+// allocated, so it is the one that must fit. A request that cannot be honoured
+// is lowered rather than refused (1 = render at the export size, no reduction).
+//
+// Always a power of two, rounded down. The reduction is a chain of exact 2:1
+// halvings (see the painter's reduceSupersampled) because that is the only ratio
+// a resampler averages every sample at: a cubic filter's support does not widen
+// with the minification, so a 4:1 cubic reduction quietly reads a fraction of the
+// samples that were paid for and lands no better than 2:1. A request of 3 is
+// therefore honoured as 2, and anything under 2 as no supersampling.
+export function resolveSupersample(supersample, size, scale, opts) {
+    const requested = Math.min(supersample ?? 1, MAX_SUPERSAMPLE);
+    if (!Number.isFinite(requested) || requested < 2)
+        return 1;
+    const longest = Math.max(size.width, size.height) * scale;
+    const ceiling = longest > 0
+        ? (opts?.maxDimension ?? MAX_EXPORT_DIMENSION) / longest
+        : requested;
+    const fitted = Math.min(requested, ceiling);
+    return fitted >= 2 ? 2 ** Math.floor(Math.log2(fitted)) : 1;
+}
+// The surface a design of `size` occupies at `scale`, in whole pixels. Rounding
+// (not flooring) is what makes a `width: 1024` constraint land on exactly 1024.
+// The painter sizes its surface with this, so a caller naming or laying out the
+// result reads the same numbers the pixels have.
+export function exportPixelSize(size, scale) {
+    return {
+        width: Math.max(1, Math.round(size.width * scale)),
+        height: Math.max(1, Math.round(size.height * scale)),
+    };
+}

package/src/font-bytes.d.ts

@@ -0,0 +1,4 @@
+import type { FontRequest, FontResolution } from "./types.js";
+export declare function resolveFontRequest(req: FontRequest | string, bytesByFamily?: Map<string, Uint8Array[]>): FontResolution;
+export declare function fontBytes(res: FontResolution): Promise<Uint8Array[]>;
+export declare function dataUrlToBytes(src: string): Uint8Array;

package/src/font-bytes.js

@@ -0,0 +1,165 @@
+// Resolve a request against the env's pre-supplied bytes, else its descriptor.
+// Shared by every runtime — the only per-env input is the pre-supplied map.
+export function resolveFontRequest(req, bytesByFamily) {
+    const r = typeof req === "string" ? { family: req } : req;
+    const pre = bytesByFamily?.get(r.family);
+    if (pre)
+        return { kind: "bytes", bytes: pre };
+    if ("descriptor" in r)
+        return { kind: "descriptor", descriptor: r.descriptor };
+    return { kind: "none" };
+}
+// Old UA nudges Google Fonts / Fontsource to serve one unsubsetted TTF, which the
+// sfnt metrics reader (readFontMetrics) can parse; it cannot parse WOFF2.
+// Browsers treat user-agent as a forbidden header and ignore it, falling back to
+// WOFF2, which CanvasKit decodes fine.
+const TTF_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/534.30 (KHTML, like Gecko)";
+const FONT_FETCH_TIMEOUT_MS = 8000;
+// Turn a resolution into raw font-file bytes: stylesheet parsing + fetch. Purely
+// async I/O over data:/http (universal) — local filesystem reads are the env's
+// job, done up-front in its resolveFont (which returns { kind: "bytes" }).
+export async function fontBytes(res) {
+    if (res.kind === "bytes")
+        return res.bytes;
+    if (res.kind === "none")
+        return [];
+    return descriptorBytes(res.descriptor);
+}
+async function descriptorBytes(d) {
+    if (d.kind === "local") {
+        return Promise.all(d.files.map((f) => fileBytes(f.src)));
+    }
+    // google / fontsource carry a CSS stylesheet, not a font file.
+    return stylesheetFontBytes(d.url);
+}
+async function fileBytes(src) {
+    if (src.startsWith("data:"))
+        return dataUrlToBytes(src);
+    if (/^https?:/i.test(src))
+        return fetchBytes(src);
+    throw new Error(`cannot fetch local font path "${src}"; a runtime must materialize local files in resolveFont`);
+}
+/**
+ * Every font file a Google / Fontsource stylesheet points at, Latin-covering
+ * faces first.
+ *
+ * Taking the stylesheet's *first* url is wrong, and silently so. When the
+ * request carries a modern user-agent — which is every browser, since UA is a
+ * forbidden header there and TTF_UA below is dropped — Google answers with one
+ * `@font-face` per (weight × unicode subset), and it lists `latin-ext` before
+ * `latin`. That first face's range starts at U+0100, so it has no A–Z at all:
+ * every ASCII glyph renders as .notdef, with correct metrics, which reads as a
+ * broken template rather than a wrong font file. Servers never saw it, because
+ * the old UA gets them a single unsubsetted TTF.
+ *
+ * So: parse the faces, sort the ones that cover Basic Latin to the front —
+ * `deriveFontMetrics` reads `faces[0]`, and a subset without Latin would give
+ * the wrong cap height — and load them all, which also picks up the accented
+ * ranges and the other weights the single-face fetch was dropping.
+ */
+async function stylesheetFontBytes(cssUrl) {
+    const css = await fetchText(cssUrl);
+    const faces = parseStylesheetFaces(css);
+    if (faces.length === 0) {
+        throw new Error(`no font file found in stylesheet: ${cssUrl}`);
+    }
+    const ordered = [
+        ...faces.filter((f) => f.coversLatin),
+        ...faces.filter((f) => !f.coversLatin),
+    ];
+    // One URL, one face. A VARIABLE family answers every requested weight with the
+    // same file per subset — `wght@400;600;700` is three @font-face rows pointing
+    // at one woff2 — so without this the same bytes are fetched and registered
+    // three times. The duplicates are not a second weight (the axis is set at
+    // draw time, see paragraph-layout's spanTextStyle); they are only cost, and
+    // they make the family's face list read as if the weights were there.
+    const seen = new Set();
+    const unique = [];
+    for (const face of ordered) {
+        if (seen.has(face.url))
+            continue;
+        seen.add(face.url);
+        unique.push(face);
+    }
+    return Promise.all(unique.map((f) => fetchBytes(f.url)));
+}
+const FONT_FILE = /\.(ttf|otf|woff2?)(\?|#|$)/i;
+const LATIN_A = 0x41;
+function parseStylesheetFaces(css) {
+    const faces = [];
+    // A CSS @font-face body has no nested braces, so the first `}` ends it.
+    for (const chunk of css.split(/@font-face/i).slice(1)) {
+        const end = chunk.indexOf("}");
+        const body = end === -1 ? chunk : chunk.slice(0, end);
+        const urls = [...body.matchAll(/url\((['"]?)([^'")]+)\1\)/g)].map((m) => m[2]);
+        const url = urls.find((u) => FONT_FILE.test(u)) ?? urls[0];
+        if (!url)
+            continue;
+        const range = body.match(/unicode-range:\s*([^;}]+)/i)?.[1];
+        // No declared range means the face carries everything it has.
+        faces.push({
+            url,
+            coversLatin: range === undefined || rangeCovers(range, LATIN_A),
+        });
+    }
+    if (faces.length > 0)
+        return faces;
+    // A stylesheet with no @font-face at all (or one shaped unexpectedly): fall
+    // back to the old whole-file scan rather than claim the font is unavailable.
+    const urls = [...css.matchAll(/url\((['"]?)([^'")]+)\1\)/g)].map((m) => m[2]);
+    const url = urls.find((u) => FONT_FILE.test(u)) ?? urls[0];
+    return url ? [{ url, coversLatin: true }] : [];
+}
+/** Whether a CSS `unicode-range` value covers a code point. */
+function rangeCovers(spec, code) {
+    for (const part of spec.split(",")) {
+        const token = part.trim().replace(/^u\+/i, "");
+        if (!token)
+            continue;
+        if (token.includes("?")) {
+            // Wildcard form, e.g. `U+00??` — every code point matching the pattern.
+            const lo = Number.parseInt(token.replace(/\?/g, "0"), 16);
+            const hi = Number.parseInt(token.replace(/\?/g, "F"), 16);
+            if (code >= lo && code <= hi)
+                return true;
+            continue;
+        }
+        const [from, to] = token.split("-");
+        const lo = Number.parseInt(from, 16);
+        const hi = to === undefined ? lo : Number.parseInt(to, 16);
+        if (Number.isFinite(lo) && code >= lo && code <= hi)
+            return true;
+    }
+    return false;
+}
+async function fetchText(url) {
+    const res = await fetch(url, {
+        headers: { "user-agent": TTF_UA },
+        signal: AbortSignal.timeout(FONT_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new Error(`fetch ${url} -> ${res.status}`);
+    return res.text();
+}
+async function fetchBytes(url) {
+    const res = await fetch(url, {
+        headers: { "user-agent": TTF_UA },
+        signal: AbortSignal.timeout(FONT_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new Error(`fetch ${url} -> ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+}
+export function dataUrlToBytes(src) {
+    const comma = src.indexOf(",");
+    const meta = src.slice(0, comma);
+    const data = src.slice(comma + 1);
+    if (meta.includes(";base64")) {
+        const bin = atob(data);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    return new TextEncoder().encode(decodeURIComponent(data));
+}

package/src/font-metrics.d.ts

@@ -0,0 +1,5 @@
+import type { FontVMetrics } from "./types.js";
+export declare function registerFontMetrics(family: string, data: Uint8Array | ArrayBuffer): void;
+export declare function getFontMetrics(family: string): FontVMetrics | undefined;
+export declare function deriveFontMetrics(fonts: Map<string, Uint8Array[]>): Record<string, FontVMetrics>;
+export declare function readFontMetrics(data: Uint8Array | ArrayBuffer): FontVMetrics | null;

package/src/font-metrics.js

@@ -0,0 +1,62 @@
+const registry = new Map();
+export function registerFontMetrics(family, data) {
+    const m = readFontMetrics(data);
+    if (m)
+        registry.set(family, m);
+}
+export function getFontMetrics(family) {
+    return registry.get(family);
+}
+// Build the { family: FontVMetrics } map compileScene wants from a family→bytes
+// map (the first face per family), skipping any the reader can't parse. The
+// standard way to derive CompileSceneOptions.fontMetrics when rendering with a
+// bytes-backed font set (headless / CanvasKit paths).
+export function deriveFontMetrics(fonts) {
+    const out = {};
+    for (const [family, faces] of fonts) {
+        const bytes = faces[0];
+        if (!bytes)
+            continue;
+        const m = readFontMetrics(bytes);
+        if (m)
+            out[family] = m;
+    }
+    return out;
+}
+// Read OS/2 sTypoAscender/Descender/LineGap + sCapHeight and head.unitsPerEm
+// from an sfnt (ttf/otf) buffer, normalized per em. Returns null on anything
+// unexpected so callers fall back.
+export function readFontMetrics(data) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    try {
+        const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        const numTables = dv.getUint16(4);
+        let os2 = 0;
+        let head = 0;
+        for (let i = 0; i < numTables; i++) {
+            const o = 12 + i * 16;
+            const tag = String.fromCharCode(bytes[o], bytes[o + 1], bytes[o + 2], bytes[o + 3]);
+            const off = dv.getUint32(o + 8);
+            if (tag === "OS/2")
+                os2 = off;
+            else if (tag === "head")
+                head = off;
+        }
+        if (!os2 || !head)
+            return null;
+        const upem = dv.getUint16(head + 18);
+        if (!upem)
+            return null;
+        const version = dv.getUint16(os2);
+        return {
+            ascent: dv.getInt16(os2 + 68) / upem,
+            descent: -dv.getInt16(os2 + 70) / upem,
+            lineGap: dv.getInt16(os2 + 72) / upem,
+            // sCapHeight exists from OS/2 v2 onward (offset 88).
+            capHeight: version >= 2 ? dv.getInt16(os2 + 88) / upem : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/src/headless.d.ts

@@ -0,0 +1,24 @@
+import type { Node } from "./node.js";
+import type { PaintCache } from "./paint-cache.js";
+import type { EncodeOptions } from "./png.js";
+import type { EncodedPaintResult, FontVMetrics, FrameFinish, PaintRuntime } from "./types.js";
+export declare function createHeadlessEnv(opts?: {
+    fonts?: Map<string, Uint8Array[]>;
+    images?: Map<string, Uint8Array>;
+    encode?: EncodeOptions;
+    cache?: PaintCache;
+    loadImage?: PaintRuntime["loadImage"];
+}): PaintRuntime;
+export declare function renderSceneToPng(node: Node, opts: {
+    width: number;
+    height: number;
+    ck: unknown;
+    fonts?: Map<string, Uint8Array[]>;
+    images?: Map<string, Uint8Array>;
+    fontMetrics?: Record<string, FontVMetrics>;
+    leadingTrim?: boolean;
+    finish?: FrameFinish;
+    encode?: EncodeOptions;
+    scale?: number;
+    supersample?: number;
+}): Promise<EncodedPaintResult>;

package/src/headless.js

@@ -0,0 +1,58 @@
+import { compileScene } from "./compile-scene.js";
+import { dataUrlToBytes, resolveFontRequest } from "./font-bytes.js";
+import { deriveFontMetrics } from "./font-metrics.js";
+import { createParagraphEngine } from "./paragraph-layout.js";
+import { makeRuntime } from "./runtime.js";
+async function fetchBytes(url) {
+    if (url.startsWith("data:"))
+        return dataUrlToBytes(url);
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`fetch ${url} -> ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+}
+// A headless runtime: font resolution + image byte I/O, NO canvas host, encode
+// policy. With no host, the paint step renders offscreen via ck.MakeSurface and
+// PaintOutput.encode() reads those pixels back as a PNG (see ./png).
+export function createHeadlessEnv(opts) {
+    return makeRuntime({
+        cache: opts?.cache,
+        ...(opts?.loadImage ? { loadImage: opts.loadImage } : {}),
+        resolveFont(req) {
+            return resolveFontRequest(req, opts?.fonts);
+        },
+        async loadImageBytes(src) {
+            return opts?.images?.get(src) ?? fetchBytes(src);
+        },
+    }, "encode", opts?.encode);
+}
+// Compile a Node scene and rasterize it to PNG bytes offscreen — the whole
+// headless path in one call. Derives font metrics from `fonts` (override with
+// `fontMetrics`), builds the CanvasKit Paragraph text engine, compiles + paints,
+// and disposes the engine. `ck` is the caller's CanvasKit-WASM instance.
+export async function renderSceneToPng(node, opts) {
+    const fonts = opts.fonts ?? new Map();
+    const fontMetrics = opts.fontMetrics ?? deriveFontMetrics(fonts);
+    const textEngine = createParagraphEngine(opts.ck, fonts);
+    try {
+        const commands = compileScene(node, {
+            width: opts.width,
+            height: opts.height,
+            textEngine,
+            fontMetrics,
+            leadingTrim: opts.leadingTrim,
+            finish: opts.finish,
+            scale: opts.scale,
+            supersample: opts.supersample,
+        });
+        const env = createHeadlessEnv({
+            fonts,
+            images: opts.images,
+            encode: opts.encode,
+        });
+        return (await env.paint(commands, opts.ck));
+    }
+    finally {
+        textEngine.dispose();
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,25 @@
+export { type AdjustOptions, brightnessMatrix, buildAdjust, type ColorMatrix, concatColorMatrix, contrastMatrix, gammaLut, identityColorMatrix, identityLut3d, saturationMatrix, } from "./adjust.js";
+export { approxEngine } from "./approx-layout.js";
+export { type BakeTextOptions, bakeText, resolveLeadingTrim, textClipOutset, } from "./bake-text.js";
+export { type CompileSceneOptions, compileScene, prepareScene, sceneAssets, } from "./compile-scene.js";
+export { type ColorResolver, oklchToHex, parseCssColor, parseLinearGradient, } from "./css.js";
+export { type DecodedPixels, type DecodeOptions, decodePixels, drawImageToPixels, type ImageBytesLoader, type ImageSampleOptions, type PixelRect, sampleImageNode, } from "./decode.js";
+export { type ExportConstraint, type ExportSetting, exportPixelSize, MAX_EXPORT_DIMENSION, MAX_SUPERSAMPLE, resolveExportScale, resolveSupersample, } from "./export-scale.js";
+export { dataUrlToBytes, fontBytes, resolveFontRequest, } from "./font-bytes.js";
+export { deriveFontMetrics, getFontMetrics, readFontMetrics, registerFontMetrics, } from "./font-metrics.js";
+export { autoLineHeight, FALLBACK_LINE_HEIGHT, type MetricsLookup, metricsLookup, resolveAutoLineHeights, } from "./line-height.js";
+export type { Align, BitmapNode, ChildLayout, EllipseNode, FlexLayout, GridLayout, GroupNode, ImageNode, Justify, Layout, MaskNode, Node, Padding, PathNode, RectNode, TextNode, TrackSize, Transform, } from "./node.js";
+export { autoLayout, createBitmap, createCircle, createEllipse, createFrame, createGroup, createImage, createMask, createPath, createRect, createText, gridLayout, } from "./node.js";
+export { createPaintCache, type PaintCache, type PaintCacheStats, } from "./paint-cache.js";
+export { decorationLine, fitRect, insetCorner, strokeInset, } from "./paint-helpers.js";
+export { createParagraphEngine } from "./paragraph-layout.js";
+export { scalePathData } from "./path-data.js";
+export { flattenOverWhite } from "./jpeg.js";
+export { DEFAULT_JPEG_QUALITY, DEFAULT_WEBP_QUALITY, type EncodeFormat, type EncodeOptions, type EncodePngOptions, encodeDecodedPng, encodePng, type PngEffort, } from "./png.js";
+export { resolveLayout } from "./resolve-layout.js";
+export { squircleSvg } from "./squircle.js";
+export { type CachedTextEngine, memoizeTextEngine, type TextEngineCacheStats, } from "./text-cache.js";
+export type { SpanFont, TextEngine } from "./text-engine.js";
+export type { MeasuredLine, MeasureText, TextLayout, TextLayoutInput, } from "./text-types.js";
+export type * from "./types.js";
+export { type IrIssue, validateCommands } from "./validate-commands.js";

package/src/index.js

@@ -0,0 +1,29 @@
+// freshcoat — the rendering foundation. Compiles the composable Node IR
+// (via compileScene) to a flat Command list and paints it to pixels via CanvasKit
+// (WASM Skia) — no native canvas anywhere. The paint TARGET (offscreen vs live
+// canvas) lives on its own subpaths — freshcoat/browser | /headless — and
+// each env's `paint(frames, ck)` defaults to the CanvasKit painter, so the barrel
+// stays free of DOM / WASM weight. The backend seam itself is
+// freshcoat/runtime (Painter + makeRuntime); the `Painter` TYPE is
+// re-exported here, since a type costs nothing.
+export { brightnessMatrix, buildAdjust, concatColorMatrix, contrastMatrix, gammaLut, identityColorMatrix, identityLut3d, saturationMatrix, } from "./adjust.js";
+export { approxEngine } from "./approx-layout.js";
+export { bakeText, resolveLeadingTrim, textClipOutset, } from "./bake-text.js";
+export { compileScene, prepareScene, sceneAssets, } from "./compile-scene.js";
+export { oklchToHex, parseCssColor, parseLinearGradient, } from "./css.js";
+export { decodePixels, drawImageToPixels, sampleImageNode, } from "./decode.js";
+export { exportPixelSize, MAX_EXPORT_DIMENSION, MAX_SUPERSAMPLE, resolveExportScale, resolveSupersample, } from "./export-scale.js";
+export { dataUrlToBytes, fontBytes, resolveFontRequest, } from "./font-bytes.js";
+export { deriveFontMetrics, getFontMetrics, readFontMetrics, registerFontMetrics, } from "./font-metrics.js";
+export { autoLineHeight, FALLBACK_LINE_HEIGHT, metricsLookup, resolveAutoLineHeights, } from "./line-height.js";
+export { autoLayout, createBitmap, createCircle, createEllipse, createFrame, createGroup, createImage, createMask, createPath, createRect, createText, gridLayout, } from "./node.js";
+export { createPaintCache, } from "./paint-cache.js";
+export { decorationLine, fitRect, insetCorner, strokeInset, } from "./paint-helpers.js";
+export { createParagraphEngine } from "./paragraph-layout.js";
+export { scalePathData } from "./path-data.js";
+export { flattenOverWhite } from "./jpeg.js";
+export { DEFAULT_JPEG_QUALITY, DEFAULT_WEBP_QUALITY, encodeDecodedPng, encodePng, } from "./png.js";
+export { resolveLayout } from "./resolve-layout.js";
+export { squircleSvg } from "./squircle.js";
+export { memoizeTextEngine, } from "./text-cache.js";
+export { validateCommands } from "./validate-commands.js";

package/src/jpeg.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Composites unpremultiplied RGBA8888 pixels over opaque white, in place, and
+ * returns the same buffer with every alpha at 255.
+ */
+export declare function flattenOverWhite(pixels: Uint8Array): Uint8Array;

package/src/jpeg.js

@@ -0,0 +1,20 @@
+// JPEG has no alpha channel. Skia's encoder drops it from premultiplied
+// pixels, so a transparent corner comes out black; a photo export wants what
+// a viewer shows on a page instead, which is white.
+/**
+ * Composites unpremultiplied RGBA8888 pixels over opaque white, in place, and
+ * returns the same buffer with every alpha at 255.
+ */
+export function flattenOverWhite(pixels) {
+    for (let i = 0; i < pixels.length; i += 4) {
+        const a = pixels[i + 3];
+        if (a === 255)
+            continue;
+        const rest = 255 * (255 - a);
+        pixels[i] = ((pixels[i] * a + rest + 127) / 255) | 0;
+        pixels[i + 1] = ((pixels[i + 1] * a + rest + 127) / 255) | 0;
+        pixels[i + 2] = ((pixels[i + 2] * a + rest + 127) / 255) | 0;
+        pixels[i + 3] = 255;
+    }
+    return pixels;
+}

package/src/line-height.d.ts

@@ -0,0 +1,7 @@
+import type { Node } from "./node.js";
+import type { FontVMetrics } from "./types.js";
+export declare const FALLBACK_LINE_HEIGHT = 1.2;
+export declare function autoLineHeight(metrics: FontVMetrics | undefined): number;
+export type MetricsLookup = (family: string) => FontVMetrics | undefined;
+export declare function metricsLookup(explicit?: Record<string, FontVMetrics>, probe?: MetricsLookup): MetricsLookup;
+export declare function resolveAutoLineHeights(root: Node, lookup: MetricsLookup): Node;

package/src/line-height.js

@@ -0,0 +1,80 @@
+// Automatic line height — the "AUTO" a design tool shows when nobody typed a
+// number. It is not a constant: it is the FONT's own line box, its typo ascent +
+// descent + line gap. Vend Sans is 1.48; Geist is not; a template that hard-codes
+// 1.2 for both renders neither the way its source did.
+//
+// A font carries `autoLineHeight` when the authored value was AUTO. `lineHeight`
+// still holds a usable number (the fallback below), so every consumer that never
+// learned about this — a bare resolveLayout, the approx engine, an older
+// painter — keeps laying text out instead of producing NaN. compileScene
+// substitutes the real value once, before layout and baking, for the families it
+// has metrics for.
+import { getFontMetrics } from "./font-metrics.js";
+// What an unresolvable AUTO falls back to: the value coatfile has always
+// written for it, so a family with no metrics renders exactly as it did before.
+export const FALLBACK_LINE_HEIGHT = 1.2;
+// A font's own line box, per em. The sum a design tool uses for AUTO.
+export function autoLineHeight(metrics) {
+    if (!metrics)
+        return FALLBACK_LINE_HEIGHT;
+    const height = metrics.ascent + metrics.descent + metrics.lineGap;
+    return height > 0 ? height : FALLBACK_LINE_HEIGHT;
+}
+export function metricsLookup(explicit, probe) {
+    return (family) => explicit?.[family] ?? getFontMetrics(family) ?? probe?.(family);
+}
+// Replace every AUTO line height in the tree with the font's own. Returns the
+// same node when nothing is marked AUTO, so a tree that never used it is not
+// copied. Idempotent: a resolved font is no longer marked.
+export function resolveAutoLineHeights(root, lookup) {
+    return hasAuto(root) ? rewrite(root, lookup) : root;
+}
+function hasAuto(node) {
+    switch (node.kind) {
+        case "text":
+            return (!!node.font.autoLineHeight ||
+                !!node.spans?.some((s) => s.font?.autoLineHeight));
+        case "group":
+            return node.children.some(hasAuto);
+        case "mask":
+            return hasAuto(node.mask) || node.children.some(hasAuto);
+        default:
+            return false;
+    }
+}
+function rewrite(node, lookup) {
+    switch (node.kind) {
+        case "text":
+            return rewriteText(node, lookup);
+        case "group":
+            return {
+                ...node,
+                children: node.children.map((c) => rewrite(c, lookup)),
+            };
+        case "mask":
+            return {
+                ...node,
+                mask: rewrite(node.mask, lookup),
+                children: node.children.map((c) => rewrite(c, lookup)),
+            };
+        default:
+            return node;
+    }
+}
+function rewriteText(node, lookup) {
+    const font = resolveFont(node.font, node.font.family, lookup);
+    const spans = node.spans?.map((span) => span.font
+        ? {
+            ...span,
+            // A span inherits the element's family unless it names its own.
+            font: resolveFont(span.font, span.font.family ?? node.font.family, lookup),
+        }
+        : span);
+    return { ...node, font, ...(spans ? { spans } : {}) };
+}
+function resolveFont(font, family, lookup) {
+    if (!font.autoLineHeight)
+        return font;
+    const { autoLineHeight: _, ...rest } = font;
+    return { ...rest, lineHeight: autoLineHeight(lookup(family)) };
+}