@vyaz/core 0.0.4 → 0.0.6

package/dist/types/LayoutTypes.d.ts

@@ -0,0 +1,128 @@
+/**
+ * LayoutTypes.ts — output types (Physical Box Model).
+ *
+ * ParagraphLayoutResult → Line[] → Span[]
+ * This is the contract between layout engine and renderers.
+ *
+ * Based on plan.md §2.5 (Output — Physical Box Model / Layout Tree)
+ */
+import type { TextRun, InlineWidget, TextAlignment } from './Document.js';
+export interface Span {
+    /** Offset from Line.x */
+    x: number;
+    /** Physical span width */
+    width: number;
+    /** Span text (or " " for justify spaces) */
+    text: string;
+    /** Index of the source run in the paragraph's `children` array. */
+    itemIndex: number;
+    /** Paragraph index in TextFrame.paragraphs[]. Stable key for grouping & diff. */
+    pIdx: number;
+    /** Optional paragraph tag (set by user via Paragraph.id). */
+    tag?: string;
+    /** Physical font metrics for this span */
+    fontMetrics: SpanFontMetrics;
+    /**
+     * A snapshot of the source run's style at layout time.
+     * Copied from the corresponding `TextRun` in the paragraph's `children` array.
+     */
+    style: TextRun;
+    /** InlineWidget data (if span is an inline-box) */
+    inlineWidget?: InlineWidget;
+    /** Per-character advance widths (for selection/tracking) */
+    glyphAdvances?: number[] | Float32Array;
+    /**
+     * Span type:
+     * - `'text'` — regular text
+     * - `'space'` — whitespace span
+     * - `'marker'` — list marker (bullet / number), rendered like text
+     */
+    type: 'text' | 'space' | 'marker';
+    /**
+     * Trailing whitespace flag.
+     * - true: span is at end of line, does not participate in line advance
+     *         and is not stretched during justify (zero width for calculations).
+     * - undefined/false: regular span.
+     *
+     * See CSS Text Module Level 3 §4.1.3 (Tracking and Dropping Spaces)
+     * and Parley LineItemData::has_trailing_whitespace.
+     */
+    trailing?: boolean;
+    /**
+     * Line break mode after this span.
+     * 'soft' — soft line break (insufficient space)
+     * 'hard' — forced break (\n, explicit separator)
+     * undefined — not end of line
+     */
+    breakType?: 'soft' | 'hard';
+}
+export interface SpanFontMetrics {
+    ascent: number;
+    descent: number;
+    fontSize: number;
+    /** Vertical offset from baseline (px). Used for sub/superscript positioning.
+     *  Negative = above baseline (superscript). Positive = below baseline (subscript).
+     *  Undefined or 0 = normal baseline position. */
+    baselineOffset?: number;
+}
+export interface Line {
+    /**
+     * Absolute X of the line box left edge within the container.
+     * Includes outside list markers when present (marker may sit left of text).
+     */
+    x: number;
+    /** Absolute Y of line top edge */
+    y: number;
+    /**
+     * Line box width covering all spans (text + outside markers).
+     * Equals max(span.x + span.width) − min(span.x).
+     */
+    width: number;
+    /** Full line height (max spans × lineHeight) */
+    height: number;
+    /** Baseline offset from y */
+    baseline: number;
+    /** Maximum ascent in line */
+    ascent: number;
+    /** Maximum descent in line */
+    descent: number;
+    /** Index of first character in the original paragraph text */
+    startIndex: number;
+    /** Index of last character + 1 (for convenient length calculation) */
+    endIndex: number;
+    /** Paragraph alignment (optional, for PowerPoint render) */
+    alignment?: TextAlignment;
+    /** Column index (0-based) when frame has multi-column layout. */
+    columnIndex?: number;
+    spans: Span[];
+}
+export interface ParagraphLayoutResult {
+    width: number;
+    height: number;
+    lines: Line[];
+    /** Actual content width (text bbox, without voids) */
+    contentWidth: number;
+    /** Actual content height (text bbox) */
+    contentHeight: number;
+}
+/** Semantic span for snapshots (without physical metrics) */
+export interface SemanticFragment {
+    text: string;
+    x: number;
+    width: number;
+    style?: 'bold' | 'italic' | 'normal';
+}
+/** Semantic line for snapshots */
+export interface SemanticLine {
+    y: number;
+    width: number;
+    height: number;
+    baseline: number;
+    fragments: SemanticFragment[];
+}
+/** Semantic paragraph for YAML snapshots */
+export interface SemanticParagraph {
+    width: number;
+    height: number;
+    lines: SemanticLine[];
+}

package/dist/utils/env.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runtime environment detection.
+ * Used to guard Node.js–only code paths (fontkit, fs, get-system-fonts)
+ * from being executed in the browser.
+ *
+ * ⚠️ Uses `globalThis.process` instead of bare `process` to avoid
+ * triggering bundler static analysis that could externalize the
+ * Node.js `process` global for browser targets.
+ */
+/** `true` when running on Node.js or Bun (has `process.versions.node`) */
+export declare const isNodeLike: boolean;

