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

package/dist/esm/core/navigation/navigation-cascade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-cascade.js","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation-cascade.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The CASCADING ORCHESTRATOR: what fills the zones a reader did not click.\n *\n * Two functions, one concern. When content lands in an adjacent zone, the zones ABOVE it must show\n * the ancestors that content belongs to, or the reader sees a record with no context beside it —\n * `cascadeAncestorZones` for a record with a parent chain, `cascadeSiblingListIntoPrimary` for a FLAT\n * resource whose detail was split out of primary (#203).\n *\n * Split out of `useNavigationController.ts` on 2026-09-25. It is the ONE piece both halves of that\n * module used — the controller cascades after a click, the router-sync hooks cascade after a deep\n * link — which is why it is its own module rather than living with either.\n */\n\nimport {\n  useNavigate,\n} from 'react-router-dom';\nimport {\n  FrontendEvents,\n} from '~wildo-frontend-lib/core/events/events.frontend.schemas';\nimport {\n  NavigationZoneState,\n  NavigationContent,\n  NavigationContentType,\n} from './navigation.schemas';\nimport {\n  NavigationTransition,\n  NavigationZoneName,\n  CoreResourceOperation,\n} from '@wildo-ai/saas-models';\nimport type { FrontendResource_ParentResourceRequirement } from '~wildo-frontend-lib/core/resources/resource-path.frontend.schemas';\nimport type {\n  FrontendResourcesRegistry,\n} from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport { NavigationSource } from './navigation.schemas';\nimport { NavigationUtils } from './navigation.utils';\nimport { FrontendResourceUtils, frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\nimport { isOperationAddressable } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport {\n  resolveEffectiveCoreOperationFromOperation,\n  getOperationsForCoreSemantic,\n  pickPreferredOperationForCoreSemantic,\n} from '~wildo-frontend-lib/core/resources/operation-semantics.frontend.utils';\n\nimport { logDebug, resourceOperationOwnsBrowserUrl, updateBrowserUrl } from './navigation-controller-internals';\n// ================================\n// Cascading Orchestrator\n// ================================\n\n/**\n * Auto-populate ancestor zones when navigating to SECONDARY or COMPANION.\n *\n * When a resource is placed in SECONDARY or COMPANION, its ancestor resources\n * should be visible in the zones above it. This function checks which\n * ancestor zones are empty and populates them with the appropriate content.\n *\n * Rules:\n * - Only cascades for resource operations (not views)\n * - Only populates EMPTY zones (never overwrites user-navigated content)\n * - Uses `parentResourcesRequirements` to determine ancestor chain\n * - Stops at primary scope ancestors (org/user level)\n * - Maximum 2 ancestor zones (PRIMARY + SECONDARY for a COMPANION target)\n */\n/** Put a flat resource's LIST into PRIMARY beside a detail restored into SECONDARY (#203). */\nexport function cascadeSiblingListIntoPrimary(params: {\n  resourceType: string;\n  contextResourceIdentifiers: Record<string, string>;\n  parentResourcesRequirements: FrontendResource_ParentResourceRequirement[];\n  registry: FrontendResourcesRegistry;\n  emit: (event: string, payload: any) => void;\n  getZoneState: (zone: NavigationZoneName) => NavigationZoneState;\n}): void {\n  const { resourceType, contextResourceIdentifiers, parentResourcesRequirements, registry, emit, getZoneState } = params;\n  if (getZoneState(NavigationZoneName.PRIMARY).stack.length > 0) return;\n\n  const resourceConfig = registry.resourceConfigurations?.[resourceType];\n  if (!resourceConfig) return;\n\n  const listContextIdentifiers = { ...contextResourceIdentifiers };\n  delete listContextIdentifiers[resourceType];\n\n  /*\n   * The DEFAULT addressable LIST, picked WITHOUT the context-addressability check.\n   * `pickPreferredOperationForCoreSemanticAddressability` asks \"reachable given the PARENT context\",\n   * which a flat STANDALONE resource can never satisfy — it answers false for an operation that is\n   * plainly addressable and reachable from the sidebar. `allowBulk` is required too: a LIST addresses\n   * a COLLECTION and the semantic filter drops bulk operations by default.\n   */\n  const listOperation = pickPreferredOperationForCoreSemantic(\n    getOperationsForCoreSemantic(resourceConfig.operations ?? [], CoreResourceOperation.LIST, { allowBulk: true })\n      .filter((candidate) => isOperationAddressable(candidate.operationFrontendConfig)),\n    CoreResourceOperation.LIST,\n    { allowBulk: true },\n  );\n  if (!listOperation) return;\n\n  /*\n   * The list's OWN address, which is not the same thing as writing the browser URL.\n   *\n   * This entry was placed address-less under the note \"the browser URL belongs to the DETAIL in\n   * secondary\" — true of who WRITES the URL, and wrong as a reason to leave `urlPath` empty. An\n   * entry's `urlPath` is its ADDRESS, read by everything that asks what a zone holds: `goBack`,\n   * `dismissZone`, `findStructuralRouteOwner`, `zoneOwnsBrowserUrl`. Nothing here writes the\n   * browser URL — this is an emit, and the controller's write lives in `navigate()`.\n   *\n   * Measured on the workbench, 2026-09-25: with the list address-less, `resolveZoneDismissUrl`\n   * found no primary address, wrote nothing, and the pane CLOSED while the URL still named it — so\n   * the next reload reopened it. `goBack` from the last pane had the identical hole, which predates\n   * the dismiss control and is fixed by the same line.\n   */\n  const listUrl = NavigationUtils.resolveResourceUrl(\n    resourceConfig as never,\n    listOperation as never,\n    listContextIdentifiers,\n    registry.allResourceFieldIdentifiers,\n    parentResourcesRequirements as never,\n  )?.resolvedUrl;\n\n  emit(FrontendEvents.NAVIGATION_REPLACE, {\n    zone: NavigationZoneName.PRIMARY,\n    content: {\n      contentType: NavigationContentType.RESOURCE_OPERATION,\n      resourceContext: frontendResourceUtils.createFrontendResourceOperationContextFromOperation({\n        resourceType, operation: listOperation,\n        contextResourceIdentifiers: listContextIdentifiers,\n        parentResourcesRequirements,\n      }),\n    },\n    ...(listUrl ? { urlPath: listUrl } : {}),\n    stackEntryId: NavigationUtils.generateStackEntryId(),\n    initiator: { sourceZone: NavigationZoneName.PRIMARY },\n    navigationSource: NavigationSource.URL_SYNC,\n    transition: NavigationTransition.REPLACE,\n  });\n}\n\nexport function cascadeAncestorZones(\n  targetContent: NavigationContent & { contentType: NavigationContentType.RESOURCE_OPERATION },\n  resolvedZone: NavigationZoneName,\n  registry: FrontendResourcesRegistry,\n  contextIdentifiers: Record<string, string>,\n  emit: (event: string, payload: any) => void,\n  routerNavigate: ReturnType<typeof useNavigate> | null,\n  getZoneState: (zone: NavigationZoneName) => NavigationZoneState,\n  options?: {\n    overwriteExisting?: boolean;\n  },\n): void {\n  const parentRequirements = targetContent.resourceContext.parentResourcesRequirements as FrontendResource_ParentResourceRequirement[];\n  if (!parentRequirements || parentRequirements.length === 0) return;\n\n  // Determine which zones need population.\n  // Order matters: zonesToPopulate[i] maps to ancestors[i] (nearest parent first).\n  // For COMPANION target: nearest parent → SECONDARY (adjacent), furthest → PRIMARY (root).\n  // This maintains the master-detail-detail convention: PRIMARY=broadest, COMPANION=most specific.\n  const zonesToPopulate: NavigationZoneName[] = [];\n  if (resolvedZone === NavigationZoneName.SECONDARY) {\n    zonesToPopulate.push(NavigationZoneName.PRIMARY);\n  } else if (resolvedZone === NavigationZoneName.COMPANION) {\n    zonesToPopulate.push(NavigationZoneName.SECONDARY, NavigationZoneName.PRIMARY);\n  }\n\n  if (zonesToPopulate.length === 0) return;\n\n  // parentResourcesRequirements is ordered root → leaf (closest ancestor last).\n  // Reverse to process nearest parent first — nearest maps to adjacent zone.\n  const ancestors = [...parentRequirements].reverse();\n\n  const targetResourceType = targetContent.resourceContext.resourceType;\n\n  for (let i = 0; i < zonesToPopulate.length && i < ancestors.length; i++) {\n    const zone = zonesToPopulate[i];\n    const ancestor = ancestors[i];\n\n    // Skip primary scope ancestors (org, user) — these don't get a zone\n    if (ancestor.isPrimaryScope) continue;\n\n    // Controller-driven cascade keeps existing user context intact, but URL-first\n    // reconstruction is allowed to replace ancestor zones so the visible stack\n    // matches the authoritative browser URL again.\n    const zoneState = getZoneState(zone);\n    if (!options?.overwriteExisting && zoneState.stack.length > 0) continue;\n\n    // Get ancestor resource config\n    const ancestorResourceType = ancestor.resourceType;\n    const ancestorConfig = registry.resourceConfigurations?.[ancestorResourceType];\n    if (!ancestorConfig) continue;\n\n    // Find relationship between ancestor and target (or intermediate child)\n    const childType = ancestor.childResourceType\n      ?? (i === 0 ? targetResourceType : ancestors[i - 1].resourceType);\n    const relationship = NavigationUtils.findRelationshipBetween(\n      ancestorResourceType, childType, registry, ancestor.foreignKeyField\n    );\n\n    // Build parent requirements for the ancestor itself:\n    // The ancestor's parents are those ABOVE it in the chain (root → leaf ordering).\n    // Using slice(0, index) ensures we only include entries before the ancestor,\n    // not entries below it (which are its children/grandchildren, not parents).\n    // Previously used filter(req => req.resourceType !== ancestorResourceType) which\n    // incorrectly kept descendants as parents for non-adjacent ancestors (Bug #1).\n    // `ancestors` is reversed (nearest parent first) but `parentRequirements`\n    // stays root → leaf, so convert back by position instead of looking up by\n    // resource type. Position-based slicing is what keeps repeated/self-ref\n    // parent types from collapsing onto the first matching entry.\n    const ancestorIndex = parentRequirements.length - 1 - i;\n    const ancestorParentReqs = ancestorIndex > 0\n      ? parentRequirements.slice(0, ancestorIndex)\n      : [];\n\n    // Build ancestor resource context\n    const ancestorContextIdentifiers: Record<string, string> = {};\n    for (const req of ancestorParentReqs) {\n      const contextKey = req.foreignKeyField ?? req.resourceType;\n      // Prefer the FK-keyed slot when present. Same-type parent chains store the\n      // parent id under the FK field so the resource-type key can continue to\n      // represent the current record.\n      const id = contextIdentifiers[contextKey] ?? contextIdentifiers[req.resourceType];\n      if (id) {\n        ancestorContextIdentifiers[contextKey] = id;\n      }\n    }\n    const ancestorSelfId = contextIdentifiers[ancestorResourceType];\n    const ancestorSelectionContextIdentifiers = ancestorSelfId\n      ? {\n          ...ancestorContextIdentifiers,\n          [ancestorResourceType]: ancestorSelfId,\n        }\n      : ancestorContextIdentifiers;\n\n    const opConfig = NavigationUtils.resolveAncestorOperationConfig(\n      relationship,\n      ancestorConfig as any,\n      {\n        registry,\n        contextResourceIdentifiers: ancestorSelectionContextIdentifiers,\n        contextualParameters: FrontendResourceUtils.buildContextualParameters(\n          ancestorSelectionContextIdentifiers,\n          registry,\n        ),\n      },\n    );\n    if (!opConfig) continue;\n    const ancestorOp = resolveEffectiveCoreOperationFromOperation(opConfig);\n    if (ancestorSelfId && ancestorOp === CoreResourceOperation.READ) {\n      ancestorContextIdentifiers[ancestorResourceType] = ancestorSelfId;\n    }\n\n    const ancestorResourceContext = frontendResourceUtils.createFrontendResourceOperationContextFromOperation({\n      resourceType: ancestorResourceType,\n      operation: opConfig,\n      contextResourceIdentifiers: ancestorContextIdentifiers,\n      parentResourcesRequirements: ancestorParentReqs,\n    });\n\n    const ancestorContent: NavigationContent = {\n      contentType: NavigationContentType.RESOURCE_OPERATION,\n      resourceContext: ancestorResourceContext,\n    };\n\n    // Resolve URL for ancestor — only when the ancestor operation actually\n    // owns a browser URL (declared ADDRESSABLE). Same surface gate as the main\n    // navigate() path: an EMBEDDED ancestor read must not stamp an unroutable\n    // URL onto the revealed zone entry or the browser.\n    let ancestorUrl: string | undefined;\n    if (resourceOperationOwnsBrowserUrl(opConfig)) {\n      const resolved = NavigationUtils.resolveResourceUrl(\n        ancestorConfig as any,\n        opConfig as any,\n        ancestorContextIdentifiers,\n        registry.allResourceFieldIdentifiers,\n        ancestorParentReqs as any,\n      );\n      if (resolved?.resolvedUrl) {\n        ancestorUrl = resolved.resolvedUrl;\n      }\n    }\n\n    const stackEntryId = NavigationUtils.generateStackEntryId();\n    logDebug('cascadeAncestorZones: populating ancestor zone', {\n      zone,\n      ancestorResourceType,\n      ancestorOp,\n      ancestorUrl,\n    });\n    emit(FrontendEvents.NAVIGATION_REPLACE, {\n      zone,\n      content: ancestorContent,\n      urlPath: ancestorUrl,\n      stackEntryId,\n      initiator: { sourceZone: zone },\n      navigationSource: NavigationSource.CONTROLLER,\n      transition: NavigationTransition.REPLACE,\n    });\n\n    // Update URL only for PRIMARY zone ancestor (the URL bar shows PRIMARY)\n    // Skip URL update when routerNavigate is null (reverse cascade from URL sync)\n    if (zone === NavigationZoneName.PRIMARY && ancestorUrl && routerNavigate) {\n      updateBrowserUrl(routerNavigate, ancestorUrl, true);\n    }\n  }\n}"]}

package/dist/esm/core/navigation/navigation-clean-break.frontend.utils.d.ts

@@ -1,5 +1,27 @@
 export type FreshStartNavigationSource = 'app_level_navigation' | 'promote_navigation';
+export type OverlayBreakoutNavigationSource = 'overlay_breakout_navigation';
 export type StrongResetNavigationSource = 'home_navigation' | 'path_navigation';
+/**
+ * Close the overlay when content it launched lands in a STRUCTURAL zone.
+ *
+ * An overlay is a floating layer over the layout, and the layout underneath is inert while it is
+ * open. So content that starts inside the overlay and is placed in PRIMARY / SECONDARY / COMPANION
+ * has left the overlay behind: the person asked for that content, and what they get is the overlay
+ * they were already looking at, with the thing they asked for rendered beneath its own backdrop.
+ *
+ * Measured 2026-09-22 on the Wonder Todos todo READ overlay (#1511). Clicking the overlay's own
+ * `Edit` action moved the URL from `…/todos` to `…/todos/<id>` and put `input[name="title"]` in the
+ * document — while the dialog count stayed at ONE and that dialog did not contain the form. Every
+ * click on it was intercepted by `[data-slot=dialog-overlay]`, so the edit form was unreachable
+ * until the overlay was dismissed by hand.
+ *
+ * This is NOT {@link emitFreshStartNavigationCleanup}: breaking out of an overlay says nothing
+ * about the SECONDARY and COMPANION zones of the page underneath, which are the context the person
+ * is returning to. Only the overlay closes.
+ *
+ * PROMOTE is excluded by the caller because it already performs the stronger reset.
+ */
+export declare function emitOverlayBreakoutCleanup(emit: (event: string, payload: unknown) => void, source: OverlayBreakoutNavigationSource): void;
 /**
  * Clear every non-primary surface that should not survive a fresh-start navigation.
  *

package/dist/esm/core/navigation/navigation-clean-break.frontend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-clean-break.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../src/core/navigation/navigation-clean-break.frontend.utils.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,0BAA0B,GAClC,sBAAsB,GACtB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,2BAA2B,GACnC,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,EAC/C,MAAM,EAAE,0BAA0B,GACjC,IAAI,CAKN;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CASP;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,2BAA2B,CAAC;CACtC,GAAG,IAAI,CAYP"}
+{"version":3,"file":"navigation-clean-break.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation-clean-break.frontend.utils.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,0BAA0B,GAClC,sBAAsB,GACtB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,+BAA+B,GAAG,6BAA6B,CAAC;AAE5E,MAAM,MAAM,2BAA2B,GACnC,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,EAC/C,MAAM,EAAE,+BAA+B,GACtC,IAAI,CAGN;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,EAC/C,MAAM,EAAE,0BAA0B,GACjC,IAAI,CAwBN;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CASP;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,2BAA2B,CAAC;CACtC,GAAG,IAAI,CAYP"}

package/dist/esm/core/navigation/navigation-clean-break.frontend.utils.js

@@ -2,6 +2,30 @@ import { FrontendEvents } from '../../core/events/events.frontend.schemas.js';
 import { NavigationZoneName } from '@wildo-ai/saas-models';
 import { NavigationUtils } from './navigation.utils.js';
 import { NavigationZone } from './navigation.schemas.js';
+/**
+ * Close the overlay when content it launched lands in a STRUCTURAL zone.
+ *
+ * An overlay is a floating layer over the layout, and the layout underneath is inert while it is
+ * open. So content that starts inside the overlay and is placed in PRIMARY / SECONDARY / COMPANION
+ * has left the overlay behind: the person asked for that content, and what they get is the overlay
+ * they were already looking at, with the thing they asked for rendered beneath its own backdrop.
+ *
+ * Measured 2026-09-22 on the Wonder Todos todo READ overlay (#1511). Clicking the overlay's own
+ * `Edit` action moved the URL from `…/todos` to `…/todos/<id>` and put `input[name="title"]` in the
+ * document — while the dialog count stayed at ONE and that dialog did not contain the form. Every
+ * click on it was intercepted by `[data-slot=dialog-overlay]`, so the edit form was unreachable
+ * until the overlay was dismissed by hand.
+ *
+ * This is NOT {@link emitFreshStartNavigationCleanup}: breaking out of an overlay says nothing
+ * about the SECONDARY and COMPANION zones of the page underneath, which are the context the person
+ * is returning to. Only the overlay closes.
+ *
+ * PROMOTE is excluded by the caller because it already performs the stronger reset.
+ */
+export function emitOverlayBreakoutCleanup(emit, source) {
+    NavigationUtils.beginTransaction(source);
+    emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });
+}
 /**
  * Clear every non-primary surface that should not survive a fresh-start navigation.
  *
@@ -11,8 +35,27 @@ import { NavigationZone } from './navigation.schemas.js';
  */
 export function emitFreshStartNavigationCleanup(emit, source) {
     NavigationUtils.beginTransaction(source);
-    emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.SECONDARY });
-    emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.COMPANION });
+    /*
+     * ─── A PERSISTENT pane survives this too, and the contract is what says so ──────────────────────
+     *
+     * `TransitionConfig.persistent` promises "the split zone persists when the source zone's content
+     * changes", and the shape it exists for is a reference kept open WHILE YOU MOVE AROUND — a thread,
+     * a terminal, a doc. Moving around is sidebar navigation, and every sidebar click is a fresh start,
+     * so clearing unconditionally here left the mechanism working only for drill-ins inside one
+     * primary destination. `persistent` only ever targets COMPANION, so the clear it could not survive
+     * was the one it most needed to.
+     *
+     * `preservePersistent` is carried on the payload and read by the reducer, which is the only place
+     * that can see whether the zone's top entry is persistent — this module emits, it does not read
+     * state. A PROMOTE is the same answer: it breaks out of the structural flow, and a reference panel
+     * is not part of that flow.
+     *
+     * What still closes a persistent pane: its own dismiss control, `goBack` in that zone, and a
+     * direct `CLEAR_ZONE`. Persistence means "do not close me because something else changed", never
+     * "I cannot be closed".
+     */
+    emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.SECONDARY, preservePersistent: true });
+    emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.COMPANION, preservePersistent: true });
     emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });
 }
 /**

package/dist/esm/core/navigation/navigation-clean-break.frontend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-clean-break.frontend.utils.js","sourceRoot":"","sources":["../../../../src/core/navigation/navigation-clean-break.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAUtD;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,IAA+C,EAC/C,MAAkC;IAElC,eAAe,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,CAAC,CAAC;IACnF,IAAI,CAAC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,CAAC,CAAC;IACnF,IAAI,CAAC,cAAc,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAI1C;IACC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,GAAG,GAAG,EAAE,GAAG,MAAM,CAAC;IAExD,0BAA0B,CAAC;QACzB,IAAI;QACJ,cAAc;QACd,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,iBAAiB;KAC1B,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAK1C;IACC,MAAM,EACJ,IAAI,EACJ,cAAc,EACd,IAAI,EACJ,MAAM,GAAG,iBAAiB,GAC3B,GAAG,MAAM,CAAC;IAEX,eAAe,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,OAAO,EAAE,CAAC,CAAC;IACjF,+BAA+B,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;IAC9D,cAAc,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC","sourcesContent":["import { FrontendEvents } from '~wildo-frontend-lib/core/events/events.frontend.schemas';\nimport { NavigationZoneName } from '@wildo-ai/saas-models';\nimport { NavigationUtils } from './navigation.utils';\nimport { NavigationZone } from './navigation.schemas';\n\nexport type FreshStartNavigationSource =\n  | 'app_level_navigation'\n  | 'promote_navigation';\n\nexport type StrongResetNavigationSource =\n  | 'home_navigation'\n  | 'path_navigation';\n\n/**\n * Clear every non-primary surface that should not survive a fresh-start navigation.\n *\n * App-level and PROMOTE navigations both intentionally break out of the current\n * structural flow. The reset must therefore stay centralized so secondary,\n * companion, and overlay cleanup cannot drift apart between call sites.\n */\nexport function emitFreshStartNavigationCleanup(\n  emit: (event: string, payload: unknown) => void,\n  source: FreshStartNavigationSource,\n): void {\n  NavigationUtils.beginTransaction(source);\n  emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.SECONDARY });\n  emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.COMPANION });\n  emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });\n}\n\n/**\n * Home/error recovery is a stronger reset than generic app-level replacement:\n * there is no controller-managed PRIMARY replacement entry to overwrite the\n * current root content, so PRIMARY must be cleared explicitly before routing to\n * the engine home path.\n */\nexport function navigateHomeWithFreshStart(params: {\n  emit: (event: string, payload: unknown) => void;\n  routerNavigate: (path: string, options?: { replace?: boolean }) => void;\n  homePath?: string;\n}): void {\n  const { emit, routerNavigate, homePath = '/' } = params;\n\n  navigatePathWithFreshStart({\n    emit,\n    routerNavigate,\n    path: homePath,\n    source: 'home_navigation',\n  });\n}\n\n/**\n * Some shell-owned recovery paths need a stronger reset before routing to a\n * concrete URL. They do not go through controller-owned PRIMARY replacement, so\n * PRIMARY must be cleared explicitly before React Router changes location.\n */\nexport function navigatePathWithFreshStart(params: {\n  emit: (event: string, payload: unknown) => void;\n  routerNavigate: (path: string, options?: { replace?: boolean }) => void;\n  path: string;\n  source?: StrongResetNavigationSource;\n}): void {\n  const {\n    emit,\n    routerNavigate,\n    path,\n    source = 'path_navigation',\n  } = params;\n\n  NavigationUtils.beginTransaction(source);\n  emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.PRIMARY });\n  emitFreshStartNavigationCleanup(emit, 'app_level_navigation');\n  routerNavigate(path, { replace: true });\n}\n"]}
+{"version":3,"file":"navigation-clean-break.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation-clean-break.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAYtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAA+C,EAC/C,MAAuC;IAEvC,eAAe,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,cAAc,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,IAA+C,EAC/C,MAAkC;IAElC,eAAe,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7G,IAAI,CAAC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7G,IAAI,CAAC,cAAc,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAI1C;IACC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,GAAG,GAAG,EAAE,GAAG,MAAM,CAAC;IAExD,0BAA0B,CAAC;QACzB,IAAI;QACJ,cAAc;QACd,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,iBAAiB;KAC1B,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAK1C;IACC,MAAM,EACJ,IAAI,EACJ,cAAc,EACd,IAAI,EACJ,MAAM,GAAG,iBAAiB,GAC3B,GAAG,MAAM,CAAC;IAEX,eAAe,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,OAAO,EAAE,CAAC,CAAC;IACjF,+BAA+B,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;IAC9D,cAAc,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC","sourcesContent":["import { FrontendEvents } from '~wildo-frontend-lib/core/events/events.frontend.schemas';\nimport { NavigationZoneName } from '@wildo-ai/saas-models';\nimport { NavigationUtils } from './navigation.utils';\nimport { NavigationZone } from './navigation.schemas';\n\nexport type FreshStartNavigationSource =\n  | 'app_level_navigation'\n  | 'promote_navigation';\n\nexport type OverlayBreakoutNavigationSource = 'overlay_breakout_navigation';\n\nexport type StrongResetNavigationSource =\n  | 'home_navigation'\n  | 'path_navigation';\n\n/**\n * Close the overlay when content it launched lands in a STRUCTURAL zone.\n *\n * An overlay is a floating layer over the layout, and the layout underneath is inert while it is\n * open. So content that starts inside the overlay and is placed in PRIMARY / SECONDARY / COMPANION\n * has left the overlay behind: the person asked for that content, and what they get is the overlay\n * they were already looking at, with the thing they asked for rendered beneath its own backdrop.\n *\n * Measured 2026-09-22 on the Wonder Todos todo READ overlay (#1511). Clicking the overlay's own\n * `Edit` action moved the URL from `…/todos` to `…/todos/<id>` and put `input[name=\"title\"]` in the\n * document — while the dialog count stayed at ONE and that dialog did not contain the form. Every\n * click on it was intercepted by `[data-slot=dialog-overlay]`, so the edit form was unreachable\n * until the overlay was dismissed by hand.\n *\n * This is NOT {@link emitFreshStartNavigationCleanup}: breaking out of an overlay says nothing\n * about the SECONDARY and COMPANION zones of the page underneath, which are the context the person\n * is returning to. Only the overlay closes.\n *\n * PROMOTE is excluded by the caller because it already performs the stronger reset.\n */\nexport function emitOverlayBreakoutCleanup(\n  emit: (event: string, payload: unknown) => void,\n  source: OverlayBreakoutNavigationSource,\n): void {\n  NavigationUtils.beginTransaction(source);\n  emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });\n}\n\n/**\n * Clear every non-primary surface that should not survive a fresh-start navigation.\n *\n * App-level and PROMOTE navigations both intentionally break out of the current\n * structural flow. The reset must therefore stay centralized so secondary,\n * companion, and overlay cleanup cannot drift apart between call sites.\n */\nexport function emitFreshStartNavigationCleanup(\n  emit: (event: string, payload: unknown) => void,\n  source: FreshStartNavigationSource,\n): void {\n  NavigationUtils.beginTransaction(source);\n  /*\n   * ─── A PERSISTENT pane survives this too, and the contract is what says so ──────────────────────\n   *\n   * `TransitionConfig.persistent` promises \"the split zone persists when the source zone's content\n   * changes\", and the shape it exists for is a reference kept open WHILE YOU MOVE AROUND — a thread,\n   * a terminal, a doc. Moving around is sidebar navigation, and every sidebar click is a fresh start,\n   * so clearing unconditionally here left the mechanism working only for drill-ins inside one\n   * primary destination. `persistent` only ever targets COMPANION, so the clear it could not survive\n   * was the one it most needed to.\n   *\n   * `preservePersistent` is carried on the payload and read by the reducer, which is the only place\n   * that can see whether the zone's top entry is persistent — this module emits, it does not read\n   * state. A PROMOTE is the same answer: it breaks out of the structural flow, and a reference panel\n   * is not part of that flow.\n   *\n   * What still closes a persistent pane: its own dismiss control, `goBack` in that zone, and a\n   * direct `CLEAR_ZONE`. Persistence means \"do not close me because something else changed\", never\n   * \"I cannot be closed\".\n   */\n  emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.SECONDARY, preservePersistent: true });\n  emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.COMPANION, preservePersistent: true });\n  emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });\n}\n\n/**\n * Home/error recovery is a stronger reset than generic app-level replacement:\n * there is no controller-managed PRIMARY replacement entry to overwrite the\n * current root content, so PRIMARY must be cleared explicitly before routing to\n * the engine home path.\n */\nexport function navigateHomeWithFreshStart(params: {\n  emit: (event: string, payload: unknown) => void;\n  routerNavigate: (path: string, options?: { replace?: boolean }) => void;\n  homePath?: string;\n}): void {\n  const { emit, routerNavigate, homePath = '/' } = params;\n\n  navigatePathWithFreshStart({\n    emit,\n    routerNavigate,\n    path: homePath,\n    source: 'home_navigation',\n  });\n}\n\n/**\n * Some shell-owned recovery paths need a stronger reset before routing to a\n * concrete URL. They do not go through controller-owned PRIMARY replacement, so\n * PRIMARY must be cleared explicitly before React Router changes location.\n */\nexport function navigatePathWithFreshStart(params: {\n  emit: (event: string, payload: unknown) => void;\n  routerNavigate: (path: string, options?: { replace?: boolean }) => void;\n  path: string;\n  source?: StrongResetNavigationSource;\n}): void {\n  const {\n    emit,\n    routerNavigate,\n    path,\n    source = 'path_navigation',\n  } = params;\n\n  NavigationUtils.beginTransaction(source);\n  emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.PRIMARY });\n  emitFreshStartNavigationCleanup(emit, 'app_level_navigation');\n  routerNavigate(path, { replace: true });\n}\n"]}

