textpour 0.1.0

package/dist/src/glyph-region.js

@@ -0,0 +1,36 @@
+/**
+ * Glyph-outline region — the opentype.js seam.
+ *
+ * This module keeps `opentype.js` (and any font-loading library) entirely out of the
+ * `textpour` package. The caller is responsible for loading a font and converting a
+ * glyph to SVG path data; this module then wraps the path into a geometry `Region`.
+ *
+ * Typical caller-side usage with opentype.js:
+ * ```ts
+ * import opentype from 'opentype.js';
+ * import { glyphToRegion } from 'textpour';
+ *
+ * const font = await opentype.load('MyFont.otf');
+ * const glyph = font.charToGlyph('A');
+ * const pathData = glyph.getPath(x, y, fontSize).toPathData();
+ * const region = glyphToRegion(pathData);
+ * ```
+ *
+ * Note: opentype.js renders glyph paths with Y-axis flipped relative to CSS (glyph
+ * coordinates increase upward). Callers should pass a negative `y` origin or apply a
+ * scaling transform via `getPath(x, y, fontSize)` to position the glyph in CSS px
+ * coordinates before calling `toPathData()`.
+ */
+import { svgPathToRegion } from './outline-region.js';
+/**
+ * Convert SVG path data from a glyph outline into a `Region`.
+ *
+ * Pass `glyph.getPath(x, y, fontSize).toPathData()` from opentype.js here.
+ * The kernel remains dependency-free — opentype.js stays on the caller's side.
+ *
+ * @param pathData SVG path `d` attribute string (M/L/C/Q/Z commands).
+ * @param opts     Optional flattening options (default `steps` = 24 per curve segment).
+ */
+export function glyphToRegion(pathData, opts) {
+    return svgPathToRegion(pathData, opts);
+}

package/dist/src/hyphen.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Conservative heuristic soft-hyphen insertion.
+ *
+ * IMPORTANT: this is a HEURISTIC, NOT a dictionary hyphenator. It does not consult any word list,
+ * pronunciation data, or language-specific hyphenation rules. It uses simple vowel→consonant
+ * boundary detection for Latin text only. For professional-quality hyphenation, use a dictionary
+ * hyphenator (e.g. Hyphenopoly / hypher) and pre-process your text before calling `insertSoftHyphens`.
+ *
+ * The `locale` option is reserved for future use (it is passed to `Intl.Segmenter` but has no effect
+ * on the heuristic itself, which is purely structural for now).
+ *
+ * INVARIANT: `insertSoftHyphens(t).replaceAll('­', '') === t` for all string inputs.
+ */
+export interface InsertSoftHyphensOptions {
+    /** Minimum word length (chars) before inserting any soft hyphens. Default: 8. */
+    minWordLength?: number;
+    /** Never insert within the first N characters of a word. Default: 3. */
+    minPrefix?: number;
+    /** Never insert within the last N characters of a word. Default: 3. */
+    minSuffix?: number;
+    /** Reserved for future use — passed to `Intl.Segmenter`. Default: undefined (host locale). */
+    locale?: string;
+}
+/**
+ * Insert U+00AD (soft hyphen) at heuristic break points in long Latin words.
+ *
+ * Only Latin alphabetic words (`/^[A-Za-z]+$/`) of at least `minWordLength` characters are
+ * processed. Within such words, soft hyphens are placed at vowel→consonant boundaries, never
+ * within the first `minPrefix` or last `minSuffix` characters, and never two in a row. All other
+ * text (numbers, punctuation, CJK, emoji, short words) passes through unchanged.
+ *
+ * @param text    The input string.
+ * @param opts    Optional configuration (see {@link InsertSoftHyphensOptions}).
+ * @returns       A copy of `text` with soft hyphens inserted. Stripping all U+00AD restores
+ *                the original: `result.replaceAll('­', '') === text`.
+ */
+export declare function insertSoftHyphens(text: string, opts?: InsertSoftHyphensOptions): string;

package/dist/src/hyphen.js

