@wildo-ai/saas-frontend-lib 1.1.1 → 1.1.3

package/dist/esm/core/navigation/NavigationContentAreas.js

@@ -10,14 +10,19 @@ import React, { useCallback, useMemo, useRef, useState, useEffect } from 'react'
 import { useNavigate } from 'react-router-dom';
 import { NavigationZoneName, OverlayAppearance, } from '@wildo-ai/saas-models';
 import { ViewportBreakpoint, DisplayDirection } from '@wildo-ai/zod-decorators';
+import { NavigationZoneContentModel } from '@wildo-ai/saas-models';
 import { useNavigationState } from './useNavigationState.js';
-import { useNavigationController, useSettingsHubOverlaySync, useStructuralZoneBackForwardSync } from './useNavigationController.js';
+import { NavigationUtils } from './navigation.utils.js';
+import { useHostedPaneRouteSync, useNavigationController, useSettingsHubOverlaySync, useStructuralZoneBackForwardSync } from './useNavigationController.js';
 import { NavigationZone, NavigationContentType } from './navigation.schemas.js';
 import { CorePresetNames, FrontendComponentType, PlacementSide, ShellAppearance, SurfaceVariant } from '@wildo-ai/presets-components-models';
 import { useUI } from '../../core/ui/useUI.js';
 import { useI18n } from '../../core/i18n/useI18n.js';
+import { resolveComponentLabel } from '../../core/i18n/component-label-resolution.utils.js';
 import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
 import { useOverlayTitle } from './useOverlayTitle.js';
+import { resolveVisibleEntryIndex } from './zone-visible-entry.js';
+import { Tabs, TabsList, TabsTrigger } from '../../components/sections/tabs.js';
 import { ResourceOperationSurface } from '../../components/resources/ResourceOperationSurface.js';
 import { FullCustomView } from '../../components/views/full-custom-view/FullCustomView.js';
 import { FlowsActorsView } from '../../components/views/flows-actors-view/FlowsActorsView.js';
@@ -37,7 +42,11 @@ import { ComponentNotInjected } from '../../core/components-registry/ComponentNo
 import { FeatureRouteGuard } from '../../core/features/FeatureRouteGuard.js';
 import { resolveInsertedChartView } from '../../core/config/chart-view.frontend.schemas.js';
 import { Surface } from '../../components/sections/surface.js';
+import { cn } from '../../core/ui/cn.js';
 import { NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE } from '../../core/ui/surface-a11y.utils.js';
+import { resolvePrimaryDestinationAdjacentZoneOnEmpty, resolveZoneEmptyBehavior, zoneOccupiesSpaceWhenEmpty, } from './zone-empty-behavior.js';
+import { resolveAdjacentZoneContentGeometry, resolvePrimaryZoneContentGeometry, zoneContentGeometryToBoundaryClassName, zoneContentGeometryToPolicyOverride, } from './zone-content-geometry.js';
+import { primaryDestinationDeclarationIsKnown } from './primary-destination-layout.js';
 const logger = LoggerFrontendService.getLogger();
 const logDebug = logger.debugByType('NavigationContentAreas');
 logger.setDebugTypeLogging('NavigationContentAreas', false);
@@ -153,6 +162,23 @@ export const NavigationContentRenderer = ({ content, zone, initiator, entryId })
     }
     return null;
 };
