@vyaz/core 0.0.5 → 0.0.7

package/src/index.ts

@@ -1,97 +0,0 @@
-/**
- * @vyaz/core — Public API.
- *
- * Exports input types (Logical level), output types (Physical Box Model),
- * layout engines, font metric providers, renderers, and utilities.
- */
-
-// ── Input types (Logical level) ─────────────────────────────────────────
-export type {
-  TextFrame,
-  Paragraph,
-  ParagraphStyle,
-  TextRun,
-  InlineWidget,
-  AutofitConfig,
-  TextAlignment,
-  WritingMode,
-  TextOrientation,
-  VerticalAlignment,
-  ScriptType,
-  WhiteSpace,
-  MultiColumnConfig,
-  DominantBaseline,
-  LineFitEdge,
-  TextAlignLast,
-  WordBreak,
-  LineBreak,
-  OverflowWrap,
-  TextDecorationStyle,
-  TextTransform,
-  ListType,
-  NumberFormat,
-  ListStylePosition,
-  ListStyle,
-} from './types/Document.js';
-export {
-  DEFAULT_PARAGRAPH_STYLE,
-  DEFAULT_TEXT_STYLE,
-} from './types/Document.js';
-
-// ── Output types (Physical Box Model) ───────────────────────────────────
-export type {
-  ParagraphLayoutResult,
-  Line,
-  Span,
-  SpanFontMetrics,
-  SemanticParagraph,
-  SemanticLine,
-  SemanticFragment,
-} from './types/LayoutTypes.js';
-
-// ── Font types ──────────────────────────────────────────────────────────
-export type {
-  FontMetrics,
-  IFontMetricsProvider,
-  GlyphData,
-} from './types/FontTypes.js';
-
-// ── Layout Engine ───────────────────────────────────────────────────────
-export { ParagraphLayoutEngine, paragraphLayoutEngine } from './layout/ParagraphLayoutEngine.js';
-export { positionLines } from './layout/PositioningEngine.js';
-export { assertLineInvariants, linesToYAML } from './layout/LineBoxValidator.js';
-export type { InvariantError } from './layout/LineBoxValidator.js';
-
-// ── TextFrame Layout Engine ──────────────────────────────────────────────
-export { layoutTextFrame } from './layout/TextFrameLayoutEngine.js';
-export type { TextFrameLayoutResult } from './layout/TextFrameLayoutEngine.js';
-
-// ── Autofit ─────────────────────────────────────────────────────────────
-export { applyScale, findScale } from './layout/AutoFitEngine.js';
-export type { AutoFitOptions, AutoFitResult } from './layout/AutoFitEngine.js';
-
-// ── Utils ────────────────────────────────────────────────────────────────
-export { groupLinesByParagraph } from './utils/groupLinesByParagraph.js';
-export type { ParagraphGroup } from './utils/groupLinesByParagraph.js';
-export { transformText } from './utils/textTransform.js';
-export { formatListNumber, defaultBulletChar, BULLET_CHARACTERS } from './utils/list.js';
-
-// ── Compiler ────────────────────────────────────────────────────────────
-export { compileParagraph, getParagraphText, makeFontToken } from './compile/DocumentCompiler.js';
-export type { PreparedRichInlineItem } from './compile/DocumentCompiler.js';
-
-// ── Font Engine ──────────────────────────────────────────────────────────
-export type { FontFace } from './measure/FontEngine.js';
-export { createFontFace, getGlyphAdvance, computePixelMetrics, isFontEngineAvailable } from './measure/FontEngine.js';
-
-// ── Font metrics ────────────────────────────────────────────────────────
-export { FontMetricsProvider, fontMetricsProvider } from './measure/FontMetricsProvider.js';
-
-// ── System font registry ────────────────────────────────────────────────
-export { SystemFontRegistry, systemFontRegistry } from './measure/SystemFontRegistry.js';
-
-// ── Font utilities ───────────────────────────────────────────────────────
-export { getFontBuffer } from './utils/font.js';
-
-// ── Errors ──────────────────────────────────────────────────────────────
-export { FontNotFoundError } from './measure/FontNotFoundError.js';

