@mat3ra/esse 2026.8.31-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/buildEntityGraph.d.ts

@@ -7,6 +7,17 @@ export interface EntityGraphNodeManifest {
     isMonitor?: boolean;
     defaultUnits?: string;
 }
+/**
+ * Navigation facets derived at build time. Keys are sorted; a value is the slug as the
+ * corpus spells it — the enum a CateCom vocabulary schema narrows, or a path segment for
+ * M-CODE and the catalogues. A narrowing to several values is joined with "|" in enum
+ * order, because such a schema is the branch rather than a point on the ladder.
+ *
+ * Present on every `category` and `directory` node, absent on every other layer.
+ */
+export type EntityGraphFacets = Record<string, string>;
+/** The five coordinate fields of `core/reusable/categories`, in ladder order. */
+export declare const CATECOM_FIELDS: readonly ["tier1", "tier2", "tier3", "type", "subtype"];
 export interface EntityGraphNode {
     /** Schema `$id`, dash-separated, e.g. "in-memory-entity/named-defaultable". */
     id: string;
@@ -31,6 +42,8 @@ export interface EntityGraphNode {
     propertyCount: number;
     hasExample: boolean;
     manifest?: EntityGraphNodeManifest;
+    /** Navigation facets — see EntityGraphFacets. Category and directory nodes only. */
+    facets?: EntityGraphFacets;
     /** Map coordinates, baked at build time so the client renders without laying out. */
     x?: number;
     y?: number;
@@ -110,6 +123,29 @@ interface RawReference {
  * under `properties.data.oneOf` is recorded as a variant *of `data`*.
  */
 export declare function collectReferences(schema: JSONSchema): RawReference[];
+interface LoadedSchema {
+    sourcePath: string;
+    relativePath: string;
+    schema: JSONSchema;
+}
+interface FacetContext {
+    nodes: Map<string, EntityGraphNode>;
+    schemaById: Map<string, LoadedSchema>;
+    schemasBySourcePath: Map<string, LoadedSchema>;
+    /** `extends` targets per source id, sorted, so the upward walk is deterministic. */
+    extendsTargets: Map<string, string[]>;
+    /** Target of the `categories` property edge, per directory node id. */
+    categoriesTarget: Map<string, string>;
+    coordinateMemo: Map<string, EntityGraphFacets>;
+}
+/**
+ * Facets for one node, or undefined when no rule covers it.
+ *
+ * Category nodes carry their scheme's coordinate (CateCom's ladder or M-CODE's axes);
+ * directory nodes carry the catalogue they belong to, that catalogue's own axis, and — when
+ * the entry declares a `categories` property — the coordinate it is filed at.
+ */
+export declare function deriveFacets(node: EntityGraphNode, context: FacetContext): EntityGraphFacets | undefined;
 export interface BuildEntityGraphResult {
     graph: EntityGraph;
     lint: EntityGraphLintResult;

package/dist/js/scripts/buildEntityGraph.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_NODE_BASELINE = void 0;
+exports.ISOLATED_NODE_BASELINE = exports.CATECOM_FIELDS = void 0;
 exports.schemaIdToPublishedPath = schemaIdToPublishedPath;
 exports.publishedPathToSchemaId = publishedPathToSchemaId;
 exports.buildPublishedPathIndex = buildPublishedPathIndex;
@@ -11,6 +11,7 @@ exports.sourcePathToSchemaId = sourcePathToSchemaId;
 exports.classifyLayer = classifyLayer;
 exports.resolveJsonPointer = resolveJsonPointer;
 exports.collectReferences = collectReferences;
+exports.deriveFacets = deriveFacets;
 exports.buildEntityGraph = buildEntityGraph;
 exports.validateEntityGraph = validateEntityGraph;
 exports.writeEntityGraph = writeEntityGraph;
@@ -34,6 +35,8 @@ const ajv_1 = require("../utils/ajv");
 const filesystem_1 = require("../utils/filesystem");
 const entity_graph_schema_json_1 = __importDefault(require("./entity_graph.schema.json"));
 const entityGraphLayout_1 = require("./entityGraphLayout");
+/** The five coordinate fields of `core/reusable/categories`, in ladder order. */
+exports.CATECOM_FIELDS = ["tier1", "tier2", "tier3", "type", "subtype"];
 /**
  * Isolated schemas at the time the lint baseline was taken; growth is reported, not failed.
  * These are leaf definitions and externally-consumed formats that nothing else references.
@@ -210,6 +213,164 @@ function readPropertiesManifest() {
         return {};
     return ((_a = js_yaml_1.default.load(fs_1.default.readFileSync(settings_1.PROPERTIES_MANIFEST_PATH, "utf-8"))) !== null && _a !== void 0 ? _a : {});
 }
+// ── Facets ────────────────────────────────────────────────────────────────────
+const ENUM_HOLDER = /^(enum_options|enum|enums)$/;
+const DIMENSIONALITY = /^(zero|one|two|three)-dimensional$/;
+const OPERATIONS_PREFIX = "materials-category-components/operations/";
+const VALUE_SHAPES = ["scalar", "non-scalar", "structural", "elemental", "workflow"];
+const METHOD_BRANCHES = ["mathematical", "physical"];
+/** Source path segments below `schema/`, so `non-scalar` keeps the dash its `$id` loses. */
+function sourceSegments(node) {
+    return node.path
+        .replace(/^schema\//, "")
+        .replace(/\.json$/, "")
+        .split("/");
+}
+function sortedFacets(facets) {
+    return Object.fromEntries(Object.entries(facets).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * Which of the five CateCom fields this vocabulary schema narrows, each resolved to its enum.
+ *
+ * The enum is the coordinate, not the path segment: `fapprx/basisexp.json` narrows `tier2`
+ * to `basisExp`, and for methods the first segment (`mathematical`, `physical`) is not a tier
+ * at all — so counting path depth gets the ladder wrong.
+ */
+function ownNarrowings(id, context) {
+    var _a;
+    const loaded = context.schemaById.get(id);
+    if (!loaded)
+        return {};
+    const properties = ((_a = loaded.schema.properties) !== null && _a !== void 0 ? _a : {});
+    const narrowed = {};
+    exports.CATECOM_FIELDS.forEach((field) => {
+        var _a;
+        const property = properties[field];
+        if (!property)
+            return;
+        let values = Array.isArray(property.enum) ? property.enum : undefined;
+        if (!values && typeof property.$ref === "string") {
+            const [filePart, pointerPart] = property.$ref.split("#");
+            const target = (_a = context.schemasBySourcePath.get(path_1.default.resolve(path_1.default.dirname(loaded.sourcePath), filePart))) === null || _a === void 0 ? void 0 : _a.schema;
+            const fragment = resolveJsonPointer(target, `/${(pointerPart !== null && pointerPart !== void 0 ? pointerPart : "").replace(/^\//, "")}`);
+            values = fragment === null || fragment === void 0 ? void 0 : fragment.enum;
+        }
+        if (Array.isArray(values) && values.length > 0) {
+            narrowed[field] = values.map(String).join("|");
+        }
+    });
+    return narrowed;
+}
+/** Ancestors' narrowings (walking `extends` within the category layer), then this node's; own wins. */
+function catecomCoordinate(id, context) {
+    var _a;
+    const memoised = context.coordinateMemo.get(id);
+    if (memoised)
+        return memoised;
+    context.coordinateMemo.set(id, {});
+    const coordinate = {};
+    ((_a = context.extendsTargets.get(id)) !== null && _a !== void 0 ? _a : [])
+        .filter((parent) => { var _a; return ((_a = context.nodes.get(parent)) === null || _a === void 0 ? void 0 : _a.layer) === "category"; })
+        .forEach((parent) => Object.assign(coordinate, catecomCoordinate(parent, context)));
+    Object.assign(coordinate, ownNarrowings(id, context));
+    context.coordinateMemo.set(id, coordinate);
+    return coordinate;
+}
+/** Last segment of the first operation reached walking `extends` upward. */
+function mcodeOperation(id, context, seen = new Set()) {
+    var _a;
+    if (seen.has(id))
+        return undefined;
+    seen.add(id);
+    const parents = (_a = context.extendsTargets.get(id)) !== null && _a !== void 0 ? _a : [];
+    const direct = parents.find((parent) => parent.startsWith(OPERATIONS_PREFIX));
+    if (direct)
+        return direct.split("/").pop();
+    return parents.map((parent) => mcodeOperation(parent, context, seen)).find(Boolean);
+}
+/**
+ * Facets for one node, or undefined when no rule covers it.
+ *
+ * Category nodes carry their scheme's coordinate (CateCom's ladder or M-CODE's axes);
+ * directory nodes carry the catalogue they belong to, that catalogue's own axis, and — when
+ * the entry declares a `categories` property — the coordinate it is filed at.
+ */
+function deriveFacets(node, context) {
+    if (node.layer !== "category" && node.layer !== "directory")
+        return undefined;
+    const segments = sourceSegments(node);
+    const [, second, third, fourth] = segments;
+    const holder = ENUM_HOLDER.test(segments[segments.length - 1]);
+    const facets = {};
+    if (node.layer === "category") {
+        if (node.domain === "models_category" || node.domain === "methods_category") {
+            facets.scheme = "catecom";
+            if (node.domain === "methods_category")
+                facets.branch = second;
+            if (holder) {
+                facets.role = "enum-options";
+            }
+            else {
+                facets.role = "vocabulary";
+                Object.assign(facets, catecomCoordinate(node.id, context));
+            }
+        }
+        else if (node.domain === "materials_category") {
+            facets.scheme = "mcode";
+            facets.role = "recipe";
+            facets.structuralClass = second.replace(/_structures$/, "").replace(/_/g, "-");
+            facets.dimensionality = third;
+            const operation = mcodeOperation(node.id, context);
+            if (operation)
+                facets.operation = operation;
+        }
+        else if (node.domain === "materials_category_components" && second === "entities") {
+            facets.scheme = "mcode";
+            facets.role = "entity";
+            facets.entityRole = third;
+            // Dimensionality sits one segment deeper here than under materials_category.
+            facets.dimensionality = fourth;
+        }
+        else if (node.domain === "materials_category_components" && second === "operations") {
+            facets.scheme = "mcode";
+            facets.role = holder ? "enum-options" : "operation";
+            facets.operationKind = fourth;
+        }
+        else {
+            return undefined;
+        }
+        return sortedFacets(facets);
+    }
+    facets.catalogue = node.domain.replace(/_directory$/, "").replace(/_/g, "-");
+    if (holder) {
+        facets.role = "enum-options";
+        return sortedFacets(facets);
+    }
+    if (second === "legacy")
+        facets.legacy = "true";
+    if (node.domain === "properties_directory" && VALUE_SHAPES.includes(second)) {
+        facets.valueShape = second;
+    }
+    if (node.domain === "software_directory")
+        facets.softwareKind = second;
+    if (node.domain === "methods_directory" && METHOD_BRANCHES.includes(second)) {
+        facets.branch = second;
+    }
+    if (node.domain === "context_providers_directory") {
+        facets.scope = second === "by_application" ? "by-application" : "generic";
+        if (second === "by_application")
+            [facets.application] = third.split("_");
+    }
+    const coordinate = context.categoriesTarget.get(node.id);
+    if (coordinate) {
+        const inherited = catecomCoordinate(coordinate, context);
+        exports.CATECOM_FIELDS.forEach((field) => {
+            if (inherited[field])
+                facets[field] = inherited[field];
+        });
+    }
+    return sortedFacets(facets);
+}
 function buildEntityGraph() {
     const failures = [];
     const warnings = [];
@@ -350,6 +511,50 @@ function buildEntityGraph() {
             ...(((_a = entry.defaults) === null || _a === void 0 ? void 0 : _a.units) ? { defaultUnits: String(entry.defaults.units) } : {}),
         };
     });
+    // L11 — facets are total on the category and directory layers, and well formed.
+    // Assigned after the edges exist (the CateCom walk and the `categories` join both need
+    // them) and before layout, so node key order stays deterministic.
+    const extendsTargets = new Map();
+    const categoriesTarget = new Map();
+    edges.forEach((edge) => {
+        var _a, _b;
+        if (edge.kind === "extends") {
+            if (!extendsTargets.has(edge.source))
+                extendsTargets.set(edge.source, []);
+            extendsTargets.get(edge.source).push(edge.target);
+        }
+        if (edge.kind === "contains" && edge.label === "categories") {
+            if (((_a = nodes.get(edge.source)) === null || _a === void 0 ? void 0 : _a.layer) === "directory" &&
+                ((_b = nodes.get(edge.target)) === null || _b === void 0 ? void 0 : _b.layer) === "category") {
+                categoriesTarget.set(edge.source, edge.target);
+            }
+        }
+    });
+    extendsTargets.forEach((targets) => targets.sort());
+    const facetContext = {
+        nodes,
+        schemaById: new Map(loadedSchemas
+            .map((item) => [nodeIdBySourcePath.get(item.sourcePath), item])
+            .filter(([id]) => Boolean(id))),
+        schemasBySourcePath,
+        extendsTargets,
+        categoriesTarget,
+        coordinateMemo: new Map(),
+    };
+    [...nodes.keys()].sort().forEach((id) => {
+        const node = nodes.get(id);
+        if (node.layer !== "category" && node.layer !== "directory")
+            return;
+        const facets = deriveFacets(node, facetContext);
+        if (!facets || Object.keys(facets).length === 0) {
+            failures.push(`L11 ${node.path}: no facet rule covers this ${node.layer} path — add one to deriveFacets`);
+            return;
+        }
+        if (facets.dimensionality && !DIMENSIONALITY.test(facets.dimensionality)) {
+            failures.push(`L11 ${node.path}: dimensionality "${facets.dimensionality}" is not <zero|one|two|three>-dimensional`);
+        }
+        node.facets = facets;
+    });
     const sortedNodes = (0, entityGraphLayout_1.computeEntityGraphLayout)([...nodes.values()].sort((a, b) => a.id.localeCompare(b.id)));
     const sortedEdges = edges.sort((a, b) => {
         var _a, _b, _c, _d;

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/dist/js/scripts/entity_graph.schema.json

@@ -154,6 +154,13 @@
                         "required": [
                             "name"
                         ]
+                    },
+                    "facets": {
+                        "description": "Navigation facets derived at build time: the CateCom coordinate a vocabulary schema narrows to, the M-CODE axes carried in a materials path, or the catalogue and axis a directory entry belongs to. Present on every category and directory node.",
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
                     }
                 },
                 "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/esse",
-    "version": "2026.8.31-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",
@@ -8,6 +8,7 @@
         "build-entity-graph": "ts-node build_entity_graph.ts --output ./site",
         "lint-entity-graph": "ts-node build_entity_graph.ts",
         "build-docs-pages": "ts-node build_docs_pages.ts",
+        "build-site": "npm run transpile-and-build-assets && ts-node build_site.ts && npm run check-site-links -- --site site",
         "check-site-links": "ts-node check_site_links.ts",
         "compile-types": "ts-node compile_ts.ts",
         "transpile-and-build-assets": "npm run set-schema-ids && npm run build-schemas && npm run compile-types && npm run transpile",