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

package/dist/browser.js

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

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

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

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

@@ -1,9 +1,10 @@
 import {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
+  DEFAULT_ENTITY_WIDTH,
   didYouMean,
   letterKey
-} from "./chunk-ITBBPZE6.js";
+} from "./chunk-ZYFFV7Y7.js";
 
 // src/icon-resolver.ts
 import { getIconData, iconToSVG } from "@iconify/utils";
@@ -215,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."),
@@ -354,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,
@@ -380,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" });
@@ -589,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(
@@ -617,11 +659,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 +687,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 +695,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 +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;
     }
@@ -670,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,
@@ -684,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(
@@ -701,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,
@@ -713,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) => {
@@ -765,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);
@@ -1042,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":

package/dist/{chunk-ITBBPZE6.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) {
@@ -136,6 +139,7 @@ export {
   BUILTIN_EDGE_KINDS,
   STEP_KIND_COLORS,
   DEFAULT_NODE_WIDTH,
+  DEFAULT_ENTITY_WIDTH,
   polylineLength,
   dist,
   pointAt,

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

@@ -6,6 +6,8 @@ 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';

package/dist/index.js

@@ -2,10 +2,11 @@ import {
   attachNested,
   linkDiagrams,
   nestedDiagrams
-} from "./chunk-3QBMUILO.js";
+} from "./chunk-P2X2XSBM.js";
 import {
   BUILTIN_EDGE_KINDS,
   BUILTIN_KINDS,
+  DEFAULT_ENTITY_WIDTH,
   DEFAULT_NODE_WIDTH,
   STEP_KIND_COLORS,
   dist,
@@ -13,7 +14,7 @@ import {
   pointAt,
   polylineLength,
   roundedPath
-} from "./chunk-ITBBPZE6.js";
+} from "./chunk-ZYFFV7Y7.js";
 
 // src/layout.ts
 import ELK from "elkjs/lib/elk.bundled.js";
@@ -960,9 +961,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 +1188,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,16 +1561,19 @@ 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,
   frameAt,
   hasPhases,
@@ -1511,12 +1591,17 @@ export {
   phaseSpans,
   pointAt,
   polylineLength,
+  positionAt,
   rectOfPath,
   roundedPath,
   routeEdges,
   runBounds,
   scopeSvgIds,
+  slotAt,
+  slotOfStep,
+  startOf,
   stepAt,
   stepEnd,
-  stepStart
+  stepStart,
+  timeAt
 };

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-P2X2XSBM.js";
 import {
   FamilySchema,
   KNOWN_KEYS,
@@ -11,8 +11,8 @@ import {
   compileDiagram,
   createIconResolver,
   renderMarkdown
-} from "./chunk-S7M3BRFI.js";
-import "./chunk-ITBBPZE6.js";
+} from "./chunk-Q2NHZ6TV.js";
+import "./chunk-ZYFFV7Y7.js";
 
 // src/node.ts
 import { existsSync, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/schema.d.ts

@@ -28,10 +28,24 @@ export declare const DirectionSchema: z.ZodEnum<{
     RIGHT: "RIGHT";
     UP: "UP";
 }>;
+/** One field per list item: `- name`, `- name: type` or `- name: { type, key, ref, note }`. */
+declare const FieldSchema: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodBoolean>;
+    ref: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>>]>;
 export declare const NodeSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     sub: z.ZodOptional<z.ZodString>;
+    pill: z.ZodOptional<z.ZodString>;
     lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodBoolean>;
+        ref: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>]>>>;
     icon: z.ZodOptional<z.ZodString>;
     kind: z.ZodOptional<z.ZodString>;
     family: z.ZodOptional<z.ZodEnum<{
@@ -440,10 +454,34 @@ export declare const ScenarioSchema: z.ZodObject<{
         }, z.core.$strict>], "type">>;
     }, z.core.$strict>], "type">>>;
 }, z.core.$strict>;
