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

package/dist/{chunk-S7M3BRFI.js → chunk-MUGDM3EQ.js}

@@ -1,9 +1,14 @@
 import {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
+  DEFAULT_ENTITY_WIDTH,
   didYouMean,
-  letterKey
-} from "./chunk-ITBBPZE6.js";
+  highlightSegments,
+  languageLabel,
+  letterKey,
+  splitPlaceholders,
+  takesPlaceholders
+} from "./chunk-H77C3DSX.js";
 
 // src/icon-resolver.ts
 import { getIconData, iconToSVG } from "@iconify/utils";
@@ -103,7 +108,62 @@ import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { unified } from "unified";
-var processor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype).use(rehypeStringify);
+var isElement = (n, tag) => n.type === "element" && (tag === void 0 || n.tagName === tag);
+var classesOf = (el2) => {
+  const c = el2.properties.className;
+  return Array.isArray(c) ? c.map(String) : typeof c === "string" ? c.split(/\s+/) : [];
+};
+var titleOf = (meta) => {
+  const m = meta?.match(/\btitle=(?:"([^"]*)"|'([^']*)')/);
+  return m?.[1] ?? m?.[2];
+};
+var el = (tagName, properties, children = []) => ({ type: "element", tagName, properties, children });
+function commandBlocks() {
+  const wrap = (pre) => {
+    const code = pre.children.find((c) => isElement(c, "code"));
+    if (!code || !isElement(code)) return pre;
+    const lang = classesOf(code).find((c) => c.startsWith("language-"))?.slice("language-".length);
+    const title = titleOf(code.data?.meta);
+    if (code.children.every((c) => c.type === "text")) {
+      const text = code.children.map((c) => c.value).join("");
+      const segments = takesPlaceholders(lang, code.data?.meta) ? splitPlaceholders(text) : [{ kind: "text", text }];
+      code.children = highlightSegments(lang, segments).map((piece) => {
+        if (piece.kind === "var") {
+          const { key, raw } = piece.segment;
+          return el("span", { className: ["idocs-ph"], dataKey: key, dataRaw: raw }, [
+            { type: "text", value: raw }
+          ]);
+        }
+        return piece.cls ? el("span", { className: [`hl-${piece.cls}`] }, [{ type: "text", value: piece.text }]) : { type: "text", value: piece.text };
+      });
+    }
+    return el(
+      "div",
+      { className: ["idocs-cmd"], dataIdocsCmd: "", ...lang ? { dataLang: lang } : {} },
+      [
+        el("div", { className: ["idocs-cmd-head"] }, [
+          el("span", { className: ["idocs-cmd-lang"] }, [
+            { type: "text", value: languageLabel(lang) }
+          ]),
+          ...title ? [el("span", { className: ["idocs-cmd-title"] }, [{ type: "text", value: title }])] : [],
+          el("div", { className: ["idocs-cmd-bar"] })
+        ]),
+        pre,
+        el("div", { className: ["idocs-cmd-panel"] })
+      ]
+    );
+  };
+  const walk = (node) => {
+    if (!("children" in node) || !node.children) return;
+    node.children = node.children.map((c) => {
+      if (isElement(c, "pre")) return wrap(c);
+      walk(c);
+      return c;
+    });
+  };
+  return (tree) => walk(tree);
+}
+var processor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype).use(commandBlocks).use(rehypeStringify);
 function renderMarkdown(md) {
   const body = stripFrontmatter(md).trim();
   if (!body) return "";
@@ -215,10 +275,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."),
@@ -354,10 +432,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,
@@ -380,7 +479,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" });
@@ -589,6 +689,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(
@@ -617,11 +718,26 @@ function build(data, src, error, warn, { resolveIcon }) {
     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,
@@ -630,7 +746,7 @@ 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 ?? [],
@@ -638,18 +754,39 @@ function build(data, src, error, warn, { resolveIcon }) {
       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}"`,
@@ -658,7 +795,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;
     }
@@ -670,8 +807,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,
@@ -684,6 +823,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(
@@ -701,10 +866,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,
@@ -713,6 +880,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) => {
@@ -765,6 +963,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);
@@ -1042,6 +1272,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":

package/dist/{chunk-3QBMUILO.js → chunk-RJUH342Z.js}

@@ -1,6 +1,6 @@
 import {
   didYouMean
-} from "./chunk-ITBBPZE6.js";
+} from "./chunk-H77C3DSX.js";
 
 // src/nesting.ts
 function nestedDiagrams(all, name) {

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/highlight.d.ts

@@ -0,0 +1,21 @@
+import type { PlaceholderSegment } from './placeholders';
+export type TokenClass = 'comment' | 'string' | 'keyword' | 'flag' | 'number' | 'variable' | 'key' | 'literal' | 'operator' | 'section';
+export interface Token {
+    text: string;
+    cls?: TokenClass;
+}
+/** The name of a language as a block's header shows it. Blocks with none are text. */
+export declare function languageLabel(lang: string | undefined): string;
+export declare function highlight(lang: string | undefined, text: string): Token[];
+export type Piece = {
+    kind: 'text';
+    text: string;
+    cls?: TokenClass;
+} | {
+    kind: 'var';
+    segment: Extract<PlaceholderSegment, {
+        kind: 'var';
+    }>;
+};
+/** A block's text as pieces to draw: coloured runs, with each placeholder where it was. */
+export declare function highlightSegments(lang: string | undefined, segments: PlaceholderSegment[]): Piece[];

package/dist/index.d.ts

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

package/dist/index.js

@@ -2,18 +2,31 @@ import {
   attachNested,
   linkDiagrams,
   nestedDiagrams
-} from "./chunk-3QBMUILO.js";
+} from "./chunk-RJUH342Z.js";
 import {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
+  DEFAULT_ENTITY_WIDTH,
   DEFAULT_NODE_WIDTH,
   STEP_KIND_COLORS,
   dist,
+  fillPlaceholders,
+  fillSegments,
+  highlight,
+  highlightSegments,
+  isSecretKey,
+  languageLabel,
   letterKey,
+  placeholdersOf,
   pointAt,
   polylineLength,
-  roundedPath
-} from "./chunk-ITBBPZE6.js";
+  roundedPath,
+  shownPlaceholder,
+  splitPlaceholders,
+  takesPlaceholders,
+  unsetPlaceholders,
+  varKey
+} from "./chunk-H77C3DSX.js";
 
 // src/layout.ts
 import ELK from "elkjs/lib/elk.bundled.js";