+/**
+ * The tab bar of a `NavigationZoneContentModel.TABBED` zone — one trigger per stack entry.
+ *
+ * A label needs `useOverlayTitle`, which is a hook, so each trigger is its own component rather than
+ * a `.map` in the parent: calling a hook per entry inside a map breaks the rules of hooks the moment
+ * the stack length changes, which for a tabbed zone is every tab open and close.
+ *
+ * `useOverlayTitle` rather than a bespoke label derivation, because an overlay title and a tab label
+ * answer the same question — "what is this entry?" — and a second derivation would drift from the
+ * first for exactly the entries (composite views, engine pages) whose titles are hardest to get
+ * right.
+ */
+const ZoneTabTrigger = ({ entry }) => {
+    const { title } = useOverlayTitle(entry);
+    return _jsx(TabsTrigger, { value: entry.id, children: title });
+};
+const ZoneTabBar = ({ zone, entries, activeEntryId, onSelect }) => (_jsx(Tabs, { value: activeEntryId, onValueChange: (entryId) => onSelect(zone, entryId), "data-zone-tab-bar": zone, children: _jsx(TabsList, { children: entries.map(entry => _jsx(ZoneTabTrigger, { entry: entry }, entry.id)) }) }));
 /**
  * Render a zone's content using **persistent stack rendering**.
  *
@@ -161,46 +187,48 @@ export const NavigationContentRenderer = ({ content, zone, initiator, entryId })
  * data on back-navigation. The top entry uses `display: contents` to avoid
  * an extra wrapper div that could break flex/grid layouts.
  *
- * -- Tabbed Mode (future -- not yet implemented) --
- *
- * When NavigationTransition.TAB is used, this component will need to:
- *
- * 1. **Detect tab entries:** Partition `zoneState.stack` into two groups:
- *    - TAB entries: entries pushed via NavigationTransition.TAB (parallel)
- *    - Stack entries: entries pushed via PUSH on top of the active tab (depth)
- *
- * 2. **Render tab bar:** For TAB entries, render a horizontal tab bar.
- *    Each tab shows a label derived from the entry's resource type + operation.
- *    The active tab is determined by `zoneState.activeTabId`.
+ * -- Tabbed mode (`NavigationZoneContentModel.TABBED`) --
  *
- * 3. **Render content:** Below the tab bar, render the active tab's content.
- *    If there are PUSH entries on top of the active tab, render the topmost.
+ * A zone whose declared content model is `TABBED` renders the SAME persistent stack with a tab bar
+ * above it: every entry is a parallel tab, all are mounted, and `NavigationZoneState.activeTabId`
+ * says which one is visible. That is the whole difference — in `SINGLE` the top entry is visible and
+ * back pops; in `TABBED` the ACTIVE entry is visible and the others are one click away.
  *
- * 4. **Tab interactions:**
- *    - Tab click → update `activeTabId` on zone state + URL update in transaction
- *    - Tab close → emit NAVIGATION_CLOSE with entryId → adjust activeTabId
- *    - Last tab closed → zone becomes empty (existing behavior)
+ * Until 2026-09-08 (#411) `TABBED` was declared in the vocabulary, documented as "parallel tabs, tab
+ * bar visible", validated by the layout schema, **selected by one of the framework's own shipped
+ * presets** — and rendered as an ordinary single stack, with no error. Nothing ever wrote
+ * `activeTabId`; nothing ever read it.
  *
- * 5. **URL coordination:**
- *    - Only the active tab is URL-addressable
- *    - Tab switch wraps in NavigationTransaction to suppress useRouterSync
- *    - On refresh, only the active tab is reconstructed (other tabs are lost)
+ * Key invariant, unchanged: a tabbed zone is FLAT. Depth navigation within a tab goes to the NEXT
+ * zone or to an overlay, which is what keeps this from becoming tab-within-tab.
  *
- * 6. **Zone collapse interaction:**
- *    - Single-zone + TAB → tabs render within PRIMARY (via zone collapse redirect)
- *    - Primary context change → all tabs in dependent zone cleared (zone cleanup)
+ * NOT done here, deliberately, because each is its own decision rather than part of rendering:
+ * per-tab URL addressability (only the active tab has an address today, so a refresh reconstructs
+ * one tab), and a per-tab close affordance (`NAVIGATION_CLOSE` already exists; what a tabbed zone
+ * should do when its LAST tab closes is a `ZoneEmptyBehavior` question).
  *
- * Key invariant: A tabbed zone is FLAT. Depth navigation within a tab goes
- * to the NEXT zone or overlay. This prevents nested tab-within-tab complexity.
+ * An earlier version of this note described the work in terms of `NavigationTransition.TAB`. There
+ * is no such transition and there never was — the content MODEL is what decides, and a transition
+ * that does not exist cannot be partitioned on.
  *
  * @see NavigationZoneState.activeTabId
- * @see NavigationTransition.TAB
- * @see Section 11 (Gap M7) in navigation-deep-analysis.md
  */
