@vyaz/renderer 0.0.1 → 0.0.3

package/src/SVGRenderer.ts

@@ -1,22 +1,27 @@
 /**
  * SVGRenderer.ts — SVG text builder.
  *
- * Converts LineBox[] into SVG markup using a builder pattern.
+ * Converts Line[] into SVG markup using an AST-first approach.
+ * Builds a tree of SvgNode, then serializes to string in one pass.
  *
- * Three presets:
+ * Four 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
+ *   browser  — expanded <tspan> per run, xml:space="preserve", diff attributes, no textLength
+ *   preserve — expanded <tspan> per run, xml:space="preserve", diff attributes, textLength
+ *   glyph    — <tspan> per glyph with per-character x positions, xml:space="preserve"
+ *
+ * All presets preserve whitespace via xml:space="preserve". Space spans (type: 'space')
+ * are rendered as separate <tspan> elements with explicit x coordinates.
  *
  * 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';
+import type { Line, Span, ParagraphLayoutResult, ParagraphGroup, MultiColumnConfig } from '@vyaz/core';
+import { groupLinesByParagraph } from '@vyaz/core';
+import type { DebugFlags, SvgElement, SvgNode } from './types.js';
+import { computeBBox, fmt } from './utils.js';
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -28,6 +33,8 @@ export type SvgFit = 'none' | 'text' | 'frag';
 
 export type SvgSizing = 'frame' | 'content';
 
+export type PerAxisSizing = { horizontal: SvgSizing; vertical: SvgSizing };
+
 export interface SVGRenderOptions {
   /** Shorthand that sets structure + spacing at once. */
   preset?: SvgPreset;
@@ -35,16 +42,35 @@ export interface SVGRenderOptions {
   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. */
+  /**
+   * How SVG determines its canvas size.
+   * Single string: applies to both axes. Object: per-axis control.
+   * 'frame' — use explicit width/height from options.
+   * 'content' — compute from lines bounding box.
+   */
+  sizing?: SvgSizing | PerAxisSizing;
+  /** SVG canvas width (px). Used when horizontal sizing='frame' or as fallback. */
   width?: number;
-  /** SVG canvas height (px). Used when sizing='frame' or as fallback. */
+  /** SVG canvas height (px). Used when vertical sizing='frame' or as fallback. */
   height?: number;
   /** CSS class for `<svg>`. */
   className?: string;
+  /**
+   * Extra padding added around the SVG canvas. Content coordinates stay unchanged;
+   * the SVG viewBox is shifted and canvas is enlarged so debug overlays
+   * (frameBox / contentBox) are visible with a gap from the edge.
+   * Useful for snapshot tests to clearly show frame vs content boundaries.
+   */
+  contentPadding?: number;
   /** Debug overlays. */
   debug?: DebugFlags;
+  /**
+   * Multi-column layout configuration for debug overlays.
+   * When set, paragraph and column boxes are rendered per-column.
+   */
+  columns?: MultiColumnConfig;
+  /** Left padding from frame (needed for column debug rendering). */
+  paddingLeft?: number;
 }
 
 type SpacingMode = 'browser' | 'preserve';
@@ -55,10 +81,12 @@ type ResolvedOptions = {
   spacing: SpacingMode;
   style: 'css' | 'xml';
   fit: 'none' | 'text' | 'frag';
-  sizing: 'frame' | 'content';
+  sizingHorizontal: 'frame' | 'content';
+  sizingVertical: 'frame' | 'content';
   width?: number;
   height?: number;
   className?: string;
+  contentPadding: number;
   debug?: DebugFlags;
 };
 
@@ -66,8 +94,8 @@ type ResolvedOptions = {
 
 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' },
+  browser:  { structure: 'expanded', spacing: 'preserve', defaultFit: 'none' },
+  preserve: { structure: 'expanded', spacing: 'preserve', defaultFit: 'frag' },
   glyph:    { structure: 'glyph',    spacing: 'preserve', defaultFit: 'none' },
 };
 
