@metaobjectsdev/docs-site 0.15.8-rc.1

package/src/link-graph.ts

@@ -0,0 +1,204 @@
+import type { MetaData, MetaObject, MetaRelationship } from "@metaobjectsdev/metadata";
+import { deriveM2MFields, stripPackage } from "@metaobjectsdev/metadata";
+import { type LoadedModel, treeOf } from "./load";
+
+export interface DocNode { kind: "object" | "prompt" | "output"; name: string; pkg: string; pkgPath: string; href: string; node: MetaData; tree: string; }
+export interface Ref {
+  from: string; to: string; via: string;
+  kind: "field" | "fk" | "extends" | "payload" | "relationship" | "origin";
+  cardinality?: "one" | "many" | undefined;
+  through?: string | undefined;         // junction FQN (M:N)
+  sourceJoinField?: string | undefined; // junction source FK (M:N)
+  targetJoinField?: string | undefined; // junction target FK (M:N)
+  symmetric?: boolean | undefined;      // undirected self-join (M:N)
+  onDelete?: string | undefined;        // referential action
+  subtype?: string | undefined;         // association / aggregation / composition
+}
+export interface OriginRef { field: string; from: string; via: string; }
+
+export function pkgOf(node: MetaData): string {
+  return (node.package ?? (node as { fileDefaultPackage?: string }).fileDefaultPackage ?? "");
+}
+export function fqnOf(node: MetaData): string {
+  const p = pkgOf(node);
+  return p ? `${p}::${node.name}` : node.name;
+}
+
+export class LinkGraph {
+  private _nodes = new Map<string, DocNode>();
+  private _from = new Map<string, Ref[]>();
+  private _to = new Map<string, Ref[]>();
+  private _extBy = new Map<string, DocNode[]>();
+  private _origins = new Map<string, OriginRef[]>();
+
+  constructor(model: LoadedModel) {
+    for (const o of model.root.ownChildren()) {
+      let kind: DocNode["kind"] | undefined;
+      if (o.type === "object") kind = "object";
+      else if (o.type === "template") kind = o.subType === "prompt" ? "prompt" : "output";
+      if (!kind) continue;
+      const pkg = pkgOf(o);
+      const pkgPath = pkg.split("::").join("/");
+      this._nodes.set(fqnOf(o), {
+        kind, name: o.name, pkg, pkgPath,
+        href: `${pkgPath}/${o.name}.html`, node: o, tree: treeOf(o, model),
+      });
+    }
+    const addRef = (r: Ref) => {
+      (this._from.get(r.from) ?? this._from.set(r.from, []).get(r.from)!).push(r);
+      (this._to.get(r.to) ?? this._to.set(r.to, []).get(r.to)!).push(r);
+    };
+    const resolveRef = (raw: string, ctxPkg: string): string | undefined => {
+      const cand = raw.includes("::") ? raw : `${ctxPkg}::${raw}`;
+      return this._nodes.has(cand) ? cand : (this._nodes.has(raw) ? raw : undefined);
+    };
+    // M:N through-junction edge. Derives the junction FK fields via the metadata
+    // SSOT (deriveM2MFields) — hetero, directed (@sourceRefField), or symmetric
+    // (@symmetric). On a derivation failure (ambiguous self-join) the edge is
+    // SKIPPED — generation never fails.
+    const addM2mEdge = (from: string, to: string, rel: MetaRelationship, obj: MetaObject, ctxPkg: string, onDelete: string | undefined, subtype: string | undefined): void => {
+      const through = rel.through ? (resolveRef(rel.through, ctxPkg) ?? rel.through) : undefined;
+      let sourceJoinField: string | undefined, targetJoinField: string | undefined;
+      try {
+        const f = deriveM2MFields(rel, obj, model.root);
+        sourceJoinField = f.sourceField;
+        targetJoinField = f.targetField;
+      } catch {
+        return;  // ambiguous junction — skip the logical edge (the two FK edges still show)
+      }
+      addRef({ from, to, via: rel.name, kind: "relationship", cardinality: "many", through, sourceJoinField, targetJoinField, symmetric: rel.symmetric, onDelete, subtype });
+    };
+    for (const dn of this._nodes.values()) {
+      const fqn = fqnOf(dn.node);
+      if (dn.kind === "object") {
+        for (const f of dn.node.childrenOfType("field")) {
+          const ref = f.attr("objectRef");
+          if (typeof ref === "string") {
+            const to = resolveRef(ref, dn.pkg);
+            if (to) addRef({ from: fqn, to, via: f.name, kind: "field" });
+          }
+        }
+        // dn.node is typed MetaData; the enclosing dn.kind === "object" guard
+        // guarantees it is a MetaObject at runtime. The `unknown` bridge is needed
+        // because MetaData does not structurally narrow to MetaObject for tsc.
+        const obj = dn.node as unknown as MetaObject;
+        // Relationship edges FIRST, so we can suppress the bare FK edge a belongs-to
+        // relationship supersedes. Dedupe is keyed by `${targetFqn}::${fkField}`
+        // (a string, robust to node-instance identity) — the FK loop skips any
+        // reference whose (target, first-field) a belongs-to relationship covered.
+        const coveredFk = new Set<string>();
+        for (const rel of obj.relationships()) {
+          const objectRef = rel.objectRef;
+          if (typeof objectRef !== "string") continue;
+          const to = resolveRef(objectRef, dn.pkg);
+          if (!to) continue;
+          const cardinality = rel.cardinality === "many" ? "many" : rel.cardinality === "one" ? "one" : undefined;
+          const onDelete = rel.onDelete;
+          const subtype = rel.subType;
+          if (cardinality === "many" && rel.through !== undefined) {
+            addM2mEdge(fqn, to, rel, obj, dn.pkg, onDelete, subtype);   // Task 3 helper
+            continue;
+          }
+          // belongs-to (1:N, one) — find the matching identity.reference to dedupe (mirrors
+          // relation-resolver: first reference whose target matches, package-stripped).
+          const target = stripPackage(objectRef);
+          const match = obj.referenceIdentities().find((r) => stripPackage(r.targetEntity ?? "") === target);
+          const fkField = match?.fields?.[0];
+          if (fkField) coveredFk.add(`${to}::${fkField}`);
+          addRef({ from: fqn, to, via: rel.name, kind: "relationship", cardinality, onDelete, subtype });
+        }
+        for (const id of dn.node.childrenOfType("identity")) {
+          if (id.subType !== "reference") continue;
+          const ref = id.attr("references");
+          if (typeof ref === "string") {
+            const to = resolveRef(ref, dn.pkg);
+            if (to) {
+              const fieldsValue = id.attr("fields") ?? id.name;
+              const firstField = Array.isArray(fieldsValue) ? String(fieldsValue[0] ?? "") : String(fieldsValue);
+              if (coveredFk.has(`${to}::${firstField}`)) continue;   // superseded by a relationship edge
+              const via = Array.isArray(fieldsValue) ? fieldsValue.join(", ") : String(fieldsValue);
+              addRef({ from: fqn, to, via, kind: "fk" });
+            }
+          }
+        }
+        for (const f of dn.node.childrenOfType("field")) {
+          for (const org of f.childrenOfType("origin")) {
+            const from = String(org.attr("from") ?? ""), via = String(org.attr("via") ?? "");
+            (this._origins.get(fqn) ?? this._origins.set(fqn, []).get(fqn)!).push({ field: f.name, from, via });
+            // connect a projection to its source object so it is not orphaned on diagrams:
+            // `from` is "pkg::Entity.field" — strip the trailing ".field" to get the source object ref.
+            const dot = from.lastIndexOf(".");
+            const srcRef = dot > 0 ? from.slice(0, dot) : "";
+            const to = srcRef ? resolveRef(srcRef, dn.pkg) : undefined;
+            if (to && to !== fqn) addRef({ from: fqn, to, via: `${f.name} (origin)`, kind: "origin" });
+          }
+        }
+        const sup = dn.node.superResolved;
+        if (sup) {
+          const supFqn = fqnOf(sup);
+          addRef({ from: fqn, to: supFqn, via: "extends", kind: "extends" });
+          (this._extBy.get(supFqn) ?? this._extBy.set(supFqn, []).get(supFqn)!).push(dn);
+        }
+      } else {
+        const p = dn.node.attr("payloadRef");
+        if (typeof p === "string") {
+          const to = resolveRef(p, dn.pkg);
+          if (to) addRef({ from: fqn, to, via: "payloadRef", kind: "payload" });
+        }
+      }
+    }
+  }
+  nodes(): DocNode[] { return [...this._nodes.values()]; }
+  byFqn(fqn: string): DocNode | undefined { return this._nodes.get(fqn); }
+  refsFrom(fqn: string): Ref[] { return this._from.get(fqn) ?? []; }
+  refsTo(fqn: string): Ref[] { return this._to.get(fqn) ?? []; }
+  degree(fqn: string): number {
+    const n = (rs: Ref[]) => rs.filter((r) => r.kind !== "extends").length;
+    return n(this.refsFrom(fqn)) + n(this.refsTo(fqn));
+  }
+  extendedBy(fqn: string): DocNode[] { return this._extBy.get(fqn) ?? []; }
+  originsOf(fqn: string): OriginRef[] { return this._origins.get(fqn) ?? []; }
+  ancestors(fqn: string): DocNode[] {
+    const out: DocNode[] = [];
+    const start = this._nodes.get(fqn);
+    if (!start) return out;
+    for (let s = start.node.superResolved; s; s = s.superResolved) {
+      const t = this._nodes.get(fqnOf(s));
+      if (!t) break;
+      out.push(t);
+    }
+    return out;
+  }
+  relationshipsOf(fqn: string): { name: string; toFqn: string; cardinality: string }[] {
+    return this.refsFrom(fqn).filter((r) => r.kind === "relationship")
+      .map((r) => ({ name: r.via, toFqn: r.to, cardinality: r.cardinality ?? "" }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+  relHref(fromHref: string, toHref: string): string {
+    const fromParts = fromHref.split("/");
+    const toParts = toHref.split("/");
+
+    // Remove the filename from fromHref to get the directory
+    fromParts.pop();
+
+    // Find the common prefix length
+    // Note: toParts.length - 1 excludes the filename segment, comparing only directories
+    let commonLen = 0;
+    for (let i = 0; i < Math.min(fromParts.length, toParts.length - 1); i++) {
+      if (fromParts[i] === toParts[i]) {
+        commonLen++;
+      } else {
+        break;
+      }
+    }
+
+    // Calculate levels to go up
+    const up = fromParts.length - commonLen;
+
+    // Get the remaining path from the common ancestor
+    const remaining = toParts.slice(commonLen).join("/");
+
+    // Construct the relative path
+    return up > 0 ? "../".repeat(up) + remaining : remaining;
+  }
+}

package/src/load.ts

@@ -0,0 +1,47 @@
+import { mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { MetaDataLoader, composeRegistry, coreTypesProvider, dbProvider, docProvider, promptProvider, uiProvider } from "@metaobjectsdev/metadata";
+import type { MetaData, MetaRoot } from "@metaobjectsdev/metadata";
+
+export interface LoadedModel {
+  root: MetaRoot;
+  warnings: string[];
+  sourceDirs: string[];
+}
+
+/** Load N metadata source dirs into ONE root via a staging dir of symlinks. */
+export async function loadModel(sourceDirs: string[]): Promise<LoadedModel> {
+  const staging = mkdtempSync(join(tmpdir(), "metadocs-"));
+  try {
+    const usedBasenames = new Set<string>();
+    for (const dir of sourceDirs) {
+      const baseName = basename(dir);
+      if (usedBasenames.has(baseName)) {
+        throw new Error(`duplicate source dir basename: ${baseName}`);
+      }
+      usedBasenames.add(baseName);
+      symlinkSync(resolve(dir), join(staging, baseName));
+    }
+    const registry = composeRegistry([coreTypesProvider, dbProvider, docProvider, promptProvider, uiProvider]);
+    const result = await MetaDataLoader.fromDirectory(staging, { registry, strict: false });
+    if (result.errors.length > 0) {
+      throw new Error(`metadata load failed:\n${result.errors.map((e) => String(e)).join("\n")}`);
+    }
+    return {
+      root: result.root,
+      warnings: result.warnings.map((w) => w.message),
+      sourceDirs: sourceDirs.map((d) => basename(resolve(d))),
+    };
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+/** Which top-level source dir a node came from (first file path segment of its source envelope). */
+export function treeOf(node: MetaData, model: LoadedModel): string {
+  const src = node.source as { files?: string[] };
+  const f = src.files?.[0] ?? "";
+  const seg = f.replace(/\\/g, "/").split("/")[0] ?? "";
+  return model.sourceDirs.includes(seg) ? seg : (model.sourceDirs[0] ?? "");
+}

package/src/mermaid.ts

@@ -0,0 +1,142 @@
+export interface ErEdge { parent: string; child: string; label: string; cardinality?: "one" | "many" | undefined; }
+
+// base theme is the only theme that honors custom themeVariables; the built-in `dark`
+// theme renders attribute-bearing ERDs unreadably. Surfaces match the site's dark palette.
+export const THEME_INIT =
+  `%%{init: {'theme':'base','themeVariables':{'darkMode':true,'background':'#0b1220',` +
+  `'primaryColor':'#1e2a3a','primaryTextColor':'#cbd5e1','primaryBorderColor':'#4a7fa5',` +
+  `'lineColor':'#64748b','secondaryColor':'#1a2535','tertiaryColor':'#0f1826',` +
+  `'fontSize':'13px'}}}%%\n`;
+
+const safe = (s: string) => s.replace(/"/g, "'");
+const nodeId = (s: string) => s.replace(/[^a-zA-Z0-9_]/g, "_");
+const edgeSort = (a: ErEdge, b: ErEdge) =>
+  a.parent.localeCompare(b.parent) || a.child.localeCompare(b.child) || a.label.localeCompare(b.label);
+
+export function packageFlowchart(edges: { from: string; to: string; n: number }[], counts: Map<string, number>): string {
+  const lines = [THEME_INIT + "flowchart LR"];
+  const used = new Set(edges.flatMap((e) => [e.from, e.to]));
+  for (const p of [...used].sort()) lines.push(`  ${p}["${safe(p)} · ${counts.get(p) ?? 0}"]`);
+  for (const e of [...edges].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to)))
+    lines.push(`  ${e.from} -->|${e.n}| ${e.to}`);
+  return lines.join("\n");
+}
+
+export function inheritanceTree(rows: { name: string; level: number; self?: boolean }[]): string {
+  const lines = [THEME_INIT + "flowchart TD"];
+  const ordered = [...rows].sort((a, b) => a.level - b.level || a.name.localeCompare(b.name));
+  for (const r of ordered) lines.push(`  ${nodeId(r.name)}["${safe(r.name)}"]${r.self ? ":::self" : ""}`);
+  // connect each node to the alphabetically-first node one level below it whose ancestor it is:
+  // for a simple chain+children, link consecutive levels deterministically.
+  const byLevel = new Map<number, string[]>();
+  for (const r of ordered) (byLevel.get(r.level) ?? byLevel.set(r.level, []).get(r.level)!).push(nodeId(r.name));
+  const levels = [...byLevel.keys()].sort((a, b) => a - b);
+  for (let i = 1; i < levels.length; i++) {
+    const parents = byLevel.get(levels[i - 1]!)!;
+    const parent = parents[parents.length - 1]; // the chain node at the shallower level
+    for (const child of byLevel.get(levels[i]!)!.sort()) lines.push(`  ${parent} --> ${child}`);
+  }
+  lines.push("  classDef self fill:#1e3a5f,stroke:#60a5fa,color:#e2e8f0,font-weight:bold");
+  return lines.join("\n");
+}
+
+// ---- v2 diagram system: domain palette + rich/simple emitters ----
+export const RICH_MAX = 8;
+const ROLE_STROKE: Record<string, string> = { focal: "#60a5fa", view: "#2dd4bf", external: "#334155", normal: "#3b5170" };
+// Deterministic domain palette — a fixed set of dark-surface color slots. Every
+// package's leaf name hashes into a slot, so the same package always renders the
+// same color, with no hardcoded domain→color vocabulary baked in.
+const PALETTE: { fill: string; stroke: string; text: string }[] = [
+  { fill: "#1e3a5f", stroke: "#60a5fa", text: "#93c5fd" },
+  { fill: "#3b2f1e", stroke: "#fbbf24", text: "#fde68a" },
+  { fill: "#3f2d5c", stroke: "#a78bfa", text: "#ede9fe" },
+  { fill: "#3f1f2e", stroke: "#fb7185", text: "#fecdd3" },
+  { fill: "#14342b", stroke: "#34d399", text: "#a7f3d0" },
+  { fill: "#1f2937", stroke: "#94a3b8", text: "#e2e8f0" },
+  { fill: "#2a2440", stroke: "#818cf8", text: "#e0e7ff" },
+  { fill: "#1a2e35", stroke: "#22d3ee", text: "#cffafe" },
+  { fill: "#332018", stroke: "#fb923c", text: "#fed7aa" },
+  { fill: "#1c2431", stroke: "#64748b", text: "#cbd5e1" },
+];
+export function domainColor(pkg: string): { fill: string; stroke: string; text: string } {
+  const leaf = pkg.split("::").pop() ?? pkg;
+  // stable slot: hash the leaf name deterministically into the palette
+  let h = 0; for (let i = 0; i < leaf.length; i++) h = (h * 31 + leaf.charCodeAt(i)) >>> 0;
+  return PALETTE[h % PALETTE.length]!;
+}
+const cls = (pkg: string) => `d_${(pkg.split("::").pop() ?? pkg).replace(/[^a-zA-Z0-9]/g, "_")}`;
+
+export interface ErAttr { type: string; name: string; key: "PK" | "FK" | "UK" | ""; note: string; }
+export interface ErNode { name: string; pkg: string; role: "focal" | "view" | "external" | "normal"; kind?: string; attrs: ErAttr[]; more: number; }
+// erDiagram can't vary box shape, so KIND is encoded as a border dash + a glyph prefix in the box title.
+const KIND_DASH: Record<string, string> = { value: ",stroke-dasharray:5 3", projection: ",stroke-dasharray:2 2" };
+const KIND_GLYPH: Record<string, string> = { entity: "▭", value: "⬭", projection: "▱" };
+const kindGlyph = (kind?: string) => KIND_GLYPH[kind ?? ""] ?? "▭";
+
+export function erDiagramRich(nodes: ErNode[], edges: ErEdge[]): string {
+  const lines = [THEME_INIT + "erDiagram"];
+  for (const n of [...nodes].sort((a, b) => a.name.localeCompare(b.name))) {
+    lines.push(`  ${nodeId(n.name)}["${kindGlyph(n.kind)} ${safe(n.name)}"] {`);
+    for (const a of n.attrs) {
+      const keyPart = a.key ? ` ${a.key}` : "";
+      lines.push(`    ${a.type} ${a.name}${keyPart} "${safe(a.note)}"`);
+    }
+    if (n.more > 0) lines.push(`    _ plus "+${n.more} more"`);
+    lines.push("  }");
+  }
+  for (const e of [...edges].sort(edgeSort)) {
+    const conn = e.cardinality === "many" ? "}o--o{" : "||--o{";
+    lines.push(`  ${nodeId(e.parent)} ${conn} ${nodeId(e.child)} : "${safe(e.label)}"`);
+  }
+  // one classDef per entity: fill = domain, stroke = role
+  for (const n of [...nodes].sort((a, b) => a.name.localeCompare(b.name))) {
+    const dc = domainColor(n.pkg);
+    lines.push(`  ${nodeId(n.name)}:::c_${nodeId(n.name)}`);
+    lines.push(`  classDef c_${nodeId(n.name)} fill:${dc.fill},stroke:${ROLE_STROKE[n.role]},color:#cbd5e1${KIND_DASH[n.kind ?? ""] ?? ""}`);
+  }
+  return lines.join("\n");
+}
+
+// node shape encodes object KIND: entity = rectangle, value object = stadium (rounded ends),
+// projection/view = parallelogram. Domain is the fill color; kind is the silhouette.
+function shapeDecl(id: string, label: string, kind?: string): string {
+  const l = `"${label}"`;
+  if (kind === "value") return `${id}([${l}])`;
+  if (kind === "projection") return `${id}[/${l}/]`;
+  return `${id}[${l}]`; // entity / default
+}
+
+export function flowchartDomain(
+  nodes: { name: string; pkg: string; kind?: string }[],
+  edges: { from: string; to: string; label?: string; style?: "dashed" | undefined }[],
+): { mermaid: string; legend: { pkg: string; fill: string; stroke: string }[] } {
+  const lines = [THEME_INIT + "flowchart LR"];
+  const kindByName = new Map(nodes.map((n) => [n.name, n.kind]));
+  // collect all node names (from node list + edge endpoints), deduplicate, declare with explicit labels
+  const allNodeNames = new Set<string>([
+    ...nodes.map((n) => n.name),
+    ...edges.flatMap((e) => [e.from, e.to]),
+  ]);
+  for (const name of [...allNodeNames].sort()) lines.push(`  ${shapeDecl(nodeId(name), safe(name), kindByName.get(name))}`);
+  // edge labels must not contain flowchart-breaking chars (parens, pipes, brackets, braces)
+  const edgeLabel = (s: string) => s.replace(/["|(){}\[\]]/g, "").replace(/\s+/g, " ").trim();
+  for (const e of [...edges].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to))) {
+    const lbl = e.label ? edgeLabel(e.label) : "";
+    const arrow = e.style === "dashed" ? "-.->" : "-->";
+    lines.push(lbl ? `  ${nodeId(e.from)} ${arrow}|${lbl}| ${nodeId(e.to)}` : `  ${nodeId(e.from)} ${arrow} ${nodeId(e.to)}`);
+  }
+  // group node names by domain class, assign, and emit one classDef per used domain
+  const byCls = new Map<string, { pkg: string; ids: string[] }>();
+  for (const n of [...nodes].sort((a, b) => a.name.localeCompare(b.name))) {
+    const c = cls(n.pkg);
+    (byCls.get(c) ?? byCls.set(c, { pkg: n.pkg, ids: [] }).get(c)!).ids.push(nodeId(n.name));
+  }
+  for (const [c, g] of [...byCls.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const dc = domainColor(g.pkg);
+    lines.push(`  class ${g.ids.sort().join(",")} ${c}`);
+    lines.push(`  classDef ${c} fill:${dc.fill},stroke:${dc.stroke},color:${dc.text}`);
+  }
+  const legend = [...new Map(nodes.map((n) => [n.pkg, n.pkg])).keys()].sort()
+    .map((pkg) => ({ pkg, fill: domainColor(pkg).fill, stroke: domainColor(pkg).stroke }));
+  return { mermaid: lines.join("\n"), legend };
+}

package/src/mustache-highlight.ts

@@ -0,0 +1,43 @@
+export interface HighlightResult { html: string; toc: { name: string; anchor: string }[]; refs: string[]; }
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+export function highlightMustache(src: string, resolveHref: (p: string) => string | undefined): HighlightResult {
+  let out = "";
+  const toc: { name: string; anchor: string }[] = [];
+  const refs: string[] = [];
+  let depth = 0;
+  let i = 0;
+  while (i < src.length) {
+    const open = src.indexOf("{{", i);
+    if (open === -1) { out += esc(src.slice(i)); break; }
+    out += esc(src.slice(i, open));
+    const triple = src.startsWith("{{{", open);
+    const close = src.indexOf(triple ? "}}}" : "}}", open);
+    if (close === -1) { out += esc(src.slice(open)); break; }
+    const end = close + (triple ? 3 : 2);
+    const rawTok = src.slice(open, end);
+    const inner = src.slice(open + (triple ? 3 : 2), close).trim();
+    const sigil = triple ? "{" : inner[0] ?? "";
+    const name = triple ? inner : inner.replace(/^[#^\/>!&]\s*/, "");
+    const span = (cls: string, extra = "") => `<span class="${cls}"${extra}>${esc(rawTok)}</span>`;
+    if (!triple && sigil === "!") out += span("mu-com");
+    else if (!triple && sigil === ">") out += span("mu-par");
+    else if (!triple && (sigil === "#" || sigil === "^")) {
+      refs.push(name);
+      const href = resolveHref(name);
+      if (depth === 0 && sigil === "#") { toc.push({ name, anchor: `sec-${name}` }); }
+      const idAttr = depth === 0 && sigil === "#" ? ` id="sec-${esc(name)}"` : "";
+      out += href ? `<a href="${esc(href)}" class="mu-sec"${idAttr}>${esc(rawTok)}</a>` : span("mu-sec mu-unresolved", idAttr);
+      depth++;
+    } else if (!triple && sigil === "/") { depth = Math.max(0, depth - 1); out += span("mu-sec"); }
+    else {
+      refs.push(name);
+      const cls = triple || sigil === "&" ? "mu-raw" : "mu-var";
+      const href = resolveHref(name);
+      out += href ? `<a href="${esc(href)}" class="${cls}">${esc(rawTok)}</a>` : span(`${cls} mu-unresolved`);
+    }
+    i = end;
+  }
+  return { html: out, toc, refs };
+}

package/src/package-docs.ts

@@ -0,0 +1,33 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { LinkGraph, fqnOf } from "./link-graph";
+
+export interface PackageDoc { title: string; description: string; }
+
+export function harvestPackageDocs(sourceDirs: string[]): Map<string, PackageDoc> {
+  const out = new Map<string, PackageDoc>();
+  const walk = (d: string) => {
+    for (const e of readdirSync(d)) {
+      const p = join(d, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (e === "_package.yaml") {
+        try {
+          const y = parse(readFileSync(p, "utf8")) as { metadata?: { package?: string; title?: string; description?: string } };
+          const m = y?.metadata;
+          if (m?.package) out.set(m.package, { title: String(m.title ?? ""), description: String(m.description ?? "") });
+        } catch { /* malformed _package.yaml is skipped; coverage/anomalies surface it elsewhere */ }
+      }
+    }
+  };
+  for (const d of sourceDirs) walk(d);
+  return out;
+}
+
+export function keyEntities(pkg: string, g: LinkGraph, n = 4): { name: string; href: string; inbound: number }[] {
+  return g.nodes()
+    .filter((dn) => dn.kind === "object" && dn.pkg === pkg && !dn.node.isAbstract)
+    .map((dn) => ({ name: dn.name, href: dn.href, inbound: g.refsTo(fqnOf(dn.node)).filter((r) => r.kind !== "extends").length }))
+    .sort((a, b) => b.inbound - a.inbound || a.name.localeCompare(b.name))
+    .slice(0, n);
+}

package/src/scaffold.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The 9 mustache templates the site is built from (basenames under templates/). */
+export const SITE_TEMPLATE_NAMES: readonly string[] = [
+  "chrome-head.mustache",
+  "chrome-foot.mustache",
+  "index.html.mustache",
+  "package.html.mustache",
+  "object.html.mustache",
+  "prompt.html.mustache",
+  "output.html.mustache",
+  "enums.html.mustache",
+  "coverage.html.mustache",
+];
+
+/** The site's themeable assets (basenames under assets/). search-index.json is generated, not themed. */
+export const SITE_ASSET_NAMES: readonly string[] = ["site.css", "site.js"];
+
+/** Read a bundled template or asset by basename (for scaffolding into a consumer). */
+export function readSiteFile(kind: "template" | "asset", name: string): string {
+  const selfDir = dirname(fileURLToPath(import.meta.url));
+  const dir = resolve(selfDir, kind === "template" ? "../templates" : "../assets");
+  return readFileSync(join(dir, name), "utf8");
+}