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

package/dist/browser.js

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

package/dist/chunk-3QBMUILO.js

@@ -0,0 +1,127 @@
+import {
+  didYouMean
+} from "./chunk-ITBBPZE6.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-FRVCGXIG.js → chunk-ITBBPZE6.js}

@@ -104,6 +104,33 @@ 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,
@@ -113,5 +140,6 @@ export {
   dist,
   pointAt,
   roundedPath,
-  letterKey
+  letterKey,
+  didYouMean
 };

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

@@ -1,8 +1,9 @@
 import {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
+  didYouMean,
   letterKey
-} from "./chunk-FRVCGXIG.js";
+} from "./chunk-ITBBPZE6.js";
 
 // src/icon-resolver.ts
 import { getIconData, iconToSVG } from "@iconify/utils";
@@ -231,7 +232,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(),
@@ -449,15 +466,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 +492,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 };
@@ -586,6 +605,13 @@ 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)
@@ -608,7 +634,8 @@ function build(data, src, error, warn, { resolveIcon }) {
       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
     };
   }
   const edges = {};
@@ -1031,31 +1058,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/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/index.d.ts

@@ -1,6 +1,10 @@
 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 './story';
 export * from './svg';

package/dist/index.js

@@ -1,3 +1,8 @@
+import {
+  attachNested,
+  linkDiagrams,
+  nestedDiagrams
+} from "./chunk-3QBMUILO.js";
 import {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
@@ -8,7 +13,7 @@ import {
   pointAt,
   polylineLength,
   roundedPath
-} from "./chunk-FRVCGXIG.js";
+} from "./chunk-ITBBPZE6.js";
 
 // src/layout.ts
 import ELK from "elkjs/lib/elk.bundled.js";
@@ -951,6 +956,236 @@ function overlap(a, b, pad) {
   return a.x < b.x + b.w + pad && a.x + a.w + pad > b.x && a.y < b.y + b.h + pad && a.y + a.h + pad > b.y;
 }
 
