freshcoat 0.1.0

package/src/paragraph-layout.js

@@ -0,0 +1,283 @@
+// A TextEngine backed by CanvasKit's native Paragraph API. It does line
+// breaking AND measurement in the same engine the CanvasKit painter shapes with,
+// so layout and paint agree.
+//
+// Whitespace runs are collapsed before shaping (CSS white-space: normal), which
+// Paragraph on its own would preserve. Break opportunities follow Skia's UAX-14
+// rules, so breaks inside URLs and punctuation-dense runs can differ from a
+// browser's.
+//
+// getLineMetrics start/end indices are UTF-16 code-unit offsets (JS string
+// indices), so per-line text is a direct string slice. Checked for Latin + BMP
+// punctuation (em dash etc.); astral/emoji (surrogate pairs) and CJK line-break
+// rules are untested.
+import { fontVariationList } from "./paint-helpers.js";
+const WEIGHTS = {
+    100: "Thin",
+    200: "ExtraLight",
+    300: "Light",
+    400: "Normal",
+    500: "Medium",
+    600: "SemiBold",
+    700: "Bold",
+    800: "ExtraBold",
+    900: "Black",
+};
+const SHRINK_FLOOR_PX = 8;
+const NATURAL_WIDTH = 1e7; // effectively unbounded — single-line advance
+// Font size the metrics probe shapes at: big enough that the reported line box
+// divides back to a per-em ratio without rounding noise.
+const PROBE_EM = 1000;
+// CSS white-space: normal: collapse every run of whitespace (spaces, tabs,
+// newlines) to a single space. Line-edge trimming is handled
+// per line via endExcludingWhitespaces.
+function collapse(text) {
+    return text.replace(/\s+/g, " ");
+}
+export function createParagraphEngine(ck, fonts) {
+    const provider = ck.TypefaceFontProvider.Make();
+    for (const [family, list] of fonts) {
+        for (const bytes of list) {
+            provider.registerFont(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength), family);
+        }
+    }
+    // Every registered family, in insertion order, used as the per-glyph fallback
+    // chain: a span names one family, but CanvasKit only falls back to families it
+    // sees in `fontFamilies`, so append the rest. Without this, any glyph the span's
+    // font lacks (emoji, CJK, Arabic…) renders as tofu even when a covering font is
+    // registered. Callers order the map so broader fallbacks come after the primary.
+    const fallbackFamilies = [...fonts.keys()];
+    function ckWeight(weight) {
+        return ck.FontWeight[WEIGHTS[Math.round((weight || 400) / 100) * 100] ?? "Normal"];
+    }
+    // The CanvasKit TextStyle for a span — the same shape canvaskit.ts paints
+    // with. CanvasKit adds letterSpacing after each glyph, so measuring/breaking
+    // with it here matches the render exactly.
+    function spanTextStyle(font) {
+        return {
+            fontFamilies: [
+                font.family,
+                ...fallbackFamilies.filter((f) => f !== font.family),
+            ],
+            fontSize: font.size,
+            fontStyle: {
+                weight: ckWeight(font.weight),
+                slant: font.style === "italic" ? ck.FontSlant.Italic : ck.FontSlant.Upright,
+            },
+            // The same weight again as a variation axis, plus any other axes the
+            // span sets. A family delivered as one variable file (what Google Fonts
+            // serves a browser, one woff2 per subset reused across every weight row)
+            // would otherwise shape a 700 span as the 400 instance under synthetic
+            // bold: lighter strokes and 400's advances, so thin and mis-wrapped.
+            fontVariations: fontVariationList(font.weight, font.variations),
+            ...(font.letterSpacing ? { letterSpacing: font.letterSpacing } : {}),
+        };
+    }
+    function build(text, font) {
+        const style = new ck.ParagraphStyle({ textStyle: spanTextStyle(font) });
+        const builder = ck.ParagraphBuilder.MakeFromFontProvider(style, provider);
+        builder.addText(text);
+        return { para: builder.build(), builder };
+    }
+    // Shape every styled span as ONE paragraph and wrap at maxWidth, so cross-span
+    // shaping, per-fragment geometry, and wrapping of mixed-style text all match
+    // what canvaskit.ts paints. Spans are added verbatim
+    // — the painter does the same — and each line's fragments are sliced by the
+    // intersection of the span's text range with the line, positioned via
+    // getRectsForRange (advance-based selection rects) relative to the line's left.
+    function layoutInline(spans, maxWidth) {
+        if (spans.length === 0)
+            return { lines: [] };
+        const pstyle = new ck.ParagraphStyle({
+            textStyle: spanTextStyle(spans[0].font),
+        });
+        const builder = ck.ParagraphBuilder.MakeFromFontProvider(pstyle, provider);
+        const ranges = [];
+        let cursor = 0;
+        let full = "";
+        spans.forEach((s, i) => {
+            builder.pushStyle(ck.TextStyle(spanTextStyle(s.font)));
+            builder.addText(s.text);
+            builder.pop();
+            ranges.push({ start: cursor, end: cursor + s.text.length, spanIndex: i });
+            cursor += s.text.length;
+            full += s.text;
+        });
+        const para = builder.build();
+        try {
+            para.layout(maxWidth);
+            const lines = para
+                .getLineMetrics()
+                .map((lm) => {
+                const fragments = [];
+                for (const r of ranges) {
+                    const fs = Math.max(r.start, lm.startIndex);
+                    const fe = Math.min(r.end, lm.endExcludingWhitespaces);
+                    if (fe <= fs)
+                        continue; // span absent from this line (or only ws)
+                    const rects = para.getRectsForRange(fs, fe, ck.RectHeightStyle.Tight, ck.RectWidthStyle.Tight);
+                    if (!rects.length)
+                        continue;
+                    let left = Number.POSITIVE_INFINITY;
+                    let right = Number.NEGATIVE_INFINITY;
+                    for (const rd of rects) {
+                        left = Math.min(left, rd.rect[0]);
+                        right = Math.max(right, rd.rect[2]);
+                    }
+                    fragments.push({
+                        spanIndex: r.spanIndex,
+                        text: full.slice(fs, fe),
+                        x: left - lm.left,
+                        width: right - left,
+                    });
+                }
+                return { fragments, width: lm.width };
+            });
+            return { lines };
+        }
+        finally {
+            para.delete();
+            builder.delete();
+        }
+    }
+    function breakLines(text, font, maxWidth) {
+        const norm = collapse(text);
+        const { para, builder } = build(norm, font);
+        try {
+            para.layout(maxWidth);
+            return para
+                .getLineMetrics()
+                .map((m) => ({
+                // UTF-16 code-unit offsets → direct string slice.
+                text: norm.slice(m.startIndex, m.endExcludingWhitespaces).trim(),
+                width: m.width,
+            }));
+        }
+        finally {
+            para.delete();
+            builder.delete();
+        }
+    }
+    function naturalWidth(text, font) {
+        const { para, builder } = build(collapse(text), font);
+        try {
+            para.layout(NATURAL_WIDTH);
+            return para.getMaxIntrinsicWidth();
+        }
+        finally {
+            para.delete();
+            builder.delete();
+        }
+    }
+    const measureText = (text, font, maxWidth) => {
+        const lineHeightPx = font.size * font.lineHeight;
+        if (text.length === 0)
+            return { width: 0, height: lineHeightPx };
+        if (maxWidth === null) {
+            // Round the single-line (hug) width UP to a whole pixel: laying a
+            // paragraph out at exactly getMaxIntrinsicWidth wraps (CanvasKit breaks on
+            // `>=`, not `>`), so a hug box sized to the raw width would wrap/ellipsize.
+            return {
+                width: Math.ceil(naturalWidth(text, font)),
+                height: lineHeightPx,
+            };
+        }
+        const lines = breakLines(text, font, maxWidth);
+        const width = lines.reduce((max, l) => Math.max(max, l.width), 0);
+        const height = Math.max(1, lines.length) * lineHeightPx;
+        return { width, height };
+    };
+    const measureSpanWidth = (text, font) => {
+        if (text.length === 0)
+            return 0;
+        return naturalWidth(text, font);
+    };
+    // Mirrors text-layout.ts's layoutText/shrinkToFit so the two engines are
+    // interchangeable inside compile.
+    const layoutText = (input) => {
+        const lh = input.lineHeight;
+        const once = (size) => {
+            const lines = breakLines(input.value, { ...input.font, size }, input.maxWidth);
+            return {
+                lines,
+                totalHeight: lines.length * size * lh,
+                effectiveFontSize: size,
+            };
+        };
+        if (input.fit !== "shrink")
+            return { ...once(input.font.size), shrinkApplied: false };
+        if (input.font.size < SHRINK_FLOOR_PX)
+            return { ...once(input.font.size), shrinkApplied: false };
+        const full = once(input.font.size);
+        if (full.totalHeight <= input.maxHeight)
+            return { ...full, shrinkApplied: false };
+        let lo = SHRINK_FLOOR_PX;
+        let hi = input.font.size;
+        let best = null;
+        while (lo <= hi) {
+            const mid = Math.floor((lo + hi) / 2);
+            const trial = once(mid);
+            if (trial.totalHeight <= input.maxHeight) {
+                best = trial;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        if (best)
+            return { ...best, shrinkApplied: true };
+        return { ...once(SHRINK_FLOOR_PX), shrinkApplied: true };
+    };
+    // A family's vertical metrics as Skia reads them from the decoded face, for
+    // the AUTO line height (see ./line-height). This exists because the sfnt
+    // reader parses ttf/otf only and a browser is served woff2 — the bytes are
+    // already decoded here, so ask the engine that holds them. Measured off a
+    // probe paragraph at PROBE_EM, which reports the line box the font itself
+    // declares; cached per family, since it costs a shape.
+    const metricsCache = new Map();
+    function metricsFor(family) {
+        const hit = metricsCache.get(family);
+        if (hit !== undefined || metricsCache.has(family))
+            return hit;
+        let out;
+        if (fonts.has(family)) {
+            const { para, builder } = build("Hg", {
+                family,
+                size: PROBE_EM,
+                weight: 400,
+                lineHeight: 1,
+            });
+            try {
+                para.layout(NATURAL_WIDTH);
+                const lm = para.getLineMetrics()[0];
+                if (lm) {
+                    out = {
+                        ascent: lm.ascent / PROBE_EM,
+                        descent: lm.descent / PROBE_EM,
+                        // Skia folds the font's leading into the line's ascent/descent, so
+                        // counting it again here would double it.
+                        lineGap: 0,
+                        // Not what the paragraph reports; a caller that needs cap height
+                        // (leading trim) still goes through readFontMetrics.
+                        capHeight: 0,
+                    };
+                }
+            }
+            finally {
+                para.delete();
+                builder.delete();
+            }
+        }
+        metricsCache.set(family, out);
+        return out;
+    }
+    return {
+        measureText,
+        measureSpanWidth,
+        layoutText,
+        layoutInline,
+        metricsFor,
+        dispose: () => provider.delete(),
+    };
+}

package/src/path-data.d.ts

@@ -0,0 +1,5 @@
+/** Scale path data by `sx` horizontally and `sy` vertically (default: `sx`).
+ *  Exact for a uniform scale; with `sx !== sy` a rotated arc's radii are scaled
+ *  per axis, which approximates it. Throws on data it cannot read rather than
+ *  emitting a different shape. */
+export declare function scalePathData(d: string, sx: number, sy?: number): string;

package/src/path-data.js

@@ -0,0 +1,101 @@
+// Scaling SVG path data. Multiplying every number in a `d` string is only right
+// for the commands whose arguments are all coordinates: an arc's x-axis rotation
+// and its two flags are not lengths, and scaling them turns a quarter circle into
+// something else entirely. This tokenizes the path and scales only the arguments
+// that are lengths.
+// Arguments per command, and which of them are x / y lengths. Anything not listed
+// (an arc's rotation and flags) passes through unchanged.
+const ARITY = {
+    M: 2,
+    L: 2,
+    T: 2,
+    H: 1,
+    V: 1,
+    C: 6,
+    S: 4,
+    Q: 4,
+    A: 7,
+    Z: 0,
+};
+const AXIS = {
+    M: ["x", "y"],
+    L: ["x", "y"],
+    T: ["x", "y"],
+    H: ["x"],
+    V: ["y"],
+    C: ["x", "y", "x", "y", "x", "y"],
+    S: ["x", "y", "x", "y"],
+    Q: ["x", "y", "x", "y"],
+    A: ["x", "y", null, null, null, "x", "y"],
+    Z: [],
+};
+const NUMBER = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/;
+/** Scale path data by `sx` horizontally and `sy` vertically (default: `sx`).
+ *  Exact for a uniform scale; with `sx !== sy` a rotated arc's radii are scaled
+ *  per axis, which approximates it. Throws on data it cannot read rather than
+ *  emitting a different shape. */
+export function scalePathData(d, sx, sy = sx) {
+    if (sx === 1 && sy === 1)
+        return d;
+    // Everything that is not a length is copied through verbatim, so the output
+    // keeps the input's separators and number formatting.
+    let out = "";
+    let i = 0;
+    let cmd = "";
+    let argIndex = 0;
+    const copySeparators = () => {
+        while (i < d.length && /[\s,]/.test(d[i]))
+            out += d[i++];
+    };
+    // A rewritten number can lose the boundary its original had ("1.5.5" →
+    // "3" + "1"), so one that would run into the previous digits gets a space.
+    const emitScaled = (token) => {
+        if (/[\d.]$/.test(out) && !/^[-+]/.test(token))
+            out += " ";
+        out += token;
+    };
+    copySeparators();
+    while (i < d.length) {
+        const ch = d[i];
+        if (/[a-zA-Z]/.test(ch)) {
+            const upper = ch.toUpperCase();
+            if (!(upper in ARITY))
+                throw new Error(`path: unknown command "${ch}"`);
+            cmd = ch;
+            argIndex = 0;
+            out += ch;
+            i++;
+            copySeparators();
+            continue;
+        }
+        const upper = cmd.toUpperCase();
+        const arity = ARITY[upper];
+        if (!cmd || !arity)
+            throw new Error(`path: number without a command at ${i}`);
+        const slot = argIndex % arity;
+        let token;
+        if (upper === "A" && (slot === 3 || slot === 4)) {
+            // Flags are one character and may be written without a separator
+            // ("a1 1 0 01 5 5").
+            token = ch;
+            if (token !== "0" && token !== "1")
+                throw new Error(`path: bad arc flag "${token}" at ${i}`);
+            i++;
+        }
+        else {
+            const m = NUMBER.exec(d.slice(i));
+            if (!m)
+                throw new Error(`path: unreadable number at ${i}`);
+            token = m[0];
+            i += token.length;
+        }
+        const axis = AXIS[upper][slot];
+        if (axis)
+            emitScaled(String(Number.parseFloat(token) * (axis === "x" ? sx : sy)));
+        else
+            out += token;
+        argIndex++;
+        copySeparators();
+    }
+    return out;
+}

package/src/png.d.ts

@@ -0,0 +1,23 @@
+import type { DecodedPixels } from "./decode.js";
+export type PngEffort = "fast" | "best";
+export type EncodePngOptions = {
+    effort?: PngEffort;
+};
+/**
+ * What a render is encoded as.
+ *
+ * `png` is lossless and is what anything read back, re-rendered or printed
+ * wants. `webp` is Skia's lossy encoder — roughly a quarter of the bytes on
+ * card artwork, for a picture a browser displays and nothing reads back.
+ * `jpeg` is what photos are exchanged as; it has no alpha, so the frame is
+ * flattened over white first (see ./jpeg).
+ */
+export type EncodeFormat = "png" | "webp" | "jpeg";
+export type EncodeOptions = EncodePngOptions & {
+    format?: EncodeFormat;
+    quality?: number;
+};
+export declare const DEFAULT_WEBP_QUALITY = 90;
+export declare const DEFAULT_JPEG_QUALITY = 90;
+export declare function encodePng(pixels: Uint8Array, width: number, height: number, opts?: EncodePngOptions): Promise<Uint8Array>;
+export declare function encodeDecodedPng(decoded: DecodedPixels, opts?: EncodePngOptions): Promise<Uint8Array>;

package/src/png.js

@@ -0,0 +1,189 @@
+export const DEFAULT_WEBP_QUALITY = 90;
+export const DEFAULT_JPEG_QUALITY = 90;
+// Encode RGBA8888 pixels (row-major, length width·height·4) as a PNG.
+export async function encodePng(pixels, width, height, opts) {
+    if (width <= 0 || height <= 0)
+        throw new Error("encodePng: empty image");
+    const expected = width * height * 4;
+    if (pixels.length < expected) {
+        throw new Error(`encodePng: expected ${expected} bytes of RGBA, got ${pixels.length}`);
+    }
+    // A fully opaque frame spends a byte per pixel on an alpha channel that says
+    // nothing — but dropping it is not always the smaller stream (long runs of an
+    // identical RGBA pixel compress better than the same runs in RGB), so it is a
+    // candidate rather than a rule.
+    const layouts = isOpaque(pixels, expected)
+        ? [{ bytes: pixels, channels: 4 }, rgbLayout(pixels, width, height)]
+        : [{ bytes: pixels, channels: 4 }];
+    const filters = opts?.effort === "best" ? [false, true] : [false];
+    const plans = layouts.flatMap((layout) => filters.map((adaptive) => ({ layout, adaptive })));
+    const streams = await Promise.all(plans.map((p) => deflate(filterRows(p.layout.bytes, width, height, p.layout.channels, p.adaptive))));
+    let best = 0;
+    for (let i = 1; i < streams.length; i++) {
+        if (streams[i].length < streams[best].length)
+            best = i;
+    }
+    return assemble(streams[best], width, height, plans[best].layout.channels);
+}
+// Read a frame's pixels straight out of a decode and encode them. The pairing
+// the callers actually want: decodePixels → encodePng.
+export function encodeDecodedPng(decoded, opts) {
+    return encodePng(new Uint8Array(decoded.data), decoded.width, decoded.height, opts);
+}
+function isOpaque(pixels, length) {
+    for (let i = 3; i < length; i += 4)
+        if (pixels[i] !== 255)
+            return false;
+    return true;
+}
+function rgbLayout(pixels, width, height) {
+    const out = new Uint8Array(width * height * 3);
+    for (let src = 0, dst = 0; dst < out.length; src += 4, dst += 3) {
+        out[dst] = pixels[src];
+        out[dst + 1] = pixels[src + 1];
+        out[dst + 2] = pixels[src + 2];
+    }
+    return { bytes: out, channels: 3 };
+}
+// Prefix each scanline with its filter type (PNG spec §6). `adaptive` picks the
+// type per row by the standard minimum-sum-of-absolute-differences heuristic;
+// otherwise every row is type 0, the bytes as they are.
+function filterRows(bytes, width, height, channels, adaptive) {
+    const stride = width * channels;
+    const out = new Uint8Array((stride + 1) * height);
+    if (!adaptive) {
+        for (let y = 0; y < height; y++) {
+            out[y * (stride + 1)] = 0;
+            out.set(bytes.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
+        }
+        return out;
+    }
+    const candidate = new Uint8Array(stride);
+    const chosen = new Uint8Array(stride);
+    for (let y = 0; y < height; y++) {
+        const row = bytes.subarray(y * stride, (y + 1) * stride);
+        const prev = y > 0 ? bytes.subarray((y - 1) * stride, y * stride) : null;
+        let bestType = 0;
+        let bestScore = Number.POSITIVE_INFINITY;
+        for (let type = 0; type <= 4; type++) {
+            let score = 0;
+            for (let i = 0; i < stride; i++) {
+                const a = i >= channels ? row[i - channels] : 0;
+                const b = prev ? prev[i] : 0;
+                const c = prev && i >= channels ? prev[i - channels] : 0;
+                const v = type === 0
+                    ? row[i]
+                    : type === 1
+                        ? row[i] - a
+                        : type === 2
+                            ? row[i] - b
+                            : type === 3
+                                ? row[i] - ((a + b) >> 1)
+                                : row[i] - paeth(a, b, c);
+                candidate[i] = v & 0xff;
+                // Signed magnitude: bytes near zero are what compresses.
+                score += Math.abs((candidate[i] << 24) >> 24);
+            }
+            if (score < bestScore) {
+                bestScore = score;
+                bestType = type;
+                chosen.set(candidate);
+            }
+        }
+        out[y * (stride + 1)] = bestType;
+        out.set(chosen, y * (stride + 1) + 1);
+    }
+    return out;
+}
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc)
+        return a;
+    return pb <= pc ? b : c;
+}
+// zlib-wrapped deflate, which is what an IDAT holds — "deflate-raw" would be
+// missing the two-byte header the spec requires.
+//
+// Driven through the stream's own reader/writer rather than Blob.stream() or
+// Response: those are DOM conveniences a test environment (jsdom) may only half
+// implement, and this needs nothing but the compression stream itself. The write
+// is deliberately not awaited before reading starts — a large frame fills the
+// stream's queue, and waiting for the write to settle first would deadlock.
+async function deflate(bytes) {
+    const cs = new CompressionStream("deflate");
+    const writer = cs.writable.getWriter();
+    const written = writer
+        .write(bytes)
+        .then(() => writer.close());
+    const reader = cs.readable.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+        total += value.length;
+    }
+    await written;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.length;
+    }
+    return out;
+}
+const PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+function assemble(idat, width, height, channels) {
+    const ihdr = new Uint8Array(13);
+    const view = new DataView(ihdr.buffer);
+    view.setUint32(0, width);
+    view.setUint32(4, height);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = channels === 4 ? 6 : 2; // colour type: RGBA / RGB
+    // 10..12: compression 0, filter 0, interlace 0 — the only values PNG defines.
+    const chunks = [
+        chunk("IHDR", ihdr),
+        chunk("IDAT", idat),
+        chunk("IEND", new Uint8Array(0)),
+    ];
+    const size = PNG_SIGNATURE.length + chunks.reduce((n, c) => n + c.length, 0);
+    const png = new Uint8Array(size);
+    png.set(PNG_SIGNATURE, 0);
+    let offset = PNG_SIGNATURE.length;
+    for (const c of chunks) {
+        png.set(c, offset);
+        offset += c.length;
+    }
+    return png;
+}
+function chunk(type, data) {
+    const out = new Uint8Array(12 + data.length);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, data.length);
+    for (let i = 0; i < 4; i++)
+        out[4 + i] = type.charCodeAt(i);
+    out.set(data, 8);
+    view.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+    return out;
+}
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}

package/src/resolve-layout.d.ts

@@ -0,0 +1,9 @@
+import type { Node } from "./node.js";
+import type { MeasureText } from "./text-types.js";
+import type { Size } from "./types.js";
+export declare function resolveLayout(root: Node, opts: {
+    measure: MeasureText;
+}): Node;
+/** The axis-aligned box a turned node covers — what its container has to make
+ *  room for. Identity for an unrotated node, so nothing changes for one. */
+export declare function rotatedFootprint(size: Size, rotation: number | undefined): Size;