package/dist/esm/core/navigation/navigation-controller-internals.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The two things every layer of the navigation controller needs, and neither of which belongs to any
+ * one of them: the debug channel, and the one function that writes the browser URL.
+ *
+ * Extracted 2026-09-25 when `useNavigationController.ts` was split — 2,322 lines holding click
+ * resolution, URL reconciliation, the ancestor cascade, clean breaks, dismiss and the emit bridge in
+ * one module. Measured across the seam, the ROUTER-SYNC half used exactly THREE symbols from the
+ * controller half (`logDebug` and the two cascade functions), which is what made the split cheap
+ * enough to be worth doing at all.
+ *
+ * ## The debug type name is DELIBERATELY still `useNavigationController`
+ *
+ * `logger.debugByType` keys on this string, and it is what an operator or a test types to turn the
+ * channel on (`setDebugTypeLogging('useNavigationController', true)`). Giving each split module its
+ * own name would be finer-grained and would silently stop every existing toggle from reaching the
+ * router-sync logs — a split is not the moment to change what a diagnostic switch covers.
+ */
+import type { useNavigate } from 'react-router-dom';
+import { ResourceOperationFrontendSurface } from '@wildo-ai/saas-models';
+export declare const logDebug: (message: string, context?: Record<string, unknown>) => void;
+/**
+ * Update the browser URL via React Router's navigate function, so React Router's
+ * `useLocation` hook updates. Everything derived from `useLocation` depends on
+ * this: deep-link shareability, back-button state, and the sidebar's
+ * most-specific-active highlight (`useSidebarBehavior` reads `useLocation`).
+ *
+ * ORDERING (why the transaction): the URL→state reconstruction hooks
+ * (`useRouterSync`, `useViewRouterSync`, `useEnginePageRouterSync`,
+ * `useSettingsHubOverlaySync`) observe `location` changes and rebuild zone state
+ * from the URL — UNLESS the target zone already owns the URL, OR a navigation
+ * transaction is active. A controller-driven navigation emits the zone-state
+ * entry (event bus → `setState`) and THEN changes the URL; if the URL change is
+ * observed before that state has committed, those hooks would re-derive stale
+ * content (the race the old code papered over). We therefore open (or extend) a
+ * navigation transaction so they skip during the commit window and re-validate
+ * via their transaction-aware retry once state has committed — by then the
+ * emitted entry owns the URL, so they no-op. This mirrors
+ * `navigatePathWithFreshStart` / `emitFreshStartNavigationCleanup`, which already
+ * pair `beginTransaction` with a synchronous `routerNavigate`.
+ *
+ * NOT PAINT-GATED (why not requestAnimationFrame): rAF callbacks are throttled to
+ * ~0fps in occluded / backgrounded / throttled tabs, so a deferred
+ * `routerNavigate` could be stranded indefinitely — zone content (event bus →
+ * state) swaps instantly while the URL, sidebar highlight, and back-button state
+ * lag until the tab is refocused (reproduced live: composite-view content visible
+ * while `location.pathname` stayed stale for 8+ seconds, converging only on tab
+ * activation). The transaction guard fills the ordering role rAF was standing in
+ * for, without the paint dependency.
+ */
+/**
+ * Only a resource operation DECLARED `ADDRESSABLE` owns a browser URL.
+ *
+ * The URL builders are surface-blind — `resolveResourceUrl` happily produces a
+ * pattern URL for any URL-bearing variant, including EMBEDDED (notAddressable)
+ * ones — but `AppRouter` registers routes for ADDRESSABLE operations only, so
+ * writing such a URL to the browser strands refresh / deep-link on the router
+ * 404 (seen live 2026-08-19: a breadcrumb click on the EMBEDDED organizations
+ * READ rewrote the URL to `/organizations/:id`, a route that does not exist).
+ * EMBEDDED content navigates as pure zone/overlay content instead.
+ *
+ * An `undefined` surface (synthetic/legacy operation objects that never passed
+ * through the registry's Step-2.5 posture resolution) keeps the historical
+ * URL-writing behavior — only an EXPLICIT non-addressable declaration opts out.
+ */
+export declare function resourceOperationOwnsBrowserUrl(operation: {
+    operationFrontendConfig?: {
+        surface?: ResourceOperationFrontendSurface;
+    };
+} | undefined): boolean;
+export declare function updateBrowserUrl(routerNavigate: ReturnType<typeof useNavigate>, urlPath: string, replace?: boolean): void;
+//# sourceMappingURL=navigation-controller-internals.d.ts.map

