flexdesk 0.1.0

package/src/tiling/desktops.js

@@ -0,0 +1,133 @@
+/**
+ * desktops.js — independent tile trees per virtual desktop, persisted
+ * through the host's `state` capability under the logical key `desktops`.
+ * Where that key actually lands is the embedder's business (see the host's
+ * `resolvePath`); this module only names it.
+ *
+ * Each desktop = { id, label, tree (TileTree), windows ([]), panels }.
+ * Switching desktops swaps the active tree under the renderer.
+ */
+
+import { TileTree, makeLeaf } from './tile_tree.js';
+
+const DEFAULT_PANEL_STATE = {
+    left: true,
+    right: true,
+    bottom: true,
+};
+
+/**
+ * `seed()` yields the leaf a fresh (or emptied) desktop starts with. It comes
+ * from the taxonomy's root kind — see WindowManager, which supplies it. The
+ * WM used to hardcode `{ kind: 'home', title: 'Home' }` here, which meant an
+ * embedder with a different ontology still got an EcoAgent Home tile it had
+ * never registered, and got the content_registry placeholder instead. There is
+ * deliberately NO default: a silent 'home' fallback is the exact bug this
+ * parameter exists to remove.
+ */
+function _makeDesktop(label, seed) {
+    const tree = new TileTree();
+    tree.setRoot(makeLeaf(seed()));
+    return {
+        id: `desk-${Math.random().toString(36).slice(2, 8)}`,
+        label,
+        tree,
+        windows: [],
+        // boot default: left + right + bottom all open. Names are
+        // assigned by wm._canonicalize via PANEL_TITLES.
+        panels: { ...DEFAULT_PANEL_STATE },
+    };
+}
+
+export class DesktopManager {
+    /** @param {{seed: () => object}} opts  `seed` builds the root leaf. Required. */
+    constructor({ seed } = {}) {
+        if (typeof seed !== 'function') {
+            throw new Error('DesktopManager: a `seed` function is required (the taxonomy root leaf)');
+        }
+        this.seed = seed;
+        this.desktops = [_makeDesktop('1', seed)];
+        this.activeIdx = 0;
+    }
+
+    active() { return this.desktops[this.activeIdx]; }
+
+    switchTo(idx) {
+        if (idx < 0 || idx >= this.desktops.length) return false;
+        if (idx === this.activeIdx) return false;
+        this.activeIdx = idx;
+        return true;
+    }
+
+    ensureCount(n) {
+        while (this.desktops.length < n) {
+            this.desktops.push(_makeDesktop(String(this.desktops.length + 1), this.seed));
+        }
+    }
+
+    addDesktop(label = null) {
+        const d = _makeDesktop(label || String(this.desktops.length + 1), this.seed);
+        this.desktops.push(d);
+        return d;
+    }
+
+    serialize() {
+        return {
+            activeIdx: this.activeIdx,
+            desktops: this.desktops.map((d) => ({
+                id: d.id, label: d.label,
+                tree: d.tree.serialize(),
+                panels: { ...d.panels },
+                // windows serialized at WM level since we don't own
+                // managed-window state in this module.
+            })),
+        };
+    }
+
+    static deserialize(blob, { seed } = {}) {
+        const m = new DesktopManager({ seed });
+        if (!blob || !Array.isArray(blob.desktops) || blob.desktops.length === 0) return m;
+        m.desktops = blob.desktops.map((raw) => ({
+            id: raw.id || `desk-${Math.random().toString(36).slice(2,8)}`,
+            label: raw.label || '?',
+            tree: raw.tree ? TileTree.deserialize(raw.tree) : new TileTree(),
+            windows: [],
+            panels: { ...DEFAULT_PANEL_STATE, ...(raw.panels || {}) },
+        }));
+        // Empty tree → seed with the taxonomy root so the desktop is usable.
+        for (const d of m.desktops) {
+            if (!d.tree.rootId) d.tree.setRoot(makeLeaf(seed()));
+        }
+        m.activeIdx = Math.min(Math.max(0, blob.activeIdx | 0), m.desktops.length - 1);
+        return m;
+    }
+}
+
+/**
+ * Persistence helpers. They take a host `state` capability; a host without
+ * one is legal and they no-op. We don't fail loudly — the WM stays functional
+ * against a host that cannot persist (e.g. the standalone demo).
+ */
+
+const DESKTOPS_KEY = 'desktops';
+
+export async function loadDesktops(state) {
+    if (!state) return null;
+    try {
+        return await state.read(DESKTOPS_KEY);
+    } catch (err) {
+        console.warn('[desktops] load failed', err);
+        return null;
+    }
+}
+
+export async function saveDesktops(state, blob) {
+    if (!state) return false;
+    try {
+        await state.write(DESKTOPS_KEY, blob);
+        return true;
+    } catch (err) {
+        console.warn('[desktops] save failed', err);
+        return false;
+    }
+}

