@diagrammo/dgmo 0.32.1 → 0.34.0

package/docs/ai-integration.md

@@ -64,6 +64,7 @@ LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the
 - **Show-everything is the default.** Every label / value / percent renders by default. Emit `no-name` / `no-value` / `no-percent` / `no-*` ONLY when the user explicitly asks to hide something — never defensively.
 - **`//` comments only** (never `#`). **Indentation closes blocks** — never `end`.
 - **Declare before reference.** An edge target must be declared on a prior line; put metadata and edges on/under one declaration to avoid `Duplicate node` warnings.
+- **No reference scaffolding in output.** Emit only DGMO source. This doc is organized with HTML-comment anchors (the `TYPE`, `TIPS`, and `AI-CORE` markers, each wrapped in comment delimiters); never copy any such `<!-- … -->` comment into a diagram. They mark sections of the docs, not DGMO syntax; the parser flags a stray HTML comment as an `Unexpected line` warning. (DGMO's only comment form is `//`.)
 
 Two traps in the *other* direction (DGMO wants a colon / a space where you might not expect):
 
@@ -90,8 +91,12 @@ Billing t: Product
 
 Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply these unless the prompt says otherwise:
 
-- **Title it.** Put a short title on the type-declaration line (`flowchart Checkout Flow`, `boxes-and-lines Service Map`) so the diagram is self-describing.
-- **Color by grouping, not at random.** When items fall into categories, declare a tag group and assign members so each category shares one color — far clearer than ad-hoc per-node colors. Use the tag-group syntax shown in the per-type section below (declare `tag Team as t`, indent the values — a trailing color is optional, bare values auto-pick a palette color — then assign `Node t: Team`). Only the 11 named palette colors exist.
+<!-- TITLE start -->
+- **Always title it.** Every diagram gets a short title on the type-declaration line (`flowchart Checkout Flow`, `sequence Checkout`, `boxes-and-lines Service Map`) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none.
+<!-- TITLE end -->
+<!-- CATEGORIZE start -->
+- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>`, then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have *fewer* values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
+<!-- CATEGORIZE end -->
 - **Keep labels short.** A few words per node. Move detail into notes or metadata, never a full sentence inside a label.
 - **Let the defaults show.** Don't add `no-*` opt-outs unless the user asked to hide or disable something — they strip helpful labels, values, and color.
 - **Pick a fitting direction.** Top-to-bottom for hierarchies and processes; left-to-right for pipelines and flows (where the type supports a direction).

package/docs/language-reference.md

@@ -60,6 +60,7 @@ LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the
 - **Show-everything is the default.** Every label / value / percent renders by default. Emit `no-name` / `no-value` / `no-percent` / `no-*` ONLY when the user explicitly asks to hide something — never defensively.
 - **`//` comments only** (never `#`). **Indentation closes blocks** — never `end`.
 - **Declare before reference.** An edge target must be declared on a prior line; put metadata and edges on/under one declaration to avoid `Duplicate node` warnings.
+- **No reference scaffolding in output.** Emit only DGMO source. This doc is organized with HTML-comment anchors (the `TYPE`, `TIPS`, and `AI-CORE` markers, each wrapped in comment delimiters); never copy any such `<!-- … -->` comment into a diagram. They mark sections of the docs, not DGMO syntax; the parser flags a stray HTML comment as an `Unexpected line` warning. (DGMO's only comment form is `//`.)
 
 Two traps in the *other* direction (DGMO wants a colon / a space where you might not expect):
 
@@ -88,8 +89,12 @@ Billing t: Product
 
 Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply these unless the prompt says otherwise:
 
-- **Title it.** Put a short title on the type-declaration line (`flowchart Checkout Flow`, `boxes-and-lines Service Map`) so the diagram is self-describing.
-- **Color by grouping, not at random.** When items fall into categories, declare a tag group and assign members so each category shares one color — far clearer than ad-hoc per-node colors. Use the tag-group syntax shown in the per-type section below (declare `tag Team as t`, indent the values — a trailing color is optional, bare values auto-pick a palette color — then assign `Node t: Team`). Only the 11 named palette colors exist.
+<!-- TITLE start -->
+- **Always title it.** Every diagram gets a short title on the type-declaration line (`flowchart Checkout Flow`, `sequence Checkout`, `boxes-and-lines Service Map`) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none.
+<!-- TITLE end -->
+<!-- CATEGORIZE start -->
+- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>`, then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have *fewer* values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
+<!-- CATEGORIZE end -->
 - **Keep labels short.** A few words per node. Move detail into notes or metadata, never a full sentence inside a label.
 - **Let the defaults show.** Don't add `no-*` opt-outs unless the user asked to hide or disable something — they strip helpful labels, values, and color.
 - **Pick a fitting direction.** Top-to-bottom for hierarchies and processes; left-to-right for pipelines and flows (where the type supports a direction).
@@ -502,7 +507,7 @@ rarely benefit. Aliases should aid comprehension, not obscure it.
 <!-- TYPE:sequence -->
 
 <!-- TIPS start -->
-**Styling tips:** stay terse — participants are created by the messages that name them, so a plain flow needs only the arrow lines (no participant declarations). Skip `is a TYPE`: the glyph is inferred from the name (`User`→actor, `*DB`→database, `Redis`→cache, `Kafka`→queue); add a declaration, a `[Group]`, or `position: N` only when it genuinely aids reading order or grouping, never as boilerplate. Give each participant a short role name; group related exchanges under `== Section ==` dividers rather than a wall of arrows; label a return arrow only when its value matters (unlabeled returns are auto-pruned). Drop a `note` where something subtle happens. When participants fall into trust or role categories, color the participants (not the messages) by category with a tag group using the named palette colors, so the boundary reads at a glance.
+**Styling tips:** stay terse — participants are created by the messages that name them, so a plain flow needs only the arrow lines (no participant declarations). Skip `is a TYPE`: the glyph is inferred from the name (`User`→actor, `*DB`→database, `Redis`→cache, `Kafka`→queue); add a declaration, a `[Group]`, or `position: N` only when it genuinely aids reading order or grouping, never as boilerplate. Give each participant a short role name. Reach for `== Section ==` dividers only when the flow splits into **two or more** distinct phases (e.g. `== Authentication ==` then `== Checkout ==`) — a single divider over one run of arrows just repeats the diagram's subject and adds a redundant band, so a one-phase flow should have no dividers at all. Label a return arrow only when its value matters (unlabeled returns are auto-pruned). Drop a `note` where something subtle happens. Categorize the participants and color them (not the messages) by that category with a tag group using the named palette colors — client vs service vs datastore, trust zones (internal / external), or owning team are almost always present, so default to coloring by one rather than leaving the lifelines monochrome, and the boundaries read at a glance.
 <!-- TIPS end -->
 
 ### 2.1 Participants
@@ -1279,7 +1284,7 @@ Optional label: `--|> Vessel : extends` (colon optional before label)
 <!-- TYPE:kanban -->
 
 <!-- TIPS start -->
-**Styling tips:** name columns for workflow stages (`Todo`, `Doing`, `Done`); keep card titles to a short task phrase; color cards by owner or priority with a tag group; let column length convey WIP instead of annotating counts. If you use a tag group, tag EVERY card — an untagged card currently inherits the first tag value (mislabeling it), so omit the tag group entirely for an uncolored board.
+**Styling tips:** Color EVERY column — write a lowercase color word right after the closing bracket (`[Done] green`). Don't match on column names; reason about what each column *means* for a card sitting in it, then pick the color whose everyday connotation fits, so the board reads at a glance. The guiding sense: green = good / finished / success, red = bad / stuck / needs attention, yellow = waiting / caution / in review, blue = active work in motion, gray = inert / not yet started / parked. Apply that to whatever columns exist — e.g. a terminal success column reads green even if it's called `Shipped`, `Hired`, or `Live`; a column meaning a card is stuck reads red whether it's `Blocked`, `On Hold`, or `Rejected`; an early holding column reads gray whether it's `Backlog`, `Ideas`, or `Inbox`. When several columns share a sense (two active-work stages), it's fine to keep a couple uncolored or reuse a color rather than force eleven distinct hues. Name columns for workflow stages, keep card titles to a short task phrase, and let column length convey WIP instead of annotating counts. Card color is separate from column color: color cards by owner or priority with a tag group, and if you use one, tag EVERY card — an untagged card currently inherits the first tag value (mislabeling it), so omit the tag group entirely for cards you want left uncolored.
 <!-- TIPS end -->
 
 ### 10.1 Declaration
@@ -1328,7 +1333,7 @@ tag Crew as c
 <!-- TYPE:sitemap -->
 
 <!-- TIPS start -->
-**Styling tips:** Mirror the real navigation: group child pages under their section and keep the tree shallow (2–3 levels), ordering siblings by prominence. Connect pages with indented `-> Target` lines under each parent (a top-level `Home -> Products` renders as one box) and declare every target as its own page.
+**Styling tips:** Build a real navigation graph, not a flat column of boxes. Three things make a sitemap read well, and a good one uses all three. (1) **Cluster pages into `[Area]` group sections** when the site has distinct areas — e.g. `[Shop]`, `[Account]`, `[Admin]` — indenting each page under its bracket header, and leave only the true entry page (`Home` / `Landing`) at the top level. (2) **Show how a visitor moves** with an indented labeled arrow under the source page: `-submit-> Home`, `-checkout-> Payment`, `-back-> Dashboard`, where the label is the action or link text. Every arrow target must be declared as its own page; an arrow can point at a whole area with `-> [Admin]`. If pages share no links you've drawn a list, not a sitemap — connect them. (3) **Classify pages with a colored tag group**, so the legend organizes the map by meaning rather than by position. Declare a facet with colored values and assign it to every page in same-line metadata — access level works well: `tag Access` with `Public green`, `Member blue`, `Admin red`, then `Pricing Access: Public`; or a functional facet (`Browse`, `Purchase`, `Admin`). A second tag group for page kind (`Landing purple`, `Form orange`, `Content cyan`) adds a second color dimension. Reason about which facet actually distinguishes this site's pages rather than reaching for a fixed list. Keep the tree shallow and order siblings by prominence.
 <!-- TIPS end -->
 
 ### 11.1 Declaration
@@ -1707,7 +1712,7 @@ See spec §13A for full date-anchoring semantics, S-curve axes, and diagnostic c
 <!-- TYPE:boxes-and-lines -->
 
 <!-- TIPS start -->
-**Styling tips:** Show one clear direction of flow; group related boxes with a `[Group]` bracket and label each edge with the relationship rather than a bare arrow. Keep every box a short noun phrase.
+**Styling tips:** Show one clear direction of flow, label each edge with the relationship rather than a bare arrow, and keep every box a short noun phrase. **Color by category with a tag group:** declare a `tag <Facet> as <alias>` with a distinct color per value, then assign each box `<alias>: <Value>` so like things share a color and unlike things visibly differ — pick the facet that actually divides this system (tier: `Client`/`Edge`/`Compute`/`Data`, ownership, internal vs external, stateful vs stateless) rather than coloring at random. **Organize when it gets busy:** with more than ~4 boxes there is almost always a structure to surface — cluster the boxes that belong together into `[Group]` sections (a backend tier, a region, a subsystem) and draw edges to the group with `-> [Group]` where a whole cluster is the target. A flat row of many boxes is a missed opportunity; derive the grouping from how the parts relate. The `[Group]` brackets handle spatial clustering and the tag group handles color — use both, and they can cut across each other (e.g. group by subsystem, color by tier).
 <!-- TIPS end -->
 
 ### 13.1 Declaration
@@ -1843,6 +1848,30 @@ Flagship -> Sloop
   legend shows a gradient capsule; boxes without a `value:` get a neutral fill.
 - `show-values` additionally prints each box's number as text.
 
+### 13.9 Tag groups (categorical color)
+
+Color boxes by a category. Declare a `tag <Facet> as <alias>` group (§1.3) with one color per value — **values are indented under the `tag` header**, one per line, color as a trailing word — then assign each box `<alias>: <Value>` in its metadata. Do **not** write the values as `<alias> <Value>` lines; that is not the grammar.
+
+```
+boxes-and-lines Service Map
+tag Tier as t
+  Client blue
+  Edge teal
+  Compute green
+  Data purple
+
+[Client]
+  Web App t: Client
+[Edge]
+  API Gateway t: Edge
+[Compute]
+  Auth Service t: Compute
+[Data]
+  Postgres t: Data
+```
+
+The tag group (color) composes with `[Group]` clustering (spatial) and can cut across it — group by subsystem, color by tier. The group must be declared before any content line (§1.3).
+
 ---
 
 ## 15. Timeline Diagrams
@@ -2794,7 +2823,7 @@ Act red
 <!-- TYPE:journey-map -->
 
 <!-- TIPS start -->
-**Styling tips:** Label a single-word `emotion:` on each step so the highs and lows are named, not just shaped; give one concrete action per stage and name the persona. Mark the trough with `pain:` and the peak with `opportunity:` so the arc’s meaning lands.
+**Styling tips:** A journey map is a story about one specific person, so author it richly even when the prompt is thin — fill the gaps with plausible, concrete detail rather than leaving it skeletal. **Persona:** give them a real first name, a color, and a short background — `persona Gina green`, then a sentence or 2–3 indented bullet (`- …`) lines covering who they are, their goal, and their constraints. Always color the persona (trailing color word after the name, or `persona Name color: green`) so the protagonist's card stands out. When the prompt implies a customer archetype, let the name's first letter echo it (a fanatic → Fred, a casual user → Carl, a beginner → Betty) — a light touch, never forced. **Structure:** organize the journey into 2–4 `[Phase]` sections, each holding 1–3 steps — and never one step per phase across the board. If every phase has exactly one step you've just bracketed a flat list; that 1:1 mapping is wrong — either give phases multiple steps or drop the brackets and let the steps run flat. Give every step a 1–5 `score:` (and a single-word `emotion:` at the highs and lows) so the mood curve has shape. **Depth per step:** every step gets a `description:` (what actually happens there) plus 2–5 annotations drawn from `pain:` (friction, red), `opportunity:` (a fix, green), and `thought:` (what they're thinking, italic) — choose the ones that genuinely fit that moment; a smooth early step might be all `thought:`/`opportunity:`, a trough heavy on `pain:`. Don't pad every step identically — let the friction cluster where the score dips so the arc reads true.
 <!-- TIPS end -->
 
 Persona-centric mood landscapes. Steps carry a 1–5 score and optional emotion label; the renderer draws an emotion curve over phase-grouped step cards. **Declaration is required** — the `journey-map` keyword must appear on the first line (no inference, to avoid colliding with kanban's `[Column]` + indented items shape).
@@ -3159,7 +3188,7 @@ Markers in cells are always **rendered in canonical alphabet order** (`R A C I`,
 <!-- TYPE:map -->
 
 <!-- TIPS start -->
-**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For routes/flows from a hub** (e.g. an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — `JFK ~daily~> LAX`, `JFK ~daily~> LHR`, … — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places that already appear in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
+**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
 <!-- TIPS end -->
 
 Geographic concept maps: highlight/shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. For "share a concept" business maps, not cartography. Renders at a fixed, auto-fit position — no pan/zoom. Basemap and viewport are **inferred from the content you reference** — most maps need no directives. v1 boundaries: world countries + US states.
@@ -3302,6 +3331,8 @@ cove -> hav l: March    # the LINE turns green
   - **Name + scope** (readable): `Georgia US value: 5` → the state, `Georgia GE value: 5` → the country.
   - The redundant `Georgia US-GA` still works but isn't needed (a mismatched code like `Georgia US-CA` is rejected). A bare ambiguous `Georgia` follows the inferred US-scope signal and warns with both fixes named.
 - **IATA airport codes** resolve to airport coordinates — `poi JFK`, `route JFK -> LAX` — with no new syntax (large international hubs + all US scheduled-commercial airports). Case-insensitive (`jfk`/`JFK`). Airports are the **lowest-precedence** identifier: a token that is both a city and a code resolves to the **city** (`Ufa` → the city, not UFA airport), with a hint naming the airport. Resolution is by **code only** (never by airport name); the POI label is the typed code. An unknown three-letter code errors with an `as <CODE>` coordinates hint.
+- **A city name must match the gazetteer's canonical form** — `New York City`, not `New York`; `Washington, D.C.`, not `Washington`. An unrecognized name is dropped (with a did-you-mean note) and the map reframes around the places that *did* resolve, so the result can look complete but be missing a point. Use the exact name or coordinates.
+- **Discover the exact token** with the lookup surface rather than guessing — `dgmo map search "<place>"` (CLI; `--json` for machine output) or the `lookup_map_location` MCP tool. It substring-searches cities **and** the bundled airports and returns the precise token to paste (e.g. `york` → `New York City`; `heathrow` → `LHR`). There is intentionally **no exhaustive printed list** — the gazetteer holds thousands of cities plus ~1,500 airports; search is the interface.
 - Positional coordinates are the escape hatch for anything missing/ambiguous (including forcing an airport over a colliding city: `poi 54.56 55.87 as UFA`).
 
 ### Directives & reserved keys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {
@@ -134,7 +134,7 @@
     "check:deadcode": "knip",
     "check:spelling": "cspell \"src/**/*.ts\" \"tests/**/*.ts\"",
     "check:all": "pnpm check:deadcode && pnpm check:spelling && pnpm check:duplication && pnpm check:circular && pnpm check:deps && pnpm check:security && pnpm build && bash scripts/check-api.sh check && pnpm check:publish && pnpm check:types",
-    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>5){console.error('New circular deps found ('+n+' > 5 known type-only/dynamic cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
+    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>7){console.error('New circular deps found ('+n+' > 7 known type-only/dynamic cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
     "check:deps": "depcheck --ignores='@diagrammo/dgmo,@codemirror/language,@lezer/*,husky,lint-staged,tsup,axe-core,type-coverage'",
     "check:security": "pnpm audit --prod",
     "check:publish": "publint",

package/src/advanced.ts

@@ -569,11 +569,16 @@ export type {
   ProjectionFamily,
   GeoExtent,
 } from './map/resolved-types';
-export { completeMapPlaces, completeMapRegions } from './map/completion';
+export {
+  completeMapPlaces,
+  completeMapRegions,
+  searchMapLocations,
+} from './map/completion';
 export type {
   MapPlaceCompletion,
   MapRegionCompletion,
   MapCompletionOptions,
+  MapLocationMatch,
 } from './map/completion';
 export type {
   Gazetteer,

package/src/boxes-and-lines/label-placement.ts

@@ -0,0 +1,339 @@
+// ============================================================
+// Boxes and Lines Diagram — Edge label placement
+// ============================================================
+//
+// Makes edge/arrow labels legible regardless of length or layout via a priority
+// ladder (each step only fires when the previous can't make the label legible):
+//
+//   1. WRAP   — cap label width and wrap onto up to MAX_LABEL_LINES lines.
+//   2. MOVE   — if the wrapped box still overlaps a node box, slide it to a clear
+//               spot near its own line (along the polyline, then a small
+//               perpendicular offset), staying proximal. No leader line.
+//   3. RELAYOUT (last resort, owned by layout.ts) — re-run the search reserving
+//               dagre label space so a gap opens; this module only reports which
+//               labels stayed unresolved so the caller can decide to escalate.
+//
+// Placement runs in layout (not the renderer) so it sees node/group boxes and so
+// the relayout decision can re-invoke the search. The renderer is a pure consumer
+// of the labelX/labelY/labelWidth/labelHeight/labelLines fields written here.
+
+import type { BLLayoutResult } from './layout';
+import {
+  measureText,
+  wrapTextToWidth,
+  truncateText,
+} from '../utils/text-measure';
+
+// Keep in sync with EDGE_LABEL_FONT_SIZE in renderer.ts (ScaleContext is identity
+// there, so layout-space px == screen px for the unscaled diagram coords).
+export const EDGE_LABEL_FONT_SIZE = 11;
+
+const LABEL_MAX_WIDTH = 160; // ≈ DESC_NODE_WIDTH + slack; flat (not canvas-relative)
+const MAX_LABEL_LINES = 3;
+const LABEL_LINE_HEIGHT = 1.3;
+const H_PAD = 6; // horizontal halo padding (each side)
+const V_PAD = 3; // vertical halo padding (each side)
+const BOX_CLEAR_PAD = 4; // min clearance kept between a label box and a node box
+const PERP_STEP = 8; // perpendicular offset increment (px)
+const PERP_MAX = 40; // max perpendicular offset before giving up
+const SLIDE_SAMPLES = 9; // arc-length samples per side when sliding along the edge
+
+type Pt = { readonly x: number; readonly y: number };
+
+interface Rect {
+  readonly minX: number;
+  readonly minY: number;
+  readonly maxX: number;
+  readonly maxY: number;
+}
+
+export interface MeasuredLabel {
+  readonly lines: readonly string[];
+  /** Halo box width, including 2·H_PAD. */
+  readonly width: number;
+  /** Halo box height, including 2·V_PAD. */
+  readonly height: number;
+}
+
+/**
+ * Wrap + measure an edge label into a bounded multi-line box. Long unbreakable
+ * tokens are hard-broken at the char boundary; overflow past MAX_LABEL_LINES is
+ * ellipsized so the box is bounded in both axes.
+ */
+export function measureEdgeLabel(
+  label: string,
+  fontSize: number = EDGE_LABEL_FONT_SIZE,
+  maxWidth: number = LABEL_MAX_WIDTH
+): MeasuredLabel {
+  let lines = wrapTextToWidth(label, fontSize, maxWidth, { hardBreak: true });
+  if (lines.length > MAX_LABEL_LINES) {
+    const kept = lines.slice(0, MAX_LABEL_LINES - 1);
+    const rest = lines.slice(MAX_LABEL_LINES - 1).join(' ');
+    kept.push(truncateText(rest, fontSize, maxWidth));
+    lines = kept;
+  }
+  let textW = 0;
+  for (const ln of lines) {
+    const w = measureText(ln, fontSize);
+    if (w > textW) textW = w;
+  }
+  return {
+    lines,
+    width: textW + 2 * H_PAD,
+    height: lines.length * fontSize * LABEL_LINE_HEIGHT + 2 * V_PAD,
+  };
+}
+
+/** Point at the half-way arc length along an edge polyline — the geometric
+ *  centre of the connector, so a label seeds in the gap BETWEEN the two nodes
+ *  rather than drifting under the target. Degenerate point lists fall back. */
+export function edgePolylineMidpoint(points: ReadonlyArray<Pt>): Pt {
+  return pointAtArcFraction(points, 0.5).p;
+}
+
+/** Position + unit normal at arc-length fraction t∈[0,1] of a polyline. The
+ *  normal is perpendicular to the local segment (for proximal perp offsets). */
+function pointAtArcFraction(
+  points: ReadonlyArray<Pt>,
+  t: number
+): { p: Pt; nx: number; ny: number } {
+  if (points.length === 0) return { p: { x: 0, y: 0 }, nx: 0, ny: 1 };
+  if (points.length === 1)
+    return { p: { x: points[0]!.x, y: points[0]!.y }, nx: 0, ny: 1 };
+  const segLen: number[] = [];
+  let total = 0;
+  for (let k = 1; k < points.length; k++) {
+    const len = Math.hypot(
+      points[k]!.x - points[k - 1]!.x,
+      points[k]!.y - points[k - 1]!.y
+    );
+    segLen.push(len);
+    total += len;
+  }
+  let want = total * Math.max(0, Math.min(1, t));
+  for (let k = 1; k < points.length; k++) {
+    const len = segLen[k - 1]!;
+    if (want <= len || k === points.length - 1) {
+      const f = len === 0 ? 0 : Math.min(1, want / len);
+      const ax = points[k - 1]!.x;
+      const ay = points[k - 1]!.y;
+      const bx = points[k]!.x;
+      const by = points[k]!.y;
+      const dx = bx - ax;
+      const dy = by - ay;
+      const dlen = Math.hypot(dx, dy) || 1;
+      // Unit normal = perpendicular to the local tangent.
+      return {
+        p: { x: ax + dx * f, y: ay + dy * f },
+        nx: -dy / dlen,
+        ny: dx / dlen,
+      };
+    }
+    want -= len;
+  }
+  const last = points[points.length - 1]!;
+  return { p: { x: last.x, y: last.y }, nx: 0, ny: 1 };
+}
+
+function rectFromCenter(cx: number, cy: number, w: number, h: number): Rect {
+  return {
+    minX: cx - w / 2,
+    minY: cy - h / 2,
+    maxX: cx + w / 2,
+    maxY: cy + h / 2,
+  };
+}
+
+/** Does a label box centred at (cx,cy) overlap any obstacle (within pad)? */
+function overlapsAny(
+  cx: number,
+  cy: number,
+  w: number,
+  h: number,
+  obstacles: readonly Rect[],
+  pad: number
+): boolean {
+  const minX = cx - w / 2 - pad;
+  const minY = cy - h / 2 - pad;
+  const maxX = cx + w / 2 + pad;
+  const maxY = cy + h / 2 + pad;
+  for (const o of obstacles) {
+    if (minX < o.maxX && maxX > o.minX && minY < o.maxY && maxY > o.minY)
+      return true;
+  }
+  return false;
+}
+
+/** Arc-length fractions sampled centre-outward (keeps the label proximal to the
+ *  true midpoint), clamped away from the endpoints. */
+function slideFractions(): number[] {
+  const out = [0.5];
+  for (let k = 1; k <= SLIDE_SAMPLES; k++) {
+    const off = k * 0.08;
+    if (0.5 - off >= 0.12) out.push(0.5 - off);
+    if (0.5 + off <= 0.88) out.push(0.5 + off);
+  }
+  return out;
+}
+
+/** Find the nearest clear centre for a label box of (w,h) along/near `points`.
+ *  Pass 1 slides along the line; pass 2 offsets perpendicular. null = no clear
+ *  spot found within the proximity budget. */
+function findClearPosition(
+  w: number,
+  h: number,
+  points: ReadonlyArray<Pt>,
+  obstacles: readonly Rect[]
+): Pt | null {
+  const ts = slideFractions();
+  for (const t of ts) {
+    const { p } = pointAtArcFraction(points, t);
+    if (!overlapsAny(p.x, p.y, w, h, obstacles, BOX_CLEAR_PAD)) return p;
+  }
+  for (let mag = PERP_STEP; mag <= PERP_MAX; mag += PERP_STEP) {
+    for (const t of ts) {
+      const { p, nx, ny } = pointAtArcFraction(points, t);
+      for (const sign of [-1, 1]) {
+        const x = p.x + nx * mag * sign;
+        const y = p.y + ny * mag * sign;
+        if (!overlapsAny(x, y, w, h, obstacles, BOX_CLEAR_PAD)) return { x, y };
+      }
+    }
+  }
+  return null;
+}
+
+interface LabelBox {
+  edgeIdx: number;
+  cx: number;
+  cy: number;
+  w: number;
+  h: number;
+  lines: readonly string[];
+  resolved: boolean;
+}
+
+/** Separate overlapping label boxes vertically (variable sizes), mirroring the
+ *  old renderer pass. Runs after node-collision resolution; the caller re-checks
+ *  node overlap afterwards. */
+function resolveLabelOverlaps(boxes: LabelBox[]): void {
+  const MAX_PASSES = 8;
+  const PAD = 4;
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    let moved = false;
+    for (let i = 0; i < boxes.length; i++) {
+      for (let j = i + 1; j < boxes.length; j++) {
+        const a = boxes[i]!;
+        const b = boxes[j]!;
+        const dx = Math.abs(a.cx - b.cx);
+        const dy = Math.abs(a.cy - b.cy);
+        const overlapX = (a.w + b.w) / 2 + PAD - dx;
+        const overlapY = (a.h + b.h) / 2 + PAD - dy;
+        if (overlapX > 0 && overlapY > 0) {
+          const shift = overlapY / 2 + 1;
+          if (a.cy < b.cy) {
+            a.cy -= shift;
+            b.cy += shift;
+          } else {
+            a.cy += shift;
+            b.cy -= shift;
+          }
+          moved = true;
+        }
+      }
+    }
+    if (!moved) break;
+  }
+}
+
+export interface PlaceEdgeLabelsResult {
+  readonly layout: BLLayoutResult;
+  /** Edge indices whose label still overlaps a node box (escalate to relayout). */
+  readonly unresolved: number[];
+}
+
+/**
+ * Wrap, then collision-resolve every edge label against node boxes (steps 1–2),
+ * writing labelX/labelY/labelWidth/labelHeight/labelLines onto each edge. Returns
+ * the edge indices that could not be cleared so the caller can trigger a
+ * last-resort relayout.
+ */
+export function placeEdgeLabels(
+  layout: BLLayoutResult,
+  opts?: { fontSize?: number; maxWidth?: number }
+): PlaceEdgeLabelsResult {
+  const fontSize = opts?.fontSize ?? EDGE_LABEL_FONT_SIZE;
+  const maxWidth = opts?.maxWidth ?? LABEL_MAX_WIDTH;
+
+  // Obstacles = real node boxes + collapsed groups (drawn as boxes). Expanded
+  // groups are containers — their interior is valid label space, so they are NOT
+  // obstacles.
+  const obstacles: Rect[] = [];
+  for (const n of layout.nodes)
+    obstacles.push(rectFromCenter(n.x, n.y, n.width, n.height));
+  for (const g of layout.groups)
+    if (g.collapsed)
+      obstacles.push(rectFromCenter(g.x, g.y, g.width, g.height));
+
+  const boxes: LabelBox[] = [];
+  layout.edges.forEach((e, idx) => {
+    if (!e.label || e.points.length < 2) return;
+    const m = measureEdgeLabel(e.label, fontSize, maxWidth);
+    const mid = edgePolylineMidpoint(e.points);
+    let cy = mid.y;
+    // Fold in the parallel-edge fan offset so each line's label clears its line.
+    if (e.parallelCount > 1 && e.yOffset !== 0)
+      cy += (e.yOffset < 0 ? -1 : 1) * (m.height / 2);
+    boxes.push({
+      edgeIdx: idx,
+      cx: mid.x,
+      cy,
+      w: m.width,
+      h: m.height,
+      lines: m.lines,
+      resolved: true,
+    });
+  });
+
+  // Step 2: reposition any box that overlaps a node.
+  for (const box of boxes) {
+    if (!overlapsAny(box.cx, box.cy, box.w, box.h, obstacles, BOX_CLEAR_PAD))
+      continue;
+    const e = layout.edges[box.edgeIdx]!;
+    const clear = findClearPosition(box.w, box.h, e.points, obstacles);
+    if (clear) {
+      box.cx = clear.x;
+      box.cy = clear.y;
+    } else {
+      box.resolved = false;
+    }
+  }
+
+  // Separate stacked labels, then re-check node overlap (a vertical nudge can
+  // push a label back onto a box — that becomes an unresolved escalation).
+  resolveLabelOverlaps(boxes);
+  for (const box of boxes) {
+    if (overlapsAny(box.cx, box.cy, box.w, box.h, obstacles, BOX_CLEAR_PAD))
+      box.resolved = false;
+  }
+
+  const boxByIdx = new Map<number, LabelBox>();
+  for (const b of boxes) boxByIdx.set(b.edgeIdx, b);
+  const edges = layout.edges.map((e, idx) => {
+    const b = boxByIdx.get(idx);
+    if (!b) return e;
+    return {
+      ...e,
+      labelX: b.cx,
+      labelY: b.cy,
+      labelWidth: b.w,
+      labelHeight: b.h,
+      labelLines: b.lines,
+    };
+  });
+
+  return {
+    layout: { ...layout, edges },
+    unresolved: boxes.filter((b) => !b.resolved).map((b) => b.edgeIdx),
+  };
+}