@vyaz/core 0.0.1

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@vyaz/core",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["dist", "src"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun"
+  },
+  "dependencies": {
+    "@chenglou/pretext": "^0.0.8",
+    "@clean-jsdoc-theme/typedoc": "^5.0.6",
+    "@napi-rs/canvas": "^1.0.1",
+    "fontkit": "^2.0.4",
+    "js-yaml": "^5.0.0",
+    "typedoc": "^0.28.19"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0"
+  }
+}

package/src/compile/DocumentCompiler.ts

@@ -0,0 +1,94 @@
+/**
+ * DocumentCompiler.ts — compile Paragraph → PreparedRichInlineItem[].
+ *
+ * Each TextRun becomes a RichInlineItem for pretext.
+ * inline-box: text → \uFFFC, dimensions in metadata.inlineWidget.
+ * super/sub: fontSize *= 0.65, baselineOffset in metadata.
+ *
+ * Simple JSON-serialisable format — does not depend on pretext directly.
+ */
+
+import type { Paragraph, TextRun } from '../types/Document.js';
+
+/** Font token for pretext: "${style}_${weight}_${fontSize}_${family}" */
+export function makeFontToken(run: TextRun, effectiveFontSize: number): string {
+  const fontStyle = run.fontStyle || 'normal';
+  const fontWeight = run.fontWeight || 400;
+  return `${fontStyle} ${fontWeight} ${effectiveFontSize}px ${run.fontFamily}`;
+}
+
+/** Compilation context (passed to pretext) */
+export interface PreparedRichInlineItem {
+  text: string;
+  font: string;
+  letterSpacing?: number;
+  extraWidth?: number;         // padding, border for inline-box
+  break?: 'normal' | 'never';  // for atomic chips
+  metadata: {
+    originalRunIndex: number;
+    baselineOffset: number;
+    effectiveFontSize: number;
+    style: TextRun;
+    inlineWidget?: TextRun['inlineWidget'];
+  };
+}
+
+const SUPER_SUB_SCALE = 0.65;
+const SUPER_OFFSET_RATIO = -0.4;
+const SUB_OFFSET_RATIO = 0.15;
+
+/**
+ * Compile a paragraph into PreparedRichInlineItem[].
+ */
+export function compileParagraph(paragraph: Paragraph): PreparedRichInlineItem[] {
+  const items: PreparedRichInlineItem[] = [];
+
+  for (let i = 0; i < paragraph.children.length; i++) {
+    const run = paragraph.children[i];
+
+    // Compute effective fontSize and baselineOffset
+    let effectiveFontSize = run.fontSize;
+    let baselineOffset = 0;
+
+    if (run.script === 'super') {
+      effectiveFontSize = run.fontSize * SUPER_SUB_SCALE;
+      baselineOffset = run.fontSize * SUPER_OFFSET_RATIO;
+    } else if (run.script === 'sub') {
+      effectiveFontSize = run.fontSize * SUPER_SUB_SCALE;
+      baselineOffset = run.fontSize * SUB_OFFSET_RATIO;
+    }
+
+    // Inline-box: text → \uFFFC
+    const text = run.type === 'inline-box' ? '\uFFFC' : run.text;
+
+    const item: PreparedRichInlineItem = {
+      text,
+      font: makeFontToken(run, effectiveFontSize),
+      letterSpacing: run.letterSpacing,
+      metadata: {
+        originalRunIndex: i,
+        baselineOffset,
+        effectiveFontSize,
+        style: { ...run, fontSize: effectiveFontSize },
+        inlineWidget: run.inlineWidget,
+      },
+    };
+
+    // Inline-box: add extraWidth and break: 'never'
+    if (run.type === 'inline-box' && run.inlineWidget) {
+      item.extraWidth = run.inlineWidget.width;
+      item.break = 'never';
+    }
+
+    items.push(item);
+  }
+
+  return items;
+}
+
+/**
+ * Get the full text of a paragraph (for INDEX_CONSIST checks).
+ */
+export function getParagraphText(paragraph: Paragraph): string {
+  return paragraph.children.map(r => r.text).join('');
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @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,
+} from './types/Document.js';
+export {
+  DEFAULT_PARAGRAPH_STYLE,
+  DEFAULT_TEXT_STYLE,
+} from './types/Document.js';
+
+// ── Output types (Physical Box Model) ───────────────────────────────────
+export type {
+  ParagraphLayoutResult,
+  LineBox,
+  FragmentBox,
+  FragmentFontMetrics,
+  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 { positionLineBoxes } from './layout/PositioningEngine.js';
+export { assertLineBoxInvariants, lineBoxToYAML } 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';
+
+// ── Compiler ────────────────────────────────────────────────────────────
+export { compileParagraph, getParagraphText, makeFontToken } from './compile/DocumentCompiler.js';
+export type { PreparedRichInlineItem } from './compile/DocumentCompiler.js';
+
+// ── Font metrics ────────────────────────────────────────────────────────
+export { FontMetricsProvider, fontMetricsProvider } from './measure/FontMetricsProvider.js';
+
+

package/src/layout/AutoFitEngine.ts

@@ -0,0 +1,101 @@
+/**
+ * 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

@@ -0,0 +1,161 @@
+/**
+ * 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 { LineBox, FragmentBox, 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 LineBox array.
+ * Throws on first violation.
+ */
+export function assertLineBoxInvariants(
+  lines: LineBox[],
+  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 fragments in a line have the same baseline
+    if (line.fragments.length > 1) {
+      const firstBaseline = line.baseline;
+      for (let j = 0; j < line.fragments.length; j++) {
+        const frag = line.fragments[j];
+        const fragBaseline = frag.fontMetrics.ascent;
+        if (Math.abs(fragBaseline - firstBaseline) > EPSILON) {
+          // NOTE: baseline may differ for super/sub — that's normal
+          // So we only check that baseline is set
+          if (fragBaseline <= 0) {
+            errors.push({
+              invariant: 'BASELINE_EQ',
+              message: `Line ${i}, fragment ${j}: baseline=${fragBaseline} 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 ─────────────────────────────────────────────────
+
+/** Fragment style label for snapshot */
+function fragmentStyleLabel(frag: FragmentBox): 'bold' | 'italic' | 'normal' {
+  if (frag.style.fontStyle === 'italic') return 'italic';
+  const w = frag.style.fontWeight;
+  if (w === 'bold' || w === 700) return 'bold';
+  return 'normal';
+}
+
+/**
+ * Convert LineBox[] to YAML string for snapshots.
+ * Only semantic data: text, x, width, style.
+ * No glyphAdvances, fontMetrics (noise), inlineWidget.
+ */
+export function lineBoxToYAML(
+  lines: LineBox[],
+  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.fragments.map(frag => ({
+        text: frag.text,
+        x: Math.round(frag.x * 100) / 100,
+        width: Math.round(frag.width * 100) / 100,
+        ...(fragmentStyleLabel(frag) !== 'normal' ? { style: fragmentStyleLabel(frag) } : {}),
+      })),
+    })),
+  };
+
+  return dump(obj, {
+    indent: 2,
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+  });
+}

package/src/layout/ParagraphLayoutEngine.ts

@@ -0,0 +1,202 @@
+/**
+ * ParagraphLayoutEngine.ts — main orchestrator.
+ *
+ * Pipeline:
+ *   Paragraph
+ *   → compile (DocumentCompiler)
+ *   → prepareRichInline (pretext)
+ *   → walkRichInlineLineRanges + materializeRichInlineLineRange (pretext)
+ *   → positionLineBoxes (PositioningEngine)
+ *   → assertLineBoxInvariants (LineBoxValidator)
+ *
+ * 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 } 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 } from '../measure/FontMetricsProvider.js';
+import { positionLineBoxes } from './PositioningEngine.js';
+import { assertLineBoxInvariants } from './LineBoxValidator.js';
+
+// @ts-ignore
+import { prepareRichInline, materializeRichInlineLineRange, walkRichInlineLineRanges, type PreparedRichInline } from '@chenglou/pretext/rich-inline';
+
+// ── 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, no per-glyph data.
+   *
+   * @param paragraph — input paragraph
+   * @param maxWidth — available container width (px)
+   * @param fontProvider — optional metrics provider (default: fontMetricsProvider)
+   * @returns ParagraphLayoutResult with LineBox[]
+   */
+  layout(
+    paragraph: Paragraph,
+    maxWidth: number,
+    yOffset: number = 0,
+    fontProvider?: IFontMetricsProvider,
+  ): 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
+    // CSS white-space: nowrap → disable wrapping (infinite width)
+    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();
+    const { lines, contentWidth } = positionLineBoxes(
+      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,
+      paragraph.id,
+    );
+
+    // Phase 5: Validate
+    assertLineBoxInvariants(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).
+   *
+   * After basic layout, fills FragmentBox.glyphAdvances
+   * via fontkit for each text fragment.
+   *
+   * @param paragraph — input paragraph
+   * @param maxWidth — available container width (px)
+   * @param yOffset — starting Y position
+   * @returns ParagraphLayoutResult with glyphAdvances[]
+   */
+  layoutGlyph(
+    paragraph: Paragraph,
+    maxWidth: number,
+    yOffset: number = 0,
+  ): ParagraphLayoutResult {
+    const result = this.layout(paragraph, maxWidth, yOffset);
+
+    for (const line of result.lines) {
+      for (const frag of line.fragments) {
+        if (frag.type === 'text' && frag.text.length > 0) {
+          frag.glyphAdvances = this.computeGlyphAdvances(
+            frag.text,
+            frag.style.fontFamily,
+            frag.fontMetrics.fontSize,
+            String(frag.style.fontWeight || 400),
+            frag.style.fontStyle || 'normal',
+          );
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Compute per-character advance widths via fontkit.
+   */
+  private computeGlyphAdvances(
+    text: string,
+    fontFamily: string,
+    fontSize: number,
+    weight: string,
+    style: string,
+  ): number[] {
+    const font = fontMetricsProvider.getFont(fontFamily, weight, style);
+    if (!font) {
+      // Fallback: uniform distribution
+      const avgWidth = fontSize * 0.6;
+      return Array.from(text).map(() => avgWidth);
+    }
+
+    const scale = fontSize / font.unitsPerEm;
+    const advances: number[] = [];
+
+    for (let i = 0; i < text.length; i++) {
+      const codePoint = text.codePointAt(i)!;
+      const glyph = font.glyphForCodePoint(codePoint);
+      if (glyph) {
+        advances.push(glyph.advanceWidth * scale);
+      } else {
+        // Missing glyph
+        advances.push(fontSize * 0.5);
+      }
+      // Skip surrogate pair
+      if (codePoint > 0xffff) i++;
+    }
+
+    return advances;
+  }
+}
+
+/** Singleton */
+export const paragraphLayoutEngine = new ParagraphLayoutEngine();