package/src/tiling/entity_sources.js

@@ -0,0 +1,179 @@
+/**
+ * entity_sources.js — the entity-source PORT.
+ *
+ * The command palette, the tile hamburger menu, and any other "find me a
+ * thing" surface need a list of every searchable entity. Where those
+ * entities come from — which endpoint returns them, what a row looks
+ * like, what to call it — is the EMBEDDER's knowledge, not the shell's.
+ *
+ * So the source list is INJECTED. The embedder describes its sources and
+ * hands them to `createEntityCatalog()` at boot. Nothing in this file
+ * names an entity type or a bridge route.
+ *
+ * ## EntitySource
+ *
+ *   navKind   The content kind used to open a row via `wm.navigate`.
+ *             The taxonomy resolves its icon + label.
+ *
+ *   list      `(api) => Promise<rawList>` — per-source fetcher. Used by
+ *             the fan-out path, and by `loadOne` when a caller wants a
+ *             subset rather than the whole catalog.
+ *
+ *   pluck?    `(raw) => Array` — extract the actual list when the
+ *             endpoint wraps it. Defaults to "raw is an array, else
+ *             raw.items if that's an array, else []".
+ *
+ *   shape     `(row) => { id, label, hint? } | null` — normalise one raw
+ *             row to the record shape every search surface consumes.
+ *             Return `null` to skip the row.
+ *
+ * ## Aggregation
+ *
+ * An embedder whose backend can answer for every source in ONE call
+ * passes `aggregate: (api) => Promise<{ [navKind]: rawList } | null>`.
+ * The catalog prefers it and fans out only for the navKinds it failed to
+ * answer for. Absent ⇒ straight fan-out. Absent capability, absent key:
+ * the shell never probes for a named endpoint of its own accord.
+ *
+ * Errors from any single source are logged and treated as "empty", so
+ * one broken endpoint can't blank the entire palette.
+ */
+
+export function createEntityCatalog({ sources, aliases = {}, aggregate = null } = {}) {
+    if (!Array.isArray(sources)) {
+        throw new TypeError('createEntityCatalog: `sources` must be an array');
+    }
+    for (const s of sources) {
+        if (!s?.navKind || typeof s.list !== 'function' || typeof s.shape !== 'function') {
+            throw new TypeError(
+                `createEntityCatalog: source '${s?.navKind ?? '?'}' needs navKind + list() + shape()`);
+        }
+    }
+    if (aggregate != null && typeof aggregate !== 'function') {
+        throw new TypeError('createEntityCatalog: `aggregate` must be a function when present');
+    }
+
+    const _sources = Object.freeze(sources.map((s) => Object.freeze({ ...s })));
+    const _byKind  = new Map(_sources.map((s) => [s.navKind, s]));
+    const _aliases = Object.freeze({ ...aliases });
+
+    const get = (navKind) => _byKind.get(navKind) || null;
+
+    /** Unwrap one source's raw payload into a row array. */
+    const _extract = (src, raw) => {
+        const list = src.pluck
+            ? src.pluck(raw)
+            : (Array.isArray(raw) ? raw
+              : Array.isArray(raw?.items) ? raw.items
+              : []);
+        return Array.isArray(list) ? list : [];
+    };
+
+    /** Shape a source's rows, dropping the ones `shape` rejects or
+     *  throws on. Shared by the palette AND the tile menu so their
+     *  semantics cannot drift apart — the menu used to re-implement
+     *  this loop by hand. */
+    const shapeRows = (navKind, rows) => {
+        const src = _byKind.get(navKind);
+        if (!src || !Array.isArray(rows)) return [];
+        const out = [];
+        for (const row of rows) {
+            let shaped;
+            try { shaped = src.shape(row); }
+            catch (err) {
+                console.warn('[entity-catalog]', navKind, 'shape failed', err, row);
+                continue;
+            }
+            if (!shaped || !shaped.id) continue;
+            out.push(shaped);
+        }
+        return out;
+    };
+
+    /** Fetch ONE source's raw rows. Used by surfaces that only care
+     *  about a subset of the catalog. */
+    const loadOne = async (navKind, api) => {
+        const src = _byKind.get(navKind);
+        if (!src || !api) return [];
+        try { return _extract(src, await src.list(api)); }
+        catch (err) {
+            console.warn('[entity-catalog]', navKind, 'fetch failed', err);
+            return [];
+        }
+    };
+
+    /** Fetch every source's raw rows, grouped by navKind.
+     *
+     *  The aggregator runs first when the embedder supplied one; the
+     *  fan-out only fires for sources it didn't answer for (it threw, it
+     *  isn't there, or it doesn't know a newly-added navKind yet).
+     *
+     *  Shape: `{ [navKind]: rawRow[] }` — every navKind is always
+     *  present (empty on failure) so consumers can destructure safely. */
+    const loadGrouped = async (api) => {
+        const out = {};
+        for (const s of _sources) out[s.navKind] = [];
+        if (!api) return out;
+
+        let bulk = null;
+        if (aggregate) {
+            try { bulk = await aggregate(api); }
+            catch (err) {
+                console.warn('[entity-catalog] aggregate failed, falling back to fan-out', err);
+            }
+            if (bulk && typeof bulk !== 'object') bulk = null;
+        }
+
+        const missing = [];
+        for (const src of _sources) {
+            const raw = bulk ? bulk[src.navKind] : undefined;
+            if (raw == null) { missing.push(src); continue; }
+            out[src.navKind] = _extract(src, raw);
+        }
+        if (missing.length === 0) return out;
+
+        await Promise.all(missing.map(async (src) => {
+            out[src.navKind] = await loadOne(src.navKind, api);
+        }));
+        return out;
+    };
+
+    /** Flat-and-shaped form for search surfaces. Builds on
+     *  `loadGrouped` so there is a single fetch path and the palette /
+     *  explorer can't drift apart in coverage. */
+    const loadAll = async (api) => {
+        const grouped = await loadGrouped(api);
+        const out = [];
+        for (const src of _sources) {
+            for (const shaped of shapeRows(src.navKind, grouped[src.navKind] || [])) {
+                out.push({ kind: src.navKind, ...shaped });
+            }
+        }
+        return out;
+    };
+
+    /** Resolve a user-typed type prefix to a list of canonical navKinds.
+     *  Accepts the embedder's aliases first, then navKinds verbatim,
+     *  then the underscore spelling of a hyphenated kind. Returns an
+     *  array of navKinds on hit, `null` otherwise. */
+    const resolveTypePrefix = (prefix) => {
+        const p = String(prefix || '').toLowerCase().trim();
+        if (!p) return null;
+        if (_aliases[p]) return _aliases[p];
+        for (const src of _sources) {
+            if (src.navKind === p) return [src.navKind];
+            if (src.navKind.replace(/-/g, '_') === p) return [src.navKind];
+        }
+        return null;
+    };
+
+    return Object.freeze({
+        sources: _sources,
+        get,
+        loadOne,
+        loadGrouped,
+        loadAll,
+        shapeRows,
+        resolveTypePrefix,
+    });
+}