package/dist/utils/font.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Font utility helpers.
+ *
+ * Provides cross‑environment helpers for loading font data in the browser
+ * (where there is no local filesystem).
+ */
+/**
+ * Download a font file from a URL and return its bytes.
+ *
+ * Works in browser environments.  In Node.js you'd typically read the file
+ * via `fs.readFileSync()` instead.
+ *
+ * @param fontUrl  URL of the font file (.ttf, .otf, .woff, .woff2)
+ * @returns        Font file bytes as an ArrayBuffer
+ */
+export declare function getFontBuffer(fontUrl: string): Promise<ArrayBuffer>;

package/dist/utils/groupLinesByParagraph.d.ts

@@ -0,0 +1,44 @@
+/**
+ * groupLinesByParagraph.ts — Group lines by paragraph index.
+ *
+ * Collects all lines with the same `pIdx` into one group,
+ * regardless of their order in the array (handles multi-column
+ * where lines of the same paragraph may be split across columns).
+ *
+ * @see {@link https://www.w3.org/TR/css-text-3/ | CSS Text Module Level 3}
+ */
+import type { Line } from '../types/LayoutTypes.js';
+/**
+ * A group of lines belonging to one paragraph.
+ */
+export interface ParagraphGroup {
+    /** Lines in this paragraph. */
+    lines: Line[];
+    /** Paragraph index in TextFrame.paragraphs[]. */
+    pIdx: number;
+    /** Optional user-assigned tag (from Paragraph.id). */
+    tag?: string;
+}
+/**
+ * Group lines by `pIdx` (paragraph index).
+ *
+ * Collects **all** lines with the same `pIdx` into one group,
+ * even if they are not consecutive in the array (multi-column layout
+ * may interleave lines of different paragraphs across columns).
+ *
+ * Returns groups sorted by `pIdx` in document order.
+ * Lines without a valid `pIdx` (e.g. `pIdx === undefined`) are grouped
+ * as index `-1`.
+ *
+ * @param lines — flat array of lines from `layoutTextFrame`
+ * @returns groups of lines grouped by paragraph
+ *
+ * @example
+ * ```ts
+ * const result = layoutTextFrame(frame);
+ * const groups = groupLinesByParagraph(result.lines);
+ * // groups[0].lines  → all lines for paragraph 0 (across all columns)
+ * // groups[0].pIdx   → 0
+ * ```
+ */
+export declare function groupLinesByParagraph(lines: Line[]): ParagraphGroup[];

package/dist/utils/list.d.ts

@@ -0,0 +1,41 @@
+/**
+ * list.ts — helper utilities for list marker generation.
+ *
+ * Provides:
+ * - `formatListNumber()` — format a number according to `NumberFormat`
+ * - `defaultBulletChar()` — pick a bullet character based on nesting level
+ * - `BULLET_CHARACTERS` — the Unicode characters for disc/circle/square
+ */
+import type { NumberFormat } from '../types/Document.js';
+/**
+ * Unicode characters used for CSS `disc`, `circle`, `square` list-style-type
+ * values at different nesting levels.
+ *
+ * @see {@link https://www.w3.org/TR/css-lists-3/#ua-stylesheet | CSS Lists UA defaults}
+ */
+export declare const BULLET_CHARACTERS: Record<number, string>;
+/**
+ * Get the default bullet character for a given nesting level.
+ *
+ * CSS UA stylesheet uses:
+ * - Level 0 (ul): disc (•)
+ * - Level 1 (ul ul): circle (○)
+ * - Level 2+ (ul ul ul): square (▪)
+ */
+export declare function defaultBulletChar(level: number): string;
+/**
+ * Format a number according to the given numbering format.
+ *
+ * Supports the same formats as CSS `list-style-type`:
+ * - `decimal`: 1, 2, 3, …
+ * - `upper-roman`: I, II, III, …
+ * - `lower-roman`: i, ii, iii, …
+ * - `upper-alpha`: A, B, C, …
+ * - `lower-alpha`: a, b, c, …
+ *
+ * Follows CSS Counter Styles Level 3 algorithms.
+ * Roman numerals support the range 1–3999.
+ *
+ * @see {@link https://www.w3.org/TR/css-counter-styles-3/ | CSS Counter Styles Level 3}
+ */
+export declare function formatListNumber(n: number, format: NumberFormat): string;

package/dist/utils/textTransform.d.ts

