@vyaz/core 0.0.4 → 0.0.6

package/dist/layout/AutoFitEngine.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AutoFitEngine.ts — proportional font-size scaling (autofit).
+ *
+ * Algorithm: binary search for scale in [0.0, 1.0].
+ * For each candidate scale: temporarily scale fontSize,
+ * run full layout, check whether the result fits in
+ * maxWidth × maxHeight.
+ *
+ * Proportions are preserved: every TextRun's fontSize is multiplied
+ * by the same scale, the visual hierarchy is unchanged.
+ * inlineWidget dimensions are NOT scaled (images keep their size).
+ */
+import type { TextFrame } from '../types/Document.js';
+/** Autofit options */
+export interface AutoFitOptions {
+    minScale?: number;
+    tolerance?: number;
+    maxIterations?: number;
+}
+/** Autofit result */
+export interface AutoFitResult {
+    scaleFactor: number;
+}
+/**
+ * Apply a scale factor to all fontSize values in the document.
+ * inlineWidget dimensions are NOT scaled.
+ * Returns a NEW document (does not mutate the original).
+ */
+export declare function applyScale(doc: TextFrame, scale: number): TextFrame;
+/**
+ * Find the optimal scale factor for a document.
+ *
+ * @param doc — source document
+ * @param layoutFn — layout(doc) → { height: number; width: number }
+ * @param config — autofit maxWidth/maxHeight
+ * @param options — search precision
+ */
+export declare function findScale(doc: TextFrame, layoutFn: (scaledDoc: TextFrame) => {
+    height: number;
+    width: number;
+}, config: {
+    maxWidth: number;
+    maxHeight: number;
+}, options?: AutoFitOptions): AutoFitResult;

package/dist/layout/LineBoxValidator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LineBoxValidator.ts — invariant checks and YAML serialization.
+ *
+ * Parley-inspired invariant checks:
+ *   NO_OVERLAP, MONOTONIC_Y, INDEX_CONSIST, WIDTH_FIT, BASELINE_EQ
+ *
+ * YAML snapshots: semantic data only (no metric noise).
+ */
+import type { Line } from '../types/LayoutTypes.js';
+export interface InvariantError {
+    invariant: string;
+    message: string;
+    details?: any;
+}
+/**
+ * Check all 5 invariants for a Line array.
+ * Throws on first violation.
+ */
+export declare function assertLineInvariants(lines: Line[], originalText: string, maxWidth: number): void;
+/**
+ * Convert Line[] to YAML string for snapshots.
+ * Only semantic data: text, x, width, style.
+ * No glyphAdvances, fontMetrics (noise), inlineWidget.
+ */
+export declare function linesToYAML(lines: Line[], paragraphWidth: number, paragraphHeight: number): string;

package/dist/layout/ParagraphLayoutEngine.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ParagraphLayoutEngine.ts — main orchestrator.
+ *
+ * Pipeline:
+ *   Paragraph
+ *   → compile (DocumentCompiler)
+ *   → prepareRichInline (pretext)
+ *   → walkRichInlineLineRanges + materializeRichInlineLineRange (pretext)
+ *   → positionLines (PositioningEngine)
+ *   → assertLineInvariants (LineInvariants)
+ *
+ * Supports autofit via AutoFitEngine.findScale.
+ * Caches PreparedRichInline per paragraph key (Parley LayoutContext pattern).
+ */
+import '../measure/canvas-polyfill.js';
+import type { Paragraph, ListStyle } from '../types/Document.js';
+import type { IFontMetricsProvider } from '../types/FontTypes.js';
+import type { ParagraphLayoutResult } from '../types/LayoutTypes.js';
+export declare class ParagraphLayoutEngine {
+    private preparedCache;
+    /**
+     * Layout a single paragraph — basic variant.
+     *
+     * @param paragraph — input paragraph
+     * @param maxWidth — available container width (px)
+     * @param fontProvider — optional metrics provider (default: fontMetricsProvider)
+     * @returns ParagraphLayoutResult with Line[]
+     */
+    layout(paragraph: Paragraph, maxWidth: number, yOffset?: number, fontProvider?: IFontMetricsProvider, listStyle?: ListStyle, listIndex?: number, listMarkerWidth?: number): ParagraphLayoutResult;
+    /**
+     * Layout with per-glyph advance widths (for SVG glyph mode).
+     *
+     * glyphAdvances are now filled by layout() automatically, so
+     * this method is equivalent to layout(). Kept for API compatibility.
+     */
+    layoutGlyph(paragraph: Paragraph, maxWidth: number, yOffset?: number): ParagraphLayoutResult;
+    /**
+     * Compute per-character advance widths via FontEngine (fontkit).
+     * Returns Float32Array for memory efficiency and faster iteration.
+     *
+     * Throws FontNotFoundError if the font is not registered.
+     */
+    private computeGlyphAdvances;
+}
+/** Singleton */
+export declare const paragraphLayoutEngine: ParagraphLayoutEngine;

