agentic-mermaid 0.1.1 → 0.2.0

package/src/agent/class-body.ts

@@ -1,319 +0,0 @@
-// ============================================================================
-// Class diagram structured body: parse, serialize, mutate, verify.
-//
-// Structured-or-opaque: returns a typed body when every line maps cleanly
-// into the model, else returns null so the caller falls back to an opaque
-// body (lossless round-trip via canonicalSource).
-//
-// Supported:
-//   class A
-//   class A { +member ... }                      (multi-line braces)
-//   class A["Display label"]
-//   class A as "Display label"
-//   A : +member                                  (separate-decl member)
-//   A <|-- B  / *-- / o-- / --> / ..> / ..|> / -- / ..   (relations)
-//   A "card" <|-- "card" B : label               (cardinalities + label)
-//   note for A "text"
-//   note "text"
-//   title T
-//
-// Unmodeled (forces opaque):
-//   - direction TB / namespaces / generic types / annotations like <<enum>>
-//     embedded after `class X` (we DO accept them as `members` of X via the
-//     `class X { <<interface>> }` form). The standalone `class X <<...>>`
-//     form falls back to opaque.
-//   - cssClass / link / callback / click handlers
-//   - styled / classDef
-// ============================================================================
-
-import { unknownOpMessage } from './mutation-ops.ts'
-import type {
-  ClassBody, ClassNode, ClassRelation, ClassRelationKind, ClassNote,
-  ClassMutationOp, MutationError, Result, LayoutWarning, VerifyOptions,
-} from './types.ts'
-import { ok, err, DEFAULT_LABEL_CHAR_CAP } from './types.ts'
-import { labelOverflowWarning } from './label-metrics.ts'
-
-// ---- Parser ---------------------------------------------------------------
-
-const RELATION_TOKENS: Array<{ pat: RegExp; kind: ClassRelationKind }> = [
-  // Order matters: more specific (4+ char) before shorter ones.
-  { pat: /<\|--/, kind: 'inheritance' },
-  { pat: /--\|>/, kind: 'inheritance' },
-  { pat: /\.\.\|>/, kind: 'realization' },
-  { pat: /\*--/, kind: 'composition' },
-  { pat: /--\*/, kind: 'composition' },
-  { pat: /o--/, kind: 'aggregation' },
-  { pat: /--o/, kind: 'aggregation' },
-  { pat: /-->/, kind: 'association' },
-  { pat: /<--/, kind: 'association' },
-  { pat: /\.\.>/, kind: 'dependency' },
-  { pat: /<\.\./, kind: 'dependency' },
-  { pat: /--/,    kind: 'link-solid' },
-  { pat: /\.\./,  kind: 'link-dashed' },
-]
-
-// `class X`, `class X { ... }`, `class X["label"]`, `class X as "label"`
-const CLASS_DECL_RE = /^class\s+(`[^`]+`|[\w$]+)(?:\s*\[\s*"([^"]*)"\s*\])?(?:\s+as\s+"([^"]+)")?\s*(\{)?\s*$/
-const MEMBER_DECL_RE = /^(`[^`]+`|[\w$]+)\s*:\s*(.+)$/
-const NOTE_RE = /^note(?:\s+for\s+(`[^`]+`|[\w$]+))?\s+"([^"]+)"\s*$/
-const TITLE_RE = /^title\s+(.+)$/i
-
-function stripBackticks(s: string): string {
-  return s.startsWith('`') && s.endsWith('`') ? s.slice(1, -1) : s
-}
-
-function parseRelation(line: string): ClassRelation | null {
-  for (const { pat, kind } of RELATION_TOKENS) {
-    const m = line.match(new RegExp(`^(\\S+?)(?:\\s+"([^"]+)")?\\s*${pat.source}\\s*(?:"([^"]+)"\\s+)?(\\S+?)(?:\\s*:\\s*(.+))?$`))
-    if (!m) continue
-    const from = stripBackticks(m[1]!)
-    const fromCardinality = m[2]
-    const toCardinality = m[3]
-    const to = stripBackticks(m[4]!)
-    const label = m[5]?.trim()
-    // Reject if from/to don't look like class names
-    if (!/^[\w$]+$/.test(from) || !/^[\w$]+$/.test(to)) return null
-    return { from, to, kind, label, fromCardinality, toCardinality }
-  }
-  return null
-}
-
-export function parseClassBody(lines: string[]): ClassBody | null {
-  const body: ClassBody = { kind: 'class', classes: [], relations: [], notes: [] }
-  const classMap = new Map<string, ClassNode>()
-  const upsert = (id: string, label?: string): ClassNode => {
-    let c = classMap.get(id)
-    if (!c) { c = { id, label, members: [] }; classMap.set(id, c); body.classes.push(c) }
-    else if (label !== undefined && !c.label) c.label = label
-    return c
-  }
-
-  let i = 0
-  while (i < lines.length) {
-    const raw = lines[i]!.trim()
-    i++
-    if (!raw || raw.startsWith('%%')) continue
-
-    // Title
-    const tm = raw.match(TITLE_RE)
-    if (tm) { body.title = tm[1]!.trim(); continue }
-
-    // Class declaration (with or without open brace)
-    const cm = raw.match(CLASS_DECL_RE)
-    if (cm) {
-      const id = stripBackticks(cm[1]!)
-      const label = cm[2] ?? cm[3]
-      const node = upsert(id, label)
-      if (cm[4] === '{') {
-        // Consume members until closing brace
-        while (i < lines.length) {
-          const ml = lines[i]!.trim()
-          i++
-          if (!ml || ml.startsWith('%%')) continue
-          if (ml === '}') break
-          node.members.push(ml)
-        }
-      }
-      continue
-    }
-
-    // Note (with or without target)
-    const nm = raw.match(NOTE_RE)
-    if (nm) {
-      body.notes.push({ text: nm[2]!, for: nm[1] ? stripBackticks(nm[1]) : undefined })
-      continue
-    }
-
-    // Relation — try this before member because relations may have `:` too
-    const rel = parseRelation(raw)
-    if (rel) { body.relations.push(rel); upsert(rel.from); upsert(rel.to); continue }
-
-    // Member declaration (X : member)
-    const mm = raw.match(MEMBER_DECL_RE)
-    if (mm) {
-      const id = stripBackticks(mm[1]!)
-      const text = mm[2]!.trim()
-      upsert(id).members.push(text)
-      continue
-    }
-
-    // Unmodeled line — bail to opaque.
-    return null
-  }
-  return body
-}
-
-// ---- Serializer -----------------------------------------------------------
-
-const ARROW_FOR: Record<ClassRelationKind, string> = {
-  inheritance: '<|--',
-  composition: '*--',
-  aggregation: 'o--',
-  association: '-->',
-  dependency:  '..>',
-  realization: '..|>',
-  'link-solid': '--',
-  'link-dashed': '..',
-}
-
-function quoteIfNeeded(id: string): string {
-  return /^[\w$]+$/.test(id) ? id : `\`${id}\``
-}
-
-export function renderClass(body: ClassBody): string {
-  const lines: string[] = ['classDiagram']
-  if (body.title) lines.push(`  title ${body.title}`)
-  for (const n of body.notes) {
-    if (n.for) lines.push(`  note for ${quoteIfNeeded(n.for)} "${n.text}"`)
-    else lines.push(`  note "${n.text}"`)
-  }
-  for (const c of body.classes) {
-    const head = `class ${quoteIfNeeded(c.id)}${c.label ? `["${c.label}"]` : ''}`
-    if (c.members.length === 0) {
-      lines.push(`  ${head}`)
-    } else {
-      lines.push(`  ${head} {`)
-      for (const m of c.members) lines.push(`    ${m}`)
-      lines.push(`  }`)
-    }
-  }
-  for (const r of body.relations) {
-    const arrow = ARROW_FOR[r.kind]
-    const left = r.fromCardinality ? `${quoteIfNeeded(r.from)} "${r.fromCardinality}"` : quoteIfNeeded(r.from)
-    const right = r.toCardinality ? `"${r.toCardinality}" ${quoteIfNeeded(r.to)}` : quoteIfNeeded(r.to)
-    const label = r.label ? ` : ${r.label}` : ''
-    lines.push(`  ${left} ${arrow} ${right}${label}`)
-  }
-  return lines.join('\n') + '\n'
-}
-
-// ---- Mutator --------------------------------------------------------------
-
-function cloneClass(body: ClassBody): ClassBody {
-  return {
-    kind: 'class',
-    title: body.title,
-    classes: body.classes.map(c => ({ id: c.id, label: c.label, members: [...c.members] })),
-    relations: body.relations.map(r => ({ ...r })),
-    notes: body.notes.map(n => ({ ...n })),
-  }
-}
-
-export function mutateClass(body: ClassBody, op: ClassMutationOp): Result<ClassBody, MutationError> {
-  const b = cloneClass(body)
-  const findClass = (id: string) => b.classes.find(c => c.id === id)
-
-  switch (op.kind) {
-    case 'set_title': {
-      b.title = op.title ?? undefined
-      return ok(b)
-    }
-    case 'add_class': {
-      if (findClass(op.id)) return err({ code: 'DUPLICATE_CLASS', message: `class ${op.id} already exists` })
-      b.classes.push({ id: op.id, label: op.label, members: op.members ?? [] })
-      return ok(b)
-    }
-    case 'remove_class': {
-      const i = b.classes.findIndex(c => c.id === op.id)
-      if (i < 0) return err({ code: 'CLASS_NOT_FOUND', message: `class ${op.id} not found` })
-      b.classes.splice(i, 1)
-      b.relations = b.relations.filter(r => r.from !== op.id && r.to !== op.id)
-      b.notes = b.notes.filter(n => n.for !== op.id)
-      return ok(b)
-    }
-    case 'rename_class': {
-      const c = findClass(op.from)
-      if (!c) return err({ code: 'CLASS_NOT_FOUND', message: `class ${op.from} not found` })
-      if (findClass(op.to)) return err({ code: 'DUPLICATE_CLASS', message: `class ${op.to} already exists` })
-      c.id = op.to
-      for (const r of b.relations) {
-        if (r.from === op.from) r.from = op.to
-        if (r.to === op.from) r.to = op.to
-      }
-      for (const n of b.notes) if (n.for === op.from) n.for = op.to
-      return ok(b)
-    }
-    case 'add_member': {
-      const c = findClass(op.class)
-      if (!c) return err({ code: 'CLASS_NOT_FOUND', message: `class ${op.class} not found` })
-      c.members.push(op.text)
-      return ok(b)
-    }
-    case 'remove_member': {
-      const c = findClass(op.class)
-      if (!c) return err({ code: 'CLASS_NOT_FOUND', message: `class ${op.class} not found` })
-      if (op.index < 0 || op.index >= c.members.length) return err({ code: 'MEMBER_NOT_FOUND', message: `member index ${op.index} out of range` })
-      c.members.splice(op.index, 1)
-      return ok(b)
-    }
-    case 'add_relation': {
-      if (!findClass(op.from)) return err({ code: 'CLASS_NOT_FOUND', message: `class ${op.from} not found` })
-      if (!findClass(op.to)) return err({ code: 'CLASS_NOT_FOUND', message: `class ${op.to} not found` })
-      b.relations.push({ from: op.from, to: op.to, kind: op.relKind, label: op.label })
-      return ok(b)
-    }
-    case 'remove_relation': {
-      if (op.index < 0 || op.index >= b.relations.length) return err({ code: 'RELATION_NOT_FOUND', message: `relation index ${op.index} out of range` })
-      b.relations.splice(op.index, 1)
-      return ok(b)
-    }
-    case 'add_note': {
-      if (op.for && !findClass(op.for)) return err({ code: 'CLASS_NOT_FOUND', message: `class ${op.for} not found` })
-      b.notes.push({ text: op.text, for: op.for })
-      return ok(b)
-    }
-    case 'remove_note': {
-      if (op.index < 0 || op.index >= b.notes.length) return err({ code: 'NOTE_NOT_FOUND', message: `note index ${op.index} out of range` })
-      b.notes.splice(op.index, 1)
-      return ok(b)
-    }
-    default:
-      return err({ code: 'INVALID_OP', message: unknownOpMessage('class', op) })
-  }
-}
-
-// ---- Verifier -------------------------------------------------------------
-
-export function verifyClass(body: ClassBody, opts: VerifyOptions): LayoutWarning[] {
-  const warnings: LayoutWarning[] = []
-  const cap = opts.labelCharCap ?? DEFAULT_LABEL_CHAR_CAP
-
-  if (body.classes.length === 0 && body.title === undefined) {
-    warnings.push({ code: 'EMPTY_DIAGRAM' })
-    return warnings
-  }
-
-  const overflow = (target: string, text: string) => {
-    const w = labelOverflowWarning(target, text, cap)
-    if (w) warnings.push(w)
-  }
-  if (body.title) overflow('title', body.title)
-
-  const ids = new Set(body.classes.map(c => c.id))
-  for (const c of body.classes) {
-    if (c.label) overflow(c.id, c.label)
-    for (let i = 0; i < c.members.length; i++) {
-      overflow(`${c.id}#m${i}`, c.members[i]!)
-    }
-  }
-  for (let i = 0; i < body.relations.length; i++) {
-    const r = body.relations[i]!
-    if (!ids.has(r.from) || !ids.has(r.to)) {
-      warnings.push({
-        code: 'EDGE_MISANCHORED', edge: `rel#${i}:${r.from}->${r.to}`,
-        from: ids.has(r.from) ? r.from : undefined, to: ids.has(r.to) ? r.to : undefined,
-      })
-    }
-    if (r.label) overflow(`rel#${i}`, r.label)
-  }
-  for (let i = 0; i < body.notes.length; i++) {
-    const n = body.notes[i]!
-    overflow(`note#${i}`, n.text)
-    if (n.for && !ids.has(n.for)) {
-      warnings.push({ code: 'EDGE_MISANCHORED', edge: `note#${i}->${n.for}`, from: undefined, to: undefined })
-    }
-  }
-
-  return warnings
-}

