freshcoat 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,17 @@
+freshcoat
+Copyright 2026 Dotside Studios
+
+This product includes software developed by Dotside Studios.
+
+This package bundles the following fonts for its tests and conformance suite,
+each under the SIL Open Font License 1.1 and not under the Apache License:
+
+  tests/fonts/Geist-Regular.ttf
+    Copyright 2024 The Geist Project Authors
+    (https://github.com/vercel/geist-font)
+    License: tests/fonts/Geist-OFL.txt
+
+  tests/fonts/VendSans-Variable-latin.woff2
+    Copyright 2025 The Vend Sans Project Authors
+    (https://github.com/ktkm/Vend-Sans)
+    License: tests/fonts/VendSans-OFL.txt

package/README.md

@@ -0,0 +1,110 @@
+# freshcoat
+
+The 2D rendering engine behind [Freshcoat](../../README.md), named
+`freshcoat` in the workspace. It lays out a scene graph,
+shapes text and paints with CanvasKit (Skia compiled to WASM).
+
+Use it directly when your application supplies its own scene: previews,
+generated images or an interactive canvas. For `.coat` templates and field
+substitution, start with [`@freshcoat/coatfile`](../coatfile), which compiles
+templates into engine nodes.
+
+The scene and command types are independent of the backend; the supplied
+painter uses CanvasKit. Browser and headless environments share that paint
+path. Template fields, variants and frame selection belong to coatfile;
+card-printer correction policy belongs to
+[`@freshcoat/for-print`](../for-print).
+
+## Quick start
+
+With an initialized CanvasKit instance (`ck`), render a scene offscreen:
+
+```ts
+import type { RectNode } from "freshcoat";
+import { renderSceneToPng } from "freshcoat/headless";
+
+const root: RectNode = {
+  kind: "rect",
+  pos: { x: 0, y: 0 },
+  size: { width: 640, height: 360 },
+  fills: [{ kind: "solid", color: "#1f6fe8" }],
+};
+
+const result = await renderSceneToPng(root, { width: 640, height: 360, ck });
+// result.bytes — PNG bytes by default; result.warnings — paint diagnostics
+```
+
+You supply CanvasKit initialization and the WASM file location for your host.
+For text, also supply a `fonts` map of family names to font byte arrays; the
+helper derives font metrics and creates the Paragraph text engine.
+
+## Node IR
+
+Eight node kinds — `rect | ellipse | path | image | bitmap | text | group |
+mask` — describe shapes, assets, text and composition. Nodes share positioning
+and compositing properties, with fills, strokes and other options appropriate
+to each kind. Groups support flex and grid layout.
+
+`compileScene()` lowers a node tree to the flat `Command[]` list the painter
+executes. Use this lower-level path when you need to inspect commands or keep
+a runtime alive across renders. The types in [`src/node.ts`](src/node.ts)
+define the scene model.
+
+```ts
+import { compileScene } from "freshcoat";
+import { createHeadlessEnv } from "freshcoat/headless";
+
+const commands = compileScene(root, { width, height, textEngine });
+const env = createHeadlessEnv({ fonts });
+const result = await env.paint(commands, ck);
+```
+
+## Painting and text
+
+The supplied text engine uses CanvasKit Paragraph for layout and shaping,
+keeping measurement and painting on the same text implementation. On the
+lower-level path, pass a `textEngine` to resolve layout and unbaked text, or
+supply a scene with resolved geometry and baked text.
+
+Gradients, masks, blend modes and per-layer `Adjust` (color matrix, lookup
+table and sharpening) are engine operations. `FrameFinish` applies operations
+after the whole scene is composited. The engine implements these operations;
+the caller decides when and where to use them.
+
+## Subpaths
+
+The barrel stays free of DOM and WASM weight; the paint target lives on its
+own subpath.
+
+| Subpath | What it is |
+|---|---|
+| `freshcoat` | node types, `compileScene`, layout, adjust and export-scale math |
+| `freshcoat/browser` | a runtime backing a live DOM canvas — the editor's preview |
+| `freshcoat/headless` | offscreen painting to PNG, napi-free — server previews, OG images |
+| `freshcoat/runtime` | the backend seam: `Painter` and `makeRuntime` |
+| `freshcoat/path` | SVG path data parsing and maths |
+
+## Staying warm
+
+For repeated renders, reuse a paint runtime with `createPaintCache` and a
+text engine wrapped by `memoizeTextEngine`. The paint cache retains the
+surface, font provider and decoded images; the text cache reuses unchanged
+paragraph layouts. Studio's render session uses both. See
+[Studio performance](../../apps/editor/docs/performance.md) for historical
+integration benchmarks and their conditions.
+
+For exports, `exportPixelSize` resolves density within
+`MAX_EXPORT_DIMENSION`. The headless runtime encodes PNG by default, with
+JPEG and WebP available through its `encode` options. Export scale changes
+the output pixel dimensions; supersampling renders at a higher density and
+reduces to the requested output size.
+
+## Conformance
+
+From this package directory, `bun run conformance` reports the golden-image
+suite, and `bun run conformance:regen` authors cases and regenerates goldens.
+
+## License
+
+Apache-2.0, see [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE). Part of
+[Freshcoat](../../README.md).

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "freshcoat",
+  "version": "0.1.0",
+  "description": "A composable 2D scene renderer powered by CanvasKit and Skia",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotside-studios/freshcoat.git",
+    "directory": "packages/engine"
+  },
+  "type": "module",
+  "private": false,
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "fixtures",
+    "schema",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./src/browser.d.ts",
+      "import": "./src/browser.js",
+      "default": "./src/browser.js"
+    },
+    "./headless": {
+      "types": "./src/headless.d.ts",
+      "import": "./src/headless.js",
+      "default": "./src/headless.js"
+    },
+    "./path": {
+      "types": "./src/path-data.d.ts",
+      "import": "./src/path-data.js",
+      "default": "./src/path-data.js"
+    },
+    "./runtime": {
+      "types": "./src/runtime.d.ts",
+      "import": "./src/runtime.js",
+      "default": "./src/runtime.js"
+    }
+  }
+}