-const ZoneContentRenderer = ({ zone, fallback }) => {
-    const { getTopEntry, getZoneState } = useNavigationState();
+const ZoneContentRenderer = ({ zone, fallback, emptyState }) => {
+    const { getTopEntry, getZoneState, setActiveTab } = useNavigationState();
+    const { navigationLayout } = useUI();
     const topEntry = getTopEntry(zone);
     const zoneState = getZoneState(zone);
+    /*
+     * The zone's DECLARED content model decides between the two renderings. Read here rather than
+     * threaded from the seven call sites: it is a property of the zone, all seven would pass the same
+     * value derived from the same layout, and a prop is one more place for them to disagree.
+     */
+    const isTabbed = navigationLayout?.zones?.[zone]?.contentModel === NavigationZoneContentModel.TABBED;
+    /*
+     * Which entry shows. `SINGLE` -> the top; `TABBED` -> the active tab. Owned by one named pure
+     * function so the distinction can be pinned, which is precisely what `TABBED` never had.
+     */
+    const visibleEntryIndex = resolveVisibleEntryIndex(zoneState.stack, navigationLayout?.zones?.[zone]?.contentModel, zoneState.activeTabId);
     logDebug('ZoneContentRenderer render', {
         zone,
         hasTopEntry: !!topEntry,
@@ -213,33 +241,70 @@ const ZoneContentRenderer = ({ zone, fallback }) => {
     const stack = zoneState.stack;
     if (stack.length > 0) {
         logDebug('ZoneContentRenderer → rendering persistent stack', { zone, stackDepth: stack.length });
-        return (_jsx(_Fragment, { children: stack.map((entry, index) => {
-                const isTop = index === stack.length - 1;
-                return (_jsx("div", { style: { display: isTop ? 'contents' : 'none' }, 
-                    // Non-top stack entries stay mounted (to preserve their state
-                    // across depth navigation) but must be hidden from both layout
-                    // and assistive technology. We use `inert` rather than
-                    // `aria-hidden` here: when a user activates a focusable element
-                    // in the top entry (e.g. clicks a list card to drill in), that
-                    // element keeps DOM focus while the OUTGOING entry re-renders as
-                    // non-top. Applying `aria-hidden` to an ancestor that still
-                    // contains the focused node triggers the browser's
-                    // "Blocked aria-hidden on an element because its descendant
-                    // retained focus" violation. `inert` is the spec-recommended
-                    // fix: it hides the subtree from AT AND actively moves focus out
-                    // of it (blurring any focused descendant), so no focused node is
-                    // ever left inside a hidden ancestor. React 19 renders the
-                    // boolean `inert` prop as the native HTML attribute.
-                    inert: !isTop, children: _jsx(NavigationContentRenderer, { content: entry.content, zone: entry.zone, initiator: entry.initiator, entryId: entry.id }) }, getContentKey(entry.content, entry.id)));
-            }) }));
+        return (_jsxs(_Fragment, { children: [isTabbed && stack.length > 0 && (_jsx(ZoneTabBar, { zone: zone, entries: stack, activeEntryId: stack[visibleEntryIndex]?.id, onSelect: setActiveTab })), stack.map((entry, index) => {
+                    /*
+                     * "Which entry is showing" is the ONE thing the two content models answer differently.
+                     * Everything below — the persistent mount, `display: contents` on the visible entry,
+                     * `inert` on the rest — is shared, because a tab that unmounted when you left it would
+                     * refetch on every switch, which is the behaviour tabs exist to avoid.
+                     */
+                    const isTop = index === visibleEntryIndex;
+                    return (_jsx("div", { style: { display: isTop ? 'contents' : 'none' }, 
+                        // Non-top stack entries stay mounted (to preserve their state
+                        // across depth navigation) but must be hidden from both layout
+                        // and assistive technology. We use `inert` rather than
+                        // `aria-hidden` here: when a user activates a focusable element
+                        // in the top entry (e.g. clicks a list card to drill in), that
+                        // element keeps DOM focus while the OUTGOING entry re-renders as
+                        // non-top. Applying `aria-hidden` to an ancestor that still
+                        // contains the focused node triggers the browser's
+                        // "Blocked aria-hidden on an element because its descendant
+                        // retained focus" violation. `inert` is the spec-recommended
+                        // fix: it hides the subtree from AT AND actively moves focus out
+                        // of it (blurring any focused descendant), so no focused node is
+                        // ever left inside a hidden ancestor. React 19 renders the
+                        // boolean `inert` prop as the native HTML attribute.
+                        inert: !isTop, children: _jsx(NavigationContentRenderer, { content: entry.content, zone: entry.zone, initiator: entry.initiator, entryId: entry.id }) }, getContentKey(entry.content, entry.id)));
+                })] }));
     }
     if (fallback) {
         logDebug('ZoneContentRenderer → rendering fallback (routerChildren / Outlet)', { zone });
         return _jsx(_Fragment, { children: fallback });
     }
+    if (emptyState) {
+        logDebug('ZoneContentRenderer → rendering empty state (onEmpty: EMPTY_STATE)', { zone });
+        return _jsx(_Fragment, { children: emptyState });
+    }
     logDebug('ZoneContentRenderer → rendering null (no entry, no fallback)', { zone });
     return null;
 };
+/**
+ * Translate a split's DIVIDER orientation into the panel group's STACKING AXIS.
+ *
+ * The two vocabularies are exact opposites, and nothing translated between them until #174 rendered
+ * the resizable branch for the first time — so a layout asking for a side panel got a bottom one.
+ *
+ * `SplitConfig.orientation` names the DIVIDER, which is what its schema `@example` documents:
+ *
+ *     orientation: DisplayDirection.VERTICAL,    // side-by-side
+ *     orientation: DisplayDirection.HORIZONTAL,  // bottom panel
+ *
+ * `react-resizable-panels`' `direction` names the STACKING AXIS: `'vertical'` stacks panels top over
+ * bottom (`flex-col`), `'horizontal'` places them side by side. So a vertical divider is a HORIZONTAL
+ * panel group, and passing `orientation` through unchanged inverts every split in the framework.
+ *
+ * Every shipped preset was already authored under the divider convention and is therefore correct;
+ * this is why the fix belongs at the boundary rather than in five preset files. It was invisible
+ * because the only branch that reads `orientation` is the resizable one, and no layout in the
+ * repository declared `resizable: true` on a zone any running application used — the STATIC branch
+ * ignores orientation entirely and lays panels out with `flex` + width percentages, which is
+ * side-by-side unconditionally and therefore accidentally right.
+ */
+export function splitDividerOrientationToPanelGroupDirection(orientation) {
+    return orientation === DisplayDirection.HORIZONTAL
+        ? DisplayDirection.VERTICAL
+        : DisplayDirection.HORIZONTAL;
+}
 /**
  * Fallback reference width when the container hasn't been measured yet.
  * Only used on the very first render before ResizeObserver fires.
@@ -287,7 +352,23 @@ function useContainerWidth(ref) {
  *
  * PRIMARY always gets the remaining space (100% - sum of side panels).
  */
-function computePanelSizes(zones, split, showSecondary, showCompanion, containerWidth) {
+/**
+ * Reconcile a panel's ratio-derived default with its pixel-derived bounds.
+ *
+ * `ratio` is a PERCENTAGE of the container and `minWidth`/`maxWidth` are PIXELS, so the two are only
+ * consistent at one container width. Narrow the window and a fixed pixel floor becomes a larger and
+ * larger share — the workbench's `minWidth: 380` against a 42% default crosses over at roughly 900px
+ * and, below that, asks a panel to open SMALLER than its own minimum.
+ *
+ * Nothing downstream can resolve that: `defaultSize < minSize` is a contradiction the panel library is
+ * handed rather than a preference it can honour. Clamping here keeps the declaration meaningful — the
+ * pane opens at its ratio where there is room, and at its floor where there is not — and keeps
+ * `usedPercent` honest, since primary's share is whatever is actually left.
+ */
+function clampDefaultWithinBounds(defaultSize, minSize, maxSize) {
+    return Math.min(Math.max(defaultSize, Math.min(minSize, maxSize)), maxSize);
+}
+export function computePanelSizes(zones, split, showSecondary, showCompanion, containerWidth) {
     let usedPercent = 0;
     let secondary;
     if (showSecondary) {
@@ -298,11 +379,33 @@ function computePanelSizes(zones, split, showSecondary, showCompanion, container
         usedPercent += defaultSize;
         const minPx = zone?.minWidth;
         const maxPx = zone?.maxWidth;
+        const secondaryMin = isResizable && minPx ? pxToPercent(minPx, containerWidth) : defaultSize;
+        const secondaryMax = isResizable && maxPx ? pxToPercent(maxPx, containerWidth) : defaultSize;
+        const secondaryDefault = clampDefaultWithinBounds(defaultSize, secondaryMin, secondaryMax);
+        usedPercent += secondaryDefault - defaultSize;
         secondary = {
-            defaultSize,
-            minSize: isResizable && minPx ? pxToPercent(minPx, containerWidth) : defaultSize,
-            maxSize: isResizable && maxPx ? pxToPercent(maxPx, containerWidth) : defaultSize,
-            collapsible: isResizable,
+            defaultSize: secondaryDefault,
+            minSize: secondaryMin,
+            maxSize: secondaryMax,
+            /*
+             * A zone that declares a MINIMUM WIDTH is asking for a FLOOR, so it must not also be
+             * collapsible — `react-resizable-panels` treats `minSize` on a collapsible panel as a SNAP
+             * THRESHOLD rather than a limit, and a drag past it jumps to `collapsedSize` instead of
+             * stopping.
+             *
+             * Measured before this gate existed: the workbench declared `minWidth: 380` and a drag inward
+             * ran straight past it to 48px — the content area's own padding around a zero-width panel. The
+             * `maxWidth` side held at 725 (its 48% of a 1512px container), so the declaration was honoured
+             * in one direction and silently ignored in the other.
+             *
+             * Collapsing is also a state nothing else in the navigation model has: the zone still HOLDS its
+             * content and still owns the URL, it is merely invisible — which is not `onEmpty`, and not
+             * something a reader can undo except by finding the handle again.
+             *
+             * A zone that declares no minimum keeps drag-to-collapse, which is a reasonable affordance when
+             * no floor was asked for.
+             */
+            collapsible: isResizable && !minPx,
             collapsedSize: 0,
             frozen: !isResizable,
         };
@@ -317,11 +420,16 @@ function computePanelSizes(zones, split, showSecondary, showCompanion, container
         usedPercent += defaultSize;
         const minPx = zone?.minWidth;
         const maxPx = zone?.maxWidth;
+        const companionMin = isResizable && minPx ? pxToPercent(minPx, containerWidth) : defaultSize;
+        const companionMax = isResizable && maxPx ? pxToPercent(maxPx, containerWidth) : defaultSize;
+        const companionDefault = clampDefaultWithinBounds(defaultSize, companionMin, companionMax);
+        usedPercent += companionDefault - defaultSize;
         companion = {
-            defaultSize,
-            minSize: isResizable && minPx ? pxToPercent(minPx, containerWidth) : defaultSize,
-            maxSize: isResizable && maxPx ? pxToPercent(maxPx, containerWidth) : defaultSize,
-            collapsible: isResizable,
+            defaultSize: companionDefault,
+            minSize: companionMin,
+            maxSize: companionMax,
+            /* See the secondary zone above: a declared minimum is a floor, and a floor cannot collapse. */
+            collapsible: isResizable && !minPx,
             collapsedSize: 0,
             frozen: !isResizable,
         };
@@ -349,7 +457,7 @@ function computePanelSizes(zones, split, showSecondary, showCompanion, container
     return { primaryDefault, secondary, companion };
 }
 /**
- * Page-content width cap for the PRIMARY zone. Wraps primary content in a
+ * Page-content width cap for a structural zone. Wraps the zone's content in a
  * chromeless SHELL surface carrying `responsiveMaxWidth: 'content'`, so wide
  * viewports cap + center primary content at `var(--content-max-width, 80rem)`
  * instead of stretching forms / lists / composites edge-to-edge. Inert below
@@ -368,8 +476,8 @@ const PRIMARY_CONTENT_WIDTH_POLICY_OVERRIDE = {
     geometry: { responsiveMaxWidth: 'content' },
     containment: { gap: 'none' },
 };
-function PrimaryContentWidthBoundary({ children }) {
-    return (_jsx(Surface, { variant: SurfaceVariant.SHELL, emitPolicyVars: true, policyOverride: PRIMARY_CONTENT_WIDTH_POLICY_OVERRIDE, 
+function ZoneContentWidthBoundary({ children, geometry }) {
+    return (_jsx(Surface, { variant: SurfaceVariant.SHELL, emitPolicyVars: true, policyOverride: zoneContentGeometryToPolicyOverride(geometry, PRIMARY_CONTENT_WIDTH_POLICY_OVERRIDE), 
         // Policy and appearance are separate channels: `Surface` ALWAYS composes the
         // variant's visual recipe, and SHELL's is the raised content slab
         // (`bg-surface-raised text-surface-raised-foreground`). This wrapper is
@@ -380,8 +488,43 @@ function PrimaryContentWidthBoundary({ children }) {
         // `twMerge(clsx(…))`, so these deterministically drop the recipe's pair
         // rather than relying on stylesheet order. `text-inherit` keeps the ambient
         // foreground, which is the right one under either appearance.
-        className: "bg-transparent text-inherit", children: children }));
+        className: cn('bg-transparent text-inherit', zoneContentGeometryToBoundaryClassName(geometry)), children: children }));
 }
+/**
+ * The placeholder a RESERVED-but-empty adjacent zone shows (`onEmpty: EMPTY_STATE`).
+ *
+ * Deliberately quiet and centered: the pane is present so the layout does not reflow between
+ * selections, so it must read as "waiting" rather than competing with the content beside it for
+ * attention. The wording is an i18n label, not a literal — the pane is engine chrome that ships in
+ * every application, and "Select an item to view details" is exactly the kind of English that has no
+ * business being hard-coded in a framework.
+ *
+ * `isReady` gates the text rather than the element: rendering the box immediately keeps the panel
+ * geometry stable while the bundle resolves, which is the whole promise of EMPTY_STATE.
+ *
+ * The label resolves through `resolveComponentLabel`, NOT `tComponent` directly. `tComponent` returns
+ * the KEY PATH on a miss — deliberately, so a missing label is visible in development — and rendering
+ * that straight into the DOM puts `components.APP_LAYOUTS_MAIN_CONTAINER.zoneEmptyState` on the
+ * reader's screen. That is exactly the defect `component-label-resolution.utils` was written for after
+ * it shipped on the 404 page, and this was the eleventh site to make it: a brand-new engine label has
+ * no translation in any application's bundle until the labelling pipeline regenerates, so the miss is
+ * the DEFAULT state rather than an edge case.
+ *
+ * An empty pane until the label lands is the correct behaviour, not a compromise: that module's
+ * standing constraint is that missing-key fallback belongs in the i18n runtime, where it can use the
+ * configured fallback language, never in a component-local English literal.
+ */
+const ZoneEmptyStatePlaceholder = () => {
+    const { tComponent, isReady } = useI18n({ component: FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER });
+    const label = isReady
+        ? resolveComponentLabel({
+            tComponent,
+            componentType: FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER,
+            key: 'zoneEmptyState',
+        })
+        : '';
+    return (_jsx("div", { className: "flex h-full items-center justify-center p-container", "data-zone-empty-state": "true", children: _jsx("p", { className: "max-w-xs text-center text-sm text-muted-foreground", children: label }) }));
+};
 export const NavigationContentAreas = ({ routerChildren }) => {
     // Reconcile the Settings Hub overlay with the URL. Mounted here — once,
     // persistently in the authenticated shell — rather than in the `/settings`
@@ -394,8 +537,12 @@ export const NavigationContentAreas = ({ routerChildren }) => {
     // the Outlet fallback below), so in-session history navigation would otherwise
     // move the URL without ever reconciling the rendered stack content.
     useStructuralZoneBackForwardSync();
-    const { isZoneVisible, getZoneDepth, setFocusedZone } = useNavigationState();
-    const { navigationLayout: resolvedNavigationLayout, UIConfig, shellAppearance } = useUI();
+    // Reconcile a HOSTED PANE (`?pane=` beside a non-resource primary) with the SECONDARY zone.
+    // Always-mounted for the same reason as the two above: the pane is never the router's route —
+    // the browser URL is the host's — so no route element ever mounts a sync hook for it.
+    useHostedPaneRouteSync();
+    const { isZoneVisible, getZoneDepth, getTopContent, setFocusedZone } = useNavigationState();
+    const { navigationLayout: resolvedNavigationLayout, UIConfig, shellAppearance, compositeViews } = useUI();
     const containerRef = useRef(null);
     const containerWidth = useContainerWidth(containerRef);
     const isMobile = UIConfig?.currentBreakpoint === ViewportBreakpoint.MOBILE;
@@ -412,8 +559,83 @@ export const NavigationContentAreas = ({ routerChildren }) => {
     const hasCompanionZone = !!zones?.companion;
     const secondaryHasContent = isZoneVisible(NavigationZoneName.SECONDARY) || getZoneDepth(NavigationZoneName.SECONDARY) > 0;
     const companionHasContent = isZoneVisible(NavigationZoneName.COMPANION) || getZoneDepth(NavigationZoneName.COMPANION) > 0;
-    const showSecondary = !isMobile && secondaryHasContent && hasSecondaryZone;
-    const showCompanion = !isMobile && companionHasContent && hasCompanionZone;
+    /*
+     * `onEmpty` resolution (#191). Until this landed the field was declared, documented and shipped to
+     * application builders in the compiled `config-navigation` skill, and read by NOTHING — every zone
+     * collapsed unconditionally, which made the COLLAPSE half accidentally correct and `EMPTY_STATE`
+     * unreachable. That is why nothing ever disagreed.
+     *
+     * The override is read from whatever occupies PRIMARY, because destinations sharing one secondary
+     * zone legitimately want different things: the artifact LIST wants its detail pane to stay put while
+     * a reviewer steps through rows, the domain-model CANVAS wants its width back the moment nothing is
+     * selected. Precedence is destination → zone → COLLAPSE, so a layout authoring neither behaves
+     * exactly as it did before this existed.
+     */
+    const primaryTopContent = getTopContent(NavigationZoneName.PRIMARY);
+    const destinationOnEmptyOverride = useMemo(() => resolvePrimaryDestinationAdjacentZoneOnEmpty({ primaryContent: primaryTopContent, compositeViews }), [primaryTopContent, compositeViews]);
+    /*
+     * How much of PRIMARY the current destination occupies (#176) — read from the same declaration the
+     * `onEmpty` override comes from, via the one shared content-kind switch.
+     */
+    const primaryZoneGeometry = useMemo(() => resolvePrimaryZoneContentGeometry({ primaryContent: primaryTopContent, compositeViews }), [primaryTopContent, compositeViews]);
+    /*
+     * Adjacent zones get the SAME content boundary primary has, and had none before: a detail pane's
+     * width was whatever the rendered component chose, so an application ended up capping and centring
+     * its own detail template — solving locally, and invisibly, a question the engine had not answered.
+     */
+    const secondaryZoneGeometry = useMemo(() => resolveAdjacentZoneContentGeometry({
+        zoneContent: getTopContent(NavigationZoneName.SECONDARY),
+        compositeViews,
+    }), [getTopContent, compositeViews]);
+    const companionZoneGeometry = useMemo(() => resolveAdjacentZoneContentGeometry({
+        zoneContent: getTopContent(NavigationZoneName.COMPANION),
+        compositeViews,
+    }), [getTopContent, compositeViews]);
+    const secondaryOnEmpty = resolveZoneEmptyBehavior({
+        zone: NavigationZoneName.SECONDARY,
+        zones,
+        destinationOverride: destinationOnEmptyOverride,
+    });
+    const companionOnEmpty = resolveZoneEmptyBehavior({
+        zone: NavigationZoneName.COMPANION,
+        zones,
+        destinationOverride: destinationOnEmptyOverride,
+    });
+    /*
+     * A zone occupies space for one of two reasons, and they are different questions: it HAS content,
+     * or it has none and its resolved behavior reserves the pane for a placeholder. `!isMobile` still
+     * gates both — below the breakpoint the responsive-collapse path owns the zone, and reserving an
+     * empty strip on a phone would be the worst possible reading of EMPTY_STATE.
+     */
+    /*
+     * One element for all four zone render sites. A shared node rather than four `<ZoneEmptyStatePlaceholder />`
+     * literals so the two multi-zone branches cannot drift into rendering different placeholders.
+     */
+    const zoneEmptyStatePlaceholder = _jsx(ZoneEmptyStatePlaceholder, {});
+    /*
+     * RESERVING requires a resolved destination; HAVING content does not.
+     *
+     * The two halves of `showSecondary` answer to different authorities. "The zone holds something" is a
+     * fact about the zone and is true or false immediately. "The zone is empty and should reserve space
+     * anyway" is a decision that belongs to whatever is in PRIMARY — and during a page or tab change
+     * there is a moment when primary's stack has not been reconciled from the URL yet. In that moment
+     * the destination override is absent, the zone's own `onEmpty` wins by default, and a layout that
+     * declares `EMPTY_STATE` reserves a third of the window for a pane its destination is about to
+     * collapse.
+     *
+     * Measured on the workbench creation board at 2400px: switching section flipped the content area
+     * 2312 -> 1294 -> 2312 within ~25ms, so the page's content jumped left and back on every tab click.
+     * Both of that layout's destinations declare COLLAPSE; only the unresolved frame ever said otherwise.
+     *
+     * So an unresolved destination reserves NOTHING. It is not a destination that declared nothing — it
+     * is a question that has not been answered, and the honest response to an unanswered structural
+     * question is to change no structure.
+     */
+    const primaryDestinationKnown = useMemo(() => primaryDestinationDeclarationIsKnown({ primaryContent: primaryTopContent, compositeViews }), [primaryTopContent, compositeViews]);
+    const showSecondary = !isMobile && hasSecondaryZone
+        && (secondaryHasContent || (primaryDestinationKnown && zoneOccupiesSpaceWhenEmpty(secondaryOnEmpty)));
+    const showCompanion = !isMobile && hasCompanionZone
+        && (companionHasContent || (primaryDestinationKnown && zoneOccupiesSpaceWhenEmpty(companionOnEmpty)));
     const anyMultiZone = hasSecondaryZone || hasCompanionZone;
     const isResizable = !isMobile && ((showSecondary && !!split?.resizable) ||
         (showCompanion && !!split?.companion?.resizable));
@@ -427,18 +649,35 @@ export const NavigationContentAreas = ({ routerChildren }) => {
     }, [zones, split, showSecondary, showCompanion, containerWidth]);
     // ── Single-zone layout (mobile or no side zones) ──
     if (!anyMultiZone || isMobile) {
-        return (_jsx(Surface, { asChild: true, emitPolicyVars: false, variant: SurfaceVariant.SHELL, policyOverride: NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE, children: _jsx("div", { ref: containerRef, className: `h-full overflow-auto p-container ${contentAreaSurface}`, "data-content-area": "primary", children: _jsx(PrimaryContentWidthBoundary, { children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.PRIMARY, fallback: routerChildren }) }) }) }));
+        return (_jsx(Surface, { asChild: true, emitPolicyVars: false, variant: SurfaceVariant.SHELL, policyOverride: NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE, children: _jsx("div", { ref: containerRef, className: `h-full overflow-auto p-container ${contentAreaSurface}`, "data-content-area": "primary", children: _jsx(ZoneContentWidthBoundary, { geometry: primaryZoneGeometry, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.PRIMARY, fallback: routerChildren }) }) }) }));
     }
     // ── Multi-zone resizable layout ──
     if (isResizable && panelSizes) {
-        const splitDirection = split?.orientation ?? DisplayDirection.VERTICAL;
-        return (_jsx("div", { ref: containerRef, className: "h-full", children: _jsx(Surface, { asChild: true, emitPolicyVars: false, variant: SurfaceVariant.SHELL, policyOverride: NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE, children: _jsxs(ResizablePanelGroup, { direction: splitDirection, autoSaveId: "nav-zones", className: `h-full ${contentAreaSurface}`, children: [_jsx(ResizablePanel, { defaultSize: panelSizes.primaryDefault, minSize: MIN_PRIMARY_PERCENT, id: "nav-primary", order: 1, className: "h-full overflow-auto p-container", children: _jsx("div", { className: "h-full", "data-content-area": "primary", onPointerDown: focusPrimary, children: _jsx(PrimaryContentWidthBoundary, { children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.PRIMARY, fallback: routerChildren }) }) }) }), showSecondary && panelSizes.secondary && (_jsxs(_Fragment, { children: [_jsx(ResizableHandle, { withHandle: true, disabled: panelSizes.secondary.frozen }), _jsx(ResizablePanel, { defaultSize: panelSizes.secondary.defaultSize, minSize: panelSizes.secondary.minSize, maxSize: panelSizes.secondary.maxSize, collapsible: panelSizes.secondary.collapsible, collapsedSize: panelSizes.secondary.collapsedSize, id: "nav-secondary", order: 2, className: "h-full overflow-auto p-container", children: _jsx("div", { className: "h-full", "data-content-area": "secondary", onPointerDown: focusSecondary, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.SECONDARY }) }) })] })), showCompanion && panelSizes.companion && (_jsxs(_Fragment, { children: [_jsx(ResizableHandle, { withHandle: true, disabled: panelSizes.companion.frozen }), _jsx(ResizablePanel, { defaultSize: panelSizes.companion.defaultSize, minSize: panelSizes.companion.minSize, maxSize: panelSizes.companion.maxSize, collapsible: panelSizes.companion.collapsible, collapsedSize: panelSizes.companion.collapsedSize, id: "nav-companion", order: 3, className: "h-full overflow-auto p-container", children: _jsx("div", { className: "h-full", "data-content-area": "companion", onPointerDown: focusCompanion, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.COMPANION }) }) })] }))] }) }) }));
+        const splitDirection = splitDividerOrientationToPanelGroupDirection(split?.orientation);
+        /*
+         * `Surface asChild` wraps the plain container DIV, exactly as the single-zone branch above and
+         * the static branch below do — NOT the panel group.
+         *
+         * It used to wrap `ResizablePanelGroup`, and that crashed the whole shell the first time this
+         * branch ever rendered. `asChild` forwards the Surface's ref to its child through Radix `Slot`;
+         * the panel-group preset spreads `...props` onto `react-resizable-panels`' `PanelGroup`, whose ref
+         * slot is an IMPERATIVE HANDLE (`{ getId, getLayout, setLayout }`) rather than a DOM node. The
+         * Surface's geometry probe then called `ResizeObserver.observe()` on a non-Element and threw.
+         * `ResizablePanelGroupProps` declares no `ref` at all, so it was never a valid `asChild` target —
+         * the contract was violated at this call site, not by the panel group.
+         *
+         * Wrapping the div instead costs NO extra DOM (that div already existed to carry `containerRef`),
+         * makes all three branches structurally identical, and hands the probe a real element so the
+         * material runtime works here rather than being silently inert. `Slot` composes its own ref with
+         * the child's, so `containerRef` keeps receiving the node.
+         */
+        return (_jsx(Surface, { asChild: true, emitPolicyVars: false, variant: SurfaceVariant.SHELL, policyOverride: NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE, children: _jsx("div", { ref: containerRef, className: `h-full ${contentAreaSurface}`, children: _jsxs(ResizablePanelGroup, { direction: splitDirection, autoSaveId: "nav-zones", className: "h-full", children: [_jsx(ResizablePanel, { defaultSize: panelSizes.primaryDefault, minSize: MIN_PRIMARY_PERCENT, id: "nav-primary", order: 1, className: "h-full", children: _jsx("div", { className: `h-full p-container ${primaryZoneGeometry.fillsHeight ? 'overflow-hidden' : 'overflow-auto'}`, "data-content-area": "primary", onPointerDown: focusPrimary, children: _jsx(ZoneContentWidthBoundary, { geometry: primaryZoneGeometry, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.PRIMARY, fallback: routerChildren }) }) }) }), showSecondary && panelSizes.secondary && (_jsxs(_Fragment, { children: [_jsx(ResizableHandle, { withHandle: true, disabled: panelSizes.secondary.frozen }), _jsx(ResizablePanel, { defaultSize: panelSizes.secondary.defaultSize, minSize: panelSizes.secondary.minSize, maxSize: panelSizes.secondary.maxSize, collapsible: panelSizes.secondary.collapsible, collapsedSize: panelSizes.secondary.collapsedSize, id: "nav-secondary", order: 2, className: "h-full", children: _jsx("div", { className: "h-full overflow-auto p-container", "data-content-area": "secondary", onPointerDown: focusSecondary, children: _jsx(ZoneContentWidthBoundary, { geometry: secondaryZoneGeometry, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.SECONDARY, emptyState: zoneEmptyStatePlaceholder }) }) }) })] })), showCompanion && panelSizes.companion && (_jsxs(_Fragment, { children: [_jsx(ResizableHandle, { withHandle: true, disabled: panelSizes.companion.frozen }), _jsx(ResizablePanel, { defaultSize: panelSizes.companion.defaultSize, minSize: panelSizes.companion.minSize, maxSize: panelSizes.companion.maxSize, collapsible: panelSizes.companion.collapsible, collapsedSize: panelSizes.companion.collapsedSize, id: "nav-companion", order: 3, className: "h-full", children: _jsx("div", { className: "h-full overflow-auto p-container", "data-content-area": "companion", onPointerDown: focusCompanion, children: _jsx(ZoneContentWidthBoundary, { geometry: companionZoneGeometry, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.COMPANION, emptyState: zoneEmptyStatePlaceholder }) }) }) })] }))] }) }) }));
     }
     // ── Multi-zone static layout (zones present but not resizable) ──
     // Use ratio-based widths when available, fall back to equal distribution.
     const secondaryRatio = split?.ratio?.[1] ?? 50;
     const companionRatio = split?.companion?.ratio?.[1] ?? 30;