+// src/nested-layout.ts
+var INLINE_PAD = { top: 40, left: 4, right: 4, bottom: 4 };
+function openingView(diagram, ref) {
+  const has = (id) => diagram.views.some((v) => v.id === id);
+  if (has(ref.view)) return ref.view;
+  const fromScenario = diagram.scenarios.find((s) => s.id === ref.scenario)?.view;
+  return has(fromScenario) ? fromScenario : diagram.views[0].id;
+}
+var canExpand = (ref, diagrams) => !!ref && ref.mode !== "open" && !!diagrams[ref.name];
+var canOpen = (ref, diagrams) => !!ref && ref.mode !== "expand" && !!diagrams[ref.name];
+var pathJoin = (prefix, id) => `${prefix}${id}`;
+function defaultExpanded(diagram, diagrams, prefix = "", seen = []) {
+  const out = [];
+  for (const node of Object.values(diagram.nodes)) {
+    const ref = node.diagram;
+    const child = ref && diagrams[ref.name];
+    if (!ref || !child || seen.includes(ref.name) || !ref.expanded || !canExpand(ref, diagrams))
+      continue;
+    const path = pathJoin(prefix, node.id);
+    out.push(path, ...defaultExpanded(child, diagrams, `${path}/`, [...seen, diagram.name]));
+  }
+  return out;
+}
+function measurable(diagram, viewId, expanded, diagrams, prefix = "") {
+  const view = diagram.views.find((v) => v.id === viewId);
+  if (!view) return [];
+  const out = [];
+  for (const id of view.nodeIds) {
+    const node = diagram.nodes[id];
+    const path = pathJoin(prefix, id);
+    out.push({ key: path, node });
+    const ref = node.diagram;
+    const child = ref && expanded.has(path) && canExpand(ref, diagrams) ? diagrams[ref.name] : void 0;
+    if (ref && child) {
+      out.push(...measurable(child, openingView(child, ref), expanded, diagrams, `${path}/`));
+    }
+  }
+  return out;
+}
+async function layoutNested(diagram, viewId, { sizes = {}, expanded, diagrams = {}, prefix = "" } = {}) {
+  const view = diagram.views.find((v) => v.id === viewId);
+  if (!view) throw new Error(`Unknown view "${viewId}"`);
+  const own = {};
+  for (const id of view.nodeIds) {
+    const size = sizes[pathJoin(prefix, id)];
+    if (size) own[id] = size;
+  }
+  const inner = {};
+  await Promise.all(
+    view.nodeIds.map(async (id) => {
+      const ref = diagram.nodes[id].diagram;
+      const path = pathJoin(prefix, id);
+      const child = ref && expanded?.has(path) && canExpand(ref, diagrams) ? diagrams[ref.name] : void 0;
+      if (!ref || !child) return;
+      const childView = openingView(child, ref);
+      const layout = await layoutNested(child, childView, {
+        sizes,
+        expanded,
+        diagrams,
+        prefix: `${path}/`
+      });
+      inner[id] = {
+        name: ref.name,
+        viewId: childView,
+        offset: { x: INLINE_PAD.left, y: INLINE_PAD.top },
+        layout
+      };
+      own[id] = {
+        w: layout.layout.width + INLINE_PAD.left + INLINE_PAD.right,
+        h: layout.layout.height + INLINE_PAD.top + INLINE_PAD.bottom
+      };
+    })
+  );
+  return { layout: await layoutView(diagram, viewId, own), inner };
+}
+function rectOfPath(nested, path) {
+  let level = nested;
+  let at = { x: 0, y: 0 };
+  const ids = path.split("/");
+  for (const [i, id] of ids.entries()) {
+    const r = level?.layout.nodes[id];
+    if (!level || !r) return void 0;
+    if (i === ids.length - 1) return { x: at.x + r.x, y: at.y + r.y, w: r.w, h: r.h };
+    const inner = level.inner[id];
+    if (!inner) return void 0;
+    at = { x: at.x + r.x + inner.offset.x, y: at.y + r.y + inner.offset.y };
+    level = inner.layout;
+  }
+  return void 0;
+}
+
+// src/outline.ts
+function buildOutline(diagram, view, { diagrams = {}, expanded = /* @__PURE__ */ new Set(), prefix = "", seen = [] } = {}) {
+  const inView = new Set(view.nodeIds);
+  const groups = new Set(view.groupIds);
+  const drawn = view.edgeIds.map((id) => diagram.edges[id]).filter((e) => !e.hidden);
+  const connectionsOf = (id) => {
+    const out = [];
+    for (const e of drawn) {
+      const sends = e.from === id;
+      const gets = e.to === id;
+      if (!sends && !gets) continue;
+      const other = sends ? e.to : e.from;
+      out.push({
+        edge: e.id,
+        dir: e.both ? "both" : sends ? "out" : "in",
+        other,
+        otherTitle: diagram.nodes[other]?.title ?? other,
+        label: e.label,
+        kind: e.kind,
+        status: e.status
+      });
+    }
+    const rank = { out: 0, both: 1, in: 2 };
+    return out.sort((a, b) => rank[a.dir] - rank[b.dir]);
+  };
+  const nodeItem = (id) => {
+    const node = diagram.nodes[id];
+    const path = pathJoin(prefix, id);
+    const item = {
+      type: "node",
+      path,
+      id,
+      title: node.title,
+      sub: node.sub,
+      icon: node.icon,
+      status: node.status,
+      connections: connectionsOf(id)
+    };
+    const ref = node.diagram;
+    const child = ref && diagrams[ref.name];
+    if (ref && child && !seen.includes(ref.name) && (canExpand(ref, diagrams) || canOpen(ref, diagrams))) {
+      const shown = canExpand(ref, diagrams) && expanded.has(path);
+      const childView = child.views.find((v) => v.id === openingView(child, ref));
+      item.inside = {
+        title: child.title,
+        expand: canExpand(ref, diagrams),
+        open: canOpen(ref, diagrams),
+        expanded: shown,
+        items: shown && childView ? buildOutline(child, childView, {
+          diagrams,
+          expanded,
+          prefix: `${path}/`,
+          seen: [...seen, diagram.name]
+        }) : []
+      };
+    }
+    return item;
+  };
+  const childGroups = /* @__PURE__ */ new Map();
+  for (const gid of view.groupIds) {
+    const parent = diagram.groups[gid]?.parent;
+    const key = parent && groups.has(parent) ? parent : "";
+    childGroups.set(key, [...childGroups.get(key) ?? [], gid]);
+  }
+  const childNodes = /* @__PURE__ */ new Map();
+  for (const id of view.nodeIds) {
+    if (!inView.has(id)) continue;
+    const group = diagram.nodes[id].group;
+    const key = group && groups.has(group) ? group : "";
+    childNodes.set(key, [...childNodes.get(key) ?? [], id]);
+  }
+  const position = new Map(view.nodeIds.map((id, i) => [id, i]));
+  const firstNode = (gid) => Math.min(
+    ...(childNodes.get(gid) ?? []).map((n) => position.get(n)),
+    ...(childGroups.get(gid) ?? []).map(firstNode)
+  );
+  const groupItem = (gid) => {
+    const g = diagram.groups[gid];
+    const items = fill(gid);
+    return {
+      type: "group",
+      path: pathJoin(prefix, `#${gid}`),
+      id: gid,
+      title: g.label,
+      caption: g.caption,
+      icon: g.icon,
+      status: g.status,
+      items,
+      count: items.reduce((n, i) => n + (i.type === "group" ? i.count : 1), 0)
+    };
+  };
+  function fill(key) {
+    const ranked = [
+      ...(childGroups.get(key) ?? []).map((gid) => ({
+        at: firstNode(gid),
+        make: () => groupItem(gid)
+      })),
+      ...(childNodes.get(key) ?? []).map((id) => ({
+        at: position.get(id),
+        make: () => nodeItem(id)
+      }))
+    ];
+    return ranked.sort((a, b) => a.at - b.at).map((r) => r.make());
+  }
+  return fill("");
+}
+function outlineNodes(items) {
+  const out = [];
+  for (const item of items) {
+    if (item.type === "group") out.push(...outlineNodes(item.items));
+    else out.push(item, ...outlineNodes(item.inside?.items ?? []));
+  }
+  return out;
+}
+
+// src/phases.ts
+var hasPhases = (scenario) => scenario.phases.some((p) => p.title);
+function phaseSpans(scenario) {
+  const out = [];
+  scenario.steps.forEach((step, i) => {
+    const last = out[out.length - 1];
+    if (last && last.index === step.phase) {
+      last.to = i;
+      last.count++;
+      return;
+    }
+    const phase = scenario.phases[step.phase];
+    out.push({
+      index: step.phase,
+      title: phase?.title ?? "",
+      caption: phase?.caption,
+      from: i,
+      to: i,
+      count: 1
+    });
+  });
+  return out;
+}
+
 // src/story.ts
 function buildStory(diagram, scenario) {
   const steps = scenario.steps;
@@ -1250,17 +1485,33 @@ export {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
   DEFAULT_NODE_WIDTH,
+  INLINE_PAD,
   STEP_KIND_COLORS,
+  attachNested,
+  buildOutline,
   buildStory,
   buildTimeline,
+  canExpand,
+  canOpen,
+  defaultExpanded,
   dist,
   frameAt,
+  hasPhases,
   labelWidth,
+  layoutNested,
   layoutView,
   letterKey,
+  linkDiagrams,
+  measurable,
+  nestedDiagrams,
+  openingView,
+  outlineNodes,
   packGrid,
+  pathJoin,
+  phaseSpans,
   pointAt,
   polylineLength,
+  rectOfPath,
   roundedPath,
   routeEdges,
   runBounds,

package/dist/nested-layout.d.ts

@@ -0,0 +1,66 @@
+import { type NodeSize } from './layout';
+import type { CompiledDiagram, CompiledNode, Layout, NodeDiagram, Pt, Rect } from './types';
+/**
+ * What an expanded node adds around the inner diagram: the header that names it, and a margin.
+ * The inner layout already keeps a margin of its own, so the sides stay thin.
+ */
+export declare const INLINE_PAD: {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+};
+/** A diagram laid out together with the diagrams expanded inside it, at any depth. */
+export interface NestedLayout {
+    layout: Layout;
+    /** By node id: the layout of the diagram that node shows in place. */
+    inner: Record<string, InnerLayout>;
+}
+export interface InnerLayout {
+    /** Name of the diagram shown. */
+    name: string;
+    viewId: string;
+    /** Where the inner diagram's origin sits inside the expanded node's rectangle. */
+    offset: Pt;
+    layout: NestedLayout;
+}
+export type Diagrams = Record<string, CompiledDiagram | undefined>;
+/** The view a node's diagram shows when opened: the one named, the scenario's, or the first. */
+export declare function openingView(diagram: CompiledDiagram, ref: NodeDiagram): string;
+/** Whether a reader may show this node's diagram in place: it is at hand and not limited to `open`. */
+export declare const canExpand: (ref: NodeDiagram | undefined, diagrams: Diagrams) => boolean;
+/** Whether a reader may move into this node's diagram: it is at hand and not limited to `expand`. */
+export declare const canOpen: (ref: NodeDiagram | undefined, diagrams: Diagrams) => boolean;
+/** Paths are node ids joined with `/` (ids cannot contain it): `orders`, `orders/stock`. */
+export declare const pathJoin: (prefix: string, id: string) => string;
+/**
+ * The paths the author asked to start expanded (`expanded: true`), at every depth. A node counts
+ * wherever it sits in its diagram, in whichever view, so switching views loses nothing.
+ */
+export declare function defaultExpanded(diagram: CompiledDiagram, diagrams: Diagrams, prefix?: string, seen?: readonly string[]): string[];
+/**
+ * Every node whose card has to be measured to lay `viewId` out with these paths expanded: the
+ * view's own, and those of each diagram shown in place. `key` is the path, which is what the
+ * layout reads sizes by.
+ */
+export declare function measurable(diagram: CompiledDiagram, viewId: string, expanded: ReadonlySet<string>, diagrams: Diagrams, prefix?: string): {
+    key: string;
+    node: CompiledNode;
+}[];
+export interface NestedOptions {
+    /** Measured card sizes by path. A plain node id for the diagram itself, `orders/api` inside. */
+    sizes?: Record<string, Partial<NodeSize>>;
+    /** Paths shown in place. */
+    expanded?: ReadonlySet<string>;
+    /** Where the diagrams a node opens are found, by name. */
+    diagrams?: Diagrams;
+    prefix?: string;
+}
+/** Lay out `viewId` with the nodes in `expanded` shown in place, each as a group around its diagram. */
+export declare function layoutNested(diagram: CompiledDiagram, viewId: string, { sizes, expanded, diagrams, prefix }?: NestedOptions): Promise<NestedLayout>;
+/**
+ * Where a node sits in the world of the diagram laid out first, however deep it is: the rectangle
+ * of `orders/stock` is `stock`'s inside `orders`, moved to where `orders` is. Undefined when a
+ * step of the path is not laid out (it is not expanded, or not in the view).
+ */
+export declare function rectOfPath(nested: NestedLayout, path: string): Rect | undefined;

package/dist/nesting.d.ts

@@ -0,0 +1,24 @@
+import type { Diagnostic, Where } from './compiler';
+import type { CompiledDiagram } from './types';
+/** What the linker needs to know about one diagram folder. `diagram` is missing when it failed to compile. */
+export interface LinkEntry {
+    diagram?: CompiledDiagram;
+    where?: Where;
+}
+/**
+ * Every diagram that `name` can reach by opening nodes, directly or through other diagrams, but
+ * not `name` itself.
+ */
+export declare function nestedDiagrams(all: Record<string, CompiledDiagram>, name: string): Record<string, CompiledDiagram>;
+/**
+ * Give every diagram that opens others the diagrams it can reach, as `nested`, so wherever a
+ * compiled diagram goes its insides go with it and the viewer is told nothing. Diagrams that open
+ * nothing are returned as they are. Safe to call twice.
+ */
+export declare function attachNested(all: Record<string, CompiledDiagram>): Record<string, CompiledDiagram>;
+/**
+ * Check what no single diagram can: that a node opens a diagram which exists, that the view and
+ * scenario it asks for exist there, and that diagrams do not open each other in a circle (a node
+ * cannot contain itself).
+ */
+export declare function linkDiagrams(entries: Record<string, LinkEntry>): Diagnostic[];

package/dist/node.d.ts

@@ -3,6 +3,7 @@ import type { CompiledDiagram } from './types';
 export * from './compile';
 export { loadIconSets, resolveIcon, searchIcons } from './icons';
 export { renderMarkdown } from './markdown';
+export { attachNested, type LinkEntry, linkDiagrams, nestedDiagrams } from './nesting';
 export { authoringJsonSchema, FamilySchema, KNOWN_KEYS, RootSchema } from './schema';
 export interface LoadedProject {
     diagrams: Record<string, CompiledDiagram>;

package/dist/node.js

@@ -1,3 +1,8 @@
+import {
+  attachNested,
+  linkDiagrams,
+  nestedDiagrams
+} from "./chunk-3QBMUILO.js";
 import {
   FamilySchema,
   KNOWN_KEYS,
@@ -6,8 +11,8 @@ import {
   compileDiagram,
   createIconResolver,
   renderMarkdown
-} from "./chunk-5BMICZRC.js";
-import "./chunk-FRVCGXIG.js";
+} from "./chunk-S7M3BRFI.js";
+import "./chunk-ITBBPZE6.js";
 
 // src/node.ts
 import { existsSync, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
@@ -48,6 +53,7 @@ function loadProject(root, dir = "diagrams") {
   const base = diagramsDir(root, dir);
   const result = { diagrams: {}, diagnostics: [], watch: [base] };
   if (!existsSync(base)) return result;
+  const entries = {};
   for (const name of readdirSync(base).sort()) {
     const folder = join(base, name);
     if (!statSync(folder).isDirectory()) continue;
@@ -59,7 +65,7 @@ function loadProject(root, dir = "diagrams") {
       file: join(scenarioDir, f),
       text: readFileSync2(join(scenarioDir, f), "utf8")
     })) : [];
-    const { diagram, diagnostics } = compileDiagram2({
+    const { diagram, diagnostics, where } = compileDiagram2({
       name,
       file: relative(root, file),
       text: readFileSync2(file, "utf8"),
@@ -68,8 +74,11 @@ function loadProject(root, dir = "diagrams") {
     });
     result.diagnostics.push(...diagnostics);
     if (diagram) result.diagrams[name] = diagram;
+    entries[name] = { diagram, where };
     result.watch.push(folder);
   }
+  result.diagnostics.push(...linkDiagrams(entries));
+  result.diagrams = attachNested(result.diagrams);
   return result;
 }
 function readInside(folder, rel) {
@@ -91,12 +100,15 @@ export {
   FamilySchema,
   KNOWN_KEYS,
   RootSchema,
+  attachNested,
   authoringJsonSchema,
   compileDiagram2 as compileDiagram,
   diagramsDir,
   formatDiagnostic,
+  linkDiagrams,
   loadIconSets,
   loadProject,
+  nestedDiagrams,
   renderMarkdown,
   resolveIcon,
   searchIcons

package/dist/outline.d.ts

@@ -0,0 +1,63 @@
+import { type Diagrams } from './nested-layout';
+import type { CompiledDiagram, CompiledView, IconData, Status } from './types';
+/** One edge of a node, seen from that node. */
+export interface OutlineConnection {
+    edge: string;
+    /** `out`: this node sends to `other`; `in`: it receives from `other`; `both`: edge goes either way. */
+    dir: 'out' | 'in' | 'both';
+    /** Id of the node at the other end, in the same diagram. */
+    other: string;
+    /** Its title, so a row needs nothing else to be read. */
+    otherTitle: string;
+    label?: string;
+    kind: string;
+    status: Status;
+}
+export interface OutlineNode {
+    type: 'node';
+    /** The node id, or ids joined with `/` for a node inside one shown in place (`orders/stock`). */
+    path: string;
+    id: string;
+    title: string;
+    sub?: string;
+    icon?: IconData;
+    status: Status;
+    connections: OutlineConnection[];
+    /** Present when the node holds a diagram the reader can reach. */
+    inside?: {
+        title: string;
+        /** The reader may show it in place, and may move into it. */
+        expand: boolean;
+        open: boolean;
+        /** Shown in place right now; `items` are then the nodes of that diagram. */
+        expanded: boolean;
+        items: OutlineItem[];
+    };
+}
+export interface OutlineGroup {
+    type: 'group';
+    /** Group id, prefixed like a node path so it is unique across the levels shown in place. */
+    path: string;
+    id: string;
+    title: string;
+    caption?: string;
+    icon?: IconData;
+    status: Status;
+    items: OutlineItem[];
+    /** How many nodes it holds, however deep. */
+    count: number;
+}
+export type OutlineItem = OutlineNode | OutlineGroup;
+export interface OutlineOptions {
+    /** Where the diagrams a node holds are found, by name. */
+    diagrams?: Diagrams;
+    /** Paths shown in place. */
+    expanded?: ReadonlySet<string>;
+    prefix?: string;
+    /** Diagrams already on the way down, so a loop cannot run forever. */
+    seen?: readonly string[];
+}
+/** The nodes and groups of `view` as a tree, in the order the author wrote them. */
+export declare function buildOutline(diagram: CompiledDiagram, view: CompiledView, { diagrams, expanded, prefix, seen }?: OutlineOptions): OutlineItem[];
+/** Every node of an outline, in reading order, at any depth. */
+export declare function outlineNodes(items: readonly OutlineItem[]): OutlineNode[];

package/dist/phases.d.ts

@@ -0,0 +1,16 @@
+import type { CompiledScenario } from './types';
+export interface PhaseSpan {
+    /** Index in `scenario.phases`. */
+    index: number;
+    title: string;
+    caption?: string;
+    /** Index of its first and last step in `scenario.steps`. */
+    from: number;
+    to: number;
+    /** How many steps it holds. */
+    count: number;
+}
+/** Whether the author named the phases. A scenario written as plain `steps` has one nameless phase. */
+export declare const hasPhases: (scenario: CompiledScenario) => boolean;
+/** The phases that hold steps, in order. Steps follow their phase, so each phase is one run. */
+export declare function phaseSpans(scenario: CompiledScenario): PhaseSpan[];

package/dist/schema.d.ts

@@ -65,6 +65,17 @@ export declare const NodeSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    diagram: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        view: z.ZodOptional<z.ZodString>;
+        scenario: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            both: "both";
+            expand: "expand";
+            open: "open";
+        }>>;
+        expanded: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
 }, z.core.$strict>;
 export declare const GroupSchema: z.ZodObject<{
     label: z.ZodString;
@@ -521,6 +532,17 @@ export declare const RootSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        diagram: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            name: z.ZodString;
+            view: z.ZodOptional<z.ZodString>;
+            scenario: z.ZodOptional<z.ZodString>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                both: "both";
+                expand: "expand";
+                open: "open";
+            }>>;
+            expanded: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>;
     }, z.core.$strict>>;
     edges: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;

package/dist/suggest.d.ts

@@ -0,0 +1 @@
+export declare function didYouMean(word: string, options: readonly string[]): string | undefined;

package/dist/types.d.ts

@@ -19,6 +19,16 @@ export interface NodeLink {
     label: string;
     url: string;
 }
+/** Another diagram that shows the inside of a node. Resolved by name against the project's diagrams. */
+export interface NodeDiagram {
+    name: string;
+    view?: string;
+    scenario?: string;
+    /** How a reader can get at it: shown in place (`expand`), moved into (`open`), or either. */
+    mode?: 'both' | 'expand' | 'open';
+    /** Starts shown in place. */
+    expanded?: boolean;
+}
 export interface CompiledNode {
     id: string;
     title: string;
@@ -37,6 +47,8 @@ export interface CompiledNode {
     links: NodeLink[];
     refs: string[];
     tags: string[];
+    /** Opens one level deeper: the diagram that describes this node's inside. */
+    diagram?: NodeDiagram;
 }
 export interface CompiledGroup {
     id: string;
@@ -145,6 +157,12 @@ export interface CompiledDiagram {
     edgeKinds: Record<string, EdgeKindDef>;
     views: CompiledView[];
     scenarios: CompiledScenario[];
+    /**
+     * The diagrams its nodes open, by name, and the ones those open in turn. Added once every
+     * diagram of the project has compiled (`attachNested`), so a diagram is all a viewer needs. The
+     * entries themselves carry no `nested`.
+     */
+    nested?: Record<string, CompiledDiagram>;
 }
 export interface Pt {
     x: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-package-labs/idocs-core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {