textpour 0.1.0

package/dist/src/prefix-widths.d.ts

@@ -0,0 +1,22 @@
+/** Measures the rendered width (px) of a string in a fixed font. */
+export interface TextMeasurer {
+    measure(text: string): number;
+}
+/**
+ * Cumulative x-offset at each grapheme boundary of a line.
+ * Returns number[] of length (graphemeCount + 1); result[0] === 0 and
+ * result[k] === width of the first k graphemes. Cumulative prefixes are measured
+ * (not summed per-grapheme) so kerning/shaping between graphemes is captured.
+ */
+export declare function buildPrefixWidths(lineText: string, measurer: TextMeasurer, segmenter?: Intl.Segmenter): number[];
+/** Map an x offset (relative to line start) to the nearest grapheme boundary index. */
+export declare function xToGraphemeIndex(prefix: number[], x: number): number;
+/** Map a grapheme boundary index to its x offset (relative to line start). */
+export declare function graphemeIndexToX(prefix: number[], index: number): number;
+/** Build a measurer backed by a Canvas 2D context (browser or node-canvas). */
+export declare function canvasMeasurer(ctx: {
+    font: string;
+    measureText(s: string): {
+        width: number;
+    };
+}, font: string): TextMeasurer;

package/dist/src/prefix-widths.js

@@ -0,0 +1,61 @@
+// Per-line cursor<->point mapping. This is the data structure that powers hit-testing
+// and caret placement (project D) and justification (project B). Build it once per line at
+// layout time, then map point->index and index->point in O(log n).
+//
+// SCOPE: this is correct for left-to-right text. Bidi (visual vs logical order) is NOT handled
+// here yet — see ROADMAP. For RTL/mixed lines you must consult Pretext's segLevels.
+function segmentGraphemes(text, segmenter) {
+    const seg = segmenter ?? new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+    const out = [];
+    for (const part of seg.segment(text))
+        out.push(part.segment);
+    return out;
+}
+/**
+ * Cumulative x-offset at each grapheme boundary of a line.
+ * Returns number[] of length (graphemeCount + 1); result[0] === 0 and
+ * result[k] === width of the first k graphemes. Cumulative prefixes are measured
+ * (not summed per-grapheme) so kerning/shaping between graphemes is captured.
+ */
+export function buildPrefixWidths(lineText, measurer, segmenter) {
+    const graphemes = segmentGraphemes(lineText, segmenter);
+    const prefix = [0];
+    let cum = '';
+    for (const g of graphemes) {
+        cum += g;
+        prefix.push(measurer.measure(cum));
+    }
+    return prefix;
+}
+/** Map an x offset (relative to line start) to the nearest grapheme boundary index. */
+export function xToGraphemeIndex(prefix, x) {
+    const last = prefix.length - 1;
+    if (x <= 0)
+        return 0;
+    if (x >= prefix[last])
+        return last;
+    // Smallest index whose prefix >= x.
+    let lo = 0;
+    let hi = last;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (prefix[mid] < x)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const hiIdx = lo;
+    const loIdx = lo - 1;
+    // Snap to the nearer of the two surrounding boundaries.
+    return x - prefix[loIdx] <= prefix[hiIdx] - x ? loIdx : hiIdx;
+}
+/** Map a grapheme boundary index to its x offset (relative to line start). */
+export function graphemeIndexToX(prefix, index) {
+    const i = Math.max(0, Math.min(index, prefix.length - 1));
+    return prefix[i];
+}
+/** Build a measurer backed by a Canvas 2D context (browser or node-canvas). */
+export function canvasMeasurer(ctx, font) {
+    ctx.font = font;
+    return { measure: (t) => ctx.measureText(t).width };
+}

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