@@ -97,22 +125,28 @@ function fontWeightNumeric(weight: string | number): number {
 
 function colorToRGB(color: string): string {
   if (!color) return 'rgb(0, 0, 0)';
+  if (color[0] !== '#') return color;
+
   let hex = color;
-  if (hex.length === 4 && hex[0] === '#') {
+  if (hex.length === 4) {
     hex = `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`;
   }
-  if (hex.length === 7 && hex[0] === '#') {
+  if (hex.length === 7) {
     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)';
+  if (hex.length === 9) {
+    const a = parseInt(hex.slice(7, 9), 16) / 255;
+    return `rgba(${parseInt(hex.slice(1, 3), 16)}, ${parseInt(hex.slice(3, 5), 16)}, ${parseInt(hex.slice(5, 7), 16)}, ${a.toFixed(3)})`;
+  }
+  return color;
 }
 
 /** 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);
+function computeGutterWidths(line: Line, totalSlack: number): number[] {
+  const spaceSpans = line.spans.filter(f => f.type === 'space' || f.text.trim() === '');
+  if (spaceSpans.length === 0) return [];
+  const perGap = totalSlack / spaceSpans.length;
+  return line.spans.map(f => (f.type === 'space' || f.text.trim() === '') ? perGap : 0);
 }
 
 // ── Resolve options ──────────────────────────────────────────────────────
@@ -142,7 +176,19 @@ function resolveOptions(opts: SVGRenderOptions): ResolvedOptions {
 
   const style = opts.style ?? 'xml';
   let fit = opts.fit ?? defaultFit;
-  const sizing = opts.sizing ?? 'frame';
+
+  // Normalize per-axis sizing
+  let sizingHorizontal: 'frame' | 'content';
+  let sizingVertical: 'frame' | 'content';
+
+  if (typeof opts.sizing === 'object' && opts.sizing !== null) {
+    sizingHorizontal = opts.sizing.horizontal ?? 'frame';
+    sizingVertical = opts.sizing.vertical ?? 'frame';
+  } else {
+    const s = opts.sizing ?? 'frame';
+    sizingHorizontal = s;
+    sizingVertical = s;
+  }
 
   // Validation rules
   if (structure === 'glyph' && fit !== 'none') {
@@ -154,7 +200,80 @@ function resolveOptions(opts: SVGRenderOptions): ResolvedOptions {
     fit = 'text';
   }
 
-  return { structure, spacing, style, fit, sizing, width: opts.width, height: opts.height, className: opts.className, debug: opts.debug };
+  return { structure, spacing, style, fit, sizingHorizontal, sizingVertical, width: opts.width, height: opts.height, className: opts.className, contentPadding: opts.contentPadding ?? 0, debug: opts.debug };
+}
+
+/**
+ * Resolve final SVG canvas width/height + viewBox.
+ *
+ * When either axis uses 'content' sizing, computes the BBox from lines.
+ */
+function resolveSize(lines: Line[], opts: ResolvedOptions): { width: number; height: number; viewBox: { x: number; y: number; w: number; h: number }; frameWidth?: number; frameHeight?: number } {
+  const needsBBox = opts.sizingHorizontal === 'content' || opts.sizingVertical === 'content';
+  const bbox = needsBBox ? computeBBox(lines) : null;
+
+  // Original frame dimensions (from user options) — used for frameBox overlay.
+  // Only set when the user explicitly provided a value, regardless of sizing mode.
+  // (sizing='frame' uses opts.width/height; sizing='content' may also have a frame value
+  //  passed explicitly for frameBox purposes.)
+  const frameWidth = opts.width;
+  const frameHeight = opts.height;
+
+  let width: number;
+  let height: number;
+
+  if (opts.sizingHorizontal === 'content') {
+    width = bbox!.width;
+  } else {
+    if (opts.width === undefined) {
+      throw new Error(
+        `renderToSVG: horizontal sizing="frame" requires explicit width. ` +
+        `Got width=${opts.width}.`
+      );
+    }
+    width = opts.width;
+  }
+
+  if (opts.sizingVertical === 'content') {
+    height = bbox!.height;
+  } else {
+    if (opts.height === undefined) {
+      throw new Error(
+        `renderToSVG: vertical sizing="frame" requires explicit height. ` +
+        `Got height=${opts.height}.`
+      );
+    }
+    height = opts.height;
+  }
+
+  // viewBox: derived per-axis. If an axis uses 'content' sizing, use the content bbox
+  // for that axis; otherwise use the frame dimension.
+  let viewBox: { x: number; y: number; w: number; h: number };
+  if (bbox) {
+    viewBox = {
+      x: opts.sizingHorizontal === 'content' ? bbox.x : 0,
+      y: opts.sizingVertical === 'content' ? bbox.y : 0,
+      w: opts.sizingHorizontal === 'content' ? bbox.width : width,
+      h: opts.sizingVertical === 'content' ? bbox.height : height,
+    };
+  } else {
+    viewBox = { x: 0, y: 0, w: width, h: height };
+  }
+
+  // Apply contentPadding: enlarge canvas and shift viewBox so padded area is visible
+  const pad = opts.contentPadding || 0;
+  if (pad > 0) {
+    width += pad * 2;
+    height += pad * 2;
+    viewBox = {
+      x: viewBox.x - pad,
+      y: viewBox.y - pad,
+      w: viewBox.w + pad * 2,
+      h: viewBox.h + pad * 2,
+    };
+  }
+
+  return { width, height, viewBox, frameWidth, frameHeight };
 }
 
 // ── Attribute builders ───────────────────────────────────────────────────
@@ -166,78 +285,117 @@ interface StyleState {
   color: string;
   fontStyle: string;
   decoration: string;
+  letterSpacing?: number;
+  backgroundColor?: string;
 }
 
-function defaultStyleState(frag: FragmentBox): StyleState {
+function defaultStyleState(span: Span): StyleState {
+  const decorations: string[] = [];
+  if (span.style.underline) decorations.push('underline');
+  if (span.style.strikethrough) decorations.push('line-through');
+
   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' : '',
+    fontFamily: span.style.fontFamily || 'Arial',
+    fontSize: span.fontMetrics.fontSize || 16,
+    fontWeight: fontWeightNumeric(span.style.fontWeight),
+    color: span.style.color || '#000000',
+    fontStyle: span.style.fontStyle || 'normal',
+    decoration: decorations.join(' '),
+    letterSpacing: span.style.letterSpacing,
+    backgroundColor: span.style.backgroundColor,
   };
 }
 
 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;
+    a.fontStyle === b.fontStyle && a.decoration === b.decoration &&
+    a.letterSpacing === b.letterSpacing &&
+    a.backgroundColor === b.backgroundColor;
+}
+
+/**
+ * Compute a deterministic string key for a span's style.
+ * Used to group spans by identical style when building <text> elements.
+ */
+function styleSignature(span: Span): string {
+  const s = defaultStyleState(span);
+  return `${s.fontFamily}|${s.fontSize}|${s.fontWeight}|${s.color}|${s.fontStyle}|${s.decoration}|${s.letterSpacing ?? ''}|${s.backgroundColor ?? ''}`;
 }
 
 /** 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(`font-size: ${fmt(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}`);
+  if (s.letterSpacing !== undefined && s.letterSpacing !== 0) parts.push(`letter-spacing: ${fmt(s.letterSpacing)}px`);
   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}"`;
+  let attrs = `font-family="${s.fontFamily}" font-size="${fmt(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}"`;
+  if (s.letterSpacing !== undefined && s.letterSpacing !== 0) attrs += ` letter-spacing="${fmt(s.letterSpacing)}"`;
   return attrs;
 }
 
-/** Build attributes for <text> element */
-function buildTextAttrs(line: LineBox, frag: FragmentBox, opts: ResolvedOptions, runId?: string): string {
+/** Build attributes for <text> element.
+ *
+ * NOTE: `text-decoration` and `letter-spacing` are intentionally NOT added
+ * here because they would be inherited by all child `<tspan>` elements.
+ * SVG text-decoration on `<text>` cascades to ALL `<tspan>` descendants,
+ * even those that should NOT have decoration. These attributes are set
+ * on `<tspan>` level by `buildTspanAttrs()` instead.
+ *
+ * Flat mode (no `<tspan>`) adds them separately in the flat render path.
+ */
+function buildTextAttrs(line: Line, span: Span, opts: ResolvedOptions, runId?: string): Record<string, string | number> {
   const x = line.x;
   const y = line.y + line.baseline;
-  const s = defaultStyleState(frag);
+  const s = defaultStyleState(span);
 
-  let attrs = ` x="${x}" y="${y}"`;
-  if (runId) attrs += ` id="${runId}"`;
+  const attrs: Record<string, string | number> = {
+    x: fmt(x),
+    y: fmt(y),
+  };
+  if (runId) attrs.id = runId;
 
   if (opts.style === 'css') {
-    let css = cssStyleString(s);
+    // text-decoration and letter-spacing are intentionally excluded
+    // from <text> to prevent inheritance by child <tspan> elements.
+    let css = `font-family: '${s.fontFamily}', sans-serif; font-size: ${fmt(s.fontSize)}px; fill: ${colorToRGB(s.color)}; font-weight: ${s.fontWeight}`;
+    if (s.fontStyle === 'italic') css += `; font-style: italic`;
     if (opts.spacing === 'preserve') css += '; white-space: pre';
-    attrs += ` style="${css}"`;
+    attrs.style = css;
   } else {
-    attrs += ` ${xmlStyleAttrs(s)}`;
-    if (opts.spacing === 'preserve') attrs += ' xml:space="preserve"';
+    // Flatten xmlStyleAttrs result into individual attrs
+    attrs['font-family'] = s.fontFamily;
+    attrs['font-size'] = fmt(s.fontSize);
+    attrs.fill = s.color;
+    attrs['font-weight'] = s.fontWeight;
+    if (s.fontStyle === 'italic') attrs['font-style'] = 'italic';
+    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}"`;
-  }
+  // text-anchor is intentionally NOT used in flat mode.
+  // PositioningEngine already accounts for alignment by shifting line.x.
+  // Adding text-anchor would double-shift the text.
 
   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}"`;
+function buildTspanAttrs(span: Span, x: number, currentStyle: StyleState | null): { attrs: Record<string, string | number>; newStyle: StyleState } {
+  const s = defaultStyleState(span);
+  const attrs: Record<string, string | number> = {
+    x: fmt(x),
+  };
 
   if (currentStyle && equalStyle(s, currentStyle)) {
     return { attrs, newStyle: s };
@@ -246,121 +404,428 @@ function buildTspanAttrs(frag: FragmentBox, x: number, currentStyle: StyleState
   // 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.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'] = fmt(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}"`;
+    if (s.decoration) attrs['text-decoration'] = s.decoration;
+  }
+  if (!currentStyle || s.letterSpacing !== currentStyle.letterSpacing) {
+    if (s.letterSpacing !== undefined && s.letterSpacing !== 0) attrs['letter-spacing'] = fmt(s.letterSpacing);
   }
 
   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) {
+/** Build per-glyph x positions for glyph mode.
+ *
+ * Accounts for letterSpacing by adding it to each glyph advance.
+ * The `letter-spacing` attribute should NOT be set on `<tspan>` when
+ * using glyph mode, because the spacing is already baked into the x positions.
+ */
+function buildGlyphPositions(span: Span, _lineX: number): string {
+  if (!span.glyphAdvances || span.glyphAdvances.length === 0) {
     return '';
   }
-  // frag.x is already absolute — computed by PositioningEngine.
+  // span.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));
+  const ls = span.style.letterSpacing || 0;
+  const spanX = span.x;
+  let xPos = spanX;
+  const positions: string[] = [fmt(xPos, 1)];
+  for (let i = 0; i < span.glyphAdvances.length - 1; i++) {
+    xPos += span.glyphAdvances[i] + ls;
+    positions.push(fmt(xPos, 1));
   }
   return positions.join(' ');
 }
 
 /** Build textLength attribute for a line */
-function buildFitAttr(line: LineBox, opts: ResolvedOptions): string {
+function buildFitAttr(line: Line, opts: ResolvedOptions): Record<string, string | number> | undefined {
   if (opts.fit === 'text') {
-    return ` textLength="${line.width}" lengthAdjust="spacing"`;
+    return { textLength: fmt(line.width), lengthAdjust: 'spacing' };
   }
-  return '';
+  return undefined;
 }
 
-/** Build textLength for a fragment */
-function buildFragFitAttr(frag: FragmentBox, opts: ResolvedOptions): string {
+/** Build textLength for a span */
+function buildSpanFitAttr(span: Span, opts: ResolvedOptions): Record<string, string | number> | undefined {
   if (opts.fit === 'frag') {
-    return ` textLength="${frag.width}"`;
+    return { textLength: fmt(span.width) };
+  }
+  return undefined;
+}
+
+// ── SVG AST helpers ──────────────────────────────────────────────────────
+
+/**
+ * Create an SVG element node.
+ */
+function el(tag: string, attrs: Record<string, string | number | undefined> = {}, children: SvgNode[] = []): SvgElement {
+  // Strip undefined values from attrs
+  const cleanAttrs: Record<string, string | number> = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v !== undefined) {
+      cleanAttrs[k] = v;
+    }
   }
-  return '';
+  return { type: 'element', tag, attrs: cleanAttrs, children };
+}
+
+/**
+ * Create an SVG text node (escaped on serialization).
+ */
+function textNode(value: string): SvgNode {
+  return { type: 'text', value };
 }
 
-// ── SVG builder ──────────────────────────────────────────────────────────
+/**
+ * Create an SVG raw node (output verbatim, no escaping).
+ */
+function rawNode(value: string): SvgNode {
+  return { type: 'raw', value };
+}
 
-class SvgBuilder {
-  private parts: string[] = [];
+// ── Serializer ───────────────────────────────────────────────────────────
+
+/**
+ * Serialize an SVG AST node to a string.
+ * Uses an indent level for pretty-printing.
+ */
+function serializeSvg(node: SvgNode, indent = 0): string {
+  const pad = '  '.repeat(indent);
+
+  switch (node.type) {
+    case 'text':
+      return escapeXml(node.value);
+
+    case 'raw':
+      return node.value;
+
+    case 'comment':
+      return `${pad}<!-- ${node.value} -->\n`;
+
+    case 'element': {
+      const tag = node.tag;
+      const attrsStr = Object.entries(node.attrs)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(' ');
+
+      if (node.children.length === 0) {
+        return `${pad}<${tag}${attrsStr ? ' ' + attrsStr : ''} />\n`;
+      }
+
+      // If all children are text nodes, render inline (same line as opening tag).
+      // This matches the old string-push behavior where <tspan>text</tspan>
+      // was emitted as a single string without extra newlines.
+      const allTextChildren = node.children.every(c => c.type === 'text');
+      if (allTextChildren) {
+        const text = node.children.map(c => (c as any).value).join('');
+        return `${pad}<${tag}${attrsStr ? ' ' + attrsStr : ''}>${escapeXml(text)}</${tag}>\n`;
+      }
+
+      const openTag = `${pad}<${tag}${attrsStr ? ' ' + attrsStr : ''}>\n`;
+      const childrenStr = node.children.map(c => serializeSvg(c, indent + 1)).join('');
+      const closeTag = `${pad}</${tag}>\n`;
+
+      return openTag + childrenStr + closeTag;
+    }
+  }
+}
+
+// ── SVG AST Builder ──────────────────────────────────────────────────────
+
+/**
+ * Builds an SVG AST tree. Unlike the old imperative SvgBuilder (which pushed
+ * strings and relied on manual open/close tracking), this builder maintains
+ * a tree of SvgElement nodes. The tree structure guarantees that:
+ *   - <tspan> nodes are always children of a <text> node
+ *   - No orphaned closing tags
+ *   - Correct nesting is enforced at the data level, not by call order
+ */
+class SvgAstBuilder {
+  /** The root <svg> element. */
+  readonly root: SvgElement;
+  /** Reference to the currently active <text> element (if any). */
+  private currentText: SvgElement | null = null;
   private opts: ResolvedOptions;
 
-  constructor(width: number, height: number, opts: ResolvedOptions) {
+  constructor(width: number, height: number, opts: ResolvedOptions, viewBox?: { x: number; y: number; w: number; h: number }) {
     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`);
+    const svgAttrs: Record<string, string | number | undefined> = {
+      xmlns: 'http://www.w3.org/2000/svg',
+      width: fmt(width),
+      height: fmt(height),
+      viewBox: viewBox
+        ? `${fmt(viewBox.x)} ${fmt(viewBox.y)} ${fmt(viewBox.w)} ${fmt(viewBox.h)}`
+        : `0 0 ${fmt(width)} ${fmt(height)}`,
+    };
     if (opts.className) {
-      this.parts[0] = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" class="${escapeXml(opts.className)}">\n`;
+      svgAttrs.class = opts.className;
     }
+    this.root = el('svg', svgAttrs);
   }
 
-  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`);
+  /**
+   * Open a new <text> element.
+   * Closes any previously open <text> automatically.
+   */
+  openText(line: Line, baseSpan: Span, runId?: string, yOverride?: number, fontSizeOverride?: number): void {
+    // Close any open text first
+    this.closeText();
+
+    let textAttrs: Record<string, string | number>;
+    if (yOverride !== undefined && fontSizeOverride !== undefined) {
+      // For sub/superscript — override y and font-size.
+      // text-decoration and letter-spacing intentionally excluded from <text>
+      // to prevent inheritance by child <tspan> elements (expanded mode).
+      const s = defaultStyleState(baseSpan);
+      const x = line.x;
+      const attrs: Record<string, string | number> = {
+        x: fmt(x),
+        y: fmt(yOverride),
+      };
+      if (this.opts.style === 'css') {
+        let css = `font-family: '${s.fontFamily}', sans-serif; font-size: ${fmt(fontSizeOverride)}px; fill: ${colorToRGB(s.color)}; font-weight: ${s.fontWeight}`;
+        if (s.fontStyle === 'italic') css += `; font-style: italic`;
+        if (this.opts.spacing === 'preserve') css += '; white-space: pre';
+        attrs.style = css;
+      } else {
+        attrs['font-family'] = s.fontFamily;
+        attrs['font-size'] = fmt(fontSizeOverride);
+        attrs.fill = s.color;
+        attrs['font-weight'] = s.fontWeight;
+        if (s.fontStyle === 'italic') attrs['font-style'] = 'italic';
+        if (this.opts.spacing === 'preserve') attrs['xml:space'] = 'preserve';
+      }
+      textAttrs = attrs;
+    } else {
+      textAttrs = buildTextAttrs(line, baseSpan, this.opts, runId);
+    }
+
+    const fitAttrs = buildFitAttr(line, this.opts);
+    if (fitAttrs) {
+      Object.assign(textAttrs, fitAttrs);
+    }
+
+    const textEl = el('text', textAttrs);
+    this.root.children.push(textEl);
+    this.currentText = textEl;
   }
 
-  addFlatFrag(text: string): void {
-    this.parts.push(`    ${escapeXml(text)}`);
+  /**
+   * Add raw SVG markup as a direct child of the root <svg>.
+   * Used for pre-rendered debug overlays.
+   */
+  addDebug(debugMarkup: string): void {
+    if (debugMarkup) {
+      this.root.children.push(rawNode(`<!-- debug overlay -->\n${debugMarkup}\n`));
+    }
+  }
+
+  /**
+   * Add text content (flat mode — no <tspan>).
+   * Text is escaped automatically on serialization.
+   */
+  addTextContent(text: string): void {
+    if (this.currentText) {
+      this.currentText.children.push(textNode(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`);
+  /**
+   * Add an expanded <tspan> node to the current <text> element.
+   */
+  addTspan(span: Span, x: number, style: StyleState | null): StyleState {
+    const { attrs, newStyle } = buildTspanAttrs(span, x, style);
+    const fitAttrs = buildSpanFitAttr(span, this.opts);
+    if (fitAttrs) {
+      Object.assign(attrs, fitAttrs);
+    }
+    const tspan = el('tspan', attrs, [textNode(span.text)]);
+    if (this.currentText) {
+      this.currentText.children.push(tspan);
+    }
     return newStyle;
   }
 
-  addGlyphFrag(frag: FragmentBox, lineX: number): void {
-    const positions = buildGlyphPositions(frag, lineX);
+  /**
+   * Add a glyph-positioned <tspan> node to the current <text> element.
+   */
+  addGlyphTspan(span: Span, lineX: number): void {
+    const positions = buildGlyphPositions(span, lineX);
+    const attrs: Record<string, string | number> = {};
     if (positions) {
-      this.parts.push(`    <tspan x="${positions}">${escapeXml(frag.text)}</tspan>\n`);
-    } else {
-      this.parts.push(`    <tspan>${escapeXml(frag.text)}</tspan>\n`);
+      attrs.x = positions;
+    }
+    const tspan = el('tspan', attrs, [textNode(span.text)]);
+    if (this.currentText) {
+      this.currentText.children.push(tspan);
     }
   }
 
-  closeText(): void {
-    this.parts.push('  </text>\n');
+  /**
+   * Add a background rect as a direct child of the root <svg>.
+   * Used for highlight marker (backgroundColor on spans).
+   * The rect is placed before any <text> elements so it renders underneath.
+   */
+  addBackgroundRect(x: number, y: number, width: number, height: number, color: string): void {
+    this.closeText();
+    const rect = el('rect', {
+      x: fmt(x),
+      y: fmt(y),
+      width: fmt(width),
+      height: fmt(height),
+      fill: color,
+    });
+    this.root.children.push(rect);
   }
 
-  addDebug(debugOverlay: string): void {
-    if (debugOverlay) {
-      this.parts.push(`<!-- debug overlay -->\n${debugOverlay}\n`);
-    }
+  /**
+   * Add a pre-rendered SVG line as a raw node directly under root.
+   * Used in flat mode when each span is its own <text>.
+   */
+  addRawLine(lineStr: string): void {
+    this.closeText();
+    this.root.children.push(rawNode(lineStr));
   }
 
-  build(): string {
-    this.parts.push('</svg>\n');
-    return this.parts.join('');
+  /**
+   * Close the currently open <text> element.
+   * Safe to call multiple times — no-op if no text is open.
+   */
+  closeText(): void {
+    this.currentText = null;
   }
 }
 
 // ── Debug overlay ────────────────────────────────────────────────────────
 
-function renderDebugToSVG(lines: LineBox[], width: number, height: number, flags: DebugFlags): string {
+function renderDebugToSVG(
+  lines: Line[],
+  flags: DebugFlags,
+  frameSize?: { width: number; height: number },
+  contentSize?: { width: number; height: number },
+  columns?: MultiColumnConfig,
+  leftPad?: number,
+  rightPad?: number,
+): string {
   const parts: string[] = [];
+  const sw = flags.widthBorder ?? 1;
 
-  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));
+  // Frame container bounding box
+  if ((flags.frameBox || flags.frame) && frameSize) {
     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" />`,
+      `  <rect x="0" y="0" width="${fmt(frameSize.width)}" height="${fmt(frameSize.height)}"` +
+      ` fill="none" stroke="rgba(0,140,255,0.8)" stroke-width="${fmt(sw)}" stroke-dasharray="4,3" />`,
     );
+    if (flags.labels) {
+      parts.push(
+        `  <text x="4" y="14" font-size="10" fill="rgba(0,140,255,0.9)" font-family="monospace">frame ${fmt(frameSize.width)}×${fmt(frameSize.height)}</text>`,
+      );
+    }
+  }
+
+  // Content bounding box
+  if (flags.contentBox) {
+    const bbox = computeBBox(lines);
+    parts.push(
+      `  <rect x="${fmt(bbox.x)}" y="${fmt(bbox.y)}" width="${fmt(bbox.width)}" height="${fmt(bbox.height)}"` +
+      ` fill="none" stroke="rgba(255,60,140,0.8)" stroke-width="${fmt(sw)}" stroke-dasharray="1,2" />`,
+    );
+    if (flags.labels) {
+      const labelY = bbox.y + bbox.height + 14;
+      parts.push(
+        `  <text x="${fmt(bbox.x)}" y="${fmt(labelY)}" font-size="10" fill="rgba(255,60,140,0.9)" font-family="monospace">content ${fmt(bbox.width)}×${fmt(bbox.height)}</text>`,
+      );
+    }
+  }
+
+  // Overflow warning when content exceeds frame
+  if (flags.contentBox && frameSize && contentSize && flags.labels) {
+    const overflowX = contentSize.width > frameSize.width;
+    const overflowY = contentSize.height > frameSize.height;
+    if (overflowX || overflowY) {
+      parts.push(
+        `  <text x="4" y="${fmt(frameSize.height + 14)}" font-size="10" fill="rgba(220,0,0,0.9)" font-family="monospace">⚠ content overflow: ${overflowX ? `Δx=${fmt(contentSize.width - frameSize.width)} ` : ''}${overflowY ? `Δy=${fmt(contentSize.height - frameSize.height)}` : ''}</text>`,
+      );
+    }
+  }
+
+  // ── Column separators ────────────────────────────────────────────
+  if (columns && columns.count > 1 && (flags.paragraphBox || flags.columnBox)) {
+    const colCount = columns.count;
+    const colGap = columns.gap;
+    const lp = leftPad ?? 0;
+    // Calculate colWidth from frame or content
+    const totalHorizontalSpace = frameSize?.width ?? (lines.length > 0 ? Math.max(...lines.map(l => l.x + l.width)) : 0);
+    const usableWidth = totalHorizontalSpace - lp - (rightPad ?? 0);
+    const colWidth = (usableWidth - (colCount - 1) * colGap) / colCount;
+    for (let c = 1; c < colCount; c++) {
+      const sepX = lp + c * (colWidth + colGap) - colGap / 2;
+      parts.push(
+        `  <line x1="${fmt(sepX)}" y1="0" x2="${fmt(sepX)}" y2="${fmt(frameSize?.height ?? 9999)}"` +
+        ` stroke="rgba(100,100,100,0.15)" stroke-width="1" stroke-dasharray="2,2" />`,
+      );
+    }
+  }
+
+  // Paragraph bounding boxes — per-column
+  if (flags.paragraphBox) {
+    const paraGroups = groupLinesByParagraph(lines);
+    const paraColors = [
+      'rgba(0,180,80,0.25)',
+      'rgba(180,0,80,0.25)',
+      'rgba(80,0,180,0.25)',
+      'rgba(180,180,0,0.25)',
+    ];
+
+    for (let i = 0; i < paraGroups.length; i++) {
+      const group = paraGroups[i];
+      if (group.lines.length === 0) continue;
+
+      // Group lines within this paragraph by columnIndex
+      const colMap = new Map<number, { top: number; bottom: number }>();
+      for (const line of group.lines) {
+        const ci = line.columnIndex ?? 0;
+        const existing = colMap.get(ci);
+        const lineTop = line.y;
+        const lineBottom = line.y + line.height;
+        if (existing) {
+          existing.top = Math.min(existing.top, lineTop);
+          existing.bottom = Math.max(existing.bottom, lineBottom);
+        } else {
+          colMap.set(ci, { top: lineTop, bottom: lineBottom });
+        }
+      }
+
+      // For non-column layout, colX = 0, colW = containerRight
+      // For column layout, calculate per-column position
+      const lp = leftPad ?? 0;
+      const rp = rightPad ?? 0;
+      const totalW = frameSize?.width ?? (lines.length > 0 ? Math.max(...lines.map(l => l.x + l.width)) : 0);
+      const usableW = totalW - lp - rp;
+      const colCount = columns?.count ?? 1;
+      const colGap = columns?.gap ?? 0;
+      const colW = (usableW - (colCount - 1) * colGap) / colCount;
+
+      const color = paraColors[i % paraColors.length];
+      for (const [ci, rect] of colMap) {
+        const colX = lp + ci * (colW + colGap);
+        parts.push(`  <rect x="${fmt(colX)}" y="${fmt(rect.top)}" width="${fmt(colW)}" height="${fmt(rect.bottom - rect.top)}" fill="none" stroke="${color}" stroke-width="${fmt(sw)}" />`);
+      }
+
+      const label = group.tag ? `#${group.pIdx} ${group.tag}` : `#${group.pIdx}`;
+      if (flags.labels) {
+        // Place label at top-left of the first column for this paragraph
+        const firstColIdx = Math.min(...Array.from(colMap.keys()));
+        const firstColX = lp + firstColIdx * (colW + colGap);
+        const firstTop = colMap.get(firstColIdx)!.top;
+        parts.push(`  <text x="${fmt(firstColX + 4)}" y="${fmt(firstTop - 2)}" font-size="9" fill="rgba(0,0,0,0.6)" font-family="monospace">¶ ${label}</text>`);
+      }
+    }
   }
 
   for (const line of lines) {
@@ -368,27 +833,27 @@ function renderDebugToSVG(lines: LineBox[], width: number, height: number, flags
     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" />`);
+      parts.push(`  <rect x="${fmt(bx)}" y="${fmt(by)}" width="${fmt(bw)}" height="${fmt(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" />`);
+      parts.push(`  <rect x="${fmt(bx)}" y="${fmt(by)}" width="${fmt(bw)}" height="${fmt(bh)}" fill="none" stroke="rgba(255,100,100,0.5)" stroke-width="${fmt(sw)}" />`);
     }
     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" />`);
+      parts.push(`  <line x1="${fmt(bx)}" y1="${fmt(baselineY)}" x2="${fmt(bx + bw)}" y2="${fmt(baselineY)}" stroke="rgba(100,100,255,0.5)" stroke-width="${fmt(sw)}" />`);
     }
     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" />`);
+      parts.push(`  <line x1="${fmt(bx)}" y1="${fmt(baselineY - line.ascent)}" x2="${fmt(bx + bw)}" y2="${fmt(baselineY - line.ascent)}" stroke="rgba(100,255,100,0.4)" stroke-width="${fmt(sw)}" stroke-dasharray="3,2" />`);
+      parts.push(`  <line x1="${fmt(bx)}" y1="${fmt(baselineY + line.descent)}" x2="${fmt(bx + bw)}" y2="${fmt(baselineY + line.descent)}" stroke="rgba(100,255,100,0.4)" stroke-width="${fmt(sw)}" 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>`);
+      parts.push(`  <text x="${fmt(bx)}" y="${fmt(by - 2)}" font-size="9" fill="rgba(0,0,0,0.55)" font-family="monospace">y=${fmt(by)} x=${fmt(bx)} w=${fmt(bw)} h=${fmt(bh)} bl=${fmt(baselineY)}</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" />`);
+      for (const span of line.spans) {
+        if (span.width <= 0) continue;
+        const rx = line.x + span.x;
+        const ry = baselineY - span.fontMetrics.ascent;
+        parts.push(`  <rect x="${fmt(rx)}" y="${fmt(ry)}" width="${fmt(span.width)}" height="${fmt(span.fontMetrics.ascent + span.fontMetrics.descent)}" fill="none" stroke="rgba(200,100,255,0.4)" stroke-width="${fmt(sw)}" />`);
       }
     }
   }
@@ -396,106 +861,215 @@ function renderDebugToSVG(lines: LineBox[], width: number, height: number, flags
   return parts.join('\n');
 }
 
+// ── Background rect helper ───────────────────────────────────────────────
+
+/**
+ * Compute background rect coordinates for a span.
+ * Returns null if the span has no backgroundColor.
+ */
+function getSpanBackgroundAttrs(span: Span, baselineY: number): { x: number; y: number; w: number; h: number; fill: string } | null {
+  if (!span.style.backgroundColor) return null;
+  const x = span.x;
+  const y = baselineY - span.fontMetrics.ascent;
+  const w = span.width;
+  const h = span.fontMetrics.ascent + span.fontMetrics.descent;
+  return { x, y, w, h, fill: span.style.backgroundColor };
+}
+
 // ── Main render logic ────────────────────────────────────────────────────
 
 /**
- * Render LineBox[] into SVG string.
+ * Render Line[] into SVG string.
  *
- * @param lines — layout lines with fragments
+ * @param lines — layout lines with spans
  * @param options — rendering options (preset + style/fit/sizing modifiers)
  * @returns SVG string
  */
-export function renderToSVG(lines: LineBox[], options: SVGRenderOptions = {}): string {
+export function renderToSVG(lines: Line[], 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;
-  }
+  // Determine canvas size and viewBox
+  const { width: svgWidth, height: svgHeight, viewBox, frameWidth, frameHeight } = resolveSize(lines, opts);
 
-  const builder = new SvgBuilder(svgWidth, svgHeight, opts);
+  const builder = new SvgAstBuilder(svgWidth, svgHeight, opts, viewBox);
 
   for (const line of lines) {
+    const baselineY = line.y + line.baseline;
+
+    // First pass: render background rects for all highlighted spans
+    for (const span of line.spans) {
+      if (!span.text || !span.style.backgroundColor) continue;
+      const bg = getSpanBackgroundAttrs(span, baselineY);
+      if (bg) {
+        const rx = line.x + bg.x;
+        builder.addBackgroundRect(rx, bg.y, bg.w, bg.h, bg.fill);
+      }
+    }
+
     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;
+      for (const span of line.spans) {
+        if (!span.text) continue;
+        const runIdx = span.itemIndex;
         if (runIdx !== currentRunIdx) {
-          if (currentRunIdx !== -1) {
-            builder.closeText();
-          }
-          const runId = frag.paragraphId ? `${frag.paragraphId}-${runIdx}` : undefined;
-          builder.addText(line, frag, runId);
+          builder.closeText();
+          const runId = span.tag ? `${span.tag}-${runIdx}` : undefined;
+          builder.openText(line, span, runId);
           currentRunIdx = runIdx;
         }
-        builder.addGlyphFrag(frag, line.x);
+        builder.addGlyphTspan(span, line.x);
       }
-      if (currentRunIdx !== -1) {
-        builder.closeText();
+      builder.closeText();
+    } else if (opts.structure === 'flat') {
+      // flat mode: each unique style → separate <text> element.
+      // Group spans by (targetY + styleSignature) so bold/normal/italic
+      // each get their own <text>. Never merge spans with different styles.
+      interface FlatGroup { spans: Span[]; targetY: number; signature: string; fontSize: number }
+      const groups: FlatGroup[] = [];
+      for (const span of line.spans) {
+        if (!span.text) continue;
+        const offset = span.fontMetrics.baselineOffset || 0;
+        const targetY = Math.round((line.y + line.baseline + offset) * 100) / 100;
+        const sig = styleSignature(span);
+        const fontSize = span.fontMetrics.fontSize;
+        const last = groups[groups.length - 1];
+        if (last && last.targetY === targetY && last.signature === sig) {
+          last.spans.push(span);
+        } else {
+          groups.push({ spans: [span], targetY, signature: sig, fontSize });
+        }
+      }
+      // Find the first text span's x to use as baseline offset
+      // Use first text or marker span's x for baseline offset
+      const firstTextX = line.spans.find(s => s.type === 'text' || s.type === 'marker')?.x ?? 0;
+      const fitAttr = buildFitAttr(line, opts);
+      for (const group of groups) {
+        const s = defaultStyleState(group.spans[0]);
+        const text = group.spans.map(sp => escapeXml(sp.text)).join('');
+        // line.x includes padding.left. span.x includes alignment offset but NOT padding.
+        // For single-span groups: span.x = firstTextX → x = line.x (correct for padding & alignment).
+        // For sub/super script: span.x differs from firstTextX → x = line.x + span.x - firstTextX.
+        const groupX = line.x + (group.spans[0].x - firstTextX);
+        const textAttrs: Record<string, string | number> = {
+          x: fmt(groupX),
+          y: fmt(group.targetY),
+          'font-family': s.fontFamily,
+          'font-size': fmt(group.fontSize),
+          fill: s.color,
+          'font-weight': s.fontWeight,
+        };
+        if (s.fontStyle === 'italic') textAttrs['font-style'] = 'italic';
+        if (s.decoration) textAttrs['text-decoration'] = s.decoration;
+        if (s.letterSpacing !== undefined && s.letterSpacing !== 0) textAttrs['letter-spacing'] = fmt(s.letterSpacing);
+        textAttrs['xml:space'] = 'preserve';
+        if (fitAttr) {
+          Object.assign(textAttrs, fitAttr);
+        }
+        // For flat mode, use addRawLine to skip text tracking
+        const attrsStr = Object.entries(textAttrs)
+          .map(([k, v]) => `${k}="${v}"`)
+          .join(' ');
+        builder.addRawLine(`  <text ${attrsStr}>${text}</text>\n`);
       }
     } 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;
+      // expanded: group spans by (targetY + styleSignature) so each
+      // unique style combination gets its own <text> element.
+      // Inside each group, <tspan> is used per span with diff attributes.
+      type TspanGroup = { targetY: number; spans: Span[]; signature: string };
+      const groups: TspanGroup[] = [];
+      for (const span of line.spans) {
+        if (!span.text) continue;
+        const offset = span.fontMetrics.baselineOffset || 0;
+        const targetY = Math.round((line.y + line.baseline + offset) * 100) / 100;
+        const sig = styleSignature(span);
+        const last = groups[groups.length - 1];
+        if (last && last.targetY === targetY && last.signature === sig) {
+          last.spans.push(span);
+        } else {
+          groups.push({ targetY, spans: [span], signature: sig });
+        }
+      }
 
-      builder.addText(line, baseFrag);
+      for (const group of groups) {
+        const baseSpan = group.spans.find(f => f.type === 'text' && f.text.length > 0) || group.spans[0];
+        if (!baseSpan) continue;
+
+        // Only use yOverride when the group targetY differs from the line baseline
+        const lineBaseY = Math.round((line.y + line.baseline) * 100) / 100;
+        const needsOffset = group.targetY !== lineBaseY;
+        if (needsOffset) {
+          // For offset groups (sub/superscript), override y and font-size from first span.
+          // text-decoration and letter-spacing intentionally excluded from <text>
+          // to prevent inheritance by child <tspan> elements.
+          const s = defaultStyleState(baseSpan);
+          const firstTextX = line.spans.find(s => s.type === 'text')?.x ?? 0;
+          const groupX = line.x + (group.spans[0].x - firstTextX);
+          const fontSize = baseSpan.fontMetrics.fontSize;
+          const textAttrs: Record<string, string | number> = {
+            x: fmt(groupX),
+            y: fmt(group.targetY),
+            'font-family': s.fontFamily,
+            'font-size': fmt(fontSize),
+            fill: s.color,
+            'font-weight': s.fontWeight,
+          };
+          if (s.fontStyle === 'italic') textAttrs['font-style'] = 'italic';
+          textAttrs['xml:space'] = 'preserve';
+          const fit = buildFitAttr(line, opts);
+          if (fit) {
+            Object.assign(textAttrs, fit);
+          }
+          builder.openText(line, baseSpan, undefined, group.targetY, fontSize);
+        } else {
+          builder.openText(line, baseSpan);
+        }
 
-      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;
+        for (const span of group.spans) {
+          if (!span.text) continue;
+          const x = span.x;
 
-          const shouldRender = frag.type !== 'space' || opts.spacing === 'preserve';
+          const shouldRender = span.type !== 'space' || opts.spacing === 'preserve';
           if (shouldRender) {
-            const newStyle = builder.addExpandedFrag(frag, x, currentStyle);
-            if (frag.type !== 'space') {
+            const newStyle = builder.addTspan(span, x, currentStyle);
+            if (span.type !== 'space') {
               currentStyle = newStyle;
             }
           }
         }
+        builder.closeText();
       }
-
-      builder.closeText();
     }
   }
 
   if (opts.debug) {
-    const debugSvg = renderDebugToSVG(lines, svgWidth, svgHeight, opts.debug);
+    // frameSize: only when both axes are explicitly set as 'frame'
+    const frameSize = frameWidth !== undefined && frameHeight !== undefined
+      ? { width: frameWidth, height: frameHeight }
+      : undefined;
+    const contentBbox = computeBBox(lines);
+    const contentSize = { width: contentBbox.width, height: contentBbox.height };
+    const debugSvg = renderDebugToSVG(
+      lines,
+      opts.debug,
+      frameSize,
+      contentSize,
+      options.columns,
+      options.paddingLeft,
+      0, // rightPad — not tracked in options yet
+    );
     builder.addDebug(debugSvg);
   }
 
-  return builder.build();
+  return serializeSvg(builder.root);
 }
 
 /**
  * Render one ParagraphLayoutResult to SVG (convenience wrapper).
  */
 export function renderParagraphToSVG(
-  lines: LineBox[],
+  lines: Line[],
   paragraphWidth: number,
   paragraphHeight: number,
   options?: SVGRenderOptions,