@cristianormazabal/triton-core 0.1.0

package/dist/contracts/anchors.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Anchors
+ *
+ * Contracts for the node-anchor registry: the mechanism that makes
+ * individual nodes addressable from outside their parent diagram.
+ *
+ * Every linkable diagram's layout engine produces a NodeAnchorRegistry
+ * alongside its Scene. The registry maps each node's logical ID to its
+ * bounding box and optional cardinal ports, expressed in the diagram's
+ * LOCAL coordinate space (before any composition-level translation/scaling).
+ *
+ * The composition layer (poster layout) transforms local anchors to
+ * poster-space coordinates, merges registries from child cells with
+ * path-prefixed keys, and publishes the merged result upward — enabling
+ * cross-diagram linking at any nesting depth.
+ *
+ * Dependency: primitives.ts
+ */
+import type { Point, Rect } from './primitives.js';
+import type { Scene } from './scene.js';
+/** The four cardinal attachment sides of a node bounding box. */
+export type CardinalSide = 'N' | 'S' | 'E' | 'W';
+/**
+ * Explicit port positions on a node's boundary.
+ * If absent, the link layer derives port midpoints from the bounding box:
+ *   N = (x + w/2, y)
+ *   S = (x + w/2, y + h)
+ *   E = (x + w, y + h/2)
+ *   W = (x, y + h/2)
+ */
+export type CardinalPorts = Partial<Record<CardinalSide, Point>>;
+/**
+ * Anchor for a single node: bounding box in local diagram coordinates,
+ * plus optional explicit port attachment points.
+ *
+ * The bounding box is the axis-aligned rectangle that fully encloses
+ * the node's visual representation (shape + label + padding).
+ */
+export interface NodeAnchor {
+    /** Bounding box in local diagram coordinates. */
+    readonly bounds: Rect;
+    /**
+     * Optional explicit port positions.
+     * When present, cross-link routing uses these instead of deriving
+     * midpoints from the bounding box edges.
+     */
+    readonly ports?: CardinalPorts;
+}
+/**
+ * Maps node IDs to their anchors in local diagram coordinates.
+ *
+ * For flat diagrams (flowchart, class, state, etc.):
+ *   keys are the raw node IDs as authored: "pay", "db", "UserService"
+ *
+ * For hierarchical diagrams (poster with nested children):
+ *   keys are dot-separated paths: "A1.pay", "B1.A1.db"
+ *   Each level of nesting prepends the cell address.
+ *
+ * The registry is intentionally a plain Record for JSON serialisability
+ * and O(1) lookup. Iteration order is not guaranteed.
+ */
+export type NodeAnchorRegistry = Readonly<Record<string, NodeAnchor>>;
+/**
+ * A port position on a node wall that is already in use by an edge rendered
+ * within a diagram cell (intra) or by another cross-link (inter).
+ *
+ * The cross-link routing engine uses these to avoid stacking connectors
+ * at the same wall position. Intra-diagram ports carry a softer penalty
+ * than inter-crosslink ports so the global cost function can override them
+ * when necessary.
+ */
+export interface OccupiedPort {
+    /** Prefixed node key (same format as NodeAnchorRegistry keys). */
+    readonly nodeKey: string;
+    /** Which wall the port is on. */
+    readonly wall: CardinalSide;
+    /**
+     * Fractional position along the wall (0 = start, 1 = end).
+     * N/S walls: 0 = left edge, 1 = right edge.
+     * E/W walls: 0 = top edge, 1 = bottom edge.
+     */
+    readonly t: number;
+    /**
+     * Origin of the occupancy.
+     * 'intra' — edge produced by the cell's own diagram layout pass.
+     * 'inter' — cross-link committed by the cross-link routing engine.
+     */
+    readonly source: 'intra' | 'inter';
+}
+/**
+ * The extended return type of a diagram layout pass.
+ *
+ * All diagram layout engines return LayoutResult instead of bare Scene.
+ * This carries the renderable scene AND the anchor registry for
+ * cross-diagram linking.
+ *
+ * Non-linkable diagrams (pie, timeline, sankey, etc.) return an empty
+ * registry {}. Links referencing their nodes degrade gracefully (WARN + skip).
+ */
+export interface LayoutResult {
+    /** The fully resolved, renderable scene. */
+    readonly scene: Scene;
+    /**
+     * Node anchors in local diagram coordinates.
+     * Empty {} for non-linkable diagram types.
+     */
+    readonly anchors: NodeAnchorRegistry;
+    /**
+     * Port positions occupied by edges produced during this layout pass.
+     * The cross-link routing engine uses these to avoid stacking connectors
+     * on top of existing intra-diagram edges.
+     * Empty or absent for non-linkable diagram types.
+     */
+    readonly occupiedPorts?: readonly OccupiedPort[];
+}
+/**
+ * A soft layout constraint injected by the composition layer to bias
+ * a node's placement toward a specific boundary edge.
+ *
+ * Port hints enable Phase 2 negotiation: when a cross-link route has
+ * poor quality (crosses cells, excessive bends), the composition layer
+ * re-invokes the child layout with hints, nudging connected nodes
+ * toward the boundary facing their cross-link target.
+ *
+ * Hints are advisory — the layout engine should treat them as tie-breakers,
+ * not hard constraints. A hint with strength 0 is ignored; strength 1
+ * means "place this node as close to the specified side as possible
+ * without violating internal graph constraints."
+ */
+export interface PortHint {
+    /** The node ID to bias. */
+    readonly nodeId: string;
+    /** Which boundary edge to prefer. */
+    readonly preferredSide: CardinalSide;
+    /** Bias strength in [0, 1]. Default interpretation: 0 = ignore, 1 = maximum bias. */
+    readonly strength: number;
+}
+/**
+ * Optional layout constraints passed to a diagram layout engine
+ * during negotiation rounds.
+ *
+ * The base layout() call receives no options (first pass).
+ * Subsequent negotiation passes may include port hints derived from
+ * cross-link quality analysis.
+ */
+export interface LayoutOptions {
+    /** Port placement hints from the composition layer. */
+    readonly portHints?: readonly PortHint[];
+}
+//# sourceMappingURL=anchors.d.ts.map

