@wildo-ai/saas-frontend-lib 1.1.4 → 1.1.6

package/dist/esm/core/navigation/navigation-policy-resolver.service.js

@@ -19,9 +19,10 @@
  *
  * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md
  */
-import { CoreResourceOperation, NavigationTransition, NavigationZoneName, ResponsiveCollapseMode, ResourceOperationFrontendSurface, OverlayAppearance, SplitAppearance, } from '@wildo-ai/saas-models';
+import { CoreResourceOperation, NavigationTransition, NavigationZoneName, ResponsiveCollapseMode, ResourceOperationFrontendSurface, OverlayAppearance, getTransitionVerb, isEphemeralTransition as isEphemeral, isPersistentTransition as isPersistent, } from '@wildo-ai/saas-models';
 import { ViewportBreakpoint } from '@wildo-ai/zod-decorators';
-import { NavigationZone, APP_LEVEL_NAVIGATION_SOURCE, } from './navigation.schemas.js';
+import { NavigationZone, APP_LEVEL_NAVIGATION_SOURCE, NavigationPlacementAdjustment, NavigationTransitionSource, } from './navigation.schemas.js';
+import { zoneIsCollapsedAtViewport } from './zone-collapse.js';
 // ════════════════════════════════════════════════════════════════
 // Viewport-Discriminated Resolution Utility
 // ════════════════════════════════════════════════════════════════
@@ -34,6 +35,49 @@ const VIEWPORT_FALLBACK_ORDER = {
     [ViewportBreakpoint.VERT_TABLET]: [ViewportBreakpoint.VERT_TABLET, ViewportBreakpoint.DESKTOP],
     [ViewportBreakpoint.DESKTOP]: [ViewportBreakpoint.DESKTOP],
 };
+/**
+ * WHICH collapse a structural zone is under at this viewport, or `undefined` for none.
+ *
+ * Exported rather than private to the resolver because THREE parties need the answer and none may
+ * re-derive it: the resolver places a CLICK's content, `useResponsiveZoneMigration` moves content
+ * ALREADY sitting in a zone the viewport has just taken away, and a test pins both. The predicate
+ * half (`zoneIsCollapsedAtViewport`) was extracted for exactly this reason on 2026-09-25; this is
+ * the mode half, and leaving it private would let the migration disagree with the placement about
+ * whether a collapsed pane becomes a page or a sheet — the two halves of one declaration, answered
+ * by two functions.
+ *
+ * Callers own the zone-identity guard, because it is a question about WHICH zone rather than about
+ * the viewport.
+ *
+ * ## An UNDECLARED collapse defaults to PUSH, and that is a decision
+ *
+ * `NavigationContentAreas` renders a single zone below the mobile breakpoint — secondary and
+ * companion are not shown at all. So on a phone a zone with no `responsiveCollapse` is not "left
+ * alone": content routed there is placed into a zone that does not render, and the user sees
+ * nothing happen. That is what an undeclared collapse meant before #411, for every application, and
+ * it is not a behaviour anyone would choose deliberately.
+ *
+ * PUSH rather than OVERLAY because it is the conservative half of the vocabulary: the content
+ * appears in primary in context, and BACK pops to what was there before — no dismissal affordance
+ * to get wrong, and no modality over a phone-sized viewport. An application that wants the sheet
+ * declares `OVERLAY` and gets it.
+ *
+ * The alternative — return `undefined` and let the content vanish — was rejected because it is the
+ * silent degradation #411 exists to remove, and because "the zone declared nothing" is not a reason
+ * to lose a user's navigation.
+ *
+ * A viewport-discriminated declaration naming no mode for THIS breakpoint is a gap in the
+ * declaration, not a statement that the zone renders — it still would not — so it takes the same
+ * default.
+ */
+export function resolveZoneCollapseMode(params) {
+    if (!zoneIsCollapsedAtViewport(params))
+        return undefined;
+    const declared = params.zoneConfig?.responsiveCollapse;
+    if (!declared)
+        return ResponsiveCollapseMode.PUSH;
+    return resolveViewportDiscriminated(declared, params.viewport) ?? ResponsiveCollapseMode.PUSH;
+}
 /**
  * Resolve a `ViewportDiscriminated<T>` value for the current viewport.
  *
@@ -69,27 +113,6 @@ function isViewportRecord(value) {
     return keys.length > 0 && keys.some(k => breakpoints.has(k));
 }
 // ════════════════════════════════════════════════════════════════
-// Transition Config Helpers
-// ════════════════════════════════════════════════════════════════
-/** Extract the transition verb from a TransitionConfig (string or object). */
-function getTransitionVerb(config) {
-    if (typeof config === 'string')
-        return config;
-    return config.transition;
-}
-/** Extract the ephemeral modifier from a TransitionConfig. */
-function isEphemeral(config) {
-    if (typeof config === 'string')
-        return false;
-    return config.ephemeral === true;
-}
-/** Extract the persistent modifier from a TransitionConfig. */
-function isPersistent(config) {
-    if (typeof config === 'string')
-        return false;
-    return config.persistent === true;
-}
-// ════════════════════════════════════════════════════════════════
 // Default Fallback Transitions
 // ════════════════════════════════════════════════════════════════
 const FRAMEWORK_FALLBACK_TRANSITION = NavigationTransition.PUSH;
