@mat3ra/esse 2026.9.5-0 → 2026.9.6-1

package/dist/js/scripts/buildDocsPages.d.ts

@@ -15,5 +15,22 @@ export declare function parseFrontMatter(source: string): {
     body: string;
 };
 export declare function expandFragments(body: string, graph: EntityGraph): string;
+/** A heading the in-page table of contents can link to. */
+export interface DocsHeading {
+    id: string;
+    text: string;
+    level: number;
+}
+/**
+ * Gives every `h2`/`h3` an id and returns them in document order.
+ *
+ * `marked` emits bare heading tags, so without this there is nothing for a table of
+ * contents — or an external deep link — to point at. Ids are de-duplicated because two
+ * sections may legitimately share a title.
+ */
+export declare function extractHeadings(html: string): {
+    html: string;
+    headings: DocsHeading[];
+};
 export declare function buildDocsPages(outputDir: string): DocsPage[];
 export {};

package/dist/js/scripts/buildDocsPages.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseFrontMatter = parseFrontMatter;
 exports.expandFragments = expandFragments;
+exports.extractHeadings = extractHeadings;
 exports.buildDocsPages = buildDocsPages;
 /**
  * Renders the concept documentation in `docs/` to static HTML for the site.
@@ -139,7 +140,7 @@ function categorizationSchemesFragment(graph) {
         const rest = graph.nodes.filter((node) => node.id.startsWith(prefix) && !reachesCategories(node.id));
         const tiered = total - rest.length;
         if (!tiered)
-            return [`\`${domain}\``, String(total), "none — compositional"];
+            return [`\`${domain}\``, String(total), "M-CODE — compositional"];
         // Today the untiered remainder is entirely enum holders; say so only while true.
         const allEnums = rest.every((node) => /\/enum-options$|\/enums$/.test(node.id));
         const remainder = rest.length
@@ -229,7 +230,65 @@ function expandFragments(body, graph) {
 function escapeHtml(value) {
     return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function renderPage(page, pages, html) {
+function slugifyHeading(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Gives every `h2`/`h3` an id and returns them in document order.
+ *
+ * `marked` emits bare heading tags, so without this there is nothing for a table of
+ * contents — or an external deep link — to point at. Ids are de-duplicated because two
+ * sections may legitimately share a title.
+ */
+function extractHeadings(html) {
+    const headings = [];
+    const seen = new Map();
+    const withIds = html.replace(/<h([23])>([\s\S]*?)<\/h\1>/g, (_match, level, inner) => {
+        var _a;
+        const text = inner.replace(/<[^>]+>/g, "").trim();
+        const base = slugifyHeading(text) || `section-${headings.length + 1}`;
+        const count = (_a = seen.get(base)) !== null && _a !== void 0 ? _a : 0;
+        seen.set(base, count + 1);
+        const id = count === 0 ? base : `${base}-${count}`;
+        headings.push({ id, text, level: Number(level) });
+        return `<h${level} id="${id}">${inner}</h${level}>`;
+    });
+    return { html: withIds, headings };
+}
+function renderTableOfContents(headings) {
+    // One heading is the page title's own section; a list of one is noise.
+    if (headings.length < 2)
+        return "";
+    const items = headings
+        .map((heading) => `<a href="#${heading.id}" class="toc-h${heading.level}">` +
+        `${escapeHtml(heading.text)}</a>`)
+        .join("\n            ");
+    return `<aside id="docs-toc">
+        <div class="nav-title">On this page</div>
+        <nav>
+            ${items}
+        </nav>
+    </aside>`;
+}
+/** Sequential links, so the pages can be read in the order they are written in. */
+function renderPageNav(page, pages) {
+    const index = pages.findIndex((item) => item.slug === page.slug);
+    const previous = index > 0 ? pages[index - 1] : undefined;
+    const next = index < pages.length - 1 ? pages[index + 1] : undefined;
+    const link = (target, direction, label) => target
+        ? `<a class="page-nav-${direction}" href="${target.slug}.html">` +
+            `<span class="page-nav-label">${label}</span>` +
+            `<span class="page-nav-title">${escapeHtml(target.title)}</span></a>`
+        : `<span class="page-nav-${direction}"></span>`;
+    return `<nav class="page-nav">
+        ${link(previous, "prev", "Previous")}
+        ${link(next, "next", "Next")}
+    </nav>`;
+}
+function renderPage(page, pages, html, headings) {
     const nav = pages
         .map((item) => `<a href="${item.slug}.html"${item.slug === page.slug ? ' class="current"' : ""}>` +
         `${escapeHtml(item.title)}</a>`)
@@ -245,26 +304,36 @@ function renderPage(page, pages, html) {
 </head>
 <body>
 <div id="titlebar">
-    <span class="app-name">AI4Materials<span class="app-name-suffix">: data standards</span></span>
+    <span class="app-name">AI4Materials</span>
     <nav id="surfaces">
         <a href="index.html" class="current">Docs</a>
         <a href="../index.html">Explorer</a>
+        <a href="../index.html#/categories">Categories</a>
+        <a href="../index.html#/directories">Directories</a>
         <a href="../map/index.html">Ontology</a>
     </nav>
-    <span id="titlebar-tagline">ESSE &middot; materials science ontology</span>
+    <span id="titlebar-tagline">ESSE &middot; materials science data standards and ontology</span>
 </div>
 <div id="workspace">
     <aside id="docs-nav">
-        <div class="nav-title">Concepts</div>
-        <nav>
-            ${nav}
-        </nav>
+        <div class="docs-nav-inner">
+            <div class="nav-title">Concepts</div>
+            <nav>
+                ${nav}
+            </nav>
+        </div>
     </aside>
     <main id="docs-content">
         <article>
 ${html}
     </article>
+        ${renderPageNav(page, pages)}
     </main>
+    ${renderTableOfContents(headings)}
+</div>
+<div id="statusbar">
+    <span id="status-page">${escapeHtml(page.summary || page.title)}</span>
+    <span id="status-position">Page ${pages.findIndex((item) => item.slug === page.slug) + 1} of ${pages.length}</span>
 </div>
 </body>
 </html>
@@ -281,6 +350,8 @@ const DOCS_STYLESHEET = `/* Concept documentation — shares the explorer's pale
     --text-muted: #858585;
     --border: #3e3e3e;
     --accent: #4ea1ff;
+    /* The Explorer and the Ontology map both paint their status bar in this blue. */
+    --accent-bar: #0078d4;
     --code: #9cdcfe;
 }
 * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -308,31 +379,39 @@ body {
     z-index: 5;
 }
 #titlebar .app-name { color: var(--text-primary); font-weight: 600; }
-/* Completes the wordmark so the name never reads as a dangling fragment. */
-#titlebar .app-name-suffix { color: var(--text-muted); font-weight: 400; }
-@media (max-width: 700px) { #titlebar .app-name-suffix { display: none; } }
-#surfaces { display: flex; gap: 14px; }
+/* Five items do not fit a phone: the nav shrinks and scrolls inside the bar rather than
+   being clipped or pushing the page sideways. */
+#surfaces { display: flex; gap: 14px; flex: 0 1 auto; min-width: 0; overflow-x: auto; scrollbar-width: none; }
+#surfaces::-webkit-scrollbar { display: none; }
+@media (max-width: 700px) { #surfaces { gap: 10px; } }
 #surfaces a { color: var(--text-muted); text-decoration: none; }
 #surfaces a:hover { color: var(--text-primary); }
 #surfaces a.current { color: var(--text-primary); border-bottom: 2px solid var(--accent); }
-#titlebar-tagline { margin-left: auto; color: var(--text-muted); }
-@media (max-width: 640px) { #titlebar-tagline { display: none; } }
-#workspace { display: flex; flex: 1; align-items: flex-start; }
+#titlebar-tagline { margin-left: auto; color: var(--text-muted); white-space: nowrap; }
+@media (max-width: 900px) { #titlebar-tagline { display: none; } }
+#workspace { display: flex; flex: 1; }
+/*
+ * Two boxes, two jobs. The panel (#docs-nav) stretches for the full height of the
+ * workspace, so its background and border run the length of the page instead of stopping
+ * where the link list ends. The inner box is what sticks.
+ *
+ * Sticking the panel itself does not work: an element can only stick while it is shorter
+ * than the space it sticks within, so a full-height panel has no slack to hold a position
+ * in. Sizing the panel to its own content instead (align-self: flex-start) restores the
+ * sticking but leaves the panel visibly cut off part-way down the page. Separating the
+ * two concerns gets both.
+ */
 #docs-nav {
     width: 250px;
     flex-shrink: 0;
     background: var(--bg-sidebar);
     border-right: 1px solid var(--border);
-    padding: 16px 0;
+}
+.docs-nav-inner {
     position: sticky;
     top: 34px;
-    /* Not "stretch": that makes this box exactly as tall as #docs-content (the long
-       sibling), leaving sticky no slack to hold its position in -- an element can only
-       stick while it is shorter than the room it is sticking within. flex-start sizes
-       this to its own (short) nav-list content, so it actually stays pinned. The height
-       cap is a second guard: if the nav list ever grows past the viewport, it scrolls
-       internally instead of being clipped or pushing off-screen. */
-    align-self: flex-start;
+    padding: 16px 0;
+    /* If the list ever outgrows the viewport it scrolls itself rather than being clipped. */
     max-height: calc(100vh - 34px);
     overflow-y: auto;
 }
@@ -359,7 +438,8 @@ body {
     border-left-color: var(--accent);
 }
 #docs-content { flex: 1; min-width: 0; padding: 32px 40px 80px; }
-article { max-width: 68ch; }
+/* A fixed measure, centred: on a wide screen the text should not hug the sidebar. */
+article { max-width: 68ch; margin: 0 auto; }
 article h1 { font-size: 27px; font-weight: 600; margin-bottom: 18px; text-wrap: balance; }
 article h2 {
     font-size: 19px;
@@ -410,17 +490,88 @@ article th { background: var(--bg-sidebar); font-weight: 600; }
 article td:not(:first-child) { font-variant-numeric: tabular-nums; }
 article hr { border: none; border-top: 1px solid var(--border); margin: 26px 0; }
 :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+/* In-page contents. Mirrors the concept nav opposite it, one weight lighter. */
+#docs-toc {
+    width: 220px;
+    flex-shrink: 0;
+    padding: 16px 0;
+    position: sticky;
+    top: 34px;
+    align-self: flex-start;
+    max-height: calc(100vh - 34px);
+    overflow-y: auto;
+}
+#docs-toc nav { display: flex; flex-direction: column; }
+#docs-toc a {
+    padding: 4px 16px;
+    color: var(--text-muted);
+    text-decoration: none;
+    font-size: 12px;
+    line-height: 1.4;
+    border-left: 2px solid transparent;
+}
+#docs-toc a:hover { color: var(--text-primary); border-left-color: var(--border); }
+#docs-toc a.toc-h3 { padding-left: 28px; font-size: 11.5px; }
+
+/* The pages are written as a sequence; give the reader a way to follow it. */
+.page-nav {
+    display: flex;
+    gap: 12px;
+    max-width: 68ch;
+    margin: 40px auto 0;
+    padding-top: 20px;
+    border-top: 1px solid var(--border);
+}
+.page-nav > * { flex: 1 1 0; min-width: 0; }
+.page-nav a {
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+    padding: 10px 14px;
+    border: 1px solid var(--border);
+    border-radius: 3px;
+    text-decoration: none;
+    color: var(--text-primary);
+}
+.page-nav a:hover { background: var(--bg-hover); border-color: var(--accent); }
+.page-nav-next { text-align: right; }
+.page-nav-label { font-size: 11px; color: var(--text-muted); }
+.page-nav-title { font-size: 13px; }
+
+/* Matches the Explorer's and the map's, so the three surfaces end the same way. */
+#statusbar {
+    height: 22px;
+    background: var(--accent-bar);
+    color: #fff;
+    display: flex;
+    align-items: center;
+    padding: 0 14px;
+    font-size: 12px;
+    flex-shrink: 0;
+    gap: 16px;
+    position: sticky;
+    bottom: 0;
+}
+#status-page { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* The contents column is the first thing to go when it stops earning its width. */
+@media (max-width: 1100px) { #docs-toc { display: none; } }
 @media (max-width: 760px) {
     #workspace { flex-direction: column; }
     #docs-nav {
         width: 100%;
-        position: static;
         border-right: none;
         border-bottom: 1px solid var(--border);
+    }
+    .docs-nav-inner {
+        position: static;
         max-height: none;
         overflow-y: visible;
     }
     #docs-content { padding: 20px; }
+    .page-nav { flex-direction: column; }
+    .page-nav-next { text-align: left; }
 }
 `;
 // ── Entry point ───────────────────────────────────────────────────────────────
@@ -448,11 +599,12 @@ function buildDocsPages(outputDir) {
     // should fail the build outright, not leave a half-written site behind.
     const rendered = pages.map((page) => {
         const expanded = expandFragments(page.body, graph);
-        const html = marked_1.marked.parse(expanded, { async: false })
+        const parsed = marked_1.marked.parse(expanded, { async: false })
             // Wide tables scroll inside their own container rather than the page body.
             .replace(/<table>/g, '<div class="table-wrap"><table>')
             .replace(/<\/table>/g, "</table></div>");
-        return { page, html: renderPage(page, pages, html) };
+        const { html, headings } = extractHeadings(parsed);
+        return { page, html: renderPage(page, pages, html, headings) };
     });
     const targetDir = path_1.default.join(outputDir, "docs");
     fs_1.default.mkdirSync(targetDir, { recursive: true });

package/dist/js/scripts/buildExplorerViews.d.ts

@@ -0,0 +1,28 @@
+import type { EntityGraph } from "./buildEntityGraph";
+/**
+ * One openable file in a view.
+ *
+ * `segments` is the folder chain with the leaf label last. An array rather than a joined
+ * string because leaf labels themselves contain slashes — a catalogue entry filed under a
+ * vocabulary node reads `models_directory/gga.json` — and joining would invent folders.
+ */
+export interface ExplorerViewEntry {
+    segments: string[];
+    /** Site-relative path of the file to open, e.g. "schema/models_directory/gga.json". */
+    path: string;
+}
+export interface ExplorerViews {
+    categories: ExplorerViewEntry[];
+    directories: ExplorerViewEntry[];
+}
+export declare function buildExplorerViews(graph: EntityGraph): ExplorerViews;
+/**
+ * L12 — the views stay in step with the corpus.
+ *
+ * A view that silently drops a schema is worse than no view: it tells the reader the corpus
+ * does not contain something it does contain. Every browsable schema must appear, and every
+ * row must open a file that exists.
+ */
+export declare function lintExplorerViews(graph: EntityGraph, views: ExplorerViews): string[];
+/** Writes `views.json` into the given directory, creating it when missing. */
+export declare function writeExplorerViews(views: ExplorerViews, outputDir: string): string;

package/dist/js/scripts/buildExplorerViews.js

@@ -0,0 +1,410 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExplorerViews = buildExplorerViews;
+exports.lintExplorerViews = lintExplorerViews;
+exports.writeExplorerViews = writeExplorerViews;
+/**
+ * Builds the Explorer's Categories and Directories trees from the entity graph.
+ *
+ * The Explorer browses by file path, which is the one arrangement that cannot show what the
+ * categorization layer is *for*: a CateCom tier ladder is a chain of `allOf`s, and M-CODE's
+ * three axes are three different ways through the same 17 recipes. Neither is a directory
+ * listing. These views are virtual trees over the same files — same widget, same editor, same
+ * tabs — so a coordinate becomes something you can walk.
+ *
+ * Built here rather than in the browser so the shape is testable and lint-able, and so the
+ * client stays a renderer. The output is `views.json`, written beside `graph.json`.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const MODELS_ROOT = "Models · CateCom";
+const METHODS_ROOT = "Methods · CateCom";
+const MATERIALS_ROOT = "Materials · M-CODE";
+/** Display names for the catalogues; the entry count is appended at build time. */
+const CATALOGUE_LABELS = {
+    properties: "Properties",
+    models: "Models",
+    methods: "Methods",
+    software: "Software",
+    "context-providers": "Context providers",
+};
+/** Titles are written for a schema reader; a tree row wants the noun, not the file kind. */
+function shortTitle(node) {
+    return node.title
+        .replace(/\s+(category|configuration)?\s*schema$/i, "")
+        .replace(/\s+category$/i, "")
+        .trim();
+}
+/**
+ * The published file name, not the source one. They differ: a source basename may contain a
+ * dash, which round-trips to an underscore through `$id` (`p-norm.json` is published as
+ * `p_norm.json`). Labelling a row with the source name names a file the site does not serve
+ * and that searching for the published name cannot find.
+ */
+function fileName(node) {
+    return node.publishedPath.split("/").pop();
+}
+function slugOf(node) {
+    return node.id.split("/").pop();
+}
+/**
+ * `pb · physics-based model`. The title is dropped when it adds nothing — either because it
+ * is the slug, or because it merely ends with it, which would otherwise print the slug twice
+ * (`nstruct · Unstructured meshing category nstruct`).
+ */
+function vocabularyLabel(node) {
+    const slug = slugOf(node);
+    const title = shortTitle(node)
+        .replace(new RegExp(`\\s*\\b${slug}$`, "i"), "")
+        .trim();
+    return title && title.toLowerCase() !== slug.toLowerCase() ? `${slug} · ${title}` : slug;
+}
+function examplePath(node) {
+    return node.hasExample ? node.publishedPath.replace(/^schema\//, "example/") : undefined;
+}
+function buildContext(graph) {
+    const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+    const ladderParents = new Map();
+    const filedUnder = new Map();
+    const filedEntries = new Map();
+    graph.edges.forEach((edge) => {
+        var _a, _b;
+        const source = byId.get(edge.source);
+        const target = byId.get(edge.target);
+        if (!source || !target)
+            return;
+        if (edge.kind === "extends" && source.layer === "category" && target.layer === "category") {
+            const parents = (_a = ladderParents.get(edge.source)) !== null && _a !== void 0 ? _a : [];
+            parents.push(edge.target);
+            ladderParents.set(edge.source, parents);
+        }
+        if (edge.kind === "contains" &&
+            edge.label === "categories" &&
+            source.layer === "directory" &&
+            target.layer === "category") {
+            filedUnder.set(edge.source, edge.target);
+            const entries = (_b = filedEntries.get(edge.target)) !== null && _b !== void 0 ? _b : [];
+            entries.push(edge.source);
+            filedEntries.set(edge.target, entries);
+        }
+    });
+    ladderParents.forEach((parents) => parents.sort());
+    filedEntries.forEach((entries) => entries.sort());
+    return { byId, ladderParents, filedUnder, filedEntries };
+}
+/**
+ * The chain of vocabulary schemas from the top of the ladder down to `nodeId`.
+ *
+ * This is the `allOf` chain, not the directory path: it is how the corpus itself defines the
+ * ladder, and it is right where the path is not. `methods_category/mathematical/regression`
+ * narrows a lower field than its depth suggests, so reading position off the path — or off
+ * which facet fields are present — misplaces it.
+ */
+function ladderChain(nodeId, context) {
+    var _a;
+    const chain = [];
+    const seen = new Set();
+    let current = nodeId;
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        const node = context.byId.get(current);
+        if (!node)
+            break;
+        chain.push(node);
+        [current] = (_a = context.ladderParents.get(current)) !== null && _a !== void 0 ? _a : [];
+    }
+    return chain.reverse();
+}
+function isEnumHolder(node) {
+    var _a;
+    return ((_a = node.facets) === null || _a === void 0 ? void 0 : _a.role) === "enum-options";
+}
+// ── Categories ────────────────────────────────────────────────────────────────
+function categoriesView(graph, context) {
+    const entries = [];
+    const push = (segments, node) => {
+        entries.push({ segments: [...segments, fileName(node)], path: node.publishedPath });
+        const example = examplePath(node);
+        if (example) {
+            entries.push({ segments: [...segments, `${fileName(node)} · example`], path: example });
+        }
+    };
+    graph.nodes
+        .filter((node) => { var _a; return ((_a = node.facets) === null || _a === void 0 ? void 0 : _a.role) === "vocabulary"; })
+        .forEach((node) => {
+        var _a, _b;
+        const root = node.domain === "models_category" ? MODELS_ROOT : METHODS_ROOT;
+        // The branch is the first path segment but not part of the `allOf` chain, so it
+        // has to be prepended for a methods coordinate to be complete.
+        const branch = (_a = node.facets) === null || _a === void 0 ? void 0 : _a.branch;
+        const folders = [
+            root,
+            ...(branch ? [branch] : []),
+            ...ladderChain(node.id, context).map(vocabularyLabel),
+        ];
+        push(folders, node);
+        ((_b = context.filedEntries.get(node.id)) !== null && _b !== void 0 ? _b : []).forEach((entryId) => {
+            const entry = context.byId.get(entryId);
+            if (!entry)
+                return;
+            // Named with its domain: inside `gga · DFT GGA functional` this sits beside
+            // the vocabulary schema's own `gga.json`, and the two must not read alike.
+            const label = `${entry.domain}/${fileName(entry)}`;
+            entries.push({ segments: [...folders, label], path: entry.publishedPath });
+            const example = examplePath(entry);
+            if (example) {
+                entries.push({
+                    segments: [...folders, `${label} · example`],
+                    path: example,
+                });
+            }
+        });
+    });
+    // M-CODE's axes are orthogonal, so a recipe is filed under each of them rather than
+    // once: reaching a slab by dimensionality and by structural class are both legitimate.
+    graph.nodes
+        .filter((node) => { var _a; return ((_a = node.facets) === null || _a === void 0 ? void 0 : _a.role) === "recipe"; })
+        .forEach((node) => {
+        var _a;
+        const { structuralClass, dimensionality, operation } = (_a = node.facets) !== null && _a !== void 0 ? _a : {};
+        if (structuralClass && dimensionality) {
+            push([MATERIALS_ROOT, "by structural class", structuralClass, dimensionality], node);
+            push([MATERIALS_ROOT, "by dimensionality", dimensionality, structuralClass], node);
+        }
+        if (operation)
+            push([MATERIALS_ROOT, "by operation", operation], node);
+    });
+    graph.nodes
+        .filter((node) => { var _a; return ((_a = node.facets) === null || _a === void 0 ? void 0 : _a.role) === "entity"; })
+        .forEach((node) => {
+        var _a;
+        const { entityRole, dimensionality } = (_a = node.facets) !== null && _a !== void 0 ? _a : {};
+        push([
+            MATERIALS_ROOT,
+            "components",
+            "entities",
+            ...(entityRole ? [entityRole] : []),
+            ...(dimensionality ? [dimensionality] : []),
+        ], node);
+    });
+    graph.nodes
+        .filter((node) => { var _a; return ((_a = node.facets) === null || _a === void 0 ? void 0 : _a.role) === "operation"; })
+        .forEach((node) => {
+        var _a;
+        const { operationKind } = (_a = node.facets) !== null && _a !== void 0 ? _a : {};
+        push([
+            MATERIALS_ROOT,
+            "components",
+            "operations",
+            ...(operationKind ? [operationKind] : []),
+        ], node);
+    });
+    return entries;
+}
+// ── Directories ───────────────────────────────────────────────────────────────
+/** Where a catalogue entry sits below its catalogue root. */
+function directoryGroup(node, context) {
+    var _a, _b, _c;
+    const facets = (_a = node.facets) !== null && _a !== void 0 ? _a : {};
+    if (facets.legacy === "true")
+        return ["legacy"];
+    switch (facets.catalogue) {
+        case "properties":
+            return facets.valueShape ? [facets.valueShape] : ["uncategorized"];
+        case "software":
+            return facets.softwareKind ? [facets.softwareKind] : ["uncategorized"];
+        case "context-providers":
+            return [
+                ...(facets.scope ? [facets.scope] : ["uncategorized"]),
+                ...(facets.application ? [facets.application] : []),
+            ];
+        case "models":
+        case "methods": {
+            // The coordinate, slugs only — a position on the ladder, not a label for one.
+            const target = context.filedUnder.get(node.id);
+            if (!target)
+                return ["uncategorized"];
+            const branch = (_c = (_b = context.byId.get(target)) === null || _b === void 0 ? void 0 : _b.facets) === null || _c === void 0 ? void 0 : _c.branch;
+            return [...(branch ? [branch] : []), ...ladderChain(target, context).map(slugOf)];
+        }
+        default:
+            return ["uncategorized"];
+    }
+}
+function directoriesView(graph, context) {
+    const directories = graph.nodes.filter((node) => node.layer === "directory" && !isEnumHolder(node));
+    const counts = new Map();
+    directories.forEach((node) => {
+        var _a, _b, _c;
+        const catalogue = (_b = (_a = node.facets) === null || _a === void 0 ? void 0 : _a.catalogue) !== null && _b !== void 0 ? _b : "other";
+        counts.set(catalogue, ((_c = counts.get(catalogue)) !== null && _c !== void 0 ? _c : 0) + 1);
+    });
+    const entries = [];
+    directories.forEach((node) => {
+        var _a, _b, _c, _d;
+        const catalogue = (_b = (_a = node.facets) === null || _a === void 0 ? void 0 : _a.catalogue) !== null && _b !== void 0 ? _b : "other";
+        const label = (_c = CATALOGUE_LABELS[catalogue]) !== null && _c !== void 0 ? _c : catalogue;
+        const root = `${label} (${(_d = counts.get(catalogue)) !== null && _d !== void 0 ? _d : 0})`;
+        const folders = [root, ...directoryGroup(node, context)];
+        entries.push({ segments: [...folders, fileName(node)], path: node.publishedPath });
+        const example = examplePath(node);
+        if (example) {
+            entries.push({ segments: [...folders, `${fileName(node)} · example`], path: example });
+        }
+    });
+    return entries;
+}
+/**
+ * Makes every leaf label unique within its folder.
+ *
+ * File names in this corpus are often generic: all 17 M-CODE recipes are `configuration.json`
+ * and the recipe name is the folder above them, so grouping by facet lands four indentical
+ * rows side by side. Where that happens, as much of the source path is prefixed as it takes
+ * to tell them apart — `adatom/configuration.json`, `island/configuration.json`.
+ */
+function disambiguateLeaves(entries) {
+    const groups = new Map();
+    entries.forEach((entry) => {
+        const key = entry.segments.join("\u0000");
+        const group = groups.get(key);
+        if (group)
+            group.push(entry);
+        else
+            groups.set(key, [entry]);
+    });
+    groups.forEach((group) => {
+        if (group.length < 2)
+            return;
+        const directoriesOf = (entry) => entry.path.split("/").slice(0, -1);
+        const deepest = Math.max(...group.map((entry) => directoriesOf(entry).length));
+        for (let depth = 1; depth <= deepest; depth += 1) {
+            const labelled = group.map((entry) => {
+                const leaf = entry.segments[entry.segments.length - 1];
+                const prefix = directoriesOf(entry).slice(-depth).join("/");
+                return prefix ? `${prefix}/${leaf}` : leaf;
+            });
+            if (new Set(labelled).size === group.length) {
+                group.forEach((entry, index) => {
+                    entry.segments = [...entry.segments.slice(0, -1), labelled[index]];
+                });
+                return;
+            }
+        }
+    });
+    return entries;
+}
+function compareEntries(a, b) {
+    const depth = Math.min(a.segments.length, b.segments.length);
+    for (let i = 0; i < depth; i += 1) {
+        const order = a.segments[i].localeCompare(b.segments[i]);
+        if (order !== 0)
+            return order;
+    }
+    return a.segments.length - b.segments.length || a.path.localeCompare(b.path);
+}
+function buildExplorerViews(graph) {
+    const context = buildContext(graph);
+    return {
+        categories: disambiguateLeaves(categoriesView(graph, context)).sort(compareEntries),
+        directories: disambiguateLeaves(directoriesView(graph, context)).sort(compareEntries),
+    };
+}
+/**
+ * L12 — the views stay in step with the corpus.
+ *
+ * A view that silently drops a schema is worse than no view: it tells the reader the corpus
+ * does not contain something it does contain. Every browsable schema must appear, and every
+ * row must open a file that exists.
+ */
+function lintExplorerViews(graph, views) {
+    const failures = [];
+    const files = new Set();
+    graph.nodes.forEach((node) => {
+        files.add(node.publishedPath);
+        const example = examplePath(node);
+        if (example)
+            files.add(example);
+    });
+    const check = (name, entries) => {
+        const rows = new Map();
+        entries.forEach((entry) => {
+            if (!files.has(entry.path)) {
+                failures.push(`L12 views.json ${name}: "${entry.path}" is not a published file`);
+            }
+            if (entry.segments.length < 2) {
+                failures.push(`L12 views.json ${name}: "${entry.path}" has no folder above its leaf`);
+            }
+            // The label must name the file the row opens. Checked because it is the one
+            // thing here NOT derivable from the inputs: everything else in this function
+            // rebuilds `entry.path` from the same node fields that produced it, and so
+            // holds by construction. Reading the source path instead of the published one
+            // shipped four rows labelled `p-norm.json` that open `p_norm.json`.
+            const leaf = entry.segments[entry.segments.length - 1]
+                .replace(/ · example$/, "")
+                .split("/")
+                .pop();
+            if (leaf !== entry.path.split("/").pop()) {
+                failures.push(`L12 views.json ${name}: row "${entry.segments.join(" / ")}" is labelled ` +
+                    `"${leaf}" but opens ${entry.path}`);
+            }
+            // Two rows reading the same in the same folder are indistinguishable to a
+            // reader, whichever files they point at.
+            const row = entry.segments.join(" / ");
+            const claimed = rows.get(row);
+            if (claimed && claimed !== entry.path) {
+                failures.push(`L12 views.json ${name}: "${row}" is used by both ${claimed} and ${entry.path}`);
+            }
+            rows.set(row, entry.path);
+        });
+    };
+    check("categories", views.categories);
+    check("directories", views.directories);
+    const countBy = (entries) => {
+        const counts = new Map();
+        entries.forEach((entry) => { var _a; return counts.set(entry.path, ((_a = counts.get(entry.path)) !== null && _a !== void 0 ? _a : 0) + 1); });
+        return counts;
+    };
+    // Every browsable category schema, not only the vocabulary pass: the recipe, entity and
+    // operation passes produce 145 of the 250 rows and were policed by nothing, so a schema
+    // one of them silently skipped would vanish from the tree with a green build. "At least
+    // once" rather than "exactly once" because M-CODE files a recipe under each axis it has.
+    const categoryCounts = countBy(views.categories);
+    graph.nodes
+        .filter((node) => node.layer === "category" && !isEnumHolder(node))
+        .forEach((node) => {
+        var _a, _b, _c;
+        const seen = (_a = categoryCounts.get(node.publishedPath)) !== null && _a !== void 0 ? _a : 0;
+        if (seen < 1) {
+            failures.push(`L12 views.json categories: ${node.id} (role ` +
+                `${(_c = (_b = node.facets) === null || _b === void 0 ? void 0 : _b.role) !== null && _c !== void 0 ? _c : "none"}) appears nowhere in the tree`);
+        }
+    });
+    const directoryCounts = countBy(views.directories);
+    graph.nodes
+        .filter((node) => node.layer === "directory" && !isEnumHolder(node))
+        .forEach((node) => {
+        var _a;
+        const seen = (_a = directoryCounts.get(node.publishedPath)) !== null && _a !== void 0 ? _a : 0;
+        if (seen !== 1) {
+            failures.push(`L12 views.json directories: catalogue entry ${node.id} appears ${seen} ` +
+                `time(s), expected exactly 1`);
+        }
+    });
+    const holders = graph.nodes.filter(isEnumHolder).map((node) => node.publishedPath);
+    holders.forEach((held) => {
+        if (categoryCounts.has(held) || directoryCounts.has(held)) {
+            failures.push(`L12 views.json: enum holder ${held} should not be browsable`);
+        }
+    });
+    return failures;
+}
+/** Writes `views.json` into the given directory, creating it when missing. */
+function writeExplorerViews(views, outputDir) {
+    fs_1.default.mkdirSync(outputDir, { recursive: true });
+    const outputPath = path_1.default.join(outputDir, "views.json");
+    fs_1.default.writeFileSync(outputPath, `${JSON.stringify(views, null, 4)}\n`, "utf8");
+    return outputPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/esse",
-    "version": "2026.9.5-0",
+    "version": "2026.9.6-1",
     "description": "Mat3ra's Excellent Source of Schemas and Examples (ESSE) for Digital Materials R&D",
     "scripts": {
         "transpile": "tsc -p tsconfig-transpile.json",