package/dist/layout/PositioningEngine.d.ts

@@ -0,0 +1,68 @@
+/**
+ * PositioningEngine.ts — pure X/Y positioning math.
+ *
+ * Takes pretext output (spans with fragments) + font metrics +
+ * paragraph style → returns Line[] with absolute coordinates.
+ *
+ * X: alignment (left/center/right/justify) + indent
+ * Y: baseline + lineHeight + spaceBefore/After
+ * Justify: fragmented approach (each space → separate Span)
+ *
+ * Specs:
+ * - CSS Text Module Level 3/4 (browser mode)
+ * - ISO/IEC 29500 (Office Open XML / DrawingML, office mode)
+ * - Parley alignment.rs (conceptually close, but here justify is simpler:
+ *   slack is divided equally among stretchable space-spans,
+ *   without mutating ClusterData.advance)
+ */
+import type { ParagraphStyle, ListStyle } from '../types/Document.js';
+import type { FontMetrics } from '../types/FontTypes.js';
+import type { Line } from '../types/LayoutTypes.js';
+import type { PreparedRichInlineItem } from '../compile/DocumentCompiler.js';
+interface PretextFragment {
+    itemIndex: number;
+    text: string;
+    gapBefore: number;
+    occupiedWidth: number;
+    start: {
+        segmentIndex: number;
+        graphemeIndex: number;
+    };
+    end: {
+        segmentIndex: number;
+        graphemeIndex: number;
+    };
+}
+interface PretextLine {
+    fragments: PretextFragment[];
+    width: number;
+    end: {
+        segmentIndex: number;
+        graphemeIndex: number;
+    };
+}
+/**
+ * Build Line[] from pretext lines with alignment and metrics.
+ *
+ * @param pretextLines — pretext result (materializeRichInlineLineRange)
+ * @param items — original PreparedRichInlineItem[] (for metadata)
+ * @param fontMetricsFn — function to get font metrics for a span
+ * @param style — paragraph style
+ * @param maxWidth — available container width
+ * @param startY — initial Y position
+ * @param mode — metric mode ('browser' | 'office'), affects line height calculation
+ * @param tag — optional tag for debugging
+ * @param measureText — function to measure text width accurately via fontkit.
+ *   The function accepts (text, fontSize, fontFamily, fontWeight, fontStyle)
+ *   and returns width in px. Throws FontNotFoundError if font not registered.
+ * @param listStyle — optional list configuration (bullet / numbered)
+ * @param listIndex — current index in the list (for numbered lists). 1-based.
+ * @param listMarkerWidth — pre-computed width of the widest marker in the list group.
+ *   When provided, bulletIndent is expanded to this value if needed.
+ * @returns { lines: Line[], contentWidth: number }
+ */
+export declare function positionLines(pretextLines: PretextLine[], items: PreparedRichInlineItem[], fontMetricsFn: (item: PreparedRichInlineItem) => FontMetrics, style: ParagraphStyle, maxWidth: number, startY: number | undefined, mode: "browser" | "office" | undefined, measureText: (text: string, fontSize: number, fontFamily?: string, fontWeight?: string, fontStyle?: string) => number, tag?: string, listStyle?: ListStyle, listIndex?: number, listMarkerWidth?: number): {
+    lines: Line[];
+    contentWidth: number;
+};
+export {};

