@vyaz/renderer 0.0.1

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@vyaz/renderer",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["dist", "src"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun"
+  },
+  "dependencies": {
+    "@vyaz/core": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}

package/src/CanvasRenderer.ts

@@ -0,0 +1,249 @@
+/**
+ * CanvasRenderer.ts — render LineBox[] → Canvas.
+ *
+ * Takes ready LineBox[] with absolute coordinates.
+ * Does not compute anything — only draws (dumb drawer principle).
+ *
+ * Options:
+ *   - sizing: 'frame' | 'content' — auto canvas size
+ *   - preserveSpaces: boolean — draw spaces (instead of skip)
+ *   - backgroundColor: string — background color
+ *   - debug: DebugFlags — debug overlays
+ */
+
+import type { LineBox, FragmentBox } from '@vyaz/core';
+import type { DebugFlags } from './types.js';
+import { computeBBox } from './utils.js';
+
+export interface CanvasRenderOptions {
+  /**
+   * How the canvas size is determined:
+   *   'frame'   — use current ctx.canvas.width/height (default)
+   *   'content' — compute bounding box from lines, resize canvas to fit
+   */
+  sizing?: 'frame' | 'content';
+  /**
+   * When true: render space fragments with a space character.
+   * When false (default): skip space fragments (position is already accounted for in x).
+   */
+  preserveSpaces?: boolean;
+  /** Background color for clearing. If omitted, canvas is cleared transparent. */
+  backgroundColor?: string;
+  /** Debug overlay flags. */
+  debug?: DebugFlags;
+}
+
+/** Font weight to CSS value */
+function fontWeightCSS(weight: string | number): string {
+  if (weight === 'bold') return 'bold';
+  if (weight === 'normal') return 'normal';
+  if (typeof weight === 'number') return String(weight);
+  return 'normal';
+}
+
+/** Font style to CSS value */
+function fontStyleCSS(style: string): string {
+  return style === 'italic' ? 'italic' : 'normal';
+}
+
+/**
+ * Render LineBox[] array to Canvas.
+ *
+ * @param ctx — Canvas 2D rendering context
+ * @param lines — ready LineBox[] with absolute coordinates
+ * @param options — rendering options
+ */
+export function renderToCanvas(
+  ctx: CanvasRenderingContext2D | any,
+  lines: LineBox[],
+  options: CanvasRenderOptions = {},
+): void {
+  const sizing = options.sizing ?? 'frame';
+  const preserveSpaces = options.preserveSpaces ?? false;
+
+  // ── Sizing: content mode resizes canvas ──────────────────────────
+  let canvasWidth: number;
+  let canvasHeight: number;
+
+  if (sizing === 'content') {
+    const bbox = computeBBox(lines);
+    canvasWidth = bbox.width;
+    canvasHeight = bbox.height;
+    ctx.canvas.width = canvasWidth;
+    ctx.canvas.height = canvasHeight;
+  } else {
+    canvasWidth = ctx.canvas.width;
+    canvasHeight = ctx.canvas.height;
+  }
+
+  // ── Background ───────────────────────────────────────────────────
+  if (options.backgroundColor) {
+    ctx.fillStyle = options.backgroundColor;
+    ctx.fillRect(0, 0, canvasWidth, canvasHeight);
+  } else {
+    ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+  }
+
+  // ── Render lines ─────────────────────────────────────────────────
+  for (const line of lines) {
+    const baselineY = line.y + line.baseline;
+
+    for (const frag of line.fragments) {
+      const x = line.x + frag.x;
+
+      // Font setting
+      const style = fontStyleCSS(frag.style.fontStyle);
+      const weight = fontWeightCSS(frag.style.fontWeight);
+      const size = frag.fontMetrics.fontSize;
+      const family = frag.style.fontFamily;
+      ctx.font = `${style} ${weight} ${size}px ${family}`;
+      ctx.fillStyle = frag.style.color || '#000000';
+      ctx.textBaseline = 'alphabetic';
+
+      // Draw text
+      if (preserveSpaces || frag.type !== 'space') {
+        ctx.fillText(frag.text, x, baselineY);
+      }
+
+      // Underline
+      if (frag.style.underline) {
+        const ulY = baselineY + 2;
+        ctx.strokeStyle = frag.style.color || '#000000';
+        ctx.lineWidth = 1;
+        ctx.beginPath();
+        ctx.moveTo(x, ulY);
+        ctx.lineTo(x + frag.width, ulY);
+        ctx.stroke();
+      }
+
+      // Strikethrough
+      if (frag.style.strikethrough) {
+        const stY = baselineY - frag.fontMetrics.ascent * 0.4;
+        ctx.strokeStyle = frag.style.color || '#000000';
+        ctx.lineWidth = 1;
+        ctx.beginPath();
+        ctx.moveTo(x, stY);
+        ctx.lineTo(x + frag.width, stY);
+        ctx.stroke();
+      }
+
+      // InlineWidget (simple rectangle)
+      if (frag.inlineWidget) {
+        const iw = frag.inlineWidget;
+        const iwY = baselineY - (iw.height || frag.fontMetrics.ascent) + (iw.baselineOffset || 0);
+        ctx.fillStyle = '#cccccc';
+        ctx.fillRect(x, iwY, iw.width, iw.height);
+      }
+    }
+  }
+
+  // Debug overlay
+  if (options.debug) {
+    renderDebugToCanvas(ctx, lines, canvasWidth, canvasHeight, options.debug);
+  }
+}
+
+// ── Debug overlay ────────────────────────────────────────────────────
+
+/** Draw debug overlays on canvas */
+export function renderDebugToCanvas(
+  ctx: CanvasRenderingContext2D,
+  lines: LineBox[],
+  _width: number,
+  _height: number,
+  flags: DebugFlags,
+): void {
+  ctx.save();
+
+  // Text frame — outer bounding box of all lines
+  if (flags.frame && lines.length > 0) {
+    const first = lines[0];
+    const last = lines[lines.length - 1];
+    const maxW = Math.max(...lines.map(l => l.x + l.width));
+    const frameX = first.x;
+    const frameY = first.y;
+    const frameW = maxW - frameX;
+    const frameH = last.y + last.height - first.y;
+    ctx.strokeStyle = 'rgba(255,200,0,0.6)';
+    ctx.lineWidth = 1;
+    ctx.setLineDash([6, 2]);
+    ctx.strokeRect(frameX, frameY, frameW, frameH);
+  }
+
+  ctx.setLineDash([]);
+
+  for (const line of lines) {
+    const bx = line.x;
+    const by = line.y;
+    const bw = line.width;
+    const bh = line.height;
+    const baselineY = line.y + line.baseline;
+
+    // Line gap — blue filled rect for lineHeight visualization
+    if (flags.lineGap) {
+      ctx.fillStyle = 'rgba(0,150,255,0.10)';
+      ctx.fillRect(bx, by, bw, bh);
+    }
+
+    // Bounding box — red rect
+    if (flags.box) {
+      ctx.strokeStyle = 'rgba(255,100,100,0.5)';
+      ctx.lineWidth = 1;
+      ctx.strokeRect(bx, by, bw, bh);
+    }
+
+    // Baseline — blue line
+    if (flags.baseline) {
+      ctx.strokeStyle = 'rgba(100,100,255,0.5)';
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(bx, baselineY);
+      ctx.lineTo(bx + bw, baselineY);
+      ctx.stroke();
+    }
+
+    // Ascent / Descent — green dashed lines
+    if (flags.ascentDescent) {
+      const ascentY = baselineY - line.ascent;
+      const descentY = baselineY + line.descent;
+      ctx.strokeStyle = 'rgba(100,255,100,0.4)';
+      ctx.lineWidth = 0.5;
+      ctx.setLineDash([3, 2]);
+      ctx.beginPath();
+      ctx.moveTo(bx, ascentY);
+      ctx.lineTo(bx + bw, ascentY);
+      ctx.stroke();
+      ctx.beginPath();
+      ctx.moveTo(bx, descentY);
+      ctx.lineTo(bx + bw, descentY);
+      ctx.stroke();
+      ctx.setLineDash([]);
+    }
+
+    // Labels — small monospace text
+    if (flags.labels) {
+      const labelY = by - 2;
+      const label = `y=${by.toFixed(1)} x=${bx.toFixed(1)} w=${bw.toFixed(1)} h=${bh.toFixed(1)} bl=${baselineY.toFixed(1)}`;
+      ctx.font = '9px monospace';
+      ctx.fillStyle = 'rgba(0,0,0,0.55)';
+      ctx.textBaseline = 'bottom';
+      ctx.fillText(label, bx, labelY);
+    }
+
+    // Run boxes — purple rects around FragmentBox
+    if (flags.runs) {
+      for (const frag of line.fragments) {
+        if (frag.width <= 0) continue;
+        const rx = line.x + frag.x;
+        const ry = baselineY - frag.fontMetrics.ascent;
+        const rw = frag.width;
+        const rh = frag.fontMetrics.ascent + frag.fontMetrics.descent;
+        ctx.strokeStyle = 'rgba(200,100,255,0.4)';
+        ctx.lineWidth = 0.5;
+        ctx.strokeRect(rx, ry, rw, rh);
+      }
+    }
+  }
+
+  ctx.restore();
+}