package/src/layout/AutoFitEngine.ts

@@ -1,101 +0,0 @@
-/**
- * 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;       // minimum scale (default 0.1)
-  tolerance?: number;      // binary search tolerance (default 0.01)
-  maxIterations?: number;  // max iterations (default 50)
-}
-
-/** Autofit result */
-export interface AutoFitResult {
-  scaleFactor: number;     // 0.0 … 1.0
-}
-
-/**
- * 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 function applyScale(
-  doc: TextFrame,
-  scale: number,
-): TextFrame {
-  const clone = JSON.parse(JSON.stringify(doc)) as TextFrame;
-
-  for (const paragraph of clone.paragraphs) {
-    for (const run of paragraph.children) {
-      run.fontSize = Math.round(run.fontSize * scale * 100) / 100;
-    }
-  }
-
-  if (clone.defaultStyle?.fontSize) {
-    clone.defaultStyle.fontSize = Math.round(clone.defaultStyle.fontSize * scale * 100) / 100;
-  }
-
-  return clone;
-}
-
-/**
- * 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 function findScale(
-  doc: TextFrame,
-  layoutFn: (scaledDoc: TextFrame) => { height: number; width: number },
-  config: { maxWidth: number; maxHeight: number },
-  options?: AutoFitOptions,
-): AutoFitResult {
-  const minScale = options?.minScale ?? 0.1;
-  const tolerance = options?.tolerance ?? 0.01;
-  const maxIterations = options?.maxIterations ?? 50;
-  const maxHeight = config.maxHeight;
-  const maxWidth = config.maxWidth;
-
-  // Check original size
-  const origResult = layoutFn(doc);
-  if (origResult.height <= maxHeight && origResult.width <= maxWidth) {
-    return { scaleFactor: 1 };
-  }
-
-  // Binary search
-  let lo = minScale;
-  let hi = 1.0;
-  let best = minScale;
-
-  for (let iter = 0; iter < maxIterations; iter++) {
-    const mid = (lo + hi) / 2;
-    const scaledDoc = applyScale(doc, mid);
-    const result = layoutFn(scaledDoc);
-
-    if (result.height <= maxHeight && result.width <= maxWidth) {
-      // scale is valid — try larger
-      best = mid;
-      lo = mid + tolerance / 2;
-    } else {
-      // scale is invalid — try smaller
-      hi = mid - tolerance / 2;
-    }
-
-    if (hi - lo < tolerance) break;
-  }
-
-  return { scaleFactor: Math.round(best * 100) / 100 };
-}

package/src/layout/LineBoxValidator.ts

@@ -1,162 +0,0 @@
-/**
- * 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 { dump } from 'js-yaml';
-import type { Line, Span, SemanticParagraph } from '../types/LayoutTypes.js';
-
-const EPSILON = 0.5; // subpixel tolerance
-
-// ── Invariant guard ────────────────────────────────────────────────────
-
-export interface InvariantError {
-  invariant: string;
-  message: string;
-  details?: any;
-}
-
-/**
- * Check all 5 invariants for a Line array.
- * Throws on first violation.
- */
-export function assertLineInvariants(
-  lines: Line[],
-  originalText: string,
-  maxWidth: number,
-): void {
-  if (lines.length === 0) return;
-
-  const errors: InvariantError[] = [];
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    // 1. NO_OVERLAP: lines[i+1].y >= lines[i].y + lines[i].height
-    if (i > 0) {
-      const prev = lines[i - 1];
-      if (line.y < prev.y + prev.height - EPSILON) {
-        errors.push({
-          invariant: 'NO_OVERLAP',
-          message: `Line ${i} overlaps with line ${i - 1}`,
-          details: {
-            prevY: prev.y,
-            prevHeight: prev.height,
-            prevBottom: prev.y + prev.height,
-            currentY: line.y,
-          },
-        });
-      }
-    }
-
-    // 2. MONOTONIC_Y: lines[i+1].y > lines[i].y
-    if (i > 0 && line.y <= lines[i - 1].y) {
-      errors.push({
-        invariant: 'MONOTONIC_Y',
-        message: `Line ${i} has Y=${line.y} not > prev Y=${lines[i - 1].y}`,
-      });
-    }
-
-    // 3. INDEX_CONSIST: checked below (sum of all lengths)
-    if (line.endIndex <= line.startIndex) {
-      errors.push({
-        invariant: 'INDEX_CONSIST',
-        message: `Line ${i}: endIndex=${line.endIndex} <= startIndex=${line.startIndex}`,
-      });
-    }
-
-    // 4. WIDTH_FIT: line.width <= maxWidth + epsilon
-    // When maxWidth=0 (zero-width container) allow any width
-    if (maxWidth > 0 && line.width > maxWidth + EPSILON) {
-      errors.push({
-        invariant: 'WIDTH_FIT',
-        message: `Line ${i}: width=${line.width} > maxWidth=${maxWidth}`,
-      });
-    }
-
-    // 5. BASELINE_EQ: all spans in a line have the same baseline
-    if (line.spans.length > 1) {
-      const firstBaseline = line.baseline;
-      for (let j = 0; j < line.spans.length; j++) {
-        const span = line.spans[j];
-        const spanBaseline = span.fontMetrics.ascent;
-        if (Math.abs(spanBaseline - firstBaseline) > EPSILON) {
-          // NOTE: baseline may differ for super/sub — that's normal
-          // So we only check that baseline is set
-          if (spanBaseline <= 0) {
-            errors.push({
-              invariant: 'BASELINE_EQ',
-              message: `Line ${i}, span ${j}: baseline=${spanBaseline} is invalid`,
-            });
-          }
-        }
-      }
-    }
-  }
-
-  // 3. INDEX_CONSIST: total text length
-  // Difference allowed due to trailing whitespace (pretext may drop it)
-  // const totalChars = lines.reduce((sum, l) => sum + (l.endIndex - l.startIndex), 0);
-  // if (totalChars > originalText.length + EPSILON) {
-  //   errors.push({
-  //     invariant: 'INDEX_CONSIST',
-  //     message: `Total chars in lines (${totalChars}) > original text length (${originalText.length})`,
-  //     details: { totalChars, originalLength: originalText.length },
-  //   });
-  // }
-
-  // if (errors.length > 0) {
-  //   const msg = errors.map(e => `[${e.invariant}] ${e.message}`).join('\n');
-  //   throw new Error(`LineBox invariants violated:\n${msg}`);
-  // }
-}
-
-// ── YAML serialization ─────────────────────────────────────────────────
-
-/** Span style label for snapshot */
-function spanStyleLabel(span: Span): 'bold' | 'italic' | 'normal' {
-  if (span.style.fontStyle === 'italic') return 'italic';
-  const w = span.style.fontWeight;
-  if (w === 'bold' || w === 700) return 'bold';
-  return 'normal';
-}
-
-/**
- * Convert Line[] to YAML string for snapshots.
- * Only semantic data: text, x, width, style.
- * No glyphAdvances, fontMetrics (noise), inlineWidget.
- */
-export function linesToYAML(
-  lines: Line[],
-  paragraphWidth: number,
-  paragraphHeight: number,
-): string {
-  const obj: SemanticParagraph = {
-    width: paragraphWidth,
-    height: paragraphHeight,
-    lines: lines.map(line => ({
-      y: Math.round(line.y * 100) / 100,
-      width: Math.round(line.width * 100) / 100,
-      height: Math.round(line.height * 100) / 100,
-      baseline: Math.round(line.baseline * 100) / 100,
-      fragments: line.spans.map(span => ({
-        text: span.text,
-        x: Math.round(span.x * 100) / 100,
-        width: Math.round(span.width * 100) / 100,
-        ...(spanStyleLabel(span) !== 'normal' ? { style: spanStyleLabel(span) } : {}),
-      })),
-    })),
-  };
-
-  return dump(obj, {
-    indent: 2,
-    lineWidth: 120,
-    noRefs: true,
-    sortKeys: false,
-  });
-}
-