@@ -0,0 +1,24 @@
+import { type LayoutCursor } from '@chenglou/pretext';
+import type { Line, LineSource } from './line-source.js';
+import type { TextMeasurer } from './prefix-widths.js';
+export declare class PretextLineSource implements LineSource<LayoutCursor> {
+    private measurer?;
+    private prepared;
+    /**
+     * @param text the paragraph to lay out
+     * @param font a Canvas 2D font shorthand, e.g. '16px Inter'. Must match the CSS used to render.
+     * @param measurer optional — when provided, `nextLine` populates `Line.words` for justification.
+     *   Pass `canvasMeasurer(ctx, font)` from `prefix-widths.ts`. Without a measurer, `words` is
+     *   undefined and `align:'justify'` silently falls back to left alignment.
+     *
+     * Soft hyphens (U+00AD) are honored natively by Pretext: unchosen soft hyphens are invisible,
+     * and when a soft hyphen wins the break, Pretext's materialized `line.text` already ends with a
+     * visible '-'. The @chenglou/pretext@0.0.1 API exposes no flag to distinguish a soft-hyphen break
+     * from a real hyphen, so `softHyphenated` is left undefined here (a real '-' is indistinguishable
+     * from a soft-hyphen break via the 0.0.1 API). To pre-insert soft hyphens into your text before
+     * constructing this source, use the `insertSoftHyphens()` helper exported from this package.
+     */
+    constructor(text: string, font: string, measurer?: TextMeasurer | undefined);
+    start(): LayoutCursor;
+    nextLine(cursor: LayoutCursor, maxWidth: number): Line<LayoutCursor> | null;
+}

package/dist/src/pretext-source.js

@@ -0,0 +1,66 @@
+// The real adapter onto @chenglou/pretext. Kept in a separate module so that
+// importing the orchestrator/tests does NOT pull Pretext (which needs Canvas 2D + Intl.Segmenter
+// at runtime). Only browser code / the demo imports this.
+//
+// VERSION NOTE: built against the published @chenglou/pretext@0.0.1, which exposes
+//   prepareWithSegments(text, font)            // no options arg yet
+//   layoutNextLine(prepared, cursor, maxWidth) // returns a materialized LayoutLine | null
+// The GitHub README is ahead of npm and adds layoutNextLineRange/materializeLineRange/
+// measureLineStats/measureNaturalWidth/rich-inline + a prepare options arg. When those ship,
+// switch nextLine() to the range API to avoid materializing text on rows you only measure.
+import { prepareWithSegments, layoutNextLine, } from '@chenglou/pretext';
+export class PretextLineSource {
+    measurer;
+    prepared;
+    /**
+     * @param text the paragraph to lay out
+     * @param font a Canvas 2D font shorthand, e.g. '16px Inter'. Must match the CSS used to render.
+     * @param measurer optional — when provided, `nextLine` populates `Line.words` for justification.
+     *   Pass `canvasMeasurer(ctx, font)` from `prefix-widths.ts`. Without a measurer, `words` is
+     *   undefined and `align:'justify'` silently falls back to left alignment.
+     *
+     * Soft hyphens (U+00AD) are honored natively by Pretext: unchosen soft hyphens are invisible,
+     * and when a soft hyphen wins the break, Pretext's materialized `line.text` already ends with a
+     * visible '-'. The @chenglou/pretext@0.0.1 API exposes no flag to distinguish a soft-hyphen break
+     * from a real hyphen, so `softHyphenated` is left undefined here (a real '-' is indistinguishable
+     * from a soft-hyphen break via the 0.0.1 API). To pre-insert soft hyphens into your text before
+     * constructing this source, use the `insertSoftHyphens()` helper exported from this package.
+     */
+    constructor(text, font, measurer) {
+        this.measurer = measurer;
+        this.prepared = prepareWithSegments(text, font);
+    }
+    start() {
+        return { segmentIndex: 0, graphemeIndex: 0 };
+    }
+    nextLine(cursor, maxWidth) {
+        const line = layoutNextLine(this.prepared, cursor, maxWidth);
+        if (line === null)
+            return null;
+        // softHyphenated is left undefined: the 0.0.1 API provides no way to detect a soft-hyphen break.
+        if (this.measurer === undefined) {
+            return { text: line.text, width: line.width, start: line.start, end: line.end };
+        }
+        // Build per-word segments for justification support.
+        // x is the natural offset of each word from the LINE LEFT (cumulative widths + space widths).
+        // flow.ts recomputes absolute x when justify is active, so approximate space measure is fine.
+        const measurer = this.measurer;
+        const spaceWidth = measurer.measure(' ');
+        const tokens = line.text.split(' ').filter(t => t.length > 0);
+        // Reconstruct natural x offsets by walking the tokens left-to-right.
+        let xOff = 0;
+        let tokenIdx = 0;
+        const wordSegments = tokens.map(token => {
+            // Find where this token starts in the displayed text (skip leading spaces/prior tokens).
+            const tokenX = xOff;
+            const w = measurer.measure(token);
+            xOff += w;
+            // Account for one space gap between tokens (approximate — ignores multiple consecutive spaces).
+            if (tokenIdx < tokens.length - 1)
+                xOff += spaceWidth;
+            tokenIdx++;
+            return { text: token, x: tokenX, width: w };
+        });
+        return { text: line.text, width: line.width, start: line.start, end: line.end, words: wordSegments };
+    }
+}

