flexdesk 0.2.0 → 0.4.0

package/src/tiling/shell.js

@@ -43,7 +43,8 @@ import { WindowManager } from './wm.js';
 import { createContentRegistry } from './content_registry.js';
 import { createCommandPalette } from './command_palette.js';
 import { installKeymap } from './keymap.js';
-import { openTileTabMenu } from './tile_tab_menu.js';
+import { openTileTabSwitcher } from './tile_tab_menu.js';
+import { mountZoomControl } from './zoom.js';
 import { showContextMenu } from '../ui/components/context_menu.js';
 import { openForm } from '../ui/components/modal.js';
 
@@ -64,9 +65,45 @@ import { openForm } from '../ui/components/modal.js';
  * @param {object}     [cfg.tableStore] threaded into ctx for table persistence
  * @param {object}     [cfg.events]     bus-event NAMES the WM listens for
  * @param {object}     [cfg.rootCrumb]  the breadcrumb's leading segment
- * @param {object}     [cfg.palette]    { placeholder }
+ * @param {object}     [cfg.palette]    { placeholder, onPick } — C30. `onPick`
+ *                                      is `(pick) => truthy` and CLAIMS the
+ *                                      open of a picked entity, so an embedder
+ *                                      with a rule about where its own entities
+ *                                      belong applies that rule whichever door
+ *                                      was used. Unclaimed picks still reset
+ *                                      the primary tile: the behaviour every
+ *                                      embedder has today.
+ * @param {object}     [cfg.panels]     C14. Which panel TILES a fresh desktop
+ *                                      opens with — `{left, right, bottom}`,
+ *                                      merged over all-three-open. An embedder
+ *                                      whose navigator is its own chrome passes
+ *                                      `{left: false, right: false}` and gets no
+ *                                      tile it never registered a factory for.
+ * @param {boolean}    [cfg.promoteInPlace] C21. Whether a window promoted out
+ *                                      of a tile stays confined to that pane
+ *                                      rather than floating over the whole root.
+ * @param {boolean}    [cfg.snapPromotion] C15. Whether dragging a promoted
+ *                                      window onto a tile puts it back in the
+ *                                      tree. Default off — it changes what a
+ *                                      drag to an edge does.
+ * @param {'top'|'bottom'} [cfg.tabLayout] C22. Where a multi-tab leaf draws its
+ *                                      tabs. `'bottom'` is the framework's own
+ *                                      spreadsheet strip under the tile body
+ *                                      and is the DEFAULT, so no existing
+ *                                      embedder's panes rearrange on upgrade;
+ *                                      `'top'` mounts the editor tab bar
+ *                                      between the chrome and the body. The
+ *                                      renderer mirrors this onto `root` as
+ *                                      `data-twm-tabs` and watches it, so an
+ *                                      embedder whose settings pane holds only
+ *                                      the root element can change it live.
  * @param {object}     [cfg.chrome]     { topNav?, paletteButton?, desktops?,
- *                                        panelToggles?: { left?, right?, bottom? } }
+ *                                        panelToggles?: { left?, right?, bottom? },
+ *                                        zoom? }
+ *                                      `zoom` is C31: the element the content
+ *                                      zoom control is painted into — see
+ *                                      zoom.js. Absent, there is no control and
+ *                                      nothing is ever scaled.
  * @returns {Promise<object>} the frozen shell
  */
 export async function createShell({
@@ -82,7 +119,15 @@ export async function createShell({
     events = {},
     rootCrumb = null,
     palette: paletteCfg = {},
+    panels = null,
+    snapPromotion = false,
+    promoteInPlace = false,
+    tabLayout = null,
     chrome = {},
+    // An embedder that moved its sections out of the top bar — into an icon
+    // rail, say — passes the selector its own buttons match, and F1..F8 keep
+    // working. Omitted, the default top-bar selector applies.
+    navSelector = null,
 } = {}) {
     // A bad shell is a BOOT error, not a runtime surprise. Same doctrine as
     // createHost / createTaxonomy.
@@ -115,6 +160,10 @@ export async function createShell({
         host,
         taxonomy,
         events,
+        panelDefaults: panels,
+        snapPromotion,
+        promoteInPlace,
+        tabLayout,
         // `ctx` is the delivery vehicle for leaf-mounted chrome: tile_renderer
         // spreads it into every content factory, which is how the breadcrumb
         // gets `taxonomy` + `rootCrumb` without a content factory knowing they
@@ -132,13 +181,23 @@ export async function createShell({
     const palette = createCommandPalette({
         wm, api, taxonomy, catalog: entities, ...paletteCfg,
     });
-    installKeymap({ wm, palette });
+    // `navSelector` lets an embedder that moved its sections out of the top
+    // bar keep F1..F8 working. Omitted, the default top-bar selector applies —
+    // the behaviour every existing embedder has today.
+    const disposeKeymap = installKeymap({ wm, palette, navSelector });
 
     // Chrome — painted into the ELEMENTS the embedder handed over. An absent
     // key means absent chrome, not a crash.
     const paletteBtn = mountPaletteButton(chrome.paletteButton, palette);
     topNavEl = mountTopNav(chrome.topNav, taxonomy, wm);
     desktopsEl = mountDesktopBar(chrome.desktops, wm);
+    // C31. The content zoom. Painted with the rest of the chrome and, unlike the
+    // rest, AWAITED before the first mount: its saved value is applied to `root`
+    // as a CSS variable, and a shell that mounted first would paint every tile at
+    // 100% and then visibly jump to the user's zoom a moment later. A host with no
+    // saved zoom — or no `state` at all — resolves immediately to the default.
+    const zoom = mountZoomControl(chrome.zoom, { root, host });
+    if (zoom) await zoom.ready;
     // NOTE: bindPanelToggles CLONES the buttons (to strip whatever state the
     // embedder's own machinery left on them) and returns the FRESH nodes. The
     // originals are detached from here on — sync against the returned map, not
@@ -165,9 +224,31 @@ export async function createShell({
             topNavEl,
             desktopsEl,
             panelToggles: toggles,
+            // `get`/`set` so an embedder can drive the zoom from its own settings
+            // pane, or read it, without reaching into the control's DOM.
+            zoom,
         }),
+        // A shell that can be built can be built TWICE — an embedder that
+        // rebuilds on a context change (a different project, a different
+        // workspace) does exactly that. Everything this function installs
+        // outside `root` has to come off, or the second shell shares the page
+        // with the first one's keyboard.
         dispose: () => {
             try { eventBus?.off?.('wm:changed', syncChrome); } catch { /* ignore */ }
+            try { disposeKeymap?.(); } catch { /* ignore */ }
+            try { palette?.close?.(); } catch { /* ignore */ }
+            // Every content factory gets its `destroy()`. Clearing the root
+            // element would detach the DOM and tell none of them, so an ERD's
+            // `window` keydown listener or a pane's interval would outlive the
+            // shell that mounted it. This also stops the renderer painting, so
+            // anything still holding a reference to this wm — a callback
+            // captured before a rebuild, a promise that has not settled —
+            // cannot repaint a dead tree into a root the live shell now owns.
+            try { wm.renderer.destroy(); } catch (err) { log.warn?.('renderer teardown', err); }
+            // The zoom lives on `root` as a variable and a class. A rebuilt shell on
+            // the same root must not inherit the old one's scale with no control on
+            // screen to change it, so dispose puts the root back to 100%.
+            try { zoom?.dispose(); } catch { /* ignore */ }
         },
     });
 }
@@ -217,10 +298,23 @@ function syncTopNav(hostEl, wm) {
     });
 }
 
+/**
+ * The palette button, REBOUND rather than reused.
+ *
+ * This used to return an existing `#twm-palette-btn` untouched, which is right
+ * only while a page mounts one shell and keeps it. An embedder that rebuilds
+ * its shell — Tables does, on every project switch — got its FIRST shell's
+ * button back, still wired to the FIRST shell's palette. Clicking it opened a
+ * palette over a disposed window manager, and picking a result called
+ * `openInPrimary` on a tree nobody could see, whose renderer then painted it
+ * into the root the live shell now owns.
+ *
+ * So the stale node is replaced, which is exactly what `bindPanelToggles` does
+ * one function below and for the same reason.
+ */
 function mountPaletteButton(hostEl, palette) {
     if (!hostEl) return null;
-    const existing = hostEl.querySelector('#twm-palette-btn');
-    if (existing) return existing;
+    hostEl.querySelector('#twm-palette-btn')?.remove();
     const btn = document.createElement('button');
     btn.id = 'twm-palette-btn';
     btn.className = 'twm-panel-toggle-btn twm-has-tooltip';
@@ -361,27 +455,27 @@ function syncDesktopBar(el, wm) {
 
 // ══ Tile menus ════════════════════════════════════════════════════════
 
-/** Hamburger button in a tile's tab bar. Lists the same content the tile's
- *  home page would, with search + pagination. Clicking a row opens the entity
- *  in a NEW TAB on the ORIGINATING tile (the leaf id is captured at click
- *  time, so a focus change between click and pick doesn't reroute it). */
+/** Hamburger button in a tile's tab bar. Opens a compact menu anchored to
+ *  the button that lists the leaf's OPEN TABS for quick switching (a
+ *  browser-style tab overflow list). Clicking a row activates that tab.
+ *  The leaf id is captured at click time, so a focus change between click
+ *  and pick doesn't reroute it. */
 function _tileTabMenu(wm, leafId, x, y) {
     const tree = wm.desktops.active().tree;
     const leaf = tree.get(leafId);
-    if (!leaf) return;
-    const kind = leaf.content?.kind || wm.taxonomy.root;
-    openTileTabMenu({
-        x, y, leafKind: kind, api: wm.api,
-        taxonomy: wm.taxonomy, entities: wm.ctx.entities,
-        onPick: (navKind, shaped) => {
-            tree.appendLeafTab(leafId, {
-                kind: navKind,
-                props: { id: shaped.id, label: shaped.label },
-            }, shaped.label || shaped.id);
+    if (!leaf || leaf.kind !== 'leaf') return;
+    const tabs = Array.isArray(leaf.tabs) ? leaf.tabs : [];
+    if (tabs.length === 0) return;
+    openTileTabSwitcher({
+        x, y,
+        tabs,
+        activeIdx: Math.max(0, Math.min(tabs.length - 1, leaf.activeTabIdx || 0)),
+        onPick: (idx) => {
+            tree.setActiveLeafTab(leafId, idx);
             tree.focus(leafId);
             wm.renderer.render();
             wm._persist?.();
-            wm._notifyChange?.('tab-open-from-menu');
+            wm._notifyChange?.('tab-switch-from-menu');
         },
     });
 }
@@ -401,10 +495,36 @@ function _tileContextMenu(wm, leafId, x, y) {
         { separator: true },
         { label: 'Open in new tab',    icon: 'tab',
           action: 'open-tab',    disabled: isPanel || !leaf.content },
-        { label: 'Open in new window', icon: 'open_in_full',
+        // TWO DIFFERENT GLYPHS FOR TWO DIFFERENT DESTINATIONS. `web_asset` is a
+        // window INSIDE the application — the same glyph `ManagedWindow` uses
+        // for itself — and an embedder that can also send content to a real
+        // browser window keeps `open_in_new`, which is the universal "this
+        // leaves the page". One glyph for both is how a user learns that the
+        // two commands are the same command, and then loses a window looking
+        // for it on the other screen.
+        { label: 'Open a copy in a window', icon: 'web_asset',
           action: 'open-window', disabled: isPanel || !leaf.content },
-        { label: 'Promote to window', icon: 'open_in_new',
-          action: 'promote', disabled: isPanel || !leaf.content },
+        // C20, THE OTHER HALF — and it was missing while the `close` half
+        // below carried a paragraph explaining why it could not be.
+        //
+        // `_floatableLeaf` (`wm.js`) refuses to float content that declared
+        // `chrome: { promote: false }`, and every door converges there — so
+        // this row offered the verb, enabled, and returned null. The chrome's
+        // own float BUTTON does not have the problem: C20 removes it from the
+        // strip. That asymmetry is what hid this: the affordance the reader
+        // checks is correct, and the menu one layer down is not.
+        //
+        // `=== false` EXACTLY, because that is the test the verb makes
+        // (`wm.js`, `_floatableLeaf`: *"content that says nothing about
+        // `promote` stays floatable"*). A falsy test here would grey the row
+        // on every leaf whose content returned no `chrome` at all, which is
+        // most of them — a menu disagreeing with its verb in the generous
+        // direction is a dead control; in the mean direction it is a missing
+        // feature, and this file has shipped one of each.
+        { label: 'Float this pane as a window', icon: 'web_asset',
+          action: 'promote',
+          disabled: isPanel || !leaf.content
+                    || wm.renderer?.leafChrome?.(leafId)?.promote === false },
     ];
     if (wm.desktops.desktops.length > 1 && !isPanel) {
         for (const [i, d] of wm.desktops.desktops.entries()) {
@@ -414,8 +534,19 @@ function _tileContextMenu(wm, leafId, x, y) {
         }
     }
     items.push({ separator: true });
+    // C20. THE MENU ROW CARRIES THE VETO, AND THE REASON WITH IT.
+    //
+    // `closeFocused` refuses when the content vetoed `close`, which is what
+    // makes the greyed × in the chrome honest — and left this row offering the
+    // same verb, enabled, doing nothing. A control that silently no-ops is the
+    // dead-control failure this file has fixed three times already. The
+    // tooltip is the content's own sentence, so the two doors explain the
+    // refusal identically rather than one explaining it and one not.
+    const closeVeto = wm.renderer?.leafChrome?.(leafId)?.close;
+    const closeVetoed = closeVeto === false || closeVeto?.disabled === true;
     items.push({ label: 'Close tile', icon: 'close', action: 'close',
-                 danger: true, disabled: isPanel });
+                 danger: true, disabled: isPanel || closeVetoed,
+                 title: closeVetoed ? (closeVeto?.title || undefined) : undefined });
 
     showContextMenu(x, y, items, (action) => {
         if (action === 'split-h') wm.split('h');

package/src/tiling/tab_strip.js

@@ -0,0 +1,184 @@
+/**
+ * tab_strip.js — ONE tab strip, over one ordered list of tab specs.
+ *
+ * ── Why this is a module and not a method ────────────────────────────────
+ *
+ * C22 taught `tile_renderer.js` to draw a leaf's tabs with `NotebookTabBar`,
+ * the editor's strip, and that code is not really about leaves: it is about
+ * translating between a component whose vocabulary is FILE PATHS and a list of
+ * `{kind, props, title}` that has no identity of its own. R8 needs exactly that
+ * translation a second time — a pane floated into a window takes its tab strip
+ * with it, because the pane IS its tabs and a window showing only one of them
+ * is not the pane — and the strip in the window is not attached to a leaf at
+ * all. Its tabs live in the WM's window record.
+ *
+ * So the translation moves here, where neither side owns it, and both sides
+ * reach it the same way. A second implementation of it in `wm.js` would be a
+ * second copy of the four corrections below, and they would drift apart
+ * silently: none of them is a syntax error and none throws at import.
+ *
+ * ── The four corrections, and why each one exists ────────────────────────
+ *
+ *   1. IDENTITY. `NotebookTabBar` keys everything — its reorder, its active
+ *      comparison, its rename selector — on a file path. A tab list has no ids
+ *      (the tree gives tabs none and neither does a window record), so the
+ *      INDEX serves, and it is the one identity such a list is guaranteed to
+ *      have. The `builtin://` prefix is not decoration: `#beginInlineRename`
+ *      refuses to start on a path carrying it (`notebook_tab_bar.js:402`),
+ *      which is what a tab needs — double-click rename would rename a TAB, and
+ *      a tab is a view of an entity whose name lives somewhere neither caller
+ *      can reach.
+ *   2. THE GLYPH. The component picks one out of a static map of FILE kinds.
+ *      Ours are the embedder's kinds and the taxonomy already answers for them.
+ *      `setFileTypeIcons()` is not the way: it is STATIC and REPLACES the whole
+ *      map, so a page that also uses the editor would find its own file icons
+ *      deleted by whichever of the two rendered last.
+ *   3. THE TOOLTIP. Its title attribute is the file PATH — ours would read
+ *      `builtin://tab/3`, i.e. a tab advertising its own array index.
+ *   4. ONE TAB CONTEXT MENU IN THE APPLICATION, not two. The component opens
+ *      its own `.nb-context-menu` whose verbs are a notebook's (rename,
+ *      duplicate, reveal in explorer). The caller has a menu already; the
+ *      component's is suppressed in the CAPTURE phase, because its handler is
+ *      bound on each tab element in the bubble phase and stopping the event on
+ *      the way DOWN is what keeps its menu from opening at all.
+ *
+ * The class names touched here are the component's published contract, stated
+ * in its own header comment.
+ */
+
+import { NotebookTabBar } from '../editor/notebook_tab_bar.js';
+
+/** A tab's identity, for a component that only understands paths. See (1). */
+export function tabKey(idx) { return `builtin://tab/${idx}`; }
+
+/** …and back. `-1` for anything that is not one of ours. */
+export function tabKeyIndex(key) {
+    const n = Number(String(key ?? '').replace('builtin://tab/', ''));
+    return Number.isInteger(n) && n >= 0 ? n : -1;
+}
+
+/**
+ * DRAG-TO-REORDER ARRIVES AS A PERMUTATION, and every tab model here moves ONE
+ * tab at a time (`TileTree.moveLeafTab(leafId, from, to)`, and the window
+ * record's own splice). They reconcile because a drag only ever moves one
+ * element: every other key shifts by exactly one place, so the element that
+ * travelled furthest between the two orders IS the one that was dragged.
+ *
+ * @returns {{from: number, to: number}|null} null when the order is not a
+ *   permutation of `count` tabs, or when nothing actually moved.
+ */
+export function reorderToMove(order, count) {
+    if (!Array.isArray(order) || order.length !== count) return null;
+    let from = -1;
+    let to = -1;
+    let furthest = 0;
+    order.forEach((key, newIdx) => {
+        const oldIdx = tabKeyIndex(key);
+        if (oldIdx < 0) return;
+        const travelled = Math.abs(newIdx - oldIdx);
+        if (travelled > furthest) { furthest = travelled; from = oldIdx; to = newIdx; }
+    });
+    if (from < 0 || from === to) return null;
+    return { from, to };
+}
+
+/**
+ * Mount a tab strip into `hostEl` and drive it from a plain tab list.
+ *
+ * Every gesture leaves through ONE callback with the SAME vocabulary the tile
+ * renderer's two layouts already use — `switch` / `close` / `move` / `menu` —
+ * so a caller wires one function and the WM's tree mutations, its persistence
+ * and its change notifications stay reachable by one path from every strip in
+ * the application.
+ *
+ * @param {object}      cfg
+ * @param {HTMLElement} cfg.hostEl    the bar element. The strip mounts into a
+ *   CHILD of it, because `mount()` assigns `container.className = 'tabs
+ *   notebook-tabs'` (`notebook_tab_bar.js:61`) — handing it the bar would take
+ *   that class, and with it the bar's height, background and `--hidden`, off
+ *   the element the caller still controls.
+ * @param {object}     [cfg.taxonomy] asked for each kind's glyph. Absent ⇒ the
+ *   glyph is hidden rather than wrong.
+ * @param {(action: 'switch'|'close'|'move'|'menu', data: object) => void} cfg.onAction
+ * @returns {{update: (tabs: object[], activeIdx: number) => void, dispose: () => void}}
+ */
+export function createTabStrip({ hostEl, taxonomy = null, onAction }) {
+    const host = document.createElement('div');
+    hostEl.appendChild(host);
+    const strip = new NotebookTabBar();
+    let tabs = [];
+
+    strip.mount(host, {
+        onActivate: (key) => {
+            const idx = tabKeyIndex(key);
+            if (idx >= 0) onAction?.('switch', { idx });
+        },
+        onClose: (key) => {
+            const idx = tabKeyIndex(key);
+            if (idx >= 0) onAction?.('close', { idx });
+        },
+        onReorder: (order) => {
+            const move = reorderToMove(order, tabs.length);
+            if (move) onAction?.('move', move);
+        },
+        // Everything else the component offers that a tab here cannot honour is
+        // deliberately absent rather than stubbed — `onRename` is refused by the
+        // `builtin://` key, and the rest (`onDuplicate`, `onSplitRight`,
+        // `onRevealInExplorer`, `onCloseAll`, …) are only ever reached from the
+        // context menu suppressed below.
+    });
+
+    // See (4). Capture phase, on the container.
+    const onContextMenu = (ev) => {
+        const tabEl = ev.target.closest?.('.tab');
+        if (!tabEl) return;
+        ev.preventDefault();
+        ev.stopPropagation();
+        const idx = Array.prototype.indexOf.call(host.querySelectorAll('.tab'), tabEl);
+        if (idx < 0) return;
+        onAction?.('menu', { idx, x: ev.clientX, y: ev.clientY });
+    };
+    host.addEventListener('contextmenu', onContextMenu, true);
+
+    /** See (2) and (3) — one pass over the DOM the component just wrote. */
+    const repaint = () => {
+        host.querySelectorAll('.tab').forEach((el, i) => {
+            const spec = tabs[i];
+            if (!spec) return;
+            el.title = spec.title || spec.kind || '';
+            const icon = spec.kind ? taxonomy?.meta?.(spec.kind)?.icon : null;
+            const glyph = el.querySelector('.tab-icon');
+            if (!glyph) return;
+            if (icon) { glyph.textContent = icon; glyph.hidden = false; }
+            else glyph.hidden = true;
+        });
+    };
+
+    return {
+        /** @param {Array<{kind: string, props?: object, title?: string, dirty?: boolean}>} next */
+        update(next, activeIdx) {
+            tabs = Array.isArray(next) ? next : [];
+            const active = Math.max(0, Math.min(tabs.length - 1, activeIdx || 0));
+            strip.update(
+                tabs.map((t, i) => ({
+                    filePath: tabKey(i),
+                    label: t.title || t.kind || '',
+                    fileType: t.kind || 'unknown',
+                    // Nothing sets `dirty` on a tab spec today, so the dot is
+                    // never drawn. Read anyway, because the day a tab can say it
+                    // holds unsaved work this is where it says it, and the
+                    // alternative is a second place to remember.
+                    isDirty: !!t.dirty,
+                })),
+                tabKey(active));
+            repaint();
+        },
+        dispose() {
+            host.removeEventListener('contextmenu', onContextMenu, true);
+            try { strip.dispose(); } catch (err) {
+                console.error('[tab-strip] dispose threw', err);
+            }
+            host.remove();
+        },
+    };
+}

package/src/tiling/tile_breadcrumb.js

@@ -73,8 +73,17 @@ export function mountTileBreadcrumb(kind, props, ctx) {
     // the breadcrumb simply starts at the top-nav.
     let rootLabel = rootCrumb?.label || '';
 
+    // Read at RENDER time, not captured: the trail grows with every
+    // click-through, and a breadcrumb that showed the trail as it was when the
+    // tile mounted would be describing a journey the user has since continued.
+    const trailOf = () => {
+        if (typeof ctx?.trailSegments !== 'function') return [];
+        try { return ctx.trailSegments() || []; }
+        catch (err) { console.warn('[breadcrumb] trailSegments threw', err); return []; }
+    };
     const render = () => {
-        _renderInto(root, _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate));
+        _renderInto(root,
+            _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate, trailOf()));
     };
     render();
 
@@ -92,6 +101,10 @@ export function mountTileBreadcrumb(kind, props, ctx) {
 
     return {
         el: root,
+        /** Repaint. A trail-driven breadcrumb changes without the tile
+         *  remounting — following a lookup replaces the active tab's content in
+         *  place — so the embedder that grew the trail says when. */
+        refresh: render,
         destroy: () => {
             try { unsubscribe?.(); }
             catch (err) { console.warn('[breadcrumb] rootCrumb teardown threw', err); }
@@ -99,7 +112,7 @@ export function mountTileBreadcrumb(kind, props, ctx) {
     };
 }
 
-function _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate) {
+function _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate, trail) {
     const segs = [];
     const meta = taxonomy.meta(kind);
 
@@ -132,6 +145,25 @@ function _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate) {
         });
     }
 
+    // 2b. THE TRAIL. An embedder whose navigation is a walk rather than a
+    //     descent — click a customer, follow a lookup to its region, follow
+    //     that to a country — has a real path that the taxonomy cannot know,
+    //     because none of those is an ANCESTOR of the next. The tree already
+    //     records it: every in-tile navigation pushes the outgoing content
+    //     onto the active tab's `history` stack, which is what Backspace pops.
+    //
+    //     `ctx.trailSegments` hands that stack over, already shaped. Absent, or
+    //     empty, this is a no-op and the breadcrumb is exactly the ancestor
+    //     walk it has always been.
+    for (const step of (trail || [])) {
+        if (!step?.kind) continue;
+        segs.push({
+            icon:  taxonomy.meta(step.kind)?.icon || 'description',
+            label: step.title || step.props?.label || step.props?.id || step.kind,
+            onClick: () => navigate(step.kind, step.props || {}),
+        });
+    }
+
     // 3. Entity-level ancestors, root-most first — supplied by the
     //    taxonomy, not by string surgery on the id.
     for (const anc of taxonomy.ancestors(kind, props)) {