@the-package-labs/idocs-core 0.3.1 → 0.5.0

package/dist/browser.js

@@ -6,8 +6,8 @@ import {
   createIconResolver,
   normalizeRoot,
   route
-} from "./chunk-5BMICZRC.js";
-import "./chunk-FRVCGXIG.js";
+} from "./chunk-Q2NHZ6TV.js";
+import "./chunk-ZYFFV7Y7.js";
 export {
   KNOWN_KEYS,
   RootSchema,

package/dist/chunk-P2X2XSBM.js

@@ -0,0 +1,127 @@
+import {
+  didYouMean
+} from "./chunk-ZYFFV7Y7.js";
+
+// src/nesting.ts
+function nestedDiagrams(all, name) {
+  const out = {};
+  const queue = [name];
+  for (let cur = queue.shift(); cur !== void 0; cur = queue.shift()) {
+    for (const node of Object.values(all[cur]?.nodes ?? {})) {
+      const next = node.diagram?.name;
+      if (next === void 0 || next === name || out[next] || !all[next]) continue;
+      out[next] = all[next];
+      queue.push(next);
+    }
+  }
+  return out;
+}
+function attachNested(all) {
+  const flat = {};
+  for (const [name, diagram] of Object.entries(all)) {
+    const { nested: _, ...rest } = diagram;
+    flat[name] = rest;
+  }
+  const out = {};
+  for (const [name, diagram] of Object.entries(flat)) {
+    const nested = nestedDiagrams(flat, name);
+    out[name] = Object.keys(nested).length ? { ...diagram, nested } : diagram;
+  }
+  return out;
+}
+function linkDiagrams(entries) {
+  const out = [];
+  const names = Object.keys(entries).sort();
+  const known = names.filter((n) => entries[n].diagram);
+  const report = (from, path, message, hint) => {
+    const at = entries[from].where?.(path);
+    out.push({
+      severity: "error",
+      message,
+      file: at?.file ?? `diagrams/${from}/diagram.yaml`,
+      line: at?.line,
+      col: at?.col,
+      path: path.join("."),
+      hint
+    });
+  };
+  const edges = /* @__PURE__ */ new Map();
+  for (const from of names) {
+    const diagram = entries[from].diagram;
+    if (!diagram) continue;
+    for (const node of Object.values(diagram.nodes)) {
+      const ref = node.diagram;
+      if (!ref) continue;
+      const at = ["nodes", node.id, "diagram"];
+      const sub = (key) => [...at, key];
+      const target = entries[ref.name];
+      if (!target) {
+        report(
+          from,
+          at,
+          `Node "${node.id}" opens diagram "${ref.name}", which does not exist`,
+          didYouMean(ref.name, names) ?? (names.length > 1 ? `Diagrams: ${names.filter((n) => n !== from).join(", ")}` : void 0)
+        );
+        continue;
+      }
+      if (!target.diagram) continue;
+      edges.set(from, (edges.get(from) ?? /* @__PURE__ */ new Set()).add(ref.name));
+      const views = target.diagram.views.map((v) => v.id);
+      const scenario = ref.scenario ? target.diagram.scenarios.find((s) => s.id === ref.scenario) : void 0;
+      if (ref.view && !views.includes(ref.view)) {
+        report(
+          from,
+          sub("view"),
+          `Diagram "${ref.name}" has no view "${ref.view}"`,
+          didYouMean(ref.view, views) ?? `Views: ${views.join(", ")}`
+        );
+      }
+      if (ref.scenario && !scenario) {
+        const ids = target.diagram.scenarios.map((s) => s.id);
+        report(
+          from,
+          sub("scenario"),
+          `Diagram "${ref.name}" has no scenario "${ref.scenario}"`,
+          didYouMean(ref.scenario, ids) ?? (ids.length ? `Scenarios: ${ids.join(", ")}` : "It has no scenarios.")
+        );
+      } else if (scenario && ref.view && scenario.view !== ref.view) {
+        report(
+          from,
+          sub("scenario"),
+          `Scenario "${scenario.id}" plays on view "${scenario.view}", not "${ref.view}"`,
+          "Drop `view`, and the diagram opens on the scenario's own view."
+        );
+      }
+    }
+  }
+  const state = /* @__PURE__ */ new Map();
+  const stack = [];
+  const visit = (name) => {
+    state.set(name, "open");
+    stack.push(name);
+    for (const next of edges.get(name) ?? /* @__PURE__ */ new Set()) {
+      if (state.get(next) === "open") {
+        const circle = [...stack.slice(stack.indexOf(next)), next];
+        const node = Object.values(entries[name].diagram.nodes).find(
+          (n) => n.diagram?.name === next
+        );
+        report(
+          name,
+          ["nodes", node.id, "diagram"],
+          next === name ? `Node "${node.id}" opens its own diagram "${name}"` : `Node "${node.id}" opens "${next}", which leads back to "${name}"`,
+          `A diagram cannot be inside itself: ${circle.join(" \u2192 ")}`
+        );
+      } else if (!state.has(next)) visit(next);
+    }
+    stack.pop();
+    state.set(name, "done");
+  };
+  for (const name of known) if (!state.has(name)) visit(name);
+  return out;
+}
+
+export {
+  nestedDiagrams,
+  attachNested,
+  linkDiagrams
+};

package/dist/{chunk-5BMICZRC.js → chunk-Q2NHZ6TV.js}

@@ -1,8 +1,10 @@
 import {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
+  DEFAULT_ENTITY_WIDTH,
+  didYouMean,
   letterKey
-} from "./chunk-FRVCGXIG.js";
+} from "./chunk-ZYFFV7Y7.js";
 
 // src/icon-resolver.ts
 import { getIconData, iconToSVG } from "@iconify/utils";
