@vyaz/core 0.0.3 → 0.0.5

package/src/measure/FontMetricsProvider.ts

@@ -2,19 +2,28 @@
  * FontMetricsProvider.ts — isomorphic font metrics provider.
  *
  * Strategy (priority):
- *   1. fontkit (Node.js) — from registered buffer
- *      - 'browser' mode: font.hhea.ascent / font.hhea.descent
- *      - 'office'  mode:  font['OS/2'].usWinAscent / font['OS/2'].usWinDescent
- *   2. Canvas TextMetrics (browser)
- *   3. Fallback (fontSize * 0.85 / 0.15)
+ *   1. FontEngine (fontkit) — from registered buffer
+ *      - 'browser' mode: hhea.ascender / hhea.descender
+ *      - 'office'  mode: OS/2.usWinAscent / OS/2.usWinDescent
+ *   2. Canvas TextMetrics (browser fallback when fontkit unavailable)
  *
- * Uses FontRegistry for font registration.
+ * Uses FontEngine as the single entry point for all fontkit operations.
  */
 
 import type { FontMetrics, IFontMetricsProvider } from '../types/FontTypes.js';
-import { enableOfficeTextMeasure, disableOfficeTextMeasure, registerCanvasFont } from './canvas-polyfill.js';
+import type { FontFace } from './FontEngine.js';
+import { enableOfficeTextMeasure, disableOfficeTextMeasure } from './canvas-polyfill.js';
 import { FontNotFoundError } from './FontNotFoundError.js';
 
+// ── Reasonable default for missing glyphs ──────────────────────────────────
+
+/**
+ * Factor used when a glyph is not found in the font.
+ * Multiplied by fontSize to estimate the missing glyph width.
+ * Used across all measurement code paths (ParagraphLayoutEngine, canvas-polyfill).
+ */
+export const MISSING_GLYPH_FACTOR = 0.5;
+
 // ── Weight normalisation ─────────────────────────────────────────────────
 
 /**
@@ -52,7 +61,8 @@ function cacheKey(family: string, weight: string, style: string): string {
 }
 
 export class FontMetricsProvider implements IFontMetricsProvider {
-  private cache = new Map<string, any>();   // fontkit.Font | undefined
+  /** Map<string, FontFace> — font engine font face cache */
+  private cache = new Map<string, FontFace>();
   private metricsCache = new Map<string, FontMetrics>();
   private mode: 'browser' | 'office' = 'browser';
 