package/src/agent/core.ts

@@ -1,207 +0,0 @@
-// ============================================================================
-// agentic-mermaid — runtime-neutral agent surface (v4).
-// Everything here is pure JS/TS (elkjs bundled build included) and safe to
-// bundle for workerd/browser targets. The public barrel (`./index.ts`)
-// re-exports this plus the Node-native `renderMermaidPNG`; import this module
-// from code that must not drag in the napi resvg addon.
-// No LayoutContext / SeededRNG / Clock / font-metrics: that apparatus did
-// nothing (ELK is deterministic on its own). See AGENT_NATIVE.md § (1).
-// ============================================================================
-
-export type {
-  Result, ValidDiagram, FlowchartValidDiagram, StateValidDiagram, SequenceValidDiagram, TimelineValidDiagram,
-  ClassValidDiagram, ErValidDiagram, JourneyValidDiagram, ArchitectureValidDiagram, XyChartValidDiagram, PieValidDiagram, QuadrantValidDiagram, GanttValidDiagram, MutableValidDiagram,
-  ValidDiagramMeta, ValidDiagramPayload, SerializedFlowchartGraph, DiagramBody, DiagramKind,
-  StateBody, StateNode, StateTransition,
-  SequenceBody, SequenceParticipant, SequenceMessage, SequenceMessageStyle,
-  TimelineBody, TimelineSection, TimelinePeriod, TimelineEvent,
-  ClassBody, ClassNode, ClassRelation, ClassRelationKind, ClassNote,
-  ErBody, ErEntity, ErRelation, ErAttribute, ErCardinality,
-  JourneyBody, JourneySection, JourneyTask,
-  ArchitectureBody, ArchitectureGroup, ArchitectureService, ArchitectureJunction, ArchitectureEdge, ArchitectureEndpoint, ArchitectureSide,
-  XyChartBody, XyChartAxis, XyChartSeries, XyChartAxisSpec,
-  PieBody, PieSlice, QuadrantBody, QuadrantAxis, QuadrantPoint,
-  GanttBody, GanttBodySection, GanttBodyTask, GanttBodyTaskTag, GanttStatement,
-  SourceMap, SourceComment, InitDirective, Accessibility,
-  ParseError, MutationError, MutationOp, FlowchartMutationOp, StateMutationOp, SequenceMutationOp, TimelineMutationOp,
-  ClassMutationOp, ErMutationOp, JourneyMutationOp, ArchitectureMutationOp, XyChartMutationOp, PieMutationOp, QuadrantMutationOp, GanttMutationOp, AnyMutationOp,
-  NodeId, EdgeId, GroupId, ParticipantId,
-  LayoutWarning, WarningCode, Tier1WarningCode, Tier2WarningCode, WarningSeverity, WarningTier,
-  VerifyOptions, VerifyResult, RenderedLayout, RenderedLayoutNode, RenderedLayoutEdge, RenderedLayoutGroup, RenderedRegion, RenderedRegionKind,
-  DiagramAnalysis, DiagramActionRecord, DiagramActionKind, DiagramActionSecurity, FeedbackEdgeAnalysis, GanttScheduleAnalysisSummary,
-  Finite,
-} from './types.ts'
-export type { MermaidFact, CheckMermaidSpec, CheckMermaidObjectSpec, CheckMermaidResult } from './facts.ts'
-
-export { WARNING_SEVERITY, WARNING_TIER, DEFAULT_LABEL_CHAR_CAP, ok, err, toFinite, asFlowchart, asState, asSequence, asTimeline, asClass, asEr, asJourney, asArchitecture, asXyChart, asPie, asQuadrant, asGantt } from './types.ts'
-export { parseMermaid } from './parse.ts'
-export { serializeMermaid, synthesizeFromGraph } from './serialize.ts'
-export { createMermaid, buildMermaid } from './create.ts'
-export type { CreateMermaidOptions, BuildError } from './create.ts'
-export { mutate, mutateChecked, edgeIdOf } from './mutate.ts'
-export { applyOps, buildChecked, verifySummary } from './apply.ts'
-export type { OpEnvelope, VerifySummary, CheckedBuildError, ApplyOpsInput } from './apply.ts'
-export { validateOp, hasOpSchema, opMenu, describeOps, opSignatures } from './op-schema.ts'
-export type { OpFamily, OpValidationError, OpFieldDoc } from './op-schema.ts'
-export { verifyMermaid } from './verify.ts'
-export { measureQuality, checkQuality, DEFAULT_BOUNDS, BOUND_PROVENANCE } from './quality.ts'
-export type { QualityMetrics, QualityBounds, QualityVerdict, RankedViolation, BoundProvenance, BoundBasis, ViolationSeverity } from './quality.ts'
-export { layoutCertificateProof } from './certificates.ts'
-export type { LayoutCertificateProof } from './certificates.ts'
-export type { RouteCertificate, EdgeRouteCertificate, FamilyEdgeRouteCertificate, RegionContainmentCertificate, FamilyRouteCertificate, LayoutRouteCertificate, LayoutRouteClass, RouteClass, RouteBlocker, RoutePortAssignment, PortSemanticRole, AnyPort, PortSide, DiamondFacet } from '../types.ts'
-export { registerFamily, getFamily, knownFamilies, BUILTIN_FAMILY_METADATA, BUILTIN_FAMILY_METADATA_COVERS_DIAGRAM_KIND, builtinFamilyMetadata } from './families.ts'
-export type { FamilyPlugin, ExtractedLabel, BuiltinFamilyMetadata, BuiltinFamilyId } from './families.ts'
-export { renderMermaidASCIIWithMeta, ASCII_ROUTE_PARITY_CONTRACT } from '../ascii/meta.ts'
-export type { AsciiRegion, AsciiWithMeta, RegionKind, AsciiWarning, AsciiWarningCode } from '../ascii/meta.ts'
-export { describeMermaid, describeMermaidSource, describeMermaidTree } from './describe.ts'
-export { describeMermaidFacts, describeMermaidFactsSource, checkMermaid, checkMermaidSource } from './facts.ts'
-export { analyzeMermaid, analyzeMermaidSource, collectActionRecords } from './analyze.ts'
-export { TEXT_MEASUREMENT_CONTRACT, measureText, measureTextWidth } from '../text-metrics.ts'
-export type { TextMeasurementContract, TextMeasurementInput, TextMeasurementResult } from '../text-metrics.ts'
-export type { DescribeTree } from './describe.ts'
-export type { DescribeOptions } from './describe.ts'
-export { asciiToMermaid } from '../ascii/reverse.ts'
-
-import { renderMermaidSVG as _svg } from '../index.ts'
-export { verifyNoExternalRefs } from '../index.ts'
-// Style system — agents reach the library through this entry, so the style
-// registry must be importable here too, not only from the main entry.
-export { registerStyle, getStyle, knownStyles, validateStyleSpec, resolveStyleStack, inferBackend } from '../scene/style-registry.ts'
-export type { StyleSpec, StyleInput } from '../scene/style-registry.ts'
-import { renderMermaidASCII as _ascii } from '../ascii/index.ts'
-import { layoutGraphSync } from '../layout-engine.ts'
-import { parseMermaid as parseFlowchartLegacy } from '../parser.ts'
-import { stateBodyToGraph } from './state-body.ts'
-import { serializeMermaid as _serialize } from './serialize.ts'
-import type { ValidDiagram, RenderedLayout, RenderedRegion } from './types.ts'
-import { positionedToRenderedLayout, emptyRenderedLayout } from './layout-to-rendered.ts'
-import { layoutFamilyToRendered } from './family-layouts.ts'
-import { collectActionRecords as collectRenderedActionRecords } from './analyze.ts'
-import { toFinite } from './types.ts'
-
-export function renderMermaidSVG(input: ValidDiagram | string, opts: Parameters<typeof _svg>[1] = {}): string {
-  return _svg(typeof input === 'string' ? input : _serialize(input), opts)
-}
-export function renderMermaidASCII(input: ValidDiagram | string, opts: Parameters<typeof _ascii>[1] = {}): string {
-  return _ascii(typeof input === 'string' ? input : _serialize(input), opts)
-}
-
-export interface LayoutMermaidOptions { debug?: boolean; regions?: boolean; actions?: boolean }
-
-export function layoutMermaid(d: ValidDiagram, opts: LayoutMermaidOptions = {}): RenderedLayout {
-  if (d.body.kind === 'flowchart') {
-    return enrichRenderedLayout(d, positionedToRenderedLayout(layoutGraphSync(d.body.graph, {}), d.kind, opts), opts)
-  }
-  // State diagrams (BUILD-19) project to a MermaidGraph via the legacy parser,
-  // so layout reuses the flowchart geometric path.
-  if (d.body.kind === 'state') {
-    return enrichRenderedLayout(d, positionedToRenderedLayout(layoutGraphSync(stateBodyToGraph(d.body), {}), d.kind, opts), opts)
-  }
-  if (d.body.kind === 'opaque' && d.kind === 'flowchart') {
-    try {
-      return enrichRenderedLayout(d, positionedToRenderedLayout(layoutGraphSync(parseFlowchartLegacy(d.canonicalSource), {}), d.kind, opts), opts)
-    } catch {
-      return emptyRenderedLayout(d.kind)
-    }
-  }
-  // QUAL-1: renderable non-graph families project their real positioned
-  // layout (parsed from d.canonicalSource — works for both structured and
-  // opaque bodies) so the perceptual-quality metrics see them. Debug mode
-  // includes family-specific route/layout certificates where available.
-  const familyLayout = layoutFamilyToRendered(d, opts)
-  if (familyLayout) return enrichRenderedLayout(d, familyLayout, opts)
-  return enrichRenderedLayout(d, emptyRenderedLayout(d.kind), opts)
-}
-
-function enrichRenderedLayout(d: ValidDiagram, layout: RenderedLayout, opts: LayoutMermaidOptions): RenderedLayout {
-  const wantRegions = opts.debug || opts.regions
-  const wantActions = opts.debug || opts.actions
-  if (!wantRegions && !wantActions) return layout
-  const next: RenderedLayout = { ...layout }
-  if (wantRegions) next.regions = buildRenderedRegions(d, layout)
-  if (wantActions) {
-    const nodeIds = new Set<string>(layout.nodes.map(n => n.id))
-    next.actions = collectRenderedActionRecords(d)
-      .filter(a => nodeIds.has(a.target))
-      .map(a => ({ ...a, regionId: a.regionId ?? `node:${a.target}` }))
-  }
-  return next
-}
-
-function buildRenderedRegions(d: ValidDiagram, layout: RenderedLayout): RenderedRegion[] {
-  const regions: RenderedRegion[] = [{
-    id: 'canvas',
-    kind: 'canvas',
-    bounds: { x: toFinite(0), y: toFinite(0), w: layout.bounds.w, h: layout.bounds.h },
-  }]
-  const groupByMember = new Map<string, string>()
-  for (const group of layout.groups) for (const member of group.members) groupByMember.set(member, group.id)
-  const sourceLines = sourceLineHints(d)
-  for (const group of layout.groups) {
-    regions.push({
-      id: `group:${group.id}`,
-      kind: 'group',
-      elementId: group.id,
-      parentId: group.parentId ? `group:${group.parentId}` : 'canvas',
-      bounds: { x: group.x, y: group.y, w: group.w, h: group.h },
-      sourceLine: d.source.groups.get(group.id)?.line ?? sourceLines.groups.get(group.id),
-    })
-  }
-  for (const node of layout.nodes) {
-    regions.push({
-      id: `node:${node.id}`,
-      kind: 'node',
-      elementId: node.id,
-      parentId: groupByMember.has(node.id) ? `group:${groupByMember.get(node.id)!}` : 'canvas',
-      bounds: { x: node.x, y: node.y, w: node.w, h: node.h },
-      sourceLine: d.source.nodes.get(node.id)?.line ?? sourceLines.nodes.get(node.id),
-    })
-  }
-  for (const edge of layout.edges) {
-    const xs = edge.path.map(p => p[0])
-    const ys = edge.path.map(p => p[1])
-    if (xs.length > 0 && ys.length > 0) {
-      const minX = Math.min(...xs), maxX = Math.max(...xs), minY = Math.min(...ys), maxY = Math.max(...ys)
-      regions.push({
-        id: `edge:${edge.id}`,
-        kind: 'edge',
-        elementId: edge.id,
-        parentId: 'canvas',
-        bounds: { x: toFinite(minX), y: toFinite(minY), w: toFinite(Math.max(1, maxX - minX)), h: toFinite(Math.max(1, maxY - minY)) },
-      })
-    }
-    if (edge.label) {
-      const w = Math.max(1, edge.label.text.length * 7)
-      const h = 14
-      const labelX = d.kind === 'sequence' && edge.from === edge.to
-        ? edge.label.x // sequence self-message labels render with text-anchor="start"
-        : edge.label.x - w / 2
-      regions.push({
-        id: `label:${edge.id}`,
-        kind: 'label',
-        elementId: edge.id,
-        parentId: `edge:${edge.id}`,
-        bounds: { x: toFinite(labelX), y: toFinite(edge.label.y - h / 2), w: toFinite(w), h: toFinite(h) },
-      })
-    }
-  }
-  return regions
-}
-
-function sourceLineHints(d: ValidDiagram): { nodes: Map<string, number>; groups: Map<string, number> } {
-  const nodes = new Map<string, number>()
-  const groups = new Map<string, number>()
-  const source = d.body.kind === 'opaque' ? d.body.source : d.canonicalSource
-  const lines = source.split(/\r?\n/)
-  for (let i = 0; i < lines.length; i++) {
-    const text = lines[i]!
-    const group = text.match(/^\s*subgraph\s+([A-Za-z0-9_:-]+)/)
-    if (group?.[1] && !groups.has(group[1])) groups.set(group[1], i + 1)
-    for (const node of text.matchAll(/(?:^|[\s&;])([A-Za-z][A-Za-z0-9_:-]*)(?=\s*(?:\[|\(|\{|--|==|-.|$))/g)) {
-      const id = node[1]!
-      if (id === 'subgraph' || id === 'end' || id === d.kind) continue
-      if (!nodes.has(id)) nodes.set(id, i + 1)
-    }
-  }
-  return { nodes, groups }
-}

package/src/agent/create.ts

@@ -1,106 +0,0 @@
-// ============================================================================
-// createMermaid / buildMermaid: blank-slate authoring through the typed
-// surface. Editing an existing diagram already goes parse → narrow → mutate;
-// creating one previously meant hand-writing Mermaid source — the fragile
-// path the typed ops exist to replace. createMermaid returns an empty
-// structured diagram for any built-in family; buildMermaid folds a mutation
-// list over that empty diagram so a whole new diagram is one typed call.
-// ============================================================================
-
-import type {
-  ValidDiagram, MutableValidDiagram, DiagramKind, DiagramBody,
-  FlowchartValidDiagram, StateValidDiagram, SequenceValidDiagram, TimelineValidDiagram,
-  ClassValidDiagram, ErValidDiagram, JourneyValidDiagram, ArchitectureValidDiagram,
-  XyChartValidDiagram, PieValidDiagram, QuadrantValidDiagram, GanttValidDiagram,
-  FlowchartMutationOp, StateMutationOp, SequenceMutationOp, TimelineMutationOp,
-  ClassMutationOp, ErMutationOp, JourneyMutationOp, ArchitectureMutationOp,
-  XyChartMutationOp, PieMutationOp, QuadrantMutationOp, GanttMutationOp, AnyMutationOp,
-  MutationError, Result,
-} from './types.ts'
-import { ok, err } from './types.ts'
-import { serializeMermaid } from './serialize.ts'
-import { logToolInvocation } from './trace-log.ts'
-import { mutate } from './mutate.ts'
-import type { Direction } from '../types.ts'
-
-export interface CreateMermaidOptions {
-  /** Layout direction for flowchart/state diagrams (default TD). Ignored elsewhere. */
-  direction?: Direction
-}
-
-/** A mutation failure annotated with which op in the build list failed. */
-export type BuildError = MutationError & { opIndex: number }
-
-function emptyBody(kind: DiagramKind, opts: CreateMermaidOptions): Exclude<DiagramBody, { kind: 'opaque' }> {
-  switch (kind) {
-    case 'flowchart': return {
-      kind: 'flowchart',
-      graph: {
-        direction: opts.direction ?? 'TD', nodes: new Map(), edges: [], subgraphs: [],
-        classDefs: new Map(), classAssignments: new Map(), nodeStyles: new Map(), linkStyles: new Map(),
-      },
-    }
-    case 'state': return { kind: 'state', states: [], transitions: [], direction: opts.direction }
-    case 'sequence': return { kind: 'sequence', participants: [], messages: [], statements: [] }
-    case 'timeline': return { kind: 'timeline', sections: [] }
-    case 'class': return { kind: 'class', classes: [], relations: [], notes: [] }
-    case 'er': return { kind: 'er', entities: [], relations: [] }
-    case 'journey': return { kind: 'journey', sections: [] }
-    case 'architecture': return { kind: 'architecture', groups: [], services: [], junctions: [], edges: [] }
-    case 'xychart': return { kind: 'xychart', series: [] }
-    case 'pie': return { kind: 'pie', showData: false, slices: [] }
-    case 'quadrant': return { kind: 'quadrant', quadrants: [undefined, undefined, undefined, undefined], points: [] }
-    case 'gantt': return { kind: 'gantt', sections: [], statements: [] }
-  }
-}
-
-export function createMermaid(kind: 'flowchart', opts?: CreateMermaidOptions): FlowchartValidDiagram
-export function createMermaid(kind: 'state', opts?: CreateMermaidOptions): StateValidDiagram
-export function createMermaid(kind: 'sequence', opts?: CreateMermaidOptions): SequenceValidDiagram
-export function createMermaid(kind: 'timeline', opts?: CreateMermaidOptions): TimelineValidDiagram
-export function createMermaid(kind: 'class', opts?: CreateMermaidOptions): ClassValidDiagram
-export function createMermaid(kind: 'er', opts?: CreateMermaidOptions): ErValidDiagram
-export function createMermaid(kind: 'journey', opts?: CreateMermaidOptions): JourneyValidDiagram
-export function createMermaid(kind: 'architecture', opts?: CreateMermaidOptions): ArchitectureValidDiagram
-export function createMermaid(kind: 'xychart', opts?: CreateMermaidOptions): XyChartValidDiagram
-export function createMermaid(kind: 'pie', opts?: CreateMermaidOptions): PieValidDiagram
-export function createMermaid(kind: 'quadrant', opts?: CreateMermaidOptions): QuadrantValidDiagram
-export function createMermaid(kind: 'gantt', opts?: CreateMermaidOptions): GanttValidDiagram
-export function createMermaid(kind: DiagramKind, opts?: CreateMermaidOptions): MutableValidDiagram
-export function createMermaid(kind: DiagramKind, opts: CreateMermaidOptions = {}): MutableValidDiagram {
-  logToolInvocation('build') // also covers buildMermaid/buildChecked, which route through here
-  const body = emptyBody(kind, opts) as ReturnType<typeof emptyBody> | undefined
-  // The switch is TS-exhaustive but callers reach this from untyped surfaces
-  // (Code Mode, CLI), so fail loudly on an unknown kind.
-  if (!body) throw new Error(`createMermaid: unknown diagram kind "${String(kind)}"`)
-  const draft: ValidDiagram = {
-    kind, body,
-    meta: { initDirectives: [], comments: [], accessibility: {} },
-    source: { nodes: new Map(), edges: new Map(), groups: new Map(), labels: new Map() },
-    canonicalSource: '',
-  }
-  return { ...draft, canonicalSource: serializeMermaid(draft) } as MutableValidDiagram
-}
-
-export function buildMermaid(kind: 'flowchart', ops: FlowchartMutationOp[], opts?: CreateMermaidOptions): Result<FlowchartValidDiagram, BuildError>
-export function buildMermaid(kind: 'state', ops: StateMutationOp[], opts?: CreateMermaidOptions): Result<StateValidDiagram, BuildError>
-export function buildMermaid(kind: 'sequence', ops: SequenceMutationOp[], opts?: CreateMermaidOptions): Result<SequenceValidDiagram, BuildError>
-export function buildMermaid(kind: 'timeline', ops: TimelineMutationOp[], opts?: CreateMermaidOptions): Result<TimelineValidDiagram, BuildError>
-export function buildMermaid(kind: 'class', ops: ClassMutationOp[], opts?: CreateMermaidOptions): Result<ClassValidDiagram, BuildError>
-export function buildMermaid(kind: 'er', ops: ErMutationOp[], opts?: CreateMermaidOptions): Result<ErValidDiagram, BuildError>
-export function buildMermaid(kind: 'journey', ops: JourneyMutationOp[], opts?: CreateMermaidOptions): Result<JourneyValidDiagram, BuildError>
-export function buildMermaid(kind: 'architecture', ops: ArchitectureMutationOp[], opts?: CreateMermaidOptions): Result<ArchitectureValidDiagram, BuildError>
-export function buildMermaid(kind: 'xychart', ops: XyChartMutationOp[], opts?: CreateMermaidOptions): Result<XyChartValidDiagram, BuildError>
-export function buildMermaid(kind: 'pie', ops: PieMutationOp[], opts?: CreateMermaidOptions): Result<PieValidDiagram, BuildError>
-export function buildMermaid(kind: 'quadrant', ops: QuadrantMutationOp[], opts?: CreateMermaidOptions): Result<QuadrantValidDiagram, BuildError>
-export function buildMermaid(kind: 'gantt', ops: GanttMutationOp[], opts?: CreateMermaidOptions): Result<GanttValidDiagram, BuildError>
-export function buildMermaid(kind: DiagramKind, ops: AnyMutationOp[], opts?: CreateMermaidOptions): Result<MutableValidDiagram, BuildError>
-export function buildMermaid(kind: DiagramKind, ops: AnyMutationOp[], opts: CreateMermaidOptions = {}): Result<MutableValidDiagram, BuildError> {
-  let d = createMermaid(kind, opts)
-  for (let i = 0; i < ops.length; i++) {
-    const r = mutate(d, ops[i]!)
-    if (!r.ok) return err({ ...r.error, opIndex: i, message: `op[${i}] (${ops[i]!.kind}): ${r.error.message}` })
-    d = r.value
-  }
-  return ok(d)
-}