@vyaz/core 0.0.4 → 0.0.5

package/README.md

@@ -0,0 +1,156 @@
+# @vyaz/core
+
+Rich text layout engine — TypeScript, isomorphic (browser + Bun/Node.js), pixel-perfect typography.
+
+Part of the [Vyaz](https://github.com/sedrew/vyaz) project. Parses styled text into positioned lines with precise font metrics, supporting both CSS Text and Office (PowerPoint/DrawingML) rendering modes.
+
+The engine operates on a **TextFrame → Paragraph → TextRun** hierarchy, following W3C CSS Text, CSS Writing Modes, and CSS Inline Layout specifications.
+
+## Installation
+
+```bash
+bun add @vyaz/core
+# or
+npm install @vyaz/core
+```
+
+## Quick Start
+
+```ts
+import { layoutTextFrame } from '@vyaz/core';
+import type { TextFrame } from '@vyaz/core';
+
+const frame: TextFrame = {
+  width: 400,
+  wrap: true,
+  paragraphs: [
+    {
+      style: { alignment: 'left', lineHeight: 1.4, spaceBefore: 0, spaceAfter: 0 },
+      children: [
+        { text: 'Hello, Vyaz!', fontFamily: 'Arial', fontSize: 16, fontWeight: 'bold', fontStyle: 'normal', color: '#000' },
+      ],
+    },
+  ],
+};
+
+const result = layoutTextFrame(frame);
+console.log(result.lines);
+```
+
+## Features
+
+- **Text frame layout** — multi-paragraph frames with padding, wrapping, and vertical alignment
+- **Multi-font, multi-style text** — bold, italic, size, color, subscript/superscript, letter-spacing
+- **Text alignment** — left, center, right, justify
+- **Line wrapping** — soft/hard breaks, `white-space` control (normal, nowrap, pre)
+- **Writing modes** — `horizontal-tb`, `vertical-rl`, `vertical-lr` with text orientation
+- **Auto-fit** — scale text proportionally to fit the container (`AutofitConfig`)
+- **Inline widgets** — embedded objects (icons, images) inside the text flow
+- **Office-compatible mode** — `mode: 'office'` for PowerPoint/DrawingML rendering
+- **Font metrics** — system font registry with fontkit-based metric extraction
+- **Compiler** — paragraph compilation with token preparation for external renderers
+
+## API Overview
+
+### Text Frame Layout
+
+```ts
+import { layoutTextFrame } from '@vyaz/core';
+import type { TextFrame, TextFrameLayoutResult } from '@vyaz/core';
+
+const frame: TextFrame = {
+  width: 600,
+  height: 400,
+  wrap: true,
+  padding: { top: 20, right: 20, bottom: 20, left: 20 },
+  verticalAlignment: 'top',
+  paragraphs: [
+    {
+      style: { alignment: 'left', lineHeight: 1.4, spaceBefore: 0, spaceAfter: 12 },
+      children: [
+        { text: 'First paragraph', fontFamily: 'Arial', fontSize: 16, fontWeight: 'normal', fontStyle: 'normal', color: '#000' },
+      ],
+    },
+  ],
+};
+
+const result: TextFrameLayoutResult = layoutTextFrame(frame);
+// → { lines: Line[], frameWidth?, frameHeight?, contentWidth, contentHeight, fitHorizontal, fitVertical }
+```
+
+### Autofit
+
+```ts
+import { applyScale, findScale } from '@vyaz/core';
+import type { AutoFitOptions, AutoFitResult } from '@vyaz/core';
+
+const scale: AutoFitResult = findScale(contentWidth, contentHeight, frameWidth, frameHeight);
+const scaledLines = applyScale(result.lines, scale);
+```
+
+### Font Registration & Metrics
+
+```ts
+import {
+  FontMetricsProvider,
+  SystemFontRegistry,
+  createFontFace,
+  getFontBuffer,
+} from '@vyaz/core';
+import type { FontMetrics, IFontMetricsProvider, FontFace } from '@vyaz/core';
+
+const provider = new FontMetricsProvider();
+
+// Node.js — register from a local file
+import { readFileSync } from 'node:fs';
+const buffer = readFileSync('/path/to/font.ttf');
+await provider.registerFont('MyFont', { weight: 'bold', style: 'normal' }, buffer);
+
+// Browser — register from a URL
+await provider.registerFont('MyFont', {}, 'https://example.com/font.woff2');
+
+// Get pixel metrics
+const metrics: FontMetrics = provider.getMetrics('MyFont', 16);
+// → { ascent, descent, capHeight, unitsPerEm, sourceTable }
+```
+
+### Compiler
+
+```ts
+import { compileParagraph, getParagraphText, makeFontToken } from '@vyaz/core';
+import type { PreparedRichInlineItem } from '@vyaz/core';
+
+const items: PreparedRichInlineItem[] = compileParagraph(paragraph, defaultStyle);
+const text: string = getParagraphText(paragraph);
+const token: string = makeFontToken(fontFamily, fontSize, fontWeight, fontStyle);
+```
+
+### Paragraph Layout Engine (low-level)
+
+```ts
+import { ParagraphLayoutEngine, paragraphLayoutEngine } from '@vyaz/core';
+
+const engine = new ParagraphLayoutEngine();
+const result = engine.layout(paragraph, maxWidth, yOffset);
+// → ParagraphLayoutResult { lines: Line[], width, height, contentWidth, contentHeight }
+```
+
+## Package Structure
+
+```
+src/
+├── compile/        — DocumentCompiler, paragraph→token compilation
+├── layout/         — Layout engines (Paragraph, TextFrame, Positioning, AutoFit)
+├── measure/        — Font metrics, fontkit integration, system font registry
+├── types/          — TypeScript type definitions (Document, Font, Layout)
+└── utils/          — Helpers (font, list, text transform, env detection)
+```
+
+## Requirements
+
+- **Runtime**: Bun 1.x, Node.js 18+, or modern browser
+- **Optional**: `@napi-rs/canvas`, `fontkit`, `get-system-fonts` for Node.js font metrics
+
+## License
+
+MIT

package/package.json

@@ -1,13 +1,30 @@
 {
   "name": "@vyaz/core",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "files": ["dist", "src"],
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "node": "./src/index.ts",
+      "browser": "./src/index.browser.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "browser": {
+    "get-system-fonts": false,
+    "fs": false,
+    "module": false,
+    "node:fs": false,
+    "child_process": false
+  },
   "scripts": {
     "build": "bun build ./src/index.ts --outdir ./dist --target bun",
     "test": "bun test"
@@ -15,15 +32,15 @@
   "dependencies": {
     "@chenglou/pretext": "^0.0.8",
     "@clean-jsdoc-theme/typedoc": "^5.0.6",
-    "fontkit": "^2.0.4",
-    "get-system-fonts": "^2.0.2",
     "js-yaml": "^5.0.0",
     "typedoc": "^0.28.19"
   },
   "optionalDependencies": {
-    "@napi-rs/canvas": "^1.0.2"
+    "@napi-rs/canvas": "^1.0.2",
+    "fontkit": "^2.0.4",
+    "get-system-fonts": "^2.0.2"
   },
   "devDependencies": {
     "@types/node": "^26.0.0"
   }
-}
+}