package/dist/src/region.d.ts

@@ -0,0 +1,62 @@
+import type { Interval, Bounds } from './types.js';
+/** Sort, drop zero/negative-width, and coalesce overlapping or touching intervals. */
+export declare function normalize(spans: Interval[]): Interval[];
+export declare function unionSpans(a: Interval[], b: Interval[]): Interval[];
+export declare function intersectSpans(a: Interval[], b: Interval[]): Interval[];
+export declare function subtractSpans(a: Interval[], b: Interval[]): Interval[];
+export interface Region {
+    /** Sorted, disjoint inside-intervals at horizontal scanline y. Empty if y is outside. */
+    spansAt(y: number): Interval[];
+    bounds(): Bounds;
+}
+export declare class RectRegion implements Region {
+    private x;
+    private y;
+    private w;
+    private h;
+    constructor(x: number, y: number, w: number, h: number);
+    spansAt(y: number): Interval[];
+    bounds(): Bounds;
+}
+export declare class CircleRegion implements Region {
+    private cx;
+    private cy;
+    private r;
+    constructor(cx: number, cy: number, r: number);
+    spansAt(y: number): Interval[];
+    bounds(): Bounds;
+}
+export declare class EllipseRegion implements Region {
+    private cx;
+    private cy;
+    private rx;
+    private ry;
+    constructor(cx: number, cy: number, rx: number, ry: number);
+    spansAt(y: number): Interval[];
+    bounds(): Bounds;
+}
+/** Polygon filled with the even-odd rule (supports concavity and holes via winding). */
+export declare class PolygonRegion implements Region {
+    private pts;
+    private bb;
+    constructor(points: Array<readonly [number, number]>);
+    spansAt(y: number): Interval[];
+    bounds(): Bounds;
+}
+type CompositeOp = 'union' | 'intersect' | 'subtract';
+/** Boolean combination of regions. 'subtract' = children[0] minus the union of the rest. */
+export declare class CompositeRegion implements Region {
+    private op;
+    private children;
+    constructor(op: CompositeOp, children: Region[]);
+    spansAt(y: number): Interval[];
+    bounds(): Bounds;
+}
+export declare const rect: (x: number, y: number, w: number, h: number) => Region;
+export declare const circle: (cx: number, cy: number, r: number) => Region;
+export declare const ellipse: (cx: number, cy: number, rx: number, ry: number) => Region;
+export declare const polygon: (points: Array<readonly [number, number]>) => Region;
+export declare const union: (...regions: Region[]) => Region;
+export declare const intersect: (...regions: Region[]) => Region;
+export declare const subtract: (base: Region, ...holes: Region[]) => Region;
+export {};

package/dist/src/region.js

