@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/config/frontend/navigation.shared.schemas.js

@@ -39,7 +39,8 @@ import { CoreResourceOperation } from '../../resources/resources.shared.core.def
  *
  * `push` behavior depends on the zone's `contentModel`:
  * - In `single` zones: stack-based (new content on top, back pops)
- * - In `tabbed` zones: opens a new tab (or activates existing for same resource)
+ * - In `tabbed` zones: opens a new tab and makes it active (an already-open record is NOT
+ *   de-duplicated — it opens again)
  *
  * @wildo_source:part:start saas.models.navigation.transition-vocabulary facet:layer:shared facet:family:navigation-config
  */
@@ -61,14 +62,17 @@ export var NavigationTransition;
      * Content opens in an adjacent zone (secondary or companion).
      * Creates a side-by-side layout. The source zone's content remains visible.
      * Back navigation un-splits (closes the adjacent zone).
-     * URL adds a split segment.
+     * URL: the detail's own address beside a resource primary; beside any other primary the host
+     * keeps its URL and a RESOURCE detail rides as `?pane=`. There is no split segment.
      */
     NavigationTransition["SPLIT"] = "split";
     /**
      * Content opens in a floating layer above the entire layout (dialog, sheet, or drawer).
-     * The underlying layout remains visible but non-interactive.
+     * The underlying layout remains visible; it is non-interactive while the overlay is modal (the
+     * default), and stays interactive under `overlayBehavior.modal: false`.
      * Back navigation or Escape dismisses the overlay.
-     * URL adds an overlay param/hash.
+     * NOT URL-addressed: opening an overlay leaves the browser URL where it was, so its content cannot
+     * be linked to or restored by a reload. Choose it knowing that.
      */
     NavigationTransition["OVERLAY"] = "overlay";
     /**
@@ -109,7 +113,8 @@ export var NavigationTransition;
     NavigationTransition["INPLACE"] = "inplace";
     /**
      * Escape the current context and open content at primary scope.
-     * Abandons the current context: overlays close, companion/secondary dismiss.
+     * Abandons the current context: overlays close, companion/secondary dismiss — except a pane
+     * placed by a `persistent` split, which survives a reset by design.
      * The promoted content becomes the primary zone's top content.
      *
      * Use case: a link within an overlay should open as a full primary view,
@@ -158,8 +163,9 @@ export var NavigationZoneName;
     NavigationZoneName["SECONDARY"] = "secondary";
     /**
      * Persistent supplementary content. Reference panels, docs, notes, threads.
-     * Only exists if declared in config. Usually hidden by default (`defaultVisible: false`).
-     * Activated by `split` with `persistent: true` or explicit user toggle.
+     * Only exists if declared in config, and starts hidden.
+     * Reached by a `split` with `persistent: true`, or by an ordinary `split` when the secondary zone
+     * is already occupied.
      * Typical use: Slack thread panel, VS Code terminal, documentation sidebar.
      */
     NavigationZoneName["COMPANION"] = "companion";
@@ -181,9 +187,10 @@ export var NavigationZoneContentModel;
      */
     NavigationZoneContentModel["SINGLE"] = "single";
     /**
-     * Parallel tabs: `push` creates a new tab (or activates existing for the same resource).
-     * Tab bar is visible, showing all open tabs. No depth stack within tabs.
-     * `replace` replaces the active tab's content. Close is an explicit action (not back).
+     * Parallel tabs: every navigation landing in the zone opens a new tab and makes it active (no
+     * de-duplication). Tab bar is visible, showing all open tabs. No depth stack within tabs.
+     * `replace` replaces the active tab's content, and back closes the active tab and shows its
+     * neighbour. The model changes RENDERING only — it does not change how navigation resolves.
      * When no tabs remain, `onEmpty` behavior applies.
      */
     NavigationZoneContentModel["TABBED"] = "tabbed";
@@ -192,8 +199,10 @@ export var NavigationZoneContentModel;
  * Responsive collapse behavior when viewport shrinks below a zone's breakpoint.
  *
  * Only applies to secondary and companion zones. Primary never collapses.
