@wildo-ai/saas-models 1.0.1

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

@@ -0,0 +1,678 @@
+/**
+ * Navigation — Configuration Schemas
+ *
+ * Zone-first, operation-driven navigation configuration model.
+ * Decomposes navigation into four independent axes:
+ *
+ * 1. **Meaning** (input signals) — contextual facts at navigation time (source zone, operation,
+ *    cardinality, viewport, depth). NOT configured — these are inputs to resolution.
+ * 2. **Transition** (verb) — HOW content arrives: push, replace, split, overlay, inplace, promote.
+ *    This is the primary thing that gets configured per zone.
+ * 3. **Placement** (zones) — WHERE content lives: primary, secondary, companion, overlay.
+ *    Zones are structural layout areas AND source context for resolution.
+ * 4. **Appearance** (visual) — HOW content renders in its slot: panel, drawer, dialog, sheet.
+ *    Only meaningful for split and overlay transitions.
+ *
+ * Key design decisions:
+ * - Zones own their complete behavior (no global defaults + override pattern)
+ * - Operations are transition keys; cardinality drives appearance only
+ * - Embedding (tabs/sections within a parent) is view composition, not navigation
+ * - `contentModel` (single/tabbed) is orthogonal to transitions
+ *
+ * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md
+ */
+import { z } from 'zod';
+import { ViewportBreakpoint, DisplayDirection } from '@wildo-ai/zod-decorators';
+import { CoreResourceOperation } from '../../resources/resources.shared.core.definitions.js';
+// ════════════════════════════════════════════════════════════════
+// Enums
+// ════════════════════════════════════════════════════════════════
+/**
+ * Navigation transition verbs — HOW content arrives at its destination.
+ *
+ * These are the six fundamental navigation actions. Every user-triggered
+ * navigation event resolves to exactly one of these verbs. The source zone's
+ * `transitions` map determines which verb fires for each operation.
+ *
+ * Four zone-level transitions: `push`, `replace`, `split`, `overlay`
+ * Two cross-context transitions: `inplace` (element-level), `promote` (escape to primary)
+ *
+ * `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)
+ */
+export var NavigationTransition;
+(function (NavigationTransition) {
+    /**
+     * Content added to the zone's stack (single) or as a new tab (tabbed).
+     * Back navigation pops the stack or switches to the previous tab.
+     * URL adds a new path segment.
+     */
+    NavigationTransition["PUSH"] = "push";
+    /**
+     * Content replaces the current content in the zone. No stack entry — the previous
+     * content is gone from the zone's state (but remains in browser history).
+     * URL replaces the current segment.
+     */
+    NavigationTransition["REPLACE"] = "replace";
+    /**
+     * 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.
+     */
+    NavigationTransition["SPLIT"] = "split";
+    /**
+     * Content opens in a floating layer above the entire layout (dialog or sheet).
+     * The underlying layout remains visible but non-interactive.
+     * Back navigation or Escape dismisses the overlay.
+     * URL adds an overlay param/hash.
+     */
+    NavigationTransition["OVERLAY"] = "overlay";
+    /**
+     * Element-level transformation within the current view. A specific item in a
+     * list/section transforms from one mode to another (read → edit, or a new
+     * create form materializes inline). The parent view stays. The zone stack is
+     * unchanged. Surrounding items remain visible.
+     *
+     * Fundamentally different from `replace` (which swaps the entire zone content).
+     * `inplace` operates at the element level, not the zone level.
+     *
+     * No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `inplace`.
+     * No appearance to configure — the element transforms within its existing slot.
+     *
+     * URL serialization: query param on the current URL (e.g., `?editing=<childId>`
+     * or `?creating=<resourceType>`).
+     *
+     * @example
+     * // Click "edit" on a child in parent's inline section → item transforms to edit form
+     * transitions: { [CoreResourceOperation.UPDATE]: NavigationTransition.INPLACE }
+     *
+     * // Click "add" in a relationship section → create form appears inline in the list
+     * transitions: { [CoreResourceOperation.CREATE]: NavigationTransition.INPLACE }
+     */
+    NavigationTransition["INPLACE"] = "inplace";
+    /**
+     * Escape the current context and open content at primary scope.
+     * Abandons the current context: overlays close, companion/secondary dismiss.
+     * The promoted content becomes the primary zone's top content.
+     *
+     * Use case: a link within an overlay should open as a full primary view,
+     * or a nested detail in a companion zone should "pop out" to primary.
+     *
+     * Fundamentally different from `push` (which stays in the current zone) and
+     * from `replace` (which replaces content within the same zone). `promote`
+     * crosses zones and always targets primary.
+     *
+     * No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `promote`.
+     * No appearance to configure — content fills primary (same as push/replace).
+     *
+     * URL serialization: full URL change (promoted resource becomes the primary route).
+     *
+     * @example
+     * // From an overlay, a link should open as primary (close overlay, show in primary)
+     * transitions: { [CoreResourceOperation.READ]: NavigationTransition.PROMOTE }
+     */
+    NavigationTransition["PROMOTE"] = "promote";
+})(NavigationTransition || (NavigationTransition = {}));
+/**
+ * Named layout zones — configurable structural areas WHERE content lives.
+ *
+ * Zones serve four purposes:
+ * 1. **Structural** — which physical areas exist in the layout (declared in config)
+ * 2. **Source context** — the same operation resolves differently FROM primary vs FROM secondary
+ * 3. **Responsive** — each zone carries its own collapse behavior per viewport
+ * 4. **Content model** — each zone independently manages single-stack or tabbed content
+ *
+ * Note: `overlay` is NOT a named zone — it's an implicit layer always available.
+ * Overlay is a runtime destination, not a configurable zone. See `NavigationZone`
+ * in the frontend runtime types for the full set including overlay.
+ */
+export var NavigationZoneName;
+(function (NavigationZoneName) {
+    /** Main content area. Lists, root-level reads, primary workspace. Always exists. */
+    NavigationZoneName["PRIMARY"] = "primary";
+    /**
+     * First adjacent zone. Detail content in list-detail patterns.
+     * Only exists if declared in config. Appears when a `split` transition targets it.
+     * Typical use: showing item details alongside a list.
+     */
+    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.
+     * Typical use: Slack thread panel, VS Code terminal, documentation sidebar.
+     */
+    NavigationZoneName["COMPANION"] = "companion";
+})(NavigationZoneName || (NavigationZoneName = {}));
+/**
+ * How a zone manages multiple items. Orthogonal to transitions.
+ *
+ * The transition says "content arrives" — the content model says
+ * "how does the zone accommodate it." Any zone can use any content model,
+ * regardless of which transitions it supports.
+ */
+export var NavigationZoneContentModel;
+(function (NavigationZoneContentModel) {
+    /**
+     * Navigation stack: new content pushes on top, previous preserved underneath.
+     * Only one item visible at a time. Back navigation pops the stack.
+     * `replace` replaces the top without adding to the stack.
+     * This is the default for all zones.
+     */
+    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).
+     * When no tabs remain, `onEmpty` behavior applies.
+     */
+    NavigationZoneContentModel["TABBED"] = "tabbed";
+})(NavigationZoneContentModel || (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).
+ */
+export var ResponsiveCollapseMode;
+(function (ResponsiveCollapseMode) {
+    /**
+     * Zone hides. Its content joins primary's navigation stack.
+     * The user sees the content in-context within primary.
+     * Back navigation pops back to primary's previous content.
+     */
+    ResponsiveCollapseMode["PUSH"] = "push";
+    /**
+     * Zone hides. Its content opens as an overlay on top of primary.
+     * The user sees the content as a floating sheet/dialog.
+     * Dismiss returns to the underlying primary content.
+     */
+    ResponsiveCollapseMode["OVERLAY"] = "overlay";
+})(ResponsiveCollapseMode || (ResponsiveCollapseMode = {}));
+/**
+ * What happens when a zone's last content is dismissed.
+ * Only meaningful for secondary and companion zones (primary never empties,
+ * overlay auto-dismisses by definition).
+ */
+export var ZoneEmptyBehavior;
+(function (ZoneEmptyBehavior) {
+    /**
+     * Zone hides, adjacent zones expand to fill the space.
+     * Example: closing the last detail → layout returns to list-only.
+     * This is the default for all non-primary zones.
+     */
+    ZoneEmptyBehavior["COLLAPSE"] = "collapse";
+    /**
+     * Zone stays visible with an empty-state placeholder.
+     * Example: "Select an item to view details" message. Keeps layout stable.
+     * Useful when the user frequently toggles between items.
+     */
+    ZoneEmptyBehavior["EMPTY_STATE"] = "emptyState";
+})(ZoneEmptyBehavior || (ZoneEmptyBehavior = {}));
+/**
+ * Visual presentation for overlay transitions.
+ * Determines how floating content renders above the layout.
+ */
+export var OverlayAppearance;
+(function (OverlayAppearance) {
+    /**
+     * Centered modal dialog with backdrop.
+     * Best for focused tasks: create forms, confirmations, destructive actions.
+     * Blocks underlying content visually. Escape or backdrop click dismisses.
+     */
+    OverlayAppearance["DIALOG"] = "dialog";
+    /**
+     * Side or bottom drawer panel that slides in from an edge.
+     * Best for contextual content that benefits from seeing the underlying layout.
+     * Less disruptive than dialog. Common for detail views on mobile.
+     */
+    OverlayAppearance["SHEET"] = "sheet";
+})(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>`.
+ *
+ * Produces a union: the plain inner schema OR a record keyed by `ViewportBreakpoint`
+ * with inner schema values. The record must have at least one key.
+ *
+ * @param innerSchema - Zod schema for the value type at each breakpoint.
+ */
+export function viewportDiscriminatedSchema(innerSchema) {
+    return z.union([
+        innerSchema,
+        z.partialRecord(z.enum(ViewportBreakpoint), innerSchema).refine((obj) => Object.keys(obj).length > 0, { message: 'Viewport-discriminated object must have at least one breakpoint key' }),
+    ]);
+}
+// ════════════════════════════════════════════════════════════════
+// Transition Config
+// ════════════════════════════════════════════════════════════════
+/**
+ * Extended transition with lifecycle modifiers.
+ *
+ * Most transitions are simple verbs (just the enum value). The object form
+ * adds lifecycle semantics for two specific patterns:
+ *
+ * - **Companion pattern**: `{ transition: NavigationTransition.SPLIT, persistent: true }`
+ *   The split zone persists when the source zone's content changes.
+ *   Without `persistent`, a split zone would clear when primary navigates away.
+ *
+ * - **Inspect pattern**: `{ transition: NavigationTransition.OVERLAY, ephemeral: true }`
+ *   The overlay auto-closes when the source zone's stack changes.
+ *   Without `ephemeral`, overlays stay open until explicitly dismissed.
+ *
+ * Semantic constraints (enforced by `.refine()`):
+ * - `persistent` is only valid on `split` transitions
+ * - `ephemeral` is only valid on `overlay` transitions
+ * - `persistent` and `ephemeral` are mutually exclusive
+ * - `inplace` and `promote` do not accept any modifier (they are always simple verbs)
+ */
+export const TransitionObjectSchema = z.object({
+    /** The transition verb. */
+    transition: z.enum(NavigationTransition),
+    /**
+     * When `true`, the split zone persists when the source zone navigates away.
+     * Only valid on `split` transitions. Targets the companion zone specifically
+     * (rather than the default adjacent zone resolution).
+     *
+     * Example: Slack thread panel stays open when switching channels.
+     */
+    persistent: z.boolean().optional(),
+    /**
+     * When `true`, the overlay auto-closes when the source zone's stack changes.
+     * Only valid on `overlay` transitions.
+     *
+     * Example: Quick-inspect preview that dismisses when the user clicks another item.
+     */
+    ephemeral: z.boolean().optional(),
+}).refine((obj) => {
+    if (obj.persistent && obj.transition !== NavigationTransition.SPLIT)
+        return false;
+    if (obj.ephemeral && obj.transition !== NavigationTransition.OVERLAY)
+        return false;
+    if (obj.persistent && obj.ephemeral)
+        return false;
+    return true;
+}, { message: 'persistent is only valid on split; ephemeral is only valid on overlay; they are mutually exclusive' });
+/**
+ * A transition configuration: either a simple verb string or an object with modifiers.
+ *
+ * @example
+ * // Simple verb
+ * transitions: { read: NavigationTransition.SPLIT, create: NavigationTransition.OVERLAY }
+ *
+ * // Object with lifecycle modifier
+ * transitions: { read: { transition: NavigationTransition.SPLIT, persistent: true } }
+ */
+export const TransitionConfigSchema = z.union([
+    z.enum(NavigationTransition),
+    TransitionObjectSchema,
+]);
+// ════════════════════════════════════════════════════════════════
+// Zone Configuration
+// ════════════════════════════════════════════════════════════════
+/**
+ * Operation → transition mapping for a zone.
+ *
+ * Partial record — only operations that the zone handles need entries.
+ * Missing operations fall back to the framework's hardcoded defaults.
+ *
+ * Keys are `CoreResourceOperation` values such as `read`, `list`, `create`,
+ * `update`, `delete`, and `search`.
+ *
+ * @example
+ * transitions: {
+ *   read:    NavigationTransition.SPLIT,       // click item → split to secondary
+ *   list:    NavigationTransition.REPLACE,     // "View all" → replace primary
+ *   create:  NavigationTransition.OVERLAY,     // new item → dialog
+ *   update:  NavigationTransition.INPLACE,     // edit → transform element inline
+ *   delete:  NavigationTransition.OVERLAY,     // confirm → dialog
+ *   search:  NavigationTransition.PUSH,        // advanced search → full-surface route
+ * }
+ *
+ * // From an overlay, promote a link to primary view
+ * transitions: {
+ *   read:    NavigationTransition.PROMOTE,     // link in overlay → escape to primary
+ * }
+ */
+/** Partial record — only operations that the zone handles need entries. Missing operations fall back to framework defaults. */
+export const ZoneTransitionsSchema = z.partialRecord(z.enum(CoreResourceOperation), TransitionConfigSchema);
+/**
+ * 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:
+ * - `push`/`replace` fill the zone
+ * - `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.DIALOG },   // sheet on tablet, dialog 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). */
+    overlay: viewportDiscriminatedSchema(z.enum(OverlayAppearance)).optional(),
+});
+/**
+ * Full zone configuration.
+ *
+ * Each declared zone in the layout owns its complete behavior:
+ * 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.
+ * Setting these on primary has no effect.
+ */
+export const ZoneConfigSchema = z.object({
+    /**
+     * How this zone manages multiple items.
+     * - `NavigationZoneContentModel.SINGLE` (default): stack-based navigation. One item visible, back pops.
+     * - `NavigationZoneContentModel.TABBED`: parallel tabs. Tab bar visible, multiple items accessible.
+     * @default NavigationZoneContentModel.SINGLE
+     */
+    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. */
+    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`.
+     */
+    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`.
+     */
+    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.
+     */
+    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).
+     *
+     * @example
+     * responsiveCollapse: ResponsiveCollapseMode.PUSH                                                              // always push into primary
+     * responsiveCollapse: { [ViewportBreakpoint.VERT_TABLET]: ResponsiveCollapseMode.PUSH, [ViewportBreakpoint.MOBILE]: ResponsiveCollapseMode.OVERLAY }     // tablet: push, mobile: overlay
+     */
+    responsiveCollapse: viewportDiscriminatedSchema(z.enum(ResponsiveCollapseMode)).optional(),
+});
+// ════════════════════════════════════════════════════════════════
+// App-Level & From-Overlay Configuration
+// ════════════════════════════════════════════════════════════════
+/**
+ * App-level navigation configuration: from OUTSIDE the zone system.
+ *
+ * Covers navigation triggered by sidebar clicks, command palette selections,
+ * hotkey shortcuts, toast actions, and notification clicks.
+ *
+ * App-level navigation causes a **layout reset**: primary content is replaced,
+ * secondary and companion zones are cleared. This is fundamentally different
+ * from zone-level navigation where the source zone's content persists.
+ *
+ * @example
+ * appLevel: {
+ *   transitions: {
+ *     list:    NavigationTransition.REPLACE,   // sidebar "Projects" → replace primary, clear others
+ *     read:    NavigationTransition.REPLACE,   // command palette "Go to X" → replace primary
+ *     create:  NavigationTransition.OVERLAY,   // quick action "New X" → dialog
+ *     search:  NavigationTransition.REPLACE,   // command/menu search surface → replace primary
+ *   },
+ *   appearance: { overlay: OverlayAppearance.DIALOG },
+ * }
+ */
+export const AppLevelConfigSchema = z.object({
+    /** Operation → transition mapping for app-level navigation. */
+    transitions: ZoneTransitionsSchema,
+    /** Appearance overrides for app-level transitions. */
+    appearance: ZoneAppearanceSchema.optional(),
+});
+/**
+ * Navigation from within an overlay (dialog or sheet).
+ *
+ * When already in an overlay, transitions behave differently to avoid
+ * nesting overlays. Typically all operations `push` within the overlay's
+ * own stack instead of opening new overlays.
+ *
+ * No appearance config — the content is already inside an overlay.
+ *
+ * @example
+ * fromOverlay: {
+ *   transitions: {
+ *     read:    NavigationTransition.PUSH,   // push within overlay — don't nest modals
+ *     list:    NavigationTransition.PUSH,
+ *     create:  NavigationTransition.PUSH,
+ *     search:  NavigationTransition.PUSH,
+ *   },
+ * }
+ */
+export const FromOverlayConfigSchema = z.object({
+    /** Operation → transition mapping when navigating from within an overlay. */
+    transitions: ZoneTransitionsSchema,
+});
+// ════════════════════════════════════════════════════════════════
+// Split Geometry
+// ════════════════════════════════════════════════════════════════
+/**
+ * Companion-specific split geometry.
+ * Controls how the companion zone is sized and positioned relative to the main content area.
+ */
+export const CompanionSplitConfigSchema = z.object({
+    /**
+     * Main-area-to-companion size ratio.
+     * @example [70, 30] — companion takes 30% of available space
+     * @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.
+     * Per-side drag constraints use `ZoneConfig.minWidth`/`maxWidth` on the companion zone.
+     * @default false
+     */
+    resizable: z.boolean().default(false),
+});
+/**
+ * Top-level split geometry — describes the physical relationship between zones.
+ *
+ * This is a top-level config (not per-zone) because it describes the INTER-zone
+ * layout: how much space each zone gets, and the split direction.
+ *
+ * @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,
+ *   },
+ * }
+ */
+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]
+     */
+    ratio: z.tuple([z.number(), z.number()]).default([50, 50]),
+    /**
+     * Split direction between primary and secondary.
+     * - `DisplayDirection.VERTICAL` (default): side-by-side (most common for list-detail)
+     * - `DisplayDirection.HORIZONTAL`: top-bottom (less common)
+     * @default DisplayDirection.VERTICAL
+     */
+    orientation: z.enum(DisplayDirection).default(DisplayDirection.VERTICAL),
+    /**
+     * Whether the primary↔secondary split boundary is user-draggable.
+     * When `true`, a draggable divider appears between primary and secondary zones.
+     * Per-side drag constraints use `ZoneConfig.minWidth`/`maxWidth` on each zone.
+     * @default false
+     */
+    resizable: z.boolean().default(false),
+    /** Companion zone split geometry. Only relevant if companion zone is declared. */
+    companion: CompanionSplitConfigSchema.optional(),
+});
+// ════════════════════════════════════════════════════════════════
+// Viewport Override Block
+// ════════════════════════════════════════════════════════════════
+/**
+ * Global viewport override — applies across ALL zones at a given breakpoint.
+ *
+ * Use for sweeping mobile/tablet overrides that affect the entire app.
+ * For per-zone responsive behavior, use `ZoneConfig.responsiveCollapse` and
+ * viewport-discriminated appearance values instead.
+ *
+ * @example
+ * // In NavigationLayout:
+ * [ViewportBreakpoint.MOBILE]: {
+ *   transitions: {
+ *     read:   NavigationTransition.PUSH,    // mobile: no splits, everything pushes
+ *     create: { transition: NavigationTransition.OVERLAY, ephemeral: true }, // mobile: create opens as an inspect-style ephemeral overlay
+ *   },
+ * }
+ */
+export const ViewportOverrideSchema = z.object({
+    /** Operation → transition overrides at this viewport. Merged over zone defaults. */
+    transitions: z.partialRecord(z.enum(CoreResourceOperation), TransitionConfigSchema).optional(),
+});
+// ════════════════════════════════════════════════════════════════
+// NavigationLayout — Top-Level App Configuration
+// ════════════════════════════════════════════════════════════════
+/**
+ * The complete navigation layout configuration for an application.
+ *
+ * This is the single configuration object that defines the entire navigation
+ * 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):
+ * 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
+ *
+ * @example
+ * const layout: NavigationLayout = {
+ *   zones: {
+ *     primary: { transitions: { read: NavigationTransition.SPLIT, create: NavigationTransition.OVERLAY, update: NavigationTransition.INPLACE } },
+ *     secondary: { transitions: { read: NavigationTransition.PUSH }, onEmpty: ZoneEmptyBehavior.COLLAPSE },
+ *   },
+ *   appLevel: { transitions: { list: NavigationTransition.REPLACE, create: NavigationTransition.OVERLAY } },
+ *   fromOverlay: { transitions: { read: NavigationTransition.PROMOTE } },
+ *   split: { autoSplit: true, ratio: [40, 60] },
+ *   maxDepth: 2,
+ * };
+ */
+export const NavigationLayoutSchema = z.object({
+    /**
+     * Zone declarations. Primary is required, secondary and companion are optional.
+     * Undeclared zones cannot be targeted by transitions — `NavigationTransition.SPLIT` in a layout
+     * without secondary will escalate to overlay.
+     */
+    zones: z.object({
+        /** Primary zone — always exists. Main content area (lists, root reads). */
+        primary: ZoneConfigSchema,
+        /** Secondary zone — optional. First adjacent zone for detail content. */
+        secondary: ZoneConfigSchema.optional(),
+        /** Companion zone — optional. Persistent supplementary content. */
+        companion: ZoneConfigSchema.optional(),
+    }),
+    /**
+     * How navigation from the app shell (sidebar, command palette, hotkey) behaves.
+     * Causes a layout reset when targeting primary.
+     */
+    appLevel: AppLevelConfigSchema.optional(),
+    /**
+     * How navigation within an overlay behaves.
+     * Prevents overlay nesting — typically everything pushes within the overlay stack.
+     */
+    fromOverlay: FromOverlayConfigSchema.optional(),
+    /** Split geometry: ratios, orientations, autoSplit. */
+    split: SplitConfigSchema.optional(),
+    /**
+     * Maximum push depth before the framework escalates to overlay.
+     * When a zone's stack depth reaches `maxDepth`, the next `push` opens an overlay instead.
+     * Prevents infinitely deep navigation stacks. Per-relationship `maxDepth` can override.
+     */
+    maxDepth: z.number().int().positive().optional(),
+    /**
+     * Mobile viewport override — applies across all zones when viewport is `<md` (< 768px).
+     * Use for sweeping mobile behavior changes (e.g., all splits become pushes).
+     */
+    [ViewportBreakpoint.MOBILE]: ViewportOverrideSchema.optional(),
+    /**
+     * Tablet viewport override — applies across all zones when viewport is `<lg` (768–1023px).
+     * Use for tablet-specific behavior changes.
+     */
+    [ViewportBreakpoint.VERT_TABLET]: ViewportOverrideSchema.optional(),
+});
+// ════════════════════════════════════════════════════════════════
+// Per-Resource Operation Override
+// ════════════════════════════════════════════════════════════════
+// DELETED — NavigationOperationOverrideSchema and NavigationOperationOverride
+// Transferred to @wildo-ai/saas-frontend-lib (resources.frontend.schemas)
+//# sourceMappingURL=navigation.shared.schemas.js.map