@wildo-ai/saas-frontend-lib 1.1.5 → 1.1.7

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

@@ -18,7 +18,7 @@
  * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md
  */
 import { z } from 'zod';
-import { NavigationTransition, NavigationZoneName, OverlayAppearance, SplitAppearance, ParentDisplay, } from '@wildo-ai/saas-models';
+import { NavigationTransition, NavigationZoneName, OverlayAppearance, ParentDisplay, } from '@wildo-ai/saas-models';
 import { ApplicationLevelComponentType, } from '../../core/config/app-level-components.frontend.schemas.js';
 import { EnginePageRef } from '../../core/config/launcher-items.frontend.schemas.js';
 import { CoreResourceOperation, RequiredFeaturesConfigSchema, } from '@wildo-ai/saas-models';
@@ -93,6 +93,125 @@ export var NavigationSource;
     NavigationSource["URL_SYNC"] = "url_sync";
 })(NavigationSource || (NavigationSource = {}));
 // ════════════════════════════════════════════════════════════════
+// Resolution Result (output of the resolver)
+// ════════════════════════════════════════════════════════════════
+/**
+ * WHICH TIER of the transition-resolution chain decided the verb.
+ *
+ * The chain has seven steps and every one of them can answer `PUSH`. So the OUTCOME alone cannot
+ * tell an authored decision from the framework's default, and for a year nothing recorded which had
+ * spoken: the resolver carries 324 lines of code, thirteen decision methods and — until 2026-09-25 —
+ * not one log statement or provenance field. Every "why did it land there?" question was therefore
+ * answered by simulating the chain by hand against the application's layout, which is what eight
+ * consecutive navigation diagnoses cost that week.
+ *
+ * Recording it is free, because the deciding tier is known at each return site of
+ * `resolveTransition`. What it buys is two things a log line could not:
+ *
+ * 1. **A test can pin the TIER, not merely the answer.** A pin that asserts `PUSH` passes when the
+ *    right verb arrives from the wrong step — `positive-evidence-must-name-its-target.md` exactly.
+ *    Steps 1, 1.5 and 2 are authored by no application today, so their unit tests are the only thing
+ *    that exercises them, and those tests could not previously distinguish "step 2 answered" from
+ *    "step 2 was skipped and the framework default happened to agree".
+ * 2. **A reader sees the tier in one field** instead of re-deriving it from the layout.
+ */
+export var NavigationTransitionSource;
+(function (NavigationTransitionSource) {
+    /** Step 1 — a `navigationOverrides` entry on the operation matched. The most specific instrument. */
+    NavigationTransitionSource["OPERATION_OVERRIDE"] = "operation-override";
+    /** Step 1.5 — the operation declares an AUTHORED `ResourceOperationActionPresentation`. */
+    NavigationTransitionSource["AUTHORED_ACTION_PRESENTATION"] = "authored-action-presentation";
+    /** Step 2 — the relationship this navigation traverses declares `inParentNavigation.transition`. */
+    NavigationTransitionSource["RELATIONSHIP"] = "relationship";
+    /** Step 3 — `layout[mobile|vertTablet].transitions` answered for this viewport. */
+    NavigationTransitionSource["VIEWPORT_OVERRIDE"] = "viewport-override";
+    /** Step 4 — the SOURCE's own declared map answered (`zones[source]`, `appLevel` or `fromOverlay`). */
+    NavigationTransitionSource["SOURCE_TRANSITIONS"] = "source-transitions";
+    /**
+     * Step 4 — the source was an OVERLAY that declares no answer for this operation, so PRIMARY's map
+     * answered instead.
+     *
+     * Distinct from {@link SOURCE_TRANSITIONS} because it is the one tier that reads a map the author
+     * did not write for this source. It is the fallback added on 2026-09-25 after the workbench's
+     * `family` backlink — an ADDRESSABLE artifact clicked inside a popup — fell past an absent
+     * `fromOverlay` to the framework default and took the whole page instead of opening beside the
+     * list. Naming it separately is what lets a reader see that the answer came from somewhere the
+     * layout does not literally say it.
+     */
+    NavigationTransitionSource["OVERLAY_FALLBACK_TO_PRIMARY"] = "overlay-fallback-to-primary";
+    /** Step 4.5 — a DERIVED action presentation (the framework's guess for an unconfigured action). */
+    NavigationTransitionSource["DERIVED_ACTION_PRESENTATION"] = "derived-action-presentation";
+    /** Step 5 — nothing answered; {@link NavigationTransition.PUSH}. */
+    NavigationTransitionSource["FRAMEWORK_DEFAULT"] = "framework-default";
+})(NavigationTransitionSource || (NavigationTransitionSource = {}));
+/**
+ * A decision taken AFTER the verb that changed where the content actually landed.
+ *
+ * Every member is a place the resolver silently overrules the authored verb. They are legitimate —
+ * each exists for a measured reason written at its site — and they are exactly what makes a
+ * navigation outcome hard to explain, because the layout says one thing and the screen shows
+ * another with nothing in between to read.
+ *
+ * Several can apply to one resolution and the order is the order they are applied in, so the array
+ * reads as the story of the placement.
+ */
+export var NavigationPlacementAdjustment;
+(function (NavigationPlacementAdjustment) {
+    /**
+     * An `EMBEDDED` view resolved onto a structural zone and was escalated to an overlay, because a
+     * structural zone is not a host — it already holds something a reader is reading.
+     */
+    NavigationPlacementAdjustment["EMBEDDED_COERCED_TO_OVERLAY"] = "embedded-coerced-to-overlay";
+    /** A `SPLIT` found the adjacent pane FREE and opened it. The pane is a host; nothing was taken over. */
+    NavigationPlacementAdjustment["SPLIT_OPENED_FREE_PANE"] = "split-opened-free-pane";
+    /**
+     * A `SPLIT` found every adjacent pane OCCUPIED and replaced the content of one.
+     *
+     * This is the second, opposite meaning of `SPLIT` that the enum cannot express, and naming it is
+     * the whole reason this vocabulary exists. It is correct for a list/detail application — clicking
+     * another record swaps the reading pane, exactly as a mailbox does — and it is a surface being
+     * taken over, which is why the EMBEDDED coercion above reads occupancy rather than the verb.
+     */
+    NavigationPlacementAdjustment["SPLIT_REPLACED_OCCUPIED_PANE"] = "split-replaced-occupied-pane";
+    /**
+     * A `SPLIT` was authored and the layout declares NO adjacent zone, so it became an overlay.
+     *
+     * Silent by design and the most surprising thing in the resolver: an author who writes
+     * `transition: SPLIT` and forgets the `secondary` zone gets a dialog and no diagnostic. Reported
+     * at boot since 2026-09-25 by `collectNavigationLayoutDiagnostics`, and named here so a runtime
+     * reader sees it too.
+     */
+    NavigationPlacementAdjustment["SPLIT_ESCALATED_NO_ADJACENT_ZONE"] = "split-escalated-no-adjacent-zone";
+    /**
+     * A `persistent` split escalated because the layout declares no `companion` — **even though a
+     * `secondary` may be declared and free.** A persistent split targets companion SPECIFICALLY.
+     *
+     * Its own member because the REMEDY differs: telling this author to "declare `zones.secondary`"
+     * sends them to change something they already have. The resolver knows which branch it took, so
+     * the distinction is carried here rather than re-derived by whoever reports it — one message
+     * covered both branches for a few hours on 2026-09-25 and was false for this one.
+     */
+    NavigationPlacementAdjustment["PERSISTENT_SPLIT_ESCALATED_NO_COMPANION"] = "persistent-split-escalated-no-companion";
+    /** The target zone is collapsed at this viewport and its `responsiveCollapse` said `PUSH`. */
+    NavigationPlacementAdjustment["RESPONSIVE_COLLAPSE_PUSH"] = "responsive-collapse-push";
+    /** The target zone is collapsed at this viewport and its `responsiveCollapse` said `OVERLAY`. */
+    NavigationPlacementAdjustment["RESPONSIVE_COLLAPSE_OVERLAY"] = "responsive-collapse-overlay";
+    /** The push would have passed `maxDepth`, so it opened an overlay instead. */
+    NavigationPlacementAdjustment["DEPTH_CEILING_ESCALATED_TO_OVERLAY"] = "depth-ceiling-escalated-to-overlay";
+    /**
+     * An `INPLACE` transition resolved on a surface with no element-level host — a detail page, a
+     * breadcrumb, a picker — so it degraded to an overlay.
+     *
+     * It is an ADJUSTMENT rather than a tier because the tier that answered `INPLACE` is unchanged and
+     * still worth knowing. Until 2026-09-25 the controller expressed this by re-resolving with a
+     * SYNTHETIC `operationOverrides: [{ transition: OVERLAY }]`, which cost two things: the provenance
+     * then read `operation-override`, telling a reader an author had declared something no author
+     * declared; and the synthetic array REPLACED the real one, so an operation that authored an
+     * `appearance` or `overlayBehavior` beside its transition silently lost it.
+     */
+    NavigationPlacementAdjustment["INPLACE_DEGRADED_TO_OVERLAY"] = "inplace-degraded-to-overlay";
+})(NavigationPlacementAdjustment || (NavigationPlacementAdjustment = {}));
+// ════════════════════════════════════════════════════════════════
 // Navigation Item Types (app-level sidebar, command menu, etc.)
 // ════════════════════════════════════════════════════════════════
 /**
@@ -262,7 +381,7 @@ export const NavigationStackEntrySchema = z.object({
     initiator: NavigationInitiatorContextSchema.optional(),
     navigationSource: z.enum(NavigationSource),
     transition: z.enum(NavigationTransition),
-    appearance: z.union([z.enum(OverlayAppearance), z.enum(SplitAppearance)]).optional(),
+    appearance: z.enum(OverlayAppearance).optional(),
     ephemeral: z.boolean().optional(),
     hostedPane: z.boolean().optional(),
 });

package/dist/esm/core/navigation/navigation.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.schemas.js","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Navigation — Frontend Runtime Types\n *\n * Runtime types for zone state, navigation stacks/tabs, events, content,\n * initiator context, and resolution results. These are the types the\n * navigation controller, context, and rendering layer operate on.\n *\n * Configuration types (what developers configure) live in\n * `@wildo-ai/saas-models` — `navigation.shared.schemas.ts`.\n * This file imports config enums from there and defines runtime state on top.\n *\n * Key runtime concepts:\n * - **NavigationZone**: type union = `NavigationZoneName | 'overlay'` — extends the 3\n *   configurable zones with the implicit overlay destination (no enum duplication)\n * - **NavigationState**: per-zone stack/tab state + separate overlay stack\n * - **NavigationResolutionResult**: output of the resolver, consumed by the controller\n *\n * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md\n */\n\nimport React from 'react';\nimport { z } from 'zod';\nimport {\n  NavigationZoneContentModel,\n  NavigationTransition,\n  NavigationZoneName,\n  OverlayAppearance,\n  SplitAppearance,\n  ParentDisplay,\n  ZoneEmptyBehavior,\n  type RelationshipDisplayInChildView,\n  type TransitionConfig,\n  type ViewportDiscriminated,\n} from '@wildo-ai/saas-models';\nimport { ViewportBreakpoint } from '@wildo-ai/zod-decorators';\nimport {\n  ApplicationLevelComponentType,\n  SidebarItemDisplayPolicy,\n} from '~wildo-frontend-lib/core/config/app-level-components.frontend.schemas';\nimport { EnginePageRef } from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\nimport type { NavigationOperationOverride, FrontendResourceConfiguration_Operation } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport {\n  CoreResourceOperation,\n  ResourceOperationFrontendSurface,\n  type RequiredFeaturesConfig,\n  RequiredFeaturesConfigSchema,\n  FeatureUnavailabilityBehavior,\n  FeatureUnavailabilityReason,\n  type FeatureUpgradeOption,\n} from '@wildo-ai/saas-models';\nimport {\n  FrontendResourceOperationContextSchema,\n  type FrontendResourceOperationContext,\n} from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport type {\n  InsertedChartDeclaration,\n  ResolvedInsertedChartDescriptor,\n} from '~wildo-frontend-lib/core/config/chart-view.frontend.schemas';\n\n\n// ════════════════════════════════════════════════════════════════\n// Runtime Enums\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Runtime zone identifiers — all possible destinations for navigation content.\n *\n * Extends `NavigationZoneName` (the 3 configurable zones) with `OVERLAY`,\n * which is an implicit runtime destination (not a configurable zone).\n *\n * Implemented as a const object (spread of `NavigationZoneName` + `OVERLAY`)\n * to avoid duplicating the 3 structural zone values already defined in\n * `NavigationZoneName`. Use `NavigationZone.PRIMARY`, `NavigationZone.OVERLAY`, etc.\n */\nconst OVERLAY_ZONE = 'overlay' as const;\n\nexport const NavigationZone = {\n  ...NavigationZoneName,\n  /**\n   * Implicit floating layer above all zones. Not a configurable zone —\n   * always available as a destination for `overlay` transitions.\n   * Content renders as dialog, sheet, or drawer based on the source zone's appearance config.\n   */\n  OVERLAY: OVERLAY_ZONE,\n} as const;\n\n/** Union of all runtime zone identifiers (3 structural + overlay). */\nexport type NavigationZone = NavigationZoneName | typeof OVERLAY_ZONE;\n\n/** Zod schema for `NavigationZone` — validates any structural zone name or `'overlay'`. */\nexport const NavigationZoneSchema = z.union([z.enum(NavigationZoneName), z.literal(OVERLAY_ZONE)]);\n\n/**\n * All structural zones (excludes overlay).\n * Used for iterating over zones that have configuration and state.\n */\nexport const NAVIGATION_STRUCTURAL_ZONES: readonly NavigationZoneName[] = Object.values(NavigationZoneName);\n\n/**\n * Navigation source for app-shell actions (sidebar, command palette, hotkey, toast, notification).\n * Used alongside `NavigationZone` to form the complete set of navigation origins.\n * App-level navigation causes a layout reset: primary replaced, other zones cleared.\n */\nexport const APP_LEVEL_NAVIGATION_SOURCE = 'appLevel' as const;\n\n/**\n * What kind of content is being navigated to.\n * Frontend-only — used by navigation stacks, resolution, and content rendering.\n */\nexport enum NavigationContentType {\n  RESOURCE_OPERATION = 'resource_operation',\n  COMPOSITE_VIEW = 'composite_view',\n  CHART_VIEW = 'chart_view',\n  FULL_CUSTOM_VIEW = 'full_custom_view',\n  FLOWS_ACTORS_VIEW = 'flows_actors_view',\n  EXECUTION_VIEW = 'execution_view',\n  CUSTOM_COMPONENT = 'custom_component',\n  ENGINE_PAGE = 'engine_page',\n  SETTINGS_HUB = 'settings_hub',\n  INLINE_CREATE = 'inline_create',\n  ERROR_MODAL = 'error_modal',\n}\n\n/**\n * How a navigation entry was created — tracks the origin of each stack entry.\n *\n * Used to coordinate between controller-initiated (programmatic) and\n * URL-initiated (browser back/forward, direct link) navigation.\n * The controller needs to know if a navigation event came from URL sync\n * to avoid infinite loops (URL change → navigate → URL change → ...).\n */\nexport enum NavigationSource {\n  /** Navigation triggered programmatically by useNavigationController. */\n  CONTROLLER = 'controller',\n  /** Navigation triggered by URL change (bookmark, back button, direct link). */\n  URL_SYNC = 'url_sync',\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Initiator Context\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Lightweight relationship metadata carried on navigation events.\n *\n * When navigation is triggered by a parent→child relationship traversal\n * (e.g., clicking a related item in a parent's detail view), this carries\n * just enough relationship info for the destination component to configure\n * its parent reference display (breadcrumb, badge, etc.).\n *\n * Intentionally NOT the full `ResourceRelationship` — avoids importing the\n * entire relationship schema tree into navigation events (Nav-2 decision).\n */\nexport interface NavigationSourceRelationship {\n  /** The resource type of the parent in this relationship. */\n  parentResourceType: string;\n  /** The specific parent instance ID, if navigating from a specific parent record. */\n  parentResourceId?: string;\n  /** The resource type of the child in this relationship. */\n  childResourceType: string;\n  /** FK field used to traverse this edge when disambiguation is required. */\n  foreignKeyField?: string;\n  /** Stable parent→child edge key for navigation-time identity. */\n  relationshipEdgeKey?: string;\n  /**\n   * The `inChildView` display config from the relationship definition.\n   * Controls how the parent reference appears in the child's view (breadcrumb, badge, etc.).\n   */\n  inChildView?: RelationshipDisplayInChildView;\n}\n\n/**\n * Source context for a navigation event — WHO triggered the navigation and FROM WHERE.\n *\n * The resolver uses `sourceZone` as the primary input signal to determine\n * which transition applies. The same operation produces different transitions\n * depending on where the user currently is.\n */\nexport interface NavigationInitiatorContext {\n  /**\n   * Where the navigation was triggered from.\n   *\n   * - A `NavigationZone` value: navigation from within a structural zone or overlay\n   * - `APP_LEVEL_NAVIGATION_SOURCE`: navigation from the app shell (sidebar,\n   *   command palette, hotkey, toast action, notification click). Causes a layout reset.\n   *\n   * This replaces the old `type: NavigationInitiatorType` + `sourcePane: NavigationPane`\n   * pattern with a single, explicit field.\n   */\n  sourceZone: NavigationZone | typeof APP_LEVEL_NAVIGATION_SOURCE;\n  /**\n   * Which app-level launcher triggered the navigation.\n   * Only relevant when `sourceZone === APP_LEVEL_NAVIGATION_SOURCE`. Examples: sidebar click,\n   * command palette selection, quick action button, hotkey.\n   */\n  launcher?: ApplicationLevelComponentType;\n  /** The operation that produced this navigation (read, create, delete, etc.). */\n  sourceOperation?: CoreResourceOperation;\n  /**\n   * When navigation was triggered by traversing a parent→child relationship.\n   * Carries lightweight relationship info so the destination can configure\n   * parent reference display (breadcrumb, badge, summary card).\n   */\n  sourceRelationship?: NavigationSourceRelationship;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Content (discriminated union — what's being shown)\n// ════════════════════════════════════════════════════════════════\n\n/** Content representing a resource operation (list, read, create, etc.). */\nexport interface NavigationContent_ResourceOperation {\n  contentType: NavigationContentType.RESOURCE_OPERATION;\n  /** Fully resolved resource context: resource type, operation, params, record ID, etc. */\n  resourceContext: FrontendResourceOperationContext;\n}\n\n/** Content representing a composite view (dashboard, overview, etc.). */\nexport interface NavigationContent_CompositeView {\n  contentType: NavigationContentType.COMPOSITE_VIEW;\n  /** Reference identifier for the composite view definition. */\n  viewRef: string;\n  /** Optional context resource IDs to pass to the view for scoping/filtering. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a chart view (data visualization). */\nexport interface NavigationContent_ChartView {\n  contentType: NavigationContentType.CHART_VIEW;\n  /** Reference identifier for the chart view definition. */\n  viewRef: string;\n  /** Optional context resource IDs to scope the chart's data. */\n  contextResourceIdentifiers?: Record<string, string>;\n  /** Optional route-derived URL params for standalone chart URL_PARAM bindings. */\n  urlParamValues?: Record<string, string>;\n  /** Optional feature-gating metadata for chart-stack rendering. */\n  requiredFeatures?: RequiredFeaturesConfig;\n  /** Optional pre-resolved chart surface definition for inserted/routed charts. */\n  viewDefinition?: InsertedChartDeclaration;\n  /** Optional pre-resolved descriptor for inserted/routed charts. */\n  runtimeDescriptor?: ResolvedInsertedChartDescriptor;\n}\n\n/** Content representing a full custom view (developer-provided component). */\nexport interface NavigationContent_FullCustomView {\n  contentType: NavigationContentType.FULL_CUSTOM_VIEW;\n  /** Reference identifier for the view definition. */\n  viewRef: string;\n  /** Reference to the custom React component registered for this view. */\n  fullCustomComponentRef: string;\n  /** Optional context resource IDs to pass to the component. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a flows & actors view (AI workflows, agent execution). */\nexport interface NavigationContent_FlowsActorsView {\n  contentType: NavigationContentType.FLOWS_ACTORS_VIEW;\n  /** Reference identifier for the view definition. */\n  viewRef: string;\n  /** The flows/actors system this view displays. */\n  flowsActorsSystemRef: string;\n  /** Optional context resource IDs to scope the view. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing an execution view (framework-owned execution host). */\nexport interface NavigationContent_ExecutionView {\n  contentType: NavigationContentType.EXECUTION_VIEW;\n  /** Reference identifier for the execution view definition. */\n  viewRef: string;\n  /** Optional context resource IDs to scope the execution view. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a generic app-level custom component. */\nexport interface NavigationContent_CustomComponent {\n  contentType: NavigationContentType.CUSTOM_COMPONENT;\n  /** Registered component reference to materialize. */\n  componentRef: string;\n  /** Optional context resource IDs to pass to the component. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a router-backed engine page. */\nexport interface NavigationContent_EnginePage {\n  contentType: NavigationContentType.ENGINE_PAGE;\n  pageRef: EnginePageRef;\n}\n\n/**\n * Content representing the unified Settings Hub.\n *\n * Always rendered in the overlay zone (DIALOG appearance, persistent — NOT\n * ephemeral, so it survives source-zone changes and closes only on explicit\n * dismiss). The optional `sectionRef` pre-selects which section opens; when\n * omitted the hub opens at its default section. URL-addressable via\n * `/settings/:sectionRef`, and `/settings/:sectionRef/:subTabRef` when the\n * section renders sub-tabs.\n */\nexport interface NavigationContent_SettingsHub {\n  contentType: NavigationContentType.SETTINGS_HUB;\n  sectionRef?: string;\n  /**\n   * Which sub-tab of `sectionRef` opens. Only meaningful for a `SUB_TABS` target; a ref the\n   * section does not declare is IGNORED rather than refused, so a stale or hand-typed link still\n   * opens the section at its first tab instead of an error page.\n   */\n  subTabRef?: string;\n}\n\n/** Content representing a typed sidebar inline-create flow. */\nexport interface NavigationContent_InlineCreate {\n  contentType: NavigationContentType.INLINE_CREATE;\n  resourceContext: FrontendResourceOperationContext;\n  defaultValues: Record<string, unknown>;\n}\n\n/**\n * Content representing an error modal pushed through the overlay stack.\n *\n * Carries the error itself, not text: the modal is pushed by `ErrorContext`, which is mounted ABOVE the\n * `I18nProvider`, so nothing there can produce words a person should read. The renderer resolves\n * `wildoError` through `useUserFacingErrorMessage`. The `message` and `context` fields were removed (#1159):\n * they held the raw i18n reference and the request context, and both reached the screen.\n */\nexport interface NavigationContent_ErrorModal {\n  contentType: NavigationContentType.ERROR_MODAL;\n  /** Technical discriminator for the stack-entry key only — never rendered. */\n  errorType: string;\n  wildoError: unknown;\n}\n\n/**\n * Discriminated union of all navigation content types.\n * Discriminated on `contentType` for clean narrowing.\n * Every navigation stack entry carries exactly one of these.\n */\nexport type NavigationContent =\n  | NavigationContent_ResourceOperation\n  | NavigationContent_CompositeView\n  | NavigationContent_ChartView\n  | NavigationContent_FullCustomView\n  | NavigationContent_FlowsActorsView\n  | NavigationContent_ExecutionView\n  | NavigationContent_CustomComponent\n  | NavigationContent_EnginePage\n  | NavigationContent_SettingsHub\n  | NavigationContent_InlineCreate\n  | NavigationContent_ErrorModal;\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Stack Entry\n// ════════════════════════════════════════════════════════════════\n\n/**\n * A single entry in a zone's navigation stack (or overlay stack).\n *\n * Each entry represents one piece of content that was navigated to.\n * The stack maintains navigation history within a zone for back navigation.\n * In tabbed zones, entries represent parallel tabs (not a depth stack).\n */\nexport interface NavigationStackEntry {\n  /** Unique identifier for this stack entry (UUID). */\n  id: string;\n  /** The content being displayed in this entry. */\n  content: NavigationContent;\n  /**\n   * URL path that represents this navigation state.\n   * Used for URL serialization, deep linking, and browser history.\n   * Every navigation state must be URL-addressable.\n   */\n  urlPath?: string;\n  /** Timestamp (ms since epoch) when this entry was created. For ordering and debugging. */\n  timestamp: number;\n  /** Which zone this entry lives in. */\n  zone: NavigationZone;\n  /** The context that triggered this navigation (source zone, operation, relationship). */\n  initiator?: NavigationInitiatorContext;\n  /** Whether this entry was created by the controller or by URL sync. */\n  navigationSource: NavigationSource;\n  /**\n   * The transition verb that placed this entry (push, replace, split, overlay, promote).\n   * Note: `inplace` does not produce a stack entry (it transforms an element in the\n   * current view without changing zone state), so it will never appear here.\n   */\n  transition: NavigationTransition;\n  /**\n   * Visual appearance for this entry's transition.\n   * Set by the resolver from zone appearance config. Only meaningful for\n   * overlay entries (dialog/sheet/drawer) and split entries (panel/drawer).\n   * Used by ContentAreas to decide how to render overlay or split content.\n   */\n  appearance?: OverlayAppearance | SplitAppearance;\n  /**\n   * Behaviour of an OVERLAY entry: is the page behind interactive, does touching it dismiss, is it\n   * dimmed. Three independent questions, and a companion panel needs all three answered — see\n   * `OverlayContainerConfig`, whose fields these feed.\n   *\n   * Declared per operation because it is a property of the CONTENT, not of the zone: one application\n   * legitimately has a create dialog that blocks everything and a detail sheet beside a live canvas\n   * that blocks nothing.\n   */\n  overlayBehavior?: {\n    /** Block interaction with the page behind. Default `true`. */\n    modal?: boolean;\n    /** Dismiss when the page behind is clicked. Default `true`. */\n    closeOnOutsideClick?: boolean;\n    /** Dim the page behind. Default `true`. */\n    showBackdrop?: boolean;\n  };\n  /**\n   * When `true`, this overlay entry auto-closes when the source zone's stack changes.\n   * Set by the resolver from `TransitionConfig.ephemeral`. Only valid on overlay entries.\n   * Used by NavigationContext auto-close logic.\n   */\n  ephemeral?: boolean;\n  /**\n   * `true` when this SECONDARY entry was opened beside a primary whose address the pane's own URL\n   * cannot re-derive (a composite view, a canvas, a chart, an engine page), so the browser URL is\n   * the HOST's address carrying this entry as `?pane=` — see `HOSTED_PANE_QUERY_PARAM` in\n   * `hosted-pane.constants.ts`.\n   *\n   * Three readers key on it, and each needs it for a different reason: the zone-dependency cleanup\n   * keeps a hosted pane beside a primary it cannot otherwise relate to (the relevance rule is\n   * relationship-aware and a composite view has no relationships); the URL reconciler closes the\n   * pane when the `pane` parameter leaves the URL (browser back); and the route-owner lookup never\n   * lets a hosted entry claim a BARE browser URL, because its address is only ever reachable in the\n   * composed form.\n   */\n  hostedPane?: boolean;\n  /**\n   * The zone this entry was AUTHORED for, when a responsive collapse placed it somewhere else.\n   *\n   * A `secondary` split on a phone lands in PRIMARY (under `ResponsiveCollapseMode.PUSH`) or in\n   * OVERLAY (under `OVERLAY`), and `zone` above records where it actually IS. This records where it\n   * belongs, so widening the viewport can migrate it back — the behaviour `ResponsiveCollapseMode`\n   * documents and, before #411, nothing implemented because nothing recorded the origin.\n   *\n   * Absent on every entry that was placed where it was authored, which is the common case.\n   */\n  collapsedFromZone?: NavigationZoneName;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Zone State (runtime)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Runtime state of a single navigation zone.\n *\n * Each zone independently tracks its navigation stack and visibility.\n * For tabbed zones, `activeTabId` identifies which tab is currently displayed.\n *\n * Zone lifecycle states (not an enum — derived from config + runtime):\n * - **Inactive**: zone not declared in config. Doesn't exist in DOM.\n * - **Hidden**: zone exists but not visible (collapsed, or `onEmpty: ZoneEmptyBehavior.COLLAPSE` with nothing pushed).\n * - **Empty**: zone visible but no content. Only when `onEmpty: 'emptyState'`.\n * - **Active**: zone has content and is visible.\n */\nexport interface NavigationZoneState {\n  /** Which zone this state belongs to. */\n  zone: NavigationZone;\n  /**\n   * The zone's navigation stack.\n   * - In `single` content model: depth stack. Top entry is visible. Back pops.\n   * - In `NavigationZoneContentModel.TABBED` content model: tab entries. All are \"open\", one is active.\n   */\n  stack: NavigationStackEntry[];\n  /**\n   * Whether this zone is currently rendered in the DOM and visible.\n   * `false` when the zone is collapsed (responsive), or is empty with\n   * `onEmpty: ZoneEmptyBehavior.COLLAPSE` and nothing has been pushed into it yet.\n   */\n  isVisible: boolean;\n  /**\n   * For `NavigationZoneContentModel.TABBED` zones — the ID of the currently active tab entry.\n   * References `NavigationStackEntry.id`. When `undefined`, the zone is in single mode.\n   * Using ID (not index) for stability when tabs are reordered or closed.\n   */\n  activeTabId?: string;\n}\n\n/**\n * Full runtime navigation state.\n *\n * Zones hold their own stack/tab state keyed by `NavigationZoneName` (the 3 structural\n * zones). Overlay is separate because it's not a configurable zone — it's an implicit\n * floating layer that can hold a stack of its own (push within overlay).\n */\nexport interface NavigationState {\n  /**\n   * Per-zone state for the 3 structural zones (primary, secondary, companion).\n   * Keyed by `NavigationZoneName` — NOT `NavigationZone` (which includes overlay).\n   */\n  zones: Record<NavigationZoneName, NavigationZoneState>;\n  /**\n   * Overlay stack — content shown in the floating layer above all zones.\n   * Supports push depth within the overlay (e.g., navigating to a related item\n   * from within a create dialog pushes onto the overlay stack).\n   * When the stack empties, the overlay dismisses.\n   */\n  overlay: NavigationStackEntry[];\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Resolution Result (output of the resolver)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Output of the navigation policy resolver — tells the controller exactly what to do.\n *\n * The resolver takes (sourceZone, operation, resourceConfig, viewport) as inputs\n * and produces this result by walking the resolution chain:\n * 1. Per-resource operation override\n * 2. Per-relationship inParentNavigation.transition\n * 3. Global viewport override\n * 4. Source zone's transitions[operation]\n * 5. Framework fallback\n */\nexport interface NavigationResolutionResult {\n  /** Which zone the content should be placed in. */\n  targetZone: NavigationZone;\n  /** The transition verb to apply. */\n  transition: NavigationTransition;\n  /**\n   * Visual appearance for the transition. Only meaningful for:\n   * - `overlay` transitions: `OverlayAppearance` (dialog, sheet, or drawer)\n   * - `split` transitions: `SplitAppearance` (panel or drawer)\n   * `undefined` for `push`, `replace`, `inplace`, and `promote`\n   * (`push`/`replace`/`promote` fill the zone; `inplace` transforms an element).\n   */\n  appearance?: OverlayAppearance | SplitAppearance;\n  /**\n   * Behaviour of an OVERLAY entry: is the page behind interactive, does touching it dismiss, is it\n   * dimmed. Three independent questions, and a companion panel needs all three answered — see\n   * `OverlayContainerConfig`, whose fields these feed.\n   *\n   * Declared per operation because it is a property of the CONTENT, not of the zone: one application\n   * legitimately has a create dialog that blocks everything and a detail sheet beside a live canvas\n   * that blocks nothing.\n   */\n  overlayBehavior?: {\n    /** Block interaction with the page behind. Default `true`. */\n    modal?: boolean;\n    /** Dismiss when the page behind is clicked. Default `true`. */\n    closeOnOutsideClick?: boolean;\n    /** Dim the page behind. Default `true`. */\n    showBackdrop?: boolean;\n  };\n  /**\n   * Whether this placement IS a responsive collapse — the zone the content was headed for is\n   * collapsed at this viewport, so `targetZone` and `transition` above are already the collapsed\n   * outcome (PRIMARY + push, or OVERLAY + overlay) rather than the authored one.\n   *\n   * It is a REPORT, not an instruction. It said the opposite until 2026-09-08 (#411) — \"the\n   * controller should apply the zone's `responsiveCollapse` behavior\" — and no controller ever did,\n   * which is exactly how the mechanism stayed inert for as long as it existed. The resolver applies\n   * it now, because placement is what the resolver answers.\n   *\n   * What it is still FOR: telling a collapsed placement apart from an authored one. A collapsed\n   * SPLIT and an authored PUSH produce an identical `targetZone`/`transition` pair, and only this\n   * flag (with `collapsedFromZone`) distinguishes them.\n   */\n  collapsed: boolean;\n  /**\n   * The zone this content was headed for before the collapse retargeted it — `secondary` or\n   * `companion`. Present only when `collapsed` is `true`.\n   *\n   * `ResponsiveCollapseMode`'s contract is that \"when viewport grows back past the breakpoint,\n   * collapsed content migrates back to its original zone\", and an entry cannot migrate back to a\n   * zone nothing recorded. The controller writes this onto the stack entry as\n   * `NavigationStackEntry.collapsedFromZone`.\n   */\n  collapsedFromZone?: NavigationZoneName;\n  /**\n   * When `true`, this overlay entry should auto-close when its source zone's stack changes.\n   * Derived from `TransitionConfig.ephemeral`. Only meaningful for overlay transitions.\n   * The controller writes this to `NavigationStackEntry.ephemeral`.\n   */\n  ephemeral?: boolean;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Resolution Context (input to the resolver)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Input to the navigation policy resolver — all the contextual signals needed\n * to determine which transition + zone + appearance to use.\n *\n * Three fundamentally different source types select different config paths:\n * - `NavigationZoneName`: structural zone → reads `layout.zones[zone].transitions`\n * - `'appLevel'`: app shell (sidebar, command palette) → reads `layout.appLevel.transitions`\n * - `'overlay'`: from within an overlay → reads `layout.fromOverlay.transitions`\n */\nexport interface NavigationResolutionContext {\n  /**\n   * Where the navigation was triggered from. Determines which config\n   * branch the resolver reads transitions from.\n   */\n  sourceZone: NavigationZoneName | typeof APP_LEVEL_NAVIGATION_SOURCE | 'overlay';\n  /** The operation being performed (read, create, list, update, etc.). */\n  operation: CoreResourceOperation | string;\n  /**\n   * Semantic core operation for custom operations that behave like a framework\n   * core surface. Transition maps are keyed by core semantics, so resolvers must\n   * use this field instead of raw custom operation identifiers.\n   */\n  effectiveOperation?: CoreResourceOperation;\n  /** Resource type being navigated to (for per-resource override matching). */\n  resourceType?: string;\n  /**\n   * The target operation's declared frontend surface (resource content only).\n   * This is the channel that keeps navigation policy surface-aware: the\n   * resolver coerces EMBEDDED content away from PRIMARY (embedded views open\n   * in a HOST — overlay/pane — never as the page), and the controller refuses\n   * API_ONLY content outright. Replaces a former `isAddressable` boolean that\n   * was populated but read by nothing (dead channel, removed 2026-08-19).\n   */\n  operationSurface?: ResourceOperationFrontendSurface;\n  /** Per-resource operation overrides (from resource operationFrontendConfig). First match wins. */\n  operationOverrides?: NavigationOperationOverride[];\n  /**\n   * The transition the target operation's ACTION PRESENTATION resolves to, when it resolves to one\n   * at all — `MODAL` → `OVERLAY`, `PAGE` → nothing (the ordinary chain answers).\n   *\n   * The presentation axis is an ALIAS over this chain, never a parallel mechanism: it lets an author\n   * say \"an overlay\" without naming a zone, a verb and an appearance. `DIRECT`, `POPOVER` and\n   * `INLINE` do not navigate at all, so on their normal path they never reach here; `POPOVER` and\n   * `INLINE` supply an `OVERLAY` only as the DEGRADE for a host that cannot anchor or has no\n   * element to transform.\n   */\n  actionPresentationTransition?: TransitionConfig;\n  /**\n   * Was the presentation AUTHORED, or derived by the framework?\n   *\n   * It decides precedence, and the distinction is load-bearing. An authored presentation is a\n   * statement about this operation and outranks the app's relationship- and zone-level navigation\n   * defaults. A DERIVED one is the framework's guess and must yield to every configuration an app\n   * actually wrote — otherwise introducing the derivation would silently restyle navigation that\n   * apps had already tuned.\n   */\n  actionPresentationIsAuthored?: boolean;\n  /**\n   * Full transition config from the relationship's\n   * `display.inParentNavigation.transition`.\n   * Preserves lifecycle modifiers (ephemeral/persistent). `undefined` when\n   * navigation is not relationship-driven.\n   */\n  relationshipTransition?: TransitionConfig;\n  /** Current viewport breakpoint for responsive resolution. */\n  viewport: ViewportBreakpoint;\n  /**\n   * The measured width, in pixels, of the CONTENT AREA the structural zones share — not the window.\n   *\n   * The two differ by the sidebar, by any pane already open, and by whatever an embedded shell gives\n   * the application; a tall narrow column on a wide monitor is `DESKTOP` at a width no split can\n   * carry. `resolveCollapseMode` escalates a SPLIT that does not fit, exactly as it escalates one\n   * below a narrow breakpoint, so this is the measurement that makes the responsive ladder answer to\n   * the space rather than to the window.\n   *\n   * `undefined` before the first layout pass, which never escalates: an unmeasured width is not a\n   * narrow one (the same reading the viewport takes).\n   */\n  contentAreaWidth?: number;\n  /** Which structural zones currently have content. Used for SPLIT target heuristic. */\n  zoneOccupancy: Partial<Record<NavigationZoneName, boolean>>;\n  /**\n   * Current stack DEPTH per structural zone — what `NavigationLayout.maxDepth` is measured against.\n   *\n   * Distinct from `zoneOccupancy`, which is this same measurement flattened to a boolean. Both are\n   * projected from ONE read of the zone state in the controller, so they cannot disagree; the depth\n   * exists separately because \"does the zone hold anything\" and \"how deep is it\" are different\n   * questions and the second cannot be recovered from the first.\n   */\n  zoneDepth: Partial<Record<NavigationZoneName, number>>;\n  /**\n   * `RelationshipDisplayConfig.maxDepth` for the relationship that triggered this navigation, when\n   * one did — the per-relationship override of the layout's global `maxDepth`.\n   *\n   * Supplied by the caller alongside `relationshipTransition`, because the relationship's display\n   * config is a fact about the CALL SITE (a nested container knows which relationship it renders)\n   * and the resolver has no way to recover it from a resource type and an operation.\n   */\n  relationshipMaxDepth?: number;\n  /** Currently focused zone — tiebreaker for SPLIT target selection. */\n  focusedZone?: NavigationZoneName;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Feature Availability (for navigation items)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Lightweight feature availability status attached to navigation items.\n *\n * Used by sidebar, command menu, and toolbar to communicate feature gating\n * status to UI components (lock icons, disabled state, upgrade prompts).\n * Subset of the full `FeatureAvailability` from the features system.\n */\nexport interface NavigationFeatureAvailability {\n  /** Whether the feature is currently available to the user. */\n  isAvailable: boolean;\n  /** Why the feature is unavailable (plan limit, not enabled, etc.). */\n  reason?: FeatureUnavailabilityReason;\n  /** How the UI should respond to unavailability (disable, hide, show upgrade). */\n  behavior: FeatureUnavailabilityBehavior;\n  /** Feature IDs that are missing/required for this item. */\n  missingFeatures?: string[];\n  /** Limit details when the feature is gated by usage limits. */\n  limitInfo?: { featureId: string; current: number; limit: number };\n  /** Available upgrade options to unlock this feature. */\n  upgradeOptions?: FeatureUpgradeOption[];\n  /** Suggested product reference for upgrade CTAs. */\n  suggestedProductRef?: string;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Item Types (app-level sidebar, command menu, etc.)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Discriminator for navigation item variants.\n * Navigation items appear in the sidebar, command menu, and toolbar.\n */\nexport enum NavigationItemType {\n  /** A navigable resource operation (list, read, create for a resource type). */\n  RESOURCE = 'resource',\n  /** A navigable view (composite, chart, custom, flows/actors). */\n  VIEW = 'view',\n  /** A navigable framework-owned engine page (home, security settings). */\n  ENGINE_PAGE = 'engine_page',\n  /** A navigable generic custom component. */\n  CUSTOM_COMPONENT = 'custom_component',\n  /** Opens the unified Settings Hub (overlay) at an optional section. */\n  SETTINGS_HUB = 'settings_hub',\n}\n\n/** Subset of `NavigationContentType` for view-based navigation items. */\nexport type ViewNavigationContentType =\n  | NavigationContentType.COMPOSITE_VIEW\n  | NavigationContentType.CHART_VIEW\n  | NavigationContentType.FULL_CUSTOM_VIEW\n  | NavigationContentType.FLOWS_ACTORS_VIEW\n  | NavigationContentType.EXECUTION_VIEW;\n\n/**\n * Shared fields across all navigation item variants.\n * Populated by per-launcher resolution (`launcher-resolution.ts`) and behavior\n * hooks from declared launcher content and resource/view definitions.\n */\nexport interface NavigationItemBase {\n  /** Unique identifier for this item (typically resourceType or viewRef based). */\n  id: string;\n  /** Stable reference for configuration matching (not display-specific). */\n  ref: string;\n  /** Display label for the item. */\n  label: string;\n  /** URL path for this item's destination. */\n  urlPath: string;\n  /** Optional icon React node for sidebar/toolbar rendering. */\n  icon?: React.ReactNode;\n  /** Section reference for grouping (e.g., 'main', 'tools', 'settings'). */\n  section?: string;\n  /** Sidebar display policy (always visible, collapsible, etc.). */\n  displayPolicy?: SidebarItemDisplayPolicy;\n  /** Badge KEY (`<scope>:<identifier>`) naming a registered notification-badge definition (see `SidebarItem`). */\n  notificationBadgeRef?: string;\n  /** Keyboard shortcut hint displayed in UI (e.g., \"⌘K\"). */\n  shortcut?: string;\n  /** Additional search keywords for command menu filtering. */\n  searchKeywords?: string[];\n  /** Parent item reference for hierarchical nesting in sidebar. */\n  parentItemRef?: string;\n  /** Whether this item has children and can be collapsed. */\n  isCollapsible?: boolean;\n  /** Category for command menu grouping. */\n  commandCategory?: string;\n  /** Whether to render as icon-only (no label) in compact modes. */\n  iconOnly?: boolean;\n\n  /** Whether this item is disabled (feature gating, permissions, etc.). */\n  disabled?: boolean;\n  /** Whether this item shows a lock indicator (feature-locked but visible). */\n  featureLocked?: boolean;\n  /** Feature availability details when `featureLocked` or `disabled` due to features. */\n  featureAvailability?: NavigationFeatureAvailability;\n}\n\n/**\n * Resource navigation item — a navigable resource operation in app-level components.\n * Discriminated by `itemType: NavigationItemType.RESOURCE`.\n */\nexport interface ResourceNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.RESOURCE;\n  /** The resource type identifier (e.g., 'project', 'task'). */\n  resourceType: string;\n  /** The operation identifier within the resource config (e.g., 'list', 'create'). */\n  operationIdentifier: string;\n  /** The full operation configuration from the resource. */\n  operation: FrontendResourceConfiguration_Operation;\n  /** Pre-built resource context for navigation dispatch. */\n  resourceContext: FrontendResourceOperationContext;\n}\n\n/**\n * View navigation item — a navigable view in app-level components.\n * Discriminated by `itemType: NavigationItemType.VIEW`.\n */\nexport interface ViewNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.VIEW;\n  /** View reference identifier. */\n  viewRef: string;\n  /** Content type for routing (composite, chart, custom, flows/actors). */\n  contentType: ViewNavigationContentType;\n  /** Optional context resource IDs carried with the app-level navigation payload. */\n  contextResourceIdentifiers?: Record<string, string>;\n  /** Optional chart-route query params for standalone chart URL_PARAM bindings. */\n  urlParamValues?: Record<string, string>;\n  /** FlowsActorsView: the flows/actors system displayed. */\n  flowsActorsSystemRef?: string;\n  /** FullCustomView: reference to the registered custom component. */\n  fullCustomComponentRef?: string;\n  /** Required features configuration for feature gating. */\n  requiredFeatures?: RequiredFeaturesConfig;\n}\n\n/**\n * Engine-page navigation item — a navigable framework-owned page in app-level components.\n * Discriminated by `itemType: NavigationItemType.ENGINE_PAGE`.\n */\nexport interface EnginePageNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.ENGINE_PAGE;\n  /** Framework-owned page reference. */\n  pageRef: EnginePageRef;\n}\n\n/** Generic custom-component navigation item — launcher escape hatch with explicit runtime meaning. */\nexport interface CustomComponentNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.CUSTOM_COMPONENT;\n  componentRef: string;\n  /** Optional context resource IDs carried with the app-level navigation payload. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/**\n * Settings-hub navigation item — opens the unified Settings Hub (overlay).\n * Discriminated by `itemType: NavigationItemType.SETTINGS_HUB`.\n */\nexport interface SettingsHubNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.SETTINGS_HUB;\n  /** Section to pre-open; omit to open the hub's default section. */\n  sectionRef?: string;\n}\n\n/** Discriminated union of all navigation items. Narrow on `itemType`. */\nexport type AnyNavigationItem =\n  | ResourceNavigationItem\n  | ViewNavigationItem\n  | EnginePageNavigationItem\n  | CustomComponentNavigationItem\n  | SettingsHubNavigationItem;\n\n/** Type guard — narrows `AnyNavigationItem` to `ResourceNavigationItem`. */\nexport function isResourceNavigationItem(item: AnyNavigationItem): item is ResourceNavigationItem {\n  return item.itemType === NavigationItemType.RESOURCE;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `ViewNavigationItem`. */\nexport function isViewNavigationItem(item: AnyNavigationItem): item is ViewNavigationItem {\n  return item.itemType === NavigationItemType.VIEW;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `EnginePageNavigationItem`. */\nexport function isEnginePageNavigationItem(item: AnyNavigationItem): item is EnginePageNavigationItem {\n  return item.itemType === NavigationItemType.ENGINE_PAGE;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `CustomComponentNavigationItem`. */\nexport function isCustomComponentNavigationItem(item: AnyNavigationItem): item is CustomComponentNavigationItem {\n  return item.itemType === NavigationItemType.CUSTOM_COMPONENT;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `SettingsHubNavigationItem`. */\nexport function isSettingsHubNavigationItem(item: AnyNavigationItem): item is SettingsHubNavigationItem {\n  return item.itemType === NavigationItemType.SETTINGS_HUB;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Zod Validation Schemas (for runtime event validation)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Zod schema for `NavigationSourceRelationship`.\n * Intentional lightweight subset of the full relationship schema —\n * only navigation-relevant fields for event validation.\n */\nconst navigationSourceRelationshipSchema = z.object({\n  parentResourceType: z.string(),\n  parentResourceId: z.string().optional(),\n  childResourceType: z.string(),\n  foreignKeyField: z.string().optional(),\n  relationshipEdgeKey: z.string().optional(),\n  inChildView: z.object({\n    showParentLink: z.boolean().optional(),\n    parentDisplay: z.enum(ParentDisplay).optional(),\n  }).optional(),\n});\n\n/** Zod schema for `NavigationInitiatorContext` — validates navigation event source. */\nexport const NavigationInitiatorContextSchema = z.object({\n  sourceZone: z.union([NavigationZoneSchema, z.literal(APP_LEVEL_NAVIGATION_SOURCE)]),\n  launcher: z.enum(ApplicationLevelComponentType).optional(),\n  sourceOperation: z.enum(CoreResourceOperation).optional(),\n  sourceRelationship: navigationSourceRelationshipSchema.optional(),\n});\n\n/** Zod schema for resource operation content. */\nconst navigationContent_ResourceOperationSchema = z.object({\n  contentType: z.literal(NavigationContentType.RESOURCE_OPERATION),\n  resourceContext: FrontendResourceOperationContextSchema,\n});\n\n/** Zod schema for composite view content. */\nconst navigationContent_CompositeViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.COMPOSITE_VIEW),\n  viewRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for chart view content. */\nconst navigationContent_ChartViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.CHART_VIEW),\n  viewRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n  urlParamValues: z.record(z.string(), z.string()).optional(),\n  requiredFeatures: RequiredFeaturesConfigSchema.optional(),\n  // Pre-resolved chart payloads ride on the navigation stack as runtime\n  // transport objects. They are already type-checked at construction sites; the\n  // stack schema only needs to validate that optional payload slots exist.\n  viewDefinition: z.custom<InsertedChartDeclaration>(() => true).optional(),\n  runtimeDescriptor: z.custom<ResolvedInsertedChartDescriptor>(() => true).optional(),\n});\n\n/** Zod schema for full custom view content. */\nconst navigationContent_FullCustomViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.FULL_CUSTOM_VIEW),\n  viewRef: z.string(),\n  fullCustomComponentRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for flows/actors view content. */\nconst navigationContent_FlowsActorsViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.FLOWS_ACTORS_VIEW),\n  viewRef: z.string(),\n  flowsActorsSystemRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for execution view content. */\nconst navigationContent_ExecutionViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.EXECUTION_VIEW),\n  viewRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for generic custom component content. */\nconst navigationContent_CustomComponentSchema = z.object({\n  contentType: z.literal(NavigationContentType.CUSTOM_COMPONENT),\n  componentRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for engine page content. */\nconst navigationContent_EnginePageSchema = z.object({\n  contentType: z.literal(NavigationContentType.ENGINE_PAGE),\n  pageRef: z.nativeEnum(EnginePageRef),\n});\n\n/**\n * Zod schema for the unified Settings Hub overlay content.\n *\n * Mirrors {@link NavigationContent_SettingsHub}, which is the SECOND declaration of this shape —\n * the interface is what components consume and this is what the navigation events validate. The two\n * must move together: `subTabRef` was added to the interface first and the emit site kept failing\n * against this one, which is the whole reason the pair is called out here rather than left implicit.\n */\nconst navigationContent_SettingsHubSchema = z.object({\n  contentType: z.literal(NavigationContentType.SETTINGS_HUB),\n  sectionRef: z.string().optional(),\n  subTabRef: z.string().optional(),\n});\n\n/** Zod schema for inline create content. */\nconst navigationContent_InlineCreateSchema = z.object({\n  contentType: z.literal(NavigationContentType.INLINE_CREATE),\n  resourceContext: FrontendResourceOperationContextSchema,\n  defaultValues: z.record(z.string(), z.unknown()),\n});\n\n/** Zod schema for error modal content. */\nconst navigationContent_ErrorModalSchema = z.object({\n  contentType: z.literal(NavigationContentType.ERROR_MODAL),\n  errorType: z.string(),\n  wildoError: z.unknown(),\n});\n\n/** Discriminated union schema for all navigation content types. */\nexport const NavigationContentSchema = z.discriminatedUnion('contentType', [\n  navigationContent_ResourceOperationSchema,\n  navigationContent_CompositeViewSchema,\n  navigationContent_ChartViewSchema,\n  navigationContent_FullCustomViewSchema,\n  navigationContent_FlowsActorsViewSchema,\n  navigationContent_ExecutionViewSchema,\n  navigationContent_CustomComponentSchema,\n  navigationContent_EnginePageSchema,\n  navigationContent_SettingsHubSchema,\n  navigationContent_InlineCreateSchema,\n  navigationContent_ErrorModalSchema,\n]);\n\n/** Zod schema for a single navigation stack entry — validates serialized navigation state. */\nexport const NavigationStackEntrySchema = z.object({\n  id: z.string(),\n  content: NavigationContentSchema,\n  urlPath: z.string().optional(),\n  timestamp: z.number(),\n  zone: NavigationZoneSchema,\n  initiator: NavigationInitiatorContextSchema.optional(),\n  navigationSource: z.enum(NavigationSource),\n  transition: z.enum(NavigationTransition),\n  appearance: z.union([z.enum(OverlayAppearance), z.enum(SplitAppearance)]).optional(),\n  ephemeral: z.boolean().optional(),\n  hostedPane: z.boolean().optional(),\n});\n"]}
+{"version":3,"file":"navigation.schemas.js","sourceRoot":"","sources":["../../../../src/core/navigation/navigation.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Navigation — Frontend Runtime Types\n *\n * Runtime types for zone state, navigation stacks/tabs, events, content,\n * initiator context, and resolution results. These are the types the\n * navigation controller, context, and rendering layer operate on.\n *\n * Configuration types (what developers configure) live in\n * `@wildo-ai/saas-models` — `navigation.shared.schemas.ts`.\n * This file imports config enums from there and defines runtime state on top.\n *\n * Key runtime concepts:\n * - **NavigationZone**: type union = `NavigationZoneName | 'overlay'` — extends the 3\n *   configurable zones with the implicit overlay destination (no enum duplication)\n * - **NavigationState**: per-zone stack/tab state + separate overlay stack\n * - **NavigationResolutionResult**: output of the resolver, consumed by the controller\n *\n * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md\n */\n\nimport React from 'react';\nimport { z } from 'zod';\nimport {\n  NavigationZoneContentModel,\n  NavigationTransition,\n  NavigationZoneName,\n  OverlayAppearance,\n  ParentDisplay,\n  ZoneEmptyBehavior,\n  type RelationshipDisplayInChildView,\n  type TransitionConfig,\n  type ViewportDiscriminated,\n} from '@wildo-ai/saas-models';\nimport { ViewportBreakpoint } from '@wildo-ai/zod-decorators';\nimport {\n  ApplicationLevelComponentType,\n  SidebarItemDisplayPolicy,\n} from '~wildo-frontend-lib/core/config/app-level-components.frontend.schemas';\nimport { EnginePageRef } from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\nimport type { NavigationOperationOverride, FrontendResourceConfiguration_Operation } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport {\n  CoreResourceOperation,\n  ResourceOperationFrontendSurface,\n  type RequiredFeaturesConfig,\n  RequiredFeaturesConfigSchema,\n  FeatureUnavailabilityBehavior,\n  FeatureUnavailabilityReason,\n  type FeatureUpgradeOption,\n} from '@wildo-ai/saas-models';\nimport {\n  FrontendResourceOperationContextSchema,\n  type FrontendResourceOperationContext,\n} from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport type {\n  InsertedChartDeclaration,\n  ResolvedInsertedChartDescriptor,\n} from '~wildo-frontend-lib/core/config/chart-view.frontend.schemas';\n\n\n// ════════════════════════════════════════════════════════════════\n// Runtime Enums\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Runtime zone identifiers — all possible destinations for navigation content.\n *\n * Extends `NavigationZoneName` (the 3 configurable zones) with `OVERLAY`,\n * which is an implicit runtime destination (not a configurable zone).\n *\n * Implemented as a const object (spread of `NavigationZoneName` + `OVERLAY`)\n * to avoid duplicating the 3 structural zone values already defined in\n * `NavigationZoneName`. Use `NavigationZone.PRIMARY`, `NavigationZone.OVERLAY`, etc.\n */\nconst OVERLAY_ZONE = 'overlay' as const;\n\nexport const NavigationZone = {\n  ...NavigationZoneName,\n  /**\n   * Implicit floating layer above all zones. Not a configurable zone —\n   * always available as a destination for `overlay` transitions.\n   * Content renders as dialog, sheet, or drawer based on the source zone's appearance config.\n   */\n  OVERLAY: OVERLAY_ZONE,\n} as const;\n\n/** Union of all runtime zone identifiers (3 structural + overlay). */\nexport type NavigationZone = NavigationZoneName | typeof OVERLAY_ZONE;\n\n/** Zod schema for `NavigationZone` — validates any structural zone name or `'overlay'`. */\nexport const NavigationZoneSchema = z.union([z.enum(NavigationZoneName), z.literal(OVERLAY_ZONE)]);\n\n/**\n * All structural zones (excludes overlay).\n * Used for iterating over zones that have configuration and state.\n */\nexport const NAVIGATION_STRUCTURAL_ZONES: readonly NavigationZoneName[] = Object.values(NavigationZoneName);\n\n/**\n * Navigation source for app-shell actions (sidebar, command palette, hotkey, toast, notification).\n * Used alongside `NavigationZone` to form the complete set of navigation origins.\n * App-level navigation causes a layout reset: primary replaced, other zones cleared.\n */\nexport const APP_LEVEL_NAVIGATION_SOURCE = 'appLevel' as const;\n\n/**\n * What kind of content is being navigated to.\n * Frontend-only — used by navigation stacks, resolution, and content rendering.\n */\nexport enum NavigationContentType {\n  RESOURCE_OPERATION = 'resource_operation',\n  COMPOSITE_VIEW = 'composite_view',\n  CHART_VIEW = 'chart_view',\n  FULL_CUSTOM_VIEW = 'full_custom_view',\n  FLOWS_ACTORS_VIEW = 'flows_actors_view',\n  EXECUTION_VIEW = 'execution_view',\n  CUSTOM_COMPONENT = 'custom_component',\n  ENGINE_PAGE = 'engine_page',\n  SETTINGS_HUB = 'settings_hub',\n  INLINE_CREATE = 'inline_create',\n  ERROR_MODAL = 'error_modal',\n}\n\n/**\n * How a navigation entry was created — tracks the origin of each stack entry.\n *\n * Used to coordinate between controller-initiated (programmatic) and\n * URL-initiated (browser back/forward, direct link) navigation.\n * The controller needs to know if a navigation event came from URL sync\n * to avoid infinite loops (URL change → navigate → URL change → ...).\n */\nexport enum NavigationSource {\n  /** Navigation triggered programmatically by useNavigationController. */\n  CONTROLLER = 'controller',\n  /** Navigation triggered by URL change (bookmark, back button, direct link). */\n  URL_SYNC = 'url_sync',\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Initiator Context\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Lightweight relationship metadata carried on navigation events.\n *\n * When navigation is triggered by a parent→child relationship traversal\n * (e.g., clicking a related item in a parent's detail view), this carries\n * just enough relationship info for the destination component to configure\n * its parent reference display (breadcrumb, badge, etc.).\n *\n * Intentionally NOT the full `ResourceRelationship` — avoids importing the\n * entire relationship schema tree into navigation events (Nav-2 decision).\n */\nexport interface NavigationSourceRelationship {\n  /** The resource type of the parent in this relationship. */\n  parentResourceType: string;\n  /** The specific parent instance ID, if navigating from a specific parent record. */\n  parentResourceId?: string;\n  /** The resource type of the child in this relationship. */\n  childResourceType: string;\n  /** FK field used to traverse this edge when disambiguation is required. */\n  foreignKeyField?: string;\n  /** Stable parent→child edge key for navigation-time identity. */\n  relationshipEdgeKey?: string;\n  /**\n   * The `inChildView` display config from the relationship definition.\n   * Controls how the parent reference appears in the child's view (breadcrumb, badge, etc.).\n   */\n  inChildView?: RelationshipDisplayInChildView;\n}\n\n/**\n * Source context for a navigation event — WHO triggered the navigation and FROM WHERE.\n *\n * The resolver uses `sourceZone` as the primary input signal to determine\n * which transition applies. The same operation produces different transitions\n * depending on where the user currently is.\n */\nexport interface NavigationInitiatorContext {\n  /**\n   * Where the navigation was triggered from.\n   *\n   * - A `NavigationZone` value: navigation from within a structural zone or overlay\n   * - `APP_LEVEL_NAVIGATION_SOURCE`: navigation from the app shell (sidebar,\n   *   command palette, hotkey, toast action, notification click). Causes a layout reset.\n   *\n   * This replaces the old `type: NavigationInitiatorType` + `sourcePane: NavigationPane`\n   * pattern with a single, explicit field.\n   */\n  sourceZone: NavigationZone | typeof APP_LEVEL_NAVIGATION_SOURCE;\n  /**\n   * Which app-level launcher triggered the navigation.\n   * Only relevant when `sourceZone === APP_LEVEL_NAVIGATION_SOURCE`. Examples: sidebar click,\n   * command palette selection, quick action button, hotkey.\n   */\n  launcher?: ApplicationLevelComponentType;\n  /** The operation that produced this navigation (read, create, delete, etc.). */\n  sourceOperation?: CoreResourceOperation;\n  /**\n   * When navigation was triggered by traversing a parent→child relationship.\n   * Carries lightweight relationship info so the destination can configure\n   * parent reference display (breadcrumb, badge, summary card).\n   */\n  sourceRelationship?: NavigationSourceRelationship;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Content (discriminated union — what's being shown)\n// ════════════════════════════════════════════════════════════════\n\n/** Content representing a resource operation (list, read, create, etc.). */\nexport interface NavigationContent_ResourceOperation {\n  contentType: NavigationContentType.RESOURCE_OPERATION;\n  /** Fully resolved resource context: resource type, operation, params, record ID, etc. */\n  resourceContext: FrontendResourceOperationContext;\n}\n\n/** Content representing a composite view (dashboard, overview, etc.). */\nexport interface NavigationContent_CompositeView {\n  contentType: NavigationContentType.COMPOSITE_VIEW;\n  /** Reference identifier for the composite view definition. */\n  viewRef: string;\n  /** Optional context resource IDs to pass to the view for scoping/filtering. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a chart view (data visualization). */\nexport interface NavigationContent_ChartView {\n  contentType: NavigationContentType.CHART_VIEW;\n  /** Reference identifier for the chart view definition. */\n  viewRef: string;\n  /** Optional context resource IDs to scope the chart's data. */\n  contextResourceIdentifiers?: Record<string, string>;\n  /** Optional route-derived URL params for standalone chart URL_PARAM bindings. */\n  urlParamValues?: Record<string, string>;\n  /** Optional feature-gating metadata for chart-stack rendering. */\n  requiredFeatures?: RequiredFeaturesConfig;\n  /** Optional pre-resolved chart surface definition for inserted/routed charts. */\n  viewDefinition?: InsertedChartDeclaration;\n  /** Optional pre-resolved descriptor for inserted/routed charts. */\n  runtimeDescriptor?: ResolvedInsertedChartDescriptor;\n}\n\n/** Content representing a full custom view (developer-provided component). */\nexport interface NavigationContent_FullCustomView {\n  contentType: NavigationContentType.FULL_CUSTOM_VIEW;\n  /** Reference identifier for the view definition. */\n  viewRef: string;\n  /** Reference to the custom React component registered for this view. */\n  fullCustomComponentRef: string;\n  /** Optional context resource IDs to pass to the component. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a flows & actors view (AI workflows, agent execution). */\nexport interface NavigationContent_FlowsActorsView {\n  contentType: NavigationContentType.FLOWS_ACTORS_VIEW;\n  /** Reference identifier for the view definition. */\n  viewRef: string;\n  /** The flows/actors system this view displays. */\n  flowsActorsSystemRef: string;\n  /** Optional context resource IDs to scope the view. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing an execution view (framework-owned execution host). */\nexport interface NavigationContent_ExecutionView {\n  contentType: NavigationContentType.EXECUTION_VIEW;\n  /** Reference identifier for the execution view definition. */\n  viewRef: string;\n  /** Optional context resource IDs to scope the execution view. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a generic app-level custom component. */\nexport interface NavigationContent_CustomComponent {\n  contentType: NavigationContentType.CUSTOM_COMPONENT;\n  /** Registered component reference to materialize. */\n  componentRef: string;\n  /** Optional context resource IDs to pass to the component. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/** Content representing a router-backed engine page. */\nexport interface NavigationContent_EnginePage {\n  contentType: NavigationContentType.ENGINE_PAGE;\n  pageRef: EnginePageRef;\n}\n\n/**\n * Content representing the unified Settings Hub.\n *\n * Always rendered in the overlay zone (DIALOG appearance, persistent — NOT\n * ephemeral, so it survives source-zone changes and closes only on explicit\n * dismiss). The optional `sectionRef` pre-selects which section opens; when\n * omitted the hub opens at its default section. URL-addressable via\n * `/settings/:sectionRef`, and `/settings/:sectionRef/:subTabRef` when the\n * section renders sub-tabs.\n */\nexport interface NavigationContent_SettingsHub {\n  contentType: NavigationContentType.SETTINGS_HUB;\n  sectionRef?: string;\n  /**\n   * Which sub-tab of `sectionRef` opens. Only meaningful for a `SUB_TABS` target; a ref the\n   * section does not declare is IGNORED rather than refused, so a stale or hand-typed link still\n   * opens the section at its first tab instead of an error page.\n   */\n  subTabRef?: string;\n}\n\n/** Content representing a typed sidebar inline-create flow. */\nexport interface NavigationContent_InlineCreate {\n  contentType: NavigationContentType.INLINE_CREATE;\n  resourceContext: FrontendResourceOperationContext;\n  defaultValues: Record<string, unknown>;\n}\n\n/**\n * Content representing an error modal pushed through the overlay stack.\n *\n * Carries the error itself, not text: the modal is pushed by `ErrorContext`, which is mounted ABOVE the\n * `I18nProvider`, so nothing there can produce words a person should read. The renderer resolves\n * `wildoError` through `useUserFacingErrorMessage`. The `message` and `context` fields were removed (#1159):\n * they held the raw i18n reference and the request context, and both reached the screen.\n */\nexport interface NavigationContent_ErrorModal {\n  contentType: NavigationContentType.ERROR_MODAL;\n  /** Technical discriminator for the stack-entry key only — never rendered. */\n  errorType: string;\n  wildoError: unknown;\n}\n\n/**\n * Discriminated union of all navigation content types.\n * Discriminated on `contentType` for clean narrowing.\n * Every navigation stack entry carries exactly one of these.\n */\nexport type NavigationContent =\n  | NavigationContent_ResourceOperation\n  | NavigationContent_CompositeView\n  | NavigationContent_ChartView\n  | NavigationContent_FullCustomView\n  | NavigationContent_FlowsActorsView\n  | NavigationContent_ExecutionView\n  | NavigationContent_CustomComponent\n  | NavigationContent_EnginePage\n  | NavigationContent_SettingsHub\n  | NavigationContent_InlineCreate\n  | NavigationContent_ErrorModal;\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Stack Entry\n// ════════════════════════════════════════════════════════════════\n\n/**\n * A single entry in a zone's navigation stack (or overlay stack).\n *\n * Each entry represents one piece of content that was navigated to.\n * The stack maintains navigation history within a zone for back navigation.\n * In tabbed zones, entries represent parallel tabs (not a depth stack).\n */\nexport interface NavigationStackEntry {\n  /** Unique identifier for this stack entry (UUID). */\n  id: string;\n  /** The content being displayed in this entry. */\n  content: NavigationContent;\n  /**\n   * URL path that represents this navigation state.\n   * Used for URL serialization, deep linking, and browser history.\n   * Every navigation state must be URL-addressable.\n   */\n  urlPath?: string;\n  /** Timestamp (ms since epoch) when this entry was created. For ordering and debugging. */\n  timestamp: number;\n  /** Which zone this entry lives in. */\n  zone: NavigationZone;\n  /** The context that triggered this navigation (source zone, operation, relationship). */\n  initiator?: NavigationInitiatorContext;\n  /** Whether this entry was created by the controller or by URL sync. */\n  navigationSource: NavigationSource;\n  /**\n   * The transition verb that placed this entry (push, replace, split, overlay, promote).\n   * Note: `inplace` does not produce a stack entry (it transforms an element in the\n   * current view without changing zone state), so it will never appear here.\n   */\n  transition: NavigationTransition;\n  /**\n   * Visual appearance for this entry's transition.\n   * Set by the resolver from zone appearance config. Only meaningful for\n   * overlay entries (dialog/sheet/drawer) and split entries (panel/drawer).\n   * Used by ContentAreas to decide how to render overlay or split content.\n   */\n  appearance?: OverlayAppearance;\n  /**\n   * Behaviour of an OVERLAY entry: is the page behind interactive, does touching it dismiss, is it\n   * dimmed. Three independent questions, and a companion panel needs all three answered — see\n   * `OverlayContainerConfig`, whose fields these feed.\n   *\n   * Declared per operation because it is a property of the CONTENT, not of the zone: one application\n   * legitimately has a create dialog that blocks everything and a detail sheet beside a live canvas\n   * that blocks nothing.\n   */\n  overlayBehavior?: {\n    /** Block interaction with the page behind. Default `true`. */\n    modal?: boolean;\n    /** Dismiss when the page behind is clicked. Default `true`. */\n    closeOnOutsideClick?: boolean;\n    /** Dim the page behind. Default `true`. */\n    showBackdrop?: boolean;\n  };\n  /**\n   * When `true`, this overlay entry auto-closes when the source zone's stack changes.\n   * Set by the resolver from `TransitionConfig.ephemeral`. Only valid on overlay entries.\n   * Used by NavigationContext auto-close logic.\n   */\n  ephemeral?: boolean;\n  /**\n   * `true` when this entry was placed by a `persistent` split, so it SURVIVES a change of the\n   * source zone's content.\n   *\n   * Implemented 2026-09-25. Before that `persistent` chose COMPANION as the target zone and did\n   * nothing else, while its schema JSDoc promised \"the split zone persists when the source zone's\n   * content changes — without `persistent`, a split zone would clear when primary navigates away\".\n   * Neither half existed: no entry carried a flag, and the zone-dependency cleanup cleared COMPANION\n   * on any irrelevant primary change regardless of how the content arrived. The documented\n   * reference-panel pattern — a thread, a terminal, a doc kept open while you move around — closed on\n   * the first unrelated navigation.\n   *\n   * It exempts the entry from the DEPENDENCY cleanup only. An explicit dismiss, a clean break\n   * (`PROMOTE`, an app-level reset) and a direct clear all still close it: persistence means \"do not\n   * close this because the page beneath changed\", not \"this cannot be closed\".\n   */\n  persistent?: boolean;\n  /**\n   * `true` when this SECONDARY entry was opened beside a primary whose address the pane's own URL\n   * cannot re-derive (a composite view, a canvas, a chart, an engine page), so the browser URL is\n   * the HOST's address carrying this entry as `?pane=` — see `HOSTED_PANE_QUERY_PARAM` in\n   * `hosted-pane.constants.ts`.\n   *\n   * Three readers key on it, and each needs it for a different reason: the zone-dependency cleanup\n   * keeps a hosted pane beside a primary it cannot otherwise relate to (the relevance rule is\n   * relationship-aware and a composite view has no relationships); the URL reconciler closes the\n   * pane when the `pane` parameter leaves the URL (browser back); and the route-owner lookup never\n   * lets a hosted entry claim a BARE browser URL, because its address is only ever reachable in the\n   * composed form.\n   */\n  hostedPane?: boolean;\n  /**\n   * The zone this entry was AUTHORED for, when a responsive collapse placed it somewhere else.\n   *\n   * A `secondary` split on a phone lands in PRIMARY (under `ResponsiveCollapseMode.PUSH`) or in\n   * OVERLAY (under `OVERLAY`), and `zone` above records where it actually IS. This records where it\n   * belongs, so widening the viewport can migrate it back — the behaviour `ResponsiveCollapseMode`\n   * documents and, before #411, nothing implemented because nothing recorded the origin.\n   *\n   * Absent on every entry that was placed where it was authored, which is the common case.\n   */\n  collapsedFromZone?: NavigationZoneName;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Zone State (runtime)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Runtime state of a single navigation zone.\n *\n * Each zone independently tracks its navigation stack and visibility.\n * For tabbed zones, `activeTabId` identifies which tab is currently displayed.\n *\n * Zone lifecycle states (not an enum — derived from config + runtime):\n * - **Inactive**: zone not declared in config. Doesn't exist in DOM.\n * - **Hidden**: zone exists but not visible (collapsed, or `onEmpty: ZoneEmptyBehavior.COLLAPSE` with nothing pushed).\n * - **Empty**: zone visible but no content. Only when `onEmpty: 'emptyState'`.\n * - **Active**: zone has content and is visible.\n */\nexport interface NavigationZoneState {\n  /** Which zone this state belongs to. */\n  zone: NavigationZone;\n  /**\n   * The zone's navigation stack.\n   * - In `single` content model: depth stack. Top entry is visible. Back pops.\n   * - In `NavigationZoneContentModel.TABBED` content model: tab entries. All are \"open\", one is active.\n   */\n  stack: NavigationStackEntry[];\n  /**\n   * Whether this zone is currently rendered in the DOM and visible.\n   * `false` when the zone is collapsed (responsive), or is empty with\n   * `onEmpty: ZoneEmptyBehavior.COLLAPSE` and nothing has been pushed into it yet.\n   */\n  isVisible: boolean;\n  /**\n   * For `NavigationZoneContentModel.TABBED` zones — the ID of the currently active tab entry.\n   * References `NavigationStackEntry.id`. When `undefined`, the zone is in single mode.\n   * Using ID (not index) for stability when tabs are reordered or closed.\n   */\n  activeTabId?: string;\n}\n\n/**\n * Full runtime navigation state.\n *\n * Zones hold their own stack/tab state keyed by `NavigationZoneName` (the 3 structural\n * zones). Overlay is separate because it's not a configurable zone — it's an implicit\n * floating layer that can hold a stack of its own (push within overlay).\n */\nexport interface NavigationState {\n  /**\n   * Per-zone state for the 3 structural zones (primary, secondary, companion).\n   * Keyed by `NavigationZoneName` — NOT `NavigationZone` (which includes overlay).\n   */\n  zones: Record<NavigationZoneName, NavigationZoneState>;\n  /**\n   * Overlay stack — content shown in the floating layer above all zones.\n   * Supports push depth within the overlay (e.g., navigating to a related item\n   * from within a create dialog pushes onto the overlay stack).\n   * When the stack empties, the overlay dismisses.\n   */\n  overlay: NavigationStackEntry[];\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Resolution Result (output of the resolver)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * WHICH TIER of the transition-resolution chain decided the verb.\n *\n * The chain has seven steps and every one of them can answer `PUSH`. So the OUTCOME alone cannot\n * tell an authored decision from the framework's default, and for a year nothing recorded which had\n * spoken: the resolver carries 324 lines of code, thirteen decision methods and — until 2026-09-25 —\n * not one log statement or provenance field. Every \"why did it land there?\" question was therefore\n * answered by simulating the chain by hand against the application's layout, which is what eight\n * consecutive navigation diagnoses cost that week.\n *\n * Recording it is free, because the deciding tier is known at each return site of\n * `resolveTransition`. What it buys is two things a log line could not:\n *\n * 1. **A test can pin the TIER, not merely the answer.** A pin that asserts `PUSH` passes when the\n *    right verb arrives from the wrong step — `positive-evidence-must-name-its-target.md` exactly.\n *    Steps 1, 1.5 and 2 are authored by no application today, so their unit tests are the only thing\n *    that exercises them, and those tests could not previously distinguish \"step 2 answered\" from\n *    \"step 2 was skipped and the framework default happened to agree\".\n * 2. **A reader sees the tier in one field** instead of re-deriving it from the layout.\n */\nexport enum NavigationTransitionSource {\n  /** Step 1 — a `navigationOverrides` entry on the operation matched. The most specific instrument. */\n  OPERATION_OVERRIDE = 'operation-override',\n  /** Step 1.5 — the operation declares an AUTHORED `ResourceOperationActionPresentation`. */\n  AUTHORED_ACTION_PRESENTATION = 'authored-action-presentation',\n  /** Step 2 — the relationship this navigation traverses declares `inParentNavigation.transition`. */\n  RELATIONSHIP = 'relationship',\n  /** Step 3 — `layout[mobile|vertTablet].transitions` answered for this viewport. */\n  VIEWPORT_OVERRIDE = 'viewport-override',\n  /** Step 4 — the SOURCE's own declared map answered (`zones[source]`, `appLevel` or `fromOverlay`). */\n  SOURCE_TRANSITIONS = 'source-transitions',\n  /**\n   * Step 4 — the source was an OVERLAY that declares no answer for this operation, so PRIMARY's map\n   * answered instead.\n   *\n   * Distinct from {@link SOURCE_TRANSITIONS} because it is the one tier that reads a map the author\n   * did not write for this source. It is the fallback added on 2026-09-25 after the workbench's\n   * `family` backlink — an ADDRESSABLE artifact clicked inside a popup — fell past an absent\n   * `fromOverlay` to the framework default and took the whole page instead of opening beside the\n   * list. Naming it separately is what lets a reader see that the answer came from somewhere the\n   * layout does not literally say it.\n   */\n  OVERLAY_FALLBACK_TO_PRIMARY = 'overlay-fallback-to-primary',\n  /** Step 4.5 — a DERIVED action presentation (the framework's guess for an unconfigured action). */\n  DERIVED_ACTION_PRESENTATION = 'derived-action-presentation',\n  /** Step 5 — nothing answered; {@link NavigationTransition.PUSH}. */\n  FRAMEWORK_DEFAULT = 'framework-default',\n}\n\n/**\n * A decision taken AFTER the verb that changed where the content actually landed.\n *\n * Every member is a place the resolver silently overrules the authored verb. They are legitimate —\n * each exists for a measured reason written at its site — and they are exactly what makes a\n * navigation outcome hard to explain, because the layout says one thing and the screen shows\n * another with nothing in between to read.\n *\n * Several can apply to one resolution and the order is the order they are applied in, so the array\n * reads as the story of the placement.\n */\nexport enum NavigationPlacementAdjustment {\n  /**\n   * An `EMBEDDED` view resolved onto a structural zone and was escalated to an overlay, because a\n   * structural zone is not a host — it already holds something a reader is reading.\n   */\n  EMBEDDED_COERCED_TO_OVERLAY = 'embedded-coerced-to-overlay',\n  /** A `SPLIT` found the adjacent pane FREE and opened it. The pane is a host; nothing was taken over. */\n  SPLIT_OPENED_FREE_PANE = 'split-opened-free-pane',\n  /**\n   * A `SPLIT` found every adjacent pane OCCUPIED and replaced the content of one.\n   *\n   * This is the second, opposite meaning of `SPLIT` that the enum cannot express, and naming it is\n   * the whole reason this vocabulary exists. It is correct for a list/detail application — clicking\n   * another record swaps the reading pane, exactly as a mailbox does — and it is a surface being\n   * taken over, which is why the EMBEDDED coercion above reads occupancy rather than the verb.\n   */\n  SPLIT_REPLACED_OCCUPIED_PANE = 'split-replaced-occupied-pane',\n  /**\n   * A `SPLIT` was authored and the layout declares NO adjacent zone, so it became an overlay.\n   *\n   * Silent by design and the most surprising thing in the resolver: an author who writes\n   * `transition: SPLIT` and forgets the `secondary` zone gets a dialog and no diagnostic. Reported\n   * at boot since 2026-09-25 by `collectNavigationLayoutDiagnostics`, and named here so a runtime\n   * reader sees it too.\n   */\n  SPLIT_ESCALATED_NO_ADJACENT_ZONE = 'split-escalated-no-adjacent-zone',\n  /**\n   * A `persistent` split escalated because the layout declares no `companion` — **even though a\n   * `secondary` may be declared and free.** A persistent split targets companion SPECIFICALLY.\n   *\n   * Its own member because the REMEDY differs: telling this author to \"declare `zones.secondary`\"\n   * sends them to change something they already have. The resolver knows which branch it took, so\n   * the distinction is carried here rather than re-derived by whoever reports it — one message\n   * covered both branches for a few hours on 2026-09-25 and was false for this one.\n   */\n  PERSISTENT_SPLIT_ESCALATED_NO_COMPANION = 'persistent-split-escalated-no-companion',\n  /** The target zone is collapsed at this viewport and its `responsiveCollapse` said `PUSH`. */\n  RESPONSIVE_COLLAPSE_PUSH = 'responsive-collapse-push',\n  /** The target zone is collapsed at this viewport and its `responsiveCollapse` said `OVERLAY`. */\n  RESPONSIVE_COLLAPSE_OVERLAY = 'responsive-collapse-overlay',\n  /** The push would have passed `maxDepth`, so it opened an overlay instead. */\n  DEPTH_CEILING_ESCALATED_TO_OVERLAY = 'depth-ceiling-escalated-to-overlay',\n  /**\n   * An `INPLACE` transition resolved on a surface with no element-level host — a detail page, a\n   * breadcrumb, a picker — so it degraded to an overlay.\n   *\n   * It is an ADJUSTMENT rather than a tier because the tier that answered `INPLACE` is unchanged and\n   * still worth knowing. Until 2026-09-25 the controller expressed this by re-resolving with a\n   * SYNTHETIC `operationOverrides: [{ transition: OVERLAY }]`, which cost two things: the provenance\n   * then read `operation-override`, telling a reader an author had declared something no author\n   * declared; and the synthetic array REPLACED the real one, so an operation that authored an\n   * `appearance` or `overlayBehavior` beside its transition silently lost it.\n   */\n  INPLACE_DEGRADED_TO_OVERLAY = 'inplace-degraded-to-overlay',\n}\n\n/**\n * How a resolution was reached: the tier that decided the verb, and every adjustment applied after.\n *\n * Carried on every {@link NavigationResolutionResult}. It is INFORMATION — nothing branches on it —\n * so a consumer may ignore it entirely, and a test or a log line may read it to say what happened\n * rather than what merely came out.\n */\nexport interface NavigationResolutionProvenance {\n  /** Which step of the chain answered. */\n  transitionSource: NavigationTransitionSource;\n  /** The verb that tier produced, BEFORE any adjustment below. Equal to `transition` when empty. */\n  authoredTransition: NavigationTransition;\n  /** Adjustments applied after the verb, in application order. Empty when the verb survived intact. */\n  adjustments: NavigationPlacementAdjustment[];\n}\n\n\n/**\n * Output of the navigation policy resolver — tells the controller exactly what to do.\n *\n * The resolver takes (sourceZone, operation, resourceConfig, viewport) as inputs\n * and produces this result by walking the resolution chain:\n * 1. Per-resource operation override\n * 2. Per-relationship inParentNavigation.transition\n * 3. Global viewport override\n * 4. Source zone's transitions[operation]\n * 5. Framework fallback\n */\nexport interface NavigationResolutionResult {\n  /** Which zone the content should be placed in. */\n  targetZone: NavigationZone;\n  /** The transition verb to apply. */\n  transition: NavigationTransition;\n  /**\n   * Visual appearance for the transition. Only meaningful for `overlay` transitions:\n   * `OverlayAppearance` (dialog, sheet, or drawer). `undefined` for every other verb — a `split`\n   * pane's shape is `split.orientation` — and for `push`, `replace`, `inplace` and `promote`\n   * (`push`/`replace`/`promote` fill the zone; `inplace` transforms an element).\n   */\n  appearance?: OverlayAppearance;\n  /**\n   * Behaviour of an OVERLAY entry: is the page behind interactive, does touching it dismiss, is it\n   * dimmed. Three independent questions, and a companion panel needs all three answered — see\n   * `OverlayContainerConfig`, whose fields these feed.\n   *\n   * Declared per operation because it is a property of the CONTENT, not of the zone: one application\n   * legitimately has a create dialog that blocks everything and a detail sheet beside a live canvas\n   * that blocks nothing.\n   */\n  overlayBehavior?: {\n    /** Block interaction with the page behind. Default `true`. */\n    modal?: boolean;\n    /** Dismiss when the page behind is clicked. Default `true`. */\n    closeOnOutsideClick?: boolean;\n    /** Dim the page behind. Default `true`. */\n    showBackdrop?: boolean;\n  };\n  /**\n   * Whether this placement IS a responsive collapse — the zone the content was headed for is\n   * collapsed at this viewport, so `targetZone` and `transition` above are already the collapsed\n   * outcome (PRIMARY + push, or OVERLAY + overlay) rather than the authored one.\n   *\n   * It is a REPORT, not an instruction. It said the opposite until 2026-09-08 (#411) — \"the\n   * controller should apply the zone's `responsiveCollapse` behavior\" — and no controller ever did,\n   * which is exactly how the mechanism stayed inert for as long as it existed. The resolver applies\n   * it now, because placement is what the resolver answers.\n   *\n   * What it is still FOR: telling a collapsed placement apart from an authored one. A collapsed\n   * SPLIT and an authored PUSH produce an identical `targetZone`/`transition` pair, and only this\n   * flag (with `collapsedFromZone`) distinguishes them.\n   */\n  collapsed: boolean;\n  /**\n   * The zone this content was headed for before the collapse retargeted it — `secondary` or\n   * `companion`. Present only when `collapsed` is `true`.\n   *\n   * `ResponsiveCollapseMode`'s contract is that \"when viewport grows back past the breakpoint,\n   * collapsed content migrates back to its original zone\", and an entry cannot migrate back to a\n   * zone nothing recorded. The controller writes this onto the stack entry as\n   * `NavigationStackEntry.collapsedFromZone`.\n   */\n  collapsedFromZone?: NavigationZoneName;\n  /**\n   * When `true`, this overlay entry should auto-close when its source zone's stack changes.\n   * Derived from `TransitionConfig.ephemeral`. Only meaningful for overlay transitions.\n   * The controller writes this to `NavigationStackEntry.ephemeral`.\n   */\n  ephemeral?: boolean;\n  /**\n   * `true` when a `persistent` split placed this content in an adjacent zone. The controller writes\n   * it onto the entry as {@link NavigationStackEntry.persistent}; the zone-dependency cleanup reads\n   * it there.\n   */\n  persistent?: boolean;\n  /**\n   * How this resolution was reached — see {@link NavigationResolutionProvenance}.\n   *\n   * Always present. Nothing branches on it; it exists so a reader, a log line and a test can name\n   * the tier that decided instead of inferring it from an outcome seven different tiers can produce.\n   */\n  provenance: NavigationResolutionProvenance;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Resolution Context (input to the resolver)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Input to the navigation policy resolver — all the contextual signals needed\n * to determine which transition + zone + appearance to use.\n *\n * Three fundamentally different source types select different config paths:\n * - `NavigationZoneName`: structural zone → reads `layout.zones[zone].transitions`\n * - `'appLevel'`: app shell (sidebar, command palette) → reads `layout.appLevel.transitions`\n * - `'overlay'`: from within an overlay → reads `layout.fromOverlay.transitions`\n */\nexport interface NavigationResolutionContext {\n  /**\n   * Where the navigation was triggered from. Determines which config\n   * branch the resolver reads transitions from.\n   */\n  sourceZone: NavigationZoneName | typeof APP_LEVEL_NAVIGATION_SOURCE | 'overlay';\n  /** The operation being performed (read, create, list, update, etc.). */\n  operation: CoreResourceOperation | string;\n  /**\n   * Semantic core operation for custom operations that behave like a framework\n   * core surface. Transition maps are keyed by core semantics, so resolvers must\n   * use this field instead of raw custom operation identifiers.\n   */\n  effectiveOperation?: CoreResourceOperation;\n  /** Resource type being navigated to (for per-resource override matching). */\n  resourceType?: string;\n  /**\n   * The target operation's declared frontend surface (resource content only).\n   * This is the channel that keeps navigation policy surface-aware: the\n   * resolver coerces EMBEDDED content away from PRIMARY (embedded views open\n   * in a HOST — overlay/pane — never as the page), and the controller refuses\n   * API_ONLY content outright. Replaces a former `isAddressable` boolean that\n   * was populated but read by nothing (dead channel, removed 2026-08-19).\n   */\n  operationSurface?: ResourceOperationFrontendSurface;\n  /** Per-resource operation overrides (from resource operationFrontendConfig). First match wins. */\n  operationOverrides?: NavigationOperationOverride[];\n  /**\n   * The transition the target operation's ACTION PRESENTATION resolves to, when it resolves to one\n   * at all — `MODAL` → `OVERLAY`, `PAGE` → nothing (the ordinary chain answers).\n   *\n   * The presentation axis is an ALIAS over this chain, never a parallel mechanism: it lets an author\n   * say \"an overlay\" without naming a zone, a verb and an appearance. `DIRECT`, `POPOVER` and\n   * `INLINE` do not navigate at all, so on their normal path they never reach here; `POPOVER` and\n   * `INLINE` supply an `OVERLAY` only as the DEGRADE for a host that cannot anchor or has no\n   * element to transform.\n   */\n  actionPresentationTransition?: TransitionConfig;\n  /**\n   * Was the presentation AUTHORED, or derived by the framework?\n   *\n   * It decides precedence, and the distinction is load-bearing. An authored presentation is a\n   * statement about this operation and outranks the app's relationship- and zone-level navigation\n   * defaults. A DERIVED one is the framework's guess and must yield to every configuration an app\n   * actually wrote — otherwise introducing the derivation would silently restyle navigation that\n   * apps had already tuned.\n   */\n  actionPresentationIsAuthored?: boolean;\n  /**\n   * Full transition config from the relationship's\n   * `display.inParentNavigation.transition`.\n   * Preserves lifecycle modifiers (ephemeral/persistent). `undefined` when\n   * navigation is not relationship-driven.\n   */\n  relationshipTransition?: TransitionConfig;\n  /** Current viewport breakpoint for responsive resolution. */\n  viewport: ViewportBreakpoint;\n  /**\n   * The measured width, in pixels, of the CONTENT AREA the structural zones share — not the window.\n   *\n   * The two differ by the sidebar, by any pane already open, and by whatever an embedded shell gives\n   * the application; a tall narrow column on a wide monitor is `DESKTOP` at a width no split can\n   * carry. `resolveCollapseMode` escalates a SPLIT that does not fit, exactly as it escalates one\n   * below a narrow breakpoint, so this is the measurement that makes the responsive ladder answer to\n   * the space rather than to the window.\n   *\n   * `undefined` before the first layout pass, which never escalates: an unmeasured width is not a\n   * narrow one (the same reading the viewport takes).\n   */\n  contentAreaWidth?: number;\n  /** Which structural zones currently have content. Used for SPLIT target heuristic. */\n  zoneOccupancy: Partial<Record<NavigationZoneName, boolean>>;\n  /**\n   * Current stack DEPTH per structural zone — what `NavigationLayout.maxDepth` is measured against.\n   *\n   * Distinct from `zoneOccupancy`, which is this same measurement flattened to a boolean. Both are\n   * projected from ONE read of the zone state in the controller, so they cannot disagree; the depth\n   * exists separately because \"does the zone hold anything\" and \"how deep is it\" are different\n   * questions and the second cannot be recovered from the first.\n   */\n  zoneDepth: Partial<Record<NavigationZoneName, number>>;\n  /**\n   * `RelationshipDisplayConfig.maxDepth` for the relationship that triggered this navigation, when\n   * one did — the per-relationship override of the layout's global `maxDepth`.\n   *\n   * Supplied by the caller alongside `relationshipTransition`, because the relationship's display\n   * config is a fact about the CALL SITE (a nested container knows which relationship it renders)\n   * and the resolver has no way to recover it from a resource type and an operation.\n   */\n  relationshipMaxDepth?: number;\n  /** Currently focused zone — tiebreaker for SPLIT target selection. */\n  focusedZone?: NavigationZoneName;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Feature Availability (for navigation items)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Lightweight feature availability status attached to navigation items.\n *\n * Used by sidebar, command menu, and toolbar to communicate feature gating\n * status to UI components (lock icons, disabled state, upgrade prompts).\n * Subset of the full `FeatureAvailability` from the features system.\n */\nexport interface NavigationFeatureAvailability {\n  /** Whether the feature is currently available to the user. */\n  isAvailable: boolean;\n  /** Why the feature is unavailable (plan limit, not enabled, etc.). */\n  reason?: FeatureUnavailabilityReason;\n  /** How the UI should respond to unavailability (disable, hide, show upgrade). */\n  behavior: FeatureUnavailabilityBehavior;\n  /** Feature IDs that are missing/required for this item. */\n  missingFeatures?: string[];\n  /** Limit details when the feature is gated by usage limits. */\n  limitInfo?: { featureId: string; current: number; limit: number };\n  /** Available upgrade options to unlock this feature. */\n  upgradeOptions?: FeatureUpgradeOption[];\n  /** Suggested product reference for upgrade CTAs. */\n  suggestedProductRef?: string;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Navigation Item Types (app-level sidebar, command menu, etc.)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Discriminator for navigation item variants.\n * Navigation items appear in the sidebar, command menu, and toolbar.\n */\nexport enum NavigationItemType {\n  /** A navigable resource operation (list, read, create for a resource type). */\n  RESOURCE = 'resource',\n  /** A navigable view (composite, chart, custom, flows/actors). */\n  VIEW = 'view',\n  /** A navigable framework-owned engine page (home, security settings). */\n  ENGINE_PAGE = 'engine_page',\n  /** A navigable generic custom component. */\n  CUSTOM_COMPONENT = 'custom_component',\n  /** Opens the unified Settings Hub (overlay) at an optional section. */\n  SETTINGS_HUB = 'settings_hub',\n}\n\n/** Subset of `NavigationContentType` for view-based navigation items. */\nexport type ViewNavigationContentType =\n  | NavigationContentType.COMPOSITE_VIEW\n  | NavigationContentType.CHART_VIEW\n  | NavigationContentType.FULL_CUSTOM_VIEW\n  | NavigationContentType.FLOWS_ACTORS_VIEW\n  | NavigationContentType.EXECUTION_VIEW;\n\n/**\n * Shared fields across all navigation item variants.\n * Populated by per-launcher resolution (`launcher-resolution.ts`) and behavior\n * hooks from declared launcher content and resource/view definitions.\n */\nexport interface NavigationItemBase {\n  /** Unique identifier for this item (typically resourceType or viewRef based). */\n  id: string;\n  /** Stable reference for configuration matching (not display-specific). */\n  ref: string;\n  /** Display label for the item. */\n  label: string;\n  /** URL path for this item's destination. */\n  urlPath: string;\n  /** Optional icon React node for sidebar/toolbar rendering. */\n  icon?: React.ReactNode;\n  /** Section reference for grouping (e.g., 'main', 'tools', 'settings'). */\n  section?: string;\n  /** Sidebar display policy (always visible, collapsible, etc.). */\n  displayPolicy?: SidebarItemDisplayPolicy;\n  /** Badge KEY (`<scope>:<identifier>`) naming a registered notification-badge definition (see `SidebarItem`). */\n  notificationBadgeRef?: string;\n  /** Keyboard shortcut hint displayed in UI (e.g., \"⌘K\"). */\n  shortcut?: string;\n  /** Additional search keywords for command menu filtering. */\n  searchKeywords?: string[];\n  /** Parent item reference for hierarchical nesting in sidebar. */\n  parentItemRef?: string;\n  /** Whether this item has children and can be collapsed. */\n  isCollapsible?: boolean;\n  /** Category for command menu grouping. */\n  commandCategory?: string;\n  /** Whether to render as icon-only (no label) in compact modes. */\n  iconOnly?: boolean;\n\n  /** Whether this item is disabled (feature gating, permissions, etc.). */\n  disabled?: boolean;\n  /** Whether this item shows a lock indicator (feature-locked but visible). */\n  featureLocked?: boolean;\n  /** Feature availability details when `featureLocked` or `disabled` due to features. */\n  featureAvailability?: NavigationFeatureAvailability;\n}\n\n/**\n * Resource navigation item — a navigable resource operation in app-level components.\n * Discriminated by `itemType: NavigationItemType.RESOURCE`.\n */\nexport interface ResourceNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.RESOURCE;\n  /** The resource type identifier (e.g., 'project', 'task'). */\n  resourceType: string;\n  /** The operation identifier within the resource config (e.g., 'list', 'create'). */\n  operationIdentifier: string;\n  /** The full operation configuration from the resource. */\n  operation: FrontendResourceConfiguration_Operation;\n  /** Pre-built resource context for navigation dispatch. */\n  resourceContext: FrontendResourceOperationContext;\n}\n\n/**\n * View navigation item — a navigable view in app-level components.\n * Discriminated by `itemType: NavigationItemType.VIEW`.\n */\nexport interface ViewNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.VIEW;\n  /** View reference identifier. */\n  viewRef: string;\n  /** Content type for routing (composite, chart, custom, flows/actors). */\n  contentType: ViewNavigationContentType;\n  /** Optional context resource IDs carried with the app-level navigation payload. */\n  contextResourceIdentifiers?: Record<string, string>;\n  /** Optional chart-route query params for standalone chart URL_PARAM bindings. */\n  urlParamValues?: Record<string, string>;\n  /** FlowsActorsView: the flows/actors system displayed. */\n  flowsActorsSystemRef?: string;\n  /** FullCustomView: reference to the registered custom component. */\n  fullCustomComponentRef?: string;\n  /** Required features configuration for feature gating. */\n  requiredFeatures?: RequiredFeaturesConfig;\n}\n\n/**\n * Engine-page navigation item — a navigable framework-owned page in app-level components.\n * Discriminated by `itemType: NavigationItemType.ENGINE_PAGE`.\n */\nexport interface EnginePageNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.ENGINE_PAGE;\n  /** Framework-owned page reference. */\n  pageRef: EnginePageRef;\n}\n\n/** Generic custom-component navigation item — launcher escape hatch with explicit runtime meaning. */\nexport interface CustomComponentNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.CUSTOM_COMPONENT;\n  componentRef: string;\n  /** Optional context resource IDs carried with the app-level navigation payload. */\n  contextResourceIdentifiers?: Record<string, string>;\n}\n\n/**\n * Settings-hub navigation item — opens the unified Settings Hub (overlay).\n * Discriminated by `itemType: NavigationItemType.SETTINGS_HUB`.\n */\nexport interface SettingsHubNavigationItem extends NavigationItemBase {\n  itemType: NavigationItemType.SETTINGS_HUB;\n  /** Section to pre-open; omit to open the hub's default section. */\n  sectionRef?: string;\n}\n\n/** Discriminated union of all navigation items. Narrow on `itemType`. */\nexport type AnyNavigationItem =\n  | ResourceNavigationItem\n  | ViewNavigationItem\n  | EnginePageNavigationItem\n  | CustomComponentNavigationItem\n  | SettingsHubNavigationItem;\n\n/** Type guard — narrows `AnyNavigationItem` to `ResourceNavigationItem`. */\nexport function isResourceNavigationItem(item: AnyNavigationItem): item is ResourceNavigationItem {\n  return item.itemType === NavigationItemType.RESOURCE;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `ViewNavigationItem`. */\nexport function isViewNavigationItem(item: AnyNavigationItem): item is ViewNavigationItem {\n  return item.itemType === NavigationItemType.VIEW;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `EnginePageNavigationItem`. */\nexport function isEnginePageNavigationItem(item: AnyNavigationItem): item is EnginePageNavigationItem {\n  return item.itemType === NavigationItemType.ENGINE_PAGE;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `CustomComponentNavigationItem`. */\nexport function isCustomComponentNavigationItem(item: AnyNavigationItem): item is CustomComponentNavigationItem {\n  return item.itemType === NavigationItemType.CUSTOM_COMPONENT;\n}\n\n/** Type guard — narrows `AnyNavigationItem` to `SettingsHubNavigationItem`. */\nexport function isSettingsHubNavigationItem(item: AnyNavigationItem): item is SettingsHubNavigationItem {\n  return item.itemType === NavigationItemType.SETTINGS_HUB;\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// Zod Validation Schemas (for runtime event validation)\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Zod schema for `NavigationSourceRelationship`.\n * Intentional lightweight subset of the full relationship schema —\n * only navigation-relevant fields for event validation.\n */\nconst navigationSourceRelationshipSchema = z.object({\n  parentResourceType: z.string(),\n  parentResourceId: z.string().optional(),\n  childResourceType: z.string(),\n  foreignKeyField: z.string().optional(),\n  relationshipEdgeKey: z.string().optional(),\n  inChildView: z.object({\n    showParentLink: z.boolean().optional(),\n    parentDisplay: z.enum(ParentDisplay).optional(),\n  }).optional(),\n});\n\n/** Zod schema for `NavigationInitiatorContext` — validates navigation event source. */\nexport const NavigationInitiatorContextSchema = z.object({\n  sourceZone: z.union([NavigationZoneSchema, z.literal(APP_LEVEL_NAVIGATION_SOURCE)]),\n  launcher: z.enum(ApplicationLevelComponentType).optional(),\n  sourceOperation: z.enum(CoreResourceOperation).optional(),\n  sourceRelationship: navigationSourceRelationshipSchema.optional(),\n});\n\n/** Zod schema for resource operation content. */\nconst navigationContent_ResourceOperationSchema = z.object({\n  contentType: z.literal(NavigationContentType.RESOURCE_OPERATION),\n  resourceContext: FrontendResourceOperationContextSchema,\n});\n\n/** Zod schema for composite view content. */\nconst navigationContent_CompositeViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.COMPOSITE_VIEW),\n  viewRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for chart view content. */\nconst navigationContent_ChartViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.CHART_VIEW),\n  viewRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n  urlParamValues: z.record(z.string(), z.string()).optional(),\n  requiredFeatures: RequiredFeaturesConfigSchema.optional(),\n  // Pre-resolved chart payloads ride on the navigation stack as runtime\n  // transport objects. They are already type-checked at construction sites; the\n  // stack schema only needs to validate that optional payload slots exist.\n  viewDefinition: z.custom<InsertedChartDeclaration>(() => true).optional(),\n  runtimeDescriptor: z.custom<ResolvedInsertedChartDescriptor>(() => true).optional(),\n});\n\n/** Zod schema for full custom view content. */\nconst navigationContent_FullCustomViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.FULL_CUSTOM_VIEW),\n  viewRef: z.string(),\n  fullCustomComponentRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for flows/actors view content. */\nconst navigationContent_FlowsActorsViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.FLOWS_ACTORS_VIEW),\n  viewRef: z.string(),\n  flowsActorsSystemRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for execution view content. */\nconst navigationContent_ExecutionViewSchema = z.object({\n  contentType: z.literal(NavigationContentType.EXECUTION_VIEW),\n  viewRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for generic custom component content. */\nconst navigationContent_CustomComponentSchema = z.object({\n  contentType: z.literal(NavigationContentType.CUSTOM_COMPONENT),\n  componentRef: z.string(),\n  contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),\n});\n\n/** Zod schema for engine page content. */\nconst navigationContent_EnginePageSchema = z.object({\n  contentType: z.literal(NavigationContentType.ENGINE_PAGE),\n  pageRef: z.nativeEnum(EnginePageRef),\n});\n\n/**\n * Zod schema for the unified Settings Hub overlay content.\n *\n * Mirrors {@link NavigationContent_SettingsHub}, which is the SECOND declaration of this shape —\n * the interface is what components consume and this is what the navigation events validate. The two\n * must move together: `subTabRef` was added to the interface first and the emit site kept failing\n * against this one, which is the whole reason the pair is called out here rather than left implicit.\n */\nconst navigationContent_SettingsHubSchema = z.object({\n  contentType: z.literal(NavigationContentType.SETTINGS_HUB),\n  sectionRef: z.string().optional(),\n  subTabRef: z.string().optional(),\n});\n\n/** Zod schema for inline create content. */\nconst navigationContent_InlineCreateSchema = z.object({\n  contentType: z.literal(NavigationContentType.INLINE_CREATE),\n  resourceContext: FrontendResourceOperationContextSchema,\n  defaultValues: z.record(z.string(), z.unknown()),\n});\n\n/** Zod schema for error modal content. */\nconst navigationContent_ErrorModalSchema = z.object({\n  contentType: z.literal(NavigationContentType.ERROR_MODAL),\n  errorType: z.string(),\n  wildoError: z.unknown(),\n});\n\n/** Discriminated union schema for all navigation content types. */\nexport const NavigationContentSchema = z.discriminatedUnion('contentType', [\n  navigationContent_ResourceOperationSchema,\n  navigationContent_CompositeViewSchema,\n  navigationContent_ChartViewSchema,\n  navigationContent_FullCustomViewSchema,\n  navigationContent_FlowsActorsViewSchema,\n  navigationContent_ExecutionViewSchema,\n  navigationContent_CustomComponentSchema,\n  navigationContent_EnginePageSchema,\n  navigationContent_SettingsHubSchema,\n  navigationContent_InlineCreateSchema,\n  navigationContent_ErrorModalSchema,\n]);\n\n/** Zod schema for a single navigation stack entry — validates serialized navigation state. */\nexport const NavigationStackEntrySchema = z.object({\n  id: z.string(),\n  content: NavigationContentSchema,\n  urlPath: z.string().optional(),\n  timestamp: z.number(),\n  zone: NavigationZoneSchema,\n  initiator: NavigationInitiatorContextSchema.optional(),\n  navigationSource: z.enum(NavigationSource),\n  transition: z.enum(NavigationTransition),\n  appearance: z.enum(OverlayAppearance).optional(),\n  ephemeral: z.boolean().optional(),\n  hostedPane: z.boolean().optional(),\n});\n"]}

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