-    return (_jsx(Surface, { asChild: true, emitPolicyVars: false, variant: SurfaceVariant.SHELL, policyOverride: NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE, children: _jsxs("div", { ref: containerRef, className: `h-full flex ${contentAreaSurface}`, children: [_jsx("div", { className: "flex-1 h-full border-e border-border overflow-auto p-container", "data-content-area": "primary", onPointerDown: focusPrimary, children: _jsx(PrimaryContentWidthBoundary, { children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.PRIMARY, fallback: routerChildren }) }) }), showSecondary && (_jsx("div", { className: `h-full overflow-auto p-container ${(hasCompanionZone || showCompanion) ? 'border-e border-border' : ''}`, style: { width: `${secondaryRatio}%` }, "data-content-area": "secondary", onPointerDown: focusSecondary, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.SECONDARY }) })), showCompanion && (_jsx("div", { className: "h-full overflow-auto p-container", style: { width: `${companionRatio}%` }, "data-content-area": "companion", onPointerDown: focusCompanion, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.COMPANION }) }))] }) }));
+    return (_jsx(Surface, { asChild: true, emitPolicyVars: false, variant: SurfaceVariant.SHELL, policyOverride: NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE, children: _jsxs("div", { ref: containerRef, className: `h-full flex ${contentAreaSurface}`, children: [_jsx("div", { className: "flex-1 h-full border-e border-border overflow-auto p-container", "data-content-area": "primary", onPointerDown: focusPrimary, children: _jsx(ZoneContentWidthBoundary, { geometry: primaryZoneGeometry, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.PRIMARY, fallback: routerChildren }) }) }), showSecondary && (_jsx("div", { className: `h-full overflow-auto p-container ${(hasCompanionZone || showCompanion) ? 'border-e border-border' : ''}`, style: { width: `${secondaryRatio}%` }, "data-content-area": "secondary", onPointerDown: focusSecondary, children: _jsx(ZoneContentWidthBoundary, { geometry: secondaryZoneGeometry, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.SECONDARY, emptyState: zoneEmptyStatePlaceholder }) }) })), showCompanion && (_jsx("div", { className: "h-full overflow-auto p-container", style: { width: `${companionRatio}%` }, "data-content-area": "companion", onPointerDown: focusCompanion, children: _jsx(ZoneContentWidthBoundary, { geometry: companionZoneGeometry, children: _jsx(ZoneContentRenderer, { zone: NavigationZoneName.COMPANION, emptyState: zoneEmptyStatePlaceholder }) }) }))] }) }));
 };
 // =============================================================================
 // Unified Overlay Component