@@ -960,9 +973,10 @@ function overlap(a, b, pad) {
 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;
+  const of = (scenario) => diagram.scenarios.find((s) => s.id === scenario)?.view;
+  return [ref.view, of(ref.scenario), of(diagram.defaults?.scenario), diagram.defaults?.view].find(
+    has
+  ) ?? 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];
@@ -1186,6 +1200,81 @@ function phaseSpans(scenario) {
   return out;
 }
 
+// src/scrubber.ts
+function buildScrubber(tl) {
+  const steps = tl.scenario.steps;
+  const slots = [];
+  let i = 0;
+  while (i < steps.length) {
+    let j = i + 1;
+    const par = steps[i].par;
+    if (par !== void 0) while (j < steps.length && steps[j].par === par) j++;
+    const run = tl.steps.slice(i, j);
+    slots.push({ from: i, to: j - 1, t0: Math.min(...run.map((s) => s.start)), t1: 0 });
+    i = j;
+  }
+  slots.forEach((slot, k) => {
+    slot.t1 = slots[k + 1]?.t0 ?? tl.duration;
+  });
+  if (slots[0]) slots[0].t0 = 0;
+  const slotOf = (step) => slots.findIndex((s) => s.from <= step && step <= s.to);
+  const sections = phaseSpans(tl.scenario).map((span) => ({
+    phase: span.index,
+    title: span.title,
+    caption: span.caption,
+    from: slotOf(span.from),
+    to: slotOf(span.to)
+  }));
+  return { slots, sections, duration: tl.duration };
+}
+var clamp01 = (n) => Math.min(1, Math.max(0, n));
+function positionAt(s, t) {
+  const n = s.slots.length;
+  if (!n) return 0;
+  let k = 0;
+  s.slots.forEach((slot2, i) => {
+    if (slot2.t0 <= t) k = i;
+  });
+  const slot = s.slots[k];
+  const length = slot.t1 - slot.t0;
+  return (k + (length > 0 ? clamp01((t - slot.t0) / length) : 0)) / n;
+}
+function timeAt(s, position) {
+  const n = s.slots.length;
+  if (!n) return 0;
+  const x = clamp01(position) * n;
+  const k = Math.min(n - 1, Math.floor(x));
+  const slot = s.slots[k];
+  return slot.t0 + (x - k) * (slot.t1 - slot.t0);
+}
+function slotAt(s, position) {
+  const n = s.slots.length;
+  return n ? Math.min(n - 1, Math.floor(clamp01(position) * n)) : -1;
+}
+function slotOfStep(s, index) {
+  return s.slots.findIndex((slot) => slot.from <= index && index <= slot.to);
+}
+
+// src/start.ts
+var defaultMode = (diagram) => diagram.defaults?.mode ?? "flow";
+function startOf(diagram, want = {}) {
+  const d = diagram.defaults ?? {};
+  const scenarioById = (id) => diagram.scenarios.find((s) => s.id === id);
+  const hasView = (id) => diagram.views.some((v) => v.id === id);
+  const first = diagram.views[0].id;
+  let view;
+  let scenario;
+  if (want.view !== void 0 || want.scenario !== void 0) {
+    view = [want.view, scenarioById(want.scenario)?.view].find(hasView) ?? first;
+    scenario = scenarioById(want.scenario)?.id ?? (scenarioById(d.scenario)?.view === view ? d.scenario ?? null : null);
+  } else {
+    scenario = scenarioById(d.scenario)?.id ?? null;
+    view = [scenarioById(scenario ?? void 0)?.view, d.view].find(hasView) ?? first;
+  }
+  const mode = want.mode ?? scenarioById(scenario ?? void 0)?.mode ?? defaultMode(diagram);
+  return { view, scenario, mode };
+}
+
 // src/story.ts
 function buildStory(diagram, scenario) {
   const steps = scenario.steps;
@@ -1484,20 +1573,29 @@ function runBounds(tl, index) {
 export {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
+  DEFAULT_ENTITY_WIDTH,
   DEFAULT_NODE_WIDTH,
   INLINE_PAD,
   STEP_KIND_COLORS,
   attachNested,
   buildOutline,
+  buildScrubber,
   buildStory,
   buildTimeline,
   canExpand,
   canOpen,
   defaultExpanded,
+  defaultMode,
   dist,
+  fillPlaceholders,
+  fillSegments,
   frameAt,
   hasPhases,
+  highlight,
+  highlightSegments,
+  isSecretKey,
   labelWidth,
+  languageLabel,
   layoutNested,
   layoutView,
   letterKey,
@@ -1509,14 +1607,25 @@ export {
   packGrid,
   pathJoin,
   phaseSpans,
+  placeholdersOf,
   pointAt,
   polylineLength,
+  positionAt,
   rectOfPath,
   roundedPath,
   routeEdges,
   runBounds,
   scopeSvgIds,
+  shownPlaceholder,
+  slotAt,
+  slotOfStep,
+  splitPlaceholders,
+  startOf,
   stepAt,
   stepEnd,
-  stepStart
+  stepStart,
+  takesPlaceholders,
+  timeAt,
+  unsetPlaceholders,
+  varKey
 };

package/dist/nested-layout.d.ts

@@ -25,7 +25,10 @@ export interface InnerLayout {
     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. */
+/**
+ * The view a node's diagram shows when opened: the one the node names, its scenario's, the one the
+ * diagram opens on by itself, 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;

package/dist/node.js

@@ -2,7 +2,7 @@ import {
   attachNested,
   linkDiagrams,
   nestedDiagrams
-} from "./chunk-3QBMUILO.js";
+} from "./chunk-RJUH342Z.js";
 import {
   FamilySchema,
   KNOWN_KEYS,
@@ -11,8 +11,8 @@ import {
   compileDiagram,
   createIconResolver,
   renderMarkdown
-} from "./chunk-S7M3BRFI.js";
-import "./chunk-ITBBPZE6.js";
+} from "./chunk-MUGDM3EQ.js";
+import "./chunk-H77C3DSX.js";
 
 // src/node.ts
 import { existsSync, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";