agentic-mermaid 0.1.1 → 0.2.0

package/src/scene/backend.ts

@@ -1,76 +0,0 @@
-// ============================================================================
-// StyleBackend interface + DefaultBackend + backend registry (SPEC §3.2).
-//
-// A backend consumes a SceneDoc and produces the SVG document string. The
-// DefaultBackend is the Agentic Mermaid crisp renderer: it emits each mark's
-// construction-time crisp serialization verbatim, so its output is
-// byte-identical to the pre-IR string renderers (svg-equivalence.test.ts is
-// the corpus-wide gate). Styled backends (rough/hybrid) redraw shape and
-// connector marks from their semantic fields and re-derive the document shell
-// from PreludeMark parameters; they never dispatch on diagram family.
-// ============================================================================
-
-import type { SceneDoc, SceneNode } from './ir.ts'
-import { indentLines } from './marks.ts'
-import type { StyleSpec } from './style-registry.ts'
-
-export interface StyleBackendContext {
-  /** User-supplied deterministic re-roll seed (RenderOptions.seed). */
-  seed: number
-  /** The selected style (undefined on the crisp default path). */
-  style?: StyleSpec
-}
-
-export interface StyleBackend {
-  id: string
-  /** Serialize one top-level mark (recursing through groups). */
-  drawNode(node: SceneNode, ctx: StyleBackendContext): string
-  /** Serialize the whole document. */
-  render(doc: SceneDoc, ctx: StyleBackendContext): string
-}
-
-/** Recompose a group from (possibly restyled) child serializations using the
- *  group's own indent/join rules. Shared by all backends so wrapper semantics
- *  (classes, data-*, ARIA) stay identical across styles. */
-export function composeGroup(
-  open: string,
-  close: string,
-  join: string,
-  children: Array<{ serialized: string; indent: number }>,
-): string {
-  return [open, ...children.map(c => indentLines(c.serialized, c.indent)), close].join(join)
-}
-
-/** Styled documents carry an explicit page rect after the prelude — resvg
- *  does not paint the root style="background:…" CSS (SPEC §10). Emitted by
- *  every backend when a style is active and the document isn't transparent;
- *  the crisp path (no style) is byte-identical to previous releases. */
-export function pageRectFor(doc: SceneDoc, ctx: StyleBackendContext): string {
-  const prelude = doc.parts[0]
-  if (!ctx.style || prelude?.kind !== 'prelude' || prelude.prelude.transparent) return ''
-  return `<rect width="${doc.width}" height="${doc.height}" fill="var(--bg)" data-backdrop="page" />`
-}
-
-export const DefaultBackend: StyleBackend = {
-  id: 'default',
-  drawNode(node: SceneNode): string {
-    return node.crisp
-  },
-  render(doc: SceneDoc, ctx: StyleBackendContext): string {
-    const pageRect = pageRectFor(doc, ctx)
-    if (!pageRect) return doc.parts.map(part => part.crisp).join('\n')
-    return doc.parts
-      .map((part, i) => (i === 0 ? `${part.crisp}\n${pageRect}` : part.crisp))
-      .join('\n')
-  },
-}
-
-const BACKENDS = new Map<string, StyleBackend>([[DefaultBackend.id, DefaultBackend]])
-
-export function registerBackend(backend: StyleBackend): void {
-  BACKENDS.set(backend.id, backend)
-}
-
-export function getBackend(id: string): StyleBackend | undefined {
-  return BACKENDS.get(id)
-}

package/src/scene/fidelity.ts

@@ -1,183 +0,0 @@
-// ============================================================================
-// Scene fidelity checker — asserts a mark's semantic fields agree with its
-// crisp serialization, so styled backends can trust the geometry they redraw.
-//
-// Test-only oracle (driven by scene-fidelity.test.ts across the corpus): it
-// parses the crisp strings we ourselves emit — a stable, owned format — and
-// returns human-readable problems instead of throwing, so one run reports
-// every divergence in a lowering.
-// ============================================================================
-
-import type { Geometry, SceneDoc, SceneNode } from './ir.ts'
-
-/** Parse the top-level SVG elements out of a crisp chunk (self-closed or
- *  paired), ignoring nested content. Good enough for our own emitters. */
-export function topLevelElements(crisp: string): Array<{ tag: string; attrs: Map<string, string> }> {
-  const out: Array<{ tag: string; attrs: Map<string, string> }> = []
-  const re = /<([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[a-zA-Z_:][\w:.-]*="[^"]*")*)\s*\/?>/g
-  let depth = 0
-  let m: RegExpExecArray | null
-  const closeRe = /<\/([a-zA-Z][a-zA-Z0-9-]*)>/g
-  // Walk open/self-close/close tags in order, tracking depth.
-  const tokens: Array<{ index: number; kind: 'open' | 'self' | 'close'; tag: string; attrs?: Map<string, string> }> = []
-  while ((m = re.exec(crisp)) !== null) {
-    const attrs = new Map<string, string>()
-    for (const am of m[2]!.matchAll(/([a-zA-Z_:][\w:.-]*)="([^"]*)"/g)) attrs.set(am[1]!, am[2]!)
-    tokens.push({ index: m.index, kind: m[0]!.endsWith('/>') ? 'self' : 'open', tag: m[1]!, attrs })
-  }
-  while ((m = closeRe.exec(crisp)) !== null) tokens.push({ index: m.index, kind: 'close', tag: m[1]! })
-  tokens.sort((a, b) => a.index - b.index)
-  for (const t of tokens) {
-    if (t.kind === 'self') {
-      if (depth === 0) out.push({ tag: t.tag, attrs: t.attrs! })
-    } else if (t.kind === 'open') {
-      if (depth === 0) out.push({ tag: t.tag, attrs: t.attrs! })
-      depth++
-    } else {
-      depth--
-    }
-  }
-  return out
-}
-
-function num(s: string | undefined): number | undefined {
-  if (s === undefined) return undefined
-  const n = Number(s)
-  return Number.isFinite(n) ? n : undefined
-}
-
-function geometryProblems(geom: Geometry, els: Array<{ tag: string; attrs: Map<string, string> }>, path: string, problems: string[]): number {
-  // Returns how many elements this geometry consumed.
-  const el = els[0]
-  const want = (tag: string) => {
-    if (!el) { problems.push(`${path}: expected <${tag}>, crisp has no element`); return undefined }
-    if (el.tag !== tag) { problems.push(`${path}: expected <${tag}>, crisp has <${el.tag}>`); return undefined }
-    return el
-  }
-  const eq = (field: string, semantic: number | string | undefined, attr: string | undefined) => {
-    if (semantic === undefined) return
-    if (String(semantic) !== attr && num(attr) !== semantic) {
-      problems.push(`${path}.${field}: semantic ${semantic} != crisp ${attr}`)
-    }
-  }
-  switch (geom.kind) {
-    case 'rect': {
-      const e = want('rect'); if (!e) return 1
-      eq('x', geom.x, e.attrs.get('x')); eq('y', geom.y, e.attrs.get('y'))
-      eq('width', geom.width, e.attrs.get('width')); eq('height', geom.height, e.attrs.get('height'))
-      if (geom.rx !== undefined) eq('rx', geom.rx, e.attrs.get('rx'))
-      return 1
-    }
-    case 'circle': {
-      const e = want('circle'); if (!e) return 1
-      eq('cx', geom.cx, e.attrs.get('cx')); eq('cy', geom.cy, e.attrs.get('cy')); eq('r', geom.r, e.attrs.get('r'))
-      return 1
-    }
-    case 'ellipse': {
-      const e = want('ellipse'); if (!e) return 1
-      eq('cx', geom.cx, e.attrs.get('cx')); eq('cy', geom.cy, e.attrs.get('cy'))
-      eq('rx', geom.rx, e.attrs.get('rx')); eq('ry', geom.ry, e.attrs.get('ry'))
-      return 1
-    }
-    case 'line': {
-      const e = want('line'); if (!e) return 1
-      eq('x1', geom.x1, e.attrs.get('x1')); eq('y1', geom.y1, e.attrs.get('y1'))
-      eq('x2', geom.x2, e.attrs.get('x2')); eq('y2', geom.y2, e.attrs.get('y2'))
-      return 1
-    }
-    case 'polygon':
-    case 'polyline': {
-      const e = want(geom.kind); if (!e) return 1
-      const expected = geom.points.map(p => `${p.x},${p.y}`).join(' ')
-      if (e.attrs.get('points') !== expected) {
-        problems.push(`${path}.points: semantic "${expected.slice(0, 60)}" != crisp "${(e.attrs.get('points') ?? '').slice(0, 60)}"`)
-      }
-      return 1
-    }
-    case 'path': {
-      const e = want('path'); if (!e) return 1
-      if (e.attrs.get('d') !== geom.d) {
-        problems.push(`${path}.d: semantic "${geom.d.slice(0, 60)}" != crisp "${(e.attrs.get('d') ?? '').slice(0, 60)}"`)
-      }
-      return 1
-    }
-    case 'compound': {
-      let consumed = 0
-      for (let i = 0; i < geom.children.length; i++) {
-        consumed += geometryProblems(geom.children[i]!, els.slice(consumed), `${path}.children[${i}]`, problems)
-      }
-      return consumed
-    }
-  }
-}
-
-function unescapeXml(s: string): string {
-  return s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&')
-}
-
-export function nodeProblems(node: SceneNode, path: string, problems: string[]): void {
-  switch (node.kind) {
-    case 'shape': {
-      const els = topLevelElements(node.crisp)
-      geometryProblems(node.geometry, els, `${path}(shape:${node.id})`, problems)
-      return
-    }
-    case 'connector': {
-      if (node.crisp === '') {
-        if (node.lineStyle !== 'invisible') problems.push(`${path}(connector:${node.id}): empty crisp but lineStyle=${node.lineStyle}`)
-        return
-      }
-      const els = topLevelElements(node.crisp)
-      geometryProblems(node.geometry as Geometry, els, `${path}(connector:${node.id})`, problems)
-      const el = els[0]
-      if (el && node.endMarker && !(el.attrs.get('marker-end') ?? '').includes(`#${node.endMarker.id}`)) {
-        problems.push(`${path}(connector:${node.id}): endMarker ${node.endMarker.id} not in crisp marker-end`)
-      }
-      if (el && node.startMarker && !(el.attrs.get('marker-start') ?? '').includes(`#${node.startMarker.id}`)) {
-        problems.push(`${path}(connector:${node.id}): startMarker ${node.startMarker.id} not in crisp marker-start`)
-      }
-      return
-    }
-    case 'text': {
-      if (node.crisp === '') { problems.push(`${path}(text:${node.id}): empty crisp`); return }
-      const els = topLevelElements(node.crisp)
-      const el = els.find(e => e.tag === 'text')
-      if (!el) { problems.push(`${path}(text:${node.id}): crisp has no <text>`); return }
-      const fs = el.attrs.get('font-size')
-      if (fs !== undefined && num(fs) !== node.fontSize) {
-        problems.push(`${path}(text:${node.id}).fontSize: semantic ${node.fontSize} != crisp ${fs}`)
-      }
-      // The semantic text must appear in the crisp chunk. Both sides are
-      // normalized the way the text emitter normalizes labels (markdown
-      // backticks, <b>/<i>/<u>/<s> emphasis tags, whitespace), so formatted
-      // labels don't false-positive.
-      const normalize = (s: string) => unescapeXml(s)
-        .replace(/<br\s*\/?>/gi, ' ')
-        .replace(/<[^>]+>/g, '')
-        .replace(/[`*_]/g, '')
-        .replace(/\s+/g, ' ')
-        .trim()
-      const wantText = normalize(node.text)
-      if (wantText && !normalize(node.crisp).includes(wantText.split(' ')[0]!)) {
-        problems.push(`${path}(text:${node.id}): text "${wantText.slice(0, 40)}" not found in crisp`)
-      }
-      return
-    }
-    case 'group': {
-      if (!node.crisp.startsWith(node.open)) problems.push(`${path}(group:${node.id}): crisp does not start with open tag`)
-      if (!node.crisp.endsWith(node.close)) problems.push(`${path}(group:${node.id}): crisp does not end with close tag`)
-      node.children.forEach((child, i) => nodeProblems(child.node, `${path}/${i}`, problems))
-      return
-    }
-    case 'raw':
-    case 'prelude':
-      return
-  }
-}
-
-/** Validate a whole SceneDoc. Returns [] when every mark is faithful. */
-export function sceneFidelityProblems(doc: SceneDoc): string[] {
-  const problems: string[] = []
-  doc.parts.forEach((part, i) => nodeProblems(part, `parts[${i}]`, problems))
-  return problems
-}

package/src/scene/hybrid-backend.ts

@@ -1,174 +0,0 @@
-// ============================================================================
-// HybridBackend (SPEC §3.2/§11 phase 4) — rough.js composition plus the
-// native marks rough.js does not provide: pressure-sensitive perfect-freehand
-// ribbons (variable-width filled outlines from a jittered centerline) and
-// watercolor washes (translucent glaze + edge darkening, Curtis '97 in cheap
-// form). Everything else — role policy, halos, marker carriers, defs — is the
-// shared sketch walker from rough-backend.ts; geometries the native marks
-// can't express (arbitrary paths) fall back to rough.js.
-//
-// Deterministic per the §8 substream contract: the centerline sampler and
-// wash jitter draw only from nodeSeed-derived mulberry32 streams.
-// ============================================================================
-
-import { getStroke } from 'perfect-freehand'
-import type { Geometry } from './ir.ts'
-import { registerBackend } from './backend.ts'
-import { createSketchBackend, sketchGeometryRough } from './rough-backend.ts'
-import type { GeometrySketcher } from './rough-backend.ts'
-import { makeRng } from './seed.ts'
-
-const r3 = (n: number) => Math.round(n * 1000) / 1000
-const lerp = (a: number, b: number, t: number) => a + (b - a) * t
-const clamp01 = (t: number) => Math.max(0, Math.min(1, t))
-
-type Pt = { x: number; y: number }
-
-/** Convert closed geometries to a polygon for freehand/wash rendering.
- *  Returns null when the geometry can't be polygonized cheaply (paths). */
-function polygonize(geom: Geometry): Pt[] | null {
-  switch (geom.kind) {
-    case 'rect':
-      return [
-        { x: geom.x, y: geom.y },
-        { x: geom.x + geom.width, y: geom.y },
-        { x: geom.x + geom.width, y: geom.y + geom.height },
-        { x: geom.x, y: geom.y + geom.height },
-      ]
-    case 'polygon':
-      return geom.points
-    case 'circle': {
-      const out: Pt[] = []
-      for (let i = 0; i < 24; i++) {
-        const a = (i / 24) * Math.PI * 2
-        out.push({ x: geom.cx + Math.cos(a) * geom.r, y: geom.cy + Math.sin(a) * geom.r })
-      }
-      return out
-    }
-    case 'ellipse': {
-      const out: Pt[] = []
-      for (let i = 0; i < 28; i++) {
-        const a = (i / 28) * Math.PI * 2
-        out.push({ x: geom.cx + Math.cos(a) * geom.rx, y: geom.cy + Math.sin(a) * geom.ry })
-      }
-      return out
-    }
-    default:
-      return null
-  }
-}
-
-function strokePathFromOutline(outline: number[][]): string {
-  if (outline.length < 2) return ''
-  const d = [`M${r3(outline[0]![0]!)},${r3(outline[0]![1]!)}`]
-  for (let i = 1; i < outline.length; i++) {
-    const [x0, y0] = outline[i]!
-    const [x1, y1] = outline[(i + 1) % outline.length]!
-    d.push(`Q${r3(x0!)},${r3(y0!)} ${r3((x0! + x1!) / 2)},${r3((y0! + y1!) / 2)}`)
-  }
-  d.push('Z')
-  return d.join(' ')
-}
-
-/** Resample a polyline/polygon into a jittered, pressure-annotated centerline
- *  (ported from the prototype's engine.ts, behavior unchanged). */
-function sampledCenterline(pts: Pt[], rng: () => number, closed: boolean, wobble: number): [number, number, number][] {
-  const src = closed ? [...pts, pts[0]!] : pts
-  const out: [number, number, number][] = []
-  for (let i = 0; i < src.length - 1; i++) {
-    const a = src[i]!, b = src[i + 1]!
-    const len = Math.hypot(b.x - a.x, b.y - a.y) || 1
-    const steps = Math.max(1, Math.ceil(len / 14))
-    const nx = -(b.y - a.y) / len, ny = (b.x - a.x) / len
-    for (let j = 0; j < steps; j++) {
-      if (i > 0 && j === 0) continue
-      const t = j / steps
-      const atEnd = !closed && ((i === 0 && j === 0) || (i === src.length - 2 && j === steps))
-      const jitter = atEnd ? 0 : (rng() - 0.5) * 2 * wobble
-      const p = { x: lerp(a.x, b.x, t) + nx * jitter, y: lerp(a.y, b.y, t) + ny * jitter }
-      const phase = (i + t) / Math.max(1, src.length - 1)
-      const pressure = clamp01(0.52 + Math.sin(phase * Math.PI * 2) * 0.12 + (rng() - 0.5) * 0.16)
-      out.push([p.x, p.y, pressure])
-    }
-  }
-  const last = src[src.length - 1]!
-  out.push([last.x, last.y, closed ? out[0]?.[2] ?? 0.55 : 0.46])
-  return out
-}
-
-function freehandStroke(pts: Pt[], rng: () => number, o: { width: number; closed: boolean }): string {
-  if (pts.length < 2) return ''
-  const input = sampledCenterline(pts, rng, o.closed, 1)
-  const outline = getStroke(input, {
-    size: o.width,
-    thinning: 0.58,
-    smoothing: 0.62,
-    streamline: 0.35,
-    simulatePressure: false,
-    start: { cap: true, taper: o.closed ? 0 : 10 },
-    end: { cap: true, taper: o.closed ? 0 : 14 },
-    last: true,
-  }) as number[][]
-  return strokePathFromOutline(outline)
-}
-
-/** Watercolor wash: wobbled translucent fill + edge-darkening stroke. */
-function watercolorWash(poly: Pt[], rng: () => number, fill: string, opacity: number, edge: number): string {
-  const wob = poly.map(p => ({ x: p.x + (rng() - 0.5) * 3, y: p.y + (rng() - 0.5) * 3 }))
-  const d = wob.map((p, i) => `${i ? 'L' : 'M'}${r3(p.x)},${r3(p.y)}`).join(' ') + ' Z'
-  return (
-    `<path d="${d}" fill="${fill}" fill-opacity="${opacity}" stroke="none" />` +
-    `\n<path d="${d}" fill="none" stroke="${fill}" stroke-width="1.4" stroke-opacity="${edge}" />`
-  )
-}
-
-/** The hybrid sketcher: freehand ribbons when the style asks for them, wash
- *  fills under the outline; null falls back to rough.js in the walker. */
-const hybridSketcher: GeometrySketcher = (geom, opts) => {
-  const strokeKind = opts.style?.stroke ?? 'jittered'
-  const fillKind = opts.style?.fill ?? 'none'
-  const wantsWash = fillKind === 'wash' && opts.fill !== undefined
-  const wantsFreehand = strokeKind === 'freehand'
-  if (!wantsWash && !wantsFreehand) return null
-
-  const parts: string[] = []
-  if (wantsWash) {
-    const rng = makeRng((opts.seed ^ 0x9e3779b9) >>> 0)
-    const poly = geom.kind === 'path' ? null : polygonize(geom)
-    if (poly) {
-      parts.push(watercolorWash(poly, rng, opts.fill!, opts.style?.washOpacity ?? 0.3, opts.style?.washEdge ?? 0.34))
-    } else if (geom.kind === 'path') {
-      // Arbitrary paths (pie wedges): translucent glaze on the exact path.
-      parts.push(`<path d="${geom.d}" fill="${opts.fill}" fill-opacity="${opts.style?.washOpacity ?? 0.3}" stroke="${opts.fill}" stroke-width="1.4" stroke-opacity="${opts.style?.washEdge ?? 0.34}" />`)
-    }
-  }
-
-  // Dashed/dotted connectors keep their dash semantics: a filled ribbon
-  // cannot carry stroke-dasharray, so they fall through to the rough stroke.
-  if (wantsFreehand && !opts.dash) {
-    const rng = makeRng(opts.seed || 1)
-    const width = Math.max(2.5, opts.width * 2.2)
-    let ribbon = ''
-    if (geom.kind === 'polyline') {
-      ribbon = freehandStroke(geom.points, rng, { width, closed: false })
-    } else if (geom.kind === 'line') {
-      ribbon = freehandStroke([{ x: geom.x1, y: geom.y1 }, { x: geom.x2, y: geom.y2 }], rng, { width, closed: false })
-    } else {
-      const poly = polygonize(geom)
-      if (poly) ribbon = freehandStroke(poly, rng, { width, closed: true })
-    }
-    if (ribbon) {
-      parts.push(`<path d="${ribbon}" fill="${opts.stroke}" stroke="none" />`)
-      return parts.join('\n')
-    }
-  }
-
-  // Outline falls back to rough (jittered); wash already drew the fill.
-  const outline = sketchGeometryRough(geom, opts.seed, opts.stroke, opts.width, wantsWash ? undefined : opts.fill, opts.p, opts.dash)
-  if (outline) parts.push(outline)
-  return parts.length > 0 ? parts.join('\n') : null
-}
-
-export const HybridBackend = createSketchBackend('hybrid', hybridSketcher)
-
-registerBackend(HybridBackend)

package/src/scene/ir.ts

@@ -1,181 +0,0 @@
-// ============================================================================
-// SceneGraph IR — the post-layout semantic render-mark tree (SPEC §3.1).
-//
-// Family renderers lower their positioned results to a SceneDoc instead of
-// concatenating SVG strings directly. Each mark carries BOTH:
-//   - semantic fields (role, geometry, paints, channels, stable id) that
-//     styled backends (rough/hybrid) consume, and
-//   - the exact crisp serialization, built at construction time from the same
-//     inputs by the mark constructors in marks.ts, which the DefaultBackend
-//     emits verbatim — so the default path stays byte-identical to the
-//     pre-IR string renderers (guarded by svg-equivalence.test.ts).
-//
-// The scene-fidelity test (scene-fidelity.test.ts) parses each mark's crisp
-// element and asserts the semantic fields agree with it, so a styled backend
-// can never silently draw different geometry than crisp output shows.
-//
-// Determinism: constructing a SceneDoc is pure — no RNG, no clock. Stochastic
-// styling happens inside styled backends, seeded per §8's substream contract
-// (see seed.ts).
-// ============================================================================
-
-import type { DiagramColors } from '../theme.ts'
-
-/** Semantic channels preserved across the renderer boundary (SPEC §5).
- *  `tone`/hue are style-derived outputs, not stored here. */
-export interface SemanticChannels {
-  /** Hierarchy / callout weight / star magnitude. */
-  importance?: number
-  /** Chart value or quantitative measure (normalized where known). */
-  value?: number
-  /** Chart series, entity type, swimlane, section identity. */
-  category?: string
-  /** e.g. gantt 'done' | 'active' | 'crit'; state 'start' | 'end'. */
-  status?: string
-  /** Task completion in [0,1]. */
-  progress?: number
-  /** Transit route / PCB net identity. */
-  route?: string
-  /** Author-flagged emphasis. */
-  emphasis?: boolean
-}
-
-/** Mark roles. A closed set per family keeps backends role-aware ("don't
- *  hachure a lifeline; do hatch a node") without importing family modules. */
-export type SceneRole =
-  // shared / flowchart
-  | 'node' | 'edge' | 'edge-label' | 'group' | 'group-header' | 'label'
-  // sequence
-  | 'actor' | 'lifeline' | 'activation' | 'message' | 'block' | 'note'
-  // class / er
-  | 'class-box' | 'member' | 'entity' | 'attribute' | 'relationship' | 'cardinality'
-  // charts
-  | 'pie-slice' | 'legend' | 'bar' | 'series' | 'point' | 'axis' | 'grid'
-  | 'plate' | 'section' | 'task' | 'milestone' | 'marker-line'
-  // timeline / journey / architecture
-  | 'rail' | 'period' | 'event' | 'score' | 'actor-pill' | 'service' | 'junction' | 'icon'
-  // document furniture
-  | 'title' | 'defs' | 'prelude' | 'chrome'
-
-/** Geometry a styled backend can redraw. Numbers are in final user units.
- *  Paint strings may be CSS var()/color-mix() refs — they resolve later via
- *  inlineResolvedColors, exactly like the crisp path. */
-export type Geometry =
-  | { kind: 'rect'; x: number; y: number; width: number; height: number; rx?: number; ry?: number }
-  | { kind: 'circle'; cx: number; cy: number; r: number }
-  | { kind: 'ellipse'; cx: number; cy: number; rx: number; ry: number }
-  | { kind: 'line'; x1: number; y1: number; x2: number; y2: number }
-  | { kind: 'polygon'; points: Array<{ x: number; y: number }> }
-  | { kind: 'polyline'; points: Array<{ x: number; y: number }> }
-  | { kind: 'path'; d: string }
-  | { kind: 'compound'; children: Geometry[] }
-
-/** The resolved paint attached to a mark — already cascaded (theme tokens,
- *  classDef, inline style, role defaults) by the family lowering. */
-export interface MarkPaint {
-  fill?: string
-  stroke?: string
-  strokeWidth?: string
-  strokeDasharray?: string
-  opacity?: string
-}
-
-export interface SceneNodeBase {
-  /** Stable identifier for seeding and cross-references. Derived from source
-   *  semantics (node id, edge endpoints, slice label...), never list position
-   *  (§8 seed contract). */
-  id: string
-  role: SceneRole
-  channels?: SemanticChannels
-  /** The exact crisp SVG serialization of this mark (possibly multi-line,
-   *  possibly '' for marks that draw nothing, e.g. invisible edges). */
-  crisp: string
-}
-
-export interface ShapeMark extends SceneNodeBase {
-  kind: 'shape'
-  geometry: Geometry
-  paint: MarkPaint
-}
-
-export interface MarkerRef {
-  /** Def id referenced via url(#...) — 'arrowhead', 'cls-inherit', ... */
-  id: string
-  /** Marker archetype so styled backends can redraw without parsing defs. */
-  shape: 'arrow' | 'open-arrow' | 'circle' | 'cross' | 'triangle' | 'diamond' | 'diamond-open'
-}
-
-export interface ConnectorMark extends SceneNodeBase {
-  kind: 'connector'
-  geometry:
-    | { kind: 'polyline'; points: Array<{ x: number; y: number }> }
-    | { kind: 'path'; d: string; points?: Array<{ x: number; y: number }> }
-    | { kind: 'line'; x1: number; y1: number; x2: number; y2: number }
-  lineStyle: 'solid' | 'dotted' | 'dashed' | 'thick' | 'invisible'
-  paint: MarkPaint
-  startMarker?: MarkerRef
-  endMarker?: MarkerRef
-}
-
-export interface TextMark extends SceneNodeBase {
-  kind: 'text'
-  /** Unescaped source text (may contain <br> separators for multiline). */
-  text: string
-  /** Anchor position the crisp emitter used. */
-  x: number
-  y: number
-  fontSize: number
-  anchor: 'start' | 'middle' | 'end'
-  paint: MarkPaint
-}
-
-/** A semantic wrapper (<g ...>...</g>) whose children are scene nodes.
- *  Serialization is reconstructed from open/close/children + per-child indent,
- *  so styled backends can restyle children while keeping wrapper semantics
- *  (classes, data-* attributes, ARIA) byte-compatible. */
-export interface GroupMark extends SceneNodeBase {
-  kind: 'group'
-  open: string
-  close: string
-  children: Array<{ node: SceneNode; indent: number }>
-  /** Joiner between open/children/close segments; '\n' everywhere today. */
-  join: string
-}
-
-/** Escape hatch for chunks not yet lowered semantically (style blocks,
- *  defs bodies, icon glyph stacks...). Styled backends pass these through or
- *  replace them wholesale via their own prelude/defs policy — they must not
- *  parse them. Aim to shrink raw usage over time. */
-export interface RawMark extends SceneNodeBase {
-  kind: 'raw'
-}
-
-/** Document prelude parameters — everything svgOpenTag/buildStyleBlock were
- *  called with, so a styled backend can re-derive its own document shell
- *  (different palette, fonts, backdrop) without string-parsing the crisp one. */
-export interface PreludeMark extends SceneNodeBase {
-  kind: 'prelude'
-  prelude: {
-    width: number
-    height: number
-    colors: DiagramColors
-    transparent: boolean
-    font: string
-    hasMonoFont: boolean
-    /** Family-specific extra CSS appended after the shared style block ('' if none). */
-    extraCss: string
-  }
-}
-
-export type SceneNode = ShapeMark | ConnectorMark | TextMark | GroupMark | RawMark | PreludeMark
-
-/** The lowered document: an ordered flat list of top-level marks. The crisp
- *  serialization is parts.map(crisp).join('\n') — exactly what the string
- *  renderers produced. */
-export interface SceneDoc {
-  family: string
-  width: number
-  height: number
-  colors: DiagramColors
-  parts: SceneNode[]
-}