package/dist/layout/TextFrameLayoutEngine.d.ts

@@ -0,0 +1,50 @@
+/**
+ * TextFrameLayoutEngine.ts — Layout a full TextFrame (multi-paragraph).
+ *
+ * Pipeline:
+ *   TextFrame → Paragraph[] → paragraphLayoutEngine.layout() each → merge Line[]
+ *
+ * Handles:
+ * - Paragraph stacking with Y offset accumulation
+ * - Multi-column layout (CSS multi-column model)
+ * - Padding (left reduces available width, left shifts X)
+ * - frame.width/height optional → fitHorizontal/fitVertical flags
+ * - List grouping: consecutive paragraphs with listStyle form a list group.
+ *   Numbered list indices are auto-incremented within each group.
+ *   `listRestart: true` breaks a group and restarts numbering.
+ *
+ * Multi-column algorithm:
+ *   1. Calculate colWidth = (frameWidth - (count-1)*gap - padding) / count
+ *   2. Layout each paragraph with maxWidth = colWidth (NOT frame.width)
+ *   3. Distribute lines column-by-column (column-fill: auto)
+ *   4. If frame.height is set, lines overflow to next column when colHeight exceeded
+ *   5. If no frame.height, columns are infinite (all lines stay in column 0)
+ */
+import type { TextFrame } from '../types/Document.js';
+import type { Line } from '../types/LayoutTypes.js';
+/**
+ * Result of laying out a full TextFrame.
+ *
+ * `fitHorizontal` / `fitVertical` tell the renderer which dimension to use:
+ * - `'frame'`   → use `frameWidth` / `frameHeight`
+ * - `'content'` → use `contentWidth` / `contentHeight`
+ */
+export interface TextFrameLayoutResult {
+    lines: Line[];
+    /** Frame width (set when TextFrame.width was provided). */
+    frameWidth?: number;
+    /** Frame height (set when TextFrame.height was provided). */
+    frameHeight?: number;
+    /** Actual content width (may exceed frameWidth when wrap=false). */
+    contentWidth: number;
+    /** Actual content height (may exceed frameHeight). */
+    contentHeight: number;
+    /** Whether horizontal dimension should use frame or content size. */
+    fitHorizontal: 'frame' | 'content';
+    /** Whether vertical dimension should use frame or content size. */
+    fitVertical: 'frame' | 'content';
+}
+/**
+ * Layout a full TextFrame by stacking paragraphs with Y offset accumulation.
+ */
+export declare function layoutTextFrame(frame: TextFrame): TextFrameLayoutResult;

package/dist/layout/estimateWidth.d.ts

@@ -0,0 +1,36 @@
+/**
+ * estimateWidth.ts — per-fragment width resolution.
+ *
+ * Uses exact measurement via FontMetricsProvider.measureText() (fontkit).
+ * After measurement — correctToSumInvariant to preserve line-breaking invariant.
+ */
+/**
+ * Correct fragment widths so that their sum equals occupiedWidth.
+ *
+ * Why needed: fontkit-based measurement measures each fragment independently,
+ * so the sum may drift from occupiedWidth due to:
+ *   - kerning across fragment boundaries
+ *   - letterSpacing adjustments from pretext
+ *   - rounding differences between font parsers
+ *
+ * The correction distributes delta proportionally to each measured width.
+ * For fallback estimates (which already sum to occupiedWidth exactly),
+ * this is effectively a no-op.
+ */
+export declare function correctToSumInvariant(measured: number[], occupiedWidth: number): number[];
+export type MeasureFn = (text: string) => number;
+/**
+ * Resolve widths for fragments of a single text group.
+ *
+ * Each group consists of pieces split from the same pretext fragment
+ * (e.g. leading-space + trimmed-text + trailing-space). Their widths
+ * must sum to occupiedWidth (pretext's measurement) to preserve the
+ * line-breaking invariant.
+ *
+ * @param fragments    — array of text pieces (e.g. [" ", "between", " form"])
+ * @param fullText     — concatenation of all fragments (the original pretext fragment text)
+ * @param occupiedWidth — total width from pretext (gapBefore + textWidth)
+ * @param measureFn    — optional callback for exact measurement via font metrics provider
+ * @returns widths that sum to occupiedWidth (within floating point tolerance)
+ */
+export declare function resolveFragmentWidths(fragments: string[], fullText: string, occupiedWidth: number, measureFn: MeasureFn): number[];

