flexdesk 0.2.0 → 0.4.0

package/src/tiles/tile_base.js

@@ -42,10 +42,25 @@ export class TileBase {
      * @param {Object} [options.eventBus] - Event bus for cross-component communication
      * @param {Object} [options.config] - Widget-specific configuration
      * @param {boolean} [options.headless] - If true, mount without tile chrome (header, controls)
+     * @param {{resolve: Function}} [options.dataSource] - Where this tile asks for its
+     *        own rows. Handed down by `TileGrid`; absent for a grid whose data is
+     *        broadcast with `setData()`, and then nothing ever calls `loadData()`.
      */
     constructor({ id, grid, eventBus = null, config = {}, readonly = false,
-                  headless = false, host = null, stateGuard = null }) {
+                  headless = false, host = null, stateGuard = null,
+                  dataSource = null }) {
         this.host = host;
+        // THE TILE PULLS; THE GRID DOES NOT PUSH.
+        //
+        // `TileGrid.setData()` broadcasts one dataset to every tile, which is the
+        // right shape when every tile reads the same simulation run and the wrong
+        // one when each tile is bound to a different query — the second tile would
+        // then have to find its own rows inside a payload it never asked for. A
+        // data source is anything answering `resolve(tileId, binding)`; the base
+        // class only holds it and hands it to `loadData()`, so a grid constructed
+        // without one behaves exactly as it did before this line existed, and the
+        // broadcast path is untouched.
+        this.dataSource = dataSource;
         // `window.__ECOSIM_JS_NEW__?.stateGuard` — an application's global, reached for
         // by a tile. The StateGuard is a FRAMEWORK service (@flexdesk/core); the INSTANCE is
         // the application's, and it is handed down through the grid. No guard => the
@@ -64,6 +79,12 @@ export class TileBase {
         /** @type {Object|null} Unfiltered analytics data for cross-namespace variable resolution */
         this.fullData = null;
         this._disposed = false;
+        // Written by whatever implements `loadData()`. `_loadSeq` is the guard
+        // against a slow first request landing after a fast second one and
+        // painting stale rows over fresh ones — a tile is re-resolved on every
+        // filter change, so that race is the normal case rather than the edge.
+        this._lastLoadedAt = null;
+        this._loadSeq = 0;
         /** @type {Map<string, {name: string, analytics: Object, color: string}>|null} */
         this.comparisonData = null;
     }
@@ -308,6 +329,33 @@ export class TileBase {
         }
     }
 