package/src/tiling/keymap.js

@@ -0,0 +1,156 @@
+/**
+ * keymap.js — Alt-based shortcuts for the tiling window manager.
+ *
+ *   Alt+H               split focused tile horizontally (new empty pane)
+ *   Alt+V               split focused tile vertically (new empty pane)
+ *   Alt+Shift+H         open focused tile's content in a horizontal split
+ *   Alt+Shift+V         open focused tile's content in a vertical split
+ *   Alt+T               open focused tile's content in a new tab
+ *   Alt+N               open focused tile's content in a new window
+ *   Alt+W               close focused tile
+ *   Alt+F               promote focused tile <-> managed window (moves it)
+ *   Alt+ArrowLeft/Right/Up/Down         move focus
+ *   Alt+Shift+Arrow…    swap focused tile with neighbour
+ *   Alt+1..9            switch desktop
+ *   Alt+Shift+1..9      move focused tile to desktop N
+ *   Ctrl+ArrowLeft/Right                iterate virtual desktops
+ *   Shift+ArrowLeft/Right               iterate bottom-panel tabs (when present)
+ *   Ctrl+Tab / Ctrl+Shift+Tab           next / previous main-panel tab (focused tile)
+ *   F1..F8              jump to the Nth top-nav page
+ *   Ctrl+K              open command palette
+ *   ?                   open Help (lists every shortcut) — bound globally
+ *                       by help_modal.js, not here
+ *   Esc                 close palette / managed-modal
+ *
+ * The full user-facing reference is the Help modal's "Keyboard shortcuts"
+ * topic (ui/js/help/help_service.js) — keep that table in sync when
+ * binding new chords here.
+ *
+ * The handler refuses to act when focus is in an editable field, unless
+ * the chord uses the Alt modifier (which is never typed into a field).
+ */
+
+export function installKeymap({ wm, palette }) {
+    document.addEventListener('keydown', (e) => {
+        const inField = e.target?.closest?.(
+            'input, textarea, select, [contenteditable="true"]');
+
+        if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k' && !e.shiftKey) {
+            e.preventDefault();
+            palette.toggle();
+            return;
+        }
+        // ── Ctrl+Tab / Ctrl+Shift+Tab → next / previous main-panel tab in the
+        // focused tile (wraps). Works everywhere (Tab isn't a text key here);
+        // no-op when the tile has a single tab.
+        if ((e.ctrlKey || e.metaKey) && !e.altKey && e.key === 'Tab') {
+            e.preventDefault();
+            wm.cycleFocusedTab(e.shiftKey ? -1 : 1);
+            return;
+        }
+        if (e.key === 'Escape') {
+            if (palette.isOpen()) { palette.close(); return; }
+            // Let managed-window system handle its own Esc.
+        }
+        // Backspace = walk one step up the breadcrumb hierarchy. Skips
+        // when the user is typing in a field so it doesn't steal
+        // text-deletion.
+        if (e.key === 'Backspace' && !inField && !e.metaKey && !e.ctrlKey) {
+            e.preventDefault();
+            wm.navigateBack?.();
+            return;
+        }
+
+        // ── F1..F8 → jump straight to the Nth top-nav page. F-keys never
+        // type, but we still skip while a field is focused so editing
+        // flows (query editor, filters) keep keyboard focus.
+        const fMatch = /^F([1-9]|1[0-2])$/.exec(e.key);
+        if (fMatch && !inField && !e.altKey && !e.ctrlKey && !e.metaKey && !e.shiftKey) {
+            const btns = document.querySelectorAll(
+                '.twm-global-top-bar .twm-bar-center.twm-top-nav .twm-top-nav__btn');
+            const idx = Number(fMatch[1]) - 1;
+            if (idx < btns.length) {
+                e.preventDefault();
+                btns[idx].click();
+                return;
+            }
+        }
+
+        // ── Shift+Left/Right → previous/next bottom-panel tab. No-op when
+        // no bottom panel is mounted. Skipped in fields so Shift+Arrow
+        // keeps selecting text there.
+        if (e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey && !inField
+            && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) {
+            const tabs = [...document.querySelectorAll('.twm-bp__tabs .twm-bp__tab')];
+            if (tabs.length) {
+                const cur = tabs.findIndex((t) => t.classList.contains('twm-bp__tab--on'));
+                const dir = e.key === 'ArrowRight' ? 1 : -1;
+                const next = ((cur < 0 ? 0 : cur) + dir + tabs.length) % tabs.length;
+                e.preventDefault();
+                tabs[next].click();
+                return;
+            }
+        }
+
+        // ── Ctrl+Left/Right → iterate virtual desktops (wraps).
+        if (e.ctrlKey && !e.altKey && !e.shiftKey && !e.metaKey && !inField
+            && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) {
+            e.preventDefault();
+            wm.cycleDesktop(e.key === 'ArrowRight' ? 1 : -1);
+            return;
+        }
+
+        if (!e.altKey) return;
+        // Browser Alt+letter triggers menu-access in some browsers — always preventDefault.
+        const key = e.key.toLowerCase();
+
+        // Desktop switch / move — Alt+digit
+        if (/^[1-9]$/.test(e.key)) {
+            e.preventDefault();
+            const idx = Number(e.key) - 1;
+            if (e.shiftKey) wm.moveFocusedToDesktop(idx);
+            else wm.switchDesktop(idx);
+            return;
+        }
+
+        switch (key) {
+            // Plain Alt+H/V split into an empty pane; with Shift they open
+            // the focused tile's own content in the new split.
+            case 'h':
+                e.preventDefault();
+                e.shiftKey ? wm.splitFocusedWith('h') : wm.split('h');
+                return;
+            case 'v':
+                e.preventDefault();
+                e.shiftKey ? wm.splitFocusedWith('v') : wm.split('v');
+                return;
+            case 't': e.preventDefault(); wm.openFocusedInTab(); return;
+            case 'n': e.preventDefault(); wm.openFocusedInWindow(); return;
+            case 'w': e.preventDefault(); wm.closeFocused(); return;
+            case 'f': e.preventDefault(); wm.toggleManagedFocused(); return;
+            case 'arrowleft':
+                e.preventDefault();
+                e.shiftKey ? wm.moveFocused('left') : wm.focusDir('left');
+                return;
+            case 'arrowright':
+                e.preventDefault();
+                e.shiftKey ? wm.moveFocused('right') : wm.focusDir('right');
+                return;
+            case 'arrowup':
+                e.preventDefault();
+                e.shiftKey ? wm.moveFocused('up') : wm.focusDir('up');
+                return;
+            case 'arrowdown':
+                e.preventDefault();
+                e.shiftKey ? wm.moveFocused('down') : wm.focusDir('down');
+                return;
+        }
+
+        // Suppress accidental browser menu-access on bare Alt+letter
+        // chords we don't bind (so the user doesn't get a Firefox/Chromium
+        // menu popping open mid-flow).
+        if (key.length === 1 && /[a-z]/.test(key) && !inField) {
+            e.preventDefault();
+        }
+    });
+}