package/dist/measure/FontEngine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * FontEngine.ts — unified facade over fontkit.
+ *
+ * Is the single entry point for all fontkit operations:
+ *   - create(buffer) → font face
+ *   - getGlyphAdvance(font, codePoint) → per‑glyph advance
+ *   - getMetrics(font) → structured metric values
+ *
+ * fontkit works in both Node.js (native addon) and browser (dist/browser-module.mjs).
+ * Bundlers pick the correct entry automatically when `package.json` browser map
+ * is removed (or when the import is not blocked by stubs).
+ */
+import type { FontMetrics } from '../types/FontTypes.js';
+/** Opaque font face handle returned by FontEngine.create() */
+export interface FontFace {
+    /** fontkit font object (private — not meant for direct access) */
+    readonly _raw: any;
+    /** Cached values extracted once after creation */
+    readonly unitsPerEm: number;
+    readonly ascent: number;
+    readonly descent: number;
+    readonly capHeight: number;
+    readonly winAscent: number | null;
+    readonly winDescent: number | null;
+}
+/**
+ * Create a font face from a binary buffer.
+ *
+ * @param buffer  Font file bytes (ArrayBuffer in browser, Uint8Array/Buffer in Node.js)
+ * @returns       Opaque FontFace handle
+ */
+export declare function createFontFace(buffer: ArrayBuffer | Uint8Array): Promise<FontFace>;
+/**
+ * Get the advance width (in font units) for a single code point.
+ *
+ * @returns advance width in font units, or `null` if the glyph is missing
+ */
+export declare function getGlyphAdvance(font: FontFace, codePoint: number): number | null;
+/**
+ * Compute pixel‑scale metrics for a given font size.
+ */
+export declare function computePixelMetrics(font: FontFace, fontSize: number, mode: 'browser' | 'office'): FontMetrics;
+/**
+ * Whether the fontkit module was successfully loaded.
+ * Useful for tests to verify the bundler isn't blocking fontkit.
+ */
+export declare function isFontEngineAvailable(): Promise<boolean>;

package/dist/measure/FontMetricsProvider.d.ts

@@ -0,0 +1,49 @@
+/**
+ * FontMetricsProvider.ts — isomorphic font metrics provider.
+ *
+ * Strategy (priority):
+ *   1. FontEngine (fontkit) — from registered buffer
+ *      - 'browser' mode: hhea.ascender / hhea.descender
+ *      - 'office'  mode: OS/2.usWinAscent / OS/2.usWinDescent
+ *   2. Canvas TextMetrics (browser fallback when fontkit unavailable)
+ *
+ * Uses FontEngine as the single entry point for all fontkit operations.
+ */
+import type { FontMetrics, IFontMetricsProvider } from '../types/FontTypes.js';
+import type { FontFace } from './FontEngine.js';
+/**
+ * Factor used when a glyph is not found in the font.
+ * Multiplied by fontSize to estimate the missing glyph width.
+ * Used across all measurement code paths (ParagraphLayoutEngine, canvas-polyfill).
+ */
+export declare const MISSING_GLYPH_FACTOR = 0.5;
+export declare class FontMetricsProvider implements IFontMetricsProvider {
+    /** Map<string, FontFace> — font engine font face cache */
+    private cache;
+    private metricsCache;
+    private mode;
+    setMode(mode: 'browser' | 'office'): void;
+    getMode(): 'browser' | 'office';
+    /**
+     * Register a binary font for use with fontkit.
+     *
+     * In both Node.js and browser the font is loaded via FontEngine.
+     * In the browser the caller must provide font bytes (e.g. fetched via
+     * `getFontBuffer()` from `../utils/font.js`).
+     *
+     * @param source      Font file bytes (ArrayBuffer / Uint8Array), or a URL string
+     * @param sourcePath  Optional filesystem path (used for @napi-rs/canvas in Node.js)
+     */
+    registerFont(family: string, options: {
+        weight?: string;
+        style?: string;
+    }, source: string | ArrayBuffer | Uint8Array, sourcePath?: string): Promise<void>;
+    /**
+     * Get font engine FontFace object for per-character calculations.
+     * Returns undefined if font is not registered.
+     */
+    getFont(family: string, weight?: string, style?: string): FontFace | undefined;
+    getMetrics(fontFamily: string, fontSize: number, weight?: string, style?: string): FontMetrics;
+}
+/** Singleton */
+export declare const fontMetricsProvider: FontMetricsProvider;

