@markdy/core 0.8.11 → 0.8.13

package/README.md

@@ -6,7 +6,8 @@ The parser and AST types for [MarkdyScript](../../docs/SYNTAX.md) — a diagram-
 
 - **Zero runtime dependencies** — pure TypeScript, no DOM or platform APIs
 - **Single-pass parser** — line-by-line state machine with strict `ParseError` diagnostics
-- **Diagram-native grammar** — scene metadata, architecture nodes, groups, styles, beats, flow chains, and reusable patterns
+- **Diagram-native grammar** — scene metadata, architecture nodes, groups, styles, beats, flow chains, annotations, visual primitives, and reusable patterns
+- **Focused modes** — `architecture`, `flowchart`, `tree`, `state`, `sequence`, and `constellation` compile into deterministic render-plan metadata
 - **Isomorphic** — runs in Node.js, Deno, Bun, edge runtimes, and the browser
 
 ## Installation
@@ -66,12 +67,12 @@ try {
 | `parseAndCompile` | `(source) => { ast, plan }` | Parse and compile in one call |
 | `ParseError` | class | Error with `.line` number for diagnostics |
 | `DiagramAST` | type | Parsed scene: meta, nodes, edges, groups, patterns, beats |
-| `RenderPlan` | type | Positioned nodes, routed edges, timed cues, beat ranges |
+| `RenderPlan` | type | Positioned nodes, routed edges, group zones, sequence messages, timed cues, beat ranges |
 | `SceneMeta` | type | Scene configuration (width, height, fps, theme, direction) |
 | `NodeDecl` | type | Node declaration (kind, id, label, style) |
 | `EdgeDecl` | type | Edge declaration (kind, from, to, label) |
 | `BeatDecl` | type | Named beat with cues |
-| `THEMES` / `resolveTheme` | tokens | Semantic theme palettes (`paper`, `midnight`, `blueprint`, `graphite`) |
+| `THEMES` / `resolveTheme` | tokens | Semantic theme palettes (`paper`, `editorial`, `nebula`, `midnight`, `blueprint`, `graphite`) |
 
 ## Documentation
 

package/dist/index.d.ts

@@ -4,6 +4,8 @@
  */
 type LayoutDirection = "LR" | "RL" | "TB" | "BT";
 type EdgeKind = "request" | "response" | "event" | "dependency";
+type DiagramType = "architecture" | "flowchart" | "tree" | "state" | "sequence" | "constellation";
+type NodeShape = "card" | "rounded" | "diamond" | "circle" | "pill" | "terminal";
 type SceneMeta = {
     title?: string;
     width: number;
@@ -12,6 +14,8 @@ type SceneMeta = {
     theme: string;
     direction: LayoutDirection;
     duration?: number;
+    /** Opt-in diagram mode; defaults to architecture. */
+    type?: DiagramType;
 };
 type NodeDecl = {
     kind: string;
@@ -37,6 +41,14 @@ type GroupDecl = {
     props: Record<string, unknown>;
     line: number;
 };
+type AnnotationDecl = {
+    id: string;
+    text: string;
+    target?: string;
+    position?: string;
+    props: Record<string, unknown>;
+    line: number;
+};
 type StyleDecl = {
     name: string;
     props: Record<string, unknown>;
@@ -118,6 +130,7 @@ type DiagramAST = {
     nodes: Record<string, NodeDecl>;
     edges: EdgeDecl[];
     groups: Record<string, GroupDecl>;
+    annotations: AnnotationDecl[];
     patterns: Record<string, PatternDecl>;
     beats: BeatDecl[];
     diagnostics: Diagnostic[];
@@ -134,6 +147,17 @@ type ThemeTokens = {
     gridMajor: string;
     vignette: string;
     accent: string;
+    /** HTTP / external link accent (editorial skin). */
+    link?: string;
+    /** Semantic editorial aliases for canvas/text/muted/border roles. */
+    paper?: string;
+    ink?: string;
+    muted?: string;
+    rule?: string;
+    /** Tertiary caption color. */
+    soft?: string;
+    /** Focal node fill tint. */
+    accentTint?: string;
     /** Node card fill (falls back to surface derivations when omitted). */
     nodeSurface?: string;
     nodeSurfaceRaised?: string;
@@ -143,8 +167,23 @@ type ThemeTokens = {
     shadow?: string;
     /** Edge label pill fill. */
     labelPlate?: string;
+    /** Editorial: flat cards without drop shadows. */
+    flatCards?: boolean;
     roles: Record<string, string>;
     edges: Record<EdgeKind, string>;
+    fonts?: {
+        title?: string;
+        nodeName?: string;
+        mono?: string;
+    };
+    radiusMd?: number;
+    spacing?: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    };
 };
 type PositionedNode = {
     id: string;
@@ -158,6 +197,10 @@ type PositionedNode = {
     style?: Record<string, unknown>;
     props?: Record<string, unknown>;
     opacity: number;
+    shape?: NodeShape;
+    focal?: boolean;
+    /** Sequence mode column index. */
+    column?: number;
 };
 type RoutedEdge = {
     id: string;
@@ -165,6 +208,48 @@ type RoutedEdge = {
     from: string;
     to: string;
     label?: string;
+    /** Declared via top-level `edge` (not only flow cues). */
+    structural?: boolean;
+    selfLoop?: boolean;
+};
+type GroupBoundary = {
+    id: string;
+    label?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    memberIds: string[];
+    props?: Record<string, unknown>;
+};
+type SequenceMessage = {
+    id: string;
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    label?: string;
+    y: number;
+    start: number;
+    duration: number;
+    beat: string;
+};
+type SequenceActivation = {
+    id: string;
+    participant: string;
+    y: number;
+    height: number;
+    start: number;
+    duration: number;
+};
+type TreeBus = {
+    id: string;
+    parentId: string;
+    childIds: string[];
+    parentX: number;
+    parentY: number;
+    branchY: number;
+    childXs: number[];
+    childY: number;
 };
 type TimedCue = {
     start: number;
@@ -186,11 +271,17 @@ type RenderPlan = {
     meta: SceneMeta;
     theme: ThemeTokens;
     title: string;
+    diagramType: DiagramType;
     nodes: PositionedNode[];
     edges: RoutedEdge[];
+    groupBoundaries: GroupBoundary[];
+    annotations: AnnotationDecl[];
     cues: TimedCue[];
     beats: BeatRange[];
     groups: Record<string, string[]>;
+    treeBuses: TreeBus[];
+    sequenceMessages: SequenceMessage[];
+    sequenceActivations: SequenceActivation[];
     duration: number;
 };
 
@@ -221,6 +312,7 @@ declare const THEMES: Record<string, ThemeTokens>;
 declare function resolveTheme(name: string): ThemeTokens;
 
 declare const NODE_KINDS: Set<string>;
+declare const DIAGRAM_TYPES: Set<string>;
 declare const EDGE_OPERATORS: Record<string, "request" | "response" | "event" | "dependency">;
 /** Natural-language cue synonyms that AIs reach for, mapped to real cues. */
 declare const CUE_ALIASES: Record<string, string>;
@@ -236,4 +328,4 @@ declare const TECHNICAL_NODE_TYPES: readonly ["service", "api", "microservice",
 declare const VISUAL_PRIMITIVE_TYPES: readonly ["panel", "surface", "terminal", "metric", "stat", "grid", "matrix", "lane", "track", "marker", "dot", "token_strip", "chips", "glyph_card", "glyph"];
 declare const TECHNICAL_NODE_KINDS: Record<(typeof TECHNICAL_NODE_TYPES)[number], string>;
 
-export { BEAT_CUE_KEYWORDS, type BeatDecl, type BeatRange, CUE_ALIASES, type Cue, type Diagnostic, type DiagramAST, EDGE_OPERATORS, type EdgeDecl, type EdgeKind, type FlowSegment, type GroupDecl, type LayoutDirection, NODE_ALIASES, NODE_KINDS, type NodeDecl, ParseError, type ParseOptions, type ParseResult, type PatternDecl, type PositionedNode, type RenderPlan, type RoutedEdge, SCENE_KEYS, type SceneMeta, type StyleDecl, TECHNICAL_NODE_KINDS, TECHNICAL_NODE_TYPES, THEMES, type ThemeTokens, type TimedCue, VISUAL_PRIMITIVE_TYPES, canonicalNodeKind, compile, compilePlan, humanizeId, nodeRole, parse, parseAndCompile, resolveTheme };
+export { type AnnotationDecl, BEAT_CUE_KEYWORDS, type BeatDecl, type BeatRange, CUE_ALIASES, type Cue, DIAGRAM_TYPES, type Diagnostic, type DiagramAST, type DiagramType, EDGE_OPERATORS, type EdgeDecl, type EdgeKind, type FlowSegment, type GroupBoundary, type GroupDecl, type LayoutDirection, NODE_ALIASES, NODE_KINDS, type NodeDecl, type NodeShape, ParseError, type ParseOptions, type ParseResult, type PatternDecl, type PositionedNode, type RenderPlan, type RoutedEdge, SCENE_KEYS, type SceneMeta, type SequenceActivation, type SequenceMessage, type StyleDecl, TECHNICAL_NODE_KINDS, TECHNICAL_NODE_TYPES, THEMES, type ThemeTokens, type TimedCue, type TreeBus, VISUAL_PRIMITIVE_TYPES, canonicalNodeKind, compile, compilePlan, humanizeId, nodeRole, parse, parseAndCompile, resolveTheme };

package/dist/index.js

@@ -178,6 +178,23 @@ var VISUAL_PRIMITIVE_TYPES = [
   "glyph_card",
   "glyph"
 ];
+var VISUAL_PRIMITIVE_KINDS = {
+  panel: "flow",
+  surface: "flow",
+  terminal: "flow",
+  metric: "observability",
+  stat: "observability",
+  grid: "flow",
+  matrix: "flow",
+  lane: "flow",
+  track: "flow",
+  marker: "flow",
+  dot: "flow",
+  token_strip: "flow",
+  chips: "flow",
+  glyph_card: "flow",
+  glyph: "flow"
+};
 var TECHNICAL_NODE_KINDS = {
   service: "compute",
   api: "compute",
@@ -342,7 +359,18 @@ var TECHNICAL_NODE_KINDS = {
 };
 
 // src/registry.ts
-var NODE_KINDS = new Set(TECHNICAL_NODE_TYPES);
+var NODE_KINDS = /* @__PURE__ */ new Set([
+  ...TECHNICAL_NODE_TYPES,
+  ...VISUAL_PRIMITIVE_TYPES
+]);
+var DIAGRAM_TYPES = /* @__PURE__ */ new Set([
+  "architecture",
+  "flowchart",
+  "tree",
+  "state",
+  "sequence",
+  "constellation"
+]);
 var EDGE_OPERATORS = {
   "->": "request",
   "<-": "response",
@@ -364,9 +392,19 @@ var BEAT_CUE_KEYWORDS = /* @__PURE__ */ new Set([
   "use",
   ...Object.keys(CUE_ALIASES)
 ]);
-var SCENE_KEYS = /* @__PURE__ */ new Set(["width", "height", "fps", "theme", "duration", "direction", "layout"]);
+var SCENE_KEYS = /* @__PURE__ */ new Set([
+  "width",
+  "height",
+  "fps",
+  "theme",
+  "duration",
+  "direction",
+  "layout",
+  "type"
+]);
 function nodeRole(kind) {
-  return TECHNICAL_NODE_KINDS[kind] ?? "compute";
+  const canonical = canonicalNodeKind(kind);
+  return TECHNICAL_NODE_KINDS[canonical] ?? VISUAL_PRIMITIVE_KINDS[canonical] ?? "compute";
 }
 function humanizeId(id) {
   const acronyms = /* @__PURE__ */ new Set(["api", "cdn", "db", "dns", "http", "https", "id", "jwt", "oidc", "sdk", "tls", "ui", "url"]);
@@ -388,7 +426,14 @@ var NODE_ALIASES = {
   gateway: "api_gateway",
   mq: "queue",
   k8s: "cluster",
-  lb: "load_balancer"
+  lb: "load_balancer",
+  panel: "surface",
+  metric: "stat",
+  grid: "matrix",
+  lane: "track",
+  marker: "dot",
+  chips: "token_strip",
+  glyph: "glyph_card"
 };
 function canonicalNodeKind(kind) {
   return NODE_ALIASES[kind] ?? kind;
@@ -399,6 +444,7 @@ var SAFE = 44;
 var TITLE_BAND = 76;
 var NODE_W = 168;
 var NODE_H = 72;
+var GROUP_PAD = 24;
 var DEFAULTS = {
   show: 0.35,
   hide: 0.35,
@@ -410,20 +456,47 @@ var DEFAULTS = {
   cueGap: 0.08,
   stagger: 0.06
 };
+function diagramType(ast) {
+  return ast.meta.type ?? "architecture";
+}
+function nodeShape(kind, dtype) {
+  if (kind === "terminal") return "terminal";
+  if (kind === "dot" || kind === "marker") return "circle";
+  if (kind === "token_strip" || kind === "chips") return "pill";
+  if (kind === "surface" || kind === "stat" || kind === "matrix" || kind === "track" || kind === "glyph_card") return "rounded";
+  if (dtype === "constellation") return "rounded";
+  if (dtype === "flowchart") {
+    if (kind === "start" || kind === "end") return "pill";
+    if (kind === "decision" || kind === "condition") return "diamond";
+  }
+  if (dtype === "state" && kind === "state") return "rounded";
+  if (kind === "user" || kind === "client") return "rounded";
+  return "card";
+}
 function collectStructuralEdges(ast) {
-  const edges = [...ast.edges.map((e) => ({
+  const edges = ast.edges.map((e) => ({
     id: e.id,
     kind: e.kind,
     from: e.from,
     to: e.to,
-    label: e.label
-  }))];
+    label: e.label,
+    structural: true,
+    selfLoop: e.from === e.to
+  }));
   let counter = edges.length;
   for (const beat of ast.beats) {
     for (const cue of beat.cues) {
       collectFlowSegments(cue, (seg) => {
         const id = `flow_${++counter}`;
-        edges.push({ id, kind: seg.op, from: seg.from, to: seg.to, label: seg.label });
+        edges.push({
+          id,
+          kind: seg.op,
+          from: seg.from,
+          to: seg.to,
+          label: seg.label,
+          structural: false,
+          selfLoop: seg.from === seg.to
+        });
       });
     }
   }
@@ -442,7 +515,7 @@ function dedupeEdges(edges) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const e of edges) {
-    const k = `${e.from}|${e.kind}|${e.to}|${e.label ?? ""}`;
+    const k = `${e.from}|${e.kind}|${e.to}|${e.label ?? ""}|${e.structural ? "s" : "f"}`;
     if (seen.has(k)) continue;
     seen.add(k);
     out.push(e);
@@ -452,7 +525,7 @@ function dedupeEdges(edges) {
 function assignRanks(nodeIds, edges, direction) {
   const ranks = /* @__PURE__ */ new Map();
   for (const id of nodeIds) ranks.set(id, 0);
-  const forward = edges.filter((e) => e.kind !== "response");
+  const forward = edges.filter((e) => e.kind !== "response" && !e.selfLoop);
   for (let sweep = 0; sweep < nodeIds.length; sweep++) {
     let changed = false;
     for (const e of forward) {
@@ -470,9 +543,14 @@ function assignRanks(nodeIds, edges, direction) {
   }
   return ranks;
 }
-function layoutNodes(ast, edges) {
+function snapGrid(n) {
+  return Math.round(n / 8) * 8;
+}
+function layoutRanked(ast, edges, opts) {
   const nodeIds = Object.keys(ast.nodes);
-  const ranks = assignRanks(nodeIds, edges, ast.meta.direction);
+  const dtype = diagramType(ast);
+  const direction = opts.forceVertical ? "TB" : ast.meta.direction;
+  const ranks = assignRanks(nodeIds, edges, direction);
   const byRank = /* @__PURE__ */ new Map();
   for (const id of nodeIds) {
     const r = ranks.get(id) ?? 0;
@@ -480,7 +558,7 @@ function layoutNodes(ast, edges) {
     byRank.get(r).push(id);
   }
   for (const ids of byRank.values()) ids.sort();
-  const isVertical = ast.meta.direction === "TB" || ast.meta.direction === "BT";
+  const isVertical = direction === "TB" || direction === "BT";
   const contentW = ast.meta.width - SAFE * 2;
   const contentH = ast.meta.height - SAFE - TITLE_BAND - SAFE;
   const maxRank = Math.max(...byRank.keys(), 0);
@@ -488,45 +566,251 @@ function layoutNodes(ast, edges) {
   const nodes = [];
   for (const [rank, ids] of [...byRank.entries()].sort((a, b) => a[0] - b[0])) {
     const rowCount = ids.length;
-    ids.forEach((id, idx) => {
+    const orderedIds = opts.columnLayout ? nodeIds.filter((id) => ids.includes(id)) : [...ids].sort();
+    orderedIds.forEach((id, idx) => {
       const decl = ast.nodes[id];
       const role = nodeRole(decl.kind);
       let x;
       let y;
-      if (isVertical) {
+      if (opts.columnLayout) {
+        x = SAFE + contentW / (rowCount + 1) * (idx + 1) - NODE_W / 2;
+        y = TITLE_BAND + 48;
+      } else if (isVertical) {
         x = SAFE + contentW / (rowCount + 1) * (idx + 1) - NODE_W / 2;
         y = TITLE_BAND + contentH / Math.max(rankCount, 1) * rank + (contentH / Math.max(rankCount, 1) - NODE_H) / 2;
       } else {
         x = SAFE + contentW / Math.max(rankCount, 1) * rank + (contentW / Math.max(rankCount, 1) - NODE_W) / 2;
         y = TITLE_BAND + contentH / (rowCount + 1) * (idx + 1) - NODE_H / 2;
       }
-      x = Math.round(x / 8) * 8;
-      y = Math.round(y / 8) * 8;
-      const style = decl.style ? ast.styles[decl.style]?.props : void 0;
+      const focal = decl.props.focal === true || decl.props.accent === true;
       nodes.push({
         id,
         kind: decl.kind,
         role,
         label: decl.label,
-        x,
-        y,
+        x: snapGrid(x),
+        y: snapGrid(y),
+        width: NODE_W,
+        height: NODE_H,
+        style: decl.style ? ast.styles[decl.style]?.props : void 0,
+        props: decl.props,
+        opacity: 0,
+        shape: nodeShape(decl.kind, dtype),
+        focal,
+        column: opts.columnLayout ? idx : void 0
+      });
+    });
+  }
+  return nodes;
+}
+function layoutTree(ast, edges) {
+  const nodeIds = Object.keys(ast.nodes);
+  const children = /* @__PURE__ */ new Map();
+  const parent = /* @__PURE__ */ new Map();
+  for (const id of nodeIds) children.set(id, []);
+  for (const e of edges) {
+    if (e.kind === "response" || e.selfLoop) continue;
+    if (!ast.nodes[e.from] || !ast.nodes[e.to]) continue;
+    if (parent.has(e.to)) continue;
+    parent.set(e.to, e.from);
+    children.get(e.from).push(e.to);
+  }
+  const root = nodeIds.find((id) => !parent.has(id)) ?? nodeIds[0];
+  const depth = /* @__PURE__ */ new Map();
+  const queue = [root];
+  depth.set(root, 0);
+  while (queue.length) {
+    const id = queue.shift();
+    for (const child of children.get(id) ?? []) {
+      if (depth.has(child)) continue;
+      depth.set(child, (depth.get(id) ?? 0) + 1);
+      queue.push(child);
+    }
+  }
+  for (const id of nodeIds) if (!depth.has(id)) depth.set(id, 0);
+  const byDepth = /* @__PURE__ */ new Map();
+  for (const id of nodeIds) {
+    const d = depth.get(id) ?? 0;
+    if (!byDepth.has(d)) byDepth.set(d, []);
+    byDepth.get(d).push(id);
+  }
+  for (const ids of byDepth.values()) ids.sort();
+  const contentW = ast.meta.width - SAFE * 2;
+  const contentH = ast.meta.height - SAFE - TITLE_BAND - SAFE;
+  const maxDepth = Math.max(...byDepth.keys(), 0);
+  const nodes = [];
+  for (const [d, ids] of [...byDepth.entries()].sort((a, b) => a[0] - b[0])) {
+    ids.forEach((id, idx) => {
+      const decl = ast.nodes[id];
+      const x = SAFE + contentW / (ids.length + 1) * (idx + 1) - NODE_W / 2;
+      const y = TITLE_BAND + contentH / Math.max(maxDepth + 1, 1) * d + 24;
+      nodes.push({
+        id,
+        kind: decl.kind,
+        role: nodeRole(decl.kind),
+        label: decl.label,
+        x: snapGrid(x),
+        y: snapGrid(y),
         width: NODE_W,
         height: NODE_H,
-        style,
+        style: decl.style ? ast.styles[decl.style]?.props : void 0,
         props: decl.props,
-        opacity: 0
+        opacity: 0,
+        shape: "card"
       });
     });
   }
   return nodes;
 }
-function resolveTargets(targets, ast, groups) {
+function cycleSafeEdges(nodeIds, edges) {
+  const outgoing = /* @__PURE__ */ new Map();
+  const incoming = /* @__PURE__ */ new Set();
+  for (const id of nodeIds) outgoing.set(id, []);
+  for (const edge of edges) {
+    if (edge.kind === "response" || edge.selfLoop) continue;
+    if (!outgoing.has(edge.from) || !outgoing.has(edge.to)) continue;
+    outgoing.get(edge.from).push(edge);
+    incoming.add(edge.to);
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const safe = [];
+  const visit = (id) => {
+    if (visited.has(id)) return;
+    visited.add(id);
+    for (const edge of outgoing.get(id) ?? []) {
+      if (visited.has(edge.to)) continue;
+      safe.push(edge);
+      visit(edge.to);
+    }
+  };
+  for (const id of nodeIds) {
+    if (!incoming.has(id)) visit(id);
+  }
+  for (const id of nodeIds) visit(id);
+  return safe;
+}
+function layoutConstellation(ast) {
+  const nodeIds = Object.keys(ast.nodes);
+  if (nodeIds.length === 0) return [];
+  const incoming = /* @__PURE__ */ new Set();
+  for (const edge of ast.edges) {
+    if (edge.kind !== "response" && edge.from !== edge.to && ast.nodes[edge.to]) incoming.add(edge.to);
+  }
+  const focalId = nodeIds.find((id) => ast.nodes[id].props.focal === true || ast.nodes[id].props.accent === true) ?? nodeIds.find((id) => !incoming.has(id)) ?? nodeIds[0];
+  const contentW = ast.meta.width - SAFE * 2;
+  const contentH = ast.meta.height - SAFE - TITLE_BAND - SAFE;
+  const centerX = SAFE + contentW / 2 - NODE_W / 2;
+  const centerY = TITLE_BAND + contentH / 2 - NODE_H / 2;
+  const orbitIds = nodeIds.filter((id) => id !== focalId);
+  const radiusX = Math.max(140, contentW / 2 - NODE_W / 2 - SAFE);
+  const radiusY = Math.max(120, contentH / 2 - NODE_H / 2 - SAFE);
+  const nodes = [];
+  for (const id of nodeIds) {
+    const decl = ast.nodes[id];
+    const isFocal = id === focalId;
+    const index = orbitIds.indexOf(id);
+    const angle = orbitIds.length > 0 ? -Math.PI / 2 + index * Math.PI * 2 / orbitIds.length : 0;
+    const x = isFocal ? centerX : SAFE + contentW / 2 + Math.cos(angle) * radiusX - NODE_W / 2;
+    const y = isFocal ? centerY : TITLE_BAND + contentH / 2 + Math.sin(angle) * radiusY - NODE_H / 2;
+    nodes.push({
+      id,
+      kind: decl.kind,
+      role: nodeRole(decl.kind),
+      label: decl.label,
+      x: snapGrid(x),
+      y: snapGrid(y),
+      width: NODE_W,
+      height: NODE_H,
+      style: decl.style ? ast.styles[decl.style]?.props : void 0,
+      props: decl.props,
+      opacity: 0,
+      shape: nodeShape(decl.kind, "constellation"),
+      focal: isFocal || decl.props.focal === true || decl.props.accent === true
+    });
+  }
+  return nodes;
+}
+function layoutNodes(ast, edges) {
+  const dtype = diagramType(ast);
+  switch (dtype) {
+    case "flowchart":
+      return layoutRanked(ast, edges, { forceVertical: true });
+    case "tree":
+      return layoutTree(ast, edges.some((edge) => edge.structural) ? edges.filter((edge) => edge.structural) : edges);
+    case "sequence":
+      return layoutRanked(ast, [], { columnLayout: true });
+    case "constellation":
+      return layoutConstellation(ast);
+    case "state":
+      return layoutRanked(ast, cycleSafeEdges(Object.keys(ast.nodes), edges), { forceVertical: false });
+    default:
+      return layoutRanked(ast, edges, { forceVertical: false });
+  }
+}
+function computeGroupBoundaries(ast, nodes) {
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const boundaries = [];
+  for (const group of Object.values(ast.groups)) {
+    const members = group.members.filter((id) => byId.has(id));
+    if (members.length === 0) continue;
+    const rects = members.map((id) => byId.get(id));
+    const minX = Math.min(...rects.map((n) => n.x)) - GROUP_PAD;
+    const minY = Math.min(...rects.map((n) => n.y)) - GROUP_PAD - 12;
+    const maxX = Math.max(...rects.map((n) => n.x + n.width)) + GROUP_PAD;
+    const maxY = Math.max(...rects.map((n) => n.y + n.height)) + GROUP_PAD;
+    boundaries.push({
+      id: group.id,
+      label: group.label,
+      x: snapGrid(minX),
+      y: snapGrid(minY),
+      width: snapGrid(maxX - minX),
+      height: snapGrid(maxY - minY),
+      memberIds: members,
+      props: group.props
+    });
+  }
+  return boundaries;
+}
+function computeTreeBuses(ast, nodes, edges) {
+  if (diagramType(ast) !== "tree") return [];
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const children = /* @__PURE__ */ new Map();
+  const parent = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    if (edge.kind === "response" || edge.selfLoop) continue;
+    if (!byId.has(edge.from) || !byId.has(edge.to) || parent.has(edge.to)) continue;
+    if (!children.has(edge.from)) children.set(edge.from, []);
+    children.get(edge.from).push(edge.to);
+    parent.add(edge.to);
+  }
+  const buses = [];
+  for (const [parentId, childIds] of children) {
+    const parentNode = byId.get(parentId);
+    const childNodes = childIds.map((id) => byId.get(id)).filter(Boolean);
+    if (!parentNode || childNodes.length === 0) continue;
+    const parentX = parentNode.x + parentNode.width / 2;
+    const parentY = parentNode.y + parentNode.height;
+    const childY = Math.min(...childNodes.map((node) => node.y));
+    buses.push({
+      id: `tree_bus_${parentId}`,
+      parentId,
+      childIds,
+      parentX: snapGrid(parentX),
+      parentY: snapGrid(parentY),
+      branchY: snapGrid((parentY + childY) / 2),
+      childXs: childNodes.map((node) => snapGrid(node.x + node.width / 2)),
+      childY: snapGrid(childY)
+    });
+  }
+  return buses;
+}
+function resolveTargets(targets, ast, groups, edgeIds) {
   const out = [];
   for (const t of targets) {
     if (t === "$nodes") {
       out.push(...Object.keys(ast.nodes));
     } else if (t === "$edges") {
-      continue;
+      out.push(...edgeIds);
     } else if (t.startsWith("$")) {
       const g = t.slice(1);
       if (groups[g]) out.push(...groups[g]);
@@ -543,6 +827,8 @@ function scheduleBeats(ast, edges) {
   const beatRanges = [];
   let t = 0;
   let edgeCounter = edges.length;
+  const edgeIds = edges.map((e) => e.id);
+  const groupMap = Object.fromEntries(Object.entries(ast.groups).map(([k, g]) => [k, g.members]));
   const hasIntro = ast.beats.some((b) => b.cues.some((c) => c.kind === "show"));
   if (!hasIntro && Object.keys(ast.nodes).length > 0) {
     cues.push({
@@ -575,7 +861,10 @@ function scheduleBeats(ast, edges) {
       const dur = "dur" in cue && cue.dur !== void 0 ? cue.dur : DEFAULTS[cue.kind] ?? 0.5;
       if (cue.kind === "flow") {
         for (const seg of cue.segments) {
-          const edgeId = `flow_${++edgeCounter}`;
+          const existing = edges.find(
+            (e) => !e.structural && e.from === seg.from && e.to === seg.to && e.kind === seg.op && e.label === seg.label
+          );
+          const edgeId = existing?.id ?? `flow_${++edgeCounter}`;
           scheduled.push({
             start: t,
             duration: dur / cue.segments.length,
@@ -591,7 +880,7 @@ function scheduleBeats(ast, edges) {
         return;
       }
       if (cue.kind !== "show" && cue.kind !== "hide" && cue.kind !== "glow" && cue.kind !== "focus" && cue.kind !== "frame") return;
-      const targets = resolveTargets(cue.targets, ast, Object.fromEntries(Object.entries(ast.groups).map(([k, g]) => [k, g.members])));
+      const targets = resolveTargets(cue.targets, ast, groupMap, edgeIds);
       scheduled.push({
         start: t,
         duration: dur,
@@ -619,10 +908,49 @@ function scheduleBeats(ast, edges) {
   }
   return { cues, beats: beatRanges };
 }
+function buildSequencePlan(ast, cues) {
+  if (diagramType(ast) !== "sequence") return { messages: [], activations: [] };
+  const flowCues = cues.filter((cue) => cue.kind === "flow" && cue.segments?.[0]);
+  const firstY = TITLE_BAND + NODE_H + 64;
+  const lastY = ast.meta.height - SAFE - 40;
+  const step = flowCues.length > 1 ? Math.max(36, Math.min(64, (lastY - firstY) / (flowCues.length - 1))) : 0;
+  const messages = [];
+  const activations = [];
+  flowCues.forEach((cue, index) => {
+    const segment = cue.segments[0];
+    if (!ast.nodes[segment.from] || !ast.nodes[segment.to]) return;
+    const message = {
+      id: `sequence_${index + 1}`,
+      from: segment.from,
+      to: segment.to,
+      kind: segment.op,
+      label: segment.label,
+      y: snapGrid(firstY + step * index),
+      start: cue.start,
+      duration: cue.duration,
+      beat: cue.beat
+    };
+    messages.push(message);
+    for (const participant of /* @__PURE__ */ new Set([message.from, message.to])) {
+      activations.push({
+        id: `${message.id}_${participant}`,
+        participant,
+        y: message.y - 18,
+        height: 36,
+        start: message.start,
+        duration: message.duration
+      });
+    }
+  });
+  return { messages, activations };
+}
 function compilePlan(ast, theme) {
   const structuralEdges = collectStructuralEdges(ast);
   const nodes = layoutNodes(ast, structuralEdges);
+  const groupBoundaries = computeGroupBoundaries(ast, nodes);
+  const treeBuses = computeTreeBuses(ast, nodes, structuralEdges.filter((edge) => edge.structural));
   const { cues, beats } = scheduleBeats(ast, structuralEdges);
+  const sequence = buildSequencePlan(ast, cues);
   const shown = /* @__PURE__ */ new Set();
   for (const cue of cues) {
     if (cue.kind === "show") cue.targets.forEach((id) => shown.add(id));
@@ -643,11 +971,17 @@ function compilePlan(ast, theme) {
     meta: ast.meta,
     theme,
     title,
+    diagramType: diagramType(ast),
     nodes,
     edges: structuralEdges,
+    groupBoundaries,
+    annotations: ast.annotations.slice(0, 2),
     cues,
     beats,
     groups: Object.fromEntries(Object.entries(ast.groups).map(([k, g]) => [k, g.members])),
+    treeBuses,
+    sequenceMessages: sequence.messages,
+    sequenceActivations: sequence.activations,
     duration
   };
 }
@@ -753,6 +1087,92 @@ var THEMES = {
     labelPlate: "#191c22",
     roles: { ...ROLE_COLORS },
     edges: { ...EDGE_COLORS }
+  },
+  editorial: {
+    name: "editorial",
+    canvas: "#fafafa",
+    surface: "#ffffff",
+    surfaceRaised: "#f8fafc",
+    border: "#e2e8f0",
+    text: "#0f172a",
+    textMuted: "#64748b",
+    paper: "#fafafa",
+    ink: "#0f172a",
+    muted: "#6b7280",
+    rule: "#e2e8f0",
+    soft: "#94a3b8",
+    link: "#047857",
+    gridMinor: "rgba(15, 23, 42, 0.06)",
+    gridMajor: "rgba(15, 23, 42, 0.10)",
+    vignette: "rgba(226, 232, 240, 0.5)",
+    accent: "#047857",
+    accentTint: "rgba(4, 120, 87, 0.08)",
+    nodeSurface: "#ffffff",
+    nodeSurfaceRaised: "#f8fafc",
+    hairline: "#e2e8f0",
+    shadow: "rgba(15, 23, 42, 0.08)",
+    labelPlate: "#fafafa",
+    flatCards: true,
+    roles: { ...ROLE_COLORS, compute: "#0f172a", client: "#64748b", data: "#64748b" },
+    edges: {
+      request: "#334155",
+      response: "#64748b",
+      event: "#047857",
+      dependency: "#94a3b8"
+    },
+    fonts: {
+      title: "Georgia, Times New Roman, serif",
+      nodeName: "ui-sans-serif, system-ui, sans-serif",
+      mono: "ui-monospace, SFMono-Regular, Menlo, monospace"
+    },
+    radiusMd: 6,
+    spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 40 }
+  },
+  nebula: {
+    name: "nebula",
+    canvas: "#090b1a",
+    surface: "#111735",
+    surfaceRaised: "#1a2250",
+    border: "rgba(167, 139, 250, 0.28)",
+    text: "#eef2ff",
+    textMuted: "#a5b4fc",
+    paper: "#090b1a",
+    ink: "#eef2ff",
+    muted: "#818cf8",
+    rule: "rgba(129, 140, 248, 0.32)",
+    soft: "#67e8f9",
+    link: "#67e8f9",
+    gridMinor: "rgba(129, 140, 248, 0.08)",
+    gridMajor: "rgba(103, 232, 249, 0.16)",
+    vignette: "rgba(3, 5, 18, 0.86)",
+    accent: "#c4b5fd",
+    accentTint: "rgba(196, 181, 253, 0.14)",
+    nodeSurface: "#111735",
+    nodeSurfaceRaised: "#202a5b",
+    hairline: "rgba(196, 181, 253, 0.32)",
+    shadow: "rgba(3, 5, 18, 0.72)",
+    labelPlate: "#12183b",
+    roles: {
+      ...ROLE_COLORS,
+      compute: "#67e8f9",
+      client: "#f9a8d4",
+      data: "#a7f3d0",
+      network: "#93c5fd",
+      flow: "#c4b5fd"
+    },
+    edges: {
+      request: "#67e8f9",
+      response: "#c4b5fd",
+      event: "#f9a8d4",
+      dependency: "#818cf8"
+    },
+    fonts: {
+      title: "Georgia, Times New Roman, serif",
+      nodeName: "ui-sans-serif, system-ui, sans-serif",
+      mono: "ui-monospace, SFMono-Regular, Menlo, monospace"
+    },
+    radiusMd: 12,
+    spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 40 }
   }
 };
 function resolveTheme(name) {
@@ -1151,8 +1571,45 @@ function readIndentedBody(blocks, startIdx, parentIndent) {
   }
   return { body, nextIdx: i };
 }
-function readBody(blocks, startIdx, parentIndent, braceDelimited) {
-  if (!braceDelimited) return readIndentedBody(blocks, startIdx, parentIndent);
+var TOP_LEVEL_KEYWORDS_RE = /^(scene|layout|pattern|group|annotation|edge|beat|var|style)\b/;
+function isTopLevelStatement(line) {
+  if (line === "}") return true;
+  if (TOP_LEVEL_KEYWORDS_RE.test(line)) return true;
+  const nodeMatch = line.match(/^(\w[\w.-]*)\s+(\w[\w.-]*)/);
+  if (!nodeMatch) return false;
+  const kind = canonicalNodeKind(nodeMatch[1].toLowerCase());
+  return NODE_KINDS.has(kind);
+}
+function readColonBody(blocks, startIdx, parentIndent, diagnostics, context, headerLine) {
+  const indented = readIndentedBody(blocks, startIdx, parentIndent);
+  if (indented.body.length > 0 || startIdx >= blocks.length) {
+    return indented;
+  }
+  if (isTopLevelStatement(blocks[startIdx].text)) {
+    return indented;
+  }
+  const body = [];
+  let i = startIdx;
+  while (i < blocks.length) {
+    const block = blocks[i];
+    if (block.indent < parentIndent) break;
+    if (block.indent === parentIndent && isTopLevelStatement(block.text)) break;
+    body.push(block);
+    i++;
+  }
+  if (body.length > 0) {
+    diagnostics.push({
+      severity: "warning",
+      message: `${context} body had no indentation; parsed until the next top-level statement (hosts like MDX/JSX often strip indent from template literals)`,
+      line: headerLine
+    });
+  }
+  return { body, nextIdx: i };
+}
+function readBody(blocks, startIdx, parentIndent, braceDelimited, diagnostics = [], context = "block", headerLine = 1) {
+  if (!braceDelimited) {
+    return readColonBody(blocks, startIdx, parentIndent, diagnostics, context, headerLine);
+  }
   const body = [];
   let i = startIdx;
   while (i < blocks.length) {
@@ -1261,6 +1718,14 @@ function validateReferences(ast) {
     validateFlowEndpoint(edge.line, edge.from);
     validateFlowEndpoint(edge.line, edge.to);
   }
+  for (const ann of ast.annotations) {
+    if (ann.target && !hasNode(ann.target)) {
+      pushWarning(ast.diagnostics, seen, ann.line, `annotation references unknown target '${ann.target}'`);
+    }
+  }
+  if (ast.annotations.length > 2) {
+    pushWarning(ast.diagnostics, seen, ast.annotations[2].line, "more than 2 annotation callouts; editorial diagrams should use \u22642");
+  }
   for (const beat of ast.beats) {
     visitCues(beat.cues, (cue) => {
       if (cue.kind === "flow") {
@@ -1280,6 +1745,61 @@ function validateReferences(ast) {
     });
   }
 }
+function detectFlowCycles(ast) {
+  if (ast.meta.type === "state") return;
+  const seen = /* @__PURE__ */ new Set();
+  const adj = /* @__PURE__ */ new Map();
+  const ensure = (id) => {
+    if (!adj.has(id)) adj.set(id, []);
+  };
+  for (const id of Object.keys(ast.nodes)) ensure(id);
+  const addEdge = (from, to, line) => {
+    if (from === to) return;
+    if (!ast.nodes[from] || !ast.nodes[to]) return;
+    ensure(from);
+    adj.get(from).push({ to, line });
+  };
+  for (const edge of ast.edges) {
+    if (edge.kind !== "response") addEdge(edge.from, edge.to, edge.line);
+  }
+  for (const beat of ast.beats) {
+    visitCues(beat.cues, (cue) => {
+      if (cue.kind !== "flow") return;
+      for (const segment of cue.segments) {
+        if (segment.op !== "response") addEdge(segment.from, segment.to, cue.line);
+      }
+    });
+  }
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  for (const id of adj.keys()) color.set(id, WHITE);
+  const stack = [];
+  const dfs = (node) => {
+    color.set(node, GRAY);
+    stack.push(node);
+    for (const { to, line } of adj.get(node) ?? []) {
+      if (color.get(to) === GRAY) {
+        const idx = stack.indexOf(to);
+        const cyclePath = [...stack.slice(idx), to].join(" -> ");
+        pushWarning(
+          ast.diagnostics,
+          seen,
+          line,
+          `flow cycle detected: ${cyclePath} \u2014 if '${to}' is receiving a reply/return value here, use '<-' for this edge instead of '->'/'~>'/'--' (an unmarked cycle can crush the ranked layout and overlap nodes)`
+        );
+      } else if (color.get(to) === WHITE) {
+        dfs(to);
+      }
+    }
+    stack.pop();
+    color.set(node, BLACK);
+  };
+  for (const id of adj.keys()) {
+    if (color.get(id) === WHITE) dfs(id);
+  }
+}
 function parse(source, opts = {}) {
   const lines = source.replace(/\r\n/g, "\n").split("\n");
   const diagnostics = [];
@@ -1296,8 +1816,10 @@ function parse(source, opts = {}) {
   const groups = {};
   const patterns = {};
   const beats = [];
+  const annotations = [];
   let title = "";
   let edgeCounter = 0;
+  let annotationCounter = 0;
   const rawBlocks = readBlocks(lines.map(stripComment));
   const { vars, rest } = extractVars(rawBlocks, diagnostics);
   const blocks = applyVars(rest, vars);
@@ -1334,6 +1856,14 @@ function parse(source, opts = {}) {
         else if (k === "duration") meta.duration = Number(v);
         else if (k === "theme") meta.theme = String(v);
         else if (k === "direction" || k === "layout") meta.direction = String(v).toUpperCase();
+        else if (k === "type") {
+          const t = String(v).toLowerCase();
+          if (!DIAGRAM_TYPES.has(t)) {
+            diagnostics.push({ severity: "warning", message: `unknown diagram type '${v}'`, line: lineNo });
+          } else {
+            meta.type = t;
+          }
+        }
       }
       i++;
       continue;
@@ -1354,7 +1884,15 @@ function parse(source, opts = {}) {
       const m = line.match(/^pattern\s+(\w+)\s*\(([^)]*)\)\s*(?::|\{)\s*$/);
       if (!m) throw new ParseError(`expected pattern name(params):`, lineNo);
       const params = m[2].trim() ? m[2].split(",").map((p) => p.trim()) : [];
-      const { body, nextIdx } = readBody(blocks, i + 1, block.indent, line.endsWith("{"));
+      const { body, nextIdx } = readBody(
+        blocks,
+        i + 1,
+        block.indent,
+        line.endsWith("{"),
+        diagnostics,
+        `pattern '${m[1]}'`,
+        lineNo
+      );
       const cues = normalizeCueBlocks(body).map((b) => parseCueLine(b.text, b.line));
       patterns[m[1]] = { name: m[1], params, body: cues, line: lineNo };
       i = nextIdx;
@@ -1375,7 +1913,14 @@ function parse(source, opts = {}) {
       }
       const header = line.match(/^group\s+(\w+)(?:\s+"([^"]*)")?\s*:\s*$/);
       if (!header) throw new ParseError(`expected group name: A B C`, lineNo);
-      const { body, nextIdx } = readIndentedBody(blocks, i + 1, block.indent);
+      const { body, nextIdx } = readColonBody(
+        blocks,
+        i + 1,
+        block.indent,
+        diagnostics,
+        `group '${header[1]}'`,
+        lineNo
+      );
       const members = body.flatMap((b) => splitTargets(b.text));
       if (members.length === 0) throw new ParseError(`group '${header[1]}' has no members`, lineNo);
       groups[header[1]] = {
@@ -1388,6 +1933,23 @@ function parse(source, opts = {}) {
       i = nextIdx;
       continue;
     }
+    if (line.startsWith("annotation ")) {
+      const str = parseStringToken(line.slice("annotation ".length).trim());
+      if (!str) throw new ParseError(`expected annotation "text" with optional target= position=`, lineNo);
+      const props = parseProps(str.rest);
+      const target = typeof props.target === "string" ? props.target : void 0;
+      const position = typeof props.position === "string" ? props.position : void 0;
+      annotations.push({
+        id: `ann_${++annotationCounter}`,
+        text: str.value,
+        target,
+        position,
+        props,
+        line: lineNo
+      });
+      i++;
+      continue;
+    }
     if (line.startsWith("edge ")) {
       const m = line.match(/^edge\s+(\w+)\s*:\s*(.+)$/);
       if (!m) throw new ParseError(`expected edge id: A -> B`, lineNo);
@@ -1409,7 +1971,15 @@ function parse(source, opts = {}) {
     if (line.startsWith("beat ")) {
       const m = line.match(/^beat\s+([\w.-]+)(?:\s+"([^"]*)")?\s*(?::|\{)\s*$/);
       if (!m) throw new ParseError(`expected beat name:`, lineNo);
-      const { body, nextIdx } = readBody(blocks, i + 1, block.indent, line.endsWith("{"));
+      const { body, nextIdx } = readBody(
+        blocks,
+        i + 1,
+        block.indent,
+        line.endsWith("{"),
+        diagnostics,
+        `beat '${m[1]}'`,
+        lineNo
+      );
       let cues = normalizeCueBlocks(body).map((b) => parseCueLine(b.text, b.line));
       cues = expandPatternCues(cues, patterns, lineNo);
       beats.push({ name: m[1], label: m[2], cues, line: lineNo });
@@ -1455,11 +2025,13 @@ function parse(source, opts = {}) {
     nodes,
     edges,
     groups,
+    annotations,
     patterns,
     beats,
     diagnostics
   };
   validateReferences(ast);
+  detectFlowCycles(ast);
   const errors = ast.diagnostics.filter((d) => d.severity === "error");
   if (errors.length) {
     throw new ParseError(errors[0].message, errors[0].line, errors[0].column);
@@ -1479,6 +2051,7 @@ function parseAndCompile(source) {
 export {
   BEAT_CUE_KEYWORDS,
   CUE_ALIASES,
+  DIAGRAM_TYPES,
   EDGE_OPERATORS,
   NODE_ALIASES,
   NODE_KINDS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdy/core",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Diagram-native MarkdyScript parser and compiler (auto-layout, edge routing, cue scheduling) — zero runtime dependencies.",
   "license": "MIT",
   "type": "module",