package/src/SVGRenderer.ts

@@ -0,0 +1,536 @@
+/**
+ * SVGRenderer.ts — SVG text builder.
+ *
+ * Converts LineBox[] into SVG markup using a builder pattern.
+ *
+ * Three presets:
+ *   flat     — all text in one <text> element, xml:space="preserve", no <tspan>
+ *   browser  — expanded <tspan> per run, NO xml:space, spaces skipped (browser collapses them)
+ *   preserve — expanded <tspan> per run, xml:space="preserve", spaces render as <tspan> </tspan>,
+ *              textLength on each line by default for pixel-perfect width
+ *
+ * Usage:
+ *   const svg = renderToSVG(lines, { preset: 'browser' })
+ *   const svg = renderToSVG(lines, { preset: 'preserve', style: 'css', fit: 'frag' })
+ */
+
+import type { LineBox, FragmentBox, ParagraphLayoutResult } from '@vyaz/core';
+import type { DebugFlags } from './types.js';
+import { computeBBox } from './utils.js';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type SvgPreset = 'flat' | 'browser' | 'preserve' | 'glyph';
+
+export type SvgStyle = 'css' | 'xml';
+
+export type SvgFit = 'none' | 'text' | 'frag';
+
+export type SvgSizing = 'frame' | 'content';
+
+export interface SVGRenderOptions {
+  /** Shorthand that sets structure + spacing at once. */
+  preset?: SvgPreset;
+  /** How style properties are expressed: as CSS `style` attribute or as XML presentation attributes. */
+  style?: SvgStyle;
+  /** How `textLength` is applied. */
+  fit?: SvgFit;
+  /** How SVG determines its size: 'frame' — use width/height from options; 'content' — compute BBox from lines. */
+  sizing?: SvgSizing;
+  /** SVG canvas width (px). Used when sizing='frame' or as fallback. */
+  width?: number;
+  /** SVG canvas height (px). Used when sizing='frame' or as fallback. */
+  height?: number;
+  /** CSS class for `<svg>`. */
+  className?: string;
+  /** Debug overlays. */
+  debug?: DebugFlags;
+}
+
+type SpacingMode = 'browser' | 'preserve';
+type StructureMode = 'flat' | 'expanded' | 'glyph';
+
+type ResolvedOptions = {
+  structure: StructureMode;
+  spacing: SpacingMode;
+  style: 'css' | 'xml';
+  fit: 'none' | 'text' | 'frag';
+  sizing: 'frame' | 'content';
+  width?: number;
+  height?: number;
+  className?: string;
+  debug?: DebugFlags;
+};
+
+// ── Preset map ───────────────────────────────────────────────────────────
+
+const PRESETS: Record<SvgPreset, { structure: StructureMode; spacing: SpacingMode; defaultFit: SvgFit }> = {
+  flat:     { structure: 'flat',     spacing: 'preserve', defaultFit: 'none' },
+  browser:  { structure: 'expanded', spacing: 'browser',  defaultFit: 'none' },
+  preserve: { structure: 'expanded', spacing: 'preserve', defaultFit: 'none' },
+  glyph:    { structure: 'glyph',    spacing: 'preserve', defaultFit: 'none' },
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, '&#38;')
+    .replace(/</g, '&#60;')
+    .replace(/>/g, '&#62;')
+    .replace(/"/g, '&#34;');
+}
+
+function fontWeightCSS(weight: string | number): string {
+  if (weight === 'bold') return 'bold';
+  if (weight === 'normal') return '400';
+  if (typeof weight === 'number') return String(weight);
+  return '400';
+}
+
+function fontWeightNumeric(weight: string | number): number {
+  if (weight === 'bold') return 700;
+  if (weight === 'normal') return 400;
+  if (typeof weight === 'number') return weight;
+  return 400;
+}
+
+function colorToRGB(color: string): string {
+  if (!color) return 'rgb(0, 0, 0)';
+  let hex = color;
+  if (hex.length === 4 && hex[0] === '#') {
+    hex = `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`;
+  }
+  if (hex.length === 7 && hex[0] === '#') {
+    return `rgb(${parseInt(hex.slice(1, 3), 16)}, ${parseInt(hex.slice(3, 5), 16)}, ${parseInt(hex.slice(5, 7), 16)})`;
+  }
+  return 'rgb(0, 0, 0)';
+}
+
+/** Compute gutter widths per line for justify alignment */
+function computeGutterWidths(line: LineBox, totalSlack: number): number[] {
+  const spaceFrags = line.fragments.filter(f => f.type === 'space' || f.text.trim() === '');
+  if (spaceFrags.length === 0) return [];
+  const perGap = totalSlack / spaceFrags.length;
+  return line.fragments.map(f => (f.type === 'space' || f.text.trim() === '') ? perGap : 0);
+}
+
+// ── Resolve options ──────────────────────────────────────────────────────
+
+function resolveOptions(opts: SVGRenderOptions): ResolvedOptions {
+  let structure: StructureMode;
+  let spacing: SpacingMode;
+  let defaultFit: SvgFit;
+
+  if (opts.preset) {
+    const preset = PRESETS[opts.preset];
+    if (!preset) {
+      console.warn(`SVGRenderer: unknown preset "${opts.preset}", falling back to browser`);
+      structure = 'expanded';
+      spacing = 'browser';
+      defaultFit = 'none';
+    } else {
+      structure = preset.structure;
+      spacing = preset.spacing;
+      defaultFit = preset.defaultFit;
+    }
+  } else {
+    structure = 'expanded';
+    spacing = 'browser';
+    defaultFit = 'none';
+  }
+
+  const style = opts.style ?? 'xml';
+  let fit = opts.fit ?? defaultFit;
+  const sizing = opts.sizing ?? 'frame';
+
+  // Validation rules
+  if (structure === 'glyph' && fit !== 'none') {
+    console.warn(`SVGRenderer: fit="${fit}" is ignored when structure="glyph"`);
+    fit = 'none';
+  }
+  if (structure === 'flat' && fit === 'frag') {
+    console.warn(`SVGRenderer: fit="frag" downgraded to "text" when structure="flat"`);
+    fit = 'text';
+  }
+
+  return { structure, spacing, style, fit, sizing, width: opts.width, height: opts.height, className: opts.className, debug: opts.debug };
+}
+
+// ── Attribute builders ───────────────────────────────────────────────────
+
+interface StyleState {
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: number;
+  color: string;
+  fontStyle: string;
+  decoration: string;
+}
+
+function defaultStyleState(frag: FragmentBox): StyleState {
+  return {
+    fontFamily: frag.style.fontFamily || 'Arial',
+    fontSize: frag.fontMetrics.fontSize || 16,
+    fontWeight: fontWeightNumeric(frag.style.fontWeight),
+    color: frag.style.color || '#000000',
+    fontStyle: frag.style.fontStyle || 'normal',
+    decoration: frag.style.underline ? 'underline' : frag.style.strikethrough ? 'line-through' : '',
+  };
+}
+
+function equalStyle(a: StyleState, b: StyleState): boolean {
+  return a.fontFamily === b.fontFamily && a.fontSize === b.fontSize &&
+    a.fontWeight === b.fontWeight && a.color === b.color &&
+    a.fontStyle === b.fontStyle && a.decoration === b.decoration;
+}
+
+/** Build style string for CSS mode */
+function cssStyleString(s: StyleState): string {
+  const parts: string[] = [];
+  parts.push(`font-family: '${s.fontFamily}', sans-serif`);
+  parts.push(`font-size: ${s.fontSize}px`);
+  parts.push(`fill: ${colorToRGB(s.color)}`);
+  if (s.fontWeight !== 400) parts.push(`font-weight: ${s.fontWeight}`);
+  if (s.fontStyle === 'italic') parts.push(`font-style: italic`);
+  if (s.decoration) parts.push(`text-decoration: ${s.decoration}`);
+  return parts.join('; ');
+}
+
+/** Build XML presentation attributes for a style */
+function xmlStyleAttrs(s: StyleState): string {
+  let attrs = `font-family="${s.fontFamily}" font-size="${s.fontSize}" fill="${s.color}" font-weight="${s.fontWeight}"`;
+  if (s.fontStyle === 'italic') attrs += ' font-style="italic"';
+  if (s.decoration) attrs += ` text-decoration="${s.decoration}"`;
+  return attrs;
+}
+
+/** Build attributes for <text> element */
+function buildTextAttrs(line: LineBox, frag: FragmentBox, opts: ResolvedOptions, runId?: string): string {
+  const x = line.x;
+  const y = line.y + line.baseline;
+  const s = defaultStyleState(frag);
+
+  let attrs = ` x="${x}" y="${y}"`;
+  if (runId) attrs += ` id="${runId}"`;
+
+  if (opts.style === 'css') {
+    let css = cssStyleString(s);
+    if (opts.spacing === 'preserve') css += '; white-space: pre';
+    attrs += ` style="${css}"`;
+  } else {
+    attrs += ` ${xmlStyleAttrs(s)}`;
+    if (opts.spacing === 'preserve') attrs += ' xml:space="preserve"';
+  }
+
+  // text-anchor is only meaningful for flat mode where text sits directly in <text>.
+  // For expanded/glyph modes, each <tspan> has explicit x="..." coordinates that already
+  // account for alignment — text-anchor on <text> would then double-shift the text.
+  if (opts.structure === 'flat') {
+    const anchor = line.alignment === 'center' ? 'middle' : line.alignment === 'right' ? 'end' : 'start';
+    if (anchor !== 'start') attrs += ` text-anchor="${anchor}"`;
+  }
+
+  return attrs;
+}
+
+/** Build attributes for <tspan> (expanded mode — only diff from current style) */
+function buildTspanAttrs(frag: FragmentBox, x: number, currentStyle: StyleState | null): { attrs: string; newStyle: StyleState } {
+  const s = defaultStyleState(frag);
+  let attrs = ` x="${x}"`;
+
+  if (currentStyle && equalStyle(s, currentStyle)) {
+    return { attrs, newStyle: s };
+  }
+
+  // textLength is NOT added here — it is handled by buildFragFitAttr() separately
+  // to avoid duplicate textLength when fit='frag'.
+
+  if (!currentStyle || s.fontWeight !== currentStyle.fontWeight) attrs += ` font-weight="${s.fontWeight}"`;
+  if (!currentStyle || s.fontStyle !== currentStyle.fontStyle) attrs += ` font-style="${s.fontStyle}"`;
+  if (!currentStyle || s.fontFamily !== currentStyle.fontFamily) attrs += ` font-family="${s.fontFamily}"`;
+  if (!currentStyle || s.fontSize !== currentStyle.fontSize) attrs += ` font-size="${s.fontSize}"`;
+  if (!currentStyle || s.color !== currentStyle.color) attrs += ` fill="${s.color}"`;
+  if (!currentStyle || s.decoration !== currentStyle.decoration) {
+    if (s.decoration) attrs += ` text-decoration="${s.decoration}"`;
+  }
+
+  return { attrs, newStyle: s };
+}
+
+/** Build per-glyph x positions for glyph mode */
+function buildGlyphPositions(frag: FragmentBox, _lineX: number): string {
+  if (!frag.glyphAdvances || frag.glyphAdvances.length === 0) {
+    return '';
+  }
+  // frag.x is already absolute — computed by PositioningEngine.
+  // lineX is NOT added because that would double-shift.
+  const fragX = frag.x;
+  let xPos = fragX;
+  const positions: string[] = [xPos.toFixed(1)];
+  for (let i = 0; i < frag.glyphAdvances.length - 1; i++) {
+    xPos += frag.glyphAdvances[i];
+    positions.push(xPos.toFixed(1));
+  }
+  return positions.join(' ');
+}
+
+/** Build textLength attribute for a line */
+function buildFitAttr(line: LineBox, opts: ResolvedOptions): string {
+  if (opts.fit === 'text') {
+    return ` textLength="${line.width}" lengthAdjust="spacing"`;
+  }
+  return '';
+}
+
+/** Build textLength for a fragment */
+function buildFragFitAttr(frag: FragmentBox, opts: ResolvedOptions): string {
+  if (opts.fit === 'frag') {
+    return ` textLength="${frag.width}"`;
+  }
+  return '';
+}
+
+// ── SVG builder ──────────────────────────────────────────────────────────
+
+class SvgBuilder {
+  private parts: string[] = [];
+  private opts: ResolvedOptions;
+
+  constructor(width: number, height: number, opts: ResolvedOptions) {
+    this.opts = opts;
+    const className = opts.className ? ` class="${escapeXml(opts.className)}"` : '';
+    this.parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"${className}>\n`);
+    if (opts.className) {
+      this.parts[0] = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" class="${escapeXml(opts.className)}">\n`;
+    }
+  }
+
+  addText(line: LineBox, baseFrag: FragmentBox, runId?: string): void {
+    const attrs = buildTextAttrs(line, baseFrag, this.opts, runId);
+    const fit = buildFitAttr(line, this.opts);
+    this.parts.push(`  <text${attrs}${fit}>\n`);
+  }
+
+  addFlatFrag(text: string): void {
+    this.parts.push(`    ${escapeXml(text)}`);
+  }
+
+  addExpandedFrag(frag: FragmentBox, x: number, style: StyleState | null): StyleState {
+    const { attrs, newStyle } = buildTspanAttrs(frag, x, style);
+    const fit = buildFragFitAttr(frag, this.opts);
+    this.parts.push(`    <tspan${attrs}${fit}>${escapeXml(frag.text)}</tspan>\n`);
+    return newStyle;
+  }
+
+  addGlyphFrag(frag: FragmentBox, lineX: number): void {
+    const positions = buildGlyphPositions(frag, lineX);
+    if (positions) {
+      this.parts.push(`    <tspan x="${positions}">${escapeXml(frag.text)}</tspan>\n`);
+    } else {
+      this.parts.push(`    <tspan>${escapeXml(frag.text)}</tspan>\n`);
+    }
+  }
+
+  closeText(): void {
+    this.parts.push('  </text>\n');
+  }
+
+  addDebug(debugOverlay: string): void {
+    if (debugOverlay) {
+      this.parts.push(`<!-- debug overlay -->\n${debugOverlay}\n`);
+    }
+  }
+
+  build(): string {
+    this.parts.push('</svg>\n');
+    return this.parts.join('');
+  }
+}
+
+// ── Debug overlay ────────────────────────────────────────────────────────
+
+function renderDebugToSVG(lines: LineBox[], width: number, height: number, flags: DebugFlags): string {
+  const parts: string[] = [];
+
+  if (flags.frame && lines.length > 0) {
+    const first = lines[0];
+    const last = lines[lines.length - 1];
+    const maxW = Math.max(...lines.map(l => l.x + l.width));
+    parts.push(
+      `  <rect x="${first.x}" y="${first.y}" width="${maxW - first.x}" height="${last.y + last.height - first.y}"` +
+      ` fill="none" stroke="rgba(255,200,0,0.6)" stroke-width="1" stroke-dasharray="6,2" />`,
+    );
+  }
+
+  for (const line of lines) {
+    const bx = line.x, by = line.y, bw = line.width, bh = line.height;
+    const baselineY = line.y + line.baseline;
+
+    if (flags.lineGap) {
+      parts.push(`  <rect x="${bx}" y="${by}" width="${bw}" height="${bh}" fill="rgba(0,150,255,0.10)" stroke="none" />`);
+    }
+    if (flags.box) {
+      parts.push(`  <rect x="${bx}" y="${by}" width="${bw}" height="${bh}" fill="none" stroke="rgba(255,100,100,0.5)" stroke-width="1" />`);
+    }
+    if (flags.baseline) {
+      parts.push(`  <line x1="${bx}" y1="${baselineY}" x2="${bx + bw}" y2="${baselineY}" stroke="rgba(100,100,255,0.5)" stroke-width="1" />`);
+    }
+    if (flags.ascentDescent) {
+      parts.push(`  <line x1="${bx}" y1="${baselineY - line.ascent}" x2="${bx + bw}" y2="${baselineY - line.ascent}" stroke="rgba(100,255,100,0.4)" stroke-width="0.5" stroke-dasharray="3,2" />`);
+      parts.push(`  <line x1="${bx}" y1="${baselineY + line.descent}" x2="${bx + bw}" y2="${baselineY + line.descent}" stroke="rgba(100,255,100,0.4)" stroke-width="0.5" stroke-dasharray="3,2" />`);
+    }
+    if (flags.labels) {
+      parts.push(`  <text x="${bx}" y="${by - 2}" font-size="9" fill="rgba(0,0,0,0.55)" font-family="monospace">y=${by.toFixed(1)} x=${bx.toFixed(1)} w=${bw.toFixed(1)} h=${bh.toFixed(1)} bl=${baselineY.toFixed(1)}</text>`);
+    }
+    if (flags.runs) {
+      for (const frag of line.fragments) {
+        if (frag.width <= 0) continue;
+        const rx = line.x + frag.x;
+        const ry = baselineY - frag.fontMetrics.ascent;
+        parts.push(`  <rect x="${rx}" y="${ry}" width="${frag.width}" height="${frag.fontMetrics.ascent + frag.fontMetrics.descent}" fill="none" stroke="rgba(200,100,255,0.4)" stroke-width="0.5" />`);
+      }
+    }
+  }
+
+  return parts.join('\n');
+}
+
+// ── Main render logic ────────────────────────────────────────────────────
+
+/**
+ * Render LineBox[] into SVG string.
+ *
+ * @param lines — layout lines with fragments
+ * @param options — rendering options (preset + style/fit/sizing modifiers)
+ * @returns SVG string
+ */
+export function renderToSVG(lines: LineBox[], options: SVGRenderOptions = {}): string {
+  const opts = resolveOptions(options);
+
+  // Determine canvas size
+  let svgWidth: number;
+  let svgHeight: number;
+
+  if (opts.sizing === 'content') {
+    const bbox = computeBBox(lines);
+    svgWidth = bbox.width;
+    svgHeight = bbox.height;
+  } else {
+    // sizing='frame' requires explicit width/height — no fallback
+    if (opts.width === undefined || opts.height === undefined) {
+      throw new Error(
+        `renderToSVG: sizing="frame" requires explicit width and height. ` +
+        `Got width=${opts.width}, height=${opts.height}. ` +
+        `Use renderResultToSVG(result, options) to auto-pass dimensions.`
+      );
+    }
+    svgWidth = opts.width;
+    svgHeight = opts.height;
+  }
+
+  const builder = new SvgBuilder(svgWidth, svgHeight, opts);
+
+  for (const line of lines) {
+    if (opts.structure === 'glyph') {
+      // Per-glyph positioning with run-based <text> grouping
+      let currentRunIdx = -1;
+      for (const frag of line.fragments) {
+        if (!frag.text) continue;
+        const runIdx = frag.itemIndex;
+        if (runIdx !== currentRunIdx) {
+          if (currentRunIdx !== -1) {
+            builder.closeText();
+          }
+          const runId = frag.paragraphId ? `${frag.paragraphId}-${runIdx}` : undefined;
+          builder.addText(line, frag, runId);
+          currentRunIdx = runIdx;
+        }
+        builder.addGlyphFrag(frag, line.x);
+      }
+      if (currentRunIdx !== -1) {
+        builder.closeText();
+      }
+    } else {
+      // flat / expanded: single <text> per line
+      const baseFrag = line.fragments.find(f => f.type === 'text' && f.text.length > 0) || line.fragments[0];
+      if (!baseFrag) continue;
+
+      builder.addText(line, baseFrag);
+
+      if (opts.structure === 'flat') {
+        // Concatenate all text on the line
+        const fullText = line.fragments.map(f => f.text).join('');
+        builder.addFlatFrag(fullText);
+      } else {
+        // expanded: each fragment as <tspan> with diff styles
+        let currentStyle: StyleState | null = null;
+        for (const frag of line.fragments) {
+          if (!frag.text) continue;
+          const x = frag.x;
+
+          const shouldRender = frag.type !== 'space' || opts.spacing === 'preserve';
+          if (shouldRender) {
+            const newStyle = builder.addExpandedFrag(frag, x, currentStyle);
+            if (frag.type !== 'space') {
+              currentStyle = newStyle;
+            }
+          }
+        }
+      }
+
+      builder.closeText();
+    }
+  }
+
+  if (opts.debug) {
+    const debugSvg = renderDebugToSVG(lines, svgWidth, svgHeight, opts.debug);
+    builder.addDebug(debugSvg);
+  }
+
+  return builder.build();
+}
+
+/**
+ * Render one ParagraphLayoutResult to SVG (convenience wrapper).
+ */
+export function renderParagraphToSVG(
+  lines: LineBox[],
+  paragraphWidth: number,
+  paragraphHeight: number,
+  options?: SVGRenderOptions,
+): string {
+  return renderToSVG(lines, {
+    width: paragraphWidth,
+    height: paragraphHeight,
+    ...options,
+  });
+}
+
+/**
+ * Render a ParagraphLayoutResult to SVG, auto-passing dimensions.
+ *
+ * Uses `result.width` and `result.height` as the SVG canvas size.
+ * This is the recommended way to render when you have a layout result
+ * and want `sizing: 'frame'` with correct dimensions.
+ *
+ * @param result — layout result from ParagraphLayoutEngine.layout()
+ * @param options — rendering options (preset, style, fit, etc.)
+ * @returns SVG string
+ *
+ * @example
+ * ```ts
+ * const result = paragraphLayoutEngine.layout(paragraph, 300);
+ * const svg = renderResultToSVG(result, { preset: 'preserve' });
+ * ```
+ */
+export function renderResultToSVG(
+  result: ParagraphLayoutResult,
+  options?: SVGRenderOptions,
+): string {
+  return renderToSVG(result.lines, {
+    width: result.width,
+    height: result.height,
+    ...options,
+  });
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @vyaz/renderer — SVG and Canvas renderers.
+ *
+ * Converts LineBox[] (from @vyaz/core) into SVG strings or Canvas drawings.
+ */
+
+export { renderToSVG, renderParagraphToSVG, renderResultToSVG } from './SVGRenderer.js';
+export type { SVGRenderOptions, SvgPreset, SvgStyle, SvgFit, SvgSizing } from './SVGRenderer.js';
+
+export { renderToCanvas, renderDebugToCanvas } from './CanvasRenderer.js';
+export type { CanvasRenderOptions } from './CanvasRenderer.js';
+
+export type { DebugFlags } from './types.js';

package/src/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Render types shared across all renderers (SVG, Canvas, etc.).
+ */
+
+export interface DebugFlags {
+  box?: boolean;
+  baseline?: boolean;
+  ascentDescent?: boolean;
+  frame?: boolean;
+  labels?: boolean;
+  runs?: boolean;
+  /** Show filled rect for each line's lineHeight (background fill). */
+  lineGap?: boolean;
+}

package/src/utils.ts

@@ -0,0 +1,15 @@
+/**
+ * render/utils.ts — shared renderer utilities.
+ */
+
+import type { LineBox } from '@vyaz/core';
+
+/**
+ * Compute the bounding box (content width + height) from an array of LineBox.
+ */
+export function computeBBox(lines: LineBox[]): { width: number; height: number } {
+  if (lines.length === 0) return { width: 0, height: 0 };
+  const width = Math.max(...lines.map(l => l.x + l.width));
+  const height = lines[lines.length - 1].y + lines[lines.length - 1].height;
+  return { width, height };
+}