package/dist/measure/FontNotFoundError.d.ts

@@ -0,0 +1,6 @@
+/**
+ * FontNotFoundError.ts — thrown when a requested font is not registered.
+ */
+export declare class FontNotFoundError extends Error {
+    constructor(family: string, weight?: string, style?: string);
+}

package/dist/measure/SystemFontRegistry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SystemFontRegistry.ts — singleton that scans system fonts using `get-system-fonts`
+ * and registers them in FontMetricsProvider for both fontkit and @napi-rs/canvas.
+ *
+ * Usage:
+ *   import { systemFontRegistry } from './SystemFontRegistry.js';
+ *   await systemFontRegistry.scan();
+ *   console.log(systemFontRegistry.getRegisteredFamilies());
+ *
+ * ⚠️ Node.js built-in module imports are dynamic (lazy) to avoid
+ * Vite/Webpack externalization errors in browser builds.
+ */
+interface ScanResult {
+    /** Total font files found on the system */
+    total: number;
+    /** Number of successfully registered font files */
+    registered: number;
+}
+export declare class SystemFontRegistry {
+    private static _instance;
+    /** Map of registered family names → true */
+    private registered;
+    private constructor();
+    static get instance(): SystemFontRegistry;
+    /**
+     * Scan the system for all fonts and register them in FontMetricsProvider.
+     *
+     * - Uses `get-system-fonts` to find all .ttf/.otf files
+     * - Opens each with fontkit to extract familyName/subfamilyName
+     * - Registers in fontMetricsProvider (fontkit buffer + canvas path)
+     *
+     * @returns stats about what was found and registered
+     */
+    scan(): Promise<ScanResult>;
+    /**
+     * Check if a font family is registered.
+     */
+    isRegistered(family: string): boolean;
+    /**
+     * Get list of all registered font families.
+     */
+    getRegisteredFamilies(): string[];
+}
+/** Singleton instance */
+export declare const systemFontRegistry: SystemFontRegistry;
+export {};

package/dist/measure/canvas-polyfill.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canvas API polyfill for Bun/Node.js via @napi-rs/canvas.
+ *
+ * Required by @chenglou/pretext in server environments (Bun/Node.js without DOM).
+ *
+ * Two levels of polyfill:
+ *   1. globalThis.document.createElement('canvas') — pretext uses this
+ *      inside prepare() to create a temporary Canvas and call measureText.
+ *   2. OffscreenCanvas — for some libraries and early versions.
+ *
+ * Exports enableOfficeTextMeasure / disableOfficeTextMeasure —
+ * ctx.measureText override for FontEngine-based measurements in Office mode.
+ *
+ * ⚠️ All Node.js built-in module imports are dynamic (lazy) to avoid
+ * Vite/Webpack externalization errors in browser builds.
+ */
+/**
+ * Register a font with @napi-rs/canvas so ctx.measureText() works in Node.js.
+ * No-op in browser or when @napi-rs/canvas is not available.
+ */
+export declare function registerCanvasFont(fontPath: string, family: string): void;
+/**
+ * Enable Office measurement: replaces ctx.measureText with FontEngine-based version.
+ * @param fontCache — Map<family_weight_style, FontFace> from FontMetricsProvider
+ */
+export declare function enableOfficeTextMeasure(fontCache: Map<string, any>): void;
+/**
+ * Restore original ctx.measureText.
+ */
+export declare function disableOfficeTextMeasure(): void;