package/src/tiling/kind_taxonomy.js

@@ -0,0 +1,172 @@
+/**
+ * kind_taxonomy.js — the taxonomy PORT.
+ *
+ * A "kind" is a content type the user can navigate to. The tiling shell
+ * needs to know four things about one: what to call it, what icon it
+ * wears, which top-nav slot owns it, and what sits above it. It must
+ * NOT know what any of them mean.
+ *
+ * So the taxonomy is INJECTED, not imported. The embedder describes its
+ * own ontology and hands it to `createTaxonomy()` at boot; the shell
+ * closes over the result. Nothing in this file names a kind, and the
+ * framework runs unchanged on a completely different vocabulary.
+ *
+ * Consumed by:
+ *
+ *   - install.js          → top-nav buttons + active-state highlight
+ *   - tile_breadcrumb.js  → breadcrumb segments
+ *   - wm.js navigateBack  → Backspace parent
+ *   - command_palette.js  → palette chip strip + row icons
+ *   - tile_tab_menu.js    → which sources a tile's hamburger lists
+ *
+ * ## KindDef
+ *
+ *   label       Long form, used in breadcrumb segments + palette.
+ *   shortLabel  Optional ≤4-char chip text for the top-nav.
+ *               Falls back to `label` when omitted.
+ *   icon        Material Symbols name.
+ *   topNav      Top-nav category this kind belongs to. Determines which
+ *               button lights up + which segment the breadcrumb inserts
+ *               after the root. Omit on the top-nav kind itself.
+ *   isTopNav    True iff this kind owns a slot in the top-nav strip.
+ *   order       Sort key for top-nav display (lower = leftward).
+ *   appGlobal   True iff the kind is not scoped to the root entity (a
+ *               preferences page, say). Its breadcrumb omits the root.
+ *   sources     Entity-source ids the tile hamburger lists when a tile
+ *               is on this page. Only meaningful on top-nav kinds; the
+ *               root's list is the fallback.
+ *
+ *   ancestors?  `(props) => [{ kind, id, label? }]` — the entity-level
+ *               ancestors of ONE instance, root-most first, EXCLUDING
+ *               the top-nav segment and the node itself. This is the
+ *               hook that replaces every hardcoded "split the id to
+ *               find its parent" branch: naming conventions are the
+ *               embedder's business, not the shell's.
+ *   labelOf?    `(props) => string` — display label for ONE instance.
+ *               Defaults to `props.label`, then `props.id`.
+ */
+
+/** Build a taxonomy from an embedder's kind map. Validated eagerly and
+ *  frozen — a typo in a `topNav` pointer is a boot error, not a chrome
+ *  surface that silently renders nothing six clicks later. */
+export function createTaxonomy({ kinds, root } = {}) {
+    if (!kinds || typeof kinds !== 'object') {
+        throw new TypeError('createTaxonomy: `kinds` must be an object of KindDefs');
+    }
+    if (!root || !kinds[root]) {
+        throw new Error(`createTaxonomy: root kind '${root}' is not in the taxonomy`);
+    }
+    for (const [kind, def] of Object.entries(kinds)) {
+        if (!def || typeof def !== 'object') {
+            throw new TypeError(`createTaxonomy: '${kind}' is not a KindDef`);
+        }
+        if (def.topNav && !kinds[def.topNav]) {
+            throw new Error(
+                `createTaxonomy: '${kind}' hangs off unknown topNav '${def.topNav}'`);
+        }
+        if (def.isTopNav && def.topNav) {
+            throw new Error(
+                `createTaxonomy: '${kind}' is both a top-nav kind and owned by one`);
+        }
+    }
+    const _kinds = Object.freeze({ ...kinds });
+
+    /** Lookup. `undefined` for unknown kinds — chrome code treats that
+     *  as "render the kind name verbatim". */
+    const meta = (kind) => _kinds[kind];
+
+    /** Top-nav category id that owns `kind`. For a top-nav kind itself,
+     *  returns the same kind. `undefined` when the kind isn't in the
+     *  taxonomy (caller renders a fallback). */
+    const topNavFor = (kind) => {
+        const m = _kinds[kind];
+        if (!m) return undefined;
+        return m.isTopNav ? kind : m.topNav;
+    };
+
+    /** Backspace target — walk one step up the KIND hierarchy. A
+     *  top-nav page goes to the root; everything else goes to its
+     *  top-nav. The root itself returns `null`. */
+    const parentKindFor = (kind) => {
+        if (kind === root) return null;
+        const m = _kinds[kind];
+        if (!m) return null;
+        if (m.isTopNav) return root;
+        return m.topNav || root;
+    };
+
+    /** Entity-level ancestors of one instance, root-most first. Empty
+     *  unless the KindDef supplies an `ancestors` hook. Normalised to
+     *  `{ kind, props }` so callers hand the result straight to
+     *  `wm.navigate`. A throwing hook is a warning, never a crash: the
+     *  breadcrumb degrades to its generic form. */
+    const ancestors = (kind, props) => {
+        const fn = _kinds[kind]?.ancestors;
+        if (typeof fn !== 'function') return [];
+        let out;
+        try { out = fn(props || {}); }
+        catch (err) {
+            console.warn('[taxonomy] ancestors() threw for', kind, err);
+            return [];
+        }
+        if (!Array.isArray(out)) return [];
+        return out
+            .filter((a) => a && a.kind)
+            .map((a) => ({ kind: a.kind, props: { id: a.id, label: a.label ?? a.id } }));
+    };
+
+    /** The nearest entity-level ancestor, or `null`. */
+    const parentOf = (kind, props) => {
+        const chain = ancestors(kind, props);
+        return chain.length ? chain[chain.length - 1] : null;
+    };
+
+    /** Display label for one instance of `kind`. */
+    const labelOf = (kind, props) => {
+        const fn = _kinds[kind]?.labelOf;
+        if (typeof fn === 'function') {
+            try {
+                const s = fn(props || {});
+                if (s) return String(s);
+            } catch (err) {
+                console.warn('[taxonomy] labelOf() threw for', kind, err);
+            }
+        }
+        if (props?.label) return String(props.label);
+        return props?.id != null ? String(props.id) : '';
+    };
+
+    /** Entity-source ids a tile on `kind` should offer. Falls back to
+     *  the root's list, which is the "everything" default. */
+    const sourcesFor = (kind) => {
+        const s = _kinds[kind]?.sources ?? _kinds[root]?.sources;
+        return Array.isArray(s) ? s : [];
+    };
+
+    /** Top-nav entries in display order:
+     *      { kind, label (short), longLabel, icon }
+     *  `label` is the chip text; `longLabel` is what the palette shows. */
+    const topNavEntries = () =>
+        Object.entries(_kinds)
+            .filter(([, m]) => m.isTopNav)
+            .sort((a, b) => (a[1].order ?? 1000) - (b[1].order ?? 1000))
+            .map(([kind, m]) => ({
+                kind,
+                label:     m.shortLabel || m.label,
+                longLabel: m.label,
+                icon:      m.icon,
+            }));
+
+    return Object.freeze({
+        root,
+        kinds: _kinds,
+        meta,
+        topNavFor,
+        parentKindFor,
+        ancestors,
+        parentOf,
+        labelOf,
+        sourcesFor,
+        topNavEntries,
+    });
+}