- * When viewport grows back past the breakpoint, collapsed content migrates
- * back to its original zone (content is preserved).
+ * It applies to content ALREADY in the zone, not only to new navigations: when the zone collapses its
+ * whole history moves (a tabbed zone's tabs too, the one on screen on top), and when the viewport
+ * grows back what is still on top of primary migrates home with every field intact. Whatever the
+ * reader navigated past at the narrow width stays where it is.
  */
 export var ResponsiveCollapseMode;
 (function (ResponsiveCollapseMode) {
@@ -261,25 +270,6 @@ export var OverlayAppearance;
      */
     OverlayAppearance["DRAWER"] = "drawer";
 })(OverlayAppearance || (OverlayAppearance = {}));
-/**
- * Visual presentation for split transitions.
- * Determines how adjacent zone content renders alongside the source zone.
- */
-export var SplitAppearance;
-(function (SplitAppearance) {
-    /**
-     * Standard vertical side panel.
-     * Content appears beside the source zone with a resizable divider.
-     * Most common for list-detail patterns.
-     */
-    SplitAppearance["PANEL"] = "panel";
-    /**
-     * Horizontal drawer (bottom panel).
-     * Content appears below the source zone.
-     * Used for companion panels like terminals, output logs, reference docs.
-     */
-    SplitAppearance["DRAWER"] = "drawer";
-})(SplitAppearance || (SplitAppearance = {}));
 /**
  * Zod schema factory for `ViewportDiscriminated<T>`.
  *
@@ -390,43 +380,34 @@ export const ZoneTransitionsSchema = z.partialRecord(z.enum(CoreResourceOperatio
 /**
  * Transition → visual appearance for a zone. Values are viewport-discriminated.
  *
- * Only `split` and `overlay` transitions have meaningful appearance choices.
- * `push`, `replace`, `inplace`, and `promote` have no appearance to configure:
+ * Only the `overlay` transition has an appearance choice. The others have none to configure:
  * - `push`/`replace` fill the zone
+ * - `split` opens a pane whose shape is `split.orientation` (there is no split appearance)
  * - `inplace` transforms an element within the current view
  * - `promote` fills primary (same as push/replace)
  *
  * @example
  * appearance: {
- *   split:   SplitAppearance.PANEL,                                                       // always side panel
  *   overlay: { [ViewportBreakpoint.VERT_TABLET]: OverlayAppearance.SHEET, [ViewportBreakpoint.MOBILE]: OverlayAppearance.DRAWER },   // sheet on tablet, drawer on mobile
  * }
  */
 export const ZoneAppearanceSchema = z.object({
-    /** How split content renders. Default: `SplitAppearance.PANEL` (vertical side panel). */
-    split: viewportDiscriminatedSchema(z.enum(SplitAppearance)).optional(),
-    /** How overlay content renders. Default: `OverlayAppearance.DIALOG` (centered modal). */
+    /**
+     * How overlay content renders. Default: `OverlayAppearance.DIALOG` (centered modal).
+     *
+     * There is deliberately no `split` sibling: how a PANE renders is `SplitConfig.orientation` plus
+     * the zone's width bounds, which the renderer reads. See the note where `SplitAppearance` used to
+     * be declared.
+     */
     overlay: viewportDiscriminatedSchema(z.enum(OverlayAppearance)).optional(),
 });
 /**
  * @wildo_source:part:start saas.models.navigation.zone-declaration facet:layer:shared facet:family:navigation-config
  *
- * How much of its zone a DESTINATION's content occupies.
- *
- * The primary zone caps and centres its content at `var(--content-max-width, 80rem)` and gives it no
- * definite-height ancestor. That is correct for almost everything a zone hosts — a form, a list, a
- * settings page stretched across a 2560px monitor is unreadable — and wrong for content whose whole
- * value is the space it occupies. Until this enum existed there was no way to tell the two apart, so
- * a canvas had to hand-roll a viewport fraction (`h-[70vh]`), which sizes against the WINDOW rather
- * than the container and therefore ignores whatever chrome sits above it.
- *
- * Declared per DESTINATION rather than per zone: the same primary zone hosts a list that wants the
- * cap, a detail page that caps itself, and a graph that wants neither.
- *
- * Width and height are separable on purpose. A wide data table wants the cap gone and its natural
- * height; collapsing both into one boolean would merge two meanings, and two independent booleans
- * would make "full height, still capped at 80rem" representable — a combination nothing wants and
- * someone would eventually author by accident.
+ * How much of its zone a destination's content occupies is NOT declared here: it is the
+ * destination's `ZoneContentGeometry` (a `maxWidth` and a `fillsHeight`), because the same primary
+ * zone hosts a list that wants the width cap, a detail that caps itself, and a graph that wants
+ * neither. A zone's own declaration follows.
  */
 /**
  * Full zone configuration.
@@ -435,10 +416,25 @@ export const ZoneAppearanceSchema = z.object({
  * which transition fires for each operation, how content appears,
  * and how the zone responds to viewport changes.
  *
- * Note: `minWidth`, `maxWidth`, `defaultVisible`, `onEmpty`,
- * and `responsiveCollapse` are only meaningful for secondary and companion zones.
- * Primary never collapses, never empties, and takes remaining space.
+ * Note: `minWidth`, `maxWidth`, `onEmpty` and `responsiveCollapse` are only meaningful for
+ * secondary and companion zones. Primary never collapses, never empties, and takes remaining space.
  * Setting these on primary has no effect.
+ *
+ * ## Every field here is READ by the runtime, and that was checked rather than assumed (#211)
+ *
+ * | field | the reader |
+ * |---|---|
+ * | `contentModel` | `NavigationContentAreas.tsx` (TABBED detection) + `zone-visible-entry.ts` |
+ * | `transitions` | `navigation-policy-resolver.service.ts` |
+ * | `appearance` | the policy resolver (`appearance.overlay` — there is no split appearance) |
+ * | `minWidth` / `maxWidth` | `NavigationContentAreas.tsx` drag constraints, both split branches |
+ * | `onEmpty` | `zone-empty-behavior.ts` |
+ * | `responsiveCollapse` | `navigation-policy-resolver.service.ts` |
+ *
+ * `defaultVisible` was REMOVED by that audit: nothing read it, and its only documented meaning was
+ * "defaults to `true` when `split.autoSplit` is `true`" — a field defined in terms of another field
+ * that was also dead. What it was reaching for is `onEmpty`, which every current layout already uses
+ * (`zoneOccupiesSpaceWhenEmpty`) and which the runtime genuinely reads.
  */
 export const ZoneConfigSchema = z.object({
     /**
@@ -450,41 +446,64 @@ export const ZoneConfigSchema = z.object({
     contentModel: z.enum(NavigationZoneContentModel).default(NavigationZoneContentModel.SINGLE),
     /** Operation → transition mapping. Defines what happens for each user action in this zone. */
     transitions: ZoneTransitionsSchema,
-    /** Transition → visual appearance. Only split and overlay have appearance choices. */
+    /** Which shape an OVERLAY opened from this zone takes. Only overlays have an appearance: a pane's shape is `split.orientation`. */
     appearance: ZoneAppearanceSchema.optional(),
     /**
      * Minimum pixel width when resizing. Constrains how far this side of the
-     * split divider can be dragged. Only meaningful for secondary and companion zones.
-     * Works in conjunction with `SplitConfigSchema.resizable`.
+     * split divider can be dragged. Only meaningful for secondary and companion zones, and only when
+     * that zone is resizable — `SplitConfigSchema.resizable` for secondary, `split.companion.resizable`
+     * for companion (independent flags).
+     *
+     * The pixel value is converted to a share of the content area and clamped to 5–70%. When OMITTED on
+     * a resizable zone the floor is 25% of the content area — or the zone's own ratio share, if that is
+     * smaller — never zero. A pane is never collapsed by dragging it: closing a pane is navigation.
+     *
+     * A declared `maxWidth` narrower than this floor lowers the floor to it. When the shown side panes ask
+     * for more than primary's 25% leaves, they shrink in proportion and none opens below its floor (a
+     * non-resizable pane's floor is 25%, or its own ratio share if smaller); primary opens at exactly 25%.
+     * The floors are pixels, so at a narrow window they may not fit together at all — they then give way
+     * to each other in proportion, and the smaller floor a pane opens at is its drag floor. Primary never
+     * gives way.
+     *
+     * ## It is ALSO a COLLAPSE TRIGGER, on every zone — not only a drag bound
+     *
+     * The paragraph above restricts this to resizing, and that stopped being the whole truth when the
+     * content-area fit escalation landed: `resolveCollapseMode` feeds `minWidth` to
+     * `contentAreaFitsSplit`, for resizable and non-resizable zones alike. A zone declaring
+     * `minWidth: W` needs `W / 0.75` of content width beside primary's 25% floor, and below that the
+     * split escalates rather than squeezing both panes under their floors.
+     *
+     * So a NON-resizable pane with `minWidth: 600` stops splitting on a 1000px content area at full
+     * desktop width — correct behaviour, and the opposite of what this field's own contract said until
+     * 2026-09-25. Declare it when you mean "this pane is not worth opening narrower than W", and omit
+     * it when you only want a drag floor on a layout that is not resizable anyway.
      */
     minWidth: z.number().positive().optional(),
     /**
      * Maximum pixel width when resizing. Constrains how far this side of the
-     * split divider can be dragged. Only meaningful for secondary and companion zones.
-     * Works in conjunction with `SplitConfigSchema.resizable`.
+     * split divider can be dragged. Only meaningful for secondary and companion zones, and only when
+     * that zone is resizable — `SplitConfigSchema.resizable` for secondary, `split.companion.resizable`
+     * for companion (independent flags).
+     *
+     * The pixel value is converted to a share of the content area and clamped to 5–70%. When OMITTED on
+     * a resizable zone the ceiling is whatever leaves the primary zone 25% of the content area.
      */
     maxWidth: z.number().positive().optional(),
     /**
-     * Whether this zone is visible on first render (before any transition targets it).
-     * - Primary: always visible (this field is ignored).
-     * - Secondary: defaults to `true` when `split.autoSplit` is `true`, `false` otherwise.
-     * - Companion: defaults to `false` (hidden until a `split` transition targets it or user toggles).
-     */
-    defaultVisible: z.boolean().optional(),
-    /**
-     * What happens when this zone's last content is dismissed (stack empty, last tab closed).
-     * - `ZoneEmptyBehavior.COLLAPSE` (default): zone hides, adjacent zones expand to fill.
-     * - `ZoneEmptyBehavior.EMPTY_STATE`: zone stays visible with placeholder ("Select an item to view details").
-     * Only meaningful for secondary and companion zones. Primary never empties.
-     */
+   * What happens when this zone's last content is dismissed (stack empty, last tab closed).
+   * - `ZoneEmptyBehavior.COLLAPSE` (default): zone hides, adjacent zones expand to fill.
+   * - `ZoneEmptyBehavior.EMPTY_STATE`: zone stays visible with placeholder ("Select an item to view details").
+   * Only meaningful for secondary and companion zones. Primary never empties.
+   */
     onEmpty: z.enum(ZoneEmptyBehavior).optional(),
     /**
      * Responsive collapse rules: what happens when viewport shrinks below the zone's breakpoint.
      * Accepts a plain `ResponsiveCollapseMode` (all breakpoints) or viewport-discriminated object.
      * Only meaningful for secondary and companion zones. Primary never collapses.
      *
-     * When viewport grows back past the breakpoint, collapsed content migrates back
-     * to its original zone (content is preserved).
+     * It moves content already in the zone as well as new navigations: the zone's whole history
+     * moves when it collapses, and what is still on top of primary goes home when it returns — see
+     * `ResponsiveCollapseMode`.
      *
      * @example
      * responsiveCollapse: ResponsiveCollapseMode.PUSH                                                              // always push into primary
@@ -560,13 +579,6 @@ export const CompanionSplitConfigSchema = z.object({
      * @default [70, 30]
      */
     ratio: z.tuple([z.number(), z.number()]).default([70, 30]),
-    /**
-     * How the companion is positioned relative to the main area.
-     * - `DisplayDirection.VERTICAL`: companion on the side (left/right)
-     * - `DisplayDirection.HORIZONTAL`: companion below (bottom panel, e.g. VS Code terminal)
-     * @default DisplayDirection.VERTICAL
-     */
-    orientation: z.enum(DisplayDirection).default(DisplayDirection.VERTICAL),
     /**
      * Whether the companion split boundary is user-draggable.
      * When `true`, a draggable divider appears between the main area and the companion zone.
@@ -574,7 +586,17 @@ export const CompanionSplitConfigSchema = z.object({
      * @default false
      */
     resizable: z.boolean().default(false),
-});
+}); /*
+ * `orientation` was REMOVED here by the #211 audit, and it is the one removal that took a
+ * capability with it. It claimed the companion could sit BELOW the main area ("bottom panel, e.g.
+ * VS Code terminal") and nothing read it: all three zones share ONE `ResizablePanelGroup` whose
+ * `direction` comes from `split.orientation`, so an author writing HORIZONTAL here got a side panel
+ * and no diagnostic. Honouring it needs a NESTED panel group, with its own sizes, autoSaveId, drag
+ * constraints and responsive-collapse behaviour — a feature, not a field fix. Left as a declared
+ * lie it was worse than absent: it ships to application builders in the compiled
+ * `config-navigation` skill and answers with silence. Build the nested group first; the field comes
+ * back when something reads it.
+ */
 /**
  * Top-level split geometry — describes the physical relationship between zones.
  *
@@ -583,36 +605,47 @@ export const CompanionSplitConfigSchema = z.object({
  *
  * @example
  * split: {
- *   autoSplit: true,                                    // LIST pre-splits when primary.read = NavigationTransition.SPLIT
  *   ratio: [40, 60],                                    // 40% primary, 60% secondary
  *   orientation: DisplayDirection.VERTICAL,              // side-by-side
  *   resizable: true,                                     // divider is draggable
  *   companion: {
  *     ratio: [70, 30],                                   // companion takes 30%
- *     orientation: DisplayDirection.HORIZONTAL,         // bottom panel
- *     resizable: true,
+ *     resizable: true,                                   // its own divider is draggable
  *   },
  * }
  */
 export const SplitConfigSchema = z.object({
-    /**
-     * Whether the primary zone pre-splits on initial load.
-     * When `true` and `primary.transitions.read === NavigationTransition.SPLIT`, the secondary zone
-     * appears immediately with the first list item selected (or empty state).
-     * @default false
-     */
-    autoSplit: z.boolean().default(false),
     /**
      * Primary-to-secondary width/height ratio. Defines the initial proportion.
      * When `resizable` is `true`, user drag overrides this (persisted to localStorage).
      * @example [40, 60] — primary gets 40%, secondary gets 60%
      * @default [50, 50]
      */
+    /*
+     * ONLY `ratio[1]` is read. Primary takes what the side panes leave — `100 − Σ(side defaults)` in
+     * the static branch, the resizable branch's own clamping otherwise — so the first element has no
+     * reader anywhere, and with BOTH a secondary and a companion shown it is not even well defined.
+     *
+     * Kept as a 2-tuple rather than narrowed to one number, deliberately: `[50, 50]` reads as a
+     * proportion, which is what an author is thinking about, and changing the shape would break every
+     * authored layout for a field whose value is already ignored. What changed on 2026-09-25 is that
+     * it says so — `ratio: [40, 30]` silently rendered a 30% pane and a 70% primary, with the authored
+     * 40 discarded and no diagnostic.
+     */
     ratio: z.tuple([z.number(), z.number()]).default([50, 50]),
     /**
-     * Split direction between primary and secondary.
+     * Split direction between primary and secondary — **the ONE axis vocabulary**.
+     *
      * - `DisplayDirection.VERTICAL` (default): side-by-side (most common for list-detail)
-     * - `DisplayDirection.HORIZONTAL`: top-bottom (less common)
+     * - `DisplayDirection.HORIZONTAL`: top-bottom — the shape `SplitAppearance.DRAWER` used to
+     *   describe before that duplicate vocabulary was removed (2026-09-25).
+     *
+     * Read by BOTH render branches since the same change. It was read only by the resizable branch
+     * before, so `HORIZONTAL` on a non-resizable layout silently produced a side panel.
+     *
+     * Note this names the DIVIDER's orientation, not the stacking axis — `VERTICAL` divider, content
+     * side by side. `splitDividerOrientationToPanelGroupDirection` is the one place that inverts it.
+     *
      * @default DisplayDirection.VERTICAL
      */
     orientation: z.enum(DisplayDirection).default(DisplayDirection.VERTICAL),
@@ -661,12 +694,15 @@ export const ViewportOverrideSchema = z.object({
  * behavior. It specifies which zones exist, how each zone handles operations,
  * how zones are sized relative to each other, and global overrides.
  *
- * Resolution order (from highest to lowest priority):
+ * Resolution order (from highest to lowest priority; the first tier that answers wins):
  * 1. Per-operation frontend override (`operation.operationFrontendConfig.navigationOverrides`)
- * 2. Per-relationship override (`display.inParentNavigation.transition`)
- * 3. Global viewport override (`ViewportBreakpoint.MOBILE` / `ViewportBreakpoint.VERT_TABLET` blocks)
- * 4. Source context `transitions[operation]` + `appearance[transition]`
- * 5. Framework hardcoded fallback
+ * 2. Authored action presentation (an operation's explicit presentation)
+ * 3. Per-relationship override (`display.inParentNavigation.transition`)
+ * 4. Global viewport override (`ViewportBreakpoint.MOBILE` / `ViewportBreakpoint.VERT_TABLET` blocks)
+ * 5. Source context `transitions[operation]` — an overlay source with no `fromOverlay` entry falls
+ *    back to primary's map
+ * 6. Derived action presentation (inferred by the framework, used only after authored policy)
+ * 7. Framework hardcoded fallback
  *
  * @example
  * const layout: NavigationLayout = {
@@ -676,7 +712,7 @@ export const ViewportOverrideSchema = z.object({
  *   },
  *   appLevel: { transitions: { list: NavigationTransition.REPLACE, create: NavigationTransition.OVERLAY } },
  *   fromOverlay: { transitions: { read: NavigationTransition.PROMOTE } },
- *   split: { autoSplit: true, ratio: [40, 60] },
+ *   split: { ratio: [40, 60] },
  *   maxDepth: 2,
  * };
  */
@@ -755,11 +791,12 @@ export const NavigationLayoutSchema = z.object({
      */
     appLevel: AppLevelConfigSchema.optional(),
     /**
-     * How navigation within an overlay behaves.
-     * Prevents overlay nesting — typically everything pushes within the overlay stack.
+     * How navigation that STARTS in an overlay resolves. `PUSH` or `REPLACE` from an overlay leaves it
+     * and lands in PRIMARY (the page changes); `OVERLAY` stacks a second overlay on the first. A
+     * missing entry falls back to primary's own map. Nothing here keeps a link inside the dialog.
      */
     fromOverlay: FromOverlayConfigSchema.optional(),
-    /** Split geometry: ratios, orientations, autoSplit. */
+    /** Split geometry: ratios, orientation, resizability. */
     split: SplitConfigSchema.optional(),
     /**
      * Maximum push depth before the framework escalates to overlay.
@@ -787,6 +824,219 @@ export const NavigationLayoutSchema = z.object({
 });
 /** @wildo_source:part:end saas.models.navigation.layout */
 // ════════════════════════════════════════════════════════════════
+// Transition Config Helpers
+// ════════════════════════════════════════════════════════════════
+/**
+ * The transition verb of a {@link TransitionConfig}, which is either the verb itself or an object
+ * carrying it alongside its modifiers.
+ *
+ * Exported from here rather than from the frontend resolver — where all three of these lived until
+ * 2026-09-25 — because they are pure functions of an AUTHORING type this file owns, and the layout
+ * diagnostics below need them too. A second copy beside the diagnostics would have been a second
+ * answer to "what verb did the author write".
+ */
+export function getTransitionVerb(config) {
+    if (typeof config === 'string')
+        return config;
+    return config.transition;
+}
+/** Whether a {@link TransitionConfig} carries the `ephemeral` modifier. */
+export function isEphemeralTransition(config) {
+    if (typeof config === 'string')
+        return false;
+    return config.ephemeral === true;
+}
+/** Whether a {@link TransitionConfig} carries the `persistent` modifier — a split that targets companion. */
+export function isPersistentTransition(config) {
+    if (typeof config === 'string')
+        return false;
+    return config.persistent === true;
+}
+// ════════════════════════════════════════════════════════════════
+// Navigation Layout Diagnostics
+// ════════════════════════════════════════════════════════════════
+/**
+ * What a {@link NavigationLayoutDiagnostic} says about the layout.
+ *
+ * `ERROR` means the runtime will do something the author did not ask for — a declared split that
+ * silently becomes a dialog. `WARNING` means a declaration is INERT: nothing goes wrong, and the
+ * author believes they configured something they did not.
+ *
+ * Neither is fatal. See {@link collectNavigationLayoutDiagnostics} for why.
+ */
+export var NavigationLayoutDiagnosticSeverity;
+(function (NavigationLayoutDiagnosticSeverity) {
+    NavigationLayoutDiagnosticSeverity["ERROR"] = "error";
+    NavigationLayoutDiagnosticSeverity["WARNING"] = "warning";
+})(NavigationLayoutDiagnosticSeverity || (NavigationLayoutDiagnosticSeverity = {}));
+/** The closed set of layout defects {@link collectNavigationLayoutDiagnostics} can recognise. */
+export var NavigationLayoutDiagnosticCode;
+(function (NavigationLayoutDiagnosticCode) {
+    /**
+     * A `SPLIT` is declared somewhere in the layout and NO adjacent zone is declared, so every one of
+     * those splits silently becomes an overlay.
+     *
+     * The single most surprising thing in the navigation runtime, and it was documented in
+     * `NavigationLayoutSchema`'s own JSDoc — *"`NavigationTransition.SPLIT` in a layout without
+     * secondary will escalate to overlay"* — while nothing checked it. An author gets a dialog where
+     * they asked for a pane, with no diagnostic anywhere.
+     */
+    NavigationLayoutDiagnosticCode["SPLIT_WITHOUT_ADJACENT_ZONE"] = "split-without-adjacent-zone";
+    /**
+     * A `persistent` split is declared and no `companion` zone exists. A persistent split targets
+     * companion SPECIFICALLY — it does not fall back to secondary — so it escalates to an overlay even
+     * in a layout that declares a perfectly good `secondary`.
+     *
+     * Separate from {@link SPLIT_WITHOUT_ADJACENT_ZONE} because the remedy is different and the
+     * surprise is larger: the author is looking at a declared pane and cannot see why their split
+     * refuses to use it.
+     */
+    NavigationLayoutDiagnosticCode["PERSISTENT_SPLIT_WITHOUT_COMPANION"] = "persistent-split-without-companion";
+    /**
+     * `minWidth`, `maxWidth`, `onEmpty` or `responsiveCollapse` declared on PRIMARY, where every one of
+     * them is inert: primary never collapses, never empties and takes the remaining space.
+     *
+     * `ZoneConfigSchema`'s JSDoc states this — *"Setting these on primary has no effect"* — so the
+     * diagnostic enforces a rule the contract already carries.
+     */
+    NavigationLayoutDiagnosticCode["INERT_PRIMARY_ZONE_FIELD"] = "inert-primary-zone-field";
+    /** A zone whose `minWidth` exceeds its `maxWidth`. The drag constraints cannot both be honoured. */
+    NavigationLayoutDiagnosticCode["ZONE_WIDTH_BOUNDS_INVERTED"] = "zone-width-bounds-inverted";
+})(NavigationLayoutDiagnosticCode || (NavigationLayoutDiagnosticCode = {}));
+/**
+ * Read an authored {@link NavigationLayout} and report what the runtime will silently do differently
+ * from what it says.
+ *
+ * ## Why this exists
+ *
+ * Nothing validated a navigation layout beyond its SHAPE until 2026-09-25 — there was no `refine`
+ * anywhere in this file — so three classes of declaration were accepted and quietly ignored. The
+ * escalation in {@link NavigationLayoutDiagnosticCode.SPLIT_WITHOUT_ADJACENT_ZONE} is the expensive
+ * one: it is documented in this file's own prose and produces a dialog where a pane was asked for.
+ *
+ * ## It REPORTS; it never refuses, and that is deliberate
+ *
+ * A `superRefine` on {@link NavigationLayoutSchema} was the obvious implementation and was rejected.
+ * The layout is parsed inside `AppConfiguration_Frontend_Schema` at application boot, so a refusal
+ * there would stop an application from starting over a split that renders as a dialog — wildly
+ * disproportionate, and the exact shape `.claude/rules/application-creation-directive.md` forbids:
+ * a mechanism that refuses rather than marks. The precedent for the chosen shape is the
+ * administrative-continuity boot report, which is non-fatal for the same reason.
+ *
+ * Pure, so it is equally usable from a test, a CLI check or a future authoring-time gate.
+ *
+ * ## What this CANNOT see, and what covers it instead
+ *
+ * A layout is not the only place a `SPLIT` is declared. A resource's `navigationOverrides`, a
+ * relationship transition and an action presentation all reach the resolver, and none of them is in
+ * the layout — so the only real instance of `SPLIT_WITHOUT_ADJACENT_ZONE` in this repository was
+ * INVISIBLE here: Wonder Todos declared `SPLIT` on `todos.READ` against a single-zone layout, every
+ * drill-in became a dialog for the life of the declaration, and this check reported clean.
+ *
+ * Re-deriving that population statically would mean a second enumeration of every tier that can
+ * produce a SPLIT, kept in step with the resolver by hand. The resolver has already decided, so the
+ * report lives at the DECISION instead: `useNavigationController` warns once per resource+operation
+ * when a resolution carries `SPLIT_ESCALATED_NO_ADJACENT_ZONE`. That covers every tier by
+ * construction and cannot drift. This function keeps the half a boot check can answer — the layout's
+ * own declarations, before anything navigates.
+ *
+ * ## The rule that was considered and REJECTED, because it fires on correct code
+ *
+ * *"A `secondary` zone is declared and no transition in the layout resolves to `SPLIT`, so the pane
+ * can never open."* It reads like the natural companion to the rules above and it is wrong: Wonder
+ * CRM declares `secondary` while `zones.primary.transitions.read` is `PUSH`, and its pane is reached
+ * ONLY by `deal`'s per-resource `navigationOverrides: [{ transition: SPLIT }]` — a declaration this
+ * function cannot see, because it lives in a resource's ui-behavior rather than in the layout. The
+ * rule would have reported the repository's one deliberate two-zone application as misconfigured.
+ *
+ * A checker that mostly reports correct code trains its reader to skim the reports that matter.
+ *
+ * (That rationale also mis-named Wonder CRM as "the repository's one deliberate two-zone
+ * application". The workbench declares `zones.secondary` too — and unlike CRM its pane IS reached
+ * from the layout, so the rejected rule would not have fired on it. The rejection stands on CRM
+ * alone.)
+ */
+export function collectNavigationLayoutDiagnostics(layout) {
+    const diagnostics = [];
+    const hasSecondary = layout.zones.secondary !== undefined;
+    const hasCompanion = layout.zones.companion !== undefined;
+    const hasAdjacentZone = hasSecondary || hasCompanion;
+    /*
+     * Every place a layout can declare a transition. Enumerated rather than walked, because the set is
+     * closed by `NavigationLayoutSchema` and a structural walk would also reach the per-resource
+     * overrides this function deliberately cannot see (see the rejected rule above).
+     */
+    const transitionSources = [
+        { path: 'zones.primary.transitions', transitions: layout.zones.primary?.transitions },
+        { path: 'zones.secondary.transitions', transitions: layout.zones.secondary?.transitions },
+        { path: 'zones.companion.transitions', transitions: layout.zones.companion?.transitions },
+        { path: 'appLevel.transitions', transitions: layout.appLevel?.transitions },
+        { path: 'fromOverlay.transitions', transitions: layout.fromOverlay?.transitions },
+        { path: `['${ViewportBreakpoint.MOBILE}'].transitions`, transitions: layout[ViewportBreakpoint.MOBILE]?.transitions },
+        { path: `['${ViewportBreakpoint.VERT_TABLET}'].transitions`, transitions: layout[ViewportBreakpoint.VERT_TABLET]?.transitions },
+    ];
+    for (const source of transitionSources) {
+        if (!source.transitions)
+            continue;
+        for (const [operation, config] of Object.entries(source.transitions)) {
+            if (config === undefined)
+                continue;
+            if (getTransitionVerb(config) !== NavigationTransition.SPLIT)
+                continue;
+            const path = `${source.path}.${operation}`;
+            if (!hasAdjacentZone) {
+                diagnostics.push({
+                    code: NavigationLayoutDiagnosticCode.SPLIT_WITHOUT_ADJACENT_ZONE,
+                    severity: NavigationLayoutDiagnosticSeverity.ERROR,
+                    path,
+                    message: 'Declares SPLIT, and the layout declares no `secondary` or `companion` zone. '
+                        + 'The split escalates to an OVERLAY, so this operation opens as a dialog rather than beside its source.',
+                    remedy: 'Declare `zones.secondary`, or change this transition to the one you want (PUSH, REPLACE or OVERLAY).',
+                });
+                continue;
+            }
+            if (isPersistentTransition(config) && !hasCompanion) {
+                diagnostics.push({
+                    code: NavigationLayoutDiagnosticCode.PERSISTENT_SPLIT_WITHOUT_COMPANION,
+                    severity: NavigationLayoutDiagnosticSeverity.ERROR,
+                    path,
+                    message: 'Declares a `persistent` SPLIT, which targets the `companion` zone specifically and does NOT '
+                        + 'fall back to `secondary`. With no companion declared it escalates to an OVERLAY.',
+                    remedy: 'Declare `zones.companion`, or drop `persistent` so the split may use `secondary`.',
+                });
+            }
+        }
+    }
+    const primary = layout.zones.primary;
+    if (primary) {
+        const inertOnPrimary = ['minWidth', 'maxWidth', 'onEmpty', 'responsiveCollapse']
+            .filter(field => primary[field] !== undefined);
+        for (const field of inertOnPrimary) {
+            diagnostics.push({
+                code: NavigationLayoutDiagnosticCode.INERT_PRIMARY_ZONE_FIELD,
+                severity: NavigationLayoutDiagnosticSeverity.WARNING,
+                path: `zones.primary.${field}`,
+                message: `\`${field}\` has no effect on the primary zone: primary never collapses, never empties, and takes `
+                    + 'the space the other zones leave.',
+                remedy: `Move \`${field}\` to \`zones.secondary\` or \`zones.companion\`, or remove it.`,
+            });
+        }
+    }
+    for (const zoneName of ['primary', 'secondary', 'companion']) {
+        const zone = layout.zones[zoneName];
+        if (zone?.minWidth !== undefined && zone.maxWidth !== undefined && zone.minWidth > zone.maxWidth) {
+            diagnostics.push({
+                code: NavigationLayoutDiagnosticCode.ZONE_WIDTH_BOUNDS_INVERTED,
+                severity: NavigationLayoutDiagnosticSeverity.ERROR,
+                path: `zones.${zoneName}`,
+                message: `\`minWidth\` (${zone.minWidth}) exceeds \`maxWidth\` (${zone.maxWidth}); the drag constraints cannot both hold.`,
+                remedy: 'Lower `minWidth` or raise `maxWidth` so the range is non-empty.',
+            });
+        }
+    }
+    return diagnostics;
+}
+// ════════════════════════════════════════════════════════════════
 // Per-Resource Operation Override
 // ════════════════════════════════════════════════════════════════
 // DELETED — NavigationOperationOverrideSchema and NavigationOperationOverride