@@ -80,49 +90,52 @@ export class FontMetricsProvider implements IFontMetricsProvider {
 
   /**
    * Register a binary font for use with fontkit.
-   * In browser — no-op (fonts are registered via CSS @font-face).
    *
-   * @param sourcePath — if provided, also registers with @napi-rs/canvas for Node.js canvas measureText
+   * In both Node.js and browser the font is loaded via FontEngine.
+   * In the browser the caller must provide font bytes (e.g. fetched via
+   * `getFontBuffer()` from `../utils/font.js`).
+   *
+   * @param source      Font file bytes (ArrayBuffer / Uint8Array), or a URL string
+   * @param sourcePath  Optional filesystem path (used for @napi-rs/canvas in Node.js)
    */
   async registerFont(
     family: string,
     options: { weight?: string; style?: string },
-    source: string | Buffer,
+    source: string | ArrayBuffer | Uint8Array,
     sourcePath?: string,
   ): Promise<void> {
-    try {
-      // Dynamic ESM import — fontkit may not be available in browser
-      const fontkit = await import('fontkit');
-      const buffer = typeof source === 'string' ? Buffer.from(source) : source;
-      // @ts-ignore fontkit CJS/ESM compatibility
-      const fk = fontkit.default || fontkit;
-      const font = fk.create(buffer);
-      const key = cacheKey(
-        family,
-        options.weight || 'normal',
-        options.style || 'normal',
-      );
-      this.cache.set(key, font);
-      // Invalidate metrics for this font
-      this.metricsCache.delete(key);
-
-      // Also register with @napi-rs/canvas so ctx.measureText() uses real fonts
-      if (sourcePath) {
-        registerCanvasFont(sourcePath, family);
-      }
-    } catch {
-      // fontkit not available (browser) — no-op
+    const { createFontFace } = await import('./FontEngine.js');
+    const { registerCanvasFont } = await import('./canvas-polyfill.js');
+
+    // Convert string (URL) to buffer — works in browser via fetch
+    if (typeof source === 'string') {
+      const { getFontBuffer } = await import('../utils/font.js');
+      source = await getFontBuffer(source);
+    }
+
+    const font = await createFontFace(source);
+    const key = cacheKey(
+      family,
+      options.weight || 'normal',
+      options.style || 'normal',
+    );
+    this.cache.set(key, font);
+    // Invalidate metrics for this font
+    this.metricsCache.delete(key);
+
+    // Also register with @napi-rs/canvas so ctx.measureText() uses real fonts
+    if (sourcePath) {
+      registerCanvasFont(sourcePath, family);
     }
-    return Promise.resolve();
   }
 
   // ── Font object access (for per-glyph advance) ────────────────────
 
   /**
-   * Get fontkit font object for per-character calculations.
-   * Returns undefined if font is not registered or fontkit unavailable.
+   * Get font engine FontFace object for per-character calculations.
+   * Returns undefined if font is not registered.
    */
-  getFont(family: string, weight = 'normal', style = 'normal'): any | undefined {
+  getFont(family: string, weight = 'normal', style = 'normal'): FontFace | undefined {
     const key = cacheKey(family, weight, style);
     return this.cache.get(key);
   }
@@ -142,55 +155,40 @@ export class FontMetricsProvider implements IFontMetricsProvider {
     const cached = this.metricsCache.get(metricsKey);
     if (cached) return cached;
 
-    let metrics: FontMetrics;
-
-    // Strategy 1: fontkit
+    // Strategy 1: FontEngine (fontkit)
     const font = this.cache.get(key);
 
     if (font) {
+      // Inline computePixelMetrics to avoid circular ESM import
       const scale = fontSize / font.unitsPerEm;
 
-      if (this.mode === 'office') {
-        // Office mode: OS/2.usWinAscent + usWinDescent
-        const os2 = font['OS/2'];
-        let ascent: number;
-        let descent: number;
-        let sourceTable: 'OS/2' | 'hhea';
-
-        if (os2 && os2.winAscent != null && os2.winDescent != null) {
-          ascent = os2.winAscent * scale  * 1.078;
-          descent = Math.abs(os2.winDescent) * scale * 1.078;
-          sourceTable = 'OS/2';
-        } else {
-          // Fallback to hhea if OS/2 is absent
-          ascent = font.ascent * scale;
-          descent = Math.abs(font.descent) * scale;
-          sourceTable = 'hhea';
-        }
-
-        metrics = {
-          ascent,
-          descent,
-          capHeight: (font.capHeight ?? ascent) * scale,
-          unitsPerEm: font.unitsPerEm,
-          sourceTable,
-        };
+      let ascent: number;
+      let descent: number;
+      let sourceTable: 'hhea' | 'OS/2';
+
+      if (this.mode === 'office' && font.winAscent != null && font.winDescent != null) {
+        ascent = font.winAscent * scale * 1.078;
+        descent = Math.abs(font.winDescent) * scale * 1.078;
+        sourceTable = 'OS/2';
       } else {
-        // Browser mode: hhea.ascender/descender
-        metrics = {
-          ascent: font.ascent * scale,
-          descent: Math.abs(font.descent) * scale,
-          capHeight: (font.capHeight ?? font.ascent) * scale,
-          unitsPerEm: font.unitsPerEm,
-          sourceTable: 'hhea',
-        };
+        ascent = font.ascent * scale;
+        descent = Math.abs(font.descent) * scale;
+        sourceTable = 'hhea';
       }
 
+      const metrics: FontMetrics = {
+        ascent,
+        descent,
+        capHeight: (font.capHeight ?? font.ascent) * scale,
+        unitsPerEm: font.unitsPerEm,
+        sourceTable,
+      };
+
       this.metricsCache.set(metricsKey, metrics);
       return metrics;
     }
 
-    // Strategy 2: If fontkit cache is non-empty, fontkit is available but font not found → throw
+    // Strategy 2: If font cache is non-empty, fontkit is available but font not found → throw
     if (this.cache.size > 0) {
       throw new FontNotFoundError(fontFamily, weight, style);
     }
@@ -203,7 +201,7 @@ export class FontMetricsProvider implements IFontMetricsProvider {
         ctx.font = `${style} ${weight} ${fontSize}px ${fontFamily}`;
         const m = ctx.measureText('M');
 
-        metrics = {
+        const metrics: FontMetrics = {
           ascent: m.fontBoundingBoxAscent || fontSize * 0.85,
           descent: m.fontBoundingBoxDescent || fontSize * 0.15,
           capHeight: m.actualBoundingBoxAscent || fontSize * 0.7,
@@ -213,7 +211,7 @@ export class FontMetricsProvider implements IFontMetricsProvider {
         this.metricsCache.set(metricsKey, metrics);
         return metrics;
       } catch {
-        // Fall through to fallback
+        // Fall through to throw
       }
     }
 

package/src/measure/SystemFontRegistry.ts

@@ -6,11 +6,13 @@
  *   import { systemFontRegistry } from './SystemFontRegistry.js';
  *   await systemFontRegistry.scan();
  *   console.log(systemFontRegistry.getRegisteredFamilies());
+ *
+ * ⚠️ Node.js built-in module imports are dynamic (lazy) to avoid
+ * Vite/Webpack externalization errors in browser builds.
  */
 
-import { readFileSync } from 'node:fs';
-import getSystemFonts from 'get-system-fonts';
 import { fontMetricsProvider } from './FontMetricsProvider.js';
+import { isNodeLike } from '../utils/env.js';
 
 interface ScanResult {
   /** Total font files found on the system */
@@ -86,6 +88,21 @@ export class SystemFontRegistry {
    * @returns stats about what was found and registered
    */
   async scan(): Promise<ScanResult> {
+    // System font scanning requires Node.js — no-op in browser
+    if (!isNodeLike) {
+      console.warn('[vyaz] systemFontRegistry.scan() недоступен в браузере');
+      return { total: 0, registered: 0 };
+    }
+
+    // Dynamic imports — hidden from bundler static analysis.
+    // Only resolves on Node.js.  No-op in browser.
+    const [{ readFileSync }, getSystemFontsModule] = await Promise.all([
+      // @ts-ignore — 'node:fs' is a Node.js built-in; not resolvable with moduleResolution:bundler.
+      import('node:fs'),
+      import('get-system-fonts') as any,
+    ]);
+    const getSystemFonts = (getSystemFontsModule.default || getSystemFontsModule) as (opts?: any) => Promise<string[]>;
+
     const paths: string[] = await getSystemFonts();
     let registered = 0;
 
@@ -93,22 +110,16 @@ export class SystemFontRegistry {
       try {
         const buffer = readFileSync(fontPath);
 
-        // Dynamic import — fontkit may not be available in browser
-        let fontkit: any;
-        try {
-          fontkit = await import('fontkit');
-          // @ts-ignore fontkit CJS/ESM compatibility
-          fontkit = fontkit.default || fontkit;
-        } catch {
-          // fontkit not available — skip font registration
-          continue;
-        }
-
-        const font = fontkit.create(buffer);
-        const family = font.familyName;
+        // Use FontEngine to extract family name — avoids direct fontkit import
+        const { createFontFace } = await import('./FontEngine.js');
+        const font = await createFontFace(buffer);
+        // Access raw fontkit object for familyName — FontFace doesn't expose it directly
+        // but we need it to know the family before calling registerFont
+        const fontkit = (font as any)._raw;
+        const family = fontkit.familyName;
         if (!family) continue;
 
-        const { weight, style } = parseSubfamily(font.subfamilyName || 'Regular');
+        const { weight, style } = parseSubfamily(fontkit.subfamilyName || 'Regular');
 
         await fontMetricsProvider.registerFont(family, { weight, style }, buffer, fontPath);
         this.registered.set(family, true);

package/src/measure/canvas-polyfill.ts

@@ -1,5 +1,6 @@
 /**
  * Canvas API polyfill for Bun/Node.js via @napi-rs/canvas.
+ *
  * Required by @chenglou/pretext in server environments (Bun/Node.js without DOM).
  *
  * Two levels of polyfill:
@@ -8,21 +9,41 @@
  *   2. OffscreenCanvas — for some libraries and early versions.
  *
  * Exports enableOfficeTextMeasure / disableOfficeTextMeasure —
- * ctx.measureText override for fontkit-based measurements in Office mode.
+ * ctx.measureText override for FontEngine-based measurements in Office mode.
+ *
+ * ⚠️ All Node.js built-in module imports are dynamic (lazy) to avoid
+ * Vite/Webpack externalization errors in browser builds.
  */
-import { createRequire } from 'module';
 
-// ⚠️ Dynamic import — prevents esbuild from resolving @napi-rs/canvas at bundle time.
-// This module is a native Node.js addon. In the browser, Canvas APIs are already available.
+// ── Lazy Node.js module loader ─────────────────────────────────────
+// Dynamic import('module') — hidden from bundler static analysis.
+// Only resolves on Node.js / Bun.  No-op in browser.
+// Use 'any' for process to avoid requiring @types/node in browser contexts.
+const _process: any = typeof globalThis !== 'undefined'
+  ? (globalThis as any).process
+  : undefined;
+
+let _require: ((id: string) => any) | null = null;
 let _createCanvas: ((w: number, h: number) => any) | null = null;
 
-const _require = createRequire(import.meta.url);
-try {
-  const mod: any = _require('@napi-rs/canvas');
-  _createCanvas = mod.createCanvas;
-} catch {
-  // Browser — document.createElement('canvas') is available natively, no polyfill needed
-  _createCanvas = null;
+async function _initNodeDeps(): Promise<void> {
+  try {
+    // @ts-ignore — 'module' is a Node.js built-in; not resolvable with moduleResolution:bundler.
+    // This dynamic import is guarded by a runtime check and never executes in browser.
+    const m: any = await import('module');
+    _require = m.createRequire(import.meta.url);
+    const canvas: any = _require!('@napi-rs/canvas');
+    _createCanvas = canvas.createCanvas;
+  } catch {
+    // Browser or server without @napi-rs/canvas
+    _createCanvas = null;
+  }
+}
+
+// ESM top-level await — guarded by runtime check so bundlers don't
+// attempt to resolve 'module' at compile time.
+if (_process && (_process.versions?.node || _process.versions?.bun)) {
+  await _initNodeDeps();
 }
 
 // ── Polyfill document.createElement('canvas') ────────────────────────────
@@ -90,7 +111,10 @@ const originalMeasureText = (globalThis as any).CanvasRenderingContext2D
   | ((text: string) => TextMetrics)
   | undefined;
 
-/** fontCache: Map<family_weight_style, fontkit.Font> */
+/**
+ * fontCache: Map<family_weight_style, FontFace> where FontFace._raw holds the
+ * raw fontkit font object.  Used by enableOfficeTextMeasure.
+ */
 let officeFontCache: Map<string, any> | null = null;
 let officeEnabled = false;
 
@@ -126,17 +150,19 @@ function officeMeasureText(this: any, text: string): TextMetrics {
   }
 
   const key = cacheKey(parsed.family, parsed.weight);
-  const font = officeFontCache.get(key);
-  if (!font) {
+  const fontFace = officeFontCache.get(key);
+  if (!fontFace) {
     return originalMeasureText?.call(this, text) ?? createEmptyMetrics();
   }
 
-  const scale = parsed.size / font.unitsPerEm;
+  // FontFace._raw holds the raw fontkit font object
+  const raw: any = fontFace._raw;
+  const scale = parsed.size / fontFace.unitsPerEm;
   let totalWidth = 0;
 
   for (let i = 0; i < text.length; i++) {
     const codePoint = text.codePointAt(i)!;
-    const glyph = font.glyphForCodePoint(codePoint);
+    const glyph = raw.glyphForCodePoint(codePoint);
     if (glyph) {
       totalWidth += glyph.advanceWidth * scale;
     } else {
@@ -144,7 +170,9 @@ function officeMeasureText(this: any, text: string): TextMetrics {
       if (originalMeasureText) {
         return originalMeasureText.call(this, text);
       }
-      totalWidth += parsed.size * 0.5; // rough estimate
+      // Uses the same MISSING_GLYPH_FACTOR (0.5) as FontMetricsProvider
+      // to avoid circular dependency. Keep in sync.
+      totalWidth += parsed.size * 0.5;
     }
     // Skip surrogate pairs
     if (codePoint > 0xffff) i++;
@@ -174,6 +202,7 @@ function createEmptyMetrics(): TextMetrics {
  * No-op in browser or when @napi-rs/canvas is not available.
  */
 export function registerCanvasFont(fontPath: string, family: string): void {
+  if (!_require) return; // @napi-rs/canvas not available
   try {
     const mod = _require('@napi-rs/canvas');
     if (mod?.registerFont) {
@@ -185,8 +214,8 @@ export function registerCanvasFont(fontPath: string, family: string): void {
 }
 
 /**
- * Enable Office measurement: replaces ctx.measureText with fontkit-based version.
- * @param fontCache — Map key->font from FontMetricsProvider
+ * Enable Office measurement: replaces ctx.measureText with FontEngine-based version.
+ * @param fontCache — Map<family_weight_style, FontFace> from FontMetricsProvider
  */
 export function enableOfficeTextMeasure(fontCache: Map<string, any>): void {
   if (officeEnabled) return;

package/src/types/Document.ts

@@ -96,7 +96,6 @@ export type TextDecorationStyle = 'solid' | 'double' | 'dotted' | 'dashed' | 'wa
  * Text case transform.
  *
  * @see {@link https://www.w3.org/TR/css-text-3/#text-transform-property | CSS Text: text-transform}
- * @todo Not yet implemented in the layout engine.
  */
 export type TextTransform = 'none' | 'uppercase' | 'lowercase' | 'capitalize';
 
@@ -143,6 +142,40 @@ export type ScriptType = 'normal' | 'sub' | 'super';
  */
 export type WhiteSpace = 'normal' | 'nowrap' | 'pre';
 
+/**
+ * Type of list marker.
+ *
+ * - `'bullet'`: unordered list (disc, circle, square).
+ * - `'number'`: ordered list (decimal, roman, alpha).
+ * - `'none'`: no list marker.
+ */
+export type ListType = 'bullet' | 'number' | 'none';
+
+/**
+ * Numbering format for ordered lists.
+ *
+ * - `'decimal'`: 1, 2, 3, ...
+ * - `'upper-roman'`: I, II, III, ...
+ * - `'lower-roman'`: i, ii, iii, ...
+ * - `'upper-alpha'`: A, B, C, ...
+ * - `'lower-alpha'`: a, b, c, ...
+ *
+ * @see {@link https://www.w3.org/TR/css-lists-3/#counter-format | CSS Lists: counter-format}
+ */
+export type NumberFormat = 'decimal' | 'upper-roman' | 'lower-roman' | 'upper-alpha' | 'lower-alpha';
+
+/**
+ * Position of the list marker relative to the text.
+ *
+ * - `'outside'`: marker hangs to the left of the text block (default). All lines
+ *   share the same indent — the marker sits inside the indent zone.
+ * - `'inside'`: marker is the first inline element in the text flow, on the first
+ *   line only.
+ *
+ * @see {@link https://www.w3.org/TR/css-lists-3/#list-style-position-property | CSS Lists: list-style-position}
+ */
+export type ListStylePosition = 'outside' | 'inside';
+
 // ── Autofit ─────────────────────────────────────────────────────────────
 
 /**
@@ -248,7 +281,7 @@ export interface TextRun {
 
   // ── Text transform ────────────────────────────────────────────────
 
-  /** Case transform (uppercase, lowercase, capitalize). @todo Not yet implemented. */
+  /** Case transform (uppercase, lowercase, capitalize). */
   textTransform?: TextTransform;
   /** Force full-width characters (CJK). @todo Not yet implemented. */
   fullWidth?: boolean;
@@ -281,6 +314,75 @@ export interface InlineWidget {
   baselineOffset?: number;
 }
 
+// ── ListStyle (block-level list configuration) ──────────────────────────
+
+/**
+ * Configuration for list markers (bullet or numbered).
+ *
+ * Applies to the paragraph via `ParagraphStyle.listStyle`.
+ * Nested lists are supported via the `level` field (0-based).
+ *
+ * **Width consistency:**
+ * For `position: 'outside'`, all lines share the same indent regardless of
+ * marker width. Paragraph indentation = `bulletIndent` (or default `fontSize * 1.5`).
+ * The marker is positioned inside that zone. If the marker text is wider than
+ * the indent zone, `bulletIndent` is expanded to fit the **widest marker**
+ * across the entire list group during layout.
+ *
+ * @see {@link https://www.w3.org/TR/css-lists-3/ | CSS Lists and Counters Module Level 3}
+ *
+ * @example
+ * ```ts
+ * // Simple bullet list
+ * { type: 'bullet', position: 'outside', bulletChar: '•' }
+ *
+ * // Numbered list starting at 5
+ * { type: 'number', numberFormat: 'decimal', startNumber: 5 }
+ * ```
+ */
+export interface ListStyle {
+  /** List type. */
+  type: ListType;
+
+  /** List nesting level (0-based). 0 = top-level. */
+  level?: number;
+
+  /** Marker position. Defaults to `'outside'`. */
+  position?: ListStylePosition;
+
+  /**
+   * Override marker character for bullet lists.
+   * If not set, defaults depend on `level`:
+   * - level 0: `'•'` (U+2022 BULLET)
+   * - level 1: `'○'` (U+25CB WHITE CIRCLE)
+   * - level 2: `'▪'` (U+25AA BLACK SMALL SQUARE)
+   */
+  bulletChar?: string;
+
+  /** Numbering format (only used when `type === 'number'`). Defaults to `'decimal'`. */
+  numberFormat?: NumberFormat;
+
+  /** Starting number for numbered lists. Defaults to 1. */
+  startNumber?: number;
+
+  /**
+   * Indent in px for the marker zone.
+   * All lines of the paragraph share this indent (for `outside` position).
+   * Default: `fontSize * 1.5` (from the paragraph-level font size).
+   *
+   * For numbered lists, the engine expands this to fit the widest marker
+   * across the entire list group.
+   */
+  bulletIndent?: number;
+
+  /**
+   * Per-level indent overrides (indexed by nesting level).
+   * E.g. `indents[1]` is the indent for level 1 (first nested).
+   * Falls back to `bulletIndent * (level + 1)` if not specified.
+   */
+  indents?: number[];
+}
+
 // ── Paragraph (block-level) ─────────────────────────────────────────────
 
 /**
@@ -357,6 +459,20 @@ export interface ParagraphStyle {
    * - `'pre'`: preserve whitespace, wrap on newline only.
    */
   whiteSpace?: WhiteSpace;
+
+  /**
+   * List marker configuration (bullet or numbered).
+   * When set, the paragraph is treated as a list item.
+   */
+  listStyle?: ListStyle;
+
+  /**
+   * Whether to restart numbering for this paragraph.
+   * Only has effect when `listStyle.type === 'number'`.
+   * When `true`, the auto-numbering counter resets to `listStyle.startNumber || 1`
+   * for this paragraph and subsequent ones in the same sequence.
+   */
+  listRestart?: boolean;
 }
 
 /**
@@ -400,13 +516,23 @@ export interface Paragraph {
  * use multiple `TextFrame` instances placed side-by-side.
  *
  * @see {@link https://www.w3.org/TR/css-multicol-1/ | CSS Multi-column Layout Level 1}
- * @todo Not yet implemented in the layout engine.
  */
 export interface MultiColumnConfig {
   /** Number of columns (like CSS `column-count`). */
   count: number;
   /** Gap between columns in px (like CSS `column-gap`). */
   gap: number;
+  /**
+   * Column fill strategy:
+   * - `'auto'`: fill columns sequentially (top-to-bottom, then next column).
+   * - `'balance'`: distribute lines evenly across columns.
+   *
+   * Defaults to `'auto'` when absent.
+   *
+   * @see {@link https://www.w3.org/TR/css-multicol-1/#cf | CSS Multi-column: column-fill}
+   * @todo `'balance'` not yet implemented.
+   */
+  fill?: 'auto' | 'balance';
 }
 
 // ── TextFrame (root container) ──────────────────────────────────────────

package/src/types/LayoutTypes.ts

@@ -20,8 +20,10 @@ export interface Span {
   text: string;
   /** Index of the source run in the paragraph's `children` array. */
   itemIndex: number;
-  /** ID of the source paragraph (for SVG grouping). */
-  paragraphId?: string;
+  /** 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;
@@ -36,10 +38,15 @@ export interface Span {
   inlineWidget?: InlineWidget;
 
   /** Per-character advance widths (for selection/tracking) */
-  glyphAdvances?: number[];
+  glyphAdvances?: number[] | Float32Array;
 
-  /** Span type: 'text' — regular text, 'space' — whitespace span */
-  type: 'text' | 'space';
+  /**
+   * Span type:
+   * - `'text'` — regular text
+   * - `'space'` — whitespace span
+   * - `'marker'` — list marker (bullet / number), rendered like text
+   */
+  type: 'text' | 'space' | 'marker';
 
   /**
    * Trailing whitespace flag.
@@ -74,12 +81,19 @@ export interface SpanFontMetrics {
 // ── Line (single line, formerly LineBox) ─────────────────────────────────
 
 export interface Line {
-  /** Absolute X within container (alignment + indent) */
+  /**
+   * 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 content width (without alignment) */
+  /**
+   * 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;
 
@@ -98,6 +112,9 @@ export interface Line {
   /** Paragraph alignment (optional, for PowerPoint render) */
   alignment?: TextAlignment;
 
+  /** Column index (0-based) when frame has multi-column layout. */
+  columnIndex?: number;
+
   spans: Span[];
 }