package/dist/esm/core/navigation/navigation-controller-internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-controller-internals.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation-controller-internals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AAOzE,eAAO,MAAM,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAoD,CAAC;AAGpI;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE;IAAE,uBAAuB,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,gCAAgC,CAAA;KAAE,CAAA;CAAE,GAAG,SAAS,GAClG,OAAO,CAIT;AAED,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,EAC9C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,OAAe,GACvB,IAAI,CAUN"}

package/dist/esm/core/navigation/navigation-controller-internals.js

@@ -0,0 +1,84 @@
+/**
+ * The two things every layer of the navigation controller needs, and neither of which belongs to any
+ * one of them: the debug channel, and the one function that writes the browser URL.
+ *
+ * Extracted 2026-09-25 when `useNavigationController.ts` was split — 2,322 lines holding click
+ * resolution, URL reconciliation, the ancestor cascade, clean breaks, dismiss and the emit bridge in
+ * one module. Measured across the seam, the ROUTER-SYNC half used exactly THREE symbols from the
+ * controller half (`logDebug` and the two cascade functions), which is what made the split cheap
+ * enough to be worth doing at all.
+ *
+ * ## The debug type name is DELIBERATELY still `useNavigationController`
+ *
+ * `logger.debugByType` keys on this string, and it is what an operator or a test types to turn the
+ * channel on (`setDebugTypeLogging('useNavigationController', true)`). Giving each split module its
+ * own name would be finer-grained and would silently stop every existing toggle from reaching the
+ * router-sync logs — a split is not the moment to change what a diagnostic switch covers.
+ */
+import { ResourceOperationFrontendSurface } from '@wildo-ai/saas-models';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { NavigationUtils } from './navigation.utils.js';
+const logger = LoggerFrontendService.getLogger();
+export const logDebug = logger.debugByType('useNavigationController');
+logger.setDebugTypeLogging('useNavigationController', false);
+/**
+ * Update the browser URL via React Router's navigate function, so React Router's
+ * `useLocation` hook updates. Everything derived from `useLocation` depends on
+ * this: deep-link shareability, back-button state, and the sidebar's
+ * most-specific-active highlight (`useSidebarBehavior` reads `useLocation`).
+ *
+ * ORDERING (why the transaction): the URL→state reconstruction hooks
+ * (`useRouterSync`, `useViewRouterSync`, `useEnginePageRouterSync`,
+ * `useSettingsHubOverlaySync`) observe `location` changes and rebuild zone state
+ * from the URL — UNLESS the target zone already owns the URL, OR a navigation
+ * transaction is active. A controller-driven navigation emits the zone-state
+ * entry (event bus → `setState`) and THEN changes the URL; if the URL change is
+ * observed before that state has committed, those hooks would re-derive stale
+ * content (the race the old code papered over). We therefore open (or extend) a
+ * navigation transaction so they skip during the commit window and re-validate
+ * via their transaction-aware retry once state has committed — by then the
+ * emitted entry owns the URL, so they no-op. This mirrors
+ * `navigatePathWithFreshStart` / `emitFreshStartNavigationCleanup`, which already
+ * pair `beginTransaction` with a synchronous `routerNavigate`.
+ *
+ * NOT PAINT-GATED (why not requestAnimationFrame): rAF callbacks are throttled to
+ * ~0fps in occluded / backgrounded / throttled tabs, so a deferred
+ * `routerNavigate` could be stranded indefinitely — zone content (event bus →
+ * state) swaps instantly while the URL, sidebar highlight, and back-button state
+ * lag until the tab is refocused (reproduced live: composite-view content visible
+ * while `location.pathname` stayed stale for 8+ seconds, converging only on tab
+ * activation). The transaction guard fills the ordering role rAF was standing in
+ * for, without the paint dependency.
+ */
+/**
+ * Only a resource operation DECLARED `ADDRESSABLE` owns a browser URL.
+ *
+ * The URL builders are surface-blind — `resolveResourceUrl` happily produces a
+ * pattern URL for any URL-bearing variant, including EMBEDDED (notAddressable)
+ * ones — but `AppRouter` registers routes for ADDRESSABLE operations only, so
+ * writing such a URL to the browser strands refresh / deep-link on the router
+ * 404 (seen live 2026-08-19: a breadcrumb click on the EMBEDDED organizations
+ * READ rewrote the URL to `/organizations/:id`, a route that does not exist).
+ * EMBEDDED content navigates as pure zone/overlay content instead.
+ *
+ * An `undefined` surface (synthetic/legacy operation objects that never passed
+ * through the registry's Step-2.5 posture resolution) keeps the historical
+ * URL-writing behavior — only an EXPLICIT non-addressable declaration opts out.
+ */
+export function resourceOperationOwnsBrowserUrl(operation) {
+    const surface = operation?.operationFrontendConfig?.surface;
+    return surface !== ResourceOperationFrontendSurface.EMBEDDED
+        && surface !== ResourceOperationFrontendSurface.API_ONLY;
+}
+export function updateBrowserUrl(routerNavigate, urlPath, replace = false) {
+    // Preserve an in-flight transaction's source label (e.g. 'app_level_navigation'
+    // opened by the APP_LEVEL clean break in navigate()) — only open a fresh window
+    // when none is active (zone-level drill, goBack, non-app-level cascade). The
+    // transaction auto-commits on setTimeout(0), after React has committed the
+    // preceding zone-state emit.
+    if (!NavigationUtils.isInTransaction()) {
+        NavigationUtils.beginTransaction('controller_url_update');
+    }
+    routerNavigate(urlPath, { replace });
+}
+//# sourceMappingURL=navigation-controller-internals.js.map