@@ -105,26 +128,97 @@ export class NavigationPolicyResolver {
      * @returns What the controller should do: target zone, transition, appearance, collapse state.
      */
     resolve(context, layout) {
-        const resolvedTransition = this.resolveTransition(context, layout);
+        const resolved = this.resolveTransition(context, layout);
+        const resolvedTransition = resolved.config;
         const transitionVerb = getTransitionVerb(resolvedTransition);
         const ephemeral = isEphemeral(resolvedTransition);
         const persistent = isPersistent(resolvedTransition);
-        const targetZone = this.deriveTargetZone(transitionVerb, context, layout, persistent);
-        // ─── Surface coercion: EMBEDDED never becomes THE PAGE ─────────────
+        /*
+         * ─── PROVENANCE ─────────────────────────────────────────────────────────────────────────────
+         *
+         * Accumulated as the placement is decided, in application order, so the array reads as the story
+         * of how the authored verb became the final one. Nothing branches on it — see
+         * `NavigationResolutionProvenance`.
+         */
+        const adjustments = [];
+        const derivedTarget = this.deriveTargetZone(transitionVerb, context, layout, persistent);
+        const targetZone = derivedTarget.zone;
+        if (derivedTarget.adjustment)
+            adjustments.push(derivedTarget.adjustment);
+        /*
+         * ─── AN ESCALATION REWRITES THE VERB. All four of them. ─────────────────────────────────────
+         *
+         * A SPLIT that found no adjacent zone lands in the OVERLAY layer, and until 2026-09-25 it kept
+         * its SPLIT verb on the way there. The result was an incoherent triple — measured against Wonder
+         * Todos' real layout, which declares a SPLIT override and only `zones.primary`:
+         *
+         *     { targetZone: 'overlay', transition: 'split', appearance: 'panel' }
+         *
+         * `panel` is a `SplitAppearance` handed to the overlay layer, and it reached the overlay
+         * container, which has no case for it. Worse, `overlayBehavior` is gated on
+         * `finalTransition === OVERLAY` further down, so an operation's authored `modal` /
+         * `closeOnOutsideClick` / `showBackdrop` were SILENTLY DROPPED for exactly the content that ends
+         * up in a dialog by accident — the one placement where a create form most needs them.
+         *
+         * The other three escalations already did this: the EMBEDDED coercion returns an explicit
+         * `transition: OVERLAY`, responsive collapse rewrites `collapsedTransition`, and the depth
+         * ceiling rewrites `finalTransition`. This was the fourth site of one invariant — the shape
+         * `.claude/rules/invariant-call-site-enumeration.md` exists for — and it was the site nobody
+         * enumerated, including the pass that ADDED the adjustment naming this very branch and asserted
+         * only `targetZone` and `adjustments` on it.
+         */
+        const escalatedVerb = derivedTarget.adjustment === NavigationPlacementAdjustment.SPLIT_ESCALATED_NO_ADJACENT_ZONE
+            || derivedTarget.adjustment === NavigationPlacementAdjustment.PERSISTENT_SPLIT_ESCALATED_NO_COMPANION
+            ? NavigationTransition.OVERLAY
+            : transitionVerb;
+        // ─── Surface coercion: EMBEDDED never TAKES OVER a structural zone ─────────────
         // `ResourceOperationFrontendSurface.EMBEDDED` is contractually a view
-        // "rendered within a host — overlay/drill-in when standalone". PRIMARY is
-        // not a host; it is the addressable page surface. The transition chain is
-        // keyed by core semantics only (an app cannot author "embedded READ →
-        // overlay" in `transitions`), so when the chain resolves EMBEDDED content
-        // onto PRIMARY we escalate to OVERLAY here — the same escalation posture
-        // `resolveSplitTarget` already uses when no adjacent zone exists. Explicit
-        // pane outcomes (SPLIT → secondary/companion) and overlay outcomes are
-        // hosts and pass through untouched, as does every non-resource content
-        // navigation (`operationSurface` is undefined there).
+        // "rendered within a host — overlay/drill-in when standalone". A STRUCTURAL
+        // zone is not a host; it is an addressable surface that already holds
+        // something a reader is reading. The transition chain is keyed by core
+        // semantics only (an app cannot author "embedded READ → overlay" in
+        // `transitions`), so when the chain resolves EMBEDDED content onto one we
+        // escalate to OVERLAY here — the same escalation posture `resolveSplitTarget`
+        // already uses when no adjacent zone exists. Explicit pane outcomes
+        // (SPLIT → secondary/companion) and overlay outcomes are hosts and pass
+        // through untouched, as does every non-resource content navigation
+        // (`operationSurface` is undefined there).
+        //
+        // ── The zone test was `=== PRIMARY` until 2026-09-11, and that was the whole of #627. ──
+        //
+        // PUSH and REPLACE both target `getStructuralSourceZone`, i.e. THE ZONE THE
+        // REFERENCE WAS CLICKED IN — so whether an EMBEDDED read opened as an overlay
+        // or silently replaced the surface beneath it depended on which pane the
+        // reference happened to be rendered in. Measured on the workbench's Build plan,
+        // which is a hosted pane in SECONDARY: clicking a task reference fetched the
+        // aspect row and every one of its split edges, then REPLACED the document the
+        // reader was reading with it. Nothing threw, nothing logged, and the page the
+        // reader had been on was simply gone.
+        //
+        // PRIMARY was never the special case. "Not a host" is true of every structural
+        // zone, and the argument the original comment makes for PRIMARY — it is the
+        // addressable surface, not a host — is the same argument for a pane.
+        //
+        // ── And a SPLIT is a host only when it actually OPENS a pane. ──
+        //
+        // The exemption below reads `zoneOccupancy`, not the verb, and the difference is the whole
+        // defect. `resolveSplitTarget` answers SECONDARY in two situations that mean opposite things:
+        // when secondary is FREE it opens a pane beside the source, which is the drill-in host the enum
+        // allows — and when both panes are taken it falls through to "push into secondary (replace
+        // existing content)", which is its own comment's wording for taking a surface over. A verb test
+        // cannot tell those apart, so exempting SPLIT wholesale re-opened the hole one line down.
+        //
+        // Measured on the workbench, which declares ONE pane: the artifact list holds PRIMARY, the
+        // document holds SECONDARY, and a reference clicked inside that document resolved
+        // `{surface: embedded, verb: split, targetZone: secondary}` — secondary occupied by the very
+        // document the reader was reading, replaced by the aspect. Occupancy is the input
+        // `resolveSplitTarget` already decides on, so reading it here cannot drift from it.
         if (context.operationSurface === ResourceOperationFrontendSurface.EMBEDDED
-            && targetZone === NavigationZoneName.PRIMARY
-            // …EXCEPT for INPLACE, which is not the page either — it is the one transition that places no
-            // content in a zone at all, and `deriveTargetZone` only reports PRIMARY for it because "the
+            && targetZone !== NavigationZone.OVERLAY
+            && !(escalatedVerb === NavigationTransition.SPLIT
+                && context.zoneOccupancy?.[targetZone] !== true)
+            // …EXCEPT for INPLACE, which takes over nothing either — it is the one transition that places
+            // no content in a zone at all, and `deriveTargetZone` only reports a zone for it because "the
             // source zone" is the closest thing that function can say about an element-level outcome.
             //
             // Without this exemption the coercion silently rewrote every EMBEDDED inline transition into
@@ -133,13 +227,15 @@ export class NavigationPolicyResolver {
             // and the surface most likely to author `inplace` (a row's EMBEDDED update) is exactly the one
             // it would have hit. Found by driving the real controller; a resolver-level test would not
             // have shown it, because at the resolver an overlay is a perfectly good answer.
-            && transitionVerb !== NavigationTransition.INPLACE) {
+            && escalatedVerb !== NavigationTransition.INPLACE) {
+            adjustments.push(NavigationPlacementAdjustment.EMBEDDED_COERCED_TO_OVERLAY);
             return {
                 targetZone: NavigationZone.OVERLAY,
                 transition: NavigationTransition.OVERLAY,
                 appearance: this.deriveAppearance(NavigationTransition.OVERLAY, context, layout),
                 collapsed: false,
                 ephemeral: ephemeral || undefined,
+                provenance: { transitionSource: resolved.source, authoredTransition: transitionVerb, adjustments },
             };
         }
         const collapseMode = this.resolveCollapseMode(targetZone, context, layout);
@@ -175,7 +271,13 @@ export class NavigationPolicyResolver {
             ? NavigationTransition.OVERLAY
             : collapseMode === ResponsiveCollapseMode.PUSH
                 ? NavigationTransition.PUSH
-                : transitionVerb;
+                : escalatedVerb;
+        if (collapseMode === ResponsiveCollapseMode.OVERLAY) {
+            adjustments.push(NavigationPlacementAdjustment.RESPONSIVE_COLLAPSE_OVERLAY);
+        }
+        else if (collapseMode === ResponsiveCollapseMode.PUSH) {
+            adjustments.push(NavigationPlacementAdjustment.RESPONSIVE_COLLAPSE_PUSH);
+        }
         /*
          * ─── maxDepth: a push past the ceiling becomes an overlay ───────────────────────────────────
          *
@@ -203,6 +305,8 @@ export class NavigationPolicyResolver {
             && targetDepth >= depthCeiling;
         const finalTargetZone = exceedsDepthCeiling ? NavigationZone.OVERLAY : collapsedTargetZone;
         const finalTransition = exceedsDepthCeiling ? NavigationTransition.OVERLAY : collapsedTransition;
+        if (exceedsDepthCeiling)
+            adjustments.push(NavigationPlacementAdjustment.DEPTH_CEILING_ESCALATED_TO_OVERLAY);
         const appearance = this.deriveAppearance(finalTransition, context, layout);
         const collapsed = collapseMode !== undefined;
         /*
@@ -220,6 +324,39 @@ export class NavigationPolicyResolver {
             collapsed,
             collapsedFromZone: collapsed ? targetZone : undefined,
             ephemeral: ephemeral || undefined,
+            /*
+             * Reported so the entry can carry it. `persistent` chose the COMPANION zone and nothing more
+             * until 2026-09-25, while its contract promised the pane would survive the source zone
+             * changing — see `NavigationStackEntry.persistent`.
+             */
+            persistent: persistent && finalTargetZone !== NavigationZone.OVERLAY ? true : undefined,
+            provenance: { transitionSource: resolved.source, authoredTransition: transitionVerb, adjustments },
+        };
+    }
+    /**
+     * The overlay an `INPLACE` transition becomes when the surface has no element-level host.
+     *
+     * A DOOR on the resolver rather than a re-resolution in the controller, because the controller's
+     * way of asking — injecting a synthetic `operationOverrides: [{ transition: OVERLAY }]` — had to
+     * lie twice to get an answer: it reported the outcome as an authored override, and it discarded
+     * the operation's REAL override along with the `appearance` and `overlayBehavior` on it. Here the
+     * context is untouched, so both are read exactly as they would be for any other overlay.
+     *
+     * The tier that answered `INPLACE` is preserved. What the degradation adds is an adjustment.
+     */
+    degradeInPlaceToOverlay(context, layout, original) {
+        return {
+            targetZone: NavigationZone.OVERLAY,
+            transition: NavigationTransition.OVERLAY,
+            appearance: this.deriveAppearance(NavigationTransition.OVERLAY, context, layout),
+            overlayBehavior: this.resolveOverlayBehavior(context),
+            collapsed: false,
+            ephemeral: original.ephemeral,
+            provenance: {
+                transitionSource: original.provenance.transitionSource,
+                authoredTransition: original.provenance.authoredTransition,
+                adjustments: [...original.provenance.adjustments, NavigationPlacementAdjustment.INPLACE_DEGRADED_TO_OVERLAY],
+            },
         };
     }
     // ──────────────────────────────────────────────────────────────
@@ -249,7 +386,7 @@ export class NavigationPolicyResolver {
         // Step 1 — Per-resource operation override (highest priority)
         const overrideResult = this.checkOperationOverrides(context);
         if (overrideResult)
-            return overrideResult;
+            return { config: overrideResult, source: NavigationTransitionSource.OPERATION_OVERRIDE };
         // Step 1.5 — An AUTHORED action presentation.
         //
         // Ranked here, immediately below `navigationOverrides` and above every app-level default,
@@ -262,22 +399,31 @@ export class NavigationPolicyResolver {
         // navigations, and an operation that has declared its own presentation is not asking for the
         // class default.
         if (context.actionPresentationIsAuthored === true && context.actionPresentationTransition !== undefined) {
-            return context.actionPresentationTransition;
+            return {
+                config: context.actionPresentationTransition,
+                source: NavigationTransitionSource.AUTHORED_ACTION_PRESENTATION,
+            };
         }
         // Step 2 — Per-relationship transition
         if (context.relationshipTransition !== undefined) {
-            return context.relationshipTransition;
+            return { config: context.relationshipTransition, source: NavigationTransitionSource.RELATIONSHIP };
         }
         // Step 3 — Global viewport override
         const viewportOverride = this.checkViewportOverride(context, layout);
         if (viewportOverride)
-            return viewportOverride;
+            return { config: viewportOverride, source: NavigationTransitionSource.VIEWPORT_OVERRIDE };
         // Step 4 — Source config transitions[operation]
         const sourceTransitions = this.getSourceTransitions(context, layout);
-        if (sourceTransitions) {
-            const transitionConfig = this.getTransitionBySemanticKey(sourceTransitions, context);
-            if (transitionConfig)
-                return transitionConfig;
+        if (sourceTransitions.transitions) {
+            const transitionConfig = this.getTransitionBySemanticKey(sourceTransitions.transitions, context);
+            if (transitionConfig) {
+                return {
+                    config: transitionConfig,
+                    source: sourceTransitions.borrowedFromPrimary
+                        ? NavigationTransitionSource.OVERLAY_FALLBACK_TO_PRIMARY
+                        : NavigationTransitionSource.SOURCE_TRANSITIONS,
+                };
+            }
         }
         // Step 4.5 — A DERIVED action presentation.
         //
@@ -289,10 +435,13 @@ export class NavigationPolicyResolver {
         // In practice this is the step that turns "a custom action with two fields" from a full page
         // into an overlay, which is the whole point of the axis.
         if (context.actionPresentationTransition !== undefined) {
-            return context.actionPresentationTransition;
+            return {
+                config: context.actionPresentationTransition,
+                source: NavigationTransitionSource.DERIVED_ACTION_PRESENTATION,
+            };
         }
         // Step 5 — Framework fallback
-        return FRAMEWORK_FALLBACK_TRANSITION;
+        return { config: FRAMEWORK_FALLBACK_TRANSITION, source: NavigationTransitionSource.FRAMEWORK_DEFAULT };
     }
     /**
      * Step 1: Check per-resource operation overrides.
@@ -350,17 +499,43 @@ export class NavigationPolicyResolver {
     }
     /**
      * Step 4: Get the transition map from the appropriate source config.
-     * Three distinct branches based on source type.
+     *
+     * ## An OVERLAY source falls back to the zone it is LANDING IN
+     *
+     * `fromOverlay` is the app's statement about leaving an overlay, and it wins. What it does NOT
+     * mean is that an app which declared nothing there has declared nothing at all: an overlay is not
+     * a structural zone, so `getStructuralSourceZone` already answers PRIMARY for it — a structural
+     * navigation out of an overlay IS a primary navigation. Reading a different map for the VERB than
+     * for the ZONE is how the two came to disagree.
+     *
+     * Measured on the workbench, 2026-09-25. Its layout declares `zones.primary.transitions.read =
+     * SPLIT` and no `fromOverlay` at all. Clicking an aspect popup's `family` backlink — an
+     * ADDRESSABLE artifact — found no overlay map, fell through to the framework fallback `PUSH`, and
+     * landed in PRIMARY: the artifact took the WHOLE PAGE, replacing the artifact list it should have
+     * opened beside. The application had said what a READ does on the page; the resolver did not ask.
+     *
+     * Wonder CRM is the control and is untouched: it declares `fromOverlay.read = PUSH` deliberately
+     * ("ADDRESSABLE targets legitimately leave the overlay and become the page"), that map answers,
+     * and the fallback never runs. The fallback also covers the gap INSIDE a declared map — one that
+     * names READ says nothing about LIST, and that gap used to take the framework default too.
+     *
+     * APP_LEVEL is deliberately NOT given the same fallback. A menubar click is a layout RESET with
+     * its own meaning, and an app that declares no `appLevel` map has not thereby asked for primary's
+     * drill-in verbs — it has asked for the framework default, which is what it gets.
      */
     getSourceTransitions(context, layout) {
         if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE) {
-            return layout.appLevel?.transitions;
+            return { transitions: layout.appLevel?.transitions, borrowedFromPrimary: false };
         }
         if (context.sourceZone === 'overlay') {
-            return layout.fromOverlay?.transitions;
+            const fromOverlay = layout.fromOverlay?.transitions;
+            const declared = fromOverlay && this.getTransitionBySemanticKey(fromOverlay, context);
+            return declared !== undefined
+                ? { transitions: fromOverlay, borrowedFromPrimary: false }
+                : { transitions: layout.zones.primary?.transitions, borrowedFromPrimary: true };
         }
         const zoneConfig = layout.zones[context.sourceZone];
-        return zoneConfig?.transitions;
+        return { transitions: zoneConfig?.transitions, borrowedFromPrimary: false };
     }
     // ──────────────────────────────────────────────────────────────
     // Target Zone Derivation
@@ -380,15 +555,15 @@ export class NavigationPolicyResolver {
             case NavigationTransition.PUSH:
             case NavigationTransition.REPLACE:
             case NavigationTransition.INPLACE:
-                return this.getStructuralSourceZone(context);
+                return { zone: this.getStructuralSourceZone(context) };
             case NavigationTransition.SPLIT:
                 return this.resolveSplitTarget(context, layout, persistent);
             case NavigationTransition.OVERLAY:
-                return NavigationZone.OVERLAY;
+                return { zone: NavigationZone.OVERLAY };
             case NavigationTransition.PROMOTE:
-                return NavigationZoneName.PRIMARY;
+                return { zone: NavigationZoneName.PRIMARY };
             default:
-                return NavigationZoneName.PRIMARY;
+                return { zone: NavigationZoneName.PRIMARY };
         }
     }
     /**
@@ -409,25 +584,44 @@ export class NavigationPolicyResolver {
      */
     resolveSplitTarget(context, layout, persistent) {
         if (persistent) {
-            return layout.zones.companion ? NavigationZoneName.COMPANION : NavigationZone.OVERLAY;
+            return layout.zones.companion
+                ? { zone: NavigationZoneName.COMPANION, adjustment: this.splitOutcomeFor(context, NavigationZoneName.COMPANION) }
+                : { zone: NavigationZone.OVERLAY, adjustment: NavigationPlacementAdjustment.PERSISTENT_SPLIT_ESCALATED_NO_COMPANION };
         }
         // Prefer secondary if declared, otherwise companion, otherwise escalate to overlay
         if (layout.zones.secondary) {
             if (!context.zoneOccupancy?.[NavigationZoneName.SECONDARY]) {
-                return NavigationZoneName.SECONDARY;
+                return { zone: NavigationZoneName.SECONDARY, adjustment: NavigationPlacementAdjustment.SPLIT_OPENED_FREE_PANE };
             }
             // Secondary occupied — try companion
             if (layout.zones.companion && !context.zoneOccupancy?.[NavigationZoneName.COMPANION]) {
-                return NavigationZoneName.COMPANION;
+                return { zone: NavigationZoneName.COMPANION, adjustment: NavigationPlacementAdjustment.SPLIT_OPENED_FREE_PANE };
             }
             // Both occupied — push into secondary (replace existing content)
-            return NavigationZoneName.SECONDARY;
+            return {
+                zone: NavigationZoneName.SECONDARY,
+                adjustment: NavigationPlacementAdjustment.SPLIT_REPLACED_OCCUPIED_PANE,
+            };
         }
         if (layout.zones.companion) {
-            return NavigationZoneName.COMPANION;
+            return { zone: NavigationZoneName.COMPANION, adjustment: this.splitOutcomeFor(context, NavigationZoneName.COMPANION) };
         }
         // No adjacent zones declared — escalate to overlay
-        return NavigationZone.OVERLAY;
+        return { zone: NavigationZone.OVERLAY, adjustment: NavigationPlacementAdjustment.SPLIT_ESCALATED_NO_ADJACENT_ZONE };
+    }
+    /**
+     * Did a split into `zone` OPEN a pane or REPLACE what was in one?
+     *
+     * The same question `resolveSplitTarget`'s secondary branch answers inline by construction — it
+     * only reaches companion when secondary is taken — but the two branches that target companion
+     * DIRECTLY (a persistent split, and a layout declaring companion without secondary) choose the
+     * zone before asking, so they ask here. Reading `zoneOccupancy` is what keeps both answers derived
+     * from one input rather than from two nearly-identical inline conditions.
+     */
+    splitOutcomeFor(context, zone) {
+        return context.zoneOccupancy?.[zone] === true
+            ? NavigationPlacementAdjustment.SPLIT_REPLACED_OCCUPIED_PANE
+            : NavigationPlacementAdjustment.SPLIT_OPENED_FREE_PANE;
     }
     // ──────────────────────────────────────────────────────────────
     // Appearance Derivation
@@ -437,7 +631,13 @@ export class NavigationPolicyResolver {
      * Only overlay and split transitions have meaningful appearance.
      */
     deriveAppearance(transition, context, layout) {
-        if (transition !== NavigationTransition.OVERLAY && transition !== NavigationTransition.SPLIT) {
+        /*
+         * OVERLAY only. A SPLIT used to derive a `SplitAppearance` here and nothing ever read it — see
+         * the removal note in `navigation.shared.schemas.ts`. How a PANE renders is `SplitConfig`'s
+         * geometry (`orientation`, `ratio`, the zone's width bounds), which the content areas read
+         * directly from the layout rather than off a resolution.
+         */
+        if (transition !== NavigationTransition.OVERLAY) {
             return undefined;
         }
         // Check operation override appearance first
@@ -453,9 +653,6 @@ export class NavigationPolicyResolver {
         if (transition === NavigationTransition.OVERLAY) {
             return resolveViewportDiscriminated(zoneAppearance?.overlay, context.viewport) ?? OverlayAppearance.DIALOG;
         }
-        if (transition === NavigationTransition.SPLIT) {
-            return resolveViewportDiscriminated(zoneAppearance?.split, context.viewport) ?? SplitAppearance.PANEL;
-        }
         return undefined;
     }
     /**
@@ -481,8 +678,19 @@ export class NavigationPolicyResolver {
             return layout.appLevel?.appearance;
         }
         if (context.sourceZone === 'overlay') {
-            // FromOverlayConfig has no appearance — overlays within overlays shouldn't happen
-            return undefined;
+            /*
+             * PRIMARY's appearance, for the same reason its TRANSITIONS are read in `getSourceTransitions`:
+             * a structural navigation out of an overlay lands in PRIMARY, so PRIMARY's declaration is the
+             * one that describes it. `FromOverlayConfig` declares no appearance of its own, and returning
+             * `undefined` here sent every such navigation to the framework default instead of to the
+             * layout's — the same "skip what the app declared" shape the transition lookup had.
+             *
+             * This read `undefined` with the comment "overlays within overlays shouldn't happen", and that
+             * is no longer true in either half: an overlay opened FROM an overlay now stacks (it is how a
+             * reader walks an aspect graph popup to popup and walks back out), and a SPLIT out of an
+             * overlay is exactly the case this function was skipping.
+             */
+            return layout.zones.primary?.appearance;
         }
         return layout.zones[context.sourceZone]?.appearance;
     }
@@ -502,48 +710,20 @@ export class NavigationPolicyResolver {
      * this decision, free to disagree with the first.
      */
     resolveCollapseMode(targetZone, context, layout) {
-        if (targetZone === NavigationZone.OVERLAY || targetZone === NavigationZoneName.PRIMARY) {
-            return undefined;
-        }
         /*
-         * Collapse applies at a KNOWN narrow breakpoint, never merely at "not desktop".
-         *
-         * Written as `!== DESKTOP` first, and that is wrong in the one case that matters: a caller with
-         * no measured viewport yet (`currentBreakpoint: undefined` during the first frames) would have
-         * been treated as a phone and had its split collapsed into primary — a layout decision taken
-         * from a missing measurement. An unknown viewport is not a narrow one.
+         * The zone-identity guard stays HERE and the viewport decision lives in `resolveZoneCollapseMode`,
+         * because they are different questions: primary never collapses (it is the zone collapsed content
+         * moves INTO) and overlay is not a structural zone — neither fact depends on how wide the window
+         * is. Everything that does is shared with the migration hook, which must not re-derive it.
          */
-        if (context.viewport !== ViewportBreakpoint.MOBILE && context.viewport !== ViewportBreakpoint.VERT_TABLET) {
+        if (targetZone === NavigationZone.OVERLAY || targetZone === NavigationZoneName.PRIMARY) {
             return undefined;
         }
-        const zoneConfig = layout.zones[targetZone];
-        /*
-         * ─── An UNDECLARED collapse defaults to PUSH, and that is a decision ────────────────────────
-         *
-         * `NavigationContentAreas` renders a single zone below the mobile breakpoint — secondary and
-         * companion are not shown at all. So on a phone a zone with no `responsiveCollapse` is not
-         * "left alone": content routed there is placed into a zone that does not render, and the user
-         * sees nothing happen. That is what an undeclared collapse meant before #411, for every
-         * application, and it is not a behaviour anyone would choose deliberately.
-         *
-         * PUSH rather than OVERLAY because it is the conservative half of the vocabulary: the content
-         * appears in primary in context, and BACK pops to what was there before — no dismissal
-         * affordance to get wrong, and no modality over a phone-sized viewport. An application that
-         * wants the sheet declares `OVERLAY` and gets it.
-         *
-         * The alternative — keep returning `undefined` and let the content vanish — was rejected
-         * because it is the silent degradation #411 exists to remove, and because "the zone declared
-         * nothing" is not a reason to lose a user's navigation.
-         */
-        const declared = zoneConfig?.responsiveCollapse;
-        if (!declared)
-            return ResponsiveCollapseMode.PUSH;
-        /*
-         * A viewport-discriminated declaration that names no mode for THIS breakpoint is a gap in the
-         * declaration, not a statement that the zone renders — it still would not render — so it takes
-         * the same default.
-         */
-        return resolveViewportDiscriminated(declared, context.viewport) ?? ResponsiveCollapseMode.PUSH;
+        return resolveZoneCollapseMode({
+            zoneConfig: layout.zones[targetZone],
+            viewport: context.viewport,
+            contentAreaWidth: context.contentAreaWidth,
+        });
     }
 }
 /** Singleton instance for use across the frontend. */