@vyaz/core 0.0.5 → 0.0.7

package/dist/types/LayoutTypes.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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;
+    /**
+     * True when this line was created by a forced hard break (\n),
+     * as opposed to a soft wrap from line width exceeding maxWidth.
+     *
+     * Used by the editor to distinguish user-inserted line breaks
+     * from automatic wrapping (affects Home/End, arrow up/down,
+     * Backspace merging behaviour).
+     */
+    isHardBreak?: boolean;
+    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/{src/utils/env.ts → dist/utils/env.d.ts}

@@ -7,12 +7,5 @@
  * triggering bundler static analysis that could externalize the
  * Node.js `process` global for browser targets.
  */
-
-const _process: any =
-  typeof globalThis !== 'undefined' ? (globalThis as any).process : undefined;
-
 /** `true` when running on Node.js or Bun (has `process.versions.node`) */
-export const isNodeLike: boolean =
-  _process != null &&
-  _process.versions != null &&
-  typeof _process.versions.node === 'string';
+export declare const isNodeLike: boolean;

package/{src/utils/font.ts → dist/utils/font.d.ts}

@@ -4,7 +4,6 @@
  * 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.
  *
@@ -14,15 +13,4 @@
  * @param fontUrl  URL of the font file (.ttf, .otf, .woff, .woff2)
  * @returns        Font file bytes as an ArrayBuffer
  */
-export async function getFontBuffer(fontUrl: string): Promise<ArrayBuffer> {
-  const response = await fetch(fontUrl);
-
-  if (!response.ok) {
-    throw new Error(
-      `[vyaz] Failed to download font from "${fontUrl}": ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const buffer = await response.arrayBuffer();
-  return buffer;
-}
+export declare function getFontBuffer(fontUrl: string): Promise<ArrayBuffer>;

package/{src/utils/groupLinesByParagraph.ts → dist/utils/groupLinesByParagraph.d.ts}

@@ -7,21 +7,18 @@
  *
  * @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;
+    /** 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).
  *
@@ -44,31 +41,4 @@ export interface ParagraphGroup {
  * // groups[0].pIdx   → 0
  * ```
  */
-export function groupLinesByParagraph(lines: Line[]): ParagraphGroup[] {
-  // Collect lines per paragraph using a Map
-  const map = new Map<number, { lines: Line[]; tag?: string }>();
-
-  for (const line of lines) {
-    const idx = line.spans[0]?.pIdx ?? -1;
-    let entry = map.get(idx);
-    if (!entry) {
-      entry = { lines: [] };
-      map.set(idx, entry);
-    }
-    entry.lines.push(line);
-    if (!entry.tag) {
-      entry.tag = line.spans[0]?.tag;
-    }
-  }
-
-  // Convert to array sorted by pIdx
-  const groups: ParagraphGroup[] = [];
-  const sortedKeys = Array.from(map.keys()).sort((a, b) => a - b);
-  for (const key of sortedKeys) {
-    if (key === -1) continue; // skip invalid
-    const entry = map.get(key)!;
-    groups.push({ lines: entry.lines, pIdx: key, tag: entry.tag });
-  }
-
-  return groups;
-}
+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,10 +1,10 @@
 {
   "name": "@vyaz/core",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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"
@@ -12,10 +12,10 @@
   "exports": {
     ".": {
       "bun": "./src/index.ts",
-      "node": "./src/index.ts",
-      "browser": "./src/index.browser.ts",
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "node": "./dist/index.js",
+      "browser": "./dist/index.browser.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "browser": {
@@ -26,14 +26,12 @@
     "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",
-    "js-yaml": "^5.0.0",
-    "typedoc": "^0.28.19"
+    "js-yaml": "^5.0.0"
   },
   "optionalDependencies": {
     "@napi-rs/canvas": "^1.0.2",
@@ -41,6 +39,8 @@
     "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,144 +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, 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) ───────────
-
-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
-  /** 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'];
-  };
-}
-
-const SUPER_SUB_SCALE = 0.65;
-const SUPER_OFFSET_RATIO = -0.4;
-const SUB_OFFSET_RATIO = 0.25;
-
-/**
- * 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 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);
-
-    // 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,
-      // Save original text if transform was applied (for copy-paste / round-trip)
-      ...(text !== rawText ? { originalText: rawText } : {}),
-      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.browser.ts

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