package/src/adjust.d.ts

@@ -0,0 +1,18 @@
+import type { Adjust, AdjustLut, AdjustLut3d } from "./types.js";
+export type ColorMatrix = number[];
+export declare function identityColorMatrix(): ColorMatrix;
+export declare function concatColorMatrix(outer: ColorMatrix, inner: ColorMatrix): ColorMatrix;
+export declare function saturationMatrix(s: number): ColorMatrix;
+export declare function contrastMatrix(c: number): ColorMatrix;
+export declare function brightnessMatrix(k: number): ColorMatrix;
+export declare function gammaLut(gamma: number): AdjustLut;
+export declare function identityLut3d(size: number): AdjustLut3d;
+export type AdjustOptions = {
+    saturation?: number;
+    contrast?: number;
+    brightness?: number;
+    gamma?: number;
+    sharpen?: number;
+    preserveHue?: boolean;
+};
+export declare function buildAdjust(o: AdjustOptions): Adjust;

package/src/adjust.js

@@ -0,0 +1,153 @@
+// Generic, domain-neutral per-layer color/tone adjustment — freshcoat's
+// vocabulary for "transform this layer's pixels as it composites", the same way
+// `opacity`, `blendMode`, and `blur` already are. It knows the MATH (color
+// matrix, per-channel curve, sharpen), never the INTENT: color correction,
+// theming, accessibility contrast, and preview effects all drive the same
+// primitive. A consumer maps its own domain policy down to an `Adjust`; freshcoat
+// applies it without knowing why.
+//
+// The primitive is the closure of per-pixel color transforms: a 4×5 color matrix
+// (cross-channel — saturation/brightness/contrast) applied FIRST, then a
+// per-channel LUT (nonlinear curves — gamma), matching SVG's
+// feColorMatrix-then-feComponentTransfer ordering. `sharpen` is a spatial
+// post-filter, a sibling of `blur`. Every field is optional; absent = identity.
+//
+// The matrix follows Skia's SkColorMatrix convention: 20 floats, row-major RGBA
+// rows, and the 5th (translation) column expressed as a fraction of full scale
+// ([0,1]), NOT 0–255.
+// Rec.709 luma coefficients — the standard luminance weights used to keep a
+// saturation change perceptually neutral.
+const LUMA_R = 0.2126;
+const LUMA_G = 0.7152;
+const LUMA_B = 0.0722;
+// Contrast pivots on the 8-bit midpoint 128 (in 0–255 space); normalized for the
+// color matrix that is 128/255, not 0.5.
+const PIVOT = 128 / 255;
+export function identityColorMatrix() {
+    // biome-ignore format: matrix rows read clearer aligned
+    return [
+        1, 0, 0, 0, 0,
+        0, 1, 0, 0, 0,
+        0, 0, 1, 0, 0,
+        0, 0, 0, 1, 0,
+    ];
+}
+// concat(outer, inner): the matrix that applies `inner` first, then `outer` — so
+// concat(contrast, saturation) saturates then contrasts. Both are 4×5 affine
+// color matrices; we extend each to 5×5 with an implicit [0,0,0,0,1] last row and
+// multiply outer · innerExt.
+export function concatColorMatrix(outer, inner) {
+    const out = new Array(20).fill(0);
+    for (let row = 0; row < 4; row++) {
+        for (let col = 0; col < 5; col++) {
+            let sum = 0;
+            for (let k = 0; k < 4; k++) {
+                sum += outer[row * 5 + k] * inner[k * 5 + col];
+            }
+            // The extended 5th row of `inner` is [0,0,0,0,1], so it contributes only
+            // to the bias (col 4) via outer's own bias term.
+            if (col === 4)
+                sum += outer[row * 5 + 4];
+            out[row * 5 + col] = sum;
+        }
+    }
+    return out;
+}
+// Saturation as a color matrix: gray + s·(channel − gray), gray = luma. s=1 is
+// identity, s=0 fully desaturates, s>1 boosts.
+export function saturationMatrix(s) {
+    const ir = (1 - s) * LUMA_R;
+    const ig = (1 - s) * LUMA_G;
+    const ib = (1 - s) * LUMA_B;
+    // biome-ignore format: matrix rows read clearer aligned
+    return [
+        ir + s, ig, ib, 0, 0,
+        ir, ig + s, ib, 0, 0,
+        ir, ig, ib + s, 0, 0,
+        0, 0, 0, 1, 0,
+    ];
+}
+// Contrast about the 128/255 pivot: v' = c·(v − pivot) + pivot.
+export function contrastMatrix(c) {
+    const b = PIVOT * (1 - c);
+    // biome-ignore format: matrix rows read clearer aligned
+    return [
+        c, 0, 0, 0, b,
+        0, c, 0, 0, b,
+        0, 0, c, 0, b,
+        0, 0, 0, 1, 0,
+    ];
+}
+// Brightness as a straight multiplier (v' = v·k); identity at k=1.
+export function brightnessMatrix(k) {
+    // biome-ignore format: matrix rows read clearer aligned
+    return [
+        k, 0, 0, 0, 0,
+        0, k, 0, 0, 0,
+        0, 0, k, 0, 0,
+        0, 0, 0, 1, 0,
+    ];
+}
+// Per-channel gamma curve as a 256-entry LUT: out = round(255·(i/255)^gamma),
+// clamped. r/g/b share one table.
+export function gammaLut(gamma) {
+    const table = new Uint8Array(256);
+    for (let i = 0; i < 256; i++) {
+        const v = Math.round(255 * (i / 255) ** gamma);
+        table[i] = v < 0 ? 0 : v > 255 ? 255 : v;
+    }
+    return { r: table, g: table, b: table };
+}
+// An identity RGB cube, useful as a starting point for an authored or measured
+// device transform. The table format is shared with Adjust.lut3d (r-fast RGB
+// triplets), deliberately independent of any print/profile vocabulary.
+export function identityLut3d(size) {
+    if (!Number.isInteger(size) || size < 2) {
+        throw new Error("identityLut3d: size must be an integer of at least 2");
+    }
+    const data = new Uint8Array(size * size * size * 3);
+    const level = (i) => Math.round((i / (size - 1)) * 255);
+    for (let b = 0; b < size; b++) {
+        for (let g = 0; g < size; g++) {
+            for (let r = 0; r < size; r++) {
+                const at = ((b * size + g) * size + r) * 3;
+                data[at] = level(r);
+                data[at + 1] = level(g);
+                data[at + 2] = level(b);
+            }
+        }
+    }
+    return { size, data };
+}
+const isMatrixIdentity = (m) => {
+    const id = identityColorMatrix();
+    for (let i = 0; i < 20; i++)
+        if (Math.abs(m[i] - id[i]) > 1e-9)
+            return false;
+    return true;
+};
+// Build an `Adjust` from semantic knobs. Cross-channel/linear ops fold into one
+// color matrix, applied in order (saturation → contrast → brightness); gamma
+// becomes the LUT applied after; sharpen passes through. Fields that are at their
+// identity value are omitted, so `buildAdjust({})` is `{}` (a no-op).
+export function buildAdjust(o) {
+    let m = identityColorMatrix();
+    if (o.saturation !== undefined && o.saturation !== 1)
+        m = concatColorMatrix(saturationMatrix(o.saturation), m);
+    if (o.contrast !== undefined && o.contrast !== 1)
+        m = concatColorMatrix(contrastMatrix(o.contrast), m);
+    if (o.brightness !== undefined && o.brightness !== 1)
+        m = concatColorMatrix(brightnessMatrix(o.brightness), m);
+    const adjust = {};
+    if (!isMatrixIdentity(m)) {
+        adjust.colorMatrix = m;
+        // Only a matrix leaves the range, so the mode is meaningless without one.
+        if (o.preserveHue)
+            adjust.gamut = "preserve-hue";
+    }
+    if (o.gamma !== undefined && o.gamma !== 1)
+        adjust.lut = gammaLut(o.gamma);
+    if (o.sharpen !== undefined && o.sharpen > 0)
+        adjust.sharpen = o.sharpen;
+    return adjust;
+}

