@mat3ra/esse 2026.9.5-0 → 2026.9.6-0

package/dist/js/scripts/buildDocsPages.js

@@ -139,7 +139,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
@@ -245,13 +245,15 @@ 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">
@@ -308,15 +310,16 @@ 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; } }
+#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; align-items: flex-start; }
 #docs-nav {
     width: 250px;

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-0",
     "description": "Mat3ra's Excellent Source of Schemas and Examples (ESSE) for Digital Materials R&D",
     "scripts": {
         "transpile": "tsc -p tsconfig-transpile.json",