@@ -0,0 +1,83 @@
+/**
+ * Conservative heuristic soft-hyphen insertion.
+ *
+ * IMPORTANT: this is a HEURISTIC, NOT a dictionary hyphenator. It does not consult any word list,
+ * pronunciation data, or language-specific hyphenation rules. It uses simple vowel→consonant
+ * boundary detection for Latin text only. For professional-quality hyphenation, use a dictionary
+ * hyphenator (e.g. Hyphenopoly / hypher) and pre-process your text before calling `insertSoftHyphens`.
+ *
+ * The `locale` option is reserved for future use (it is passed to `Intl.Segmenter` but has no effect
+ * on the heuristic itself, which is purely structural for now).
+ *
+ * INVARIANT: `insertSoftHyphens(t).replaceAll('­', '') === t` for all string inputs.
+ */
+const SOFT_HYPHEN = '­';
+const VOWELS = new Set(['a', 'e', 'i', 'o', 'u', 'A', 'E', 'I', 'O', 'U']);
+const LATIN_WORD = /^[A-Za-z]+$/;
+/**
+ * Insert U+00AD (soft hyphen) at heuristic break points in long Latin words.
+ *
+ * Only Latin alphabetic words (`/^[A-Za-z]+$/`) of at least `minWordLength` characters are
+ * processed. Within such words, soft hyphens are placed at vowel→consonant boundaries, never
+ * within the first `minPrefix` or last `minSuffix` characters, and never two in a row. All other
+ * text (numbers, punctuation, CJK, emoji, short words) passes through unchanged.
+ *
+ * @param text    The input string.
+ * @param opts    Optional configuration (see {@link InsertSoftHyphensOptions}).
+ * @returns       A copy of `text` with soft hyphens inserted. Stripping all U+00AD restores
+ *                the original: `result.replaceAll('­', '') === text`.
+ */
+export function insertSoftHyphens(text, opts = {}) {
+    const minWordLength = opts.minWordLength ?? 8;
+    const minPrefix = opts.minPrefix ?? 3;
+    const minSuffix = opts.minSuffix ?? 3;
+    const locale = opts.locale;
+    const segmenter = new Intl.Segmenter(locale, { granularity: 'word' });
+    const segments = segmenter.segment(text);
+    let result = '';
+    for (const seg of segments) {
+        const word = seg.segment;
+        if (seg.isWordLike &&
+            LATIN_WORD.test(word) &&
+            word.length >= minWordLength) {
+            result += hyphenateWord(word, minPrefix, minSuffix);
+        }
+        else {
+            result += word;
+        }
+    }
+    return result;
+}
+/**
+ * Insert soft hyphens into a single Latin word at vowel→consonant boundaries.
+ * Never within first `minPrefix` or last `minSuffix` chars; never two in a row.
+ */
+function hyphenateWord(word, minPrefix, minSuffix) {
+    const len = word.length;
+    // The zone where we may insert: [minPrefix, len - minSuffix)
+    // If that range is empty, return unchanged.
+    if (minPrefix + minSuffix >= len)
+        return word;
+    let out = '';
+    let lastInsert = -2; // index of last soft-hyphen insertion (prevent consecutive)
+    for (let i = 0; i < len; i++) {
+        out += word[i];
+        // Candidate position is AFTER character i, i.e. between i and i+1.
+        // Must be within the allowed zone: i+1 >= minPrefix AND i+1 <= len - minSuffix
+        // i.e. i >= minPrefix - 1 AND i < len - minSuffix
+        const afterI = i + 1;
+        if (afterI >= minPrefix &&
+            afterI <= len - minSuffix &&
+            i !== lastInsert + 1 // no two in a row
+        ) {
+            const cur = word[i];
+            const next = word[i + 1];
+            // Vowel→consonant boundary: current is a vowel, next is a consonant.
+            if (next !== undefined && VOWELS.has(cur) && !VOWELS.has(next)) {
+                out += SOFT_HYPHEN;
+                lastInsert = i;
+            }
+        }
+    }
+    return out;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,19 @@
+export type { Interval, Bounds, MultiSpan, Align, FlowOptions, PlacedLine, FlowResult, WordSegment, } from './types.js';
+export { normalize, unionSpans, intersectSpans, subtractSpans, RectRegion, CircleRegion, EllipseRegion, PolygonRegion, CompositeRegion, rect, circle, ellipse, polygon, union, intersect, subtract, } from './region.js';
+export type { Region } from './region.js';
+export { MonospaceLineSource } from './line-source.js';
+export type { Line, LineSource, MonoCursor } from './line-source.js';
+export { PretextLineSource } from './pretext-source.js';
+export { buildPrefixWidths, xToGraphemeIndex, graphemeIndexToX, canvasMeasurer, } from './prefix-widths.js';
+export type { TextMeasurer } from './prefix-widths.js';
+export { shapeFlow, ShapeFlow } from './flow.js';
+export { balanceWidth, balancedFlow } from './balance.js';
+export { autoFit } from './auto-fit.js';
+export type { AutoFitOptions, AutoFitResult } from './auto-fit.js';
+export { insertSoftHyphens } from './hyphen.js';
+export type { InsertSoftHyphensOptions } from './hyphen.js';
+export { Canvas2DRenderer, HtmlInCanvasRenderer, } from './renderer.js';
+export type { Renderer, Canvas2DLike, HtmlInCanvasTarget } from './renderer.js';
+export { svgPathToPolygon, svgPathToRegion, maskRegion } from './outline-region.js';
+export { glyphToRegion } from './glyph-region.js';
+export type { GlyphContour } from './glyph-region.js';

package/dist/src/index.js

@@ -0,0 +1,17 @@
+export { 
+// interval algebra
+normalize, unionSpans, intersectSpans, subtractSpans, 
+// region primitives
+RectRegion, CircleRegion, EllipseRegion, PolygonRegion, CompositeRegion, 
+// builders
+rect, circle, ellipse, polygon, union, intersect, subtract, } from './region.js';
+export { MonospaceLineSource } from './line-source.js';
+export { PretextLineSource } from './pretext-source.js';
+export { buildPrefixWidths, xToGraphemeIndex, graphemeIndexToX, canvasMeasurer, } from './prefix-widths.js';
+export { shapeFlow, ShapeFlow } from './flow.js';
+export { balanceWidth, balancedFlow } from './balance.js';
+export { autoFit } from './auto-fit.js';
+export { insertSoftHyphens } from './hyphen.js';
+export { Canvas2DRenderer, HtmlInCanvasRenderer, } from './renderer.js';
+export { svgPathToPolygon, svgPathToRegion, maskRegion } from './outline-region.js';
+export { glyphToRegion } from './glyph-region.js';

package/dist/src/line-source.d.ts

@@ -0,0 +1,46 @@
+import type { WordSegment } from './types.js';
+/** One line produced by a source, with cursors back into the source. */
+export interface Line<C> {
+    text: string;
+    width: number;
+    start: C;
+    end: C;
+    /** True when a soft hyphen (U+00AD) was chosen as the line-break point and a visible '-' was appended. */
+    softHyphenated?: boolean;
+    /**
+     * Per-word segments with x relative to the LINE LEFT (not canvas). Each x is the natural offset
+     * of the word from the start of the line; width does NOT include surrounding spaces. Populated by
+     * sources that can cheaply compute word offsets (e.g. MonospaceLineSource). When present and
+     * align==='justify', flow.ts replaces these relative x values with absolute canvas x positions
+     * on PlacedLine.words.
+     */
+    words?: WordSegment[];
+}
+export interface LineSource<C> {
+    /** The cursor at the very start of the text. */
+    start(): C;
+    /**
+     * Return the next line that fits within `maxWidth` starting from `cursor`,
+     * or null when the text is exhausted. Implementations MUST make progress
+     * (emit >= 1 grapheme) whenever text remains, even if maxWidth is tiny.
+     */
+    nextLine(cursor: C, maxWidth: number): Line<C> | null;
+}
+/** Cursor for the monospace source: an index into the grapheme array. */
+export interface MonoCursor {
+    i: number;
+}
+/**
+ * Deterministic, dependency-free source for unit tests and offline demos.
+ * Fixed advance width per grapheme, word-aware greedy wrapping with hard-break fallback.
+ * Supports U+00AD soft hyphens: unchosen soft hyphens are invisible (zero width); when a soft
+ * hyphen is chosen as the break point the displayed text gains a trailing '-' and softHyphenated=true.
+ * Not for production rendering — it ignores kerning, shaping, bidi, and real fonts.
+ */
+export declare class MonospaceLineSource implements LineSource<MonoCursor> {
+    private charWidth;
+    private graphemes;
+    constructor(text: string, charWidth?: number);
+    start(): MonoCursor;
+    nextLine(cursor: MonoCursor, maxWidth: number): Line<MonoCursor> | null;
+}

package/dist/src/line-source.js

@@ -0,0 +1,134 @@
+// The seam that decouples the shape-flow orchestrator from any specific text engine.
+// The orchestrator only knows LineSource, so it is testable in Node with no canvas/Pretext,
+// and the same seam lets an HTML-in-Canvas planner reuse the geometry without changes.
+/**
+ * Build a WordSegment array from a displayed text line for a monospace source.
+ * Scans for maximal non-space runs; x is the character-offset * charWidth (natural offset from
+ * the LINE LEFT), width is the run's character count * charWidth.
+ * The trailing '-' from a soft-hyphen break is considered part of its last word.
+ * Single-token lines get a one-element array.
+ */
+function monoWords(text, charWidth) {
+    const chars = Array.from(text);
+    const words = [];
+    let i = 0;
+    while (i < chars.length) {
+        if (chars[i] === ' ') {
+            i++;
+            continue;
+        }
+        const start = i;
+        while (i < chars.length && chars[i] !== ' ')
+            i++;
+        const run = chars.slice(start, i).join('');
+        words.push({ text: run, x: start * charWidth, width: run.length * charWidth });
+    }
+    return words;
+}
+const SOFT_HYPHEN = '­';
+/**
+ * Deterministic, dependency-free source for unit tests and offline demos.
+ * Fixed advance width per grapheme, word-aware greedy wrapping with hard-break fallback.
+ * Supports U+00AD soft hyphens: unchosen soft hyphens are invisible (zero width); when a soft
+ * hyphen is chosen as the break point the displayed text gains a trailing '-' and softHyphenated=true.
+ * Not for production rendering — it ignores kerning, shaping, bidi, and real fonts.
+ */
+export class MonospaceLineSource {
+    charWidth;
+    graphemes;
+    constructor(text, charWidth = 10) {
+        this.charWidth = charWidth;
+        this.graphemes = Array.from(text); // code-point granularity is sufficient for tests
+    }
+    start() {
+        return { i: 0 };
+    }
+    nextLine(cursor, maxWidth) {
+        const g = this.graphemes;
+        let i = cursor.i;
+        if (i >= g.length)
+            return null;
+        // Collapse leading spaces at the start of a line (browser-like).
+        // Leading soft hyphens are NOT collapsed — they are invisible but not whitespace.
+        while (i < g.length && g[i] === ' ')
+            i++;
+        if (i >= g.length)
+            return null;
+        // Discard any stray leading soft hyphens (invisible, zero-width).
+        while (i < g.length && g[i] === SOFT_HYPHEN)
+            i++;
+        if (i >= g.length)
+            return null;
+        const maxChars = Math.max(1, Math.floor(maxWidth / this.charWidth));
+        const lineStart = i;
+        // Walk forward, counting only VISIBLE characters (excluding soft hyphens).
+        // Track the latest break opportunity: space index OR soft-hyphen index.
+        // breakKind: 'space' means break before lastBreak, 'softhyphen' means break after it (append '-').
+        let end = i;
+        let visibleCount = 0;
+        let lastBreakEnd = -1; // source index AFTER the break (where next line starts)
+        let lastBreakKind = null;
+        while (end < g.length) {
+            const ch = g[end];
+            if (ch === SOFT_HYPHEN) {
+                // A soft hyphen is a break opportunity. If appending '-' would still fit, record it.
+                // The '-' counts as 1 visible char.
+                if (visibleCount + 1 <= maxChars) {
+                    lastBreakEnd = end + 1; // consume the soft hyphen
+                    lastBreakKind = 'softhyphen';
+                }
+                end++;
+                // Soft hyphen is NOT counted in visibleCount.
+                continue;
+            }
+            if (ch === ' ') {
+                // Space is a break opportunity (break BEFORE it, existing behavior).
+                lastBreakEnd = end;
+                lastBreakKind = 'space';
+            }
+            if (visibleCount >= maxChars) {
+                // Reached the limit — don't consume this character.
+                break;
+            }
+            visibleCount++;
+            end++;
+        }
+        // Determine if we stopped because we ran out of characters (exhausted) or hit the limit.
+        const hitLimit = end < g.length && g[end] !== ' ' && g[end] !== SOFT_HYPHEN;
+        // If we hit the limit mid-word and have an earlier break, back up to it.
+        if (hitLimit && lastBreakEnd > lineStart && lastBreakKind !== null) {
+            if (lastBreakKind === 'space') {
+                // Break before the space: end = space index, next line starts there.
+                const spaceIdx = lastBreakEnd;
+                const raw = g.slice(lineStart, spaceIdx).filter(c => c !== SOFT_HYPHEN).join('');
+                const text = raw.replace(/\s+$/u, '');
+                const width = Array.from(text).length * this.charWidth;
+                return { text, width, start: { i: lineStart }, end: { i: spaceIdx }, words: monoWords(text, this.charWidth) };
+            }
+            else {
+                // lastBreakKind === 'softhyphen'
+                // Break at/after the soft hyphen: append '-', next line starts after soft hyphen.
+                const raw = g.slice(lineStart, lastBreakEnd - 1).filter(c => c !== SOFT_HYPHEN).join('');
+                const text = raw + '-';
+                const width = Array.from(text).length * this.charWidth;
+                return { text, width, softHyphenated: true, start: { i: lineStart }, end: { i: lastBreakEnd }, words: monoWords(text, this.charWidth) };
+            }
+        }
+        // No overflow or no usable break — take everything up to `end`, strip soft hyphens.
+        // Guarantee at least 1 visible grapheme progress (skip all-soft-hyphen edge case).
+        if (end === lineStart) {
+            // All remaining chars from lineStart were soft hyphens with no visible char — force progress.
+            end = lineStart + 1;
+        }
+        const raw = g.slice(lineStart, end).filter(c => c !== SOFT_HYPHEN).join('');
+        const text = raw.replace(/\s+$/u, '');
+        // If text is empty but end advanced, we need to guarantee progress on the cursor.
+        if (text.length === 0) {
+            // Skip to end (all soft hyphens / spaces — shouldn't normally happen post the leading collapse).
+            const width = 0;
+            return { text: '', width, start: { i: lineStart }, end: { i: end } };
+        }
+        const width = Array.from(text).length * this.charWidth;
+        return { text, width, start: { i: lineStart }, end: { i: end }, words: monoWords(text, this.charWidth) };
+    }
+}

package/dist/src/outline-region.d.ts

@@ -0,0 +1,30 @@
+import type { Region } from './region.js';
+/**
+ * Parse a minimal subset of SVG path data into a flat array of [x, y] points.
+ *
+ * Supported commands: M/m, L/l, H/h, V/v, C/c, Q/q, Z/z (absolute + relative).
+ * Cubic (C) and quadratic (Q) Béziers are flattened with `opts.steps` subdivisions
+ * per segment (default 24).
+ *
+ * Multiple subpaths are concatenated (acceptable for even-odd polygon fill).
+ */
+export declare function svgPathToPolygon(d: string, opts?: {
+    steps?: number;
+}): Array<[number, number]>;
+/**
+ * Convenience: parse an SVG path string into a `Region` (via `PolygonRegion`, even-odd fill).
+ */
+export declare function svgPathToRegion(d: string, opts?: {
+    steps?: number;
+}): Region;
+/**
+ * Build a `Region` from a raster alpha mask.
+ *
+ * @param width     Pixel width of the mask grid.
+ * @param height    Pixel height of the mask grid.
+ * @param alpha     Row-major array of alpha values (`alpha[row * width + col]`).
+ * @param threshold Minimum alpha to count as "inside" (default 128, half-transparent).
+ * @param originX   X offset of the mask's top-left corner in canvas space (default 0).
+ * @param originY   Y offset of the mask's top-left corner in canvas space (default 0).
+ */
+export declare function maskRegion(width: number, height: number, alpha: Uint8ClampedArray | number[], threshold?: number, originX?: number, originY?: number): Region;

package/dist/src/outline-region.js

@@ -0,0 +1,255 @@
+import { polygon } from './region.js';
+// ---------------------------------------------------------------------------
+// SVG path tokenizer
+// ---------------------------------------------------------------------------
+/**
+ * Tokenize an SVG `d` attribute string into commands and numeric arguments.
+ * Handles: M/m L/l H/h V/v C/c Q/q Z/z (absolute + relative variants).
+ * Numbers may be delimited by whitespace, commas, or sign characters.
+ */
+function* tokenizePath(d) {
+    const re = /([MmLlHhVvCcQqZz])|([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)/g;
+    let m;
+    while ((m = re.exec(d)) !== null) {
+        if (m[1] !== undefined) {
+            yield m[1];
+        }
+        else if (m[2] !== undefined) {
+            yield parseFloat(m[2]);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// De Casteljau flattening helpers
+// ---------------------------------------------------------------------------
+/** Evaluate a cubic Bézier at parameter t. */
+function cubicBezier(p0, p1, p2, p3, t) {
+    const mt = 1 - t;
+    const mt2 = mt * mt;
+    const t2 = t * t;
+    return [
+        mt2 * mt * p0[0] + 3 * mt2 * t * p1[0] + 3 * mt * t2 * p2[0] + t2 * t * p3[0],
+        mt2 * mt * p0[1] + 3 * mt2 * t * p1[1] + 3 * mt * t2 * p2[1] + t2 * t * p3[1],
+    ];
+}
+/** Evaluate a quadratic Bézier at parameter t. */
+function quadBezier(p0, p1, p2, t) {
+    const mt = 1 - t;
+    return [
+        mt * mt * p0[0] + 2 * mt * t * p1[0] + t * t * p2[0],
+        mt * mt * p0[1] + 2 * mt * t * p1[1] + t * t * p2[1],
+    ];
+}
+// ---------------------------------------------------------------------------
+// SVG path flattener
+// ---------------------------------------------------------------------------
+/**
+ * Parse a minimal subset of SVG path data into a flat array of [x, y] points.
+ *
+ * Supported commands: M/m, L/l, H/h, V/v, C/c, Q/q, Z/z (absolute + relative).
+ * Cubic (C) and quadratic (Q) Béziers are flattened with `opts.steps` subdivisions
+ * per segment (default 24).
+ *
+ * Multiple subpaths are concatenated (acceptable for even-odd polygon fill).
+ */
+export function svgPathToPolygon(d, opts) {
+    const steps = opts?.steps ?? 24;
+    const pts = [];
+    const tokens = [...tokenizePath(d)];
+    let i = 0;
+    let cx = 0; // current x
+    let cy = 0; // current y
+    let subpathStartX = 0;
+    let subpathStartY = 0;
+    let cmd = '';
+    function nextNum() {
+        while (i < tokens.length && typeof tokens[i] === 'string')
+            i++;
+        if (i >= tokens.length)
+            throw new Error('SVG path: expected number');
+        return tokens[i++];
+    }
+    function addPoint(x, y) {
+        pts.push([x, y]);
+    }
+    while (i < tokens.length) {
+        const tok = tokens[i];
+        if (typeof tok === 'string') {
+            cmd = tok;
+            i++;
+        }
+        // Implicit line-to: after M, subsequent coords are L; after m, they are l.
+        const impliedCmd = cmd === 'M' ? 'L' : cmd === 'm' ? 'l' : cmd;
+        switch (cmd) {
+            case 'M':
+            case 'm': {
+                const x = nextNum();
+                const y = nextNum();
+                if (cmd === 'M') {
+                    cx = x;
+                    cy = y;
+                }
+                else {
+                    cx += x;
+                    cy += y;
+                }
+                subpathStartX = cx;
+                subpathStartY = cy;
+                addPoint(cx, cy);
+                // Switch to implied L/l for subsequent coordinate pairs.
+                cmd = cmd === 'M' ? 'L' : 'l';
+                break;
+            }
+            case 'L':
+            case 'l': {
+                const x = nextNum();
+                const y = nextNum();
+                if (impliedCmd === 'L') {
+                    cx = x;
+                    cy = y;
+                }
+                else {
+                    cx += x;
+                    cy += y;
+                }
+                addPoint(cx, cy);
+                break;
+            }
+            case 'H':
+            case 'h': {
+                const x = nextNum();
+                cx = cmd === 'H' ? x : cx + x;
+                addPoint(cx, cy);
+                break;
+            }
+            case 'V':
+            case 'v': {
+                const y = nextNum();
+                cy = cmd === 'V' ? y : cy + y;
+                addPoint(cx, cy);
+                break;
+            }
+            case 'C':
+            case 'c': {
+                const x1 = nextNum();
+                const y1 = nextNum();
+                const x2 = nextNum();
+                const y2 = nextNum();
+                const x = nextNum();
+                const y = nextNum();
+                const p0 = [cx, cy];
+                const p1 = cmd === 'C' ? [x1, y1] : [cx + x1, cy + y1];
+                const p2 = cmd === 'C' ? [x2, y2] : [cx + x2, cy + y2];
+                const p3 = cmd === 'C' ? [x, y] : [cx + x, cy + y];
+                for (let s = 1; s <= steps; s++) {
+                    addPoint(...cubicBezier(p0, p1, p2, p3, s / steps));
+                }
+                cx = p3[0];
+                cy = p3[1];
+                break;
+            }
+            case 'Q':
+            case 'q': {
+                const x1 = nextNum();
+                const y1 = nextNum();
+                const x = nextNum();
+                const y = nextNum();
+                const p0 = [cx, cy];
+                const p1 = cmd === 'Q' ? [x1, y1] : [cx + x1, cy + y1];
+                const p2 = cmd === 'Q' ? [x, y] : [cx + x, cy + y];
+                for (let s = 1; s <= steps; s++) {
+                    addPoint(...quadBezier(p0, p1, p2, s / steps));
+                }
+                cx = p2[0];
+                cy = p2[1];
+                break;
+            }
+            case 'Z':
+            case 'z': {
+                // Close path: line back to subpath start (add the close point so the polygon closes).
+                addPoint(subpathStartX, subpathStartY);
+                cx = subpathStartX;
+                cy = subpathStartY;
+                // Reset cmd so the next token is always read as a command.
+                cmd = '';
+                break;
+            }
+            default:
+                // Unknown command — skip to next command token.
+                i++;
+        }
+    }
+    return pts;
+}
+/**
+ * Convenience: parse an SVG path string into a `Region` (via `PolygonRegion`, even-odd fill).
+ */
+export function svgPathToRegion(d, opts) {
+    return polygon(svgPathToPolygon(d, opts));
+}
+// ---------------------------------------------------------------------------
+// Alpha-mask region
+// ---------------------------------------------------------------------------
+class MaskRegion {
+    width;
+    height;
+    alpha;
+    threshold;
+    originX;
+    originY;
+    bb;
+    constructor(width, height, alpha, threshold, originX, originY) {
+        this.width = width;
+        this.height = height;
+        this.alpha = alpha;
+        this.threshold = threshold ?? 128;
+        this.originX = originX ?? 0;
+        this.originY = originY ?? 0;
+        this.bb = {
+            minX: this.originX,
+            minY: this.originY,
+            maxX: this.originX + width,
+            maxY: this.originY + height,
+        };
+    }
+    spansAt(y) {
+        const row = Math.floor(y - this.originY);
+        if (row < 0 || row >= this.height)
+            return [];
+        const out = [];
+        let inRun = false;
+        let runStart = 0;
+        const { width, alpha, threshold, originX } = this;
+        for (let col = 0; col < width; col++) {
+            const inside = (alpha[row * width + col] ?? 0) >= threshold;
+            if (inside && !inRun) {
+                inRun = true;
+                runStart = col;
+            }
+            else if (!inside && inRun) {
+                out.push([originX + runStart, originX + col]);
+                inRun = false;
+            }
+        }
+        if (inRun) {
+            out.push([originX + runStart, originX + width]);
+        }
+        return out;
+    }
+    bounds() {
+        return this.bb;
+    }
+}
+/**
+ * Build a `Region` from a raster alpha mask.
+ *
+ * @param width     Pixel width of the mask grid.
+ * @param height    Pixel height of the mask grid.
+ * @param alpha     Row-major array of alpha values (`alpha[row * width + col]`).
+ * @param threshold Minimum alpha to count as "inside" (default 128, half-transparent).
+ * @param originX   X offset of the mask's top-left corner in canvas space (default 0).
+ * @param originY   Y offset of the mask's top-left corner in canvas space (default 0).
+ */
+export function maskRegion(width, height, alpha, threshold, originX, originY) {
+    return new MaskRegion(width, height, alpha, threshold, originX, originY);
+}