@@ -0,0 +1,229 @@
+// ---------------------------------------------------------------------------
+// Interval-set algebra. All public functions return sorted, disjoint intervals.
+// ---------------------------------------------------------------------------
+/** Sort, drop zero/negative-width, and coalesce overlapping or touching intervals. */
+export function normalize(spans) {
+    const valid = spans.filter((s) => s[1] > s[0]);
+    if (valid.length === 0)
+        return [];
+    const sorted = [...valid].sort((a, b) => a[0] - b[0]);
+    const out = [];
+    let curStart = sorted[0][0];
+    let curEnd = sorted[0][1];
+    for (let i = 1; i < sorted.length; i++) {
+        const s = sorted[i];
+        if (s[0] <= curEnd) {
+            if (s[1] > curEnd)
+                curEnd = s[1];
+        }
+        else {
+            out.push([curStart, curEnd]);
+            curStart = s[0];
+            curEnd = s[1];
+        }
+    }
+    out.push([curStart, curEnd]);
+    return out;
+}
+export function unionSpans(a, b) {
+    return normalize([...a, ...b]);
+}
+export function intersectSpans(a, b) {
+    const A = normalize(a);
+    const B = normalize(b);
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < A.length && j < B.length) {
+        const lo = Math.max(A[i][0], B[j][0]);
+        const hi = Math.min(A[i][1], B[j][1]);
+        if (lo < hi)
+            out.push([lo, hi]);
+        if (A[i][1] < B[j][1])
+            i++;
+        else
+            j++;
+    }
+    return out;
+}
+export function subtractSpans(a, b) {
+    const A = normalize(a);
+    const B = normalize(b);
+    const out = [];
+    for (const [as, ae] of A) {
+        let curStart = as;
+        for (const [bs, be] of B) {
+            if (be <= curStart)
+                continue;
+            if (bs >= ae)
+                break;
+            if (bs > curStart)
+                out.push([curStart, bs]);
+            curStart = Math.max(curStart, be);
+            if (curStart >= ae)
+                break;
+        }
+        if (curStart < ae)
+            out.push([curStart, ae]);
+    }
+    return normalize(out);
+}
+export class RectRegion {
+    x;
+    y;
+    w;
+    h;
+    constructor(x, y, w, h) {
+        this.x = x;
+        this.y = y;
+        this.w = w;
+        this.h = h;
+    }
+    spansAt(y) {
+        if (y < this.y || y >= this.y + this.h)
+            return [];
+        return [[this.x, this.x + this.w]];
+    }
+    bounds() {
+        return { minX: this.x, minY: this.y, maxX: this.x + this.w, maxY: this.y + this.h };
+    }
+}
+export class CircleRegion {
+    cx;
+    cy;
+    r;
+    constructor(cx, cy, r) {
+        this.cx = cx;
+        this.cy = cy;
+        this.r = r;
+    }
+    spansAt(y) {
+        const dy = y - this.cy;
+        if (Math.abs(dy) >= this.r)
+            return [];
+        const hc = Math.sqrt(this.r * this.r - dy * dy);
+        return [[this.cx - hc, this.cx + hc]];
+    }
+    bounds() {
+        return { minX: this.cx - this.r, minY: this.cy - this.r, maxX: this.cx + this.r, maxY: this.cy + this.r };
+    }
+}
+export class EllipseRegion {
+    cx;
+    cy;
+    rx;
+    ry;
+    constructor(cx, cy, rx, ry) {
+        this.cx = cx;
+        this.cy = cy;
+        this.rx = rx;
+        this.ry = ry;
+    }
+    spansAt(y) {
+        const dy = (y - this.cy) / this.ry;
+        if (Math.abs(dy) >= 1)
+            return [];
+        const hc = this.rx * Math.sqrt(1 - dy * dy);
+        return [[this.cx - hc, this.cx + hc]];
+    }
+    bounds() {
+        return { minX: this.cx - this.rx, minY: this.cy - this.ry, maxX: this.cx + this.rx, maxY: this.cy + this.ry };
+    }
+}
+/** Polygon filled with the even-odd rule (supports concavity and holes via winding). */
+export class PolygonRegion {
+    pts;
+    bb;
+    constructor(points) {
+        if (points.length < 3)
+            throw new Error('PolygonRegion needs at least 3 points');
+        this.pts = points;
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const [px, py] of points) {
+            if (px < minX)
+                minX = px;
+            if (px > maxX)
+                maxX = px;
+            if (py < minY)
+                minY = py;
+            if (py > maxY)
+                maxY = py;
+        }
+        this.bb = { minX, minY, maxX, maxY };
+    }
+    spansAt(y) {
+        const xs = [];
+        const pts = this.pts;
+        const n = pts.length;
+        for (let i = 0; i < n; i++) {
+            const a = pts[i];
+            const b = pts[(i + 1) % n];
+            const y1 = a[1];
+            const y2 = b[1];
+            // Half-open crossing test avoids double-counting shared vertices.
+            if ((y1 <= y && y < y2) || (y2 <= y && y < y1)) {
+                const t = (y - y1) / (y2 - y1);
+                xs.push(a[0] + t * (b[0] - a[0]));
+            }
+        }
+        xs.sort((p, q) => p - q);
+        const out = [];
+        for (let i = 0; i + 1 < xs.length; i += 2)
+            out.push([xs[i], xs[i + 1]]);
+        return normalize(out);
+    }
+    bounds() {
+        return this.bb;
+    }
+}
+/** Boolean combination of regions. 'subtract' = children[0] minus the union of the rest. */
+export class CompositeRegion {
+    op;
+    children;
+    constructor(op, children) {
+        this.op = op;
+        this.children = children;
+        if (children.length === 0)
+            throw new Error('CompositeRegion needs at least one child');
+    }
+    spansAt(y) {
+        const c = this.children;
+        if (this.op === 'union') {
+            return c.reduce((acc, r) => unionSpans(acc, r.spansAt(y)), []);
+        }
+        if (this.op === 'intersect') {
+            let acc = c[0].spansAt(y);
+            for (let i = 1; i < c.length; i++)
+                acc = intersectSpans(acc, c[i].spansAt(y));
+            return acc;
+        }
+        // subtract
+        let holes = [];
+        for (let i = 1; i < c.length; i++)
+            holes = unionSpans(holes, c[i].spansAt(y));
+        return subtractSpans(c[0].spansAt(y), holes);
+    }
+    bounds() {
+        // Over-approximate with the union of child bounds; empty rows simply produce no spans.
+        let b = this.children[0].bounds();
+        for (let i = 1; i < this.children.length; i++) {
+            const o = this.children[i].bounds();
+            b = {
+                minX: Math.min(b.minX, o.minX),
+                minY: Math.min(b.minY, o.minY),
+                maxX: Math.max(b.maxX, o.maxX),
+                maxY: Math.max(b.maxY, o.maxY),
+            };
+        }
+        // For subtract, the vertical/horizontal extent can only shrink, so children[0] bounds is tighter:
+        return this.op === 'subtract' ? this.children[0].bounds() : b;
+    }
+}
+// ---- convenience builders ----
+export const rect = (x, y, w, h) => new RectRegion(x, y, w, h);
+export const circle = (cx, cy, r) => new CircleRegion(cx, cy, r);
+export const ellipse = (cx, cy, rx, ry) => new EllipseRegion(cx, cy, rx, ry);
+export const polygon = (points) => new PolygonRegion(points);
+export const union = (...regions) => new CompositeRegion('union', regions);
+export const intersect = (...regions) => new CompositeRegion('intersect', regions);
+export const subtract = (base, ...holes) => new CompositeRegion('subtract', [base, ...holes]);