package/src/layout/ParagraphLayoutEngine.ts

@@ -1,264 +0,0 @@
-/**
- * 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).
- */
-
-// Polyfill OffscreenCanvas for Node.js (node-canvas)
-import '../measure/canvas-polyfill.js';
-
-import type { Paragraph, ListStyle } from '../types/Document.js';
-import type { FontMetrics } from '../types/FontTypes.js';
-import type { IFontMetricsProvider } from '../types/FontTypes.js';
-import type { ParagraphLayoutResult } from '../types/LayoutTypes.js';
-import { compileParagraph, getParagraphText } from '../compile/DocumentCompiler.js';
-import type { PreparedRichInlineItem } from '../compile/DocumentCompiler.js';
-import { fontMetricsProvider, MISSING_GLYPH_FACTOR } from '../measure/FontMetricsProvider.js';
-import { FontNotFoundError } from '../measure/FontNotFoundError.js';
-import { positionLines } from './PositioningEngine.js';
-import { assertLineInvariants } from './LineBoxValidator.js';
-
-// @ts-ignore
-import { prepareRichInline, materializeRichInlineLineRange, walkRichInlineLineRanges, type PreparedRichInline } from '@chenglou/pretext/rich-inline';
-
-// ── Cache key builder ─────────────────────────────────────────────────────
-
-function glyphCacheKey(
-  text: string,
-  fontSize: number,
-  fontFamily?: string,
-  fontWeight?: string,
-  fontStyle?: string,
-): string {
-  return `${fontSize}_${fontFamily || ''}_${fontWeight || ''}_${fontStyle || ''}_${text}`;
-}
-
-// ── Helpers ─────────────────────────────────────────────────────────────
-
-/** Get FontMetrics for a PreparedRichInlineItem */
-function getFontMetricsForItem(item: PreparedRichInlineItem): FontMetrics {
-  return fontMetricsProvider.getMetrics(
-    item.metadata.style.fontFamily,
-    item.metadata.effectiveFontSize,
-    String(item.metadata.style.fontWeight || 400),
-    item.metadata.style.fontStyle || 'normal',
-  );
-}
-
-// ── ParagraphLayoutEngine ─────────────────────────────────────────────
-
-export class ParagraphLayoutEngine {
-  private preparedCache = new Map<string, PreparedRichInline>();
-
-  /**
-   * 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 = 0,
-    fontProvider?: IFontMetricsProvider,
-    listStyle?: ListStyle,
-    listIndex?: number,
-    listMarkerWidth?: number,
-  ): ParagraphLayoutResult {
-    const provider = fontProvider || fontMetricsProvider;
-
-    // Phase 1: Compile
-    const items = compileParagraph(paragraph);
-
-    // Phase 2: Prepare (cached)
-    const cacheKey = JSON.stringify(paragraph);
-    let prepared = this.preparedCache.get(cacheKey);
-    if (!prepared) {
-      prepared = prepareRichInline(items);
-      this.preparedCache.set(cacheKey, prepared);
-    }
-
-    // Phase 3: Layout — walk lines
-    const effectiveMaxWidth = paragraph.style.whiteSpace === 'nowrap' ? Infinity : maxWidth;
-    const pretextLines: any[] = [];
-    walkRichInlineLineRanges(prepared, effectiveMaxWidth, (range: any) => {
-      pretextLines.push(range);
-    });
-
-    // Materialize each line
-    const materializedLines: any[] = [];
-    for (const range of pretextLines) {
-      materializedLines.push(materializeRichInlineLineRange(prepared, range));
-    }
-
-    // Phase 4: Position
-    const renderMode = provider.getMode();
-
-    // Per-layout glyph cache: map<text+font+size, Float32Array>
-    // Lives only for the duration of one layout() call.
-    const glyphCache = new Map<string, Float32Array>();
-
-    // Build measureText callback: single fontkit pass, caches advances.
-    const measureTextFn = (
-      text: string,
-      fontSize: number,
-      fontFamily?: string,
-      fontWeight?: string,
-      fontStyle?: string,
-    ): number => {
-      if (!text) return 0;
-      const key = glyphCacheKey(text, fontSize, fontFamily, fontWeight, fontStyle);
-
-      // Check cache first — same text+font may appear across multiple fragments
-      let advances = glyphCache.get(key);
-      if (!advances) {
-        advances = this.computeGlyphAdvances(text, fontSize, fontFamily, fontWeight, fontStyle);
-        glyphCache.set(key, advances);
-      }
-
-      let total = 0;
-      for (let i = 0; i < advances.length; i++) total += advances[i];
-      return Math.round(total * 100) / 100;
-    };
-
-    const { lines, contentWidth } = positionLines(
-      materializedLines,
-      items,
-      (item) => {
-        if (fontProvider) {
-          return fontProvider.getMetrics(
-            item.metadata.style.fontFamily,
-            item.metadata.effectiveFontSize,
-            String(item.metadata.style.fontWeight || 400),
-            item.metadata.style.fontStyle || 'normal',
-          );
-        }
-        return getFontMetricsForItem(item);
-      },
-      paragraph.style,
-      maxWidth,
-      yOffset,
-      renderMode,
-      measureTextFn,
-      paragraph.id,
-      paragraph.style.listStyle,
-      paragraph.style.listStyle ? (listIndex ?? 1) : undefined,
-      listMarkerWidth,
-    );
-
-    // Phase 4b: Fill per-glyph advances — pull from cache or compute if miss
-    for (const line of lines) {
-      for (const span of line.spans) {
-        if (span.type === 'text' && span.text.length > 0 && !span.inlineWidget && !span.glyphAdvances) {
-          const key = glyphCacheKey(
-            span.text,
-            span.fontMetrics.fontSize,
-            span.style.fontFamily,
-            String(span.style.fontWeight || 400),
-            span.style.fontStyle || 'normal',
-          );
-          const cached = glyphCache.get(key);
-          if (cached) {
-            span.glyphAdvances = Array.from(cached);
-          } else {
-            // Cache miss (single-fragment spans skip resolveFragmentWidths),
-            // compute directly.
-            span.glyphAdvances = Array.from(this.computeGlyphAdvances(
-              span.text,
-              span.fontMetrics.fontSize,
-              span.style.fontFamily,
-              String(span.style.fontWeight || 400),
-              span.style.fontStyle || 'normal',
-            ));
-          }
-        }
-      }
-    }
-
-    // Phase 5: Validate
-    assertLineInvariants(lines, getParagraphText(paragraph), maxWidth);
-
-    // Phase 6: Compute height
-    const totalHeight = lines.length > 0
-      ? lines[lines.length - 1].y + lines[lines.length - 1].height + (paragraph.style.spaceAfter || 0)
-      : 0;
-
-    // Phase 7: Content BBox
-    const contentHeight = lines.length > 0
-      ? lines[lines.length - 1].y + lines[lines.length - 1].height
-      : 0;
-
-    return { width: maxWidth, height: totalHeight, lines, contentWidth, contentHeight };
-  }
-
-  /**
-   * 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 = 0,
-  ): ParagraphLayoutResult {
-    return this.layout(paragraph, maxWidth, yOffset);
-  }
-
-  /**
-   * 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(
-    text: string,
-    fontSize: number,
-    fontFamily?: string,
-    fontWeight?: string,
-    fontStyle?: string,
-  ): Float32Array {
-    const font = fontMetricsProvider.getFont(
-      fontFamily || 'Arial',
-      fontWeight || '400',
-      fontStyle || 'normal',
-    );
-    if (!font) {
-      throw new FontNotFoundError(
-        fontFamily || 'Arial',
-        fontWeight || '400',
-        fontStyle || 'normal',
-      );
-    }
-
-    const scale = fontSize / font.unitsPerEm;
-    const advances = new Float32Array(text.length);
-
-    for (let i = 0; i < text.length; i++) {
-      const codePoint = text.codePointAt(i)!;
-      const advance = font._raw.glyphForCodePoint(codePoint)?.advanceWidth;
-      if (advance != null) {
-        advances[i] = advance * scale;
-      } else {
-        advances[i] = fontSize * MISSING_GLYPH_FACTOR;
-      }
-      if (codePoint > 0xffff) i++;
-    }
-
-    return advances;
-  }
-}
-
-/** Singleton */
-export const paragraphLayoutEngine = new ParagraphLayoutEngine();