package/src/approx-layout.d.ts

@@ -0,0 +1,2 @@
+import type { TextEngine } from "./text-engine.js";
+export declare const approxEngine: TextEngine;

package/src/approx-layout.js

@@ -0,0 +1,91 @@
+// Mean glyph advance as a fraction of font size — a serviceable stand-in for a
+// proportional font's average character width.
+const CHAR_W = 0.5;
+const SHRINK_FLOOR_PX = 8;
+function collapse(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function advance(text, size, letterSpacing = 0) {
+    const n = [...text].length;
+    if (n === 0)
+        return 0;
+    return n * size * CHAR_W + Math.max(0, n - 1) * letterSpacing;
+}
+// Proportional char-count wrap: split into ceil(natural / maxWidth) even chunks.
+// Bars, not glyphs, are drawn from this, so mid-word splits are invisible.
+function wrap(text, size, letterSpacing, maxWidth) {
+    const norm = collapse(text);
+    const chars = [...norm];
+    const natural = advance(norm, size, letterSpacing);
+    if (natural <= maxWidth || chars.length <= 1) {
+        return [{ text: norm, width: natural }];
+    }
+    const lineCount = Math.max(1, Math.ceil(natural / maxWidth));
+    const perLine = Math.ceil(chars.length / lineCount);
+    const lines = [];
+    for (let i = 0; i < chars.length; i += perLine) {
+        const chunk = chars.slice(i, i + perLine).join("");
+        lines.push({
+            text: chunk,
+            width: Math.min(advance(chunk, size, letterSpacing), maxWidth),
+        });
+    }
+    return lines;
+}
+const measureText = (text, font, maxWidth) => {
+    const lineHeightPx = font.size * font.lineHeight;
+    if (text.length === 0)
+        return { width: 0, height: lineHeightPx };
+    if (maxWidth === null) {
+        return {
+            width: advance(collapse(text), font.size, font.letterSpacing ?? 0),
+            height: lineHeightPx,
+        };
+    }
+    const lines = wrap(text, font.size, font.letterSpacing ?? 0, maxWidth);
+    const width = lines.reduce((max, l) => Math.max(max, l.width), 0);
+    return { width, height: Math.max(1, lines.length) * lineHeightPx };
+};
+const measureSpanWidth = (text, font) => advance(collapse(text), font.size, font.letterSpacing ?? 0);
+const layoutText = (input) => {
+    const lh = input.lineHeight;
+    const ls = input.font.letterSpacing ?? 0;
+    const once = (size) => {
+        const lines = wrap(input.value, size, ls, input.maxWidth);
+        return {
+            lines,
+            totalHeight: lines.length * size * lh,
+            effectiveFontSize: size,
+        };
+    };
+    if (input.fit !== "shrink" || 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;
+        }
+    }
+    return best
+        ? { ...best, shrinkApplied: true }
+        : { ...once(SHRINK_FLOOR_PX), shrinkApplied: true };
+};
+// compile's default engine. No layoutInline — compile falls back to
+// independent-span single-line placement, which is fine for the skeleton.
+export const approxEngine = {
+    measureText,
+    measureSpanWidth,
+    layoutText,
+};

package/src/bake-text.d.ts

@@ -0,0 +1,12 @@
+import type { TextNode } from "./node.js";
+import type { TextEngine } from "./text-engine.js";
+import type { BakedTextLayout, ClipOutset, FontVMetrics, ResolvedFont } from "./types.js";
+export type BakeTextOptions = {
+    textEngine: TextEngine;
+    leadingTrim?: boolean;
+    fontMetrics?: Record<string, FontVMetrics>;
+    deviceScale?: number;
+};
+export declare function resolveLeadingTrim(node: TextNode, fallback?: boolean): boolean;
+export declare function textClipOutset(font: ResolvedFont, leadingTrim: boolean, metricsMap?: Record<string, FontVMetrics>): ClipOutset;
+export declare function bakeText(node: TextNode, opts: BakeTextOptions): BakedTextLayout;