package/dist/src/renderer.d.ts

@@ -0,0 +1,47 @@
+import type { FlowResult } from './types.js';
+/** A paint backend. The kernel produces geometry; renderers turn it into pixels/DOM. */
+export interface Renderer<Target, C = unknown> {
+    render(result: FlowResult<C>, target: Target): void;
+}
+/** Minimal slice of CanvasRenderingContext2D we actually use (keeps it testable). */
+export interface Canvas2DLike {
+    font: string;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    textBaseline: CanvasTextBaseline;
+    fillText(text: string, x: number, y: number): void;
+}
+/** Working backend: draws each placed line to a 2D canvas. */
+export declare class Canvas2DRenderer<C = unknown> implements Renderer<Canvas2DLike, C> {
+    private font;
+    private opts;
+    constructor(font: string, opts?: {
+        color?: string;
+    });
+    render(result: FlowResult<C>, ctx: Canvas2DLike): void;
+}
+/**
+ * STUB. HTML-in-Canvas is a Chrome origin-trial API (chrome://flags/#canvas-draw-element); no
+ * Firefox/Safari intent yet. The seam exists so the shape-flow module can target a high-fidelity,
+ * accessible paint path without knowing the backend. Pretext still does ALL line-breaking/geometry
+ * (the plan); HTML-in-Canvas only does the paint.
+ *
+ * Intended implementation (see ROADMAP phase 2):
+ *   1. Give the <canvas> the `layoutsubtree` attribute.
+ *   2. Keep one real styled child element per PlacedLine (e.g. a <span> with the same CSS font),
+ *      as a direct child of the canvas, positioned via CSS transform to (line.x, line.baseline).
+ *   3. In the canvas `paint` event, for each line call
+ *        const m = ctx.drawElementImage(span, line.x, line.y);
+ *        span.style.transform = m.toString();   // keep hit-testing + a11y aligned
+ *   4. Repaint only when the FlowResult changes; use canvas.requestPaint() for per-frame needs.
+ *      Caching matters: the element layout pass is the expensive op (the very reflow Pretext avoids),
+ *      so plan with Pretext every frame and only drawElementImage when the chosen layout changes.
+ */
+export interface HtmlInCanvasTarget {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+}
+export declare class HtmlInCanvasRenderer<C = unknown> implements Renderer<HtmlInCanvasTarget, C> {
+    /** Feature-detect the origin-trial API before using this backend. */
+    static isSupported(): boolean;
+    render(_result: FlowResult<C>, _target: HtmlInCanvasTarget): void;
+}