package/dist/esm/core/navigation/navigation-controller-internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-controller-internals.js","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation-controller-internals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAC;AACpG,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,EAAE,CAAC;AAEjD,MAAM,CAAC,MAAM,QAAQ,GAAiE,MAAM,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC;AACpI,MAAM,CAAC,mBAAmB,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,+BAA+B,CAC7C,SAAmG;IAEnG,MAAM,OAAO,GAAG,SAAS,EAAE,uBAAuB,EAAE,OAAO,CAAC;IAC5D,OAAO,OAAO,KAAK,gCAAgC,CAAC,QAAQ;WACvD,OAAO,KAAK,gCAAgC,CAAC,QAAQ,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,cAA8C,EAC9C,OAAe,EACf,UAAmB,KAAK;IAExB,gFAAgF;IAChF,gFAAgF;IAChF,6EAA6E;IAC7E,2EAA2E;IAC3E,6BAA6B;IAC7B,IAAI,CAAC,eAAe,CAAC,eAAe,EAAE,EAAE,CAAC;QACvC,eAAe,CAAC,gBAAgB,CAAC,uBAAuB,CAAC,CAAC;IAC5D,CAAC;IACD,cAAc,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACvC,CAAC","sourcesContent":["/**\n * The two things every layer of the navigation controller needs, and neither of which belongs to any\n * one of them: the debug channel, and the one function that writes the browser URL.\n *\n * Extracted 2026-09-25 when `useNavigationController.ts` was split — 2,322 lines holding click\n * resolution, URL reconciliation, the ancestor cascade, clean breaks, dismiss and the emit bridge in\n * one module. Measured across the seam, the ROUTER-SYNC half used exactly THREE symbols from the\n * controller half (`logDebug` and the two cascade functions), which is what made the split cheap\n * enough to be worth doing at all.\n *\n * ## The debug type name is DELIBERATELY still `useNavigationController`\n *\n * `logger.debugByType` keys on this string, and it is what an operator or a test types to turn the\n * channel on (`setDebugTypeLogging('useNavigationController', true)`). Giving each split module its\n * own name would be finer-grained and would silently stop every existing toggle from reaching the\n * router-sync logs — a split is not the moment to change what a diagnostic switch covers.\n */\n\nimport type { useNavigate } from 'react-router-dom';\n\nimport { ResourceOperationFrontendSurface } from '@wildo-ai/saas-models';\n\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\nimport { NavigationUtils } from './navigation.utils';\n\nconst logger = LoggerFrontendService.getLogger();\n\nexport const logDebug: (message: string, context?: Record<string, unknown>) => void = logger.debugByType('useNavigationController');\nlogger.setDebugTypeLogging('useNavigationController', false);\n\n/**\n * Update the browser URL via React Router's navigate function, so React Router's\n * `useLocation` hook updates. Everything derived from `useLocation` depends on\n * this: deep-link shareability, back-button state, and the sidebar's\n * most-specific-active highlight (`useSidebarBehavior` reads `useLocation`).\n *\n * ORDERING (why the transaction): the URL→state reconstruction hooks\n * (`useRouterSync`, `useViewRouterSync`, `useEnginePageRouterSync`,\n * `useSettingsHubOverlaySync`) observe `location` changes and rebuild zone state\n * from the URL — UNLESS the target zone already owns the URL, OR a navigation\n * transaction is active. A controller-driven navigation emits the zone-state\n * entry (event bus → `setState`) and THEN changes the URL; if the URL change is\n * observed before that state has committed, those hooks would re-derive stale\n * content (the race the old code papered over). We therefore open (or extend) a\n * navigation transaction so they skip during the commit window and re-validate\n * via their transaction-aware retry once state has committed — by then the\n * emitted entry owns the URL, so they no-op. This mirrors\n * `navigatePathWithFreshStart` / `emitFreshStartNavigationCleanup`, which already\n * pair `beginTransaction` with a synchronous `routerNavigate`.\n *\n * NOT PAINT-GATED (why not requestAnimationFrame): rAF callbacks are throttled to\n * ~0fps in occluded / backgrounded / throttled tabs, so a deferred\n * `routerNavigate` could be stranded indefinitely — zone content (event bus →\n * state) swaps instantly while the URL, sidebar highlight, and back-button state\n * lag until the tab is refocused (reproduced live: composite-view content visible\n * while `location.pathname` stayed stale for 8+ seconds, converging only on tab\n * activation). The transaction guard fills the ordering role rAF was standing in\n * for, without the paint dependency.\n */\n/**\n * Only a resource operation DECLARED `ADDRESSABLE` owns a browser URL.\n *\n * The URL builders are surface-blind — `resolveResourceUrl` happily produces a\n * pattern URL for any URL-bearing variant, including EMBEDDED (notAddressable)\n * ones — but `AppRouter` registers routes for ADDRESSABLE operations only, so\n * writing such a URL to the browser strands refresh / deep-link on the router\n * 404 (seen live 2026-08-19: a breadcrumb click on the EMBEDDED organizations\n * READ rewrote the URL to `/organizations/:id`, a route that does not exist).\n * EMBEDDED content navigates as pure zone/overlay content instead.\n *\n * An `undefined` surface (synthetic/legacy operation objects that never passed\n * through the registry's Step-2.5 posture resolution) keeps the historical\n * URL-writing behavior — only an EXPLICIT non-addressable declaration opts out.\n */\nexport function resourceOperationOwnsBrowserUrl(\n  operation: { operationFrontendConfig?: { surface?: ResourceOperationFrontendSurface } } | undefined,\n): boolean {\n  const surface = operation?.operationFrontendConfig?.surface;\n  return surface !== ResourceOperationFrontendSurface.EMBEDDED\n    && surface !== ResourceOperationFrontendSurface.API_ONLY;\n}\n\nexport function updateBrowserUrl(\n  routerNavigate: ReturnType<typeof useNavigate>,\n  urlPath: string,\n  replace: boolean = false\n): void {\n  // Preserve an in-flight transaction's source label (e.g. 'app_level_navigation'\n  // opened by the APP_LEVEL clean break in navigate()) — only open a fresh window\n  // when none is active (zone-level drill, goBack, non-app-level cascade). The\n  // transaction auto-commits on setTimeout(0), after React has committed the\n  // preceding zone-state emit.\n  if (!NavigationUtils.isInTransaction()) {\n    NavigationUtils.beginTransaction('controller_url_update');\n  }\n  routerNavigate(urlPath, { replace });\n}\n\n"]}

package/dist/esm/core/navigation/navigation-policy-resolver.service.d.ts

@@ -19,9 +19,49 @@
  *
  * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md
  */
-import { type NavigationLayout, type ViewportDiscriminated } from '@wildo-ai/saas-models';
+import { ResponsiveCollapseMode, type NavigationLayout, type ZoneConfig, type ViewportDiscriminated } from '@wildo-ai/saas-models';
 import { ViewportBreakpoint } from '@wildo-ai/zod-decorators';
 import { type NavigationResolutionContext, type NavigationResolutionResult } from './navigation.schemas';
+/**
+ * WHICH collapse a structural zone is under at this viewport, or `undefined` for none.
+ *
+ * Exported rather than private to the resolver because THREE parties need the answer and none may
+ * re-derive it: the resolver places a CLICK's content, `useResponsiveZoneMigration` moves content
+ * ALREADY sitting in a zone the viewport has just taken away, and a test pins both. The predicate
+ * half (`zoneIsCollapsedAtViewport`) was extracted for exactly this reason on 2026-09-25; this is
+ * the mode half, and leaving it private would let the migration disagree with the placement about
+ * whether a collapsed pane becomes a page or a sheet — the two halves of one declaration, answered
+ * by two functions.
+ *
+ * Callers own the zone-identity guard, because it is a question about WHICH zone rather than about
+ * the viewport.
+ *
+ * ## An UNDECLARED collapse defaults to PUSH, and that is a decision
+ *
+ * `NavigationContentAreas` renders a single zone below the mobile breakpoint — secondary and
+ * companion are not shown at all. So on a phone a zone with no `responsiveCollapse` is not "left
+ * alone": content routed there is placed into a zone that does not render, and the user sees
+ * nothing happen. That is what an undeclared collapse meant before #411, for every application, and
+ * it is not a behaviour anyone would choose deliberately.
+ *
+ * PUSH rather than OVERLAY because it is the conservative half of the vocabulary: the content
+ * appears in primary in context, and BACK pops to what was there before — no dismissal affordance
+ * to get wrong, and no modality over a phone-sized viewport. An application that wants the sheet
+ * declares `OVERLAY` and gets it.
+ *
+ * The alternative — return `undefined` and let the content vanish — was rejected because it is the
+ * silent degradation #411 exists to remove, and because "the zone declared nothing" is not a reason
+ * to lose a user's navigation.
+ *
+ * A viewport-discriminated declaration naming no mode for THIS breakpoint is a gap in the
+ * declaration, not a statement that the zone renders — it still would not — so it takes the same
+ * default.
+ */
+export declare function resolveZoneCollapseMode(params: {
+    zoneConfig: ZoneConfig | undefined;
+    viewport: ViewportBreakpoint | undefined;
+    contentAreaWidth?: number;
+}): ResponsiveCollapseMode | undefined;
 /**
  * Resolve a `ViewportDiscriminated<T>` value for the current viewport.
  *
@@ -41,6 +81,18 @@ export declare class NavigationPolicyResolver {
      * @returns What the controller should do: target zone, transition, appearance, collapse state.
      */
     resolve(context: NavigationResolutionContext, layout: NavigationLayout): NavigationResolutionResult;
+    /**
+     * The overlay an `INPLACE` transition becomes when the surface has no element-level host.
+     *
+     * A DOOR on the resolver rather than a re-resolution in the controller, because the controller's
+     * way of asking — injecting a synthetic `operationOverrides: [{ transition: OVERLAY }]` — had to
+     * lie twice to get an answer: it reported the outcome as an authored override, and it discarded
+     * the operation's REAL override along with the `appearance` and `overlayBehavior` on it. Here the
+     * context is untouched, so both are read exactly as they would be for any other overlay.
+     *
+     * The tier that answered `INPLACE` is preserved. What the degradation adds is an adjustment.
+     */
+    degradeInPlaceToOverlay(context: NavigationResolutionContext, layout: NavigationLayout, original: NavigationResolutionResult): NavigationResolutionResult;
     private resolveTransition;
     /**
      * Step 1: Check per-resource operation overrides.
@@ -65,7 +117,29 @@ export declare class NavigationPolicyResolver {
     private getTransitionBySemanticKey;
     /**
      * Step 4: Get the transition map from the appropriate source config.
-     * Three distinct branches based on source type.
+     *
+     * ## An OVERLAY source falls back to the zone it is LANDING IN
+     *
+     * `fromOverlay` is the app's statement about leaving an overlay, and it wins. What it does NOT
+     * mean is that an app which declared nothing there has declared nothing at all: an overlay is not
+     * a structural zone, so `getStructuralSourceZone` already answers PRIMARY for it — a structural
+     * navigation out of an overlay IS a primary navigation. Reading a different map for the VERB than
+     * for the ZONE is how the two came to disagree.
+     *
+     * Measured on the workbench, 2026-09-25. Its layout declares `zones.primary.transitions.read =
+     * SPLIT` and no `fromOverlay` at all. Clicking an aspect popup's `family` backlink — an
+     * ADDRESSABLE artifact — found no overlay map, fell through to the framework fallback `PUSH`, and
+     * landed in PRIMARY: the artifact took the WHOLE PAGE, replacing the artifact list it should have
+     * opened beside. The application had said what a READ does on the page; the resolver did not ask.
+     *
+     * Wonder CRM is the control and is untouched: it declares `fromOverlay.read = PUSH` deliberately
+     * ("ADDRESSABLE targets legitimately leave the overlay and become the page"), that map answers,
+     * and the fallback never runs. The fallback also covers the gap INSIDE a declared map — one that
+     * names READ says nothing about LIST, and that gap used to take the framework default too.
+     *
+     * APP_LEVEL is deliberately NOT given the same fallback. A menubar click is a layout RESET with
+     * its own meaning, and an app that declares no `appLevel` map has not thereby asked for primary's
+     * drill-in verbs — it has asked for the framework default, which is what it gets.
      */
     private getSourceTransitions;
     /**
@@ -91,6 +165,16 @@ export declare class NavigationPolicyResolver {
      * Falls back to overlay if no adjacent zone is declared in config.
      */
     private resolveSplitTarget;
+    /**
+     * Did a split into `zone` OPEN a pane or REPLACE what was in one?
+     *
+     * The same question `resolveSplitTarget`'s secondary branch answers inline by construction — it
+     * only reaches companion when secondary is taken — but the two branches that target companion
+     * DIRECTLY (a persistent split, and a layout declaring companion without secondary) choose the
+     * zone before asking, so they ask here. Reading `zoneOccupancy` is what keeps both answers derived
+     * from one input rather than from two nearly-identical inline conditions.
+     */
+    private splitOutcomeFor;
     /**
      * Derive visual appearance from zone config, resolved for the current viewport.
      * Only overlay and split transitions have meaningful appearance.

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

@@ -1 +1 @@
-{"version":3,"file":"navigation-policy-resolver.service.d.ts","sourceRoot":"","sources":["../../../../src/core/navigation/navigation-policy-resolver.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAQL,KAAK,gBAAgB,EAKrB,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAChC,MAAM,sBAAsB,CAAC;AAiB9B;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,SAAS,EAC3C,QAAQ,EAAE,kBAAkB,GAC3B,CAAC,GAAG,SAAS,CAUf;AAiDD,qBAAa,wBAAwB;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,2BAA2B,EAAE,MAAM,EAAE,gBAAgB,GAAG,0BAA0B;IAqInG,OAAO,CAAC,iBAAiB;IA6EzB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAY7B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAgBlC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAO/B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAY9B,6DAA6D;IAC7D,OAAO,CAAC,mBAAmB;IAkB3B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;CAiD5B;AAED,sDAAsD;AACtD,eAAO,MAAM,wBAAwB,0BAAiC,CAAC"}
+{"version":3,"file":"navigation-policy-resolver.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/navigation-policy-resolver.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAIL,sBAAsB,EAMtB,KAAK,gBAAgB,EAIrB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAKL,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAChC,MAAM,sBAAsB,CAAC;AAkB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,sBAAsB,GAAG,SAAS,CAKrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,SAAS,EAC3C,QAAQ,EAAE,kBAAkB,GAC3B,CAAC,GAAG,SAAS,CAUf;AAsDD,qBAAa,wBAAwB;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,2BAA2B,EAAE,MAAM,EAAE,gBAAgB,GAAG,0BAA0B;IA0NnG;;;;;;;;;;OAUG;IACH,uBAAuB,CACrB,OAAO,EAAE,2BAA2B,EACpC,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,0BAA0B,GACnC,0BAA0B;IAoB7B,OAAO,CAAC,iBAAiB;IA0FzB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAY7B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAgBlC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAO/B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAmC1B;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAavB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAiCxB;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAY9B,6DAA6D;IAC7D,OAAO,CAAC,mBAAmB;IA6B3B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;CAoB5B;AAED,sDAAsD;AACtD,eAAO,MAAM,wBAAwB,0BAAiC,CAAC"}