package/dist/contracts/anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../../../../src/contracts/anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIxC,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC;AAIjE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAChC;AAID;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;AAMtE;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAClD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAC;IACrC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC1C"}

package/dist/contracts/crosslink.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Cross-Link
+ *
+ * Contracts for cross-diagram linking in poster compositions.
+ *
+ * Two constructs:
+ *   - CrossLink: a single directed/undirected edge between nodes in
+ *     different cells of a poster.
+ *   - Trace: a named, ordered, optionally-typed multi-hop path of
+ *     cross-links representing a logical thread (user journey,
+ *     requirement traceability, distributed request path).
+ *
+ * Cross-links are presentation-layer assertions on the composition.
+ * They do NOT modify any child diagram's IR or Scene — each cell
+ * compiles as if links don't exist. All resolution happens at
+ * composition time, after every cell has produced its LayoutResult.
+ *
+ * Dependency: primitives.ts, anchors.ts
+ */
+import type { Point, Color } from './primitives.js';
+import type { CardinalSide, NodeAnchor } from './anchors.js';
+import type { RouteStyle } from './routing.js';
+/**
+ * Address of a node across poster nesting levels.
+ *
+ * A flat poster uses a single-segment path: ["A1", "pay"]
+ *   → cell A1, node "pay"
+ *
+ * A nested poster uses multi-segment paths: ["A1", "B1", "db"]
+ *   → cell A1 (which is itself a poster), cell B1 within it, node "db"
+ *
+ * The last segment is always the node ID.
+ * All preceding segments are cell addresses traversed from the poster
+ * where the link is declared.
+ */
+export interface NodeAddress {
+    /** Ordered cell path from the declaring poster to the target cell. */
+    readonly cellPath: readonly string[];
+    /** Node ID within the target cell's diagram. */
+    readonly nodeId: string;
+}
+/** Visual style of a cross-diagram edge. */
+export type CrossLinkEdgeStyle = 'solid' | 'dashed' | 'dotted';
+/** Direction of a cross-diagram edge. */
+export type CrossLinkDirection = 'directed' | 'undirected' | 'bidirectional';
+/**
+ * A single cross-diagram edge between two nodes in different cells.
+ * This is the primitive — traces desugar into ordered sequences of these.
+ */
+export interface CrossLink {
+    /** Source endpoint address. */
+    readonly from: NodeAddress;
+    /** Target endpoint address. */
+    readonly to: NodeAddress;
+    readonly direction: CrossLinkDirection;
+    readonly style: CrossLinkEdgeStyle;
+    /** Optional label rendered at the route midpoint. */
+    readonly label?: string;
+    /**
+     * Geometric routing style for this edge.
+     * Defaults to 'orthogonal' when omitted.
+     */
+    readonly routing?: RouteStyle;
+    /**
+     * Optional hint for which wall to exit from the source node.
+     * When set, the routing engine skips all other srcWall candidates.
+     */
+    readonly exitWall?: CardinalSide;
+    /**
+     * Optional hint for which wall to enter the destination node.
+     * When set, the routing engine skips all other dstWall candidates.
+     */
+    readonly entryWall?: CardinalSide;
+    /**
+     * Animation applied to the rendered connector.
+     *
+     * 'march'    — marching ants (stroke-dashoffset cycle). Only visible when
+     *              the edge style is dashed or dotted; silently ignored on solid.
+     * 'particle' — a dot travels along the path. Works on any edge style.
+     * 'none'     — explicitly suppresses the default animation for this edge.
+     *
+     * When omitted the renderer applies defaults:
+     *   dashed → 'march', dotted → 'march', solid → no animation.
+     */
+    readonly animation?: 'march' | 'particle' | 'none';
+    /**
+     * If this link is part of a trace, the trace's ID.
+     * Used to apply consistent styling (colour, grouping) across trace members.
+     */
+    readonly traceId?: string;
+    /**
+     * Optional property bag for future per-link overrides (tension, color, etc.).
+     * Parsed from `{ key: value }` blocks in the syntax.
+     */
+    readonly props?: Readonly<Record<string, string | number>>;
+}
+/**
+ * Semantic type of a trace — what relationship the hops represent.
+ * Extensible; these are the built-in vocabulary from the design spec.
+ */
+export type TraceType = 'satisfies' | 'triggers' | 'calls' | 'reads' | 'writes' | 'extends' | 'custom';
+/**
+ * A named, ordered, optionally-typed multi-hop path of cross-diagram links.
+ *
+ * Traces desugar to atomic CrossLink[]s at composition time.
+ * The TraceRecord groups them under a name for consistent styling,
+ * legend display, and agent addressability.
+ */
+export interface TraceRecord {
+    /** Unique trace ID (auto-generated or author-specified). */
+    readonly id: string;
+    /** Human-readable name displayed in the legend. */
+    readonly name: string;
+    /** Optional semantic type governing the trace legend pill label. */
+    readonly type?: TraceType;
+    /**
+     * Ordered hop endpoints. Length N produces N-1 atomic links:
+     *   hops[0]→hops[1], hops[1]→hops[2], …, hops[N-2]→hops[N-1]
+     */
+    readonly hops: readonly NodeAddress[];
+    /** Resolved colour assigned at composition time from the categorical palette. */
+    readonly color?: Color;
+}
+/**
+ * A cross-link with both endpoints resolved to poster-space coordinates.
+ * Produced by the resolution pass; consumed by the routing pass.
+ */
+export interface ResolvedCrossLink {
+    readonly link: CrossLink;
+    /** Source anchor in poster coordinates. */
+    readonly fromAnchor: NodeAnchor;
+    /** Target anchor in poster coordinates. */
+    readonly toAnchor: NodeAnchor;
+    /** Selected port pair (minimises distance). */
+    readonly fromPort: Point;
+    readonly toPort: Point;
+    readonly fromSide: CardinalSide;
+    readonly toSide: CardinalSide;
+}
+/**
+ * Quality metrics for a computed cross-link route.
+ * Used by Phase 2 negotiation to decide whether to perturb layout.
+ */
+export interface RouteQuality {
+    /** Number of 90° bends in the route. */
+    readonly bends: number;
+    /** Total route length in px. */
+    readonly length: number;
+    /** Number of cell bounding boxes the route crosses through. */
+    readonly cellCrossings: number;
+    /**
+     * Ratio of actual route length to straight-line distance.
+     * 1.0 = perfectly direct. Higher = more detour.
+     */
+    readonly detourRatio: number;
+    /** Overall quality verdict. */
+    readonly acceptable: boolean;
+}
+/**
+ * A perturbation proposal generated by the quality analyser.
+ * The composition engine evaluates proposals and applies the best ones.
+ */
+export type PerturbationKind = 'expand-gutter' | 'swap-cells' | 'add-routing-bus' | 'port-hint';
+export interface Perturbation {
+    readonly kind: PerturbationKind;
+    /** Which cross-link triggered this proposal. */
+    readonly linkIndex: number;
+    /** Perturbation-specific payload. */
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=crosslink.d.ts.map

package/dist/contracts/crosslink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crosslink.d.ts","sourceRoot":"","sources":["../../../../src/contracts/crosslink.ts"],"names":[],"mappings":"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"}

package/dist/contracts/diagram.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Diagram
+ *
+ * The contract every diagram type must satisfy.
+ *
+ * Parsing and layout are defined as separate interfaces.
+ * This segregation matters:
+ *
+ *   DiagramParser<IR>       — knows how to turn text into an IR.
+ *                             Testable in isolation; no theme required.
+ *
+ *   DiagramLayoutEngine<IR> — knows how to turn an IR into a Scene.
+ *                             Testable in isolation with a fixture IR.
+ *
+ *   DiagramModule<IR>       — the full module: composes both.
+ *                             This is the type diagram directories export.
+ *
+ * Callers that only need to parse (e.g. a linter, a validator) depend on
+ * DiagramParser. Callers that only need to render a pre-built IR (e.g. a
+ * server receiving JSON) depend on DiagramLayoutEngine. The full pipeline
+ * depends on DiagramModule.
+ */
+import type { ResolvedTheme, ThemeInput } from './theme.js';
+import type { RawOverlay } from './overlay.js';
+import type { LayoutResult, LayoutOptions } from './anchors.js';
+/**
+ * The minimum shape every diagram IR must satisfy.
+ *
+ * All diagram-specific IR interfaces extend BaseIR. This ensures:
+ *   - Every IR carries uniform metadata (version, title, etc.)
+ *   - Every IR can carry overlays (notes, legends) without the pipeline
+ *     needing to know the concrete diagram type.
+ *   - Every IR can express per-diagram theme overrides parsed from
+ *     frontmatter, applied by the pipeline before layout() is called.
+ */
+export interface BaseIR {
+    readonly version: string;
+    readonly metadata: {
+        readonly [key: string]: unknown;
+    };
+    /** Overlays declared in the diagram source (notes, legends). */
+    readonly overlays?: readonly RawOverlay[];
+    /**
+     * Per-diagram theme overrides parsed from frontmatter.
+     * Applied on top of global theme + module defaults before layout().
+     */
+    readonly themeOverride?: ThemeInput;
+}
+export interface DiagramParser<IR extends BaseIR> {
+    /**
+     * Parse Mermaid-syntax text into the canonical IR.
+     * Throws a descriptive error on invalid input.
+     */
+    parseMermaid(input: string): IR;
+    /**
+     * Validate and parse YAML text into the canonical IR.
+     * Throws a descriptive error on invalid or schema-violating input.
+     */
+    parseYaml(input: string): IR;
+}
+export interface DiagramLayoutEngine<IR extends BaseIR> {
+    /**
+     * Transform a validated IR into a fully resolved, renderable LayoutResult.
+     *
+     * Returns both the renderable Scene and the node anchor registry.
+     * Non-linkable diagram types return an empty anchors registry {}.
+     *
+     * Synchronous: every Triton layout engine computes its geometry in-process
+     * with no deferred work (no font-metric I/O, no WASM, no fetching). Keeping
+     * layout sync lets the frontend expose a synchronous render path
+     * (renderSync) for hosts that need it (e.g. the markdown-it preview plugin),
+     * while the async render() wrapper remains for existing callers.
+     *
+     * The returned Scene is complete — all overlay geometry has been
+     * incorporated into Scene.elements before it is returned.
+     *
+     * @param options - Optional layout constraints (port hints) from the
+     *   composition layer during negotiation passes. Absent on first pass.
+     */
+    layout(ir: IR, theme: ResolvedTheme, options?: LayoutOptions): LayoutResult;
+}
+/**
+ * The complete diagram module interface — parsing and layout together.
+ * Every src/diagrams/<type>/index.ts exports a value satisfying this.
+ */
+export interface DiagramModule<IR extends BaseIR> extends DiagramParser<IR>, DiagramLayoutEngine<IR> {
+    /**
+     * Optional per-diagram theme defaults.
+     * Applied on top of the global theme but below ir.themeOverride:
+     *
+     *   result = global ← defaultThemeOverride ← ir.themeOverride
+     */
+    readonly defaultThemeOverride?: ThemeInput;
+}
+/**
+ * The exhaustive set of diagram types recognised by Triton.
+ *
+ * This is the single source of truth for valid diagram kind strings.
+ * The frontend detector, the CLI, and the API all narrow to this type.
+ *
+ * Adding a new diagram type requires adding it here first — before any
+ * implementation exists. This makes the set of intended diagrams explicit.
+ */
+export type DiagramKind = 'flowchart' | 'timeline' | 'poster' | 'sequence' | 'mindmap' | 'state' | 'class' | 'er' | 'gantt' | 'c4' | 'sankey' | 'kanban' | 'requirement' | 'gitgraph' | 'packet' | 'block' | 'architecture' | 'pie' | 'xychart' | 'quadrant' | 'radar' | 'journey' | 'tree' | 'plan' | 'avl' | 'rbtree' | 'btree' | 'radix' | 'segtree' | 'heap' | 'array' | 'linkedlist' | 'memory' | 'page' | 'queue' | 'cqueue' | 'deque' | 'pqueue' | 'stack' | 'hashmap' | 'matrix' | 'trie' | 'nodegraph' | 'unionfind' | 'topology';
+/** The two input formats Triton accepts. */
+export type InputFormat = 'mermaid' | 'yaml';
+//# sourceMappingURL=diagram.d.ts.map

package/dist/contracts/diagram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram.d.ts","sourceRoot":"","sources":["../../../../src/contracts/diagram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIhE;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACvD,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC;CACrC;AAID,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,MAAM;IAC9C;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,CAAC;IAEhC;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,CAAC;CAC9B;AAID,MAAM,WAAW,mBAAmB,CAAC,EAAE,SAAS,MAAM;IACpD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;CAC7E;AAID;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,MAAM,CAAE,SAAQ,aAAa,CAAC,EAAE,CAAC,EAAE,mBAAmB,CAAC,EAAE,CAAC;IAClG;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,UAAU,CAAC;CAC5C;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,GACV,SAAS,GACT,OAAO,GACP,OAAO,GACP,IAAI,GACJ,OAAO,GACP,IAAI,GACJ,QAAQ,GACR,QAAQ,GACR,aAAa,GACb,UAAU,GACV,QAAQ,GACR,OAAO,GACP,cAAc,GACd,KAAK,GACL,SAAS,GACT,UAAU,GACV,OAAO,GACP,SAAS,GACT,MAAM,GACN,MAAM,GACN,KAAK,GACL,QAAQ,GACR,OAAO,GACP,OAAO,GACP,SAAS,GACT,MAAM,GACN,OAAO,GACP,YAAY,GACZ,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,QAAQ,GACR,MAAM,GACN,WAAW,GACX,WAAW,GACX,UAAU,CAAC;AAEf,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC"}

package/dist/contracts/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Contracts — barrel re-export.
+ *
+ * Import everything from here. Do not import directly from sub-files
+ * outside the contracts/ directory.
+ *
+ * Dependency order (each file imports only from files above it):
+ *
+ *   primitives   (no deps)
+ *   scene        ← primitives
+ *   theme        ← primitives
+ *   overlay      ← primitives
+ *   routing      ← primitives
+ *   result       (no deps)
+ *   renderer     ← scene
+ *   diagram      ← scene, theme, overlay
+ */
+export type { Point, Size, Rect, Color, FontFamily, TextAnchor, FontWeight, } from './primitives.js';
+export type { SceneRect, SceneCircle, ScenePath, SceneText, SceneGroup, SceneElement, Scene, } from './scene.js';
+export type { ThemePalette, ThemeTypography, ThemeSpacing, ThemeEdges, ThemePanel, ResolvedTheme, ThemeInput, } from './theme.js';
+export type { RawNote, RawLegend, RawOverlay, LegendCorner, LegendEntry, Legend, Annotation, CompiledOverlays, } from './overlay.js';
+export type { RouteStyle, PortDirection, RouteRequest, Route, Router, } from './routing.js';
+export type { DiagramParser, DiagramLayoutEngine, DiagramModule, DiagramKind, InputFormat, BaseIR, } from './diagram.js';
+export type { DiagramErrorCode, DiagramError, Result, } from './result.js';
+export { ok, err } from './result.js';
+export type { Renderer } from './renderer.js';
+export type { CardinalSide, CardinalPorts, NodeAnchor, NodeAnchorRegistry, OccupiedPort, LayoutResult, PortHint, LayoutOptions, } from './anchors.js';
+export type { NodeAddress, CrossLinkEdgeStyle, CrossLinkDirection, CrossLink, TraceType, TraceRecord, ResolvedCrossLink, RouteQuality, PerturbationKind, Perturbation, } from './crosslink.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,YAAY,EACV,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,UAAU,EACV,UAAU,EACV,UAAU,GACX,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,SAAS,EACT,UAAU,EACV,YAAY,EACZ,KAAK,GACN,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,OAAO,EACP,SAAS,EACT,UAAU,EACV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,UAAU,EACV,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,KAAK,EACL,MAAM,GACP,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,WAAW,EACX,MAAM,GACP,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,MAAM,GACP,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAEtC,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,YAAY,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC"}

package/dist/contracts/overlay.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Overlay
+ *
+ * Contracts for diagram annotations and legends.
+ *
+ * This file defines two layers:
+ *
+ *   RAW layer  — types emitted by PEG grammars. These are structural captures
+ *                of the overlay syntax, not yet positioned or resolved.
+ *
+ *   RESOLVED layer — types consumed by layout engines and the overlay pipeline.
+ *                    These have fully specified positions and anchor references.
+ *
+ * The separation matters: grammars produce Raw types; the overlay compiler
+ * (implementation, not defined here) converts Raw → Resolved; layout engines
+ * incorporate Resolved overlays into the final Scene geometry.
+ *
+ * Neither layer appears on the Scene type — overlays are fully resolved into
+ * SceneElement[]s before a Scene is returned from layout().
+ */
+import type { Point } from './primitives.js';
+/**
+ * A note/annotation directive as captured verbatim by a grammar rule.
+ * The target is an element label or ID — not yet a screen coordinate.
+ */
+export interface RawNote {
+    readonly type: 'note';
+    readonly text: string;
+    /** Element ID or label this note is anchored to. */
+    readonly target: string;
+    /** Optional pixel offset from the anchor, e.g. to avoid overlap. */
+    readonly offset?: {
+        readonly dx: number;
+        readonly dy: number;
+    };
+}
+/**
+ * A legend block directive as captured verbatim by a grammar rule.
+ * Corner is a raw string — the overlay compiler validates and narrows it.
+ */
+export interface RawLegend {
+    readonly type: 'legend';
+    readonly corner: string;
+    readonly title?: string;
+    readonly entries: ReadonlyArray<{
+        readonly key: string;
+        readonly value: string;
+    }>;
+}
+/** Union of every overlay directive a grammar can emit. */
+export type RawOverlay = RawNote | RawLegend;
+/** The four corners a legend may occupy. */
+export type LegendCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export interface LegendEntry {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * A resolved legend block — position is determined by the layout engine
+ * relative to the diagram's viewBox using the corner property.
+ */
+export interface Legend {
+    readonly title?: string;
+    readonly entries: ReadonlyArray<LegendEntry>;
+    readonly corner: LegendCorner;
+    /** Width override in px. Auto-sized to content if absent. */
+    readonly width?: number;
+}
+/**
+ * A resolved annotation — a callout box with a connector to an anchor.
+ *
+ * Position is the top-left of the callout box.
+ * Anchor is either a resolved screen point or an element group ID that
+ * the overlay layout engine will resolve at render time.
+ */
+export interface Annotation {
+    readonly id: string;
+    readonly text: string;
+    /** Top-left corner of the annotation box in diagram coordinates. */
+    readonly position: Point;
+    /** What the connector line points to. */
+    readonly anchor: {
+        readonly elementId: string;
+    } | {
+        readonly point: Point;
+    };
+    /** Width override in px. Auto-sized to content if absent. */
+    readonly width?: number;
+}
+/**
+ * The fully compiled set of overlays for a diagram.
+ * Produced by the overlay compiler from RawOverlay[].
+ */
+export interface CompiledOverlays {
+    readonly annotations: ReadonlyArray<Annotation>;
+    readonly legend?: Legend;
+}
+//# sourceMappingURL=overlay.d.ts.map

package/dist/contracts/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../../src/contracts/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAI7C;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAChE;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnF;AAED,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAI7C,4CAA4C;AAC5C,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,CAAC;AAErF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;IAC5E,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/contracts/primitives.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Primitives
+ *
+ * Foundational geometric and visual value types.
+ * These are the atoms of the rendering coordinate system.
+ *
+ * Rules for this file:
+ *   - No imports from anywhere in the project.
+ *   - No functions, classes, or values — types only.
+ *   - Every other contract file may import from here; nothing here imports upward.
+ */
+/** A 2D point in SVG coordinate space (origin top-left, y grows downward). */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** A width × height pair. */
+export interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * An axis-aligned bounding box — position + size combined.
+ * Extends both Point and Size so callers can destructure either way.
+ */
+export interface Rect extends Point, Size {
+}
+/**
+ * A CSS color string — hex, rgb(), hsl(), named color, etc.
+ * Opaque alias: the type system trusts the caller to provide a valid value.
+ */
+export type Color = string;
+/**
+ * A CSS font-family string (may include fallback stack).
+ * Opaque alias: conveys intent without runtime validation overhead.
+ */
+export type FontFamily = string;
+/** Horizontal text alignment in SVG terms. */
+export type TextAnchor = 'start' | 'middle' | 'end';
+/** Font weight values supported by the renderer. */
+export type FontWeight = 'normal' | 'bold';
+//# sourceMappingURL=primitives.d.ts.map

package/dist/contracts/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../../src/contracts/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,6BAA6B;AAC7B,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,IAAK,SAAQ,KAAK,EAAE,IAAI;CAAG;AAI5C;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,8CAA8C;AAC9C,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEpD,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC"}

package/dist/contracts/renderer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Renderer
+ *
+ * Output-format contract. A Renderer transforms a resolved Scene into a
+ * specific output format (SVG string, PNG buffer, Canvas draw calls…).
+ *
+ * Renderers are registered by name via the render registry. The default
+ * renderer is 'svg'. Third-party output formats register themselves with
+ * registerRenderer().
+ *
+ * Renderers know nothing about diagram types, themes, or IR shapes — they
+ * consume only Scene, which is the universal render-ready representation.
+ */
+import type { Scene } from './scene.js';
+export interface Renderer<Output = string> {
+    /** Unique name used for renderer lookup, e.g. 'svg', 'png', 'canvas'. */
+    readonly name: string;
+    /** Transform a fully resolved Scene into the target output format. */
+    render(scene: Scene): Output;
+}
+//# sourceMappingURL=renderer.d.ts.map

package/dist/contracts/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../../src/contracts/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,QAAQ,CAAC,MAAM,GAAG,MAAM;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sEAAsE;IACtE,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;CAC9B"}