@@ -450,7 +689,7 @@ export const NavigationContentAreas = ({ routerChildren }) => {
  * Defaults to DIALOG when no appearance is set (backward compatibility).
  */
 const NavigationOverlay = () => {
-    const { state } = useNavigationState();
+    const { state, getZoneState } = useNavigationState();
     const { closeOverlay } = useNavigationController();
     const routerNavigate = useNavigate();
     const overlayStack = state.overlay;
@@ -480,17 +719,40 @@ const NavigationOverlay = () => {
         // navigation lands, so the overlay closes exactly once.
         if (topEntry?.content.contentType === NavigationContentType.SETTINGS_HUB) {
             const primaryStack = state.zones[NavigationZoneName.PRIMARY]?.stack ?? [];
-            const revealUrl = primaryStack[primaryStack.length - 1]?.urlPath ?? CommonRoutePaths.home;
+            const secondaryStack = state.zones[NavigationZoneName.SECONDARY]?.stack ?? [];
+            const secondaryTop = secondaryStack[secondaryStack.length - 1];
+            const primaryUrl = primaryStack[primaryStack.length - 1]?.urlPath;
+            /*
+             * The surface beneath the hub is revealed by URL. A HOSTED pane beside a composite primary is
+             * addressed only through the composed form, so the reveal composes it back; a bare host URL
+             * here would make the pane reconciler read "the pane left the URL" and close it.
+             */
+            const revealUrl = (secondaryTop?.hostedPane && primaryUrl
+                ? NavigationUtils.resolveBrowserUrlForZoneEntry({
+                    zone: NavigationZoneName.SECONDARY,
+                    entryUrlPath: secondaryTop.urlPath,
+                    currentBrowserUrl: primaryUrl,
+                    getZoneState,
+                })
+                : primaryUrl) ?? CommonRoutePaths.home;
             routerNavigate(revealUrl, { replace: true });
             return;
         }
         closeOverlay();
-    }, [closeOverlay, routerNavigate, topEntry, state.zones]);
+    }, [closeOverlay, routerNavigate, topEntry, state.zones, getZoneState]);
     const overlayClassName = topEntry?.content.contentType === NavigationContentType.SETTINGS_HUB
         ? SETTINGS_HUB_NAVIGATION_OVERLAY_CLASS_NAME
         : getNavigationOverlayClassName(mode);
     return (_jsx(OverlayContainer, { open: isOpen, onOpenChange: handleOpenChange, title: title || undefined, titleVisuallyHidden: true, config: {
             mode,
+            /*
+             * The behaviour the top entry's operation DECLARED, defaulted here rather than at the
+             * declaration so an entry that says nothing behaves exactly as every overlay did before this
+             * channel existed: modal, dismiss-on-outside-click, dimmed.
+             */
+            modal: topEntry?.overlayBehavior?.modal ?? true,
+            closeOnOutsideClick: topEntry?.overlayBehavior?.closeOnOutsideClick ?? true,
+            showBackdrop: topEntry?.overlayBehavior?.showBackdrop ?? true,
             side: PlacementSide.END,
         }, className: overlayClassName, children: topEntry && (_jsx(NavigationContentRenderer, { content: topEntry.content, zone: NavigationZone.OVERLAY, initiator: topEntry.initiator, entryId: topEntry.id })) }));
 };