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

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

@@ -6,7 +6,9 @@
  * - Which transition verb to apply (push, replace, split, overlay, inplace, promote)
  * - Which zone the content lands in (derived from the transition verb)
  * - What visual appearance to use (dialog/sheet/drawer for overlay, panel/drawer for split)
- * - Whether the target zone is responsively collapsed at the current viewport
+ * - Whether the target zone is responsively collapsed at the current viewport, and — since #411 —
+ *   APPLYING that collapse (push into primary, or overlay) rather than merely reporting it
+ * - Whether the push would exceed `maxDepth`, escalating it to an overlay if so
  *
  * Resolution chain (first match wins):
  * 1. Per-resource operation override (highest priority)
@@ -17,7 +19,7 @@
  *
  * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md
  */
-import { CoreResourceOperation, NavigationTransition, NavigationZoneName, ResourceOperationFrontendSurface, OverlayAppearance, SplitAppearance, } from '@wildo-ai/saas-models';
+import { CoreResourceOperation, NavigationTransition, NavigationZoneName, ResponsiveCollapseMode, ResourceOperationFrontendSurface, OverlayAppearance, SplitAppearance, } from '@wildo-ai/saas-models';
 import { ViewportBreakpoint } from '@wildo-ai/zod-decorators';
 import { NavigationZone, APP_LEVEL_NAVIGATION_SOURCE, } from './navigation.schemas.js';
 // ════════════════════════════════════════════════════════════════
@@ -140,14 +142,110 @@ export class NavigationPolicyResolver {
                 ephemeral: ephemeral || undefined,
             };
         }
-        const appearance = this.deriveAppearance(transitionVerb, context, layout);
-        const collapsed = this.checkCollapse(targetZone, context, layout);
-        return { targetZone, transition: transitionVerb, appearance, collapsed, ephemeral: ephemeral || undefined };
+        const collapseMode = this.resolveCollapseMode(targetZone, context, layout);
+        /*
+         * ─── RESPONSIVE COLLAPSE IS APPLIED HERE, not merely reported ───────────────────────────────
+         *
+         * Until 2026-09-08 (#411) `collapsed` was computed, returned, and read by nobody: the controller
+         * logged it, and `NavigationContentAreas` hid the secondary and companion zones unconditionally
+         * on mobile. So content routed to a collapsed zone went into a zone that would not render, and
+         * the declared choice between `PUSH` and `OVERLAY` had no effect whatsoever.
+         *
+         * Collapse is a PLACEMENT decision, which is what this resolver answers, so it belongs here
+         * rather than in the controller. Applying it downstream would mean two places deciding where
+         * content lands, and the second would have to re-derive the first's inputs.
+         *
+         *   PUSH    -> the content joins PRIMARY's stack. The user sees it in context, and back pops
+         *              to primary's previous content — the enum's own contract.
+         *   OVERLAY -> the content opens over primary as a sheet/dialog. Dismiss returns underneath.
+         *
+         * The appearance is derived AFTER the retarget, from the transition the content actually gets:
+         * deriving it from the pre-collapse verb would give an overlay a SPLIT appearance
+         * (`panel`/`drawer`), which the overlay container cannot render.
+         *
+         * `collapsed` stays in the result as INFORMATION — it is what lets a reader (and a test) tell a
+         * PUSH that was authored from a PUSH that is a collapsed SPLIT, which otherwise look identical.
+         */
+        const collapsedTargetZone = collapseMode === ResponsiveCollapseMode.OVERLAY
+            ? NavigationZone.OVERLAY
+            : collapseMode === ResponsiveCollapseMode.PUSH
+                ? NavigationZoneName.PRIMARY
+                : targetZone;
+        const collapsedTransition = collapseMode === ResponsiveCollapseMode.OVERLAY
+            ? NavigationTransition.OVERLAY
+            : collapseMode === ResponsiveCollapseMode.PUSH
+                ? NavigationTransition.PUSH
+                : transitionVerb;
+        /*
+         * ─── maxDepth: a push past the ceiling becomes an overlay ───────────────────────────────────
+         *
+         * `NavigationLayout.maxDepth` documents itself as "when a zone's stack depth reaches `maxDepth`,
+         * the next `push` opens an overlay instead" and, until 2026-09-08 (#411), NOTHING read it — the
+         * field and its per-relationship override were declared, validated and inert, so an application
+         * that set it got unbounded stacks and no error.
+         *
+         * It is applied AFTER the collapse above, and the order is load-bearing in both directions: a
+         * collapsed SPLIT becomes a push into PRIMARY, which must then answer to PRIMARY's ceiling
+         * rather than to the ceiling of the zone it was authored for; and an authored push that is
+         * already escalated to an overlay cannot then be collapsed, because an overlay is not a
+         * structural zone and has no `responsiveCollapse`.
+         *
+         * "Reaches" is `>=`, taken from the declaration verbatim: at `maxDepth: 3` the third entry is
+         * the last one pushed, and the fourth navigation opens an overlay.
+         */
+        const depthCeiling = context.relationshipMaxDepth ?? layout.maxDepth;
+        const targetDepth = collapsedTargetZone === NavigationZone.OVERLAY
+            ? undefined
+            : context.zoneDepth[collapsedTargetZone];
+        const exceedsDepthCeiling = depthCeiling !== undefined
+            && targetDepth !== undefined
+            && collapsedTransition === NavigationTransition.PUSH
+            && targetDepth >= depthCeiling;
+        const finalTargetZone = exceedsDepthCeiling ? NavigationZone.OVERLAY : collapsedTargetZone;
+        const finalTransition = exceedsDepthCeiling ? NavigationTransition.OVERLAY : collapsedTransition;
+        const appearance = this.deriveAppearance(finalTransition, context, layout);
+        const collapsed = collapseMode !== undefined;
+        /*
+         * Overlay behaviour rides with the appearance because it is answered by the same declaration and
+         * is meaningless without it — only an OVERLAY has a page behind to block, dismiss on, or dim.
+         */
+        const overlayBehavior = finalTransition === NavigationTransition.OVERLAY
+            ? this.resolveOverlayBehavior(context)
+            : undefined;
+        return {
+            targetZone: finalTargetZone,
+            transition: finalTransition,
+            appearance,
+            overlayBehavior,
+            collapsed,
+            collapsedFromZone: collapsed ? targetZone : undefined,
+            ephemeral: ephemeral || undefined,
+        };
     }
     // ──────────────────────────────────────────────────────────────
     // Step 0–5: Transition Resolution Chain
     // ──────────────────────────────────────────────────────────────
     resolveTransition(context, layout) {
+        /*
+         * ## Coverage: steps 1, 1.5 and 2 run in unit tests only — accepted deliberately, 2026-09-08 (#467)
+         *
+         * Three of this chain's seven steps are authored by NEITHER dogfood application: per-operation
+         * navigation overrides (step 1), authored action presentations (step 1.5) and per-relationship
+         * transitions (step 2). The resolver reads all three; nothing in either application declares
+         * them, so they have never executed outside their own unit tests.
+         *
+         * Nothing is wrong. The gap is that no application has yet had a reason to declare them, and
+         * buying the proof would mean authoring a declaration in order to test it — which proves the
+         * harness more than the product. Weighed and accepted; the project's usual bar for a shipped
+         * subsystem is knowingly not met for these three.
+         *
+         * **What would change the answer:** an application authoring any one of the three. That author
+         * is the first party to execute the step, and should read a surprise there as expected.
+         *
+         * Do NOT narrow the chain to the steps something uses today — that was the third option and it
+         * was not chosen. The ordering below is load-bearing and its reasoning is written out at each
+         * step; a shorter chain would lose it.
+         */
         // Step 1 — Per-resource operation override (highest priority)
         const overrideResult = this.checkOperationOverrides(context);
         if (overrideResult)
@@ -360,6 +458,23 @@ export class NavigationPolicyResolver {
         }
         return undefined;
     }
