@vyaz/core 0.0.4 → 0.0.6

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/dist/compile/DocumentCompiler.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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';
+export declare const FONT_WEIGHTS: Record<string, number>;
+/** Normalize fontWeight to a numeric value (400 by default). */
+export declare function normalizeFontWeight(weight: number | string | undefined): number;
+/** Font token for pretext: "${style}_${weight}_${fontSize}_${family}" */
+export declare function makeFontToken(run: TextRun, effectiveFontSize: number): string;
+/** Compilation context (passed to pretext) */
+export interface PreparedRichInlineItem {
+    text: string;
+    font: string;
+    letterSpacing?: number;
+    extraWidth?: number;
+    break?: 'normal' | 'never';
+    /** Original text before text-transform (if transform was applied). Used for copy-paste / round-trip. */
+    originalText?: string;
+    metadata: {
+        originalRunIndex: number;
+        baselineOffset: number;
+        effectiveFontSize: number;
+        style: TextRun;
+        inlineWidget?: TextRun['inlineWidget'];
+    };
+}
+/**
+ * Compile a paragraph into PreparedRichInlineItem[].
+ */
+export declare function compileParagraph(paragraph: Paragraph): PreparedRichInlineItem[];
+/**
+ * Get the full text of a paragraph (for INDEX_CONSIST checks).
+ */
+export declare function getParagraphText(paragraph: Paragraph): string;

package/dist/index.browser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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.
+ */
+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';
+export type { ParagraphLayoutResult, Line, Span, SpanFontMetrics, SemanticParagraph, SemanticLine, SemanticFragment, } from './types/LayoutTypes.js';
+export type { FontMetrics, IFontMetricsProvider, GlyphData, } from './types/FontTypes.js';
+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';
+export { layoutTextFrame } from './layout/TextFrameLayoutEngine.js';
+export type { TextFrameLayoutResult } from './layout/TextFrameLayoutEngine.js';
+export { applyScale, findScale } from './layout/AutoFitEngine.js';
+export type { AutoFitOptions, AutoFitResult } from './layout/AutoFitEngine.js';
+export { compileParagraph, getParagraphText, makeFontToken } from './compile/DocumentCompiler.js';
+export type { PreparedRichInlineItem } from './compile/DocumentCompiler.js';
+export { FontMetricsProvider, fontMetricsProvider } from './measure/FontMetricsProvider.js';
+export { FontNotFoundError } from './measure/FontNotFoundError.js';

package/dist/index.browser.js

@@ -0,0 +1,18 @@
+export {
+  positionLines,
+  paragraphLayoutEngine,
+  makeFontToken,
+  linesToYAML,
+  layoutTextFrame,
+  getParagraphText,
+  fontMetricsProvider,
+  findScale,
+  compileParagraph,
+  assertLineInvariants,
+  applyScale,
+  ParagraphLayoutEngine,
+  FontNotFoundError,
+  FontMetricsProvider,
+  DEFAULT_TEXT_STYLE,
+  DEFAULT_PARAGRAPH_STYLE
+};

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @vyaz/core — Public API.
+ *
+ * Exports input types (Logical level), output types (Physical Box Model),
+ * layout engines, font metric providers, renderers, and utilities.
+ */
+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';
+export type { ParagraphLayoutResult, Line, Span, SpanFontMetrics, SemanticParagraph, SemanticLine, SemanticFragment, } from './types/LayoutTypes.js';
+export type { FontMetrics, IFontMetricsProvider, GlyphData, } from './types/FontTypes.js';
+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';
+export { layoutTextFrame } from './layout/TextFrameLayoutEngine.js';
+export type { TextFrameLayoutResult } from './layout/TextFrameLayoutEngine.js';
+export { applyScale, findScale } from './layout/AutoFitEngine.js';
+export type { AutoFitOptions, AutoFitResult } from './layout/AutoFitEngine.js';
+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';
+export { compileParagraph, getParagraphText, makeFontToken } from './compile/DocumentCompiler.js';
+export type { PreparedRichInlineItem } from './compile/DocumentCompiler.js';
+export type { FontFace } from './measure/FontEngine.js';
+export { createFontFace, getGlyphAdvance, computePixelMetrics, isFontEngineAvailable } from './measure/FontEngine.js';
+export { FontMetricsProvider, fontMetricsProvider } from './measure/FontMetricsProvider.js';
+export { SystemFontRegistry, systemFontRegistry } from './measure/SystemFontRegistry.js';
+export { getFontBuffer } from './utils/font.js';
+export { FontNotFoundError } from './measure/FontNotFoundError.js';