package/dist/src/renderer.js

@@ -0,0 +1,37 @@
+/** Working backend: draws each placed line to a 2D canvas. */
+export class Canvas2DRenderer {
+    font;
+    opts;
+    constructor(font, opts = {}) {
+        this.font = font;
+        this.opts = opts;
+    }
+    render(result, ctx) {
+        ctx.font = this.font;
+        ctx.textBaseline = 'alphabetic';
+        if (this.opts.color)
+            ctx.fillStyle = this.opts.color;
+        for (const line of result.lines) {
+            if (line.words !== undefined) {
+                // Justified line: draw each word at its individually computed absolute x position.
+                for (const word of line.words)
+                    ctx.fillText(word.text, word.x, line.baseline);
+            }
+            else {
+                ctx.fillText(line.text, line.x, line.baseline);
+            }
+        }
+    }
+}
+export class HtmlInCanvasRenderer {
+    /** Feature-detect the origin-trial API before using this backend. */
+    static isSupported() {
+        return (typeof CanvasRenderingContext2D !== 'undefined' &&
+            'drawElementImage' in CanvasRenderingContext2D.prototype);
+    }
+    render(_result, _target) {
+        throw new Error('HtmlInCanvasRenderer is a stub (ROADMAP phase 2). HTML-in-Canvas is a Chrome origin-trial ' +
+            'API behind chrome://flags/#canvas-draw-element. See renderer.ts comments for the intended ' +
+            'drawElementImage flow. Use Canvas2DRenderer until this is implemented.');
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,85 @@
+/** A horizontal inside-interval [x0, x1] with x0 <= x1. */
+export type Interval = readonly [number, number];
+export interface Bounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/** How to use multiple disjoint spans on a single row. */
+export type MultiSpan = 'fill' | 'widest' | 'first';
+export type Align = 'left' | 'center' | 'right' | 'justify';
+/**
+ * One word segment with an absolute x position within the canvas/target coordinate space.
+ * Set on `PlacedLine.words` when `align === 'justify'` and the line is not the last line
+ * of a paragraph. The renderer draws each word individually at its computed x so that
+ * inter-word gaps expand to fill the span exactly.
+ */
+export interface WordSegment {
+    text: string;
+    /** Absolute x of the word's left edge (in canvas coordinates). */
+    x: number;
+    /** Rendered width of the word (NOT including surrounding spaces). */
+    width: number;
+}
+export interface FlowOptions {
+    /** CSS line-height in px. Required. */
+    lineHeight: number;
+    /** Baseline offset within the row box (px). Default: lineHeight * 0.8. */
+    ascent?: number;
+    /** First row's top y. Default: region.bounds().minY. */
+    startY?: number;
+    /** Multi-span strategy. Default: 'fill'. */
+    multiSpan?: MultiSpan;
+    /** Horizontal alignment within each span. Default: 'left'. */
+    align?: Align;
+    /** Ignore spans narrower than this (px). Default: 1. */
+    minSpanWidth?: number;
+    /**
+     * Sample the FULL row band instead of only its vertical center. When true, the row's spans are the
+     * intersection of `region.spansAt` taken at several y within [y, y+lineHeight), so a line never
+     * pokes outside a tight curve (the row only claims x-ranges inside the shape across the whole band).
+     * More conservative (text stays strictly inside), at the cost of extra `spansAt` calls. Default: false.
+     */
+    conservativeBandSampling?: boolean;
+    /** Number of band samples when `conservativeBandSampling` is on. Default: 3. Clamped to >= 1. */
+    bandSamplingSteps?: number;
+}
+/** One laid-out line, positioned. Carries source cursors for hit-testing / continuation. */
+export interface PlacedLine<C> {
+    text: string;
+    /** Left x of the line after alignment. */
+    x: number;
+    /** Top y of the row box. */
+    y: number;
+    /** y + ascent — pass this to Canvas2D fillText with textBaseline 'alphabetic'. */
+    baseline: number;
+    /** Measured width of the line. */
+    width: number;
+    /** Row index from startY (0-based; rows with no content still increment it). */
+    rowIndex: number;
+    /** Which span within the row this line filled (0 for single-span rows). */
+    spanIndex: number;
+    /** Inclusive start cursor in the source. */
+    start: C;
+    /** Exclusive end cursor in the source. */
+    end: C;
+    /** True when a soft hyphen (U+00AD) was chosen as the line-break point and a visible '-' was appended. */
+    softHyphenated?: boolean;
+    /**
+     * Justified word positions with ABSOLUTE x coordinates (set ONLY when align==='justify',
+     * words.length > 1, and this is NOT the last line of the paragraph). When present, the renderer
+     * draws each word individually to achieve exact span-filling. When absent, the renderer falls
+     * back to a single fillText of the whole line string.
+     */
+    words?: WordSegment[];
+}
+export interface FlowResult<C> {
+    lines: PlacedLine<C>[];
+    /** True if text remained when vertical room ran out. */
+    overflow: boolean;
+    /** Where layout stopped — the start of any leftover text (drive pagination / auto-fit with this). */
+    endCursor: C;
+    /** Vertical extent actually used: bottom of last content row minus startY. */
+    height: number;
+}

package/dist/src/types.js

@@ -0,0 +1,5 @@
+// Core geometry & result types for the kernel.
+// Coordinate model: top-left origin, +y points down, units are CSS px.
+// A text row occupies the vertical band [y, y + lineHeight). Spans are sampled
+// at the row's vertical center. The baseline (where Canvas2D fillText draws) is y + ascent.
+export {};