+    /**
+     * The overlay behaviour declared by a matching per-operation override, if any.
+     *
+     * First match wins, exactly as the transition and appearance do — one override describes one
+     * situation, so reading a different override's behaviour than its transition would let a single
+     * declaration be split across two answers.
+     */
+    resolveOverlayBehavior(context) {
+        if (!context.operationOverrides?.length)
+            return undefined;
+        for (const override of context.operationOverrides) {
+            if (this.overrideMatches(override, context) && override.overlayBehavior !== undefined) {
+                return override.overlayBehavior;
+            }
+        }
+        return undefined;
+    }
     /** Get the appearance config from the appropriate source. */
     getSourceAppearance(context, layout) {
         if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE) {
@@ -375,22 +490,60 @@ export class NavigationPolicyResolver {
     // Responsive Collapse Check
     // ──────────────────────────────────────────────────────────────
     /**
-     * Check if the target zone is responsively collapsed at the current viewport.
-     * Only secondary and companion zones can collapse. Primary never collapses.
-     * Overlay is not a structural zone — it cannot collapse.
+     * WHICH collapse the target zone is under at this viewport, or `undefined` for none.
+     *
+     * Only secondary and companion zones can collapse. Primary never collapses — it is the zone
+     * collapsed content moves INTO. Overlay is not a structural zone and cannot collapse either.
+     *
+     * This returned a BOOLEAN until 2026-09-08 (#411), and the boolean is why the whole mechanism was
+     * inert: `PUSH` and `OVERLAY` are the entire content of the declaration, and a flag that says
+     * "collapsed" without saying which cannot place anything. The consumer would have had to re-read
+     * `layout.zones[…].responsiveCollapse` and re-resolve the breakpoint itself — a second copy of
+     * this decision, free to disagree with the first.
      */
-    checkCollapse(targetZone, context, layout) {
+    resolveCollapseMode(targetZone, context, layout) {
         if (targetZone === NavigationZone.OVERLAY || targetZone === NavigationZoneName.PRIMARY) {
-            return false;
+            return undefined;
         }
-        if (context.viewport === ViewportBreakpoint.DESKTOP) {
-            return false;
+        /*
+         * 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.
+         */
+        if (context.viewport !== ViewportBreakpoint.MOBILE && context.viewport !== ViewportBreakpoint.VERT_TABLET) {
+            return undefined;
         }
         const zoneConfig = layout.zones[targetZone];
-        if (!zoneConfig?.responsiveCollapse)
-            return false;
-        const collapseMode = resolveViewportDiscriminated(zoneConfig.responsiveCollapse, context.viewport);
-        return collapseMode !== undefined;
+        /*
+         * ─── 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;
     }
 }
 /** Singleton instance for use across the frontend. */

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

@@ -1 +1 @@
-{"version":3,"file":"navigation-policy-resolver.service.js","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation-policy-resolver.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Navigation Policy Resolver — v3 zone-first, operation-driven resolution.\n *\n * Given a source context (zone, appLevel, or overlay), an operation, and the\n * navigation layout config, determines:\n * - Which transition verb to apply (push, replace, split, overlay, inplace, promote)\n * - Which zone the content lands in (derived from the transition verb)\n * - What visual appearance to use (dialog/sheet/drawer for overlay, panel/drawer for split)\n * - Whether the target zone is responsively collapsed at the current viewport\n *\n * Resolution chain (first match wins):\n * 1. Per-resource operation override (highest priority)\n * 2. Per-relationship transition\n * 3. Global viewport override\n * 4. Source context transitions[operation]\n * 5. Framework hardcoded fallback\n *\n * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md\n */\n\nimport {\n  CoreResourceOperation,\n  NavigationTransition,\n  NavigationZoneName,\n  ResourceOperationFrontendSurface,\n  OverlayAppearance,\n  SplitAppearance,\n  type NavigationLayout,\n  type TransitionConfig,\n  type TransitionObject,\n  type ZoneTransitions,\n  type ZoneAppearance,\n  type ViewportDiscriminated,\n} from '@wildo-ai/saas-models';\nimport type { NavigationOperationOverride } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport { ViewportBreakpoint } from '@wildo-ai/zod-decorators';\nimport {\n  NavigationZone,\n  APP_LEVEL_NAVIGATION_SOURCE,\n  type NavigationResolutionContext,\n  type NavigationResolutionResult,\n} from './navigation.schemas';\n\n\n// ════════════════════════════════════════════════════════════════\n// Viewport-Discriminated Resolution Utility\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Viewport priority order — when no exact match exists for the current\n * viewport, fall back to the next more general breakpoint, then to desktop.\n */\nconst VIEWPORT_FALLBACK_ORDER: Record<ViewportBreakpoint, ViewportBreakpoint[]> = {\n  [ViewportBreakpoint.MOBILE]: [ViewportBreakpoint.MOBILE, ViewportBreakpoint.VERT_TABLET, ViewportBreakpoint.DESKTOP],\n  [ViewportBreakpoint.VERT_TABLET]: [ViewportBreakpoint.VERT_TABLET, ViewportBreakpoint.DESKTOP],\n  [ViewportBreakpoint.DESKTOP]: [ViewportBreakpoint.DESKTOP],\n};\n\n/**\n * Resolve a `ViewportDiscriminated<T>` value for the current viewport.\n *\n * If the value is a plain `T`, it applies at all viewports. If it's a\n * viewport-keyed partial record, resolves by trying the current viewport\n * first, then falling back through larger breakpoints.\n *\n * Returns `undefined` when no match is found (caller applies defaults).\n */\nexport function resolveViewportDiscriminated<T>(\n  value: ViewportDiscriminated<T> | undefined,\n  viewport: ViewportBreakpoint,\n): T | undefined {\n  if (value === undefined || value === null) return undefined;\n  if (typeof value !== 'object' || !isViewportRecord(value)) return value as T;\n\n  const record = value as Partial<Record<ViewportBreakpoint, T>>;\n  const fallbacks = VIEWPORT_FALLBACK_ORDER[viewport] ?? [viewport];\n  for (const bp of fallbacks) {\n    if (bp in record) return record[bp];\n  }\n  return undefined;\n}\n\n/**\n * Type guard: distinguishes a viewport-keyed record from a plain enum value.\n * Viewport breakpoints are strings like '<md', '<lg', '>=lg'. If any key\n * matches a known breakpoint, the value is a viewport record.\n */\nfunction isViewportRecord<T>(value: unknown): value is Partial<Record<ViewportBreakpoint, T>> {\n  if (typeof value !== 'object' || value === null) return false;\n  const keys = Object.keys(value);\n  const breakpoints = new Set(Object.values(ViewportBreakpoint) as string[]);\n  return keys.length > 0 && keys.some(k => breakpoints.has(k));\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Transition Config Helpers\n// ════════════════════════════════════════════════════════════════\n\n/** Extract the transition verb from a TransitionConfig (string or object). */\nfunction getTransitionVerb(config: TransitionConfig): NavigationTransition {\n  if (typeof config === 'string') return config;\n  return (config as TransitionObject).transition;\n}\n\n/** Extract the ephemeral modifier from a TransitionConfig. */\nfunction isEphemeral(config: TransitionConfig): boolean {\n  if (typeof config === 'string') return false;\n  return (config as TransitionObject).ephemeral === true;\n}\n\n/** Extract the persistent modifier from a TransitionConfig. */\nfunction isPersistent(config: TransitionConfig): boolean {\n  if (typeof config === 'string') return false;\n  return (config as TransitionObject).persistent === true;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Default Fallback Transitions\n// ════════════════════════════════════════════════════════════════\n\nconst FRAMEWORK_FALLBACK_TRANSITION = NavigationTransition.PUSH;\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Policy Resolver\n// ════════════════════════════════════════════════════════════════\n\nexport class NavigationPolicyResolver {\n\n  /**\n   * Resolve a navigation event to a concrete result.\n   *\n   * @param context - Input signals: source zone, operation, viewport, overrides, etc.\n   * @param layout - The app's NavigationLayout configuration.\n   * @returns What the controller should do: target zone, transition, appearance, collapse state.\n   */\n  resolve(context: NavigationResolutionContext, layout: NavigationLayout): NavigationResolutionResult {\n    const resolvedTransition = this.resolveTransition(context, layout);\n    const transitionVerb = getTransitionVerb(resolvedTransition);\n    const ephemeral = isEphemeral(resolvedTransition);\n    const persistent = isPersistent(resolvedTransition);\n\n    const targetZone = this.deriveTargetZone(transitionVerb, context, layout, persistent);\n\n    // ─── Surface coercion: EMBEDDED never becomes THE PAGE ─────────────\n    // `ResourceOperationFrontendSurface.EMBEDDED` is contractually a view\n    // \"rendered within a host — overlay/drill-in when standalone\". PRIMARY is\n    // not a host; it is the addressable page surface. The transition chain is\n    // keyed by core semantics only (an app cannot author \"embedded READ →\n    // overlay\" in `transitions`), so when the chain resolves EMBEDDED content\n    // onto PRIMARY we escalate to OVERLAY here — the same escalation posture\n    // `resolveSplitTarget` already uses when no adjacent zone exists. Explicit\n    // pane outcomes (SPLIT → secondary/companion) and overlay outcomes are\n    // hosts and pass through untouched, as does every non-resource content\n    // navigation (`operationSurface` is undefined there).\n    if (\n      context.operationSurface === ResourceOperationFrontendSurface.EMBEDDED\n      && targetZone === NavigationZoneName.PRIMARY\n      // …EXCEPT for INPLACE, which is not the page either — it is the one transition that places no\n      // content in a zone at all, and `deriveTargetZone` only reports PRIMARY for it because \"the\n      // source zone\" is the closest thing that function can say about an element-level outcome.\n      //\n      // Without this exemption the coercion silently rewrote every EMBEDDED inline transition into\n      // an overlay BEFORE the controller could hand it to the element host — so the inline-edit kit\n      // would have gone on not editing inline, one layer further down than the defect it replaced,\n      // and the surface most likely to author `inplace` (a row's EMBEDDED update) is exactly the one\n      // it would have hit. Found by driving the real controller; a resolver-level test would not\n      // have shown it, because at the resolver an overlay is a perfectly good answer.\n      && transitionVerb !== NavigationTransition.INPLACE\n    ) {\n      return {\n        targetZone: NavigationZone.OVERLAY,\n        transition: NavigationTransition.OVERLAY,\n        appearance: this.deriveAppearance(NavigationTransition.OVERLAY, context, layout),\n        collapsed: false,\n        ephemeral: ephemeral || undefined,\n      };\n    }\n\n    const appearance = this.deriveAppearance(transitionVerb, context, layout);\n    const collapsed = this.checkCollapse(targetZone, context, layout);\n\n    return { targetZone, transition: transitionVerb, appearance, collapsed, ephemeral: ephemeral || undefined };\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Step 0–5: Transition Resolution Chain\n  // ──────────────────────────────────────────────────────────────\n\n  private resolveTransition(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): TransitionConfig {\n    // Step 1 — Per-resource operation override (highest priority)\n    const overrideResult = this.checkOperationOverrides(context);\n    if (overrideResult) return overrideResult;\n\n    // Step 1.5 — An AUTHORED action presentation.\n    //\n    // Ranked here, immediately below `navigationOverrides` and above every app-level default,\n    // because both are authored ON THIS OPERATION and the override is the more specific of the two:\n    // it names the zone, the appearance and the viewport, so an author who wrote one meant it. The\n    // presentation axis says only what KIND of chrome the action wants, which is exactly why it\n    // yields to the instrument that says more.\n    //\n    // A relationship- or zone-level transition, by contrast, is a default for a WHOLE CLASS of\n    // navigations, and an operation that has declared its own presentation is not asking for the\n    // class default.\n    if (context.actionPresentationIsAuthored === true && context.actionPresentationTransition !== undefined) {\n      return context.actionPresentationTransition;\n    }\n\n    // Step 2 — Per-relationship transition\n    if (context.relationshipTransition !== undefined) {\n      return context.relationshipTransition;\n    }\n\n    // Step 3 — Global viewport override\n    const viewportOverride = this.checkViewportOverride(context, layout);\n    if (viewportOverride) return viewportOverride;\n\n    // Step 4 — Source config transitions[operation]\n    const sourceTransitions = this.getSourceTransitions(context, layout);\n    if (sourceTransitions) {\n      const transitionConfig = this.getTransitionBySemanticKey(sourceTransitions, context);\n      if (transitionConfig) return transitionConfig;\n    }\n\n    // Step 4.5 — A DERIVED action presentation.\n    //\n    // Below every authored configuration and above the framework fallback ONLY. The derivation is\n    // the framework's guess about an operation nobody configured, so it may improve the default and\n    // must never override a decision an app already made — an app whose zone `transitions` route\n    // this operation somewhere keeps that routing, unchanged.\n    //\n    // In practice this is the step that turns \"a custom action with two fields\" from a full page\n    // into an overlay, which is the whole point of the axis.\n    if (context.actionPresentationTransition !== undefined) {\n      return context.actionPresentationTransition;\n    }\n\n    // Step 5 — Framework fallback\n    return FRAMEWORK_FALLBACK_TRANSITION;\n  }\n\n  /**\n   * Step 1: Check per-resource operation overrides.\n   * First-match wins. Matches on fromZone + viewport discriminators.\n   */\n  private checkOperationOverrides(\n    context: NavigationResolutionContext,\n  ): TransitionConfig | undefined {\n    if (!context.operationOverrides?.length) return undefined;\n\n    for (const override of context.operationOverrides) {\n      if (this.overrideMatches(override, context)) {\n        return override.transition;\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * Match an override against the current context.\n   * Both `fromZone` and `viewport` must match when specified.\n   */\n  private overrideMatches(\n    override: NavigationOperationOverride,\n    context: NavigationResolutionContext,\n  ): boolean {\n    if (override.fromZone !== undefined && override.fromZone !== context.sourceZone) {\n      return false;\n    }\n    if (override.viewport !== undefined && override.viewport !== context.viewport) {\n      return false;\n    }\n    return true;\n  }\n\n  /**\n   * Step 3: Check global viewport override.\n   * Reads `layout[viewport].transitions[operation]`.\n   */\n  private checkViewportOverride(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): TransitionConfig | undefined {\n    if (context.viewport === ViewportBreakpoint.DESKTOP) return undefined;\n\n    const viewportBlock = layout[context.viewport as ViewportBreakpoint.MOBILE | ViewportBreakpoint.VERT_TABLET];\n    if (!viewportBlock?.transitions) return undefined;\n\n    return this.getTransitionBySemanticKey(viewportBlock.transitions, context);\n  }\n\n  /**\n   * Transition maps are keyed by core semantics, not arbitrary operation ids.\n   * Custom addressable operations therefore resolve through their effective core\n   * semantic while literal core operations still match directly.\n   */\n  private getTransitionBySemanticKey(\n    transitions: ZoneTransitions,\n    context: NavigationResolutionContext,\n  ): TransitionConfig | undefined {\n    const transitionKey = context.effectiveOperation\n      ?? (Object.values(CoreResourceOperation).includes(context.operation as CoreResourceOperation)\n        ? context.operation as CoreResourceOperation\n        : undefined);\n\n    if (!transitionKey) {\n      return undefined;\n    }\n\n    return transitions[transitionKey];\n  }\n\n  /**\n   * Step 4: Get the transition map from the appropriate source config.\n   * Three distinct branches based on source type.\n   */\n  private getSourceTransitions(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): ZoneTransitions | undefined {\n    if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE) {\n      return layout.appLevel?.transitions;\n    }\n    if (context.sourceZone === 'overlay') {\n      return layout.fromOverlay?.transitions;\n    }\n    const zoneConfig = layout.zones[context.sourceZone as NavigationZoneName];\n    return zoneConfig?.transitions;\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Target Zone Derivation\n  // ──────────────────────────────────────────────────────────────\n\n  /**\n   * Derive the target zone from the resolved transition verb.\n   *\n   * - push/replace → same zone (primary for appLevel/overlay sources)\n   * - split → first available adjacent zone (secondary, then companion)\n   * - split(persistent) → companion specifically\n   * - overlay → OVERLAY\n   * - inplace → same zone (no stack change)\n   * - promote → primary\n   */\n  private deriveTargetZone(\n    transition: NavigationTransition,\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n    persistent: boolean,\n  ): NavigationZone {\n    switch (transition) {\n      case NavigationTransition.PUSH:\n      case NavigationTransition.REPLACE:\n      case NavigationTransition.INPLACE:\n        return this.getStructuralSourceZone(context);\n\n      case NavigationTransition.SPLIT:\n        return this.resolveSplitTarget(context, layout, persistent);\n\n      case NavigationTransition.OVERLAY:\n        return NavigationZone.OVERLAY;\n\n      case NavigationTransition.PROMOTE:\n        return NavigationZoneName.PRIMARY;\n\n      default:\n        return NavigationZoneName.PRIMARY;\n    }\n  }\n\n  /**\n   * For push/replace/inplace: return the source zone as a structural zone.\n   * AppLevel and overlay sources map to primary.\n   */\n  private getStructuralSourceZone(context: NavigationResolutionContext): NavigationZone {\n    if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE || context.sourceZone === 'overlay') {\n      return NavigationZoneName.PRIMARY;\n    }\n    return context.sourceZone;\n  }\n\n  /**\n   * Resolve the target zone for a SPLIT transition.\n   * Persistent splits always target companion. Non-persistent splits\n   * target the first available adjacent zone.\n   * Falls back to overlay if no adjacent zone is declared in config.\n   */\n  private resolveSplitTarget(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n    persistent: boolean,\n  ): NavigationZone {\n    if (persistent) {\n      return layout.zones.companion ? NavigationZoneName.COMPANION : NavigationZone.OVERLAY;\n    }\n\n    // Prefer secondary if declared, otherwise companion, otherwise escalate to overlay\n    if (layout.zones.secondary) {\n      if (!context.zoneOccupancy?.[NavigationZoneName.SECONDARY]) {\n        return NavigationZoneName.SECONDARY;\n      }\n      // Secondary occupied — try companion\n      if (layout.zones.companion && !context.zoneOccupancy?.[NavigationZoneName.COMPANION]) {\n        return NavigationZoneName.COMPANION;\n      }\n      // Both occupied — push into secondary (replace existing content)\n      return NavigationZoneName.SECONDARY;\n    }\n\n    if (layout.zones.companion) {\n      return NavigationZoneName.COMPANION;\n    }\n\n    // No adjacent zones declared — escalate to overlay\n    return NavigationZone.OVERLAY;\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Appearance Derivation\n  // ──────────────────────────────────────────────────────────────\n\n  /**\n   * Derive visual appearance from zone config, resolved for the current viewport.\n   * Only overlay and split transitions have meaningful appearance.\n   */\n  private deriveAppearance(\n    transition: NavigationTransition,\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): OverlayAppearance | SplitAppearance | undefined {\n    if (transition !== NavigationTransition.OVERLAY && transition !== NavigationTransition.SPLIT) {\n      return undefined;\n    }\n\n    // Check operation override appearance first\n    if (context.operationOverrides?.length) {\n      for (const override of context.operationOverrides) {\n        if (this.overrideMatches(override, context) && override.appearance !== undefined) {\n          return resolveViewportDiscriminated(override.appearance, context.viewport) as\n            OverlayAppearance | SplitAppearance | undefined;\n        }\n      }\n    }\n\n    // Read from source zone's appearance config\n    const zoneAppearance = this.getSourceAppearance(context, layout);\n    if (transition === NavigationTransition.OVERLAY) {\n      return resolveViewportDiscriminated(zoneAppearance?.overlay, context.viewport) ?? OverlayAppearance.DIALOG;\n    }\n    if (transition === NavigationTransition.SPLIT) {\n      return resolveViewportDiscriminated(zoneAppearance?.split, context.viewport) ?? SplitAppearance.PANEL;\n    }\n\n    return undefined;\n  }\n\n  /** Get the appearance config from the appropriate source. */\n  private getSourceAppearance(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): ZoneAppearance | undefined {\n    if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE) {\n      return layout.appLevel?.appearance;\n    }\n    if (context.sourceZone === 'overlay') {\n      // FromOverlayConfig has no appearance — overlays within overlays shouldn't happen\n      return undefined;\n    }\n    return layout.zones[context.sourceZone as NavigationZoneName]?.appearance;\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Responsive Collapse Check\n  // ──────────────────────────────────────────────────────────────\n\n  /**\n   * Check if the target zone is responsively collapsed at the current viewport.\n   * Only secondary and companion zones can collapse. Primary never collapses.\n   * Overlay is not a structural zone — it cannot collapse.\n   */\n  private checkCollapse(\n    targetZone: NavigationZone,\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): boolean {\n    if (targetZone === NavigationZone.OVERLAY || targetZone === NavigationZoneName.PRIMARY) {\n      return false;\n    }\n    if (context.viewport === ViewportBreakpoint.DESKTOP) {\n      return false;\n    }\n\n    const zoneConfig = layout.zones[targetZone as NavigationZoneName];\n    if (!zoneConfig?.responsiveCollapse) return false;\n\n    const collapseMode = resolveViewportDiscriminated(zoneConfig.responsiveCollapse, context.viewport);\n    return collapseMode !== undefined;\n  }\n}\n\n/** Singleton instance for use across the frontend. */\nexport const navigationPolicyResolver = new NavigationPolicyResolver();\n"]}
+{"version":3,"file":"navigation-policy-resolver.service.js","sourceRoot":"","sources":["../../../../src/core/navigation/navigation-policy-resolver.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Navigation Policy Resolver — v3 zone-first, operation-driven resolution.\n *\n * Given a source context (zone, appLevel, or overlay), an operation, and the\n * navigation layout config, determines:\n * - Which transition verb to apply (push, replace, split, overlay, inplace, promote)\n * - Which zone the content lands in (derived from the transition verb)\n * - What visual appearance to use (dialog/sheet/drawer for overlay, panel/drawer for split)\n * - Whether the target zone is responsively collapsed at the current viewport, and — since #411 —\n *   APPLYING that collapse (push into primary, or overlay) rather than merely reporting it\n * - Whether the push would exceed `maxDepth`, escalating it to an overlay if so\n *\n * Resolution chain (first match wins):\n * 1. Per-resource operation override (highest priority)\n * 2. Per-relationship transition\n * 3. Global viewport override\n * 4. Source context transitions[operation]\n * 5. Framework hardcoded fallback\n *\n * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md\n */\n\nimport {\n  CoreResourceOperation,\n  NavigationTransition,\n  NavigationZoneName,\n  ResponsiveCollapseMode,\n  ResourceOperationFrontendSurface,\n  OverlayAppearance,\n  SplitAppearance,\n  type NavigationLayout,\n  type TransitionConfig,\n  type TransitionObject,\n  type ZoneTransitions,\n  type ZoneAppearance,\n  type ViewportDiscriminated,\n} from '@wildo-ai/saas-models';\nimport type { NavigationOperationOverride } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport { ViewportBreakpoint } from '@wildo-ai/zod-decorators';\nimport {\n  NavigationZone,\n  APP_LEVEL_NAVIGATION_SOURCE,\n  type NavigationResolutionContext,\n  type NavigationResolutionResult,\n} from './navigation.schemas';\n\n\n// ════════════════════════════════════════════════════════════════\n// Viewport-Discriminated Resolution Utility\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Viewport priority order — when no exact match exists for the current\n * viewport, fall back to the next more general breakpoint, then to desktop.\n */\nconst VIEWPORT_FALLBACK_ORDER: Record<ViewportBreakpoint, ViewportBreakpoint[]> = {\n  [ViewportBreakpoint.MOBILE]: [ViewportBreakpoint.MOBILE, ViewportBreakpoint.VERT_TABLET, ViewportBreakpoint.DESKTOP],\n  [ViewportBreakpoint.VERT_TABLET]: [ViewportBreakpoint.VERT_TABLET, ViewportBreakpoint.DESKTOP],\n  [ViewportBreakpoint.DESKTOP]: [ViewportBreakpoint.DESKTOP],\n};\n\n/**\n * Resolve a `ViewportDiscriminated<T>` value for the current viewport.\n *\n * If the value is a plain `T`, it applies at all viewports. If it's a\n * viewport-keyed partial record, resolves by trying the current viewport\n * first, then falling back through larger breakpoints.\n *\n * Returns `undefined` when no match is found (caller applies defaults).\n */\nexport function resolveViewportDiscriminated<T>(\n  value: ViewportDiscriminated<T> | undefined,\n  viewport: ViewportBreakpoint,\n): T | undefined {\n  if (value === undefined || value === null) return undefined;\n  if (typeof value !== 'object' || !isViewportRecord(value)) return value as T;\n\n  const record = value as Partial<Record<ViewportBreakpoint, T>>;\n  const fallbacks = VIEWPORT_FALLBACK_ORDER[viewport] ?? [viewport];\n  for (const bp of fallbacks) {\n    if (bp in record) return record[bp];\n  }\n  return undefined;\n}\n\n/**\n * Type guard: distinguishes a viewport-keyed record from a plain enum value.\n * Viewport breakpoints are strings like '<md', '<lg', '>=lg'. If any key\n * matches a known breakpoint, the value is a viewport record.\n */\nfunction isViewportRecord<T>(value: unknown): value is Partial<Record<ViewportBreakpoint, T>> {\n  if (typeof value !== 'object' || value === null) return false;\n  const keys = Object.keys(value);\n  const breakpoints = new Set(Object.values(ViewportBreakpoint) as string[]);\n  return keys.length > 0 && keys.some(k => breakpoints.has(k));\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Transition Config Helpers\n// ════════════════════════════════════════════════════════════════\n\n/** Extract the transition verb from a TransitionConfig (string or object). */\nfunction getTransitionVerb(config: TransitionConfig): NavigationTransition {\n  if (typeof config === 'string') return config;\n  return (config as TransitionObject).transition;\n}\n\n/** Extract the ephemeral modifier from a TransitionConfig. */\nfunction isEphemeral(config: TransitionConfig): boolean {\n  if (typeof config === 'string') return false;\n  return (config as TransitionObject).ephemeral === true;\n}\n\n/** Extract the persistent modifier from a TransitionConfig. */\nfunction isPersistent(config: TransitionConfig): boolean {\n  if (typeof config === 'string') return false;\n  return (config as TransitionObject).persistent === true;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Default Fallback Transitions\n// ════════════════════════════════════════════════════════════════\n\nconst FRAMEWORK_FALLBACK_TRANSITION = NavigationTransition.PUSH;\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Policy Resolver\n// ════════════════════════════════════════════════════════════════\n\nexport class NavigationPolicyResolver {\n\n  /**\n   * Resolve a navigation event to a concrete result.\n   *\n   * @param context - Input signals: source zone, operation, viewport, overrides, etc.\n   * @param layout - The app's NavigationLayout configuration.\n   * @returns What the controller should do: target zone, transition, appearance, collapse state.\n   */\n  resolve(context: NavigationResolutionContext, layout: NavigationLayout): NavigationResolutionResult {\n    const resolvedTransition = this.resolveTransition(context, layout);\n    const transitionVerb = getTransitionVerb(resolvedTransition);\n    const ephemeral = isEphemeral(resolvedTransition);\n    const persistent = isPersistent(resolvedTransition);\n\n    const targetZone = this.deriveTargetZone(transitionVerb, context, layout, persistent);\n\n    // ─── Surface coercion: EMBEDDED never becomes THE PAGE ─────────────\n    // `ResourceOperationFrontendSurface.EMBEDDED` is contractually a view\n    // \"rendered within a host — overlay/drill-in when standalone\". PRIMARY is\n    // not a host; it is the addressable page surface. The transition chain is\n    // keyed by core semantics only (an app cannot author \"embedded READ →\n    // overlay\" in `transitions`), so when the chain resolves EMBEDDED content\n    // onto PRIMARY we escalate to OVERLAY here — the same escalation posture\n    // `resolveSplitTarget` already uses when no adjacent zone exists. Explicit\n    // pane outcomes (SPLIT → secondary/companion) and overlay outcomes are\n    // hosts and pass through untouched, as does every non-resource content\n    // navigation (`operationSurface` is undefined there).\n    if (\n      context.operationSurface === ResourceOperationFrontendSurface.EMBEDDED\n      && targetZone === NavigationZoneName.PRIMARY\n      // …EXCEPT for INPLACE, which is not the page either — it is the one transition that places no\n      // content in a zone at all, and `deriveTargetZone` only reports PRIMARY for it because \"the\n      // source zone\" is the closest thing that function can say about an element-level outcome.\n      //\n      // Without this exemption the coercion silently rewrote every EMBEDDED inline transition into\n      // an overlay BEFORE the controller could hand it to the element host — so the inline-edit kit\n      // would have gone on not editing inline, one layer further down than the defect it replaced,\n      // and the surface most likely to author `inplace` (a row's EMBEDDED update) is exactly the one\n      // it would have hit. Found by driving the real controller; a resolver-level test would not\n      // have shown it, because at the resolver an overlay is a perfectly good answer.\n      && transitionVerb !== NavigationTransition.INPLACE\n    ) {\n      return {\n        targetZone: NavigationZone.OVERLAY,\n        transition: NavigationTransition.OVERLAY,\n        appearance: this.deriveAppearance(NavigationTransition.OVERLAY, context, layout),\n        collapsed: false,\n        ephemeral: ephemeral || undefined,\n      };\n    }\n\n    const collapseMode = this.resolveCollapseMode(targetZone, context, layout);\n\n    /*\n     * ─── RESPONSIVE COLLAPSE IS APPLIED HERE, not merely reported ───────────────────────────────\n     *\n     * Until 2026-09-08 (#411) `collapsed` was computed, returned, and read by nobody: the controller\n     * logged it, and `NavigationContentAreas` hid the secondary and companion zones unconditionally\n     * on mobile. So content routed to a collapsed zone went into a zone that would not render, and\n     * the declared choice between `PUSH` and `OVERLAY` had no effect whatsoever.\n     *\n     * Collapse is a PLACEMENT decision, which is what this resolver answers, so it belongs here\n     * rather than in the controller. Applying it downstream would mean two places deciding where\n     * content lands, and the second would have to re-derive the first's inputs.\n     *\n     *   PUSH    -> the content joins PRIMARY's stack. The user sees it in context, and back pops\n     *              to primary's previous content — the enum's own contract.\n     *   OVERLAY -> the content opens over primary as a sheet/dialog. Dismiss returns underneath.\n     *\n     * The appearance is derived AFTER the retarget, from the transition the content actually gets:\n     * deriving it from the pre-collapse verb would give an overlay a SPLIT appearance\n     * (`panel`/`drawer`), which the overlay container cannot render.\n     *\n     * `collapsed` stays in the result as INFORMATION — it is what lets a reader (and a test) tell a\n     * PUSH that was authored from a PUSH that is a collapsed SPLIT, which otherwise look identical.\n     */\n    const collapsedTargetZone = collapseMode === ResponsiveCollapseMode.OVERLAY\n      ? NavigationZone.OVERLAY\n      : collapseMode === ResponsiveCollapseMode.PUSH\n        ? NavigationZoneName.PRIMARY\n        : targetZone;\n    const collapsedTransition = collapseMode === ResponsiveCollapseMode.OVERLAY\n      ? NavigationTransition.OVERLAY\n      : collapseMode === ResponsiveCollapseMode.PUSH\n        ? NavigationTransition.PUSH\n        : transitionVerb;\n\n    /*\n     * ─── maxDepth: a push past the ceiling becomes an overlay ───────────────────────────────────\n     *\n     * `NavigationLayout.maxDepth` documents itself as \"when a zone's stack depth reaches `maxDepth`,\n     * the next `push` opens an overlay instead\" and, until 2026-09-08 (#411), NOTHING read it — the\n     * field and its per-relationship override were declared, validated and inert, so an application\n     * that set it got unbounded stacks and no error.\n     *\n     * It is applied AFTER the collapse above, and the order is load-bearing in both directions: a\n     * collapsed SPLIT becomes a push into PRIMARY, which must then answer to PRIMARY's ceiling\n     * rather than to the ceiling of the zone it was authored for; and an authored push that is\n     * already escalated to an overlay cannot then be collapsed, because an overlay is not a\n     * structural zone and has no `responsiveCollapse`.\n     *\n     * \"Reaches\" is `>=`, taken from the declaration verbatim: at `maxDepth: 3` the third entry is\n     * the last one pushed, and the fourth navigation opens an overlay.\n     */\n    const depthCeiling = context.relationshipMaxDepth ?? layout.maxDepth;\n    const targetDepth = collapsedTargetZone === NavigationZone.OVERLAY\n      ? undefined\n      : context.zoneDepth[collapsedTargetZone as NavigationZoneName];\n    const exceedsDepthCeiling = depthCeiling !== undefined\n      && targetDepth !== undefined\n      && collapsedTransition === NavigationTransition.PUSH\n      && targetDepth >= depthCeiling;\n\n    const finalTargetZone = exceedsDepthCeiling ? NavigationZone.OVERLAY : collapsedTargetZone;\n    const finalTransition = exceedsDepthCeiling ? NavigationTransition.OVERLAY : collapsedTransition;\n\n    const appearance = this.deriveAppearance(finalTransition, context, layout);\n    const collapsed = collapseMode !== undefined;\n\n    /*\n     * Overlay behaviour rides with the appearance because it is answered by the same declaration and\n     * is meaningless without it — only an OVERLAY has a page behind to block, dismiss on, or dim.\n     */\n    const overlayBehavior = finalTransition === NavigationTransition.OVERLAY\n      ? this.resolveOverlayBehavior(context)\n      : undefined;\n    return {\n      targetZone: finalTargetZone,\n      transition: finalTransition,\n      appearance,\n      overlayBehavior,\n      collapsed,\n      collapsedFromZone: collapsed ? (targetZone as NavigationZoneName) : undefined,\n      ephemeral: ephemeral || undefined,\n    };\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Step 0–5: Transition Resolution Chain\n  // ──────────────────────────────────────────────────────────────\n\n  private resolveTransition(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): TransitionConfig {\n    /*\n     * ## Coverage: steps 1, 1.5 and 2 run in unit tests only — accepted deliberately, 2026-09-08 (#467)\n     *\n     * Three of this chain's seven steps are authored by NEITHER dogfood application: per-operation\n     * navigation overrides (step 1), authored action presentations (step 1.5) and per-relationship\n     * transitions (step 2). The resolver reads all three; nothing in either application declares\n     * them, so they have never executed outside their own unit tests.\n     *\n     * Nothing is wrong. The gap is that no application has yet had a reason to declare them, and\n     * buying the proof would mean authoring a declaration in order to test it — which proves the\n     * harness more than the product. Weighed and accepted; the project's usual bar for a shipped\n     * subsystem is knowingly not met for these three.\n     *\n     * **What would change the answer:** an application authoring any one of the three. That author\n     * is the first party to execute the step, and should read a surprise there as expected.\n     *\n     * Do NOT narrow the chain to the steps something uses today — that was the third option and it\n     * was not chosen. The ordering below is load-bearing and its reasoning is written out at each\n     * step; a shorter chain would lose it.\n     */\n\n    // Step 1 — Per-resource operation override (highest priority)\n    const overrideResult = this.checkOperationOverrides(context);\n    if (overrideResult) return overrideResult;\n\n    // Step 1.5 — An AUTHORED action presentation.\n    //\n    // Ranked here, immediately below `navigationOverrides` and above every app-level default,\n    // because both are authored ON THIS OPERATION and the override is the more specific of the two:\n    // it names the zone, the appearance and the viewport, so an author who wrote one meant it. The\n    // presentation axis says only what KIND of chrome the action wants, which is exactly why it\n    // yields to the instrument that says more.\n    //\n    // A relationship- or zone-level transition, by contrast, is a default for a WHOLE CLASS of\n    // navigations, and an operation that has declared its own presentation is not asking for the\n    // class default.\n    if (context.actionPresentationIsAuthored === true && context.actionPresentationTransition !== undefined) {\n      return context.actionPresentationTransition;\n    }\n\n    // Step 2 — Per-relationship transition\n    if (context.relationshipTransition !== undefined) {\n      return context.relationshipTransition;\n    }\n\n    // Step 3 — Global viewport override\n    const viewportOverride = this.checkViewportOverride(context, layout);\n    if (viewportOverride) return viewportOverride;\n\n    // Step 4 — Source config transitions[operation]\n    const sourceTransitions = this.getSourceTransitions(context, layout);\n    if (sourceTransitions) {\n      const transitionConfig = this.getTransitionBySemanticKey(sourceTransitions, context);\n      if (transitionConfig) return transitionConfig;\n    }\n\n    // Step 4.5 — A DERIVED action presentation.\n    //\n    // Below every authored configuration and above the framework fallback ONLY. The derivation is\n    // the framework's guess about an operation nobody configured, so it may improve the default and\n    // must never override a decision an app already made — an app whose zone `transitions` route\n    // this operation somewhere keeps that routing, unchanged.\n    //\n    // In practice this is the step that turns \"a custom action with two fields\" from a full page\n    // into an overlay, which is the whole point of the axis.\n    if (context.actionPresentationTransition !== undefined) {\n      return context.actionPresentationTransition;\n    }\n\n    // Step 5 — Framework fallback\n    return FRAMEWORK_FALLBACK_TRANSITION;\n  }\n\n  /**\n   * Step 1: Check per-resource operation overrides.\n   * First-match wins. Matches on fromZone + viewport discriminators.\n   */\n  private checkOperationOverrides(\n    context: NavigationResolutionContext,\n  ): TransitionConfig | undefined {\n    if (!context.operationOverrides?.length) return undefined;\n\n    for (const override of context.operationOverrides) {\n      if (this.overrideMatches(override, context)) {\n        return override.transition;\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * Match an override against the current context.\n   * Both `fromZone` and `viewport` must match when specified.\n   */\n  private overrideMatches(\n    override: NavigationOperationOverride,\n    context: NavigationResolutionContext,\n  ): boolean {\n    if (override.fromZone !== undefined && override.fromZone !== context.sourceZone) {\n      return false;\n    }\n    if (override.viewport !== undefined && override.viewport !== context.viewport) {\n      return false;\n    }\n    return true;\n  }\n\n  /**\n   * Step 3: Check global viewport override.\n   * Reads `layout[viewport].transitions[operation]`.\n   */\n  private checkViewportOverride(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): TransitionConfig | undefined {\n    if (context.viewport === ViewportBreakpoint.DESKTOP) return undefined;\n\n    const viewportBlock = layout[context.viewport as ViewportBreakpoint.MOBILE | ViewportBreakpoint.VERT_TABLET];\n    if (!viewportBlock?.transitions) return undefined;\n\n    return this.getTransitionBySemanticKey(viewportBlock.transitions, context);\n  }\n\n  /**\n   * Transition maps are keyed by core semantics, not arbitrary operation ids.\n   * Custom addressable operations therefore resolve through their effective core\n   * semantic while literal core operations still match directly.\n   */\n  private getTransitionBySemanticKey(\n    transitions: ZoneTransitions,\n    context: NavigationResolutionContext,\n  ): TransitionConfig | undefined {\n    const transitionKey = context.effectiveOperation\n      ?? (Object.values(CoreResourceOperation).includes(context.operation as CoreResourceOperation)\n        ? context.operation as CoreResourceOperation\n        : undefined);\n\n    if (!transitionKey) {\n      return undefined;\n    }\n\n    return transitions[transitionKey];\n  }\n\n  /**\n   * Step 4: Get the transition map from the appropriate source config.\n   * Three distinct branches based on source type.\n   */\n  private getSourceTransitions(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): ZoneTransitions | undefined {\n    if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE) {\n      return layout.appLevel?.transitions;\n    }\n    if (context.sourceZone === 'overlay') {\n      return layout.fromOverlay?.transitions;\n    }\n    const zoneConfig = layout.zones[context.sourceZone as NavigationZoneName];\n    return zoneConfig?.transitions;\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Target Zone Derivation\n  // ──────────────────────────────────────────────────────────────\n\n  /**\n   * Derive the target zone from the resolved transition verb.\n   *\n   * - push/replace → same zone (primary for appLevel/overlay sources)\n   * - split → first available adjacent zone (secondary, then companion)\n   * - split(persistent) → companion specifically\n   * - overlay → OVERLAY\n   * - inplace → same zone (no stack change)\n   * - promote → primary\n   */\n  private deriveTargetZone(\n    transition: NavigationTransition,\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n    persistent: boolean,\n  ): NavigationZone {\n    switch (transition) {\n      case NavigationTransition.PUSH:\n      case NavigationTransition.REPLACE:\n      case NavigationTransition.INPLACE:\n        return this.getStructuralSourceZone(context);\n\n      case NavigationTransition.SPLIT:\n        return this.resolveSplitTarget(context, layout, persistent);\n\n      case NavigationTransition.OVERLAY:\n        return NavigationZone.OVERLAY;\n\n      case NavigationTransition.PROMOTE:\n        return NavigationZoneName.PRIMARY;\n\n      default:\n        return NavigationZoneName.PRIMARY;\n    }\n  }\n\n  /**\n   * For push/replace/inplace: return the source zone as a structural zone.\n   * AppLevel and overlay sources map to primary.\n   */\n  private getStructuralSourceZone(context: NavigationResolutionContext): NavigationZone {\n    if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE || context.sourceZone === 'overlay') {\n      return NavigationZoneName.PRIMARY;\n    }\n    return context.sourceZone;\n  }\n\n  /**\n   * Resolve the target zone for a SPLIT transition.\n   * Persistent splits always target companion. Non-persistent splits\n   * target the first available adjacent zone.\n   * Falls back to overlay if no adjacent zone is declared in config.\n   */\n  private resolveSplitTarget(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n    persistent: boolean,\n  ): NavigationZone {\n    if (persistent) {\n      return layout.zones.companion ? NavigationZoneName.COMPANION : NavigationZone.OVERLAY;\n    }\n\n    // Prefer secondary if declared, otherwise companion, otherwise escalate to overlay\n    if (layout.zones.secondary) {\n      if (!context.zoneOccupancy?.[NavigationZoneName.SECONDARY]) {\n        return NavigationZoneName.SECONDARY;\n      }\n      // Secondary occupied — try companion\n      if (layout.zones.companion && !context.zoneOccupancy?.[NavigationZoneName.COMPANION]) {\n        return NavigationZoneName.COMPANION;\n      }\n      // Both occupied — push into secondary (replace existing content)\n      return NavigationZoneName.SECONDARY;\n    }\n\n    if (layout.zones.companion) {\n      return NavigationZoneName.COMPANION;\n    }\n\n    // No adjacent zones declared — escalate to overlay\n    return NavigationZone.OVERLAY;\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Appearance Derivation\n  // ──────────────────────────────────────────────────────────────\n\n  /**\n   * Derive visual appearance from zone config, resolved for the current viewport.\n   * Only overlay and split transitions have meaningful appearance.\n   */\n  private deriveAppearance(\n    transition: NavigationTransition,\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): OverlayAppearance | SplitAppearance | undefined {\n    if (transition !== NavigationTransition.OVERLAY && transition !== NavigationTransition.SPLIT) {\n      return undefined;\n    }\n\n    // Check operation override appearance first\n    if (context.operationOverrides?.length) {\n      for (const override of context.operationOverrides) {\n        if (this.overrideMatches(override, context) && override.appearance !== undefined) {\n          return resolveViewportDiscriminated(override.appearance, context.viewport) as\n            OverlayAppearance | SplitAppearance | undefined;\n        }\n      }\n    }\n\n    // Read from source zone's appearance config\n    const zoneAppearance = this.getSourceAppearance(context, layout);\n    if (transition === NavigationTransition.OVERLAY) {\n      return resolveViewportDiscriminated(zoneAppearance?.overlay, context.viewport) ?? OverlayAppearance.DIALOG;\n    }\n    if (transition === NavigationTransition.SPLIT) {\n      return resolveViewportDiscriminated(zoneAppearance?.split, context.viewport) ?? SplitAppearance.PANEL;\n    }\n\n    return undefined;\n  }\n\n  /**\n   * The overlay behaviour declared by a matching per-operation override, if any.\n   *\n   * First match wins, exactly as the transition and appearance do — one override describes one\n   * situation, so reading a different override's behaviour than its transition would let a single\n   * declaration be split across two answers.\n   */\n  private resolveOverlayBehavior(\n    context: NavigationResolutionContext,\n  ): NavigationResolutionResult['overlayBehavior'] {\n    if (!context.operationOverrides?.length) return undefined;\n    for (const override of context.operationOverrides) {\n      if (this.overrideMatches(override, context) && override.overlayBehavior !== undefined) {\n        return override.overlayBehavior;\n      }\n    }\n    return undefined;\n  }\n\n  /** Get the appearance config from the appropriate source. */\n  private getSourceAppearance(\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): ZoneAppearance | undefined {\n    if (context.sourceZone === APP_LEVEL_NAVIGATION_SOURCE) {\n      return layout.appLevel?.appearance;\n    }\n    if (context.sourceZone === 'overlay') {\n      // FromOverlayConfig has no appearance — overlays within overlays shouldn't happen\n      return undefined;\n    }\n    return layout.zones[context.sourceZone as NavigationZoneName]?.appearance;\n  }\n\n  // ──────────────────────────────────────────────────────────────\n  // Responsive Collapse Check\n  // ──────────────────────────────────────────────────────────────\n\n  /**\n   * WHICH collapse the target zone is under at this viewport, or `undefined` for none.\n   *\n   * Only secondary and companion zones can collapse. Primary never collapses — it is the zone\n   * collapsed content moves INTO. Overlay is not a structural zone and cannot collapse either.\n   *\n   * This returned a BOOLEAN until 2026-09-08 (#411), and the boolean is why the whole mechanism was\n   * inert: `PUSH` and `OVERLAY` are the entire content of the declaration, and a flag that says\n   * \"collapsed\" without saying which cannot place anything. The consumer would have had to re-read\n   * `layout.zones[…].responsiveCollapse` and re-resolve the breakpoint itself — a second copy of\n   * this decision, free to disagree with the first.\n   */\n  private resolveCollapseMode(\n    targetZone: NavigationZone,\n    context: NavigationResolutionContext,\n    layout: NavigationLayout,\n  ): ResponsiveCollapseMode | undefined {\n    if (targetZone === NavigationZone.OVERLAY || targetZone === NavigationZoneName.PRIMARY) {\n      return undefined;\n    }\n    /*\n     * Collapse applies at a KNOWN narrow breakpoint, never merely at \"not desktop\".\n     *\n     * Written as `!== DESKTOP` first, and that is wrong in the one case that matters: a caller with\n     * no measured viewport yet (`currentBreakpoint: undefined` during the first frames) would have\n     * been treated as a phone and had its split collapsed into primary — a layout decision taken\n     * from a missing measurement. An unknown viewport is not a narrow one.\n     */\n    if (context.viewport !== ViewportBreakpoint.MOBILE && context.viewport !== ViewportBreakpoint.VERT_TABLET) {\n      return undefined;\n    }\n\n    const zoneConfig = layout.zones[targetZone as NavigationZoneName];\n    /*\n     * ─── An UNDECLARED collapse defaults to PUSH, and that is a decision ────────────────────────\n     *\n     * `NavigationContentAreas` renders a single zone below the mobile breakpoint — secondary and\n     * companion are not shown at all. So on a phone a zone with no `responsiveCollapse` is not\n     * \"left alone\": content routed there is placed into a zone that does not render, and the user\n     * sees nothing happen. That is what an undeclared collapse meant before #411, for every\n     * application, and it is not a behaviour anyone would choose deliberately.\n     *\n     * PUSH rather than OVERLAY because it is the conservative half of the vocabulary: the content\n     * appears in primary in context, and BACK pops to what was there before — no dismissal\n     * affordance to get wrong, and no modality over a phone-sized viewport. An application that\n     * wants the sheet declares `OVERLAY` and gets it.\n     *\n     * The alternative — keep returning `undefined` and let the content vanish — was rejected\n     * because it is the silent degradation #411 exists to remove, and because \"the zone declared\n     * nothing\" is not a reason to lose a user's navigation.\n     */\n    const declared = zoneConfig?.responsiveCollapse;\n    if (!declared) return ResponsiveCollapseMode.PUSH;\n\n    /*\n     * A viewport-discriminated declaration that names no mode for THIS breakpoint is a gap in the\n     * declaration, not a statement that the zone renders — it still would not render — so it takes\n     * the same default.\n     */\n    return resolveViewportDiscriminated(declared, context.viewport) ?? ResponsiveCollapseMode.PUSH;\n  }\n}\n\n/** Singleton instance for use across the frontend. */\nexport const navigationPolicyResolver = new NavigationPolicyResolver();\n"]}

package/dist/esm/core/navigation/navigation.schemas.d.ts

@@ -202,8 +202,8 @@ export interface NavigationContent_FlowsActorsView {
     contentType: NavigationContentType.FLOWS_ACTORS_VIEW;
     /** Reference identifier for the view definition. */
     viewRef: string;
-    /** System references for the flows/actors displayed in this view. */
-    flowsActorsSystemRefs: string[];
+    /** The flows/actors system this view displays. */
+    flowsActorsSystemRef: string;
     /** Optional context resource IDs to scope the view. */
     contextResourceIdentifiers?: Record<string, string>;
 }
@@ -300,12 +300,54 @@ export interface NavigationStackEntry {
      * Used by ContentAreas to decide how to render overlay or split content.
      */
     appearance?: OverlayAppearance | SplitAppearance;
+    /**
+     * Behaviour of an OVERLAY entry: is the page behind interactive, does touching it dismiss, is it
+     * dimmed. Three independent questions, and a companion panel needs all three answered — see
+     * `OverlayContainerConfig`, whose fields these feed.
+     *
+     * Declared per operation because it is a property of the CONTENT, not of the zone: one application
+     * legitimately has a create dialog that blocks everything and a detail sheet beside a live canvas
+     * that blocks nothing.
+     */
+    overlayBehavior?: {
+        /** Block interaction with the page behind. Default `true`. */
+        modal?: boolean;
+        /** Dismiss when the page behind is clicked. Default `true`. */
+        closeOnOutsideClick?: boolean;
+        /** Dim the page behind. Default `true`. */
+        showBackdrop?: boolean;
+    };
     /**
      * When `true`, this overlay entry auto-closes when the source zone's stack changes.
      * Set by the resolver from `TransitionConfig.ephemeral`. Only valid on overlay entries.
      * Used by NavigationContext auto-close logic.
      */
     ephemeral?: boolean;
+    /**
+     * `true` when this SECONDARY entry was opened beside a primary whose address the pane's own URL
+     * cannot re-derive (a composite view, a canvas, a chart, an engine page), so the browser URL is
+     * the HOST's address carrying this entry as `?pane=` — see `HOSTED_PANE_QUERY_PARAM` in
+     * `hosted-pane.constants.ts`.
+     *
+     * Three readers key on it, and each needs it for a different reason: the zone-dependency cleanup
+     * keeps a hosted pane beside a primary it cannot otherwise relate to (the relevance rule is
+     * relationship-aware and a composite view has no relationships); the URL reconciler closes the
+     * pane when the `pane` parameter leaves the URL (browser back); and the route-owner lookup never
+     * lets a hosted entry claim a BARE browser URL, because its address is only ever reachable in the
+     * composed form.
+     */
+    hostedPane?: boolean;
+    /**
+     * The zone this entry was AUTHORED for, when a responsive collapse placed it somewhere else.
+     *
+     * A `secondary` split on a phone lands in PRIMARY (under `ResponsiveCollapseMode.PUSH`) or in
+     * OVERLAY (under `OVERLAY`), and `zone` above records where it actually IS. This records where it
+     * belongs, so widening the viewport can migrate it back — the behaviour `ResponsiveCollapseMode`
+     * documents and, before #411, nothing implemented because nothing recorded the origin.
+     *
+     * Absent on every entry that was placed where it was authored, which is the common case.
+     */
+    collapsedFromZone?: NavigationZoneName;
 }
 /**
  * Runtime state of a single navigation zone.
@@ -387,11 +429,47 @@ export interface NavigationResolutionResult {
      */
     appearance?: OverlayAppearance | SplitAppearance;
     /**
-     * Whether the target zone is currently in responsive collapse mode at this viewport.
-     * When `true`, the controller should apply the zone's `responsiveCollapse` behavior
-     * (push into primary or show as overlay) instead of normal zone rendering.
+     * Behaviour of an OVERLAY entry: is the page behind interactive, does touching it dismiss, is it
+     * dimmed. Three independent questions, and a companion panel needs all three answered — see
+     * `OverlayContainerConfig`, whose fields these feed.
+     *
+     * Declared per operation because it is a property of the CONTENT, not of the zone: one application
+     * legitimately has a create dialog that blocks everything and a detail sheet beside a live canvas
+     * that blocks nothing.
+     */
+    overlayBehavior?: {
+        /** Block interaction with the page behind. Default `true`. */
+        modal?: boolean;
+        /** Dismiss when the page behind is clicked. Default `true`. */
+        closeOnOutsideClick?: boolean;
+        /** Dim the page behind. Default `true`. */
+        showBackdrop?: boolean;
+    };
+    /**
+     * Whether this placement IS a responsive collapse — the zone the content was headed for is
+     * collapsed at this viewport, so `targetZone` and `transition` above are already the collapsed
+     * outcome (PRIMARY + push, or OVERLAY + overlay) rather than the authored one.
+     *
+     * It is a REPORT, not an instruction. It said the opposite until 2026-09-08 (#411) — "the
+     * controller should apply the zone's `responsiveCollapse` behavior" — and no controller ever did,
+     * which is exactly how the mechanism stayed inert for as long as it existed. The resolver applies
+     * it now, because placement is what the resolver answers.
+     *
+     * What it is still FOR: telling a collapsed placement apart from an authored one. A collapsed
+     * SPLIT and an authored PUSH produce an identical `targetZone`/`transition` pair, and only this
+     * flag (with `collapsedFromZone`) distinguishes them.
      */
     collapsed: boolean;
+    /**
+     * The zone this content was headed for before the collapse retargeted it — `secondary` or
+     * `companion`. Present only when `collapsed` is `true`.
+     *
+     * `ResponsiveCollapseMode`'s contract is that "when viewport grows back past the breakpoint,
+     * collapsed content migrates back to its original zone", and an entry cannot migrate back to a
+     * zone nothing recorded. The controller writes this onto the stack entry as
+     * `NavigationStackEntry.collapsedFromZone`.
+     */
+    collapsedFromZone?: NavigationZoneName;
     /**
      * When `true`, this overlay entry should auto-close when its source zone's stack changes.
      * Derived from `TransitionConfig.ephemeral`. Only meaningful for overlay transitions.
@@ -467,6 +545,24 @@ export interface NavigationResolutionContext {
     viewport: ViewportBreakpoint;
     /** Which structural zones currently have content. Used for SPLIT target heuristic. */
     zoneOccupancy: Partial<Record<NavigationZoneName, boolean>>;
+    /**
+     * Current stack DEPTH per structural zone — what `NavigationLayout.maxDepth` is measured against.
+     *
+     * Distinct from `zoneOccupancy`, which is this same measurement flattened to a boolean. Both are
+     * projected from ONE read of the zone state in the controller, so they cannot disagree; the depth
+     * exists separately because "does the zone hold anything" and "how deep is it" are different
+     * questions and the second cannot be recovered from the first.
+     */
+    zoneDepth: Partial<Record<NavigationZoneName, number>>;
+    /**
+     * `RelationshipDisplayConfig.maxDepth` for the relationship that triggered this navigation, when
+     * one did — the per-relationship override of the layout's global `maxDepth`.
+     *
+     * Supplied by the caller alongside `relationshipTransition`, because the relationship's display
+     * config is a fact about the CALL SITE (a nested container knows which relationship it renders)
+     * and the resolver has no way to recover it from a resource type and an operation.
+     */
+    relationshipMaxDepth?: number;
     /** Currently focused zone — tiebreaker for SPLIT target selection. */
     focusedZone?: NavigationZoneName;
 }
@@ -535,7 +631,7 @@ export interface NavigationItemBase {
     section?: string;
     /** Sidebar display policy (always visible, collapsible, etc.). */
     displayPolicy?: SidebarItemDisplayPolicy;
-    /** Typed reference to a registered notification-badge definition (see `SidebarItem`). */
+    /** Badge KEY (`<scope>:<identifier>`) naming a registered notification-badge definition (see `SidebarItem`). */
     notificationBadgeRef?: string;
     /** Keyboard shortcut hint displayed in UI (e.g., "⌘K"). */
     shortcut?: string;
@@ -585,8 +681,8 @@ export interface ViewNavigationItem extends NavigationItemBase {
     contextResourceIdentifiers?: Record<string, string>;
     /** Optional chart-route query params for standalone chart URL_PARAM bindings. */
     urlParamValues?: Record<string, string>;
-    /** FlowsActorsView: system references for the flows/actors displayed. */
-    flowsActorsSystemRefs?: string[];
+    /** FlowsActorsView: the flows/actors system displayed. */
+    flowsActorsSystemRef?: string;
     /** FullCustomView: reference to the registered custom component. */
     fullCustomComponentRef?: string;
     /** Required features configuration for feature gating. */
@@ -710,7 +806,7 @@ export declare const NavigationContentSchema: z.ZodDiscriminatedUnion<[z.ZodObje
 }, z.core.$strip>, z.ZodObject<{
     contentType: z.ZodLiteral<NavigationContentType.FLOWS_ACTORS_VIEW>;
     viewRef: z.ZodString;
-    flowsActorsSystemRefs: z.ZodArray<z.ZodString>;
+    flowsActorsSystemRef: z.ZodString;
     contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>, z.ZodObject<{
     contentType: z.ZodLiteral<NavigationContentType.EXECUTION_VIEW>;
@@ -825,7 +921,7 @@ export declare const NavigationStackEntrySchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         contentType: z.ZodLiteral<NavigationContentType.FLOWS_ACTORS_VIEW>;
         viewRef: z.ZodString;
-        flowsActorsSystemRefs: z.ZodArray<z.ZodString>;
+        flowsActorsSystemRef: z.ZodString;
         contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         contentType: z.ZodLiteral<NavigationContentType.EXECUTION_VIEW>;
@@ -897,6 +993,7 @@ export declare const NavigationStackEntrySchema: z.ZodObject<{
     transition: z.ZodEnum<typeof NavigationTransition>;
     appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>>;
     ephemeral: z.ZodOptional<z.ZodBoolean>;
+    hostedPane: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export {};
 //# sourceMappingURL=navigation.schemas.d.ts.map