@@ -214,10 +216,28 @@ var ChipSchema = z.union([
   z.string(),
   z.strictObject({ label: z.string(), sub: z.string().optional() })
 ]);
+var FieldProps = z.strictObject({
+  type: z.string().optional().describe("Its type: `keyword`, `uuid`, `string[]`."),
+  key: z.boolean().optional().describe("Part of the primary key. Shown with a `#` in front."),
+  ref: z.string().optional().describe(
+    "The `node` or `node.field` this one points at, like a foreign key. Draws a relation between the two cards."
+  ),
+  note: z.string().optional().describe("Shown on hover and in the drawer.")
+});
+var FieldSchema = z.union([
+  z.string().min(1),
+  z.record(z.string().min(1), z.union([z.string(), z.null(), FieldProps])).refine((o) => Object.keys(o).length === 1, {
+    message: "One field per list item: `- name: type`"
+  })
+]);
 var NodeSchema = z.strictObject({
   title: z.string().optional().describe("Display name. Defaults to the node id."),
   sub: z.string().optional().describe("One line under the title, rendered in mono (ports, stack, version)."),
+  pill: z.string().optional().describe("Short label in the card header, like `TABLE` or `ES INDEX`."),
   lines: z.array(z.string()).optional().describe("Short body lines inside the card."),
+  fields: z.array(FieldSchema).optional().describe(
+    "Makes the card an entity: a table of fields, each `name: type`. `ref` points a field at another entity."
+  ),
   icon: z.string().optional().describe("`postgresql`, `logos:redis`, `lucide:server` or ./path/to.svg."),
   kind: z.string().optional().describe("Gives a default icon and colour family. See `kinds`."),
   family: FamilySchema.optional().describe("Accent colour family; overrides the kind default."),
@@ -231,7 +251,23 @@ var NodeSchema = z.strictObject({
   doc: z.string().optional().describe("Markdown file for the drawer. Defaults to nodes/<id>.md when present."),
   links: z.array(z.strictObject({ label: z.string(), url: z.string() })).optional(),
   refs: z.array(z.string()).optional().describe("Source files or URLs this node is based on."),
-  tags: z.array(z.string()).optional()
+  tags: z.array(z.string()).optional(),
+  diagram: z.union([
+    z.string().min(1),
+    z.strictObject({
+      name: z.string().min(1).describe("Folder name of the diagram, under diagrams/."),
+      view: Id.optional().describe(
+        "View to open first. Defaults to the scenario view, then the first."
+      ),
+      scenario: Id.optional().describe("Scenario to select when the diagram opens."),
+      mode: z.enum(["both", "expand", "open"]).optional().describe(
+        "both (default): the reader can expand it in place or open it. expand: only in place. open: only move into it."
+      ),
+      expanded: z.boolean().optional().describe("Start expanded in place, so the whole inner diagram shows as a group.")
+    })
+  ]).optional().describe(
+    "Another diagram (its folder name) that shows the inside of this node. The card gets buttons to expand it in place, as a group, or to open it one level deeper, with a way back."
+  )
 });
 var GroupSchema = z.strictObject({
   label: z.string(),
@@ -337,10 +373,31 @@ var ScenarioSchema = ScenarioBase.refine(
   (s) => (s.phases?.length ?? 0) + (s.steps?.length ?? 0) > 0,
   { message: "A scenario needs `steps` or `phases`" }
 );
+var DefaultsSchema = z.strictObject({
+  view: Id.optional().describe(
+    "View shown first. Defaults to the view of `scenario`, or else the first view."
+  ),
+  scenario: Id.optional().describe(
+    "Scenario selected first. Without it the diagram opens on its overview. It does not play until a reader presses play, unless `autoplay` is on."
+  ),
+  mode: z.enum(["flow", "sequence", "story"]).optional().describe(
+    "How a scenario is drawn when it has no `mode` of its own: packets over the diagram, a sequence diagram, or a swimlane story."
+  ),
+  sidebar: z.boolean().optional().describe(
+    "Whether the panel over the picture starts open. By default it does when there is a scenario or another view to choose, and the frame is wide enough."
+  ),
+  subtitles: z.boolean().optional().describe("Words over the picture saying what the scenario is doing. On by default."),
+  autoplay: z.boolean().optional().describe(
+    "Play `scenario` as soon as the diagram is on screen. Needs `scenario`, and is ignored when the system asks for reduced motion."
+  )
+});
 var RootSchema = z.strictObject({
   $schema: z.string().optional(),
   title: z.string(),
   description: z.string().optional().describe("Markdown shown above the first view."),
+  defaults: DefaultsSchema.optional().describe(
+    "How the diagram opens: its view, scenario and mode, and whether the panel and subtitles show. A page can still choose otherwise with the props of `<Diagram>`."
+  ),
   kinds: z.record(Id, z.strictObject({ icon: z.string().optional(), family: FamilySchema.optional() })).optional(),
   edgeKinds: z.record(
     Id,
@@ -363,7 +420,8 @@ var KNOWN_KEYS = {
   group: Object.keys(GroupSchema.shape),
   edge: Object.keys(EdgeSchema.shape),
   view: Object.keys(ViewSchema.shape),
-  scenario: Object.keys(ScenarioBase.shape)
+  scenario: Object.keys(ScenarioBase.shape),
+  defaults: Object.keys(DefaultsSchema.shape)
 };
 function authoringJsonSchema() {
   const schema = z.toJSONSchema(RootSchema, { io: "input", unrepresentable: "any" });
@@ -449,15 +507,17 @@ function compileDiagram(src, assets) {
     scenarios[f.id] = body;
     scenarioSources.set(f.id, s);
   }
-  const report = (severity, message, path, hint) => {
+  const where = (path) => {
     let source = main;
     let p = path;
     if (path[0] === "scenarios" && typeof path[1] === "string" && scenarioSources.has(path[1])) {
       source = scenarioSources.get(path[1]);
       p = path.slice(2);
     }
-    const pos = locate(source, p);
-    diagnostics.push({ severity, message, file: source.file, ...pos, path: path.join("."), hint });
+    return { file: source.file, ...locate(source, p) };
+  };
+  const report = (severity, message, path, hint) => {
+    diagnostics.push({ severity, message, ...where(path), path: path.join("."), hint });
   };
   const error = (message, path, hint) => report("error", message, path, hint);
   const warn = (message, path, hint) => report("warning", message, path, hint);
@@ -473,7 +533,7 @@ function compileDiagram(src, assets) {
   }
   const diagram = build(parsed.data, src, error, warn, assets);
   if (diagnostics.some((d) => d.severity === "error")) return { diagnostics };
-  return { diagram, diagnostics };
+  return Object.defineProperty({ diagram, diagnostics }, "where", { value: where });
 }
 function build(data, src, error, warn, { resolveIcon }) {
   const kinds = { ...BUILTIN_KINDS };
@@ -570,6 +630,7 @@ function build(data, src, error, warn, { resolveIcon }) {
   const fixParents = Object.values(groups);
   for (const g of fixParents) g.style = g.parent ? "frame" : "zone";
   const nodes = {};
+  const refTexts = [];
   for (const [id, n] of Object.entries(data.nodes)) {
     if (n.kind && !kinds[n.kind]) {
       warn(
@@ -586,16 +647,38 @@ function build(data, src, error, warn, { resolveIcon }) {
         didYouMean(n.in, Object.keys(groups))
       );
     }
+    if (typeof n.diagram === "object" && n.diagram.expanded && n.diagram.mode === "open") {
+      warn(
+        "`expanded` has no effect with `mode: open`",
+        ["nodes", id, "diagram", "expanded"],
+        "Use `mode: expand` or `mode: both`, or drop `expanded`."
+      );
+    }
     const docPath = n.doc ?? `nodes/${id}.md`;
     const docText = src.readFile?.(docPath);
     if (n.doc && docText === void 0)
       warn(`Doc file "${n.doc}" was not found`, ["nodes", id, "doc"]);
     const docHtml = [n.description, docText].filter((t) => !!t).map(renderMarkdown).join("");
+    const fields = (n.fields ?? []).map(toField);
+    const seenFields = /* @__PURE__ */ new Set();
+    fields.forEach((f, i) => {
+      if (seenFields.has(f.name)) {
+        error(`Field "${f.name}" appears twice in "${id}"`, ["nodes", id, "fields", i]);
+      }
+      seenFields.add(f.name);
+    });
+    n.fields?.forEach((item, i) => {
+      const ref = typeof item === "object" && item ? Object.values(item)[0] : void 0;
+      if (ref && typeof ref === "object" && ref.ref !== void 0)
+        refTexts.push({ node: id, index: i, text: ref.ref });
+    });
     nodes[id] = {
       id,
       title: n.title ?? id,
       sub: n.sub,
+      pill: n.pill,
       lines: n.lines ?? [],
+      fields,
       icon: iconFor(n.icon ?? kind?.icon, ["nodes", id, n.icon ? "icon" : "kind"]),
       kind: n.kind,
       family: n.family ?? kind?.family,
@@ -604,25 +687,47 @@ function build(data, src, error, warn, { resolveIcon }) {
       badge: n.badge === void 0 ? void 0 : String(n.badge),
       uses: n.uses ?? [],
       chips: (n.chips ?? []).map((c) => typeof c === "string" ? { label: c } : c),
-      w: n.w,
+      w: n.w ?? (fields.length ? DEFAULT_ENTITY_WIDTH : void 0),
       docHtml: docHtml || void 0,
       links: n.links ?? [],
       refs: n.refs ?? [],
-      tags: n.tags ?? []
+      tags: n.tags ?? [],
+      diagram: typeof n.diagram === "string" ? { name: n.diagram } : n.diagram
     };
   }
+  for (const { node: id, index, text } of refTexts) {
+    const found = resolveEnd(text, nodes);
+    if ("end" in found) {
+      nodes[id].fields[index].ref = found.end;
+      continue;
+    }
+    const name = nodes[id].fields[index].name;
+    error(
+      found.message ?? `Field "${name}" points at "${text}", which is not a node`,
+      ["nodes", id, "fields", index, name, "ref"],
+      found.hint ?? didYouMean(text, Object.keys(nodes))
+    );
+  }
   const edges = {};
   const nodeIds = Object.keys(nodes);
   (data.edges ?? []).forEach((e, i) => {
     const path = ["edges", i];
     let ok = true;
+    const ends = {};
     for (const end of ["from", "to"]) {
-      if (!nodes[e[end]]) {
-        error(`Edge ${end} "${e[end]}" is not a node`, [...path, end], didYouMean(e[end], nodeIds));
+      const found = resolveEnd(e[end], nodes);
+      if ("end" in found) ends[end] = found.end;
+      else {
+        error(
+          found.message ?? `Edge ${end} "${e[end]}" is not a node`,
+          [...path, end],
+          found.hint ?? didYouMean(e[end], nodeIds)
+        );
         ok = false;
       }
     }
-    const kind = e.kind ?? "http";
+    const between = ends.from && ends.to && [ends.from, ends.to].every((x) => nodes[x.node].fields.length);
+    const kind = e.kind ?? (between ? "relation" : "http");
     if (!edgeKinds[kind]) {
       error(
         `Unknown edge kind "${kind}"`,
@@ -631,7 +736,7 @@ function build(data, src, error, warn, { resolveIcon }) {
       );
       ok = false;
     }
-    if (e.from === e.to) {
+    if (ok && ends.from.node === ends.to.node) {
       warn("Edge connects a node to itself and is not drawn", path);
       ok = false;
     }
@@ -643,8 +748,10 @@ function build(data, src, error, warn, { resolveIcon }) {
     }
     edges[id] = {
       id,
-      from: e.from,
-      to: e.to,
+      from: ends.from.node,
+      to: ends.to.node,
+      fromField: ends.from.field,
+      toField: ends.to.field,
       label: e.label,
       kind,
       both: e.both ?? false,
@@ -657,6 +764,32 @@ function build(data, src, error, warn, { resolveIcon }) {
       noteHtml: e.note ? renderMarkdown(e.note) : void 0
     };
   });
+  const written = new Set(
+    Object.values(edges).flatMap((e) => {
+      const a = `${e.from}.${e.fromField ?? ""}`;
+      const b = `${e.to}.${e.toField ?? ""}`;
+      return [`${a}>${b}`, `${b}>${a}`];
+    })
+  );
+  for (const node of Object.values(nodes)) {
+    for (const f of node.fields) {
+      if (!f.ref || f.ref.node === node.id) continue;
+      const key = `${node.id}.${f.name}>${f.ref.node}.${f.ref.field ?? ""}`;
+      if (written.has(key)) continue;
+      const id = `ref:${node.id}.${f.name}`;
+      edges[id] = {
+        id,
+        from: node.id,
+        to: f.ref.node,
+        fromField: f.name,
+        toField: f.ref.field,
+        kind: "relation",
+        both: false,
+        hidden: false,
+        status: "built"
+      };
+    }
+  }
   const viewDefs = Object.keys(data.views ?? {}).length ? data.views : { main: { title: data.title } };
   const views = Object.entries(viewDefs).map(
     ([id, v]) => buildView(
@@ -674,10 +807,12 @@ function build(data, src, error, warn, { resolveIcon }) {
     const sc = buildScenario(id, s, views, nodes, edges, error, warn);
     if (sc) scenarios.push(sc);
   }
+  const defaults = buildDefaults(data.defaults, views, scenarios, error);
   return {
     name: src.name,
     title: data.title,
     descriptionHtml: data.description ? renderMarkdown(data.description) : void 0,
+    defaults,
     nodes,
     groups,
     edges,
@@ -686,6 +821,37 @@ function build(data, src, error, warn, { resolveIcon }) {
     scenarios
   };
 }
+function toField(item) {
+  if (typeof item === "string") return { name: item };
+  const [name, value] = Object.entries(item)[0];
+  if (value == null) return { name };
+  if (typeof value === "string") return { name, type: value };
+  const { ref: _ref, ...rest } = value;
+  return { name, ...rest };
+}
+function resolveEnd(text, nodes) {
+  if (nodes[text]) return { end: { node: text } };
+  const matches = [];
+  let known;
+  for (let i = text.indexOf("."); i > 0; i = text.indexOf(".", i + 1)) {
+    const node = nodes[text.slice(0, i)];
+    if (!node) continue;
+    known ??= node;
+    const field2 = text.slice(i + 1);
+    if (node.fields.some((f) => f.name === field2)) matches.push({ node: node.id, field: field2 });
+  }
+  if (matches.length === 1) return { end: matches[0] };
+  if (matches.length > 1) {
+    return { message: `"${text}" could be more than one field`, hint: "Rename a node or a field." };
+  }
+  if (!known) return {};
+  const field = text.slice(known.id.length + 1);
+  const names = known.fields.map((f) => f.name);
+  return {
+    message: `Node "${known.id}" has no field "${field}"`,
+    hint: didYouMean(field, names) ?? (names.length ? `Fields: ${names.join(", ")}` : void 0)
+  };
+}
 function buildView(id, v, diagramTitle, nodes, groups, edges, error) {
   const known = [...Object.keys(nodes), ...Object.keys(groups)];
   const members = (gid, out) => {
@@ -738,6 +904,38 @@ function buildView(id, v, diagramTitle, nodes, groups, edges, error) {
     interfaces: v.interfaces ?? false
   };
 }
+function buildDefaults(d, views, scenarios, error) {
+  if (!d) return void 0;
+  const ids = (list) => list.map((x) => x.id);
+  const view = views.find((v) => v.id === d.view);
+  if (d.view !== void 0 && !view) {
+    error(
+      `defaults.view "${d.view}" is not a view`,
+      ["defaults", "view"],
+      didYouMean(d.view, ids(views))
+    );
+  }
+  const scenario = scenarios.find((s) => s.id === d.scenario);
+  if (d.scenario !== void 0 && !scenario) {
+    error(
+      `defaults.scenario "${d.scenario}" is not a scenario`,
+      ["defaults", "scenario"],
+      didYouMean(d.scenario, ids(scenarios))
+    );
+  }
+  if (view && scenario && scenario.view !== view.id) {
+    error(
+      `defaults.scenario "${scenario.id}" plays on view "${scenario.view}", not "${view.id}"`,
+      ["defaults", "scenario"],
+      `Drop \`view\` and the diagram opens on "${scenario.view}", or pick a scenario of "${view.id}".`
+    );
+  }
+  if (d.autoplay && d.scenario === void 0) {
+    error("defaults.autoplay needs a defaults.scenario to play", ["defaults", "autoplay"]);
+  }
+  const out = Object.fromEntries(Object.entries(d).filter(([, v]) => v !== void 0));
+  return Object.keys(out).length ? out : void 0;
+}
 function buildScenario(id, s, views, nodes, edges, error, warn) {
   const viewId = s.view ?? views[0].id;
   const view = views.find((v) => v.id === viewId);
@@ -1015,6 +1213,7 @@ function describeIssue(issue) {
 function allowedKeysFor(path) {
   const [section] = path;
   if (path.length === 0) return KNOWN_KEYS.root;
+  if (path.length === 1) return section === "defaults" ? KNOWN_KEYS.defaults : void 0;
   if (path.length !== 2) return void 0;
   switch (section) {
     case "nodes":
@@ -1031,31 +1230,6 @@ function allowedKeysFor(path) {
       return void 0;
   }
 }
-function didYouMean(word, options) {
-  let best;
-  let bestDist = Math.max(2, Math.floor(word.length / 3)) + 1;
-  for (const o of options) {
-    const d = levenshtein(word.toLowerCase(), o.toLowerCase());
-    if (d < bestDist) {
-      best = o;
-      bestDist = d;
-    }
-  }
-  return best ? `Did you mean "${best}"?` : void 0;
-}
-function levenshtein(a, b) {
-  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i++) {
-    let prev = row[0];
-    row[0] = i;
-    for (let j = 1; j <= b.length; j++) {
-      const tmp = row[j];
-      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
-      prev = tmp;
-    }
-  }
-  return row[b.length];
-}
 
 export {
   createIconResolver,

package/dist/{chunk-FRVCGXIG.js → chunk-ZYFFV7Y7.js}

@@ -17,7 +17,8 @@ var BUILTIN_KINDS = {
   network: { icon: "lucide:network", family: "violet" },
   vm: { icon: "lucide:box", family: "violet" },
   auth: { icon: "lucide:key-round", family: "teal" },
-  monitor: { icon: "lucide:activity", family: "teal" }
+  monitor: { icon: "lucide:activity", family: "teal" },
+  entity: { icon: "lucide:table-2", family: "blue" }
 };
 var BUILTIN_EDGE_KINDS = {
   http: { label: "HTTP request / response", color: "ink", width: 1.5 },
@@ -25,7 +26,8 @@ var BUILTIN_EDGE_KINDS = {
   tunnel: { label: "Overlay tunnel", color: "tunnel", width: 5 },
   queue: { label: "Queue / broker", color: "ok", width: 2, dash: "2 4" },
   ws: { label: "WebSocket", color: "ink", width: 1.6, dash: "7 4" },
-  data: { label: "Data access", color: "muted", width: 1.3 }
+  data: { label: "Data access", color: "muted", width: 1.3 },
+  relation: { label: "Relation between entities", color: "muted", width: 1.4 }
 };
 var STEP_KIND_COLORS = {
   request: "accent",
@@ -35,6 +37,7 @@ var STEP_KIND_COLORS = {
   event: "warn"
 };
 var DEFAULT_NODE_WIDTH = 178;
+var DEFAULT_ENTITY_WIDTH = 280;
 
 // src/geometry.ts
 function polylineLength(points) {
@@ -104,14 +107,43 @@ function letterKey(index) {
   return out;
 }
 
+// src/suggest.ts
+function didYouMean(word, options) {
+  let best;
+  let bestDist = Math.max(2, Math.floor(word.length / 3)) + 1;
+  for (const o of options) {
+    const d = levenshtein(word.toLowerCase(), o.toLowerCase());
+    if (d < bestDist) {
+      best = o;
+      bestDist = d;
+    }
+  }
+  return best ? `Did you mean "${best}"?` : void 0;
+}
+function levenshtein(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return row[b.length];
+}
+
 export {
   BUILTIN_KINDS,
   BUILTIN_EDGE_KINDS,
   STEP_KIND_COLORS,
   DEFAULT_NODE_WIDTH,
+  DEFAULT_ENTITY_WIDTH,
   polylineLength,
   dist,
   pointAt,
   roundedPath,
-  letterKey
+  letterKey,
+  didYouMean
 };

package/dist/compiler.d.ts

@@ -23,9 +23,20 @@ export interface DiagramSource {
     /** Read a file relative to the diagram directory (docs, local icons). Undefined when missing. */
     readFile?: (relPath: string) => string | undefined;
 }
+/** Where a dotted path of the diagram lives in the files it was compiled from. */
+export type Where = (path: (string | number)[]) => {
+    file: string;
+    line?: number;
+    col?: number;
+};
 export interface CompileResult {
     diagram?: CompiledDiagram;
     diagnostics: Diagnostic[];
+    /**
+     * Lets a later pass (linking diagrams to each other) report at a line. A closure over the parsed
+     * files, so it is not enumerable: spreading, cloning or serialising a result leaves it behind.
+     */
+    readonly where?: Where;
 }
 export interface CompilerAssets {
     resolveIcon: (spec: string) => IconResult;

package/dist/defaults.d.ts

@@ -8,3 +8,5 @@ export declare const BUILTIN_KINDS: Record<string, KindDef>;
 export declare const BUILTIN_EDGE_KINDS: Record<string, EdgeKindDef>;
 export declare const STEP_KIND_COLORS: Record<string, string>;
 export declare const DEFAULT_NODE_WIDTH = 178;
+/** Cards with fields need room for a name and a type side by side. */
+export declare const DEFAULT_ENTITY_WIDTH = 280;

package/dist/index.d.ts

@@ -1,7 +1,13 @@
 export * from './defaults';
 export * from './geometry';
 export * from './layout';
+export * from './nested-layout';
+export * from './nesting';
+export * from './outline';
+export * from './phases';
 export * from './route';
+export * from './scrubber';
+export * from './start';
 export * from './story';
 export * from './svg';
 export * from './timeline';