+export declare const DefaultsSchema: z.ZodObject<{
+    view: z.ZodOptional<z.ZodString>;
+    scenario: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        flow: "flow";
+        sequence: "sequence";
+        story: "story";
+    }>>;
+    sidebar: z.ZodOptional<z.ZodBoolean>;
+    subtitles: z.ZodOptional<z.ZodBoolean>;
+    autoplay: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
 export declare const RootSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    defaults: z.ZodOptional<z.ZodObject<{
+        view: z.ZodOptional<z.ZodString>;
+        scenario: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            flow: "flow";
+            sequence: "sequence";
+            story: "story";
+        }>>;
+        sidebar: z.ZodOptional<z.ZodBoolean>;
+        subtitles: z.ZodOptional<z.ZodBoolean>;
+        autoplay: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     kinds: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         icon: z.ZodOptional<z.ZodString>;
         family: z.ZodOptional<z.ZodEnum<{
@@ -498,7 +536,14 @@ export declare const RootSchema: z.ZodObject<{
     nodes: z.ZodRecord<z.ZodString, z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         sub: z.ZodOptional<z.ZodString>;
+        pill: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            key: z.ZodOptional<z.ZodBoolean>;
+            ref: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>]>>>;
         icon: z.ZodOptional<z.ZodString>;
         kind: z.ZodOptional<z.ZodString>;
         family: z.ZodOptional<z.ZodEnum<{
@@ -784,6 +829,7 @@ export declare const RootSchema: z.ZodObject<{
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type RootInput = z.infer<typeof RootSchema>;
+export type FieldInput = z.infer<typeof FieldSchema>;
 export type Step = z.infer<typeof StepSchema>;
 export declare const KNOWN_KEYS: {
     readonly root: string[];
@@ -792,6 +838,7 @@ export declare const KNOWN_KEYS: {
     readonly edge: string[];
     readonly view: string[];
     readonly scenario: string[];
+    readonly defaults: string[];
 };
 type Json = Record<string, unknown>;
 /**

package/dist/scrubber.d.ts

@@ -0,0 +1,34 @@
+import type { Timeline } from './timeline';
+/** One stop of the slider: a step, or the steps of a `par` block that start together. */
+export interface Slot {
+    /** First and last step of the slot, as indexes into `scenario.steps`. */
+    from: number;
+    to: number;
+    /** The time it covers. A slot runs until the next one starts, so pauses belong to the step before. */
+    t0: number;
+    t1: number;
+}
+/** A run of slots under one phase. A scenario without named phases is one section with no title. */
+export interface Section {
+    /** Index in `scenario.phases`. */
+    phase: number;
+    title: string;
+    caption?: string;
+    /** First and last slot. */
+    from: number;
+    to: number;
+}
+export interface Scrubber {
+    slots: Slot[];
+    sections: Section[];
+    duration: number;
+}
+export declare function buildScrubber(tl: Timeline): Scrubber;
+/** Where on the slider, 0 to 1, the moment `t` falls. */
+export declare function positionAt(s: Scrubber, t: number): number;
+/** The moment a place on the slider stands for. The inverse of `positionAt`. */
+export declare function timeAt(s: Scrubber, position: number): number;
+/** The slot a place on the slider falls in. */
+export declare function slotAt(s: Scrubber, position: number): number;
+/** The slot that holds step `index`, or -1. */
+export declare function slotOfStep(s: Scrubber, index: number): number;

package/dist/start.d.ts

@@ -0,0 +1,22 @@
+import type { CompiledDiagram, ScenarioMode } from './types';
+/** What the page that shows a diagram asked for, if anything. Its choices win over the diagram's. */
+export interface StartWant {
+    view?: string;
+    scenario?: string;
+    mode?: ScenarioMode;
+}
+export interface Start {
+    /** Always one of the diagram's views. */
+    view: string;
+    /** The scenario selected first, or null for the overview. */
+    scenario: string | null;
+    mode: ScenarioMode;
+}
+/** The mode a scenario is drawn in when neither it nor the page says: the diagram's, then `flow`. */
+export declare const defaultMode: (diagram: CompiledDiagram) => ScenarioMode;
+/**
+ * Where a diagram opens. The page's props come first, then what the diagram's author wrote under
+ * `defaults`, then the first view with nothing selected. The page choosing a scenario takes its
+ * view along, and one choosing a view leaves the default scenario out unless it plays there.
+ */
+export declare function startOf(diagram: CompiledDiagram, want?: StartWant): Start;

package/dist/types.d.ts

@@ -29,11 +29,27 @@ export interface NodeDiagram {
     /** Starts shown in place. */
     expanded?: boolean;
 }
+/** A row of an entity card: one column, property or attribute of what the node stores. */
+export interface CompiledField {
+    name: string;
+    type?: string;
+    /** Part of the primary key. */
+    key?: boolean;
+    /** The node (and field) this one points at, like a foreign key. Each one draws a relation. */
+    ref?: {
+        node: string;
+        field?: string;
+    };
+    note?: string;
+}
 export interface CompiledNode {
     id: string;
     title: string;
     sub?: string;
+    /** A short label in the card header, like `TABLE` or `ES INDEX`. */
+    pill?: string;
     lines: string[];
+    fields: CompiledField[];
     icon?: IconData;
     kind?: string;
     family?: Family;
@@ -76,6 +92,9 @@ export interface CompiledEdge {
     id: string;
     from: string;
     to: string;
+    /** Set when the edge starts or ends on one field of an entity card. */
+    fromField?: string;
+    toField?: string;
     label?: string;
     kind: string;
     both: boolean;
@@ -147,10 +166,23 @@ export interface CompiledScenario {
     phases: CompiledPhase[];
     steps: CompiledStep[];
 }
+/**
+ * How a diagram opens, as its author wrote it. A page's own choices (the props of `<Diagram>`) win
+ * over these. Validated by the compiler: the view and the scenario exist, and agree.
+ */
+export interface DiagramDefaults {
+    view?: string;
+    scenario?: string;
+    mode?: ScenarioMode;
+    sidebar?: boolean;
+    subtitles?: boolean;
+    autoplay?: boolean;
+}
 export interface CompiledDiagram {
     name: string;
     title: string;
     descriptionHtml?: string;
+    defaults?: DiagramDefaults;
     nodes: Record<string, CompiledNode>;
     groups: Record<string, CompiledGroup>;
     edges: Record<string, CompiledEdge>;

package/package.json

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