@@ -0,0 +1,32 @@
+/**
+ * textTransform.ts — pure text transformation functions.
+ *
+ * Implements CSS `text-transform` for: none, uppercase, lowercase, capitalize.
+ *
+ * Explicit capitalization contract (edge cases):
+ * - Apostrophe (') is NOT a word boundary: "don't stop" → "Don't Stop"
+ * - Hyphen (-) IS a word boundary: "hello-world" → "Hello-World"
+ * - Leading whitespace is preserved: "  hello" → "  Hello"
+ * - Numbers are not capitalized: "3d model" → "3d Model"
+ * - Unicode full-range: first `\p{L}` in each word segment gets .toUpperCase()
+ * - Empty string → ""
+ * - No letters → unchanged: "123" → "123"
+ *
+ * @see {@link https://www.w3.org/TR/css-text-3/#text-transform-property | CSS Text: text-transform}
+ */
+import type { TextTransform } from '../types/Document.js';
+/**
+ * Apply text-transform to a string.
+ *
+ * @param text — input text
+ * @param transform — transform type ('none' | 'uppercase' | 'lowercase' | 'capitalize')
+ * @returns transformed text
+ *
+ * @example
+ * ```ts
+ * transformText("hello world", 'uppercase')  // → "HELLO WORLD"
+ * transformText("HELLO", 'lowercase')         // → "hello"
+ * transformText("don't stop", 'capitalize')   // → "Don't Stop"
+ * ```
+ */
+export declare function transformText(text: string, transform?: TextTransform): string;

package/package.json

@@ -1,29 +1,46 @@
 {
   "name": "@vyaz/core",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "files": ["dist", "src"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "node": "./dist/index.js",
+      "browser": "./dist/index.browser.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "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",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/index.browser.ts --outdir ./dist --outfile ./dist/index.browser.js --target browser && tsc --project tsconfig.json --emitDeclarationOnly",
     "test": "bun test"
   },
   "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"
+    "js-yaml": "^5.0.0"
   },
   "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"
+    "@types/node": "^26.0.0",
+    "@clean-jsdoc-theme/typedoc": "^5.0.6",
+    "typedoc": "^0.28.19"
   }
-}
+}

package/src/compile/DocumentCompiler.ts

@@ -1,136 +0,0 @@
-/**
- * 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';
-import { DEFAULT_TEXT_STYLE } from '../types/Document.js';
-
-// ── Font Weight normalization (matching react-pdf convention) ───────────
-
-export const FONT_WEIGHTS: Record<string, number> = {
-  thin: 100,
-  hairline: 100,
-  ultralight: 200,
-  extralight: 200,
-  light: 300,
-  normal: 400,
-  medium: 500,
-  semibold: 600,
-  demibold: 600,
-  bold: 700,
-  ultrabold: 800,
-  extrabold: 800,
-  heavy: 900,
-  black: 900,
-};
-
-/** Normalize fontWeight to a numeric value (400 by default). */
-export function normalizeFontWeight(weight: number | string | undefined): number {
-  if (weight == null) return FONT_WEIGHTS.normal;
-  if (typeof weight === 'number') return weight;
-  return FONT_WEIGHTS[weight.toLowerCase()] ?? FONT_WEIGHTS.normal;
-}
-
-/** Font token for pretext: "${style}_${weight}_${fontSize}_${family}" */
-export function makeFontToken(run: TextRun, effectiveFontSize: number): string {
-  const fontStyle = run.fontStyle || DEFAULT_TEXT_STYLE.fontStyle || 'normal';
-  const fontWeight = normalizeFontWeight(run.fontWeight ?? DEFAULT_TEXT_STYLE.fontWeight);
-  const fontFamily = run.fontFamily || DEFAULT_TEXT_STYLE.fontFamily || 'Arial';
-  return `${fontStyle} ${fontWeight} ${effectiveFontSize}px ${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
-    const baseFontSize = run.fontSize ?? DEFAULT_TEXT_STYLE.fontSize ?? 12;
-    let effectiveFontSize = baseFontSize;
-    let baselineOffset = 0;
-
-    if (run.script === 'super') {
-      effectiveFontSize = baseFontSize * SUPER_SUB_SCALE;
-      baselineOffset = baseFontSize * SUPER_OFFSET_RATIO;
-    } else if (run.script === 'sub') {
-      effectiveFontSize = baseFontSize * SUPER_SUB_SCALE;
-      baselineOffset = baseFontSize * SUB_OFFSET_RATIO;
-    }
-
-    // Inline-box: text → \uFFFC
-    const text = run.type === 'inline-box' ? '\uFFFC' : run.text;
-
-    // Normalize fontWeight to numeric value
-    const resolvedFontWeight = normalizeFontWeight(run.fontWeight ?? DEFAULT_TEXT_STYLE.fontWeight);
-
-    // Fill missing style fields from DEFAULT_TEXT_STYLE
-    const resolvedStyle: TextRun = {
-      ...DEFAULT_TEXT_STYLE,
-      ...run,
-      fontSize: effectiveFontSize,
-      fontWeight: resolvedFontWeight,
-      text: run.text,
-      type: run.type,
-    } as TextRun;
-
-    const item: PreparedRichInlineItem = {
-      text,
-      font: makeFontToken(run, effectiveFontSize),
-      letterSpacing: run.letterSpacing,
-      metadata: {
-        originalRunIndex: i,
-        baselineOffset,
-        effectiveFontSize,
-        style: resolvedStyle,
-        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

@@ -1,80 +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,
-} 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';
-
-// ── 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';
-
-// ── System font registry ────────────────────────────────────────────────
-export { SystemFontRegistry, systemFontRegistry } from './measure/SystemFontRegistry.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 };
-}