package/src/compile/DocumentCompiler.ts

@@ -8,8 +8,9 @@
  * Simple JSON-serialisable format — does not depend on pretext directly.
  */
 
-import type { Paragraph, TextRun } from '../types/Document.js';
+import type { Paragraph, TextRun, TextTransform } from '../types/Document.js';
 import { DEFAULT_TEXT_STYLE } from '../types/Document.js';
+import { transformText } from '../utils/textTransform.js';
 
 // ── Font Weight normalization (matching react-pdf convention) ───────────
 
@@ -52,6 +53,8 @@ export interface PreparedRichInlineItem {
   letterSpacing?: number;
   extraWidth?: number;         // padding, border for inline-box
   break?: 'normal' | 'never';  // for atomic chips
+  /** Original text before text-transform (if transform was applied). Used for copy-paste / round-trip. */
+  originalText?: string;
   metadata: {
     originalRunIndex: number;
     baselineOffset: number;
@@ -63,7 +66,7 @@ export interface PreparedRichInlineItem {
 
 const SUPER_SUB_SCALE = 0.65;
 const SUPER_OFFSET_RATIO = -0.4;
-const SUB_OFFSET_RATIO = 0.15;
+const SUB_OFFSET_RATIO = 0.25;
 
 /**
  * Compile a paragraph into PreparedRichInlineItem[].
@@ -88,7 +91,10 @@ export function compileParagraph(paragraph: Paragraph): PreparedRichInlineItem[]
     }
 
     // Inline-box: text → \uFFFC
-    const text = run.type === 'inline-box' ? '\uFFFC' : run.text;
+    const rawText = run.type === 'inline-box' ? '\uFFFC' : run.text;
+    // Apply text-transform (only for text runs, not inline-box)
+    const textTransformValue: TextTransform | undefined = run.textTransform;
+    const text = transformText(rawText, textTransformValue);
 
     // Normalize fontWeight to numeric value
     const resolvedFontWeight = normalizeFontWeight(run.fontWeight ?? DEFAULT_TEXT_STYLE.fontWeight);
@@ -107,6 +113,8 @@ export function compileParagraph(paragraph: Paragraph): PreparedRichInlineItem[]
       text,
       font: makeFontToken(run, effectiveFontSize),
       letterSpacing: run.letterSpacing,
+      // Save original text if transform was applied (for copy-paste / round-trip)
+      ...(text !== rawText ? { originalText: rawText } : {}),
       metadata: {
         originalRunIndex: i,
         baselineOffset,

package/src/index.browser.ts

@@ -0,0 +1,90 @@
+/**
+ * @vyaz/core — Browser entry point.
+ *
+ * Re-exports everything from the main index **except** `SystemFontRegistry`
+ * and `systemFontRegistry`, which require Node.js built-in modules
+ * (`node:fs`, `get-system-fonts`).
+ *
+ * All server-only code paths are guarded by runtime checks (`isNodeLike`)
+ * so tree-shakers can safely eliminate dead branches.
+ *
+ * ✅ Safe for Vite / webpack / Rollup / esbuild browser builds.
+ */
+
+// ── 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 (browser‑safe: uses Canvas 2D measureText fallback) ──
+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';
+
+// ── Compiler (browser‑safe: FontMetricsProvider falls back to Canvas) ──
+export { compileParagraph, getParagraphText, makeFontToken } from './compile/DocumentCompiler.js';
+export type { PreparedRichInlineItem } from './compile/DocumentCompiler.js';
+
+// ── Font metrics (browser‑safe: canvas-polyfill has runtime guards) ────
+export { FontMetricsProvider, fontMetricsProvider } from './measure/FontMetricsProvider.js';
+
+// ── Errors ──────────────────────────────────────────────────────────────
+export { FontNotFoundError } from './measure/FontNotFoundError.js';
+
+// ❌ NOT exported in browser entry:
+//   - SystemFontRegistry / systemFontRegistry — requires `node:fs` + `get-system-fonts`

package/src/index.ts

@@ -28,6 +28,10 @@ export type {
   OverflowWrap,
   TextDecorationStyle,
   TextTransform,
+  ListType,
+  NumberFormat,
+  ListStylePosition,
+  ListStyle,
 } from './types/Document.js';
 export {
   DEFAULT_PARAGRAPH_STYLE,
@@ -66,15 +70,28 @@ export type { TextFrameLayoutResult } from './layout/TextFrameLayoutEngine.js';
 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/ParagraphLayoutEngine.ts

@@ -16,19 +16,32 @@
 // Polyfill OffscreenCanvas for Node.js (node-canvas)
 import '../measure/canvas-polyfill.js';
 
-import type { Paragraph } from '../types/Document.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 } from '../measure/FontMetricsProvider.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 */
@@ -47,7 +60,7 @@ export class ParagraphLayoutEngine {
   private preparedCache = new Map<string, PreparedRichInline>();
 
   /**
-   * Layout a single paragraph — basic variant, no per-glyph data.
+   * Layout a single paragraph — basic variant.
    *
    * @param paragraph — input paragraph
    * @param maxWidth — available container width (px)
@@ -59,6 +72,9 @@ export class ParagraphLayoutEngine {
     maxWidth: number,
     yOffset: number = 0,
     fontProvider?: IFontMetricsProvider,
+    listStyle?: ListStyle,
+    listIndex?: number,
+    listMarkerWidth?: number,
   ): ParagraphLayoutResult {
     const provider = fontProvider || fontMetricsProvider;
 
@@ -74,7 +90,6 @@ export class ParagraphLayoutEngine {
     }
 
     // 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) => {
@@ -89,6 +104,34 @@ export class ParagraphLayoutEngine {
 
     // 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,
@@ -107,9 +150,42 @@ export class ParagraphLayoutEngine {
       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);
 
@@ -129,68 +205,54 @@ export class ParagraphLayoutEngine {
   /**
    * Layout with per-glyph advance widths (for SVG glyph mode).
    *
-   * After basic layout, fills Span.glyphAdvances
-   * via fontkit for each text span.
-   *
-   * @param paragraph — input paragraph
-   * @param maxWidth — available container width (px)
-   * @param yOffset — starting Y position
-   * @returns ParagraphLayoutResult with glyphAdvances[]
+   * 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 {
-    const result = this.layout(paragraph, maxWidth, yOffset);
-
-    for (const line of result.lines) {
-      for (const span of line.spans) {
-        if (span.type === 'text' && span.text.length > 0) {
-          span.glyphAdvances = this.computeGlyphAdvances(
-            span.text,
-            span.style.fontFamily,
-            span.fontMetrics.fontSize,
-            String(span.style.fontWeight || 400),
-            span.style.fontStyle || 'normal',
-          );
-        }
-      }
-    }
-
-    return result;
+    return this.layout(paragraph, maxWidth, yOffset);
   }
 
   /**
-   * Compute per-character advance widths via fontkit.
+   * 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,
-    fontFamily: string,
     fontSize: number,
-    weight: string,
-    style: string,
-  ): number[] {
-    const font = fontMetricsProvider.getFont(fontFamily, weight, style);
+    fontFamily?: string,
+    fontWeight?: string,
+    fontStyle?: string,
+  ): Float32Array {
+    const font = fontMetricsProvider.getFont(
+      fontFamily || 'Arial',
+      fontWeight || '400',
+      fontStyle || 'normal',
+    );
     if (!font) {
-      // Fallback: uniform distribution
-      const avgWidth = fontSize * 0.6;
-      return Array.from(text).map(() => avgWidth);
+      throw new FontNotFoundError(
+        fontFamily || 'Arial',
+        fontWeight || '400',
+        fontStyle || 'normal',
+      );
     }
 
     const scale = fontSize / font.unitsPerEm;
-    const advances: number[] = [];
+    const advances = new Float32Array(text.length);
 
     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);
+      const advance = font._raw.glyphForCodePoint(codePoint)?.advanceWidth;
+      if (advance != null) {
+        advances[i] = advance * scale;
       } else {
-        // Missing glyph
-        advances.push(fontSize * 0.5);
+        advances[i] = fontSize * MISSING_GLYPH_FACTOR;
       }
-      // Skip surrogate pair
       if (codePoint > 0xffff) i++;
     }