@wildo-ai/saas-frontend-lib 1.0.1

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

@@ -0,0 +1,824 @@
+/**
+ * Navigation — Frontend Runtime Types
+ *
+ * Runtime types for zone state, navigation stacks/tabs, events, content,
+ * initiator context, and resolution results. These are the types the
+ * navigation controller, context, and rendering layer operate on.
+ *
+ * Configuration types (what developers configure) live in
+ * `@wildo-ai/saas-models` — `navigation.shared.schemas.ts`.
+ * This file imports config enums from there and defines runtime state on top.
+ *
+ * Key runtime concepts:
+ * - **NavigationZone**: type union = `NavigationZoneName | 'overlay'` — extends the 3
+ *   configurable zones with the implicit overlay destination (no enum duplication)
+ * - **NavigationState**: per-zone stack/tab state + separate overlay stack
+ * - **NavigationResolutionResult**: output of the resolver, consumed by the controller
+ *
+ * @see _code_archive/docs-archive/navigation/navigation-v3-reflection.md
+ */
+import React from 'react';
+import { z } from 'zod';
+import { NavigationTransition, NavigationZoneName, OverlayAppearance, SplitAppearance, ParentDisplay, type RelationshipDisplayInChildView, type TransitionConfig } from '@wildo-ai/saas-models';
+import { ViewportBreakpoint } from '@wildo-ai/zod-decorators';
+import { ApplicationLevelComponentType, SidebarItemDisplayPolicy } from '../../core/config/app-level-components.frontend.schemas.js';
+import { EnginePageRef } from '../../core/config/launcher-items.frontend.schemas.js';
+import type { NavigationOperationOverride, FrontendResourceConfiguration_Operation } from '../../core/resources/resources.frontend.schemas.js';
+import { CoreResourceOperation, type RequiredFeaturesConfig, FeatureUnavailabilityBehavior, FeatureUnavailabilityReason, type FeatureUpgradeOption } from '@wildo-ai/saas-models';
+import { type FrontendResourceOperationContext } from '../../core/resources/resources.frontend.schemas.js';
+import type { ChartViewDefinition, InsertedChartDeclaration, ResolvedInsertedChartDescriptor } from '../../core/config/chart-view.frontend.schemas.js';
+/**
+ * Runtime zone identifiers — all possible destinations for navigation content.
+ *
+ * Extends `NavigationZoneName` (the 3 configurable zones) with `OVERLAY`,
+ * which is an implicit runtime destination (not a configurable zone).
+ *
+ * Implemented as a const object (spread of `NavigationZoneName` + `OVERLAY`)
+ * to avoid duplicating the 3 structural zone values already defined in
+ * `NavigationZoneName`. Use `NavigationZone.PRIMARY`, `NavigationZone.OVERLAY`, etc.
+ */
+declare const OVERLAY_ZONE: "overlay";
+export declare const NavigationZone: {
+    /**
+     * Implicit floating layer above all zones. Not a configurable zone —
+     * always available as a destination for `overlay` transitions.
+     * Content renders as dialog or sheet based on the source zone's appearance config.
+     */
+    readonly OVERLAY: "overlay";
+    readonly PRIMARY: NavigationZoneName.PRIMARY;
+    readonly SECONDARY: NavigationZoneName.SECONDARY;
+    readonly COMPANION: NavigationZoneName.COMPANION;
+};
+/** Union of all runtime zone identifiers (3 structural + overlay). */
+export type NavigationZone = NavigationZoneName | typeof OVERLAY_ZONE;
+/** Zod schema for `NavigationZone` — validates any structural zone name or `'overlay'`. */
+export declare const NavigationZoneSchema: z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"overlay">]>;
+/**
+ * All structural zones (excludes overlay).
+ * Used for iterating over zones that have configuration and state.
+ */
+export declare const NAVIGATION_STRUCTURAL_ZONES: readonly NavigationZoneName[];
+/**
+ * Navigation source for app-shell actions (sidebar, command palette, hotkey, toast, notification).
+ * Used alongside `NavigationZone` to form the complete set of navigation origins.
+ * App-level navigation causes a layout reset: primary replaced, other zones cleared.
+ */
+export declare const APP_LEVEL_NAVIGATION_SOURCE: "appLevel";
+/**
+ * What kind of content is being navigated to.
+ * Frontend-only — used by navigation stacks, resolution, and content rendering.
+ */
+export declare enum NavigationContentType {
+    RESOURCE_OPERATION = "resource_operation",
+    COMPOSITE_VIEW = "composite_view",
+    CHART_VIEW = "chart_view",
+    FULL_CUSTOM_VIEW = "full_custom_view",
+    FLOWS_ACTORS_VIEW = "flows_actors_view",
+    EXECUTION_VIEW = "execution_view",
+    CUSTOM_COMPONENT = "custom_component",
+    ENGINE_PAGE = "engine_page",
+    INLINE_CREATE = "inline_create",
+    ERROR_MODAL = "error_modal"
+}
+/**
+ * How a navigation entry was created — tracks the origin of each stack entry.
+ *
+ * Used to coordinate between controller-initiated (programmatic) and
+ * URL-initiated (browser back/forward, direct link) navigation.
+ * The controller needs to know if a navigation event came from URL sync
+ * to avoid infinite loops (URL change → navigate → URL change → ...).
+ */
+export declare enum NavigationSource {
+    /** Navigation triggered programmatically by useNavigationController. */
+    CONTROLLER = "controller",
+    /** Navigation triggered by URL change (bookmark, back button, direct link). */
+    URL_SYNC = "url_sync"
+}
+/**
+ * Lightweight relationship metadata carried on navigation events.
+ *
+ * When navigation is triggered by a parent→child relationship traversal
+ * (e.g., clicking a related item in a parent's detail view), this carries
+ * just enough relationship info for the destination component to configure
+ * its parent reference display (breadcrumb, badge, etc.).
+ *
+ * Intentionally NOT the full `ResourceRelationship` — avoids importing the
+ * entire relationship schema tree into navigation events (Nav-2 decision).
+ */
+export interface NavigationSourceRelationship {
+    /** The resource type of the parent in this relationship. */
+    parentResourceType: string;
+    /** The specific parent instance ID, if navigating from a specific parent record. */
+    parentResourceId?: string;
+    /** The resource type of the child in this relationship. */
+    childResourceType: string;
+    /** FK field used to traverse this edge when disambiguation is required. */
+    foreignKeyField?: string;
+    /** Stable parent→child edge key for navigation-time identity. */
+    relationshipEdgeKey?: string;
+    /**
+     * The `inChildView` display config from the relationship definition.
+     * Controls how the parent reference appears in the child's view (breadcrumb, badge, etc.).
+     */
+    inChildView?: RelationshipDisplayInChildView;
+}
+/**
+ * Source context for a navigation event — WHO triggered the navigation and FROM WHERE.
+ *
+ * The resolver uses `sourceZone` as the primary input signal to determine
+ * which transition applies. The same operation produces different transitions
+ * depending on where the user currently is.
+ */
+export interface NavigationInitiatorContext {
+    /**
+     * Where the navigation was triggered from.
+     *
+     * - A `NavigationZone` value: navigation from within a structural zone or overlay
+     * - `APP_LEVEL_NAVIGATION_SOURCE`: navigation from the app shell (sidebar,
+     *   command palette, hotkey, toast action, notification click). Causes a layout reset.
+     *
+     * This replaces the old `type: NavigationInitiatorType` + `sourcePane: NavigationPane`
+     * pattern with a single, explicit field.
+     */
+    sourceZone: NavigationZone | typeof APP_LEVEL_NAVIGATION_SOURCE;
+    /**
+     * Which app-level launcher triggered the navigation.
+     * Only relevant when `sourceZone === APP_LEVEL_NAVIGATION_SOURCE`. Examples: sidebar click,
+     * command palette selection, quick action button, hotkey.
+     */
+    launcher?: ApplicationLevelComponentType;
+    /** The operation that produced this navigation (read, create, delete, etc.). */
+    sourceOperation?: CoreResourceOperation;
+    /**
+     * When navigation was triggered by traversing a parent→child relationship.
+     * Carries lightweight relationship info so the destination can configure
+     * parent reference display (breadcrumb, badge, summary card).
+     */
+    sourceRelationship?: NavigationSourceRelationship;
+}
+/** Content representing a resource operation (list, read, create, etc.). */
+export interface NavigationContent_ResourceOperation {
+    contentType: NavigationContentType.RESOURCE_OPERATION;
+    /** Fully resolved resource context: resource type, operation, params, record ID, etc. */
+    resourceContext: FrontendResourceOperationContext;
+}
+/** Content representing a composite view (dashboard, overview, etc.). */
+export interface NavigationContent_CompositeView {
+    contentType: NavigationContentType.COMPOSITE_VIEW;
+    /** Reference identifier for the composite view definition. */
+    viewRef: string;
+    /** Optional context resource IDs to pass to the view for scoping/filtering. */
+    contextResourceIdentifiers?: Record<string, string>;
+}
+/** Content representing a chart view (data visualization). */
+export interface NavigationContent_ChartView {
+    contentType: NavigationContentType.CHART_VIEW;
+    /** Reference identifier for the chart view definition. */
+    viewRef: string;
+    /** Optional context resource IDs to scope the chart's data. */
+    contextResourceIdentifiers?: Record<string, string>;
+    /** Optional route-derived URL params for standalone chart URL_PARAM bindings. */
+    urlParamValues?: Record<string, string>;
+    /** Optional feature-gating metadata for chart-stack rendering. */
+    requiredFeatures?: RequiredFeaturesConfig;
+    /** Optional pre-resolved chart surface definition for inserted/routed charts. */
+    viewDefinition?: ChartViewDefinition | InsertedChartDeclaration;
+    /** Optional pre-resolved descriptor for inserted/routed charts. */
+    runtimeDescriptor?: ResolvedInsertedChartDescriptor;
+}
+/** Content representing a full custom view (developer-provided component). */
+export interface NavigationContent_FullCustomView {
+    contentType: NavigationContentType.FULL_CUSTOM_VIEW;
+    /** Reference identifier for the view definition. */
+    viewRef: string;
+    /** Reference to the custom React component registered for this view. */
+    fullCustomComponentRef: string;
+    /** Optional context resource IDs to pass to the component. */
+    contextResourceIdentifiers?: Record<string, string>;
+}
+/** Content representing a flows & actors view (AI workflows, agent execution). */
+export interface NavigationContent_FlowsActorsView {
+    contentType: NavigationContentType.FLOWS_ACTORS_VIEW;
+    /** Reference identifier for the view definition. */
+    viewRef: string;
+    /** System references for the flows/actors displayed in this view. */
+    flowsActorsSystemRefs: string[];
+    /** Optional context resource IDs to scope the view. */
+    contextResourceIdentifiers?: Record<string, string>;
+}
+/** Content representing an execution view (framework-owned execution host). */
+export interface NavigationContent_ExecutionView {
+    contentType: NavigationContentType.EXECUTION_VIEW;
+    /** Reference identifier for the execution view definition. */
+    viewRef: string;
+    /** Optional context resource IDs to scope the execution view. */
+    contextResourceIdentifiers?: Record<string, string>;
+}
+/** Content representing a generic app-level custom component. */
+export interface NavigationContent_CustomComponent {
+    contentType: NavigationContentType.CUSTOM_COMPONENT;
+    /** Registered component reference to materialize. */
+    componentRef: string;
+    /** Optional context resource IDs to pass to the component. */
+    contextResourceIdentifiers?: Record<string, string>;
+}
+/** Content representing a router-backed engine page. */
+export interface NavigationContent_EnginePage {
+    contentType: NavigationContentType.ENGINE_PAGE;
+    pageRef: EnginePageRef;
+}
+/** Content representing a typed sidebar inline-create flow. */
+export interface NavigationContent_InlineCreate {
+    contentType: NavigationContentType.INLINE_CREATE;
+    resourceContext: FrontendResourceOperationContext;
+    defaultValues: Record<string, unknown>;
+}
+/** Content representing an error modal pushed through the overlay stack. */
+export interface NavigationContent_ErrorModal {
+    contentType: NavigationContentType.ERROR_MODAL;
+    errorType: string;
+    message: string;
+    context?: Record<string, unknown>;
+    wildoError?: unknown;
+}
+/**
+ * Discriminated union of all navigation content types.
+ * Discriminated on `contentType` for clean narrowing.
+ * Every navigation stack entry carries exactly one of these.
+ */
+export type NavigationContent = NavigationContent_ResourceOperation | NavigationContent_CompositeView | NavigationContent_ChartView | NavigationContent_FullCustomView | NavigationContent_FlowsActorsView | NavigationContent_ExecutionView | NavigationContent_CustomComponent | NavigationContent_EnginePage | NavigationContent_InlineCreate | NavigationContent_ErrorModal;
+/**
+ * A single entry in a zone's navigation stack (or overlay stack).
+ *
+ * Each entry represents one piece of content that was navigated to.
+ * The stack maintains navigation history within a zone for back navigation.
+ * In tabbed zones, entries represent parallel tabs (not a depth stack).
+ */
+export interface NavigationStackEntry {
+    /** Unique identifier for this stack entry (UUID). */
+    id: string;
+    /** The content being displayed in this entry. */
+    content: NavigationContent;
+    /**
+     * URL path that represents this navigation state.
+     * Used for URL serialization, deep linking, and browser history.
+     * Every navigation state must be URL-addressable.
+     */
+    urlPath?: string;
+    /** Timestamp (ms since epoch) when this entry was created. For ordering and debugging. */
+    timestamp: number;
+    /** Which zone this entry lives in. */
+    zone: NavigationZone;
+    /** The context that triggered this navigation (source zone, operation, relationship). */
+    initiator?: NavigationInitiatorContext;
+    /** Whether this entry was created by the controller or by URL sync. */
+    navigationSource: NavigationSource;
+    /**
+     * The transition verb that placed this entry (push, replace, split, overlay, promote).
+     * Note: `inplace` does not produce a stack entry (it transforms an element in the
+     * current view without changing zone state), so it will never appear here.
+     */
+    transition: NavigationTransition;
+    /**
+     * Visual appearance for this entry's transition.
+     * Set by the resolver from zone appearance config. Only meaningful for
+     * overlay entries (dialog/sheet) and split entries (panel/drawer).
+     * Used by ContentAreas to decide how to render overlay or split content.
+     */
+    appearance?: OverlayAppearance | SplitAppearance;
+    /**
+     * When `true`, this overlay entry auto-closes when the source zone's stack changes.
+     * Set by the resolver from `TransitionConfig.ephemeral`. Only valid on overlay entries.
+     * Used by NavigationContext auto-close logic.
+     */
+    ephemeral?: boolean;
+}
+/**
+ * Runtime state of a single navigation zone.
+ *
+ * Each zone independently tracks its navigation stack and visibility.
+ * For tabbed zones, `activeTabId` identifies which tab is currently displayed.
+ *
+ * Zone lifecycle states (not an enum — derived from config + runtime):
+ * - **Inactive**: zone not declared in config. Doesn't exist in DOM.
+ * - **Hidden**: zone exists but not visible (`defaultVisible: false`, collapsed, `onEmpty: ZoneEmptyBehavior.COLLAPSE`).
+ * - **Empty**: zone visible but no content. Only when `onEmpty: 'emptyState'`.
+ * - **Active**: zone has content and is visible.
+ */
+export interface NavigationZoneState {
+    /** Which zone this state belongs to. */
+    zone: NavigationZone;
+    /**
+     * The zone's navigation stack.
+     * - In `single` content model: depth stack. Top entry is visible. Back pops.
+     * - In `NavigationZoneContentModel.TABBED` content model: tab entries. All are "open", one is active.
+     */
+    stack: NavigationStackEntry[];
+    /**
+     * Whether this zone is currently rendered in the DOM and visible.
+     * `false` when: zone is collapsed (responsive), empty with `onEmpty: ZoneEmptyBehavior.COLLAPSE`,
+     * or `defaultVisible: false` and no content has been pushed yet.
+     */
+    isVisible: boolean;
+    /**
+     * For `NavigationZoneContentModel.TABBED` zones — the ID of the currently active tab entry.
+     * References `NavigationStackEntry.id`. When `undefined`, the zone is in single mode.
+     * Using ID (not index) for stability when tabs are reordered or closed.
+     */
+    activeTabId?: string;
+}
+/**
+ * Full runtime navigation state.
+ *
+ * Zones hold their own stack/tab state keyed by `NavigationZoneName` (the 3 structural
+ * zones). Overlay is separate because it's not a configurable zone — it's an implicit
+ * floating layer that can hold a stack of its own (push within overlay).
+ */
+export interface NavigationState {
+    /**
+     * Per-zone state for the 3 structural zones (primary, secondary, companion).
+     * Keyed by `NavigationZoneName` — NOT `NavigationZone` (which includes overlay).
+     */
+    zones: Record<NavigationZoneName, NavigationZoneState>;
+    /**
+     * Overlay stack — content shown in the floating layer above all zones.
+     * Supports push depth within the overlay (e.g., navigating to a related item
+     * from within a create dialog pushes onto the overlay stack).
+     * When the stack empties, the overlay dismisses.
+     */
+    overlay: NavigationStackEntry[];
+}
+/**
+ * Output of the navigation policy resolver — tells the controller exactly what to do.
+ *
+ * The resolver takes (sourceZone, operation, resourceConfig, viewport) as inputs
+ * and produces this result by walking the resolution chain:
+ * 1. Per-resource operation override
+ * 2. Per-relationship inParentNavigation.transition
+ * 3. Global viewport override
+ * 4. Source zone's transitions[operation]
+ * 5. Framework fallback
+ */
+export interface NavigationResolutionResult {
+    /** Which zone the content should be placed in. */
+    targetZone: NavigationZone;
+    /** The transition verb to apply. */
+    transition: NavigationTransition;
+    /**
+     * Visual appearance for the transition. Only meaningful for:
+     * - `overlay` transitions: `OverlayAppearance` (dialog or sheet)
+     * - `split` transitions: `SplitAppearance` (panel or drawer)
+     * `undefined` for `push`, `replace`, `inplace`, and `promote`
+     * (`push`/`replace`/`promote` fill the zone; `inplace` transforms an element).
+     */
+    appearance?: OverlayAppearance | SplitAppearance;
+    /**
+     * Whether the target zone is currently in responsive collapse mode at this viewport.
+     * When `true`, the controller should apply the zone's `responsiveCollapse` behavior
+     * (push into primary or show as overlay) instead of normal zone rendering.
+     */
+    collapsed: boolean;
+    /**
+     * When `true`, this overlay entry should auto-close when its source zone's stack changes.
+     * Derived from `TransitionConfig.ephemeral`. Only meaningful for overlay transitions.
+     * The controller writes this to `NavigationStackEntry.ephemeral`.
+     */
+    ephemeral?: boolean;
+}
+/**
+ * Input to the navigation policy resolver — all the contextual signals needed
+ * to determine which transition + zone + appearance to use.
+ *
+ * Three fundamentally different source types select different config paths:
+ * - `NavigationZoneName`: structural zone → reads `layout.zones[zone].transitions`
+ * - `'appLevel'`: app shell (sidebar, command palette) → reads `layout.appLevel.transitions`
+ * - `'overlay'`: from within an overlay → reads `layout.fromOverlay.transitions`
+ */
+export interface NavigationResolutionContext {
+    /**
+     * Where the navigation was triggered from. Determines which config
+     * branch the resolver reads transitions from.
+     */
+    sourceZone: NavigationZoneName | typeof APP_LEVEL_NAVIGATION_SOURCE | 'overlay';
+    /** The operation being performed (read, create, list, update, etc.). */
+    operation: CoreResourceOperation | string;
+    /**
+     * Semantic core operation for custom operations that behave like a framework
+     * core surface. Transition maps are keyed by core semantics, so resolvers must
+     * use this field instead of raw custom operation identifiers.
+     */
+    effectiveOperation?: CoreResourceOperation;
+    /** Resource type being navigated to (for per-resource override matching). */
+    resourceType?: string;
+    /** Whether the target resource is URL-addressable. */
+    isAddressable?: boolean;
+    /** Per-resource operation overrides (from resource operationFrontendConfig). First match wins. */
+    operationOverrides?: NavigationOperationOverride[];
+    /**
+     * Full transition config from the relationship's
+     * `display.inParentNavigation.transition`.
+     * Preserves lifecycle modifiers (ephemeral/persistent). `undefined` when
+     * navigation is not relationship-driven.
+     */
+    relationshipTransition?: TransitionConfig;
+    /** Current viewport breakpoint for responsive resolution. */
+    viewport: ViewportBreakpoint;
+    /** Which structural zones currently have content. Used for SPLIT target heuristic. */
+    zoneOccupancy: Partial<Record<NavigationZoneName, boolean>>;
+    /** Currently focused zone — tiebreaker for SPLIT target selection. */
+    focusedZone?: NavigationZoneName;
+}
+/**
+ * Lightweight feature availability status attached to navigation items.
+ *
+ * Used by sidebar, command menu, and toolbar to communicate feature gating
+ * status to UI components (lock icons, disabled state, upgrade prompts).
+ * Subset of the full `FeatureAvailability` from the features system.
+ */
+export interface NavigationFeatureAvailability {
+    /** Whether the feature is currently available to the user. */
+    isAvailable: boolean;
+    /** Why the feature is unavailable (plan limit, not enabled, etc.). */
+    reason?: FeatureUnavailabilityReason;
+    /** How the UI should respond to unavailability (disable, hide, show upgrade). */
+    behavior: FeatureUnavailabilityBehavior;
+    /** Feature IDs that are missing/required for this item. */
+    missingFeatures?: string[];
+    /** Limit details when the feature is gated by usage limits. */
+    limitInfo?: {
+        featureId: string;
+        current: number;
+        limit: number;
+    };
+    /** Available upgrade options to unlock this feature. */
+    upgradeOptions?: FeatureUpgradeOption[];
+    /** Suggested product reference for upgrade CTAs. */
+    suggestedProductRef?: string;
+}
+/**
+ * Discriminator for navigation item variants.
+ * Navigation items appear in the sidebar, command menu, and toolbar.
+ */
+export declare enum NavigationItemType {
+    /** A navigable resource operation (list, read, create for a resource type). */
+    RESOURCE = "resource",
+    /** A navigable view (composite, chart, custom, flows/actors). */
+    VIEW = "view",
+    /** A navigable generic custom component. */
+    CUSTOM_COMPONENT = "custom_component"
+}
+/** Subset of `NavigationContentType` for view-based navigation items. */
+export type ViewNavigationContentType = NavigationContentType.COMPOSITE_VIEW | NavigationContentType.CHART_VIEW | NavigationContentType.FULL_CUSTOM_VIEW | NavigationContentType.FLOWS_ACTORS_VIEW | NavigationContentType.EXECUTION_VIEW;
+/**
+ * Shared fields across all navigation item variants.
+ * Populated by per-launcher resolution (`launcher-resolution.ts`) and behavior
+ * hooks from declared launcher content and resource/view definitions.
+ */
+export interface NavigationItemBase {
+    /** Unique identifier for this item (typically resourceType or viewRef based). */
+    id: string;
+    /** Stable reference for configuration matching (not display-specific). */
+    ref: string;
+    /** Display label for the item. */
+    label: string;
+    /** URL path for this item's destination. */
+    urlPath: string;
+    /** Optional icon React node for sidebar/toolbar rendering. */
+    icon?: React.ReactNode;
+    /** Section reference for grouping (e.g., 'main', 'tools', 'settings'). */
+    section?: string;
+    /** Sidebar display policy (always visible, collapsible, etc.). */
+    displayPolicy?: SidebarItemDisplayPolicy;
+    /** Badge reference for notification count display. */
+    badgeReference?: string;
+    /** Keyboard shortcut hint displayed in UI (e.g., "⌘K"). */
+    shortcut?: string;
+    /** Additional search keywords for command menu filtering. */
+    searchKeywords?: string[];
+    /** Parent item reference for hierarchical nesting in sidebar. */
+    parentItemRef?: string;
+    /** Whether this item has children and can be collapsed. */
+    isCollapsible?: boolean;
+    /** Category for command menu grouping. */
+    commandCategory?: string;
+    /** Whether to render as icon-only (no label) in compact modes. */
+    iconOnly?: boolean;
+    /** Whether this item is disabled (feature gating, permissions, etc.). */
+    disabled?: boolean;
+    /** Whether this item shows a lock indicator (feature-locked but visible). */
+    featureLocked?: boolean;
+    /** Feature availability details when `featureLocked` or `disabled` due to features. */
+    featureAvailability?: NavigationFeatureAvailability;
+}
+/**
+ * Resource navigation item — a navigable resource operation in app-level components.
+ * Discriminated by `itemType: NavigationItemType.RESOURCE`.
+ */
+export interface ResourceNavigationItem extends NavigationItemBase {
+    itemType: NavigationItemType.RESOURCE;
+    /** The resource type identifier (e.g., 'project', 'task'). */
+    resourceType: string;
+    /** The operation identifier within the resource config (e.g., 'list', 'create'). */
+    operationIdentifier: string;
+    /** The full operation configuration from the resource. */
+    operation: FrontendResourceConfiguration_Operation;
+    /** Pre-built resource context for navigation dispatch. */
+    resourceContext: FrontendResourceOperationContext;
+}
+/**
+ * View navigation item — a navigable view in app-level components.
+ * Discriminated by `itemType: NavigationItemType.VIEW`.
+ */
+export interface ViewNavigationItem extends NavigationItemBase {
+    itemType: NavigationItemType.VIEW;
+    /** View reference identifier. */
+    viewRef: string;
+    /** Content type for routing (composite, chart, custom, flows/actors). */
+    contentType: ViewNavigationContentType;
+    /** Optional context resource IDs carried with the app-level navigation payload. */
+    contextResourceIdentifiers?: Record<string, string>;
+    /** Optional chart-route query params for standalone chart URL_PARAM bindings. */
+    urlParamValues?: Record<string, string>;
+    /** FlowsActorsView: system references for the flows/actors displayed. */
+    flowsActorsSystemRefs?: string[];
+    /** FullCustomView: reference to the registered custom component. */
+    fullCustomComponentRef?: string;
+    /** Required features configuration for feature gating. */
+    requiredFeatures?: RequiredFeaturesConfig;
+}
+/** Generic custom-component navigation item — launcher escape hatch with explicit runtime meaning. */
+export interface CustomComponentNavigationItem extends NavigationItemBase {
+    itemType: NavigationItemType.CUSTOM_COMPONENT;
+    componentRef: string;
+    /** Optional context resource IDs carried with the app-level navigation payload. */
+    contextResourceIdentifiers?: Record<string, string>;
+}
+/** Discriminated union of all navigation items. Narrow on `itemType`. */
+export type AnyNavigationItem = ResourceNavigationItem | ViewNavigationItem | CustomComponentNavigationItem;
+/** Type guard — narrows `AnyNavigationItem` to `ResourceNavigationItem`. */
+export declare function isResourceNavigationItem(item: AnyNavigationItem): item is ResourceNavigationItem;
+/** Type guard — narrows `AnyNavigationItem` to `ViewNavigationItem`. */
+export declare function isViewNavigationItem(item: AnyNavigationItem): item is ViewNavigationItem;
+/** Type guard — narrows `AnyNavigationItem` to `CustomComponentNavigationItem`. */
+export declare function isCustomComponentNavigationItem(item: AnyNavigationItem): item is CustomComponentNavigationItem;
+/** Zod schema for `NavigationInitiatorContext` — validates navigation event source. */
+export declare const NavigationInitiatorContextSchema: z.ZodObject<{
+    sourceZone: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"overlay">]>, z.ZodLiteral<"appLevel">]>;
+    launcher: z.ZodOptional<z.ZodEnum<typeof ApplicationLevelComponentType>>;
+    sourceOperation: z.ZodOptional<z.ZodEnum<typeof CoreResourceOperation>>;
+    sourceRelationship: z.ZodOptional<z.ZodObject<{
+        parentResourceType: z.ZodString;
+        parentResourceId: z.ZodOptional<z.ZodString>;
+        childResourceType: z.ZodString;
+        foreignKeyField: z.ZodOptional<z.ZodString>;
+        relationshipEdgeKey: z.ZodOptional<z.ZodString>;
+        inChildView: z.ZodOptional<z.ZodObject<{
+            showParentLink: z.ZodOptional<z.ZodBoolean>;
+            parentDisplay: z.ZodOptional<z.ZodEnum<typeof ParentDisplay>>;
+        }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+/** Discriminated union schema for all navigation content types. */
+export declare const NavigationContentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.RESOURCE_OPERATION>;
+    resourceContext: z.ZodObject<{
+        resourceType: z.ZodString;
+        parentResourcesRequirements: z.ZodArray<z.ZodObject<{
+            resourceType: z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>;
+            foreignKeyField: z.ZodOptional<z.ZodString>;
+            childResourceType: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>>;
+            relationshipEdgeKey: z.ZodOptional<z.ZodString>;
+            requirement: z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourceParentResourceRequirement>;
+            isPrimaryScope: z.ZodBoolean;
+            primaryScope: z.ZodOptional<z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourcePrimaryScope>>;
+        }, z.core.$strip, core.$ZodObjectExtra>>;
+        operationIdentifier: z.ZodString;
+        isOperationDefault: z.ZodBoolean;
+        isBulkOperation: z.ZodBoolean;
+        variantKey: z.ZodOptional<z.ZodString>;
+        operation: z.ZodAny;
+        contextResourceIdentifiers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            fieldIdentifier: z.ZodString;
+            resourceId: z.ZodString;
+        }, z.core.$strip, core.$ZodObjectExtra>]>>;
+        additionalContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.COMPOSITE_VIEW>;
+    viewRef: z.ZodString;
+    contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.CHART_VIEW>;
+    viewRef: z.ZodString;
+    contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    urlParamValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    requiredFeatures: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+        features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            OR: "OR";
+            AND: "AND";
+        }>>;
+        limitChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            featureId: z.ZodString;
+            increment: z.ZodOptional<z.ZodNumber>;
+            countingOverride: z.ZodOptional<z.ZodObject<{
+                resourceType: z.ZodString;
+                filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                aggregate: z.ZodOptional<z.ZodObject<{
+                    field: z.ZodString;
+                    operation: z.ZodEnum<typeof import("@wildo-ai/saas-models").AggregationOperation>;
+                }, z.core.$strip, core.$ZodObjectExtra>>;
+            }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip, core.$ZodObjectExtra>]>>;
+    viewDefinition: z.ZodOptional<z.ZodCustom<InsertedChartDeclaration | ChartViewDefinition, InsertedChartDeclaration | ChartViewDefinition>>;
+    runtimeDescriptor: z.ZodOptional<z.ZodCustom<ResolvedInsertedChartDescriptor, ResolvedInsertedChartDescriptor>>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.FULL_CUSTOM_VIEW>;
+    viewRef: z.ZodString;
+    fullCustomComponentRef: z.ZodString;
+    contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.FLOWS_ACTORS_VIEW>;
+    viewRef: z.ZodString;
+    flowsActorsSystemRefs: z.ZodArray<z.ZodString>;
+    contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.EXECUTION_VIEW>;
+    viewRef: z.ZodString;
+    contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.CUSTOM_COMPONENT>;
+    componentRef: z.ZodString;
+    contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.ENGINE_PAGE>;
+    pageRef: z.ZodEnum<typeof EnginePageRef>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.INLINE_CREATE>;
+    resourceContext: z.ZodObject<{
+        resourceType: z.ZodString;
+        parentResourcesRequirements: z.ZodArray<z.ZodObject<{
+            resourceType: z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>;
+            foreignKeyField: z.ZodOptional<z.ZodString>;
+            childResourceType: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>>;
+            relationshipEdgeKey: z.ZodOptional<z.ZodString>;
+            requirement: z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourceParentResourceRequirement>;
+            isPrimaryScope: z.ZodBoolean;
+            primaryScope: z.ZodOptional<z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourcePrimaryScope>>;
+        }, z.core.$strip, core.$ZodObjectExtra>>;
+        operationIdentifier: z.ZodString;
+        isOperationDefault: z.ZodBoolean;
+        isBulkOperation: z.ZodBoolean;
+        variantKey: z.ZodOptional<z.ZodString>;
+        operation: z.ZodAny;
+        contextResourceIdentifiers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            fieldIdentifier: z.ZodString;
+            resourceId: z.ZodString;
+        }, z.core.$strip, core.$ZodObjectExtra>]>>;
+        additionalContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip, core.$ZodObjectExtra>;
+    defaultValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    contentType: z.ZodLiteral<NavigationContentType.ERROR_MODAL>;
+    errorType: z.ZodString;
+    message: z.ZodString;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    wildoError: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip, core.$ZodObjectExtra>], "contentType">;
+/** Zod schema for a single navigation stack entry — validates serialized navigation state. */
+export declare const NavigationStackEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    content: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.RESOURCE_OPERATION>;
+        resourceContext: z.ZodObject<{
+            resourceType: z.ZodString;
+            parentResourcesRequirements: z.ZodArray<z.ZodObject<{
+                resourceType: z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>;
+                foreignKeyField: z.ZodOptional<z.ZodString>;
+                childResourceType: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>>;
+                relationshipEdgeKey: z.ZodOptional<z.ZodString>;
+                requirement: z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourceParentResourceRequirement>;
+                isPrimaryScope: z.ZodBoolean;
+                primaryScope: z.ZodOptional<z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourcePrimaryScope>>;
+            }, z.core.$strip, core.$ZodObjectExtra>>;
+            operationIdentifier: z.ZodString;
+            isOperationDefault: z.ZodBoolean;
+            isBulkOperation: z.ZodBoolean;
+            variantKey: z.ZodOptional<z.ZodString>;
+            operation: z.ZodAny;
+            contextResourceIdentifiers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                fieldIdentifier: z.ZodString;
+                resourceId: z.ZodString;
+            }, z.core.$strip, core.$ZodObjectExtra>]>>;
+            additionalContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.COMPOSITE_VIEW>;
+        viewRef: z.ZodString;
+        contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.CHART_VIEW>;
+        viewRef: z.ZodString;
+        contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        urlParamValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        requiredFeatures: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+            features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                OR: "OR";
+                AND: "AND";
+            }>>;
+            limitChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                featureId: z.ZodString;
+                increment: z.ZodOptional<z.ZodNumber>;
+                countingOverride: z.ZodOptional<z.ZodObject<{
+                    resourceType: z.ZodString;
+                    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    aggregate: z.ZodOptional<z.ZodObject<{
+                        field: z.ZodString;
+                        operation: z.ZodEnum<typeof import("@wildo-ai/saas-models").AggregationOperation>;
+                    }, z.core.$strip, core.$ZodObjectExtra>>;
+                }, z.core.$strip, core.$ZodObjectExtra>>;
+            }, z.core.$strip, core.$ZodObjectExtra>>>;
+        }, z.core.$strip, core.$ZodObjectExtra>]>>;
+        viewDefinition: z.ZodOptional<z.ZodCustom<InsertedChartDeclaration | ChartViewDefinition, InsertedChartDeclaration | ChartViewDefinition>>;
+        runtimeDescriptor: z.ZodOptional<z.ZodCustom<ResolvedInsertedChartDescriptor, ResolvedInsertedChartDescriptor>>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.FULL_CUSTOM_VIEW>;
+        viewRef: z.ZodString;
+        fullCustomComponentRef: z.ZodString;
+        contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.FLOWS_ACTORS_VIEW>;
+        viewRef: z.ZodString;
+        flowsActorsSystemRefs: z.ZodArray<z.ZodString>;
+        contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.EXECUTION_VIEW>;
+        viewRef: z.ZodString;
+        contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.CUSTOM_COMPONENT>;
+        componentRef: z.ZodString;
+        contextResourceIdentifiers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.ENGINE_PAGE>;
+        pageRef: z.ZodEnum<typeof EnginePageRef>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.INLINE_CREATE>;
+        resourceContext: z.ZodObject<{
+            resourceType: z.ZodString;
+            parentResourcesRequirements: z.ZodArray<z.ZodObject<{
+                resourceType: z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>;
+                foreignKeyField: z.ZodOptional<z.ZodString>;
+                childResourceType: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").CoreResourceType>, z.ZodString]>>;
+                relationshipEdgeKey: z.ZodOptional<z.ZodString>;
+                requirement: z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourceParentResourceRequirement>;
+                isPrimaryScope: z.ZodBoolean;
+                primaryScope: z.ZodOptional<z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourcePrimaryScope>>;
+            }, z.core.$strip, core.$ZodObjectExtra>>;
+            operationIdentifier: z.ZodString;
+            isOperationDefault: z.ZodBoolean;
+            isBulkOperation: z.ZodBoolean;
+            variantKey: z.ZodOptional<z.ZodString>;
+            operation: z.ZodAny;
+            contextResourceIdentifiers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                fieldIdentifier: z.ZodString;
+                resourceId: z.ZodString;
+            }, z.core.$strip, core.$ZodObjectExtra>]>>;
+            additionalContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip, core.$ZodObjectExtra>;
+        defaultValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        contentType: z.ZodLiteral<NavigationContentType.ERROR_MODAL>;
+        errorType: z.ZodString;
+        message: z.ZodString;
+        context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        wildoError: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip, core.$ZodObjectExtra>], "contentType">;
+    urlPath: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodNumber;
+    zone: z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"overlay">]>;
+    initiator: z.ZodOptional<z.ZodObject<{
+        sourceZone: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"overlay">]>, z.ZodLiteral<"appLevel">]>;
+        launcher: z.ZodOptional<z.ZodEnum<typeof ApplicationLevelComponentType>>;
+        sourceOperation: z.ZodOptional<z.ZodEnum<typeof CoreResourceOperation>>;
+        sourceRelationship: z.ZodOptional<z.ZodObject<{
+            parentResourceType: z.ZodString;
+            parentResourceId: z.ZodOptional<z.ZodString>;
+            childResourceType: z.ZodString;
+            foreignKeyField: z.ZodOptional<z.ZodString>;
+            relationshipEdgeKey: z.ZodOptional<z.ZodString>;
+            inChildView: z.ZodOptional<z.ZodObject<{
+                showParentLink: z.ZodOptional<z.ZodBoolean>;
+                parentDisplay: z.ZodOptional<z.ZodEnum<typeof ParentDisplay>>;
+            }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+    navigationSource: z.ZodEnum<typeof NavigationSource>;
+    transition: z.ZodEnum<typeof NavigationTransition>;
+    appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>>;
+    ephemeral: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export {};
+//# sourceMappingURL=navigation.schemas.d.ts.map