schematex 0.5.0 → 0.5.2

package/dist/{chunk-NWPCY65Z.cjs → chunk-HK56GQQP.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk3YUUC6RN_cjs = require('./chunk-3YUUC6RN.cjs');
+var chunk4QPDZJAL_cjs = require('./chunk-4QPDZJAL.cjs');
 
 // src/ai/registry.ts
 var DIAGRAM_REGISTRY = [
@@ -217,6 +217,15 @@ var DIAGRAM_REGISTRY = [
     standard: "OMG UML 2.5.1 \xA718 visual subset; see 29-USECASE-STANDARD.md",
     syntaxKey: "usecase"
   },
+  {
+    type: "sequence",
+    name: "UML sequence diagram",
+    tagline: "UML 2.5.1 \xA717 interaction \u2014 lifelines, messages over time, activations, and combined fragments.",
+    useWhen: "Use for time-ordered interactions between participants \u2014 API call flows, auth handshakes, distributed protocols, object collaborations, 'who calls whom in what order'. Lifelines run top\u2192bottom; messages run left\u2192right: `->` synchronous (filled head), `->>` asynchronous (open head), `-->` reply (dashed), `-x` lost, `o->` found. `+`/`-` suffixes open/close activation bars; `*Target` creates a participant and `destroy` ends one. All twelve UML combined fragments \u2014 `alt`/`opt`/`loop`/`par`/`break`/`critical`/`seq`/`strict`/`neg`/`ignore`/`consider`/`assert` \u2014 plus `ref` interaction-use frames. Participant kinds `actor`/`boundary`/`control`/`entity`/`database` render their UML/Jacobson symbols; `\xABstereotype\xBB` overrides the label. Distinct from `usecase` (system scope, not message order), `state` (one object's modes, not inter-object messages), `bpmn` (organisational process), and `flowchart` (no lifelines/time axis).",
+    cluster: "behavior-modeling",
+    standard: "OMG UML 2.5.1 \xA717 (Interactions); see 33-SEQUENCE-STANDARD.md",
+    syntaxKey: "sequence"
+  },
   // ── Research / evidence synthesis ────────────────────────────
   {
     type: "prisma",
@@ -286,46 +295,26 @@ var DIAGRAM_REGISTRY = [
     syntaxKey: "timeline"
   }
 ];
+var TYPE_ALIASES = {
+  block: "blockdiagram",
+  "entity-structure": "entity",
+  graph: "flowchart",
+  statediagram: "state",
+  "statediagram-v2": "state",
+  sequencediagram: "sequence"
+};
+function resolveDiagramType(type) {
+  const normalized = type.trim().toLowerCase();
+  return DIAGRAM_REGISTRY.find((d) => d.type === normalized)?.type ?? TYPE_ALIASES[normalized];
+}
 function getDiagramMeta(type) {
-  return DIAGRAM_REGISTRY.find((d) => d.type === type);
+  const resolved = resolveDiagramType(type);
+  return DIAGRAM_REGISTRY.find((d) => d.type === resolved);
 }
 function getAllDiagramTypes() {
   return DIAGRAM_REGISTRY.map((d) => d.type);
 }
 
-// src/ai/errors.ts
-var ENGINE_BUG_NAMES = /* @__PURE__ */ new Set([
-  "ReferenceError",
-  "TypeError",
-  "RangeError"
-]);
-function extractError(err) {
-  if (err instanceof Error) {
-    const anyErr = err;
-    const hasParseFields = typeof anyErr.line === "number";
-    const isEngineBug = !hasParseFields && ENGINE_BUG_NAMES.has(err.name);
-    const sourceHint = isEngineBug ? firstStackFrame(err.stack) : typeof anyErr.source === "string" ? anyErr.source : void 0;
-    return {
-      line: typeof anyErr.line === "number" ? anyErr.line : void 0,
-      column: typeof anyErr.column === "number" ? anyErr.column : void 0,
-      source: sourceHint,
-      message: isEngineBug ? `[engine bug: ${err.name}] ${err.message}` : err.message,
-      hint: typeof anyErr.hint === "string" ? anyErr.hint : isEngineBug ? "This looks like a Schematex internal error rather than a DSL syntax problem. Please file an issue with the failing DSL at https://github.com/SchemaTex/Schematex/issues." : void 0
-    };
-  }
-  return { message: String(err) };
-}
-function firstStackFrame(stack) {
-  if (!stack) return void 0;
-  for (const line of stack.split("\n")) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith("at ")) {
-      return trimmed.replace(/\((?:.*\/)?([^/]+)\)/, "($1)");
-    }
-  }
-  return void 0;
-}
-
 // src/ai/_generated.ts
 var EXAMPLES = [
   {
@@ -1251,6 +1240,56 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
     "dsl": 'phylo "Bacterial Diversity"\n  newick: "((((Ecoli:0.1,Salmonella:0.12):0.05[&&NHX:B=98],Vibrio:0.2):0.08[&&NHX:B=85],((Bacillus:0.15,Staph:0.18):0.06[&&NHX:B=92],Listeria:0.22):0.1):0.15,((Myco_tb:0.3,Myco_leprae:0.28):0.12[&&NHX:B=100],(Strepto:0.25,Lactobacillus:0.2):0.08[&&NHX:B=78]):0.2);"\n  clade Gamma = (Ecoli, Salmonella, Vibrio) [color: "#1E88E5", label: "\u03B3-Proteobacteria"]\n  clade Firmi = (Bacillus, Staph, Listeria, Strepto, Lactobacillus) [color: "#E53935", label: "Firmicutes"]\n  clade Actino = (Myco_tb, Myco_leprae) [color: "#43A047", label: "Actinobacteria"]\n  scale "substitutions/site"',
     "notes": '## Scenario\n\nA microbiologist or bioinformatician pastes a Newick tree string exported from RAxML, IQ-TREE, or MEGA and immediately gets a publication-ready SVG with clade highlights and a branch-length scale bar \u2014 no manual layout required.\n\n## Annotation key\n\n- `newick: "..."` \u2014 standard Newick format tree string; branch lengths follow `:` after each taxon name\n- `[&&NHX:B=98]` \u2014 NHX annotation; `B=` is the bootstrap support value (0\u2013100), rendered on internal nodes\n- `clade id = (taxon, ...)` \u2014 defines a named clade by listing its leaf members\n- `[color: "#hex", label: "..."]` \u2014 colors the clade\'s subtree and adds a labeled arc\n- `scale "..."` \u2014 draws a calibrated scale bar with the given unit label\n\n## How to read\n\nThe tree shows three major bacterial clades. Blue (\u03B3-Proteobacteria): *E. coli*, *Salmonella*, and *Vibrio* cluster with 98% bootstrap support. Red (Firmicutes): *Bacillus*, *Staph*, *Listeria*, *Streptococcus*, and *Lactobacillus*. Green (Actinobacteria): the two *Mycobacterium* species form a highly supported clade (bootstrap 100). Branch lengths represent substitutions per site \u2014 longer branches indicate faster evolutionary rates.'
   },
+  {
+    "slug": "pid-pump-flow-control",
+    "diagram": "pid",
+    "title": "Pump with flow control loop (P&ID)",
+    "description": "Classic centrifugal pump pulling from an atmospheric tank, with a flow transmitter (FT-101), flow indicating controller (FIC-101), and a fail-closed pneumatic control valve \u2014 the minimum viable P&ID that every process engineer recognises at a glance.",
+    "standard": "ANSI/ISA-5.1-2009 + ISO 10628-1:2014",
+    "tags": [
+      "pid",
+      "isa-5.1",
+      "flow-control",
+      "centrifugal-pump",
+      "control-valve",
+      "instrument-loop"
+    ],
+    "complexity": 1,
+    "featured": true,
+    "dsl": 'pid "Water Pump Flow Control"\n\nequip T-101 : tank_atm [tag: "Feed Tank"]\nequip P-101 : pump_centrifugal [tag: "Feed Pump"]\nequip V-101 : valve_control [actuator: "diaphragm", fail: "FC"]\nequip V-100 : valve_gate [tag: "Isolation"]\n\nline L1 from T-101.bottom to P-101.in [size: "4\\"", service: "water", type: "process"]\nline L2 from P-101.out to V-101.in [size: "4\\"", service: "water", type: "process"]\nline L3 from V-101.out to dest [size: "4\\"", type: "process"]\n\ninst FT-101 : field_discrete\n  measures L2\ninst FIC-101 : cr_shared\n  controls V-101\n\nline s1 from FT-101 to FIC-101 [type: "electric"]\nline s2 from FIC-101 to V-101 [type: "pneumatic"]',
+    "notes": 'The pump-with-flow-control loop is to P&ID what the "hello world" program is to software: every process engineer has drawn one, every piping textbook uses it as chapter one, and once you understand it you understand the grammar of every more complex diagram.\n\n**What the diagram shows.** T-101 is an atmospheric tank (dome-roof symbol, open to atmosphere). The centrifugal pump P-101 pulls fluid from the bottom nozzle and pushes it downstream through a 4-inch water service line. The flow transmitter FT-101 \u2014 a field-mounted discrete instrument, drawn as a plain circle per ISA-5.1 \xA74.1 \u2014 sits on the discharge line L2 and measures the volumetric flow rate. Its 4\u201320 mA electric signal travels to FIC-101, the flow indicating controller in the main control room (drawn as a circle with a horizontal line through it, indicating it is panel-mounted and has a display). FIC-101 computes the error between the setpoint and the measured flow and drives V-101, a diaphragm-actuated control valve, open or closed via a pneumatic signal. V-100 is a manual gate valve upstream \u2014 the isolation valve you close when you need to pull the pump for maintenance.\n\n**ISA-5.1 signal line types.** The two non-process lines in this diagram are drawn differently from the main pipe: the electric signal between FT-101 and FIC-101 is a dashed line (`stroke-dasharray: 6 4`), and the pneumatic signal between FIC-101 and V-101 is a solid line with small perpendicular slash marks at regular intervals. These are not stylistic choices \u2014 they are ISA-5.1 \xA75.2 mandatory line type codes. An instrument technician reading the diagram needs to know, at a glance, whether a run of wire failed or an air supply pressure dropped. The line type tells them which.\n\n**Fail-safe position.** V-101 is marked `fail: "FC"` \u2014 fail-closed. When the air supply to the diaphragm actuator is lost (instrument air header trips, tubing rupture), the spring return pushes the valve shut. This is the correct failure mode for a pump discharge valve: loss of control should stop flow, not open it fully. If this were a cooling-water valve on a reactor, you\'d want fail-open instead. The choice of fail position is one of the first decisions in a safety instrumented system review (HAZOP, SIL assessment) and it belongs on the P&ID from day one.\n\n**Why not draw.io.** Process engineers currently draw P&IDs in AutoCAD P&ID, SmartPlant P&ID, or draw.io with stencil libraries \u2014 all of which require manual symbol placement and wiring. The Schematex DSL lets you describe the topology and generate a standards-compliant SVG. This is particularly useful when a process is described in prose (from a process description document or a licensor\'s PFD) and needs to be turned into a P&ID for HAZOP review \u2014 the conversion becomes a text transformation task that LLMs can assist with, producing a reviewable first draft rather than a blank canvas.'
+  },
+  {
+    "slug": "pid-reactor-feed-system",
+    "diagram": "pid",
+    "title": "Reactor feed with multi-loop control and pressure safety (P&ID)",
+    "description": "CSTR reactor system with centrifugal pump, shell-and-tube pre-heater, flow control on the feed line, temperature control on the product outlet, and a PSHH pressure switch interlock \u2014 four instrument loops in one diagram, covering the core vocabulary of ISA-5.1 P&ID engineering.",
+    "standard": "ANSI/ISA-5.1-2009 + ISO 10628-1:2014",
+    "tags": [
+      "pid",
+      "isa-5.1",
+      "reactor",
+      "heat-exchanger",
+      "multi-loop",
+      "pshh",
+      "interlock",
+      "safety"
+    ],
+    "complexity": 3,
+    "featured": false,
+    "dsl": 'pid "High-Pressure Reactor Feed"\n\nequip T-201 : tank_atm [tag: "Raw Material Tank"]\nequip P-201 : pump_centrifugal [tag: "Feed Pump P-201A/B"]\nequip E-201 : hx_shell_tube [tag: "Feed Pre-heater"]\nequip R-201 : reactor_cstr [tag: "Reactor R-201"]\nequip V-201 : valve_control [actuator: "diaphragm", fail: "FC"]\nequip V-202 : valve_control [actuator: "diaphragm", fail: "FO"]\nequip V-203 : valve_psv [set_pressure: "150 psig"]\n\nline L1 from T-201.bottom to P-201.in [size: "6\\"", service: "feed", type: "process"]\nline L2 from P-201.out to E-201.shell_in [size: "6\\"", service: "feed", type: "process"]\nline L3 from E-201.shell_out to V-201.in [size: "6\\"", service: "feed", type: "process"]\nline L4 from V-201.out to R-201.in [size: "6\\"", service: "feed", type: "process"]\nline L5 from R-201.out to V-202.in [size: "4\\"", service: "product", type: "process"]\n\ninst FT-201 : field_discrete\n  measures L2\ninst FIC-201 : cr_shared\n  controls V-201\n\ninst TT-201 : field_discrete\n  measures R-201\ninst TIC-201 : cr_shared\n  controls V-202\n\ninst PT-201 : field_discrete\n  measures R-201\ninst PSHH-201 : field_discrete\n  measures R-201\n\nline s1 from FT-201 to FIC-201 [type: "electric"]\nline s2 from FIC-201 to V-201 [type: "pneumatic"]\nline s3 from TT-201 to TIC-201 [type: "electric"]\nline s4 from TIC-201 to V-202 [type: "pneumatic"]\nline s5 from PT-201 to PSHH-201 [type: "electric"]',
+    "notes": `Real process plants don't have one control loop \u2014 they have a web of them. This diagram shows a CSTR reactor system with four instrument loops and a safety instrument, which is about the minimum complexity for a unit operation that would appear in a HAZOP study. Understanding how to read this diagram cold is a core skill for every process, instrumentation, and safety engineer on the project team.
+
+**The process path.** Raw material is stored in T-201 (atmospheric tank). The centrifugal pump P-201A/B (the A/B suffix is conventional for spared pumps \u2014 one online, one standby) pulls from the bottom nozzle and pushes through 6-inch feed line L2 to the shell-and-tube heat exchanger E-201, which pre-heats the feed before it enters the reactor. From E-201, the line continues through the feed control valve V-201 into the reactor R-201. The reactor product exits through L5 and the product control valve V-202.
+
+**Loop 201 \u2014 flow control.** FT-201 (flow transmitter, field-mounted) sits on the pump discharge line L2 and sends a 4\u201320 mA signal to FIC-201 (flow indicating controller, control-room mounted, DCS shared \u2014 note the horizontal line through the circle). FIC-201 closes or opens V-201 to maintain the feed flow setpoint. V-201 is fail-closed: if instrument air is lost, the feed to the reactor stops. Starving a reactor on air loss is usually safer than flooding it.
+
+**Loop 201T \u2014 temperature control.** TT-201 (temperature transmitter) measures the reactor body temperature and signals TIC-201, which throttles V-202 \u2014 the product outlet valve \u2014 to regulate residence time and therefore heat generation in the reactor. V-202 is fail-open: losing air means the product continues to drain out, preventing dangerous temperature accumulation inside the vessel. The fail-safe position is always chosen by answering the question: "which state causes less harm if control is lost?"
+
+**Loop 201P \u2014 pressure monitoring and safety.** PT-201 is a field-mounted pressure transmitter \u2014 it sends the continuous pressure reading to the DCS historian. PSHH-201 is a pressure switch, high-high: a discrete field-mounted device that trips at the maximum allowable working pressure (MAWP). It is wired to the safety interlock system (SIS), not the DCS. The distinction matters: DCS loops control the process; SIS loops protect equipment and people. OSHA PSM (29 CFR 1910.119) requires the two to be functionally independent. V-203 is the pressure safety valve \u2014 a spring-loaded valve that opens automatically at the set pressure of 150 psig regardless of any control signal, providing the last line of mechanical protection.
+
+**Why P&ID, not PFD.** A process flow diagram (PFD) shows the same equipment but only the major process streams, mass balances, and operating conditions. A P&ID adds every instrument, every valve, every signal line, and every utility connection \u2014 it is the engineering document used by instrument engineers to write I/O lists, by safety engineers to perform HAZOP, and by construction teams to verify field installation. The DSL lets you build this level of detail from text, making it tractable for AI-assisted first drafts and version-controlled review cycles.`
+  },
   {
     "slug": "prisma-dual-pipeline",
     "diagram": "prisma",
@@ -1289,6 +1328,43 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
     "dsl": "prisma\nmode: 2020-single\ntitle: Effect of exercise on chronic low-back pain \u2014 SR\n\nidentification:\n  databases:\n    n: 1418\n    sources: PubMed=600, Embase=450, Cochrane=184, Web of Science=184\n    duplicates-removed: 318\n\nscreening:\n  records-screened: 1100\n  excluded:\n    n: 870\n    reasons: irrelevant title=750, non-English=120\n\neligibility:\n  full-text-assessed: 230\n  excluded:\n    n: 195\n    reasons: wrong population=80, wrong intervention=60, wrong outcome=55\n\nincluded:\n  studies: 35\n  reports: 38",
     "notes": '## Scenario\n\nA research librarian produces the PRISMA 2020 flow diagram for a Cochrane review submission. The journal **requires** the diagram in the exact four-row structure \u2014 Identification \u2192 Screening \u2192 Eligibility \u2192 Included \u2014 with the count `(n = \u2026)` shown in every box and the excluded boxes itemizing reasons. With the dedicated `prisma` engine the librarian writes only counts and reasons; the rigid layout, the "Records removed before screening" side-box, and the exclusion side-boxes are produced automatically and are correct by construction.\n\n## Annotation key\n\n- **`mode: 2020-single`** \u2014 one Identification column (databases & registers). Use `mode: 2020-dual` to add the "other methods" column.\n- **`identification.databases`** \u2014 `n:` is the mandatory total; `sources:` renders the per-database breakdown; `duplicates-removed:` splits out into the right-column "Records removed before screening" box automatically.\n- **`screening` / `eligibility` `excluded:` blocks** \u2014 each has its own `n:` total and an optional `reasons:` breakdown rendered in a side-box to the right, connected by a horizontal arrow.\n- **`included.studies` / `reports`** \u2014 one study can yield several reports, so both counts render.\n\n## How to read\n\nTop to bottom mirrors the PRISMA 2020 template exactly. The left capsule bands label the three canonical stages; the orange bar spans the Identification column group. Counts reconcile across stages (1418 \u2212 318 = 1100 screened; 1100 \u2212 870 = 230 assessed; 230 \u2212 195 = 35 included) \u2014 the engine warns if they don\'t.\n\n## Standard reference\n\nPage MJ, McKenzie JE, Bossuyt PM, et al. *The PRISMA 2020 statement: an updated guideline for reporting systematic reviews.* BMJ 2021;372:n71. Template: [prisma-statement.org/prisma-2020-flow-diagram](https://www.prisma-statement.org/prisma-2020-flow-diagram).'
   },
+  {
+    "slug": "sequence-microservices-saga",
+    "diagram": "sequence",
+    "title": "Microservices order saga",
+    "description": "A distributed order-processing saga showing the parts of UML sequence notation that generic tools omit \u2014 a ref interaction-use frame, a par fragment for concurrent service calls, asynchronous event-bus messages, and an alt fragment with a compensating rollback on payment failure.",
+    "standard": "OMG UML 2.5.1 \xA717 (Interactions)",
+    "tags": [
+      "sequence",
+      "uml",
+      "microservices",
+      "saga",
+      "async",
+      "event-driven"
+    ],
+    "complexity": 3,
+    "featured": false,
+    "dsl": 'sequence "Order processing (saga)"\n  actor Customer\n  participant Gateway as "API Gateway"\n  control Orders as "Order Service"\n  participant Payment as "Payment Service"\n  participant Inventory as "Inventory Service"\n  queue Bus as "Event Bus"\n\n  Customer -> Gateway : POST /orders\n  Gateway ->+ Orders : createOrder()\n  ref over Orders, Bus : Validate cart & price\n\n  par\n    Orders ->> Payment : charge(card)\n  and\n    Orders ->> Inventory : reserve(items)\n  end\n\n  alt [payment captured && stock reserved]\n    Payment --> Orders : paid\n    Inventory --> Orders : reserved\n    Orders ->> Bus : OrderConfirmed\n    Orders -->- Gateway : 201 Created\n    Gateway --> Customer : confirmation\n  else [payment failed]\n    Orders ->> Inventory : release(items)\n    Orders ->> Bus : OrderCancelled\n    Orders -->- Gateway : 402 Payment Required\n    Gateway --> Customer : declined\n  end',
+    "notes": "This is the case that separates a real UML engine from a flowchart with stick figures. A saga is concurrent, asynchronous, and has a compensating path \u2014 and Schematex has dedicated notation for each.\n\n**`ref` keeps the diagram composable.** \"Validate cart & price\" is its own interaction; inlining it here would bury the saga in detail. The `ref over Orders, Bus : \u2026` frame references it instead \u2014 notation most text-to-diagram tools simply don't have.\n\n**`par` shows true concurrency.** The order service charges the card and reserves stock *at the same time*. The `par` fragment's two operands say these run concurrently, not in sequence \u2014 a distinction a top-to-bottom message list cannot express.\n\n**Async vs. reply arrows are not cosmetic.** `->>` (open head) marks fire-and-forget calls and event-bus publishes; `-->` (dashed) marks the replies that come back. Reading the arrowheads tells you which steps block and which don't.\n\n**The compensation lives in the `alt`.** When payment fails, the second operand *releases* the previously reserved inventory and emits `OrderCancelled` \u2014 the saga's rollback, drawn right beside the happy path instead of in a separate diagram."
+  },
+  {
+    "slug": "sequence-oauth-login",
+    "diagram": "sequence",
+    "title": "OAuth 2.0 authorization-code login",
+    "description": "The canonical browser-based sign-in handshake as a UML sequence diagram \u2014 redirect to the auth server, user consent, code-for-token exchange, and an alt fragment for the success vs. failure branch, with activation bars tracking who is busy at each step.",
+    "standard": "OMG UML 2.5.1 \xA717 (Interactions)",
+    "tags": [
+      "sequence",
+      "uml",
+      "oauth",
+      "authentication",
+      "api"
+    ],
+    "complexity": 2,
+    "featured": true,
+    "dsl": 'sequence "OAuth 2.0 Authorization Code"\n  actor User\n  boundary Browser\n  control App as "Web App"\n  participant Auth as "Auth Server"\n  database DB as "User Store"\n\n  User -> Browser : click "Sign in"\n  Browser ->+ App : GET /login\n  App --> Browser : 302 \u2192 Auth Server\n  Browser ->+ Auth : GET /authorize\n  Auth --> User : consent screen\n  User -> Auth : approve\n  Auth -->- Browser : 302 + auth code\n\n  Browser ->+ App : GET /callback?code\n  App ->+ Auth : POST /token (code)\n  Auth ->+ DB : load user\n  DB -->- Auth : profile\n  Auth -->- App : access + refresh token\n  alt [token exchange ok]\n    App --> Browser : Set-Cookie: session\n    Browser --> User : signed in\n  else [exchange failed]\n    App --> Browser : 401 Unauthorized\n    Browser --> User : retry\n  end\n  deactivate App',
+    "notes": "Almost every product ships this flow, and almost every whiteboard drawing of it is subtly wrong about *who is active when*. A sequence diagram makes the call order and the active spans explicit.\n\n**Lifeline kinds carry meaning.** The `boundary` Browser, the `control` App, and the `entity`/`database` user store render as their UML symbols, so a reviewer reads the architecture at a glance: the browser is the UI edge, the app orchestrates, the auth server and store are collaborators.\n\n**Activation bars track the redirect dance.** OAuth bounces the user between the app and the auth server twice. The `+`/`-` suffixes open and close execution-specification bars exactly where each party becomes busy and hands control back \u2014 the `Auth -->- Browser` reply both returns the auth code *and* closes the auth server's first activation.\n\n**The branch is a real fragment, not two diagrams.** The `alt` frame captures the success and failure paths in one place: a valid token exchange sets the session cookie; a failed one returns `401`. That is the single most common place sequence diagrams earn their keep \u2014 showing the unhappy path next to the happy one instead of hiding it."
+  },
   {
     "slug": "sfc-bake-cool-concurrent",
     "diagram": "sfc",
@@ -1468,6 +1544,46 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
     "dsl": 'sociogram "Engineering team \u2014 informal influence"\n  config: layout = force-directed\n  group leads [label: "Tech leads", color: "#1976D2"]\n    alex; sam\n  group sr [label: "Senior ICs", color: "#66BB6A"]\n    priya; jordan; kim; tao\n  group jr [label: "Junior", color: "#FFA726"]\n    lee; ravi; nina; dev\n  alex <-> sam\n  alex -> priya\n  sam -> jordan\n  priya <-> kim\n  jordan <-> tao\n  kim -> lee\n  priya -> ravi\n  tao -> nina\n  dev -.- lee\n  nina -.- priya',
     "notes": "## Scenario\n\nAn engineering manager runs an informal network analysis survey (\"Who do you go to when you're stuck?\") and maps the results to identify knowledge hubs, bridging individuals between seniority tiers, and team members who are drifting toward isolation before performance reviews surface the issue.\n\n## Annotation key\n\n- `group id [label:..., color:...]` \u2014 assigns individuals to organizational tiers, color-coded\n- `<->` \u2014 mutual influence; both nominated each other\n- `->` \u2014 one-way influence nomination\n- `-.-` \u2014 weak tie; neither party nominated the other in the survey\n- The force-directed layout clusters mutual-nomination groups and separates isolates\n\n## How to read\n\nAlex and Sam (tech leads) are mutually influential. Alex bridges down to Priya, Sam to Jordan \u2014 healthy knowledge flow across tiers. Priya and Kim form a strong senior IC hub. Dev and Nina have only weak ties (--. to the network), suggesting integration risk. Dev's only connection is a weak tie to Lee \u2014 a coaching opportunity before the next performance cycle."
   },
+  {
+    "slug": "state-ecommerce-order",
+    "diagram": "state",
+    "title": "E-commerce order lifecycle (state diagram)",
+    "description": "Full order state machine \u2014 from Pending through payment routing (choice pseudo-state), composite Processing state with Picking/Packing/Shipped sub-states, delivery, refund, and cancellation paths. Demonstrates composite states, choice pseudo-states, guard conditions, entry actions, and UML notes.",
+    "standard": "OMG UML 2.5.1 \xA714",
+    "tags": [
+      "state",
+      "uml",
+      "composite",
+      "choice",
+      "guard",
+      "order-management",
+      "e-commerce",
+      "lifecycle"
+    ],
+    "complexity": 2,
+    "featured": false,
+    "dsl": 'state "E-Commerce Order Lifecycle"\n\ninitial i\ni -> Pending\n\nPending -> Confirmed : place_order [items_in_stock] / reserveInventory()\nPending -> Cancelled : cancel\n\nchoice PayRoute\nConfirmed -> PayRoute : pay\nPayRoute -> Processing : [method == "card"]\nPayRoute -> Processing : [method == "wallet"]\nPayRoute -> AwaitingTransfer : [method == "bank_transfer"]\n\nAwaitingTransfer -> Processing : transfer_received [amount_correct]\nAwaitingTransfer -> Cancelled : transfer_timeout\n\ncomposite Processing {\n  initial pi\n  final pf\n\n  pi -> Picking\n  Picking -> Packing : picked / updateWarehouse()\n  Packing -> Shipped : label_printed\n  Shipped -> pf : carrier_confirmed\n}\n\nProcessing -> Delivered : delivered / notifyCustomer()\nProcessing -> Failed : fulfillment_error\n\nDelivered -> Refunded : return_request [within_30_days] / initiateRefund()\nFailed -> Pending : retry [attempt < 3]\nFailed -> Cancelled : retry [attempt >= 3]\n\nfinal f\nDelivered -> f\nRefunded -> f\nCancelled -> f\n\nnote right_of AwaitingTransfer : SLA: 48 h before timeout.',
+    "notes": 'Order state machines are one of the most common backend design artifacts, and one of the most commonly under-specified. Teams often start with a simple enum (`PENDING / PAID / SHIPPED / DELIVERED`) and then bolt on edge cases over time: partial shipments, payment holds, carrier errors, refund windows. Six months later the enum has twelve values, the transition logic is scattered across three services, and nobody can explain what sequence of events gets an order from `FAILED` to `CANCELLED` versus from `FAILED` back to `PENDING`. A UML state diagram catches all of this upfront.\n\n**Guard conditions on `place_order`.** The transition from `Pending` to `Confirmed` carries `[items_in_stock]` \u2014 a guard. Guards are boolean predicates that must be true for the transition to fire even when the trigger event (`place_order`) occurs. If the guard is false, the trigger is silently absorbed and the system stays in `Pending`. In practice this means inventory is checked synchronously during order placement, and the transition only proceeds if stock is available. The action `/ reserveInventory()` fires when the transition does go through, atomically.\n\n**Choice pseudo-state for payment routing.** `PayRoute` is a UML choice pseudo-state (drawn as a diamond). When the `pay` trigger fires from `Confirmed`, the machine immediately evaluates the guards on all outgoing transitions from `PayRoute`. If `method == "card"` or `method == "wallet"`, control goes directly to `Processing`. If `method == "bank_transfer"`, it goes to `AwaitingTransfer` \u2014 a waiting state with its own 48-hour SLA note. Choice pseudo-states do not dwell; they route. This is the correct model for "take different paths based on a value computed at runtime."\n\n**Composite state for fulfillment.** `Processing` is a composite state \u2014 it contains its own internal state machine with `Picking`, `Packing`, and `Shipped`. From the outside, the system is "in Processing" whether it\'s picking, packing, or confirming with the carrier. From the inside, the sub-machine tracks exactly where the warehouse is. The composite state has its own `initial` and `final` pseudo-states: the machine enters at `pi` (starts picking) and exits through `pf` (carrier confirmed), which fires the outer transition to `Delivered`. Cross-composite transitions to `Failed` are also valid \u2014 a fulfillment error at any sub-state terminates the Processing phase and moves to the outer `Failed` state.\n\n**Retry with bounded attempts.** `Failed` has two outgoing transitions back to `Pending` and `Cancelled`, both triggered by `retry` but guarded on `attempt`. This is the explicit model for "retry up to N times, then give up." Without the state diagram, this logic typically lives in a cron job or a dead-letter queue processor that nobody fully understands. Here it is the specification: anyone reading the diagram knows the retry policy without digging through queue configurations.\n\n**Final state convergence.** `Delivered`, `Refunded`, and `Cancelled` all transition to the same `final` pseudo-state. In implementation, "final" might mean the order record is archived, the event bus receives an `order.closed` event, and no further state transitions are accepted. The model is silent on what happens after final \u2014 that\'s intentional. The state machine is done; downstream processes (analytics, accounting, data retention) are separate concerns.'
+  },
+  {
+    "slug": "state-traffic-light",
+    "diagram": "state",
+    "title": "Traffic light (state diagram)",
+    "description": "A three-state finite state machine for a traffic signal \u2014 Red, Green, Yellow \u2014 with timer-driven transitions and a power_off exit to a final state. Introduces UML initial and final pseudo-states, transition labels, and the cyclic structure that makes state diagrams the right tool for reactive systems.",
+    "standard": "OMG UML 2.5.1 \xA714",
+    "tags": [
+      "state",
+      "uml",
+      "fsm",
+      "state-machine",
+      "embedded",
+      "reactive"
+    ],
+    "complexity": 1,
+    "featured": true,
+    "dsl": 'state "Traffic Light"\n\ninitial i\nfinal f\n\ni -> Red\nRed -> Green : timer\nGreen -> Yellow : timer\nYellow -> Red : timer\nRed -> f : power_off',
+    "notes": "The traffic light is to state diagrams what the pump loop is to P&IDs: every textbook uses it, every engineer has drawn it, and if you understand it you understand the grammar of every more complex model.\n\n**Why a state diagram and not a flowchart.** A flowchart for a traffic light would show a loop: start \u2192 Red \u2192 (timer fires?) \u2192 Green \u2192 (timer fires?) \u2192 Yellow \u2192 back to Red. That works for describing an algorithm, but it misses the essential question: *what is the system doing right now?* A state machine makes the current state a first-class concept. The traffic light is not executing a loop \u2014 it *is* Red, or it *is* Green. Transitions are events that change what it is. This distinction matters the moment you add complexity: \"what happens if a pedestrian button is pressed while we're in Green?\" You answer that by looking at the transitions out of Green, not by tracing a flowchart path.\n\n**UML pseudo-states.** The filled black circle (`initial i`) and the bull's-eye circle (`final f`) are pseudo-states \u2014 they are not real states the system can dwell in, just notational entry and exit points. The initial pseudo-state shows where the machine starts; the arrow from `i` to Red tells you Red is the first real state. The final pseudo-state shows where the machine terminates. In the traffic light, termination is the `power_off` event from Red \u2014 the system shuts down from the Red state only (it wouldn't be safe to power off mid-Green).\n\n**Transition labels.** Each arrow is labeled with the trigger event that causes the transition. `timer` means \"the countdown for this phase has elapsed.\" In a real embedded implementation, this would be a hardware timer interrupt or a software watchdog expiry. Schematex doesn't execute the state machine \u2014 it renders the model. The labels are free text; you write exactly what your system calls the event.\n\n**Cyclic structure.** The three main states form a cycle: Red \u2192 Green \u2192 Yellow \u2192 Red. Most state diagrams describing continuous systems have cycles \u2014 the system runs until something external stops it. The `power_off` transition is the only way to reach the final state, and it is only modeled on Red because that is the safe state to stop in. If you wanted to model an emergency override (traffic officer stops the light mid-cycle), you would add `power_off` transitions from Green and Yellow too.\n\n**From model to code.** A UML state diagram maps directly to an enum + switch statement, a state table, or a state-machine framework (XState, Boost.MSM, Qt State Machine). The diagram is the specification; the implementation strategy is separate. Generating this diagram from a DSL means you can keep the spec in version control alongside the code, diff it in PRs, and regenerate it from an LLM prompt when requirements change."
+  },
   {
     "slug": "timeline-company-milestones",
     "diagram": "timeline",
@@ -1711,6 +1827,10 @@ var SYNTAX = {
     "title": "UML Use Case Diagram",
     "content": '## 1. Your first diagram\n\nEvery document starts with the `usecase` keyword, then a header, then declarations and relationships:\n\n```\nusecase\nsystem: "Library"\n\nactor: Member\nusecase: "Borrow Book" as Borrow\n\nMember -- Borrow\n```\n\n`actor:` declares an actor (a stick figure), `usecase:` declares a use case (an ellipse), and `Member -- Borrow` draws a plain association between them. `system:` wraps the use cases in a labelled **subject** rectangle. The primary actor is placed on the left; supporting actors on the right.\n\nThe header accepts:\n\n- `title: "\u2026"` \u2014 a heading drawn above the diagram.\n- `system: "\u2026"` \u2014 the subject (system boundary) name. Omit it to let the use cases float free (Schematex warns if you omit it with \u22653 use cases).\n- `direction: LR | TB` \u2014 default `LR` (actors flank the subject horizontally).\n- `generalization: tree | individual` \u2014 whether to merge sibling generalization arrows (default `tree`).\n\n---\n\n## 2. Actors\n\n```\nactor: Customer\nactor: "Payment Gateway" as PG (external)\nactor: "Warehouse Staff" as WH\nactor: Admin (left)\n```\n\n- A bare or `"quoted"` name becomes the label; `as ID` gives it a short identifier for relationships.\n- `(external)` (or `(system)`) renders the actor as a **rectangle with an `\xABactor\xBB` stereotype** instead of a stick figure \u2014 use it for other software systems (payment gateways, third-party APIs).\n- `(business)` adds the Bittner & Spence diagonal slash across the stick figure.\n- `(left)` / `(right)` pins the actor to a side. By default the first actor goes left and the rest go right.\n\nCustom stereotypes go in guillemets after the declaration: `actor: "Audit Service" as Audit (external) \xABsystem\xBB`. The parser also accepts ASCII `<<system>>` and normalises it to `\xABsystem\xBB`.\n\n---\n\n## 3. Use cases\n\n```\nusecase: "Checkout" as Checkout {\n  extension point: payment failed\n  extension point: stock depleted\n}\n```\n\nA use case is an ellipse sized to fit its text. The optional `{ \u2026 }` block lists **extension points** in a compartment below the name, separated by a divider line. Stereotypes work here too: `usecase: "Validate Card" as ValidateCard \xABsecured\xBB`.\n\n---\n\n## 4. Relationships\n\nFour line types connect actors and use cases:\n\n| DSL | Meaning | Rendering |\n|-----|---------|-----------|\n| `A -- B` | association | solid line, no arrow |\n| `A --> B` | directed association | solid line, open arrow at B |\n| `A ..> B` | `A` **includes** `B` | dashed line, open arrow \u2192 B, `\xABinclude\xBB` pill |\n| `A <.. B` | `A` **extends** `B` | dashed line, open arrow \u2192 B (the base), `\xABextend\xBB` pill |\n| `A --\\|> B` | `A` is a specialisation of `B` | solid line, hollow triangle \u2192 parent B |\n\n```\nCustomer -- Checkout\nCheckout ..> Pay          : \xABinclude\xBB\nPay      ..> ValidateCard : \xABinclude\xBB\nCancel   <.. Checkout     : \xABextend\xBB [payment failed] (extension point: payment failed)\n```\n\n- **`\xABinclude\xBB`** points *toward the included use case* \u2014 the reusable behavior `A` always runs. Source includes target.\n- **`\xABextend\xBB`** points *toward the base* \u2014 `A` is the optional behavior, `B` is the base it extends. You can attach a `[condition]` and reference one of the base\'s `(extension point: \u2026)` entries. (The arrowhead is always drawn toward the base regardless of how you order the endpoints.)\n- An `\xABextend\xBB` line is drawn in the theme **accent color** so the rarer, more surprising relationship stands out.\n\nThe parser rejects the high-confidence mistakes humans and LLMs both make, with the offending line number: association between two actors or two use cases, `include`/`extend` touching an actor, generalization across metaclasses (actor \u2192 use case), reused identifiers, and extension-point references that don\'t exist on the base.\n\n---\n\n## 5. Generalization\n\n`--|>` works between two actors **or** between two use cases (never across the two \u2014 that\'s a hard error):\n\n```\nactor: User as U\nactor: "Premium User" as PU\nPU --|> U\n\nusecase: "Pay by Card"   as PayCard\nusecase: "Pay by PayPal" as PayPaypal\nusecase: "Pay"           as Pay\nPayCard   --|> Pay\nPayPaypal --|> Pay\n```\n\nThe arrow carries a **hollow triangle** pointing at the parent. When three or more siblings share one parent, the arrows merge into a single shared head (UML 2.5 Figure 18.5 convention); set `generalization: individual` in the header to keep them separate. Actor hierarchies route as a clean bus on the outer edge of the actor stack.\n\n---\n\n## 6. Multiplicity\n\nQuote a multiplicity string immediately beside the endpoint it belongs to:\n\n```\nCustomer "1"    -- "*" Checkout\nCashier  "1..*" -- "1" Register\n```\n\n---\n\n## 7. PlantUML-style inline form\n\nComing from PlantUML? The inline declaration form works and mixes freely with the declarative form:\n\n```\nusecase\n:Customer: as C\n(Browse Catalog) as Browse\n(Add to Cart)    as AddCart\n\nC -- Browse\nC -- AddCart\nBrowse ..> AddCart : \xABinclude\xBB\n```\n\n`:Name:` declares an actor, `(Name)` declares a use case, and `as ID` aliases either. Schematex is *inspired by* PlantUML, not a 1:1 transpiler \u2014 multiplicity and relationship syntax differ slightly.\n\n---\n\n## 8. Grammar (EBNF)\n\n```text\ndocument     = "usecase" NEWLINE header_prop* statement*\nheader_prop  = ("title:" | "system:") quoted_string\n             | "direction:" ("LR" | "TB")\n             | "generalization:" ("tree" | "individual")\n\nstatement    = actor_decl | usecase_decl | plantuml_inline | relation | note\n\nactor_decl   = "actor" ":" name ("as" IDENT)? actor_kind? stereotype?\nactor_kind   = "(" ("external" | "system" | "business" | "left" | "right") ")"\nusecase_decl = "usecase" ":" quoted ("as" IDENT)? stereotype? extpoints?\nextpoints    = "{" ("extension point:" TEXT)+ "}"\nplantuml_inline = ":" name ":" ("as" IDENT)?      ; actor\n                | "(" name ")" ("as" IDENT)?       ; use case\n\nrelation     = endpoint relop endpoint label_clause?\nendpoint     = (IDENT | quoted) multiplicity? | multiplicity? (IDENT | quoted)\nrelop        = "--" | "-->" | "..>" | "<.." | "--|>"\nlabel_clause = ":" stereotype? condition? extpoint_ref?\nstereotype   = "\xAB" TEXT "\xBB" | "<<" TEXT ">>"\ncondition    = "[" TEXT "]"\nextpoint_ref = "(extension point:" TEXT ")"\nmultiplicity = quoted_string                       ; "1", "*", "0..1", "1..*"\n```\n\n---'
   },
+  "sequence": {
+    "title": "UML Sequence Diagram",
+    "content": '## 1. Your first diagram\n\nEvery document starts with the `sequence` keyword and an optional `"title"`. Participants don\'t need to be declared \u2014 the first time you mention one in a message, it becomes a lifeline:\n\n```\nsequence\n  Alice -> Bob : Authentication Request\n  Bob --> Alice : Authentication Response\n```\n\nLifelines appear left-to-right in first-use order. `->` is a synchronous call (solid line, filled arrowhead); `-->` is a reply (dashed line, open arrowhead). Text after `:` is the message label.\n\n---\n\n## 2. Participants\n\nDeclare a participant explicitly to set its **kind**, give it an **alias**, or fix its **order**:\n\n```\nsequence\n  actor User\n  participant Web as "Web App"\n  boundary LoginUI\n  control Auth\n  entity Account\n  database DB\n  collections Sessions\n  queue Events\n```\n\n| Kind | Rendered as |\n|------|-------------|\n| `participant` (default) | rounded classifier box |\n| `actor` | stick figure |\n| `boundary` / `control` / `entity` | the Jacobson robustness icons (\u22A2\u25EF / \u25EF with arrow / \u25EF with underline) |\n| `database` | cylinder |\n| `collections` / `queue` | box with the kind as a `\xABstereotype\xBB` |\n\n- `as "Label"` sets the display name (quotes optional; `\u300C\u2026\u300D` CJK quotes accepted).\n- A custom **stereotype** goes in guillemets or ASCII angle brackets after the declaration \u2014 it overrides the default label: `actor Printer \xABsystem\xBB`, `participant Bus as "Event Bus" <<service>>`.\n\n---\n\n## 3. Messages\n\nThe arrow token chooses the UML semantics:\n\n| DSL | Meaning | Rendering |\n|-----|---------|-----------|\n| `A -> B` | synchronous call | solid line, **filled** arrowhead |\n| `A ->> B` | asynchronous signal | solid line, **open** arrowhead |\n| `A --> B` | reply / return | **dashed** line, open arrowhead |\n| `A -x B` | lost message | line ending at a filled circle |\n| `o-> B` | found message | line starting from a filled circle |\n| `A -> A` | self message | bent loop back to the same lifeline |\n\nWhitespace around arrows is optional (`A->B` works), and labels are free text \u2014 including a return value, e.g. `aHotel -> aHotel : available(roomId, date): isRoom`.\n\n---\n\n## 4. Activations (execution specifications)\n\nThe thin bar on a lifeline shows it is active. Open and close it with explicit statements, or with `+` / `-` suffixes on the messages themselves:\n\n```\nsequence\n  participant Client\n  participant Server\n  Client ->+ Server : request()\n  Server ->> Server : validate()\n  Server -->- Client : response\n```\n\n`+` after the arrow activates the **receiver** on arrival; `-` deactivates the **sender** after the message is sent. The explicit form is `activate X` / `deactivate X`. Overlapping bars on one lifeline nest with a horizontal offset.\n\n---\n\n## 5. Object creation & destruction\n\n```\nsequence\n  participant Factory\n  Factory -> *Worker : \xABcreate\xBB\n  Factory -> Worker : work()\n  destroy Worker\n```\n\nPrefix the receiver with `*` to make the message **instantiate** it \u2014 the new lifeline\'s head is drawn at the arrival row, not at the top. `destroy X` ends a lifeline with a \u2715 and stops its time axis.\n\n---\n\n## 6. Combined fragments\n\nA combined fragment is a labelled frame around a region. Schematex implements the full UML `InteractionOperatorKind` set:\n\n| Operator | Meaning | Operands |\n|----------|---------|----------|\n| `alt` | alternatives (if/else-if/else) | `else`, each guarded |\n| `opt` | runs iff the guard holds | one, guarded |\n| `loop` | repeat | one; guard may be `(min,max)` |\n| `par` | concurrent operands | `and` |\n| `break` | exceptional exit | one, guarded |\n| `critical` | atomic / no interleaving | one |\n| `seq` / `strict` | weak / strict sequencing | `and` |\n| `neg` | invalid traces (rendered tinted) | one |\n| `ignore` / `consider` | message-set filter `{m1, m2}` | one |\n| `assert` | the only valid continuation | one |\n\n```\nsequence\n  actor User\n  participant API\n  User -> API : GET /resource\n  alt [authorized]\n    API --> User : 200 + body\n  else [forbidden]\n    API --> User : 403\n  end\n```\n\nGuards go in `[brackets]` after the operator (and after `else`). Fragments nest, and inner frames inset automatically so they sit cleanly inside their parent.\n\n---\n\n## 7. Interaction use (`ref`)\n\nReference another interaction instead of inlining it \u2014 the way UML keeps large diagrams composable:\n\n```\nsequence\n  participant A\n  participant B\n  ref over A, B : Establish session\n  A -> B : poll()\n```\n\n`ref over <lifelines> : Name` draws a framed box across the named lifelines. Most tools omit this; it\'s how real systems decompose long flows.\n\n---\n\n## 8. Notes, dividers, invariants, numbering\n\n```\nsequence\n  autonumber 1 1\n  actor Shopper\n  participant Cart\n  == Phase 1: review ==\n  Shopper -> Cart : view items\n  note over Cart : cart persisted in Redis\n  state Cart : ready\n```\n\n- `note over A` / `note over A, B` / `note left of A` / `note right of A` \u2014 folded-corner annotations.\n- `== text ==` \u2014 a full-width section divider.\n- `state X : text` \u2014 a state-invariant capsule on a lifeline.\n- `autonumber [start] [step]` \u2014 prefix every message with an incrementing number.\n\n---\n\n## 9. Grammar (EBNF)\n\n```text\ndiagram      = "sequence" [ string ] NEWLINE statement*\nstatement    = participant | message | activation | note\n             | fragment | ref | divider | invariant | destroy | autonumber\n\nparticipant  = kind IDENT ("as" label)? stereotype?\nkind         = "participant" | "actor" | "boundary" | "control"\n             | "entity" | "database" | "collections" | "queue"\nstereotype   = "\xAB" TEXT "\xBB" | "<<" TEXT ">>"\n\nmessage      = IDENT? act? arrow act? ("*")? IDENT? (":" TEXT)?\narrow        = "->" | "->>" | "-->" | "-x" | "o->"\nact          = "+" | "-"\nactivation   = ("activate" | "deactivate") IDENT\n\nfragment     = ("alt"|"opt"|"loop"|"par"|"break"|"critical"|"seq"\n               |"strict"|"neg"|"ignore"|"consider"|"assert") guard? NEWLINE\n                 statement* (("else"|"and") guard? NEWLINE statement*)* "end"\nguard        = "[" TEXT "]" | "(" NUMBER ("," NUMBER)? ")"\nref          = "ref" "over" IDENT ("," IDENT)* ":" TEXT\nnote         = "note" ("over"|"left of"|"right of") IDENT ("," IDENT)? ":" TEXT\ndivider      = "==" TEXT "=="\ninvariant    = "state" IDENT ":" TEXT\ndestroy      = "destroy" IDENT\nautonumber   = "autonumber" NUMBER? NUMBER?\n```\n\n---'
+  },
   "prisma": {
     "title": "PRISMA 2020 flow diagram",
     "content": '## 1. Your first diagram\n\nThe minimum is the four stage blocks. Counts are mandatory; the parser refuses to lay out a diagram with a missing total.\n\n```\nprisma\n\nidentification:\n  databases:\n    n: 1000\n\nscreening:\n  records-screened: 900\n  excluded:\n    n: 600\n\neligibility:\n  full-text-assessed: 300\n  excluded:\n    n: 250\n\nincluded:\n  studies: 50\n```\n\nIndentation is significant \u2014 **two spaces per level**, like genogram and SLD. The first non-blank line must be `prisma`. Comments use `#` or `//`.\n\n---\n\n## 2. Meta lines\n\nTop-level `key: value` lines, written before the stage blocks:\n\n```\nprisma\nmode: 2020-single\nkind: systematic-review\ntitle: My review\nvalidate-counts: warn\n```\n\n| Key | Values | Default | Meaning |\n|---|---|---|---|\n| `mode` | `2020-single` \xB7 `2020-dual` \xB7 `2009` | `2020-single` | Single column, or dual ("other methods") column. |\n| `kind` | `systematic-review` \xB7 `scoping-review` \xB7 `ipd` \xB7 `nma` | `systematic-review` | Swaps stage vocabulary (see \xA76). |\n| `title` | string | \u2014 | Rendered above the diagram. |\n| `validate-counts` | `warn` \xB7 `strict` \xB7 `off` | `warn` | Arithmetic checking (see \xA77). |\n| `direction` | `TB` / `TD` | `TB` | PRISMA is vertical by standard; horizontal is rejected. |\n\n---\n\n## 3. Identification\n\nThe `identification:` block holds a `databases:` sub-block (always) and an optional `other:` sub-block (dual mode).\n\n```\nidentification:\n  databases:\n    n: 1418\n    sources: PubMed=600, Embase=450, Cochrane=184\n    duplicates-removed: 318\n    ineligible-automation: 0\n    other-removed: 0\n```\n\n- `n:` \u2014 total records identified (**mandatory**).\n- `sources:` \u2014 `name=count` pairs, comma-separated. Rendered as an indented breakdown. Names with spaces or punctuation can be quoted: `"Web of Science"=184`.\n- `duplicates-removed:`, `ineligible-automation:`, `other-removed:` \u2014 optional removal counts. When any are present they render as a separate **"Records removed before screening"** box in the right column, connected by a horizontal arrow.\n\nLarge numbers may use commas: `n: 1,418` is the same as `n: 1418`.\n\n---\n\n## 4. Screening & Eligibility\n\nBoth stages carry a main count plus an `excluded:` block. The excluded block has its own `n:` and an optional `reasons:` breakdown.\n\n```\nscreening:\n  records-screened: 1100\n  excluded:\n    n: 870\n    reasons: irrelevant title=750, non-English=120\n  reports-sought: 226        # optional\n  reports-not-retrieved: 12  # optional\n\neligibility:\n  full-text-assessed: 230\n  excluded:\n    n: 195\n    reasons: wrong population=80, wrong intervention=60, wrong outcome=55\n```\n\n`reasons:` are `name=count` pairs. If you list more than 8, the renderer sorts them descending and aggregates the tail as `Other (n = \u2026)` so the side-box stays readable.\n\n---\n\n## 5. Included\n\n```\nincluded:\n  studies: 35\n  reports: 38          # one study may yield several reports\n  participants: 28741  # PRISMA-IPD only\n```\n\n`studies:` is mandatory. `reports:` and `participants:` are optional extra count lines.\n\n---\n\n## 6. Dual pipeline & review kinds\n\n**Dual pipeline** \u2014 the PRISMA 2020 update added a second "Identification via other methods" column (citation searching, hand searches, expert recommendations). Add an `other:` block; the two columns merge into Screening via a Y-junction.\n\n```\nprisma\nmode: 2020-dual\n\nidentification:\n  databases:\n    n: 1234\n    duplicates-removed: 254\n  other:\n    n: 56\n    sources: citation-search=30, hand-search=20, expert-recommendation=6\n\nscreening:\n  records-screened: 1036\n  excluded:\n    n: 810\n\neligibility:\n  full-text-assessed: 226\n  excluded:\n    n: 195\n\nincluded:\n  studies: 31\n```\n\n**Scoping review** \u2014 `kind: scoping-review` swaps "studies" \u2192 "sources of evidence" and re-labels the stages per Tricco et al. 2018, without changing geometry.\n\n**Updated review** \u2014 an optional `previous-studies:` block draws a dashed box on top that feeds into the identification section:\n\n```\nprevious-studies:\n  n: 19\n  sources: previous review=19\n```\n\n---\n\n## 7. Count arithmetic validation\n\nWith `validate-counts: warn` (default) the engine checks that the counts reconcile across stages \u2014 e.g. `databases.n + other.n \u2212 duplicates-removed = records-screened`, and that source/reason breakdowns sum to their totals. Mismatches render a small warning under the diagram (also surfaced in the SVG `<desc>` for screen readers).\n\n`validate-counts: strict` turns a mismatch into a parse error with an "off by N" message. `off` skips checking entirely.\n\n---\n\n## 8. Grammar (EBNF)\n\n```\nprisma-document  = "prisma", { meta-line }, stage-block, { stage-block } ;\nmeta-line        = ("mode:" | "kind:" | "title:" | "review-id:" | "validate-counts:" | "direction:") value ;\n\nstage-block      = previous-block | identification-block | screening-block | eligibility-block | included-block ;\n\nprevious-block       = "previous-studies:" , indent, "n:" int, [ "reports:" int ], { "sources:" pairs } ;\nidentification-block = "identification:" , indent,\n                         "databases:" , indent, "n:" int, { "sources:" pairs },\n                           [ "duplicates-removed:" int ], [ "ineligible-automation:" int ], [ "other-removed:" int ],\n                         [ "other:" , indent, "n:" int, { "sources:" pairs } ] ;\nscreening-block      = "screening:" , indent, "records-screened:" int,\n                         "excluded:" , indent, "n:" int, { "reasons:" pairs },\n                         [ "reports-sought:" int ], [ "reports-not-retrieved:" int ] ;\neligibility-block    = "eligibility:" , indent, "full-text-assessed:" int,\n                         "excluded:" , indent, "n:" int, { "reasons:" pairs } ;\nincluded-block       = "included:" , indent, "studies:" int, [ "reports:" int ], [ "participants:" int ] ;\n\npairs            = pair, { "," pair } ;\npair             = (string | quoted) "=" int ;\nint              = digit, { digit | "," } ;     (* commas stripped: 1,234 == 1234 *)\n```\n\nIndentation is two spaces per level. Unknown keys inside a stage block are a parse error, keeping each stage well-defined.\n\n---'
@@ -1748,11 +1868,345 @@ function getExamplesForType(type, opts = {}) {
   return sorted.slice(0, limit);
 }
 
+// src/ai/profiles.ts
+var COMMON_GENERATION_RULES = [
+  "Generate one diagram document with one selected diagram type.",
+  "Use the canonical header and canonical forms from the generation profile first.",
+  'Use ASCII double quotes (") for generated labels and titles.',
+  "Do not emit DSL comments unless the user explicitly asks for annotated source.",
+  "Prefer explicit IDs and declarations when they make validation less ambiguous.",
+  "Call validateDsl with the explicit selected type, fix reported errors, and validate again before returning DSL."
+];
+var PROFILES = {
+  genogram: {
+    type: "genogram",
+    header: 'genogram "Title"',
+    mode: "family declarations + indented children",
+    forms: [
+      "personId [sex, birthYear, optionalAttrs]",
+      'parentA -- parentB "optional relationship label"',
+      "indent children under the couple line"
+    ],
+    prefer: ["Declare people before emotional relationships.", 'Use `[label: "..."]` only where the syntax reference shows a label attribute.'],
+    avoid: ["Avoid inline comments and speculative relationship operators."],
+    repair: ["Unknown individuals usually need a declaration before the relationship line."]
+  },
+  ecomap: {
+    type: "ecomap",
+    header: 'ecomap "Title"',
+    mode: "center + external systems",
+    forms: [
+      'center: client [label: "Client"]',
+      'systemId [label: "System", category: family]',
+      'systemId === client [label: "support"]'
+    ],
+    prefer: ["Declare exactly one center.", "Declare outside systems before their connection lines."],
+    avoid: ["Avoid borrowing genogram operators such as `--`."],
+    repair: ["A valid render with a missing center is semantically wrong; add `center:` first."]
+  },
+  pedigree: {
+    type: "pedigree",
+    header: 'pedigree "Title"',
+    mode: "clinical pedigree",
+    forms: [
+      "personId [sex, generationAttrs]",
+      "parentA -- parentB",
+      "indent offspring under the couple line"
+    ],
+    prefer: ["Use pedigree status/trait attributes from the syntax reference.", "Keep generation structure explicit."],
+    avoid: ["Avoid genogram emotional-relationship lines in pedigree output."],
+    repair: ["Declare every referenced individual before relationships."]
+  },
+  phylo: {
+    type: "phylo",
+    header: 'phylo "Title"',
+    mode: "quoted Newick",
+    forms: ['newick: "((A:0.1,B:0.2),C:0.3);"', 'clade Group = (A, B) [label: "Group"]'],
+    prefer: ["Use Newick for first-shot generation.", "Quote the Newick string."],
+    avoid: ["Avoid indent-tree mode unless the user wants a hand-authored tree."],
+    repair: ["A phylo document needs exactly one tree definition: Newick or indent tree."]
+  },
+  sociogram: {
+    type: "sociogram",
+    header: 'sociogram "Title"',
+    mode: "declared nodes + social ties",
+    forms: ['nodeId [label: "Person"]', 'nodeA -> nodeB [label: "choice"]', "config: layout = circular"],
+    prefer: ["Declare actors first.", "Use one supported layout/config value at a time."],
+    avoid: ["Avoid unknown config values; some adapters keep defaults."],
+    repair: ["Unknown edge endpoints need matching node declarations."]
+  },
+  timing: {
+    type: "timing",
+    header: 'timing "Title"',
+    mode: "WaveDrom-compatible signals",
+    forms: ["CLK: pppppppp", 'DATA: x======x data: ["A", "B"]'],
+    prefer: ["Keep wave strings contiguous with no internal spaces.", "Use `data:` labels for bus segments."],
+    avoid: ["Avoid unsupported WaveDrom annotation syntax."],
+    repair: ["Invalid wave strings usually contain a character outside the timing wave table."]
+  },
+  logic: {
+    type: "logic",
+    header: 'logic "Title"',
+    mode: "logic netlist",
+    forms: ["INPUT A, B", "G1 = AND(A, B)", "OUTPUT Y = G1"],
+    prefer: ["Use canonical gate names and explicit inputs/outputs."],
+    avoid: ["Avoid circuit component names inside logic diagrams."],
+    repair: ["Unknown gate kinds should be replaced with the closest listed logic primitive."]
+  },
+  circuit: {
+    type: "circuit",
+    header: 'circuit "Title" netlist',
+    mode: "SPICE-style netlist",
+    forms: ["V1 vcc 0 5V", "R1 vcc out 10k", "C1 out 0 100n"],
+    prefer: ["Use netlist mode for generated schematics unless geometry is the task.", "Add explicit `type=` when an ID prefix is ambiguous."],
+    avoid: ["Avoid positional cursor routing (`wire`, `at:`) for first-shot output."],
+    repair: ["If a component type or pin count is ambiguous, make the symbol type explicit."]
+  },
+  blockdiagram: {
+    type: "blockdiagram",
+    header: 'blockdiagram "Title"',
+    mode: "blocks, sums, signals",
+    forms: ['ctrl = block("PID") [role: controller]', "err = sum(+r, -y)", "err -> ctrl -> plant"],
+    prefer: ["Use named blocks and directed `->` chains."],
+    avoid: ["Avoid unlabeled feedback intent; model the summing junction."],
+    repair: ["Connections must point at declared blocks, sums, signals, or boundary IDs."]
+  },
+  ladder: {
+    type: "ladder",
+    header: 'ladder "Title"',
+    mode: "rungs + IEC/Rockwell elements",
+    forms: ['rung 1 "Run motor":', "  XIC(START_PB)", "  OTE(MOTOR_RUN)"],
+    prefer: ["Use uppercase element names.", "Use `parallel:` + `branch:` only for OR branches."],
+    avoid: ["Avoid variable declarations and ST syntax."],
+    repair: ["Element typos are repairable from parser suggestions; keep the tag in parentheses."]
+  },
+  sld: {
+    type: "sld",
+    header: 'sld "Title"',
+    mode: "equipment assignments + power-flow edges",
+    forms: ['util = utility [label: "Grid"]', 'xfmr = transformer [rating: "500 kVA"]', "util -> xfmr -> load is not allowed; use one edge per line"],
+    prefer: ["Declare equipment as `id = nodeType [attrs]`.", "Use one `from -> to` connection per line."],
+    avoid: ["Avoid generic flowchart node syntax."],
+    repair: ["Unknown equipment types often have a suggested canonical type or alias."]
+  },
+  entity: {
+    type: "entity",
+    header: 'entity-structure "Title"',
+    mode: "legal entities + ownership edges",
+    forms: ['entity holdco "HoldCo" corp@US', 'entity opco "OpCo" llc@DE', "holdco -> opco : 100%"],
+    prefer: ["Use `entity` declarations before ownership edges.", "Keep legal form and jurisdiction explicit when known."],
+    avoid: ["Avoid database schema terminology; use `erd` for tables and FKs."],
+    repair: ["Unknown ownership endpoints need entity declarations."]
+  },
+  fishbone: {
+    type: "fishbone",
+    header: 'fishbone "Title"',
+    mode: "effect + cause categories",
+    forms: ['effect "Late Delivery"', 'category process "Process"', 'process: "Handoff delay"'],
+    prefer: ["Use one effect and structured categories for generated DSL."],
+    avoid: ["Avoid mixing compact alien syntax when a structured category form works."],
+    repair: ["If a cause lands nowhere, add or reference its category explicitly."]
+  },
+  venn: {
+    type: "venn",
+    header: 'venn "Title"',
+    mode: "declared-set region counts",
+    forms: ['set A "Group A"', 'set B "Group B"', "A & B : 120", "A only : 80"],
+    prefer: ["Use declared sets plus region counts for first-shot Venn output.", "Use Euler relations only when subset/disjoint structure is the request."],
+    avoid: ["Avoid mixing enumeration mode with explicit region counts."],
+    repair: ["Declare every set before region or Euler relation lines."]
+  },
+  flowchart: {
+    type: "flowchart",
+    header: 'flowchart TD "Title"',
+    mode: "Mermaid-compatible nodes + edges",
+    forms: ["start([Start]) --> check{Decision?}", "check -->|Yes| done([Done])"],
+    prefer: ["Choose one direction in the header.", "Declare shapes explicitly when shape matters."],
+    avoid: ["Avoid subgraph complexity unless grouping is part of the request."],
+    repair: ["A bad header direction fails early; use TD, TB, BT, LR, or RL."]
+  },
+  mindmap: {
+    type: "mindmap",
+    header: "mindmap",
+    mode: "Markdown headings + bullets",
+    forms: ["# Root", "## Branch", "- Child item"],
+    prefer: ["Use exactly one `#` root heading.", "Use bullets/headings instead of graph edges."],
+    avoid: ["Avoid comments in the body."],
+    repair: ["An orphan branch means the root `#` heading is missing."]
+  },
+  matrix: {
+    type: "matrix",
+    header: 'matrix "Title"',
+    mode: "quadrant scatter",
+    forms: ["x-axis: Low -> High", "y-axis: Low -> High", '"Item" at (0.25, 0.8)'],
+    prefer: ["Use quadrant scatter for first-shot prioritization/portfolio requests.", "Use built-in templates when the framework is named."],
+    avoid: ["Avoid heatmap, correlation, and table modes unless the user asks for that form."],
+    repair: ["Point coordinates are normalized fractions; keep them in `[0,1]`."]
+  },
+  orgchart: {
+    type: "orgchart",
+    header: 'orgchart "Title"',
+    mode: "indented hierarchy",
+    forms: ['ceo: "Name" | CEO', '  cto: "Name" | CTO', '    eng: "Name" | Engineer'],
+    prefer: ["Use indentation for the reporting tree.", "Use dotted explicit edges only for matrix reporting."],
+    avoid: ["Avoid mixing explicit report edges with indentation unless needed."],
+    repair: ["Duplicate IDs and unknown explicit edge endpoints are parse failures."]
+  },
+  decisiontree: {
+    type: "decisiontree",
+    header: 'decisiontree "Title"',
+    mode: "taxonomy questions",
+    forms: ['question "Question?"', '  yes: answer "Outcome"', '  no: answer "Other outcome"'],
+    prefer: ["Use taxonomy mode for troubleshooting and triage.", "Select `decisiontree:decision` or `decisiontree:ml` only when expected value or ML is explicit."],
+    avoid: ["Avoid mixing mode-specific keywords."],
+    repair: ["Indent each child under its parent and use the branch prefix required by the selected mode."]
+  },
+  timeline: {
+    type: "timeline",
+    header: 'timeline "Title"',
+    mode: "dated events",
+    forms: ['2026-05-22: "Event"', '2026-06-01 - 2026-06-30: "Phase"', '2026-07-01: milestone "Launch"'],
+    prefer: ["Use dated events/ranges and `milestone` for important points."],
+    avoid: ["Avoid custom row keys when a date is known."],
+    repair: ["Quote labels and keep the colon after the date/range."]
+  },
+  state: {
+    type: "state",
+    header: 'state "Title"',
+    mode: "Schematex statechart core",
+    forms: ["initial Start", "Start --> Running : event", "Running --> Done", "final Done"],
+    prefer: ["Use `state` header for generated DSL.", "Use Mermaid `stateDiagram-v2` only when adapting Mermaid input."],
+    avoid: ["Avoid composite/concurrent-state syntax until the request needs it."],
+    repair: ["Use `-->` transitions and a named state between initial/final aliases."]
+  },
+  pid: {
+    type: "pid",
+    header: 'pid "Title"',
+    mode: "equipment + process lines",
+    forms: ["equip T-101 : tank_atm", "equip P-101 : pump_centrifugal", "line L1 from T-101.bottom to P-101.in"],
+    prefer: ["Declare equipment first, then process/signal lines."],
+    avoid: ["Avoid SLD electrical nodes in a P&ID."],
+    repair: ["Unknown equipment and instrument categories must come from the catalog."]
+  },
+  erd: {
+    type: "erd",
+    header: "erd",
+    mode: "table blocks + named cardinality refs",
+    forms: ["table User { id int PK; email varchar }", "table Order { id int PK; user_id int FK -> User.id }", "ref Order.user_id many-mandatory -- one-mandatory User.id"],
+    prefer: ["Use named cardinality tokens for generated refs.", "Keep FK targets explicit."],
+    avoid: ["Avoid Mermaid cardinality glyphs unless converting Mermaid input."],
+    repair: ["Unknown cardinality tokens and unterminated table blocks fail validation."]
+  },
+  breadboard: {
+    type: "breadboard",
+    header: "breadboard",
+    mode: "parts + wires blocks",
+    forms: ['title: "Prototype"', "parts", "wires"],
+    prefer: ["Use physical parts and addressable tie points.", "Keep schematic tasks on `circuit` instead."],
+    avoid: ["Avoid abstract netlist syntax in breadboard output."],
+    repair: ["Missing parts or invalid breadboard connection endpoints need the breadboard syntax reference."]
+  },
+  bpmn: {
+    type: "bpmn",
+    header: "bpmn",
+    mode: "pool/lane objects + flows",
+    forms: ['pool "Service" {', '  lane "Worker" { A: start "Request" }', "flows", "A --> B"],
+    prefer: ["Use pools, lanes, and a `flows` block.", "Use `~~>` only for cross-pool message flow."],
+    avoid: ["Avoid generic flowchart syntax for BPMN semantics."],
+    repair: ["Sequence flows cannot cross pools; switch to message flow when needed."]
+  },
+  fbd: {
+    type: "fbd",
+    header: 'fbd "Title"',
+    mode: "networks + blocks",
+    forms: ["var Start: bool", 'network "Logic":', "Motor = AND(Start, Safe)"],
+    prefer: ["Use network/expression forms from the FBD syntax guide."],
+    avoid: ["Avoid ladder rung syntax in FBD output."],
+    repair: ["Invalid block calls need a supported block and valid arguments."]
+  },
+  sfc: {
+    type: "sfc",
+    header: 'sfc "Title"',
+    mode: "steps + transitions",
+    forms: ["step Idle [initial]", "transition Idle -> Run : Start", "step Run"],
+    prefer: ["Use explicit steps and transitions before alternative/simultaneous branches."],
+    avoid: ["Avoid UML state syntax in SFC output."],
+    repair: ["Every transition step reference must resolve to a declared step."]
+  },
+  prisma: {
+    type: "prisma",
+    header: "prisma",
+    mode: "PRISMA 2020 single pipeline",
+    forms: ["identification:", "  databases:", "    n: 1000", "screening:", "included:"],
+    prefer: ["Use the required four stages and mandatory counts.", "Use single-pipeline 2020 mode unless other-methods data is present."],
+    avoid: ["Avoid generic flowchart boxes for PRISMA requests."],
+    repair: ["Missing stage blocks or mandatory `n` fields are intentional parser errors."]
+  },
+  usecase: {
+    type: "usecase",
+    header: "usecase",
+    mode: "declarative UML use cases",
+    forms: ['system: "System"', "actor: Customer", 'usecase: "Checkout" as Checkout', "Customer -- Checkout"],
+    prefer: ["Use declarative actor/usecase lines for generated DSL."],
+    avoid: ["Avoid PlantUML inline form unless converting PlantUML-like input."],
+    repair: ["Include/extend relations must connect use cases, not actors."]
+  },
+  pert: {
+    type: "pert",
+    header: "pert",
+    mode: "AON tasks + dependencies",
+    forms: ['task A "Spec" duration: 3', 'task B "Build" duration: 8 after: A'],
+    prefer: ["Use AON network tasks first.", "Use time-scaled/AOA layouts only when requested."],
+    avoid: ["Avoid writing computed ES/EF/LS/LF fields yourself."],
+    repair: ["Task IDs must exist before they are used in `after:` lists."]
+  },
+  sequence: {
+    type: "sequence",
+    header: 'sequence "Title"',
+    mode: "participants + messages",
+    forms: ["actor User", 'participant API as "API"', "User -> API : request", "API --> User : response"],
+    prefer: ["Start with participants/messages, then add fragments only if control flow matters."],
+    avoid: ["Avoid Mermaid `sequenceDiagram` header; this parser uses `sequence`."],
+    repair: ["Unmatched `end`, `else`, or activation statements are validation failures."]
+  }
+};
+function getGenerationProfile(type) {
+  return PROFILES[type];
+}
+
 // src/ai/syntax.ts
-function getSyntaxForType(syntaxKey) {
+function getSyntaxForType(syntaxKey, type, detail = "canonical") {
   const s = SYNTAX[syntaxKey];
   if (!s) return void 0;
-  return { key: syntaxKey, ...s };
+  return {
+    key: syntaxKey,
+    title: s.title,
+    detail,
+    content: detail === "reference" ? s.content : buildCanonicalSyntax(getGenerationProfile(type))
+  };
+}
+function buildCanonicalSyntax(profile) {
+  return [
+    "# Canonical generation syntax",
+    "",
+    'Use this compact path for new DSL generation. Ask for `detail: "reference"` only when the request needs advanced forms or an imported adapter.',
+    "",
+    "## Generation profile",
+    "",
+    `- Canonical type: \`${profile.type}\``,
+    `- Canonical header: \`${profile.header}\``,
+    `- Preferred mode: ${profile.mode}`,
+    bulletSection("Core forms", profile.forms),
+    bulletSection("Prefer", profile.prefer),
+    bulletSection("Avoid by default", profile.avoid),
+    bulletSection("Repair checks", profile.repair),
+    "## Shared generation rules",
+    "",
+    ...COMMON_GENERATION_RULES.map((rule) => `- ${rule}`)
+  ].filter((part) => part !== "").join("\n");
+}
+function bulletSection(title, items) {
+  return [`### ${title}`, "", ...items.map((item) => `- ${item}`), ""].join("\n");
 }
 
 // src/ai/tools.ts
@@ -1766,14 +2220,14 @@ function listDiagrams() {
     standard: d.standard
   }));
 }
-function getSyntax(type) {
+function getSyntax(type, opts = {}) {
   const meta = getDiagramMeta(type);
   if (!meta) {
     throw new Error(
       `Unknown diagram type '${type}'. Call listDiagrams() for valid types.`
     );
   }
-  const syntax = getSyntaxForType(meta.syntaxKey);
+  const syntax = getSyntaxForType(meta.syntaxKey, meta.type, opts.detail);
   if (!syntax) {
     throw new Error(`No syntax doc available for '${type}' (key: ${meta.syntaxKey}).`);
   }
@@ -1795,38 +2249,66 @@ function getExamples(type, opts = {}) {
   return { type: meta.type, count: examples.length, examples };
 }
 function validateDsl(type, dsl) {
-  const config = type ? { type } : void 0;
-  try {
-    chunk3YUUC6RN_cjs.parse(dsl, config);
-    return { ok: true, type: type ?? resolveTypeFromText(dsl) };
-  } catch (err) {
-    return {
-      ok: false,
-      type: type ?? resolveTypeFromText(dsl),
-      errors: [extractError(err)]
-    };
+  const resolvedType = type ? resolveDiagramType(type) : void 0;
+  const config = type ? { type: resolvedType ?? type } : void 0;
+  const result = chunk4QPDZJAL_cjs.parseResult(dsl, config);
+  if (result.ok) {
+    return { ok: true, type: result.type };
   }
+  return {
+    ok: false,
+    type: result.type ?? resolvedType ?? resolveTypeFromText(dsl),
+    errors: result.diagnostics.map(
+      (diagnostic) => toValidationError(diagnostic, result.type ?? resolvedType)
+    )
+  };
 }
 function renderDsl(type, dsl, options = {}) {
+  const resolvedType = type ? resolveDiagramType(type) : void 0;
   const config = {
     ...options,
-    ...type ? { type } : {}
+    ...type ? { type: resolvedType ?? type } : {}
   };
-  try {
-    const svg = chunk3YUUC6RN_cjs.render(dsl, config);
-    return { ok: true, type: type ?? resolveTypeFromText(dsl), svg };
-  } catch (err) {
+  const result = chunk4QPDZJAL_cjs.renderResult(dsl, config);
+  if (result.ok) {
     return {
-      ok: false,
-      type: type ?? resolveTypeFromText(dsl),
-      errors: [extractError(err)]
+      ok: true,
+      status: result.status,
+      type: result.type,
+      svg: result.svg
     };
   }
+  return {
+    ok: false,
+    status: result.status,
+    type: result.type ?? resolvedType ?? resolveTypeFromText(dsl),
+    svg: result.svg,
+    errors: result.diagnostics.map(
+      (diagnostic) => toValidationError(diagnostic, result.type ?? resolvedType)
+    )
+  };
 }
 function resolveTypeFromText(text) {
   const first = text.trim().split(/\s+|\n/)[0]?.toLowerCase() ?? "";
-  const meta = DIAGRAM_REGISTRY.find((d) => d.type === first);
-  return meta?.type ?? null;
+  return resolveDiagramType(first) ?? null;
+}
+function toValidationError(diagnostic, type) {
+  return {
+    line: diagnostic.line,
+    column: diagnostic.column,
+    source: diagnostic.source,
+    message: diagnostic.message,
+    hint: diagnostic.hint ?? repairHint(type)
+  };
+}
+function repairHint(type) {
+  const resolved = type ? resolveDiagramType(type) : void 0;
+  const profile = resolved ? getGenerationProfile(resolved) : void 0;
+  const typeHint = profile?.repair[0];
+  return [
+    typeHint,
+    "Fix the reported DSL error, then call validateDsl again before rendering or returning DSL."
+  ].filter(Boolean).join(" ");
 }
 
 exports.DIAGRAM_REGISTRY = DIAGRAM_REGISTRY;
@@ -1836,6 +2318,7 @@ exports.getExamples = getExamples;
 exports.getSyntax = getSyntax;
 exports.listDiagrams = listDiagrams;
 exports.renderDsl = renderDsl;
+exports.resolveDiagramType = resolveDiagramType;
 exports.validateDsl = validateDsl;
-//# sourceMappingURL=chunk-NWPCY65Z.cjs.map
-//# sourceMappingURL=chunk-NWPCY65Z.cjs.map
+//# sourceMappingURL=chunk-HK56GQQP.cjs.map
+//# sourceMappingURL=chunk-HK56GQQP.cjs.map