feat(dashboard): auto-hide rail + reveal/dismiss + pin — the atomic interaction arc (#14654) (#14906)

* feat(dashboard): DockRail edge-tab affordance with executor-routed restore (#14654)

* refactor(dashboard): rebuild DockRail on container.Base + button.Base composition (#14654)

* feat(dashboard): auto-hide reveal/dismiss + pin escape — atomic interaction contract (#14660)

* fix(dashboard): embodied focus + dismiss paths, live-pane parking, fraction threading (#14660)

* fix(dashboard): reveal pane mirrors projectItem cascade — blueprint fallback + recoverable placeholder (#14660)

Author: neo-opus-grace

examples/dashboard/dock/MainContainer.mjs

@@ -8,33 +8,39 @@ import '../../../src/tab/Container.mjs'; // registers the `tab-container` ntype
 import '../../../src/toolbar/Base.mjs';  // registers the `toolbar` ntype used by the perspective toolbar
 
 /**
- * A representative dock-zone document (`neo.harness.dockZone.v1`): a horizontal split of a two-tab main zone and a
- * vertical side-split of two single-tab zones, over four items. The shape `Neo.dashboard.DockLayoutAdapter.project`
- * consumes — see its spec for the full contract. Used as the example's INITIAL committed document; the live document
- * advances on each splitter resize (see `MainContainer#dockModel`).
+ * A representative dock-zone document (`neo.harness.dockZone.v1`): an edge-zone root whose center is a
+ * horizontal split of a two-tab main zone and a vertical side-split of two single-tab zones, plus a
+ * right edge band holding a single-tab inspector zone — the auto-hide surface (committing
+ * `setItemAutoHidden` on an edge-band item collapses it to a `Neo.dashboard.DockRail` edge tab).
+ * The shape `Neo.dashboard.DockLayoutAdapter.project` consumes — see its spec for the full contract.
+ * Used as the example's INITIAL committed document; the live document advances on each commit
+ * (see `MainContainer#dockModel`).
  * @type {Object}
  */
 const initialDockModel = {
     schema: 'neo.harness.dockZone.v1',
     root  : 'root',
     items : {
-        strategy: {componentRef: 'Strategy', title: 'Strategy', kind: 'panel'},
-        swarm   : {componentRef: 'Swarm',    title: 'Swarm',    kind: 'panel'},
-        terminal: {componentRef: 'Terminal', title: 'Terminal', kind: 'terminal'},
-        logs    : {componentRef: 'Logs',     title: 'Logs',     kind: 'panel'}
+        strategy : {componentRef: 'Strategy',  title: 'Strategy',  kind: 'panel'},
+        swarm    : {componentRef: 'Swarm',     title: 'Swarm',     kind: 'panel'},
+        terminal : {componentRef: 'Terminal',  title: 'Terminal',  kind: 'terminal'},
+        logs     : {componentRef: 'Logs',      title: 'Logs',      kind: 'panel'},
+        inspector: {componentRef: 'Inspector', title: 'Inspector', kind: 'panel'}
     },
     nodes: {
-        root           : {type: 'split', orientation: 'horizontal', children: ['main-tabs', 'side-split'], sizes: [0.65, 0.35]},
-        'main-tabs'    : {type: 'tabs',  items: ['strategy', 'swarm'], activeItemId: 'strategy'},
-        'side-split'   : {type: 'split', orientation: 'vertical', children: ['terminal-tabs', 'logs-tabs'], sizes: [0.6, 0.4]},
-        'terminal-tabs': {type: 'tabs',  items: ['terminal'], activeItemId: 'terminal'},
-        'logs-tabs'    : {type: 'tabs',  items: ['logs'],     activeItemId: 'logs'}
+        root            : {type: 'edge-zone', zones: {center: 'root-split', right: 'inspector-tabs'}},
+        'root-split'    : {type: 'split', orientation: 'horizontal', children: ['main-tabs', 'side-split'], sizes: [0.65, 0.35]},
+        'main-tabs'     : {type: 'tabs',  items: ['strategy', 'swarm'], activeItemId: 'strategy'},
+        'side-split'    : {type: 'split', orientation: 'vertical', children: ['terminal-tabs', 'logs-tabs'], sizes: [0.6, 0.4]},
+        'terminal-tabs' : {type: 'tabs',  items: ['terminal'],  activeItemId: 'terminal'},
+        'logs-tabs'     : {type: 'tabs',  items: ['logs'],      activeItemId: 'logs'},
+        'inspector-tabs': {type: 'tabs',  items: ['inspector'], activeItemId: 'inspector'}
     }
 };
 
 const reviewDockModel = DockZoneModel.clone(initialDockModel);
 
-reviewDockModel.nodes.root.sizes = [0.48, 0.52];
+reviewDockModel.nodes['root-split'].sizes = [0.48, 0.52];
 reviewDockModel.nodes['main-tabs'].activeItemId = 'swarm';
 reviewDockModel.nodes['side-split'].sizes = [0.42, 0.58];
 

resources/scss/src/dashboard/Container.scss

@@ -14,3 +14,63 @@
         cursor: ns-resize;
     }
 }
+
+// Demo-consumable minimal hooks only — the real visual language lands with the F-tranche.
+// Flow direction comes from the rail's layout (vbox/vertical, hbox/horizontal edges); the
+// buttons bring their own base theming — these hooks only shape the strip.
+.neo-dashboard-dock-edge-rail {
+    flex-shrink: 0;
+    gap        : 2px;
+
+    &-left,
+    &-right {
+        width: 14px;
+
+        .neo-dashboard-dock-rail-tab {
+            writing-mode: vertical-rl;
+        }
+    }
+
+    &-top,
+    &-bottom {
+        height: 14px;
+    }
+}
+
+.neo-dashboard-dock-rail-tab {
+    font-size: 11px;
+    padding  : 4px 1px;
+}
+
+.neo-dashboard-dock-edge-band {
+    &-left,
+    &-right {
+        width: 280px;
+    }
+
+    &-top,
+    &-bottom {
+        height: 200px;
+    }
+}
+
+.neo-dashboard-dock-reveal-overlay {
+    --neo-dock-reveal-ms : 200ms;
+    --neo-dock-dismiss-ms: 160ms;
+
+    position: absolute;
+    z-index : 20;
+
+    &-hidden {
+        display: none;
+    }
+
+    &-left   { inset: 0 auto 0 14px; }
+    &-right  { inset: 0 14px 0 auto; }
+    &-top    { inset: 14px 0 auto 0; }
+    &-bottom { inset: auto 0 14px 0; }
+}
+
+.neo-dashboard-dock-reveal-header {
+    gap: 4px;
+}

src/dashboard/DockLayoutAdapter.mjs

@@ -1,4 +1,5 @@
 import Base            from '../core/Base.mjs';
+import DockRail        from './DockRail.mjs';
 import DockSplitter    from './DockSplitter.mjs';
 import DockTabSortZone from './DockTabSortZone.mjs';
 import DockZoneModel   from './DockZoneModel.mjs';
@@ -208,6 +209,8 @@ class DockLayoutAdapter extends Base {
 
         return this.projectNode(model.root, {
             applyDockZoneOperation  : options.applyDockZoneOperation,
+            autoHideRevealOnHover   : options.autoHideRevealOnHover === true,
+            defaultRevealFraction   : Number.isFinite(options.defaultRevealFraction) ? options.defaultRevealFraction : null,
             dockZoneDocument        : options.dockZoneDocument || model,
             items                   : model.items || {},
             nodes                   : model.nodes,
@@ -257,10 +260,12 @@ class DockLayoutAdapter extends Base {
     }
 
     /**
-     * Projects one auto-hidden item id into a collapsed rail-tab affordance.
+     * Projects one auto-hidden item id into the rail-tab metadata `DockRail` renders.
      *
-     * The rail tab carries stable `dockItemId` + `dockEdge` metadata so a later reveal/pin slice
-     * can convert a click into a transient reveal or a `setItemPinned` operation.
+     * The metadata carries stable `dockItemId` + `dockEdge` so the rail's click (and the follow-up
+     * reveal/pin slice) can address the item semantically, plus the `restorable` policy projection
+     * (`pinnable !== false`) — a tab whose restore the model would reject renders disabled instead
+     * of lying about the affordance.
      * No DOMRect, hover, or open geometry is emitted — reveal/open state stays runtime-only per the
      * JSON-first guardrail (HarnessDockZoneModel.md §Serializable vs Runtime).
      * @param {String} itemId
@@ -274,18 +279,21 @@ class DockLayoutAdapter extends Base {
         let item = context.items[itemId] || {};
 
         return {
-            cls         : ['neo-dashboard-dock-rail-tab'],
-            data        : {dockEdge: edge, dockItemId: itemId, dockRailTab: true},
-            dockEdge    : edge,
-            dockItemId  : itemId,
-            dockNodeType: 'edge-rail-tab',
-            ntype       : 'button',
-            text        : item.title || itemId
+            dockEdge  : edge,
+            dockItemId: itemId,
+            restorable: item.pinnable !== false,
+            title     : item.title || itemId
         }
     }
 
     /**
-     * Projects a set of auto-hidden item ids into a thin edge-rail strip for the owning edge.
+     * Projects a set of auto-hidden item ids into a `Neo.dashboard.DockRail` affordance for the
+     * owning edge.
+     *
+     * Mirrors `createSplitterAffordance()`: the reducer callbacks thread from projection context into
+     * the component so restore commits ride the workspace's single operation path — no parallel
+     * mutation grammar. Rail extent and tab writing-mode are CSS concerns keyed off the per-edge cls
+     * hook (JSON-first: no pixel geometry in the projection).
      * @param {String[]} itemIds
      * @param {String} edge One of `top`, `right`, `bottom`, `left`.
      * @param {Object} context
@@ -294,16 +302,75 @@ class DockLayoutAdapter extends Base {
      * @static
      */
     static createEdgeRail(itemIds, edge, context) {
-        let isVertical = edge === 'left' || edge === 'right';
-
         return {
-            cls         : ['neo-dashboard-dock-edge-rail', `neo-dashboard-dock-edge-rail-${edge}`],
-            dockEdge    : edge,
-            dockNodeType: 'edge-rail',
-            items       : itemIds.map(itemId => this.createRailTab(itemId, edge, context)),
-            layout      : {ntype: isVertical ? 'vbox' : 'hbox', align: 'start'},
-            ntype       : 'container'
+            applyDockZoneOperation  : context.applyDockZoneOperation,
+            autoHideRevealOnHover   : context.autoHideRevealOnHover === true,
+            defaultRevealFraction   : context.defaultRevealFraction ?? null,
+            dockEdge                : edge,
+            dockNodeType            : 'edge-rail',
+            dockZoneDocument        : context.dockZoneDocument,
+            edge,
+            module                  : DockRail,
+            ntype                   : 'dashboard-dock-rail',
+            onDockZoneDocumentChange: context.onDockZoneDocumentChange,
+            railItems               : itemIds.map(itemId => this.createRailTab(itemId, edge, context)),
+            resolveComponentRef     : context.resolveComponentRef
+        }
+    }
+
+    /**
+     * Resolves the reveal overlay's free-dimension extent for an item: the share its owning
+     * subtree holds at the nearest ancestor split, per that split's committed `sizes` — the
+     * "last committed extent, still in the document" rule. Returns `null` when no ancestor split
+     * carries usable sizes (e.g. a tabs node sitting directly in an edge-zone slot); the overlay
+     * then falls back to its workspace-configurable default fraction. Never reads DOM geometry.
+     * @param {Object} model Committed dock-zone document.
+     * @param {String} itemId
+     * @returns {Number|null} Fraction in `(0, 1]`, or `null`.
+     * @static
+     */
+    static resolveRevealExtent(model, itemId) {
+        let nodes   = model?.nodes || {},
+            childId = Object.keys(nodes).find(nodeId =>
+                nodes[nodeId].type === 'tabs' && (nodes[nodeId].items || []).includes(itemId)),
+            parent;
+
+        const findParent = id => {
+            for (const [nodeId, node] of Object.entries(nodes)) {
+                if (node.type === 'split' && (node.children || []).includes(id)) {
+                    return {index: node.children.indexOf(id), nodeId, split: true}
+                }
+                if (node.type === 'edge-zone' && Object.values(node.zones || {}).includes(id)) {
+                    return {nodeId, split: false}
+                }
+            }
+            return null
+        };
+
+        while (childId) {
+            parent = findParent(childId);
+
+            if (!parent) {
+                return null
+            }
+
+            if (parent.split) {
+                let sizes = nodes[parent.nodeId].sizes;
+
+                if (Array.isArray(sizes) && sizes.length) {
+                    let total = sizes.reduce((sum, value) => sum + (Number(value) || 0), 0),
+                        share = Number(sizes[parent.index]);
+
+                    return total > 0 && Number.isFinite(share) && share > 0 ? share / total : null
+                }
+
+                return null
+            }
+
+            childId = parent.nodeId
         }
+
+        return null
     }
 
     /**
@@ -340,20 +407,27 @@ class DockLayoutAdapter extends Base {
         // Pass the railed set down so projectTabsNode drops those items from the tab flow.
         let childContext = railedItemIds.size ? {...context, railedItemIds} : context,
             middleItems  = [],
-            rows         = [];
+            rows         = [],
+            centerConfig;
 
         if (railsByEdge.left)  middleItems.push(this.createEdgeRail(railsByEdge.left, 'left', context));
-        if (zones.left)        middleItems.push(this.projectNode(zones.left, childContext));
-        if (zones.center)      middleItems.push(this.projectNode(zones.center, childContext));
-        if (zones.right)       middleItems.push(this.projectNode(zones.right, childContext));
+        if (zones.left)        middleItems.push(this.projectEdgeBand(zones.left, 'left', childContext));
+
+        if (zones.center) {
+            centerConfig      = this.projectNode(zones.center, childContext);
+            centerConfig.flex = 1;
+            middleItems.push(centerConfig)
+        }
+
+        if (zones.right)       middleItems.push(this.projectEdgeBand(zones.right, 'right', childContext));
         if (railsByEdge.right) middleItems.push(this.createEdgeRail(railsByEdge.right, 'right', context));
 
         if (railsByEdge.top) {
             rows.push(this.createEdgeRail(railsByEdge.top, 'top', context))
         }
 
         if (zones.top) {
-            rows.push(this.projectNode(zones.top, childContext))
+            rows.push(this.projectEdgeBand(zones.top, 'top', childContext))
         }
 
         if (middleItems.length === 1) {
@@ -369,7 +443,7 @@ class DockLayoutAdapter extends Base {
         }
 
         if (zones.bottom) {
-            rows.push(this.projectNode(zones.bottom, childContext))
+            rows.push(this.projectEdgeBand(zones.bottom, 'bottom', childContext))
         }
 
         if (railsByEdge.bottom) {
@@ -386,6 +460,26 @@ class DockLayoutAdapter extends Base {
         }
     }
 
+    /**
+     * Marks an edge-band zone projection: bands keep a fixed cross-extent (the
+     * `neo-dashboard-dock-edge-band(-edge)` CSS hooks) instead of flexing against the center —
+     * an unsized band silently eats workspace geometry the center owns.
+     * @param {String} zoneId
+     * @param {String} edge One of `top`, `right`, `bottom`, `left`.
+     * @param {Object} context
+     * @returns {Object}
+     * @protected
+     * @static
+     */
+    static projectEdgeBand(zoneId, edge, context) {
+        let config = this.projectNode(zoneId, context);
+
+        config.cls  = [...(config.cls || []), 'neo-dashboard-dock-edge-band', `neo-dashboard-dock-edge-band-${edge}`];
+        config.flex = 'none';
+
+        return config
+    }
+
     /**
      * Projects one dock item id into a Neo config or recoverable placeholder.
      * @param {String} itemId