@graphrefly/graphrefly 0.1.0

package/dist/index-C3BMRmmp.d.cts

@@ -0,0 +1,449 @@
+import { N as Node } from './meta-BsF6Sag9.cjs';
+import { G as Graph } from './graph-CL_ZDAj9.cjs';
+
+/** Pluggable measurement backend. */
+interface MeasurementAdapter {
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+    /** Optional; adapters may omit for read-only / stateless measurement. */
+    clearCache?(): void;
+}
+/** Mutable counters for `analyzeAndMeasure` cache hit ratio (hits / (hits + misses)). */
+type SegmentMeasureStats = {
+    hits: number;
+    misses: number;
+};
+/** Break kind for each segment (ported from Pretext analysis.ts). */
+type SegmentBreakKind = "text" | "space" | "zero-width-break" | "soft-hyphen" | "hard-break";
+/** A measured text segment ready for line breaking. */
+type PreparedSegment = {
+    text: string;
+    width: number;
+    kind: SegmentBreakKind;
+    /** Grapheme widths for overflow-wrap: break-word (null if single grapheme). */
+    graphemeWidths: number[] | null;
+};
+/** A laid-out line with start/end cursors. */
+type LayoutLine = {
+    text: string;
+    width: number;
+    startSegment: number;
+    startGrapheme: number;
+    endSegment: number;
+    endGrapheme: number;
+};
+/** Per-character position for hit testing. */
+type CharPosition = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    line: number;
+};
+/** Full layout result from the line-breaks derived node. */
+type LineBreaksResult = {
+    lines: LayoutLine[];
+    lineCount: number;
+};
+/** Result of the reactive layout graph's describe-accessible state. */
+type ReactiveLayoutBundle = {
+    graph: Graph;
+    /** Set input text. */
+    setText: (text: string) => void;
+    /** Set CSS font string. */
+    setFont: (font: string) => void;
+    /** Set line height (px). */
+    setLineHeight: (lineHeight: number) => void;
+    /** Set max width constraint (px). */
+    setMaxWidth: (maxWidth: number) => void;
+    /** Segments node. */
+    segments: Node<PreparedSegment[]>;
+    /** Line breaks node. */
+    lineBreaks: Node<LineBreaksResult>;
+    /** Total height node. */
+    height: Node<number>;
+    /** Per-character positions node. */
+    charPositions: Node<CharPosition[]>;
+};
+/**
+ * Merge segmentation pieces: sticky punctuation, CJK per-grapheme splitting,
+ * and produce the final measured segment list.
+ */
+declare function analyzeAndMeasure(text: string, font: string, adapter: MeasurementAdapter, cache: Map<string, Map<string, number>>, stats?: SegmentMeasureStats): PreparedSegment[];
+/**
+ * Greedy line-breaking algorithm.
+ *
+ * Walks segments left to right, accumulating width. Breaks when a segment would
+ * overflow maxWidth. Supports:
+ * - Trailing space hang (spaces don't trigger breaks)
+ * - overflow-wrap: break-word via grapheme widths
+ * - Soft hyphens (break opportunity, adds visible hyphen width)
+ * - Hard breaks (forced newline)
+ */
+declare function computeLineBreaks(segments: PreparedSegment[], maxWidth: number, adapter: MeasurementAdapter, font: string, cache: Map<string, Map<string, number>>): LineBreaksResult;
+/** Compute per-character x,y positions from line breaks and segments. */
+declare function computeCharPositions(lineBreaks: LineBreaksResult, segments: PreparedSegment[], lineHeight: number): CharPosition[];
+type ReactiveLayoutOptions = {
+    /** Measurement backend (required). */
+    adapter: MeasurementAdapter;
+    /** Graph name (default: "reactive-layout"). */
+    name?: string;
+    /** Initial text. */
+    text?: string;
+    /** Initial CSS font string. */
+    font?: string;
+    /** Initial line height in px. */
+    lineHeight?: number;
+    /** Initial max width in px (clamped to ≥ 0). */
+    maxWidth?: number;
+};
+/**
+ * Create a reactive text layout graph.
+ *
+ * ```
+ * Graph("reactive-layout")
+ * ├── state("text")
+ * ├── state("font")
+ * ├── state("line-height")
+ * ├── state("max-width")
+ * ├── derived("segments")      — text + font → PreparedSegment[]
+ * ├── derived("line-breaks")   — segments + max-width → LineBreaksResult
+ * ├── derived("height")        — line-breaks → number
+ * └── derived("char-positions") — line-breaks + segments → CharPosition[]
+ * ```
+ */
+declare function reactiveLayout(opts: ReactiveLayoutOptions): ReactiveLayoutBundle;
+
+/**
+ * MeasurementAdapter implementations (roadmap §7.1 — pluggable backends).
+ *
+ * All adapters implement {@link MeasurementAdapter} from `reactive-layout.ts`.
+ * Sync constructors, sync `measureSegment()` — no async, no polling.
+ */
+
+type CliMeasureAdapterOptions = {
+    /** Pixel width per terminal cell (default: 8). */
+    cellPx?: number;
+};
+/**
+ * Monospace terminal measurement adapter.
+ *
+ * Width = cell count × `cellPx`. CJK / fullwidth characters count as 2 cells.
+ * No external dependencies. Works in any JS environment.
+ */
+declare class CliMeasureAdapter implements MeasurementAdapter {
+    private readonly cellPx;
+    constructor(opts?: CliMeasureAdapterOptions);
+    measureSegment(text: string, _font: string): {
+        width: number;
+    };
+}
+type PrecomputedAdapterOptions = {
+    /**
+     * Pre-computed metrics: `{ font: { segment: widthPx } }`.
+     * Outer key is the CSS font string; inner key is the text segment.
+     */
+    metrics: Record<string, Record<string, number>>;
+    /**
+     * Fallback when a segment is not found in the metrics map.
+     * - `"per-char"`: sum individual character widths from the same font map (default)
+     * - `"error"`: throw an error for unknown segments
+     */
+    fallback?: "per-char" | "error";
+};
+/**
+ * Pre-computed measurement adapter for SSR / snapshot replay.
+ *
+ * Reads from a static metrics object — zero measurement at runtime.
+ * Ideal for server-side rendering or replaying snapshotted layouts.
+ */
+declare class PrecomputedAdapter implements MeasurementAdapter {
+    private readonly metrics;
+    private readonly fallback;
+    constructor(opts: PrecomputedAdapterOptions);
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+}
+type CanvasMeasureAdapterOptions = {
+    /** Emoji width correction factor (default: 1, no correction). */
+    emojiCorrection?: number;
+};
+/**
+ * Browser measurement adapter using `OffscreenCanvas.measureText()`.
+ *
+ * Lazily creates an OffscreenCanvas and 2D context on first call.
+ * Requires a browser environment with OffscreenCanvas support.
+ */
+declare class CanvasMeasureAdapter implements MeasurementAdapter {
+    private ctx;
+    private currentFont;
+    private readonly emojiCorrection;
+    constructor(opts?: CanvasMeasureAdapterOptions);
+    private getContext;
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+    clearCache(): void;
+}
+/**
+ * Canvas API subset expected from `@napi-rs/canvas` or `skia-canvas`.
+ * Passed via dependency injection — no dynamic import, no polling.
+ */
+type CanvasModule = {
+    createCanvas(width: number, height: number): {
+        getContext(type: "2d"): {
+            font: string;
+            measureText(text: string): {
+                width: number;
+            };
+        };
+    };
+};
+/**
+ * Node.js measurement adapter using an injected canvas module.
+ *
+ * ```ts
+ * import * as canvas from "@napi-rs/canvas";
+ * const adapter = new NodeCanvasMeasureAdapter(canvas);
+ * ```
+ *
+ * Works with `@napi-rs/canvas`, `skia-canvas`, or any module exposing
+ * `createCanvas(w, h).getContext("2d").measureText(text)`.
+ */
+declare class NodeCanvasMeasureAdapter implements MeasurementAdapter {
+    private ctx;
+    private currentFont;
+    private readonly canvasModule;
+    constructor(canvasModule: CanvasModule);
+    private getContext;
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+    clearCache(): void;
+}
+/**
+ * SVG measurement adapter — extracts dimensions from `viewBox` attribute
+ * or explicit `width`/`height` attributes in the SVG string.
+ *
+ * Pure arithmetic: parses the SVG string for dimension attributes.
+ * No DOM required. Works in any JS environment.
+ *
+ * Browser users who need `getBBox()` should pre-measure and pass explicit
+ * `viewBox` on the content block instead.
+ */
+declare class SvgBoundsAdapter {
+    measureSvg(content: string): {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Image measurement adapter — returns pre-registered dimensions by src key.
+ *
+ * Sync-only: dimensions must be provided upfront via the `sizes` map.
+ * No I/O, no polling, no async. For browser use, pre-measure via
+ * `Image.onload` and pass natural dimensions on the content block directly,
+ * or register them here.
+ *
+ * ```ts
+ * const adapter = new ImageSizeAdapter({
+ *   "hero.png": { width: 1200, height: 630 },
+ *   "logo.svg": { width: 120, height: 40 },
+ * });
+ * ```
+ */
+declare class ImageSizeAdapter {
+    private readonly sizes;
+    constructor(sizes: Record<string, {
+        width: number;
+        height: number;
+    }>);
+    measureImage(src: string): {
+        width: number;
+        height: number;
+    };
+}
+
+/** Pluggable measurement backend for SVG content. */
+interface SvgMeasurer {
+    measureSvg(content: string): {
+        width: number;
+        height: number;
+    };
+}
+/** Pluggable measurement backend for image content. */
+interface ImageMeasurer {
+    measureImage(src: string): {
+        width: number;
+        height: number;
+    };
+}
+/** Adapters map for `reactiveBlockLayout`. */
+type BlockAdapters = {
+    /** Text measurement adapter (required — delegates to `reactiveLayout` internals). */
+    text: MeasurementAdapter;
+    /** SVG measurement (optional — required only if SVG blocks are present). */
+    svg?: SvgMeasurer;
+    /** Image measurement (optional — required only if image blocks without explicit dimensions are present). */
+    image?: ImageMeasurer;
+};
+/** A content block — text, image, or SVG. */
+type ContentBlock = {
+    type: "text";
+    text: string;
+    font?: string;
+    lineHeight?: number;
+} | {
+    type: "image";
+    src: string;
+    /** Natural width in px. Required if no ImageMeasurer adapter is provided. */
+    naturalWidth?: number;
+    /** Natural height in px. Required if no ImageMeasurer adapter is provided. */
+    naturalHeight?: number;
+} | {
+    type: "svg";
+    content: string;
+    /** Explicit viewBox dimensions. Required if no SvgMeasurer adapter is provided. */
+    viewBox?: {
+        width: number;
+        height: number;
+    };
+};
+/**
+ * A block after measurement — knows its natural dimensions.
+ *
+ * **Equality note:** The reactive `measured-blocks` node uses dimension-only equality
+ * (`type`, `width`, `height`, `index`). Inner text layout data (`textSegments`,
+ * `textLineBreaks`, `textCharPositions`) is NOT compared for change detection.
+ * If you need text-level reactivity, use `reactiveLayout()` directly per text block.
+ */
+type MeasuredBlock = {
+    index: number;
+    type: "text" | "image" | "svg";
+    width: number;
+    height: number;
+    /** For text blocks: the inner layout results. */
+    textSegments?: PreparedSegment[];
+    textLineBreaks?: LineBreaksResult;
+    textCharPositions?: CharPosition[];
+};
+/** A block after flow — positioned in the container. */
+type PositionedBlock = MeasuredBlock & {
+    x: number;
+    y: number;
+};
+/** Options for `reactiveBlockLayout`. */
+type ReactiveBlockLayoutOptions = {
+    adapters: BlockAdapters;
+    name?: string;
+    blocks?: ContentBlock[];
+    /** Container max width in px (clamped to ≥ 0 on init and `setMaxWidth`). */
+    maxWidth?: number;
+    /** Vertical gap between blocks in px (default 0). */
+    gap?: number;
+    /** Default font for text blocks that don't specify one. */
+    defaultFont?: string;
+    /** Default line height for text blocks that don't specify one. */
+    defaultLineHeight?: number;
+};
+/** Result bundle from `reactiveBlockLayout`. */
+type ReactiveBlockLayoutBundle = {
+    graph: Graph;
+    setBlocks: (blocks: ContentBlock[]) => void;
+    setMaxWidth: (maxWidth: number) => void;
+    setGap: (gap: number) => void;
+    measuredBlocks: Node<MeasuredBlock[]>;
+    blockFlow: Node<PositionedBlock[]>;
+    totalHeight: Node<number>;
+};
+/**
+ * Measure a single content block, returning natural (unconstrained) dimensions.
+ * Text blocks use the text layout pipeline; image/SVG use adapters or explicit dims.
+ */
+declare function measureBlock(block: ContentBlock, maxWidth: number, adapters: BlockAdapters, measureCache: Map<string, Map<string, number>>, defaultFont: string, defaultLineHeight: number, index: number): MeasuredBlock;
+/**
+ * Measure all blocks in a content array.
+ */
+declare function measureBlocks(blocks: ContentBlock[], maxWidth: number, adapters: BlockAdapters, measureCache: Map<string, Map<string, number>>, defaultFont: string, defaultLineHeight: number): MeasuredBlock[];
+/**
+ * Vertical stacking flow: blocks are placed top-to-bottom, left-aligned,
+ * separated by `gap` pixels. Pure arithmetic over measured sizes.
+ */
+declare function computeBlockFlow(measured: MeasuredBlock[], gap: number): PositionedBlock[];
+/**
+ * Compute total height from positioned blocks.
+ */
+declare function computeTotalHeight(flow: PositionedBlock[]): number;
+/**
+ * Create a reactive block layout graph for mixed content (text + image + SVG).
+ *
+ * ```
+ * Graph("reactive-block-layout")
+ * ├── state("blocks")              — ContentBlock[] input
+ * ├── state("max-width")           — container constraint
+ * ├── state("gap")                 — vertical gap (px)
+ * ├── derived("measured-blocks")   — blocks + max-width → MeasuredBlock[]
+ * ├── derived("block-flow")        — measured-blocks + gap → PositionedBlock[]
+ * ├── derived("total-height")      — block-flow → number
+ * └── meta: { block-count, layout-time-ns }
+ * ```
+ */
+declare function reactiveBlockLayout(opts: ReactiveBlockLayoutOptions): ReactiveBlockLayoutBundle;
+
+/**
+ * Reactive layout pattern — standalone subpath export.
+ *
+ * ```ts
+ * import { reactiveLayout, CliMeasureAdapter } from "@graphrefly/graphrefly-ts/reactive-layout";
+ * ```
+ */
+
+type index_BlockAdapters = BlockAdapters;
+type index_CanvasMeasureAdapter = CanvasMeasureAdapter;
+declare const index_CanvasMeasureAdapter: typeof CanvasMeasureAdapter;
+type index_CanvasMeasureAdapterOptions = CanvasMeasureAdapterOptions;
+type index_CanvasModule = CanvasModule;
+type index_CharPosition = CharPosition;
+type index_CliMeasureAdapter = CliMeasureAdapter;
+declare const index_CliMeasureAdapter: typeof CliMeasureAdapter;
+type index_CliMeasureAdapterOptions = CliMeasureAdapterOptions;
+type index_ContentBlock = ContentBlock;
+type index_ImageMeasurer = ImageMeasurer;
+type index_ImageSizeAdapter = ImageSizeAdapter;
+declare const index_ImageSizeAdapter: typeof ImageSizeAdapter;
+type index_LayoutLine = LayoutLine;
+type index_LineBreaksResult = LineBreaksResult;
+type index_MeasuredBlock = MeasuredBlock;
+type index_MeasurementAdapter = MeasurementAdapter;
+type index_NodeCanvasMeasureAdapter = NodeCanvasMeasureAdapter;
+declare const index_NodeCanvasMeasureAdapter: typeof NodeCanvasMeasureAdapter;
+type index_PositionedBlock = PositionedBlock;
+type index_PrecomputedAdapter = PrecomputedAdapter;
+declare const index_PrecomputedAdapter: typeof PrecomputedAdapter;
+type index_PrecomputedAdapterOptions = PrecomputedAdapterOptions;
+type index_PreparedSegment = PreparedSegment;
+type index_ReactiveBlockLayoutBundle = ReactiveBlockLayoutBundle;
+type index_ReactiveBlockLayoutOptions = ReactiveBlockLayoutOptions;
+type index_ReactiveLayoutBundle = ReactiveLayoutBundle;
+type index_ReactiveLayoutOptions = ReactiveLayoutOptions;
+type index_SegmentBreakKind = SegmentBreakKind;
+type index_SegmentMeasureStats = SegmentMeasureStats;
+type index_SvgBoundsAdapter = SvgBoundsAdapter;
+declare const index_SvgBoundsAdapter: typeof SvgBoundsAdapter;
+type index_SvgMeasurer = SvgMeasurer;
+declare const index_analyzeAndMeasure: typeof analyzeAndMeasure;
+declare const index_computeBlockFlow: typeof computeBlockFlow;
+declare const index_computeCharPositions: typeof computeCharPositions;
+declare const index_computeLineBreaks: typeof computeLineBreaks;
+declare const index_computeTotalHeight: typeof computeTotalHeight;
+declare const index_measureBlock: typeof measureBlock;
+declare const index_measureBlocks: typeof measureBlocks;
+declare const index_reactiveBlockLayout: typeof reactiveBlockLayout;
+declare const index_reactiveLayout: typeof reactiveLayout;
+declare namespace index {
+  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, type index_CharPosition as CharPosition, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ContentBlock as ContentBlock, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, type index_LayoutLine as LayoutLine, type index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, type index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_PositionedBlock as PositionedBlock, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, type index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveLayoutBundle as ReactiveLayoutBundle, type index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_SegmentBreakKind as SegmentBreakKind, type index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveLayout as reactiveLayout };
+}
+
+export { reactiveBlockLayout as A, type BlockAdapters as B, CanvasMeasureAdapter as C, reactiveLayout as D, type ImageMeasurer as I, type LayoutLine as L, type MeasuredBlock as M, NodeCanvasMeasureAdapter as N, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, type SegmentBreakKind as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CharPosition as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ContentBlock as f, ImageSizeAdapter as g, type LineBreaksResult as h, index as i, type MeasurementAdapter as j, PrecomputedAdapter as k, type PrecomputedAdapterOptions as l, type PreparedSegment as m, type ReactiveBlockLayoutOptions as n, type ReactiveLayoutBundle as o, type ReactiveLayoutOptions as p, type SegmentMeasureStats as q, SvgBoundsAdapter as r, type SvgMeasurer as s, analyzeAndMeasure as t, computeBlockFlow as u, computeCharPositions as v, computeLineBreaks as w, computeTotalHeight as x, measureBlock as y, measureBlocks as z };