@@ -12,7 +12,30 @@ import { z } from 'zod';
 import type { InlineParentContext } from '../../components/resources/component-props.resources-layout.frontend.schemas';
 import { NavigationZone, NavigationInitiatorContext, NavigationContent, NavigationContentType, NavigationZoneState, NavigationStackEntry, NavigationState, type AnyNavigationItem, type ViewNavigationItem } from './navigation.schemas';
 /**
- * Navigation utility class with static methods for navigation operations
+ * Navigation utility class with static methods for navigation operations.
+ *
+ * ## Why this is a CLASS of statics and not a module of functions — decided 2026-09-25
+ *
+ * It looks like the one file in this directory that is a namespace rather than a module: 56 static
+ * methods, ~1,180 lines of code, and exactly one export, so every consumer pulls all of it and
+ * nothing tree-shakes. Converting it to plain exported functions was measured and REJECTED, and the
+ * reason is not inertia:
+ *
+ * - **The class is a live TEST SEAM.** `vi.spyOn(NavigationUtils, 'resolveResourceUrl')` works
+ *   because the method hangs off an object; an ESM module binding cannot be reassigned, so four
+ *   existing spy sites would have to become `vi.mock` factories that restate the module's whole
+ *   surface. That trades a precise, one-method substitution for a mock that silently goes stale
+ *   whenever a method is added — the shape `.claude/rules/invariant-call-site-enumeration.md` #16
+ *   warns about.
+ * - **71 files import it**, so the conversion is a 71-file diff whose only observable gain is bundle
+ *   size in a frontend that already ships the whole navigation runtime. `design-philosophy.md` is
+ *   explicit that a cleaner pattern touching 15+ files loses to a targeted one unless it buys lasting
+ *   architectural value, and here it buys none: the class has no state, no inheritance and no
+ *   instances, so it is already a module in everything but its export shape.
+ *
+ * **What WOULD change the answer:** a measured bundle cost attributable to this file, or a decision
+ * to drop `vi.spyOn` in favour of dependency injection at these call sites. Neither is true today.
+ * Recorded here so the next reader who notices the shape does not re-derive the same answer.
  */
 export declare class NavigationUtils {
     private static resolveContextIdentifierValue;
@@ -47,7 +70,21 @@ export declare class NavigationUtils {
      * exactly how the per-instance timer failed: the ending and the waiting were wired separately.
      */
     private static endTransactionAndNotify;
+    /**
+     * End any open transaction outright, whatever its nesting depth.
+     *
+     * `commitTransaction` unwinds ONE level, which is right for a nested caller and wrong for a
+     * cleanup: seven test files call it in `beforeEach`/`afterEach` meaning "leave no transaction
+     * open", and counting nesting (2026-09-25) silently made a leftover depth-2 transaction survive
+     * one call — suppressing `useRouterSync` into the next test. Idempotent, and a no-op when nothing
+     * is open.
+     */
+    static resetTransactions(): void;
+    /** Clear both pending transaction timers. Safe to call when neither is armed. */
+    private static disarmTransactionTimers;
     private static _transactionSafetyTimer;
+    /** How many `beginTransaction` calls are open. See the nesting note on `beginTransaction`. */
+    private static _transactionDepth;
     /**
      * Begin a navigation transaction.
      *
@@ -130,6 +167,11 @@ export declare class NavigationUtils {
      * URL over. An EMPTY primary is "derivable" too: there is nothing to host.
      */
     static primaryContentIsUrlDerivable(content: NavigationContent | undefined): boolean;
+    /**
+     * Is this PRIMARY entry a hosted pane held there only because its secondary is collapsed?
+     * Such an entry is still addressed as `?pane=` on the host's URL, not by its own path.
+     */
+    static isHeldHostedPane(entry: NavigationStackEntry | undefined): boolean;
     /** `hostUrl` is the browser URL without the pane param; `paneUrl` the pane's own address, if any. */
     static decomposeHostedPaneBrowserUrl(browserUrl: string): {
         hostUrl: string;
@@ -137,6 +179,36 @@ export declare class NavigationUtils {
     };
     /** The host's URL (its own pane param, if any, replaced) carrying `paneUrl` as the hosted pane. */
     static composeHostedPaneBrowserUrl(hostUrl: string, paneUrl: string): string;
+    /**
+     * Is a SECONDARY entry HOSTED — its address carried as `?pane=` on the primary's URL?
+     *
+     * ## Two answers to one question, and only one of them wrote the URL
+     *
+     * This lived in two places that did not agree. The controller stamped
+     * `NavigationStackEntry.hostedPane` only for RESOURCE-OPERATION content; the composer below decided
+     * to compose purely from the primary being non-derivable. So a composite view, a chart or an engine
+     * page opened into the pane beside a board got a COMPOSED `?pane=` URL and an entry flagged
+     * `hostedPane: false` — and `zoneOwnsBrowserUrl` reads the FLAG, so the secondary zone was judged
+     * not to own the very URL that had just been composed for it. The reconciler then treated the
+     * pane's address as unclaimed.
+     *
+     * ## The resource condition is the one that survives, and the restore path is why
+     *
+     * `useHostedPaneRouteSync` rebuilds a `?pane=` address by resolving it as a RESOURCE route —
+     * `route.resourceType` and `route.operation` — so a resource pane is the only kind a reload can put
+     * back. Composing a pane URL for anything else writes an address that claims a pane the next reload
+     * cannot restore, which is a worse outcome than a pane whose URL is simply its own: a promise the
+     * product cannot keep. So the narrower answer is the true one, and the composer adopts it rather
+     * than the flag being widened to match the composer.
+     *
+     * Addressability (`shouldUpdateUrl`, a resolved `urlPath`) stays with the CONTROLLER: it is about
+     * the navigation being performed, not about the two contents, and the composer has already
+     * answered it by the time it holds an `entryUrlPath`.
+     */
+    static hostedPaneApplies(params: {
+        paneContent: NavigationContent | undefined;
+        primaryTop: NavigationStackEntry | undefined;
+    }): boolean;
     /**
      * The browser URL to write when `zone`'s visible entry is (or becomes) `entryUrlPath`.
      *
@@ -151,12 +223,26 @@ export declare class NavigationUtils {
      * - SECONDARY beside a derivable primary → the entry's own URL, the pre-existing model (#203).
      * - PRIMARY, or a secondary that has just emptied → the entry's own URL; a hosted pane is closed by
      *   the URL reconciler the moment the `pane` param is gone.
-     * - COMPANION is not hosted: no layout opens a companion beside a non-resource primary, and a
-     *   second parameter would be invented for nothing. It keeps the entry's own URL.
+     * - COMPANION beside a HOSTED secondary → the secondary's composed URL, unchanged. The companion
+     *   gets no parameter of its own, so its address is not in the URL while the pane holds `?pane=`.
+     * - COMPANION otherwise → the entry's own URL.
+     *
+     * The companion row was "not hosted, keeps its own URL", on the premise that no layout opens a
+     * companion beside a non-resource primary. The three-pane layout over a board does exactly that,
+     * and writing the companion's bare address dropped both the host and `?pane=` — whereupon the pane
+     * reconciler, seeing the pane leave the URL, cleared the secondary. Opening the companion closed
+     * the pane. Keeping the composed URL costs the companion its address on reload; the alternative, a
+     * second parameter, is a URL contract of its own and would be invented to serve one layout.
      */
     static resolveBrowserUrlForZoneEntry(params: {
         zone: NavigationZone;
         entryUrlPath: string | undefined;
+        /**
+         * The content being addressed. Required to answer {@link hostedPaneApplies} — without it the
+         * composer decided hosting from the PRIMARY alone and composed `?pane=` for panes the reload
+         * path cannot rebuild, contradicting the flag every reader of the URL consults.
+         */
+        paneContent: NavigationContent | undefined;
         currentBrowserUrl: string;
         getZoneState: (zone: NavigationZoneName) => NavigationZoneState;
     }): string | undefined;
@@ -467,9 +553,19 @@ export declare class NavigationUtils {
      *
      * ## What a reconstruction can and cannot read
      *
-     * An override scoped with `fromZone` says "when clicked FROM there". A reload was clicked from
-     * nowhere, so such an override cannot describe it and is skipped — the zone map decides, exactly
-     * as before. `viewport` IS knowable and is honoured when the caller supplies one; a caller with
+     * An override scoped with `fromZone` says "when clicked FROM there". The question this predicate
+     * answers fixes the source: it asks whether the detail SPLITS OUT OF PRIMARY, i.e. what a click
+     * made from the list in primary would have done. So an override scoped to PRIMARY describes
+     * exactly this reconstruction and is honoured; one scoped to any other zone describes a click
+     * made from somewhere else and is skipped.
+     *
+     * It skipped EVERY scoped override until 2026-09-25, on the reading that a reload "was clicked
+     * from nowhere". That was harmless while no application scoped one, and it stopped being harmless
+     * the day scoping became the documented fix: an unscoped SPLIT override also fires from inside
+     * the pane, where it replaces the record, so Wonder Todos scoped its `todos` override to
+     * `fromZone: PRIMARY` and the framework's navigation skill told every application to do the same.
+     * From then on a todo opened by URL filled the page while the same todo clicked opened beside its
+     * list — measured in the running application, at desktop and at tablet widths. `viewport` IS knowable and is honoured when the caller supplies one; a caller with
      * no measured viewport yet matches only the unconditional overrides, which is the conservative
      * half (an unknown viewport is not a particular one — the same reading `resolveCollapseMode`
      * takes).