+    /**
+     * Load this tile's own data from `this.dataSource` and render it.
+     *
+     * A NO-OP HERE ON PURPOSE. The base class knows nothing about what a binding
+     * is or what a dataset looks like — those belong to the consumer, and the
+     * consumer that has them (Tables' `TablesTile`) implements this in ~30 lines
+     * over `showLoading()` / `render()` / `showError()`. What upstream owns is the
+     * CALL SITES: `TileGrid` invokes this after mount, after a resize settles and
+     * after a config save, but only when a `dataSource` was injected. Making it a
+     * hook rather than an implementation is what keeps EcoAgent's broadcast path
+     * (`setData` -> `update`) bit-identical: with no data source nothing here ever
+     * runs.
+     *
+     * @param {{force?: boolean}} [_opts] - `force` bypasses the source's cache.
+     * @returns {Promise<void>}
+     */
+    async loadData(_opts = {}) {}
+
+    /**
+     * Called once after a drag-resize settles, for widgets whose content does not
+     * reflow on its own — a Plotly figure sizes itself at draw time and stays that
+     * size until something calls `Plotly.Plots.resize`. Deliberately NOT wired to a
+     * ResizeObserver: the grid already knows when a resize ended, and an observer
+     * per tile fires during the drag, which is a relayout per pointer-move.
+     */
+    onResize() {}
+
     /** Add, update, or remove the info (ⓘ) button in the header to match current docs state. */
     _syncInfoButton() {
         const header = this.element?.querySelector('.tile-header');
@@ -367,6 +415,60 @@ export class TileBase {
         this.fullData = null;
     }
 
+    /**
+     * The entries in the tile's ⋯ menu, as `{action, label, icon, hidden}`.
+     *
+     * This existed as a LITERAL inside `_buildChrome`, and the literal was
+     * EcoAgent's: "Add to Documentation" and "Show in Documentation". Both are
+     * meaningful only for a tile whose `config.sourceCellId` names a notebook
+     * cell, and the first one's hide condition is `sourceCellId && already-added` —
+     * so on a tile that has no `sourceCellId` at all it renders VISIBLE, and
+     * choosing it emits `tile:add-to-documentation` at an application that has no
+     * documentation. Every consumer other than EcoAgent therefore shipped a menu
+     * item that did nothing, and could not remove it without editing this file.
+     *
+     * Returning `[]` drops the whole wrapper — button, dropdown and all — because
+     * a ⋯ button that opens an empty menu reads as a broken feature rather than
+     * an absent one. The default is the two entries above, so EcoAgent's chrome
+     * is unchanged.
+     *
+     * Selection is routed through `_onMenuAction()`; override both together.
+     * @returns {Array<{action: string, label: string, icon?: string, hidden?: boolean}>}
+     */
+    menuItems() {
+        const linked = !!(this.config?.sourceCellId
+                          && this.grid?.documentationCellIds?.has(this.config.sourceCellId));
+        return [
+            { action: 'add-to-documentation',
+              label: 'Add to Documentation',  icon: 'post_add',    hidden: linked },
+            { action: 'show-in-documentation',
+              label: 'Show in Documentation', icon: 'description', hidden: !linked },
+        ];
+    }
+
+    /**
+     * Act on a ⋯ menu selection. One dispatch point for every entry, so an
+     * override of `menuItems()` cannot add a row that has nothing behind it, and
+     * an unrecognised action is silently ignored rather than throwing into a
+     * click handler.
+     * @param {string} action
+     * @protected
+     */
+    _onMenuAction(action) {
+        if (action === 'add-to-documentation') {
+            this.eventBus?.emit?.('tile:add-to-documentation', {
+                tileType: this.constructor.TYPE,
+                config: { ...this.config },
+            });
+        } else if (action === 'show-in-documentation') {
+            if (this.config?.sourceCellId) {
+                this.eventBus?.emit?.('tile:show-in-documentation', {
+                    sourceCellId: this.config.sourceCellId,
+                });
+            }
+        }
+    }
+
     /**
      * Build the tile chrome (header, content area, resize handles).
      * @private
@@ -397,6 +499,24 @@ export class TileBase {
                </button>`
             : '';
 
+        // The ⋯ menu, from `menuItems()` rather than from a literal. Read-only
+        // chrome never had one, so the hook is not even asked in that mode.
+        const menuEntries = (this.readonly ? [] : this.menuItems()) ?? [];
+        const menuHtml = menuEntries.length
+            ? `<div class="tile-menu-wrapper">
+                        <button class="tile-menu-btn twm-has-tooltip" data-tooltip="More actions">
+                            <span class="material-symbols-outlined">more_vert</span>
+                        </button>
+                        <div class="tile-menu-dropdown" hidden>
+                            ${menuEntries.map((item) => `
+                            <button class="tile-menu-item" data-action="${this.#escapeAttr(item.action)}"${item.hidden ? ' style="display:none"' : ''}>
+                                ${item.icon ? `<span class="material-symbols-outlined">${this.#escapeAttr(item.icon)}</span>` : ''}
+                                <span>${this.#escapeAttr(item.label ?? '')}</span>
+                            </button>`).join('')}
+                        </div>
+                    </div>`
+            : '';
+
         if (this.readonly) {
             // Read-only mode: no drag handle, no menu, no remove button
             header.innerHTML = `
@@ -416,21 +536,7 @@ export class TileBase {
                     <button class="tile-config-btn twm-has-tooltip" data-tooltip="Configure">
                         <span class="material-symbols-outlined">settings</span>
                     </button>
-                    <div class="tile-menu-wrapper">
-                        <button class="tile-menu-btn twm-has-tooltip" data-tooltip="More actions">
-                            <span class="material-symbols-outlined">more_vert</span>
-                        </button>
-                        <div class="tile-menu-dropdown" hidden>
-                            <button class="tile-menu-item" data-action="add-to-documentation" style="${this.config?.sourceCellId && this.grid?.documentationCellIds?.has(this.config.sourceCellId) ? 'display:none' : ''}">
-                                <span class="material-symbols-outlined">post_add</span>
-                                <span>Add to Documentation</span>
-                            </button>
-                            <button class="tile-menu-item" data-action="show-in-documentation" style="${this.config?.sourceCellId && this.grid?.documentationCellIds?.has(this.config.sourceCellId) ? '' : 'display:none'}">
-                                <span class="material-symbols-outlined">description</span>
-                                <span>Show in Documentation</span>
-                            </button>
-                        </div>
-                    </div>
+                    ${menuHtml}
                     ${infoBtnHtml}
                     ${expandBtnHtml}
                     <button class="tile-remove-btn twm-has-tooltip" data-tooltip="Remove widget">
@@ -485,23 +591,17 @@ export class TileBase {
                         });
                     }
                 });
-                menuDropdown.querySelector('[data-action="add-to-documentation"]')?.addEventListener('click', (e) => {
-                    e.stopPropagation();
-                    menuDropdown.hidden = true;
-                    this.eventBus?.emit?.('tile:add-to-documentation', {
-                        tileType: this.constructor.TYPE,
-                        config: { ...this.config },
+                // One listener per rendered entry, dispatching by `data-action`
+                // into `_onMenuAction`. Wiring each action by name here is what
+                // made the menu un-overridable: a subclass could add a row and
+                // could not add the handler behind it.
+                menuDropdown.querySelectorAll('.tile-menu-item').forEach((itemEl) => {
+                    itemEl.addEventListener('click', (e) => {
+                        e.stopPropagation();
+                        menuDropdown.hidden = true;
+                        this._onMenuAction(itemEl.dataset.action);
                     });
                 });
-                menuDropdown.querySelector('[data-action="show-in-documentation"]')?.addEventListener('click', (e) => {
-                    e.stopPropagation();
-                    menuDropdown.hidden = true;
-                    if (this.config?.sourceCellId) {
-                        this.eventBus?.emit?.('tile:show-in-documentation', {
-                            sourceCellId: this.config.sourceCellId,
-                        });
-                    }
-                });
             }
 
             const removeBtn = header.querySelector('.tile-remove-btn');
@@ -619,6 +719,13 @@ export class TileBase {
 
     /**
      * Show empty state in content area.
+     *
+     * The message is ESCAPED. Both this and `showError` interpolated straight
+     * into `innerHTML`, and the string reaching `showError` is the one place a
+     * caller has least control over — a server's error text, echoed back with a
+     * column name or a filter value in it. Callers pass plain text; this decides
+     * what that means in HTML.
+     *
      * @param {string} [message] - Custom message
      */
     showEmpty(message = 'No data available') {
@@ -626,14 +733,14 @@ export class TileBase {
             this.contentElement.innerHTML = `
                 <div class="tile-empty">
                     <span class="material-symbols-outlined">inbox</span>
-                    <span>${message}</span>
+                    <span>${this.#escapeAttr(message)}</span>
                 </div>
             `;
         }
     }
 
     /**
-     * Show error state in content area.
+     * Show error state in content area. The message is escaped — see `showEmpty`.
      * @param {string} [message] - Error message
      */
     showError(message = 'Failed to load data') {
@@ -641,7 +748,7 @@ export class TileBase {
             this.contentElement.innerHTML = `
                 <div class="twm-tile-error">
                     <span class="material-symbols-outlined">error</span>
-                    <span>${message}</span>
+                    <span>${this.#escapeAttr(message)}</span>
                 </div>
             `;
         }
@@ -760,7 +867,8 @@ export class TileBase {
     }
 
     /**
-     * Escape a string for safe insertion into an HTML attribute.
+     * Escape a string for safe insertion into HTML — an attribute value or a text
+     * node, since the five characters that matter are the same five in both.
      * @private
      */
     #escapeAttr(s) {

package/src/tiles/tile_grid.js

@@ -21,6 +21,9 @@ export class TileGrid {
      * @param {Function} [options.onAddWidget] - Callback for add widget action
      * @param {Function} [options.onResetLayout] - Callback for reset layout action
      * @param {Function} [options.onExport] - Callback for export action
+     * @param {{resolve: Function}} [options.dataSource] - Per-tile data provider,
+     *        handed to every tile. With none, the grid is the broadcast-only grid
+     *        it has always been and no tile is ever asked to load anything.
      */
     constructor({ container, columns = 12, rowHeight = 80, gap = 16, eventBus = null,
                   showToolbar = true, readonly = false, onLayoutChange, onBeforeLayoutChange,
@@ -29,9 +32,13 @@ export class TileGrid {
                   // ui/js/ecoagent/ to back Expand -> Export CSV/PNG; a grid that has
                   // no host simply gets the Blob-download fallback the host contract
                   // promises. It is not an error to have none.
-                  host = null, stateGuard = null }) {
+                  host = null, stateGuard = null,
+                  // Injected, never constructed here: the grid does not know what
+                  // a binding is, only that a tile may have somewhere to ask.
+                  dataSource = null }) {
         this.host = host;
         this.stateGuard = stateGuard;
+        this.dataSource = dataSource;
         this.container = container;
         this.columns = columns;
         this.rowHeight = rowHeight;
@@ -181,6 +188,7 @@ export class TileGrid {
             readonly: this.readonly,
             host: this.host,
             stateGuard: this.stateGuard,
+            dataSource: this.dataSource,
         });
 
         if (!tile) return null;
@@ -211,6 +219,14 @@ export class TileGrid {
         if (this.data) {
             tile.fullData = this.fullData;
             tile.update(this.data);
+        } else if (this.dataSource) {
+            // A tile that fetches its own rows is never handed any, so the branch
+            // above cannot fire for it and it would mount empty and stay empty
+            // until something else happened to it. NOT awaited: `setLayout` calls
+            // `addTile` in a loop, and awaiting here would serialise a board into
+            // one request per tile in sequence — the opposite of what a batching
+            // data source exists to do.
+            tile.loadData?.();
         }
 
         // Emit layout changed
@@ -248,6 +264,31 @@ export class TileGrid {
         });
     }
 
+    /**
+     * Ask every self-fetching tile to load again, bypassing whatever the data
+     * source has cached.
+     *
+     * The counterpart of `setData` for the pull model: `setData` is how a caller
+     * with one dataset for the whole board pushes it, and this is how a caller
+     * whose tiles each own a query says "that underlying data changed". Passing
+     * `ids` narrows it to the tiles a change actually touched, which is what an
+     * invalidation carrying a table id can work out and a broadcast cannot.
+     *
+     * Not awaited and returns nothing: the tiles render themselves as their own
+     * requests land, and a caller that waited for all of them would be waiting on
+     * the slowest tile to show the fastest one.
+     *
+     * @param {string[]|Set<string>|null} [ids] - Tile ids, or null for all.
+     */
+    reloadAll(ids = null) {
+        if (!this.dataSource) return;
+        const wanted = ids ? new Set(ids) : null;
+        this.tiles.forEach((tile, tileId) => {
+            if (wanted && !wanted.has(tileId)) return;
+            tile.loadData?.({ force: true });
+        });
+    }
+
     /**
      * Get current layout.
      * @returns {Array} Layout array
@@ -560,6 +601,12 @@ export class TileGrid {
                 if (this.data) {
                     state.tile.fullData = this.fullData;
                     state.tile.update(this.data);
+                } else if (this.dataSource) {
+                    // Re-rendering from a dataset already in hand is free; asking
+                    // the server again because a tile got 40 px wider is not. A
+                    // self-fetching tile is told the geometry settled and decides
+                    // what that costs it — for a chart, one `Plotly.Plots.resize`.
+                    state.tile.onResize?.();
                 }
             }
         }
@@ -771,6 +818,10 @@ export class TileGrid {
                 if (tile) {
                     tile.fullData = this.fullData;
                     tile.update(this.data, newConfig);
+                    // A saved config is usually a changed BINDING, and the data
+                    // source's cache is keyed by the old one — so this is the one
+                    // reload that must not be served from it.
+                    if (this.dataSource) tile.loadData?.({ force: true });
                     // Update layout config
                     const layoutItem = this.layout.find(l => l.id === tileId);
                     if (layoutItem) {

package/src/tiling/command_palette.js

@@ -33,8 +33,13 @@ const STATIC_COMMANDS = [
 /** @param taxonomy    injected ontology — supplies the chip strip + row icons
  *  @param catalog     injected entity catalog — supplies the searchable rows
  *  @param placeholder input placeholder. It names the embedder's entity types
- *                     ("try foo:bar"), so the embedder owns the string. */
-export function createCommandPalette({ wm, api, taxonomy, catalog, placeholder = 'Search…' }) {
+ *                     ("try foo:bar"), so the embedder owns the string.
+ *  @param onPick      C30. `(pick) => truthy` CLAIMS the open, exactly the way
+ *                     `ManagedWindow.onMaximize` claims the maximise gesture.
+ *                     See `commit` for what it is for; omitted, the palette
+ *                     behaves as it always has. */
+export function createCommandPalette({ wm, api, taxonomy, catalog, placeholder = 'Search…',
+                                       onPick = null }) {
     if (!taxonomy) throw new Error('createCommandPalette: a taxonomy is required');
     if (!catalog)  throw new Error('createCommandPalette: an entity catalog is required');
     let overlay = null;
@@ -53,7 +58,7 @@ export function createCommandPalette({ wm, api, taxonomy, catalog, placeholder =
         overlay = document.createElement('div');
         overlay.id = ROOT_ID;
         overlay.className = 'twm-cmdpal-overlay';
-        overlay.innerHTML = _markup(taxonomy, placeholder);
+        overlay.innerHTML = _markup(taxonomy, placeholder, wm);
         document.body.appendChild(overlay);
         overlay.addEventListener('click', (e) => {
             if (e.target === overlay) close();
@@ -143,11 +148,50 @@ export function createCommandPalette({ wm, api, taxonomy, catalog, placeholder =
                 el.addEventListener('click', () => commit(Number(el.dataset.idx)));
             });
         };
+        /**
+         * ══ C30. THE PALETTE IS A DOOR, NOT A PLACEMENT POLICY ══════════
+         *
+         * `openInPrimary` is the wrong verb for a picked ENTITY and it was the
+         * only one here. It RESETS the primary leaf to a single fresh tab —
+         * its own doc says so, and says why: navigation from outside the tile
+         * is a page change, and a page change replaces the page. So picking a
+         * table from Ctrl+K threw away every other tab in that leaf, ignored
+         * whatever rule the embedder has about where its entities open (a tab
+         * beside its siblings, a floating window on a canvas pane, a split),
+         * and bypassed any per-mount-site bookkeeping the embedder keeps —
+         * for Tables, the grid registry keyed on `(mount site, table)`, which
+         * is what holds staged edits across a re-render.
+         *
+         * The result was a door that did something different from every other
+         * door onto the same object: the rail opened a table one way, the
+         * palette another, and only the palette destroyed work. Reported as
+         * "open table via Ctrl+K does not work" — which is exactly what it
+         * looks like from the outside when the tab you were in is replaced.
+         *
+         * The library cannot decide this. It does not know what a `table` is,
+         * which is the whole point of the injected taxonomy and catalogue. So
+         * the embedder is offered the pick and may CLAIM it, on the same
+         * contract as `ManagedWindow.onMaximize` (`managed_window.js:230`):
+         * return truthy and nothing else happens. Guarded, because a throwing
+         * embedder must not leave the palette closed over a half-done open —
+         * and unclaimed picks still land in the primary tile, so no existing
+         * embedder changes behaviour by upgrading.
+         *
+         * `pick` is the catalogue row verbatim (`{kind, id, label, hint,
+         * props?}`) rather than a re-shaped argument: the embedder wrote the
+         * `shape` that produced it, so it is the one party that can read it.
+         */
         const commit = (i) => {
             const pick = filtered[i];
             if (!pick) return;
             close();
             if (pick.action) { try { pick.action(); } catch (err) { console.error(err); } return; }
+            if (onPick) {
+                let handled = false;
+                try { handled = onPick(pick) ?? false; }
+                catch (err) { console.error('[cmdpal] onPick threw', err); }
+                if (handled) return;
+            }
             wm.openInPrimary(pick.kind, pick.props || { id: pick.id, label: pick.label });
         };
 
@@ -240,7 +284,29 @@ export function createCommandPalette({ wm, api, taxonomy, catalog, placeholder =
     return { open, close, toggle, isOpen };
 }
 
-function _markup(taxonomy, placeholder) {
+function _markup(taxonomy, placeholder, wm) {
+    // ONLY THE PANELS THIS SHELL CAN ACTUALLY SHOW.
+    //
+    // The three toggles were hardcoded, so the palette offered `panel:left` to
+    // an embedder that has no factory for it — and `togglePanel` then
+    // canonicalized a leaf whose only possible rendering is "no factory
+    // registered yet", permanently, because the renderer caches tile DOM per
+    // (kind, props). C14 closed that path at boot; this closes the other end of
+    // it. A panel with no factory is not a panel this shell can show, and the
+    // registry is the thing that knows.
+    const PANEL_CHIPS = [
+        { side: 'left',   icon: 'menu',            label: 'Left nav' },
+        { side: 'right',  icon: 'dock_to_left',    label: 'Right panel' },
+        { side: 'bottom', icon: 'dock_to_bottom',  label: 'Bottom panel' },
+    ];
+    const panelToggles = PANEL_CHIPS
+        .filter((p) => wm.content?.has?.(`panel:${p.side}`) !== false)
+        .map((p) => `
+                <button class="twm-chip" data-toggle="${p.side}">
+                    <span class="material-symbols-outlined">${p.icon}</span>
+                    ${p.label}
+                </button>`).join('');
+
     const chips = taxonomy.topNavEntries().map((k) => `
         <button class="twm-chip" data-shortcut="${k.kind}">
             <span class="material-symbols-outlined">${k.icon}</span>
@@ -256,20 +322,7 @@ function _markup(taxonomy, placeholder) {
                        autocomplete="off" />
             </div>
             <div class="twm-cmdpal__chips">${chips}</div>
-            <div class="twm-cmdpal__toggles">
-                <button class="twm-chip" data-toggle="left">
-                    <span class="material-symbols-outlined">menu</span>
-                    Left nav
-                </button>
-                <button class="twm-chip" data-toggle="right">
-                    <span class="material-symbols-outlined">dock_to_left</span>
-                    Right panel
-                </button>
-                <button class="twm-chip" data-toggle="bottom">
-                    <span class="material-symbols-outlined">dock_to_bottom</span>
-                    Bottom panel
-                </button>
-            </div>
+            <div class="twm-cmdpal__toggles">${panelToggles}</div>
             <div class="twm-cmdpal__list" data-role="list"></div>
             <div class="twm-cmdpal__footer">
                 <span><kbd>↑</kbd><kbd>↓</kbd> navigate</span>

package/src/tiling/desktops.js

@@ -10,6 +10,16 @@
 
 import { TileTree, makeLeaf } from './tile_tree.js';
 
+/** What a FRESH desktop's panel tiles start as, when the embedder says nothing.
+ *
+ *  C14. It is a DEFAULT, not a constant. An embedder whose navigator and
+ *  inspector are its own chrome OUTSIDE the WM root — an icon rail, say — has
+ *  no `panel:left` factory to mount, and every desktop it creates would open
+ *  with two "no factory registered yet" placeholders wedged either side of its
+ *  content. It cannot fix that after the fact: `wm.load()` canonicalizes the
+ *  panels in before it returns, and the renderer caches tile DOM per
+ *  (kind, props). The only place the answer can be given is here, before the
+ *  first desktop exists — which is what `panelDefaults` is for. */
 const DEFAULT_PANEL_STATE = {
     left: true,
     right: true,
@@ -25,7 +35,7 @@ const DEFAULT_PANEL_STATE = {
  * deliberately NO default: a silent 'home' fallback is the exact bug this
  * parameter exists to remove.
  */
-function _makeDesktop(label, seed) {
+function _makeDesktop(label, seed, panelDefaults = DEFAULT_PANEL_STATE) {
     const tree = new TileTree();
     tree.setRoot(makeLeaf(seed()));
     return {
@@ -33,20 +43,28 @@ function _makeDesktop(label, seed) {
         label,
         tree,
         windows: [],
-        // boot default: left + right + bottom all open. Names are
-        // assigned by wm._canonicalize via PANEL_TITLES.
-        panels: { ...DEFAULT_PANEL_STATE },
+        // Boot default: whatever the embedder asked for, left + right + bottom
+        // when it asked for nothing. Names are assigned by wm._canonicalize via
+        // PANEL_TITLES.
+        panels: { ...panelDefaults },
     };
 }
 
 export class DesktopManager {
-    /** @param {{seed: () => object}} opts  `seed` builds the root leaf. Required. */
-    constructor({ seed } = {}) {
+    /**
+     * @param {object}   opts
+     * @param {function} opts.seed           builds the root leaf. Required.
+     * @param {object}  [opts.panelDefaults] C14. Which panel tiles a fresh
+     *   desktop opens with, merged over `DEFAULT_PANEL_STATE`. Omitted, every
+     *   desktop opens with all three — today's behaviour, unchanged.
+     */
+    constructor({ seed, panelDefaults = null } = {}) {
         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.panelDefaults = { ...DEFAULT_PANEL_STATE, ...(panelDefaults || {}) };
+        this.desktops = [_makeDesktop('1', seed, this.panelDefaults)];
         this.activeIdx = 0;
     }
 
@@ -61,12 +79,14 @@ export class DesktopManager {
 
     ensureCount(n) {
         while (this.desktops.length < n) {
-            this.desktops.push(_makeDesktop(String(this.desktops.length + 1), this.seed));
+            this.desktops.push(_makeDesktop(
+                String(this.desktops.length + 1), this.seed, this.panelDefaults));
         }
     }
 
     addDesktop(label = null) {
-        const d = _makeDesktop(label || String(this.desktops.length + 1), this.seed);
+        const d = _makeDesktop(
+            label || String(this.desktops.length + 1), this.seed, this.panelDefaults);
         this.desktops.push(d);
         return d;
     }
@@ -84,15 +104,19 @@ export class DesktopManager {
         };
     }
 
-    static deserialize(blob, { seed } = {}) {
-        const m = new DesktopManager({ seed });
+    static deserialize(blob, { seed, panelDefaults = null } = {}) {
+        const m = new DesktopManager({ seed, panelDefaults });
         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 || {}) },
+            // A RESTORED desktop's own answer wins over the default: the user
+            // closed that panel, and re-opening it on every reload is the bug
+            // this merge order avoids. The default only fills a key the stored
+            // blob predates.
+            panels: { ...m.panelDefaults, ...(raw.panels || {}) },
         }));
         // Empty tree → seed with the taxonomy root so the desktop is usable.
         for (const d of m.desktops) {

package/src/tiling/keymap.js

@@ -28,10 +28,20 @@
  *
  * 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).
+ *
+ * ── It returns a disposer, and that is not decoration ──────────────────
+ * The listener is on `document` and is bound to ONE shell's `wm` and
+ * `palette`. An embedder that can build a second shell in the same page —
+ * Tables rebuilds its whole shell when you switch project, because every open
+ * tab names a table by id — would otherwise leave the first one's handler
+ * attached for ever. Two handlers is not "twice as responsive": `Ctrl+K`
+ * toggles the dead palette open and the live one closed in the same keystroke,
+ * and `Alt+W` closes a tile in a tree nobody can see. `createShell().dispose()`
+ * calls this.
  */
 
-export function installKeymap({ wm, palette }) {
-    document.addEventListener('keydown', (e) => {
+export function installKeymap({ wm, palette, ...opts } = {}) {
+    const onKeyDown = (e) => {
         const inField = e.target?.closest?.(
             'input, textarea, select, [contenteditable="true"]');
 
@@ -66,8 +76,15 @@ export function installKeymap({ wm, palette }) {
         // 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) {
+            // The selector is a CONFIG option, not a constant. An embedder that
+            // moves its sections out of the top bar — into an icon rail, say —
+            // would otherwise find F1..F8 silently doing nothing: the query
+            // returns an empty NodeList, `idx < btns.length` is false, and the
+            // handler falls through without a hint that anything is bound.
+            // Passing `navSelector` is how such an embedder keeps the keys.
             const btns = document.querySelectorAll(
-                '.twm-global-top-bar .twm-bar-center.twm-top-nav .twm-top-nav__btn');
+                opts.navSelector
+                || '.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();
@@ -152,5 +169,8 @@ export function installKeymap({ wm, palette }) {
         if (key.length === 1 && /[a-z]/.test(key) && !inField) {
             e.preventDefault();
         }
-    });
+    };
+
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
 }