textpour 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beansint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# textpour
+
+A render-agnostic **text-geometry kernel** on top of
+[`@chenglou/pretext`](https://github.com/chenglou/pretext).
+
+- **Shape-flow**: pour text into arbitrary 2D regions — circles, polygons, holes, boolean
+  combinations, SVG paths, glyph outlines, and raster alpha masks — by routing Pretext's
+  line-breaking through per-row spans. (CSS `shape-inside` never shipped; this does it.)
+- **Typographic quality** (the moat): justification (`align: 'justify'`), soft-hyphenation,
+  balanced lines, auto-fit (binary-search font size), and conservative band sampling so glyphs
+  never poke outside tight curves.
+- **Cursor ↔ point mapping**: map pixel positions to exact grapheme positions and back, for
+  caret/hit-testing in custom-rendered text.
+- **Pluggable paint**: the kernel computes geometry; `Renderer`s paint it. Canvas2D works today;
+  an HTML-in-Canvas adapter (for high-fidelity, accessible, 3D-surface paint) is stubbed for later.
+
+The design bet is the **plan/paint split**: Pretext plans cheaply every frame (no DOM reflow); an
+expensive high-fidelity backend paints only when the plan changes.
+
+## Demo
+
+Text poured into a circle and a donut (multi-span), reflowing live as the region changes — the same
+prepared pass reused on every frame:
+
+![textpour demo: text flowing into a circle and a donut, reflowing live](assets/textpour-demo.gif)
+
+## Why not just Pretext?
+
+Pretext is the line-breaking and measurement engine — a very good one. It breaks lines at a width
+*you give it*, measures without DOM reflow, and its fuller API even does Knuth–Plass justification,
+syllable hyphenation, and "shrinkwrap" (`walkLineRanges`). It can already flow text past a floated
+image, because that's still **one rectangular width that varies by `y`**.
+
+What Pretext deliberately does **not** model is **2D geometry**. Its layout call is "one line, one
+width." textpour adds exactly that missing layer:
+
+- **Arbitrary regions, not a scalar width.** A `Region` turns any 2D shape — circles, ellipses,
+  polygons, boolean unions/intersections/**holes**, SVG paths, glyph outlines, raster alpha masks —
+  into the per-row spans Pretext consumes. Pretext has no notion of a shape, a hole, or an outline.
+- **Multiple disjoint spans per line — the "cursor trick."** Pouring a single row across the left
+  *and* right of a hole (a donut), or into the prongs of a concave shape, in reading order on one
+  baseline. Pretext's one-line-one-width API can't natively continue a row across a gap; textpour
+  threads one cursor through every span on the row.
+- **Auto-fit to a region** — binary-search the font size that exactly fills a shape. Pretext keys
+  layout on `(text, font)`; it doesn't size-to-fit a 2D area.
+- **A render-agnostic plan/paint kernel** — geometry computed once, painted by pluggable
+  `Renderer`s (Canvas2D today, HTML-in-Canvas later).
+- **Cursor ↔ point mapping** for hit-testing/caret in custom-rendered text.
+
+Honest overlap: textpour targets the **published `@chenglou/pretext@0.0.1`**, whose API is just
+`prepareWithSegments` + `layoutNextLine`. So textpour's own justification, soft-hyphenation, and
+balanced-lines are pragmatic implementations over that minimal surface — when Pretext ships its
+richer API (Knuth–Plass justify, real hyphenation, `walkLineRanges`), textpour will defer to those
+and keep only the geometry it uniquely contributes.
+
+In one line: **Pretext breaks the lines; textpour decides the shape those lines fill.**
+
+## Quickstart
+
+```bash
+npm install
+npm test          # builds, runs the pure-logic test suite (56 specs)
+npm run build     # emits dist/
+# demo (needs a browser + http):
+npx http-server . # or any static server
+# open /demo/index.html
+```
+
+## Status
+
+**Phase 0** (kernel scaffold) and **Phase 1** (shape-flow quality — justification, soft-hyphenation,
+balanced lines, auto-fit, region-from-outline, conservative band sampling) are complete and tested
+(56 specs). See **ROADMAP.md** for what's next — the HTML-in-Canvas renderer (Phase 2), then the
+flagship "shaped CSS text on a 3D surface" demo (Phase 3).
+
+## Docs
+
+- **EXPLAINER.md** — plain-words overview, ELI5, and the origin story (start here for the why).
+- **CLAUDE.md** — how to work in this repo (conventions, commands, guardrails).
+- **SPEC.md** — the full design, API reference, and the relationship to Pretext + HTML-in-Canvas.
+- **ROADMAP.md** — phased tasks with acceptance + kill criteria.
+
+## Example
+
+```ts
+import { shapeFlow, circle, subtract, Canvas2DRenderer, PretextLineSource } from 'textpour';
+
+const source = new PretextLineSource(longText, '17px Georgia'); // one prepare pass
+const region = subtract(circle(220, 220, 160), circle(220, 220, 67)); // a donut
+const result = shapeFlow(source, region, { lineHeight: 24, ascent: 18 });
+
+new Canvas2DRenderer('17px Georgia', { color: '#1a1a1a' }).render(result, ctx);
+// result.overflow / result.endCursor drive auto-fit and multi-region pagination
+```
+
+MIT.

package/dist/src/auto-fit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * auto-fit.ts — binary-search the largest font size at which text fits a region without overflow.
+ *
+ * Performance note: because Pretext's prepare is keyed on (text, font), each size trial requires
+ * a fresh prepareWithSegments call. Under PretextLineSource this makes each trial moderately
+ * expensive (O(text length) Unicode segmentation). Callers should:
+ *   - Keep maxIterations low (default 24 is already generous for 0.5 px tolerance over a
+ *     6–96 px range — fewer than 10 iterations converge in practice).
+ *   - Cache results when the text and region don't change between frames.
+ *   - When the range API ships (measureLineStats / layoutNextLineRange), a non-materializing stats
+ *     call from inside the source can shortcut the full shapeFlow pass; slot it in here behind the
+ *     makeSource seam without changing this module.
+ */
+import type { Region } from './region.js';
+import type { LineSource } from './line-source.js';
+import type { FlowOptions, FlowResult } from './types.js';
+export interface AutoFitOptions extends FlowOptions {
+    /** Smallest font size to try (px). Default: 6. */
+    minSizePx?: number;
+    /** Largest font size to try (px). Default: 96. */
+    maxSizePx?: number;
+    /**
+     * Stop when hi − lo < tolerance (px). Default: 0.5.
+     * The returned sizePx is accurate to within this margin.
+     */
+    tolerance?: number;
+    /** Safety cap on iterations. Default: 24. */
+    maxIterations?: number;
+    /**
+     * When set, lineHeight for each trial = sizePx * lineHeightRatio instead of the fixed
+     * opts.lineHeight. Required for the overflow predicate to be monotonic in size (bigger
+     * font → taller rows → fewer rows fit → more likely overflow). Without this, a fixed
+     * lineHeight means more text fits as charWidth grows but row count is constant, which
+     * can break monotonicity.
+     */
+    lineHeightRatio?: number;
+    /**
+     * When set, ascent for each trial = sizePx * ascentRatio instead of opts.ascent.
+     * Defaults to lineHeightRatio * 0.8 when lineHeightRatio is set and ascentRatio is omitted.
+     */
+    ascentRatio?: number;
+}
+export interface AutoFitResult<C> {
+    /** The winning font size (px). May be minSizePx if even the minimum overflows. */
+    sizePx: number;
+    /** The FlowResult at the winning size. overflow===true only when even minSizePx overflowed. */
+    result: FlowResult<C>;
+}
+/**
+ * Binary-search the largest sizePx in [minSizePx, maxSizePx] such that shapeFlow does not
+ * overflow the region. Returns the best-effort smallest size when all sizes overflow.
+ *
+ * @param makeSource  Factory called once per trial — returns a LineSource calibrated for sizePx.
+ *                    Under Pretext this is a full prepareWithSegments; keep maxIterations small.
+ * @param region      The target region (unchanged across trials).
+ * @param opts        Flow options plus auto-fit knobs. lineHeight/ascent are overridden per
+ *                    iteration when lineHeightRatio / ascentRatio are set.
+ */
+export declare function autoFit<C>(makeSource: (sizePx: number) => LineSource<C>, region: Region, opts: AutoFitOptions): AutoFitResult<C>;

package/dist/src/auto-fit.js

@@ -0,0 +1,74 @@
+/**
+ * auto-fit.ts — binary-search the largest font size at which text fits a region without overflow.
+ *
+ * Performance note: because Pretext's prepare is keyed on (text, font), each size trial requires
+ * a fresh prepareWithSegments call. Under PretextLineSource this makes each trial moderately
+ * expensive (O(text length) Unicode segmentation). Callers should:
+ *   - Keep maxIterations low (default 24 is already generous for 0.5 px tolerance over a
+ *     6–96 px range — fewer than 10 iterations converge in practice).
+ *   - Cache results when the text and region don't change between frames.
+ *   - When the range API ships (measureLineStats / layoutNextLineRange), a non-materializing stats
+ *     call from inside the source can shortcut the full shapeFlow pass; slot it in here behind the
+ *     makeSource seam without changing this module.
+ */
+import { shapeFlow } from './flow.js';
+/**
+ * Binary-search the largest sizePx in [minSizePx, maxSizePx] such that shapeFlow does not
+ * overflow the region. Returns the best-effort smallest size when all sizes overflow.
+ *
+ * @param makeSource  Factory called once per trial — returns a LineSource calibrated for sizePx.
+ *                    Under Pretext this is a full prepareWithSegments; keep maxIterations small.
+ * @param region      The target region (unchanged across trials).
+ * @param opts        Flow options plus auto-fit knobs. lineHeight/ascent are overridden per
+ *                    iteration when lineHeightRatio / ascentRatio are set.
+ */
+export function autoFit(makeSource, region, opts) {
+    const minSizePx = opts.minSizePx ?? 6;
+    const maxSizePx = opts.maxSizePx ?? 96;
+    const tolerance = opts.tolerance ?? 0.5;
+    const maxIterations = opts.maxIterations ?? 24;
+    /** Build per-iteration FlowOptions with scaled lineHeight/ascent. */
+    function iterOpts(sizePx) {
+        const lineHeight = opts.lineHeightRatio != null
+            ? sizePx * opts.lineHeightRatio
+            : opts.lineHeight;
+        const ascent = opts.ascentRatio != null
+            ? sizePx * opts.ascentRatio
+            : opts.lineHeightRatio != null
+                ? sizePx * opts.lineHeightRatio * 0.8
+                : opts.ascent;
+        // Spread the rest of FlowOptions, then override lineHeight/ascent.
+        const { minSizePx: _a, maxSizePx: _b, tolerance: _c, maxIterations: _d, lineHeightRatio: _e, ascentRatio: _f, ...rest } = opts;
+        return { ...rest, lineHeight, ...(ascent !== undefined ? { ascent } : {}) };
+    }
+    /** Flow once at sizePx. Each call is one full prepare under Pretext — so we reuse results. */
+    function flowAt(sizePx) {
+        return shapeFlow(makeSource(sizePx), region, iterOpts(sizePx));
+    }
+    // Fast paths: check the extremes first (saves iterations in the common case).
+    const maxRes = flowAt(maxSizePx);
+    if (!maxRes.overflow)
+        return { sizePx: maxSizePx, result: maxRes };
+    const minRes = flowAt(minSizePx);
+    if (minRes.overflow)
+        return { sizePx: minSizePx, result: minRes };
+    // Invariant: lo fits (overflow===false), hi overflows. Track lo's result to avoid re-flowing it.
+    let lo = minSizePx;
+    let hi = maxSizePx;
+    let loResult = minRes;
+    let iterations = 0;
+    while (hi - lo >= tolerance && iterations < maxIterations) {
+        const mid = (lo + hi) / 2;
+        const midRes = flowAt(mid);
+        if (!midRes.overflow) {
+            lo = mid;
+            loResult = midRes;
+        }
+        else {
+            hi = mid;
+        }
+        iterations++;
+    }
+    // lo is the largest size that fits; reuse its already-computed result.
+    return { sizePx: lo, result: loResult };
+}

package/dist/src/balance.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Balanced-line width search.
+ *
+ * Finds the narrowest line width that keeps the same number of lines as the unconstrained layout,
+ * reducing the ragged edge by avoiding a near-empty final line.
+ *
+ * NOTE: this is meaningful for rectangular / near-rectangular regions. For highly variable-width
+ * shapes (circles, stars, concave polygons) uniform narrowing is only a hint, not a guarantee —
+ * the per-row span width still varies independently of the global maxWidth cap, so balance is best
+ * paired with `multiSpan: 'widest'` or `'first'` where the dominant span drives the width.
+ *
+ * // FUTURE: when Pretext's measureLineStats/walkLineRanges range API ships, use a non-materializing
+ * // stats walk instead of full shapeFlow calls per binary-search step.
+ */
+import type { Region } from './region.js';
+import type { LineSource } from './line-source.js';
+import type { FlowOptions, FlowResult } from './types.js';
+/**
+ * Find the narrowest line width `w` such that flowing `source` through a region whose spans are
+ * capped to `w` produces the same number of lines (and the same `overflow` flag) as the full
+ * unconstrained layout.
+ *
+ * The result is determined by binary search (~20 iterations, resolution 0.5 px). Use it to pour
+ * text with a more even ragged edge — avoiding a last line that is nearly empty.
+ *
+ * **Caveat (rectangular / near-rectangular regions):** For shapes with highly variable per-row
+ * widths (circles, stars, concave polygons) the uniform width cap is only a hint. The binary
+ * search still converges and preserves the line count, but the visual balance improvement is
+ * region-specific. Best paired with `multiSpan: 'widest'` or `'first'` for such shapes.
+ *
+ * // FUTURE: when Pretext's measureLineStats/walkLineRanges range API ships, use a non-materializing
+ * // stats walk instead of full shapeFlow calls per binary-search step.
+ */
+export declare function balanceWidth(source: LineSource<unknown>, region: Region, options: FlowOptions): number;
+/**
+ * Compute a balanced layout: finds the narrowest width that preserves the line count of the
+ * unconstrained layout, then flows through the capped region.
+ *
+ * This is equivalent to:
+ *   `shapeFlow(source, narrowedRegion(region, balanceWidth(source, region, options)), options)`
+ * but keeps `NarrowedRegion` private to this module.
+ *
+ * **Caveat:** see `balanceWidth` — most effective for rectangular / near-rectangular regions.
+ *
+ * // FUTURE: when Pretext's measureLineStats/walkLineRanges range API ships, use a non-materializing
+ * // stats walk instead of full shapeFlow calls per binary-search step.
+ */
+export declare function balancedFlow<C>(source: LineSource<C>, region: Region, options: FlowOptions): FlowResult<C>;

package/dist/src/balance.js

@@ -0,0 +1,98 @@
+/**
+ * Balanced-line width search.
+ *
+ * Finds the narrowest line width that keeps the same number of lines as the unconstrained layout,
+ * reducing the ragged edge by avoiding a near-empty final line.
+ *
+ * NOTE: this is meaningful for rectangular / near-rectangular regions. For highly variable-width
+ * shapes (circles, stars, concave polygons) uniform narrowing is only a hint, not a guarantee —
+ * the per-row span width still varies independently of the global maxWidth cap, so balance is best
+ * paired with `multiSpan: 'widest'` or `'first'` where the dominant span drives the width.
+ *
+ * // FUTURE: when Pretext's measureLineStats/walkLineRanges range API ships, use a non-materializing
+ * // stats walk instead of full shapeFlow calls per binary-search step.
+ */
+import { shapeFlow } from './flow.js';
+// ---------------------------------------------------------------------------
+// NarrowedRegion — caps each span's width at a global maximum.
+// Not exported: it is an implementation detail of the binary search.
+// ---------------------------------------------------------------------------
+class NarrowedRegion {
+    inner;
+    maxWidth;
+    constructor(inner, maxWidth) {
+        this.inner = inner;
+        this.maxWidth = maxWidth;
+    }
+    spansAt(y) {
+        return this.inner.spansAt(y).map(([x0, x1]) => [x0, Math.min(x1, x0 + this.maxWidth)]);
+    }
+    bounds() {
+        return this.inner.bounds();
+    }
+}
+// ---------------------------------------------------------------------------
+// balanceWidth — public utility
+// ---------------------------------------------------------------------------
+/**
+ * Find the narrowest line width `w` such that flowing `source` through a region whose spans are
+ * capped to `w` produces the same number of lines (and the same `overflow` flag) as the full
+ * unconstrained layout.
+ *
+ * The result is determined by binary search (~20 iterations, resolution 0.5 px). Use it to pour
+ * text with a more even ragged edge — avoiding a last line that is nearly empty.
+ *
+ * **Caveat (rectangular / near-rectangular regions):** For shapes with highly variable per-row
+ * widths (circles, stars, concave polygons) the uniform width cap is only a hint. The binary
+ * search still converges and preserves the line count, but the visual balance improvement is
+ * region-specific. Best paired with `multiSpan: 'widest'` or `'first'` for such shapes.
+ *
+ * // FUTURE: when Pretext's measureLineStats/walkLineRanges range API ships, use a non-materializing
+ * // stats walk instead of full shapeFlow calls per binary-search step.
+ */
+export function balanceWidth(source, region, options) {
+    const bounds = region.bounds();
+    const fullWidth = bounds.maxX - bounds.minX;
+    const base = shapeFlow(source, region, options);
+    const baseCount = base.lines.length;
+    // One line (or no lines): nothing to balance.
+    if (baseCount <= 1)
+        return fullWidth;
+    // Binary search for the minimum width that preserves both line count AND overflow flag.
+    let lo = 1;
+    let hi = fullWidth;
+    let best = fullWidth; // fallback: full width always qualifies
+    const iterations = 20;
+    for (let k = 0; k < iterations && hi - lo > 0.5; k++) {
+        const mid = (lo + hi) / 2;
+        const candidate = shapeFlow(source, new NarrowedRegion(region, mid), options);
+        if (candidate.lines.length === baseCount && candidate.overflow === base.overflow) {
+            best = mid;
+            hi = mid; // try even narrower
+        }
+        else {
+            lo = mid; // too narrow — needs more width
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// balancedFlow — convenience combinator (keeps NarrowedRegion private here)
+// ---------------------------------------------------------------------------
+/**
+ * Compute a balanced layout: finds the narrowest width that preserves the line count of the
+ * unconstrained layout, then flows through the capped region.
+ *
+ * This is equivalent to:
+ *   `shapeFlow(source, narrowedRegion(region, balanceWidth(source, region, options)), options)`
+ * but keeps `NarrowedRegion` private to this module.
+ *
+ * **Caveat:** see `balanceWidth` — most effective for rectangular / near-rectangular regions.
+ *
+ * // FUTURE: when Pretext's measureLineStats/walkLineRanges range API ships, use a non-materializing
+ * // stats walk instead of full shapeFlow calls per binary-search step.
+ */
+export function balancedFlow(source, region, options) {
+    const w = balanceWidth(source, region, options);
+    return shapeFlow(source, new NarrowedRegion(region, w), options);
+}

package/dist/src/flow.d.ts

@@ -0,0 +1,34 @@
+import type { Region } from './region.js';
+import type { LineSource } from './line-source.js';
+import type { FlowOptions, FlowResult } from './types.js';
+/**
+ * Pour text from `source` into `region`, line by line.
+ *
+ * For each row band [y, y+lineHeight) we sample the region's inside-spans at the row center,
+ * then feed each span's width to the source as a maxWidth. With multiSpan='fill' a single row can
+ * consume several disjoint spans (the cursor trick): we keep advancing the same cursor across
+ * spans WITHOUT advancing y, which is how concave shapes and holes get filled.
+ *
+ * Pure function of (source, region, options) — the source is stateless w.r.t. the cursor, so this
+ * is safe to call repeatedly (e.g. on every animation frame for a moving region).
+ */
+export declare function shapeFlow<C>(source: LineSource<C>, region: Region, options: FlowOptions): FlowResult<C>;
+/**
+ * Holds a source so the (expensive) prepare pass is done once, and re-flows cheaply when only the
+ * region or options change. This is the reactive-region perf story: build once, reflow() per frame.
+ */
+export declare class ShapeFlow<C> {
+    private source;
+    private options;
+    constructor(source: LineSource<C>, options: FlowOptions);
+    flow(region: Region): FlowResult<C>;
+    reflow(region: Region, optionsPatch?: Partial<FlowOptions>): FlowResult<C>;
+    /**
+     * Like `reflow`, but first binary-searches for the narrowest width that preserves the
+     * unconstrained line count, then flows through the capped region. This reduces the ragged edge
+     * by avoiding a near-empty last line.
+     *
+     * Delegates to `balancedFlow` from balance.ts so `NarrowedRegion` stays private there.
+     */
+    rebalance(region: Region, optionsPatch?: Partial<FlowOptions>): FlowResult<C>;
+}

package/dist/src/flow.js

@@ -0,0 +1,172 @@
+import { intersectSpans } from './region.js';
+import { balancedFlow } from './balance.js';
+function widestSpan(spans) {
+    let best = spans[0];
+    let bestW = best[1] - best[0];
+    for (let i = 1; i < spans.length; i++) {
+        const w = spans[i][1] - spans[i][0];
+        if (w > bestW) {
+            best = spans[i];
+            bestW = w;
+        }
+    }
+    return best;
+}
+/**
+ * Conservative band sampling: intersect the region's spans across `steps` sample points evenly
+ * spread within [y, y+lineHeight). The result is the x-ranges inside the shape across the WHOLE
+ * band, so a line never pokes outside a tight curve. Returns [] as soon as any sample is empty.
+ */
+function bandSpans(region, y, lineHeight, steps) {
+    const step = lineHeight / steps;
+    let acc = null;
+    for (let k = 0; k < steps; k++) {
+        const sampleY = y + step * (k + 0.5);
+        const s = region.spansAt(sampleY);
+        acc = acc === null ? s : intersectSpans(acc, s);
+        if (acc.length === 0)
+            return [];
+    }
+    return acc ?? [];
+}
+/**
+ * Pour text from `source` into `region`, line by line.
+ *
+ * For each row band [y, y+lineHeight) we sample the region's inside-spans at the row center,
+ * then feed each span's width to the source as a maxWidth. With multiSpan='fill' a single row can
+ * consume several disjoint spans (the cursor trick): we keep advancing the same cursor across
+ * spans WITHOUT advancing y, which is how concave shapes and holes get filled.
+ *
+ * Pure function of (source, region, options) — the source is stateless w.r.t. the cursor, so this
+ * is safe to call repeatedly (e.g. on every animation frame for a moving region).
+ */
+export function shapeFlow(source, region, options) {
+    const lineHeight = options.lineHeight;
+    const ascent = options.ascent ?? lineHeight * 0.8;
+    const multiSpan = options.multiSpan ?? 'fill';
+    const align = options.align ?? 'left';
+    const minSpanWidth = options.minSpanWidth ?? 1;
+    const conservative = options.conservativeBandSampling ?? false;
+    const bandSteps = Math.max(1, Math.floor(options.bandSamplingSteps ?? 3));
+    const bounds = region.bounds();
+    const startY = options.startY ?? bounds.minY;
+    const maxY = bounds.maxY;
+    const eps = 1e-6;
+    const lines = [];
+    let cursor = source.start();
+    let y = startY;
+    let rowIndex = 0;
+    let exhausted = false;
+    let lastContentBottom = startY;
+    while (!exhausted && y + lineHeight <= maxY + eps) {
+        const rawSpans = conservative
+            ? bandSpans(region, y, lineHeight, bandSteps)
+            : region.spansAt(y + lineHeight / 2);
+        let spans = rawSpans.filter((s) => s[1] - s[0] >= minSpanWidth);
+        if (spans.length > 0) {
+            if (multiSpan === 'widest')
+                spans = [widestSpan(spans)];
+            else if (multiSpan === 'first')
+                spans = [spans[0]];
+            let spanIndex = 0;
+            let placedThisRow = false;
+            for (const span of spans) {
+                const x0 = span[0];
+                const x1 = span[1];
+                const width = x1 - x0;
+                const line = source.nextLine(cursor, width);
+                if (line === null) {
+                    exhausted = true;
+                    break;
+                }
+                if (line.text.length === 0)
+                    continue; // span too small to make progress; skip it
+                let x = x0;
+                if (align === 'right')
+                    x = x1 - line.width;
+                else if (align === 'center')
+                    x = x0 + (width - line.width) / 2;
+                // 'justify' is left-anchored: x stays x0 (same as 'left').
+                // Compute justified word positions when applicable.
+                // Last-line detection: probe one more line from this line's end. This materializes an
+                // extra line under Pretext 0.0.1; when the range API ships (measureLineStats / walkLineRanges),
+                // replace this with a non-materializing stats call to avoid the extra work.
+                let justifiedWords;
+                if (align === 'justify' && line.words !== undefined && line.words.length > 1) {
+                    const probeForLast = source.nextLine(line.end, width);
+                    const isLastLine = probeForLast === null || probeForLast.text.length === 0;
+                    if (!isLastLine) {
+                        // Distribute span width across words: word k's absolute x = x0 + sumWidths[0..k-1] + k*gap.
+                        const spanWidth = x1 - x0;
+                        const sumW = line.words.reduce((acc, w) => acc + w.width, 0);
+                        const gap = (spanWidth - sumW) / (line.words.length - 1);
+                        // Single left-to-right pass: each word sits after the prior words plus k justified gaps.
+                        let priorWidths = 0;
+                        justifiedWords = line.words.map((w, k) => {
+                            const seg = { text: w.text, x: x0 + priorWidths + k * gap, width: w.width };
+                            priorWidths += w.width;
+                            return seg;
+                        });
+                    }
+                }
+                lines.push({
+                    text: line.text,
+                    x,
+                    y,
+                    baseline: y + ascent,
+                    width: line.width,
+                    rowIndex,
+                    spanIndex,
+                    start: line.start,
+                    end: line.end,
+                    softHyphenated: line.softHyphenated,
+                    words: justifiedWords,
+                });
+                cursor = line.end;
+                spanIndex++;
+                placedThisRow = true;
+            }
+            if (placedThisRow)
+                lastContentBottom = y + lineHeight;
+        }
+        y += lineHeight;
+        rowIndex++;
+    }
+    // Overflow = text remained when we ran out of vertical room. Probing does not mutate the source.
+    let overflow = false;
+    if (!exhausted) {
+        const probeWidth = Math.max(1, bounds.maxX - bounds.minX);
+        const probe = source.nextLine(cursor, probeWidth);
+        overflow = probe !== null && probe.text.length > 0;
+    }
+    return { lines, overflow, endCursor: cursor, height: lastContentBottom - startY };
+}
+/**
+ * Holds a source so the (expensive) prepare pass is done once, and re-flows cheaply when only the
+ * region or options change. This is the reactive-region perf story: build once, reflow() per frame.
+ */
+export class ShapeFlow {
+    source;
+    options;
+    constructor(source, options) {
+        this.source = source;
+        this.options = options;
+    }
+    flow(region) {
+        return shapeFlow(this.source, region, this.options);
+    }
+    reflow(region, optionsPatch) {
+        return shapeFlow(this.source, region, { ...this.options, ...optionsPatch });
+    }
+    /**
+     * Like `reflow`, but first binary-searches for the narrowest width that preserves the
+     * unconstrained line count, then flows through the capped region. This reduces the ragged edge
+     * by avoiding a near-empty last line.
+     *
+     * Delegates to `balancedFlow` from balance.ts so `NarrowedRegion` stays private there.
+     */
+    rebalance(region, optionsPatch) {
+        const merged = { ...this.options, ...optionsPatch };
+        return balancedFlow(this.source, region, merged);
+    }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * 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 type { Region } from './region.js';
+/**
+ * An array of [x, y] points representing one contour of a glyph.
+ * Exported as a convenience type for callers who pre-process glyph outlines before
+ * passing path data to `glyphToRegion`.
+ */
+export type GlyphContour = Array<[number, number]>;
+/**
+ * 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 declare function glyphToRegion(pathData: string, opts?: {
+    steps?: number;
+}): Region;