@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/config/frontend/chart-registration-alignment.shared.js

@@ -0,0 +1,61 @@
+/** ──────────────────────────────────────────────────────────────
+ * Chart registration alignment (drift guard)
+ *
+ * A resource-owned chart must be wired on BOTH sides:
+ *   - FRONTEND: authored in `ResourceUIBehaviorConfig.chartViews[].chartDefinition`
+ *     (frontend-only — the backend cannot import it), and
+ *   - BACKEND: registered via `BackendDomainModule.chartDefinitions`, which feeds
+ *     the backend `ChartRegistry` so `POST /charts/:ref/data` can execute.
+ *
+ * A frontend chartView whose `chartDefinition.ref` has NO backend registration
+ * produces a silent runtime 404 (`chart_not_found`) — the host renders but the
+ * data fetch fails. This module is the pure, framework-general comparator that a
+ * build-time / CLI guard uses to catch that drift before it ships.
+ *
+ * ## Join key
+ * The comparison key is `chartView.chartDefinition.ref` (the execution ref the
+ * frontend runtime sends), NOT the outer `chartView.ref` (the view identity).
+ *
+ * This module is import-safe (pure functions + types, no frontend-lib /
+ * backend-lib deps) so it can run from the companion subprocess, a CLI audit,
+ * and unit tests alike.
+ * ────────────────────────────────────────────────────────────── */
+/**
+ * Normalize a chart execution reference to its canonical registry key. This is
+ * the SINGLE source of truth for ref normalization, shared by the backend
+ * `ChartRegistry` (registration + lookup) and this alignment guard, so the two
+ * can never diverge on whitespace and silently disagree about whether a chart is
+ * registered.
+ */
+export function normalizeChartExecutionRef(rawRef) {
+    return rawRef.trim();
+}
+/**
+ * Compare the set of frontend chartView refs against the set of backend-registered
+ * chart refs. Both sides are normalized via {@link normalizeChartExecutionRef}
+ * before comparison so whitespace never causes a phantom mismatch.
+ */
+export function computeChartRegistrationAlignment(params) {
+    const normalizedBackend = params.backendRegisteredRefs.map(normalizeChartExecutionRef);
+    const backendSet = new Set(normalizedBackend);
+    const frontendSet = new Set(params.frontendChartRefs.map((r) => normalizeChartExecutionRef(r.chartDefinitionRef)));
+    const unregisteredFrontendCharts = params.frontendChartRefs.filter((r) => !backendSet.has(normalizeChartExecutionRef(r.chartDefinitionRef)));
+    const orphanBackendCharts = [
+        ...new Set(normalizedBackend.filter((ref) => !frontendSet.has(ref))),
+    ];
+    return { unregisteredFrontendCharts, orphanBackendCharts };
+}
+/**
+ * Throw a verbose, locatable error if any frontend chartView is unregistered
+ * backend-side. Only the FAIL channel throws; `orphanBackendCharts` (WARN) never
+ * throws. Use in the `--strict` path of the CLI audit / a CI gate.
+ */
+export function assertChartRegistrationAligned(report, errorPrefix = 'ChartRegistrationAlignment') {
+    if (report.unregisteredFrontendCharts.length === 0)
+        return;
+    const lines = report.unregisteredFrontendCharts.map((r) => `  - ${r.resourceType}.${r.chartViewRef} → chartDefinition.ref '${r.chartDefinitionRef}' has no backend chartDefinitions registration`);
+    throw new Error(`${errorPrefix}: ${report.unregisteredFrontendCharts.length} chart view(s) reference a chart that is NOT registered backend-side (each would 404 with chart_not_found at runtime):\n` +
+        `${lines.join('\n')}\n` +
+        `Fix: add the shared ChartDefinition to the owning backend module's \`chartDefinitions\` array.`);
+}
+//# sourceMappingURL=chart-registration-alignment.shared.js.map

package/dist/esm/config/frontend/chart-registration-alignment.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-registration-alignment.shared.js","sourceRoot":"","sources":["../../../../../src/config/frontend/chart-registration-alignment.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;oEAqBoE;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AA2BD;;;;GAIG;AACH,MAAM,UAAU,iCAAiC,CAAC,MAGjD;IACC,MAAM,iBAAiB,GAAG,MAAM,CAAC,qBAAqB,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;IACvF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,0BAA0B,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CACtF,CAAC;IAEF,MAAM,0BAA0B,GAAG,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAChE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CACzE,CAAC;IAEF,MAAM,mBAAmB,GAAG;QAC1B,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;KACrE,CAAC;IAEF,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAwC,EACxC,WAAW,GAAG,4BAA4B;IAE1C,IAAI,MAAM,CAAC,0BAA0B,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,0BAA0B,CAAC,GAAG,CACjD,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,2BAA2B,CAAC,CAAC,kBAAkB,gDAAgD,CACzI,CAAC;IACF,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,KAAK,MAAM,CAAC,0BAA0B,CAAC,MAAM,0HAA0H;QACnL,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACvB,gGAAgG,CACnG,CAAC;AACJ,CAAC","sourcesContent":["/** ──────────────────────────────────────────────────────────────\n * Chart registration alignment (drift guard)\n *\n * A resource-owned chart must be wired on BOTH sides:\n *   - FRONTEND: authored in `ResourceUIBehaviorConfig.chartViews[].chartDefinition`\n *     (frontend-only — the backend cannot import it), and\n *   - BACKEND: registered via `BackendDomainModule.chartDefinitions`, which feeds\n *     the backend `ChartRegistry` so `POST /charts/:ref/data` can execute.\n *\n * A frontend chartView whose `chartDefinition.ref` has NO backend registration\n * produces a silent runtime 404 (`chart_not_found`) — the host renders but the\n * data fetch fails. This module is the pure, framework-general comparator that a\n * build-time / CLI guard uses to catch that drift before it ships.\n *\n * ## Join key\n * The comparison key is `chartView.chartDefinition.ref` (the execution ref the\n * frontend runtime sends), NOT the outer `chartView.ref` (the view identity).\n *\n * This module is import-safe (pure functions + types, no frontend-lib /\n * backend-lib deps) so it can run from the companion subprocess, a CLI audit,\n * and unit tests alike.\n * ────────────────────────────────────────────────────────────── */\n\n/**\n * Normalize a chart execution reference to its canonical registry key. This is\n * the SINGLE source of truth for ref normalization, shared by the backend\n * `ChartRegistry` (registration + lookup) and this alignment guard, so the two\n * can never diverge on whitespace and silently disagree about whether a chart is\n * registered.\n */\nexport function normalizeChartExecutionRef(rawRef: string): string {\n  return rawRef.trim();\n}\n\n/** One frontend chartView's registration identity (the drift-guard input). */\nexport interface FrontendChartRegistrationRef {\n  /** `chartView.chartDefinition.ref` — the execution/registry join key. */\n  chartDefinitionRef: string;\n  /** The resource type whose ui-behavior authored this chartView. */\n  resourceType: string;\n  /** `chartView.ref` — the view identity (for a precise, locatable error). */\n  chartViewRef: string;\n}\n\n/** The two-channel drift report. */\nexport interface ChartRegistrationAlignmentReport {\n  /**\n   * Frontend chartViews whose `chartDefinition.ref` has NO backend registration.\n   * FAIL channel — each one is a guaranteed runtime 404.\n   */\n  unregisteredFrontendCharts: FrontendChartRegistrationRef[];\n  /**\n   * Backend-registered chart refs referenced by NO frontend chartView. WARN\n   * channel — a backend-only chart is valid (e.g. a programmatic/API-only chart\n   * consumed directly via `/charts/:ref/data`), so this is never a hard failure.\n   */\n  orphanBackendCharts: string[];\n}\n\n/**\n * Compare the set of frontend chartView refs against the set of backend-registered\n * chart refs. Both sides are normalized via {@link normalizeChartExecutionRef}\n * before comparison so whitespace never causes a phantom mismatch.\n */\nexport function computeChartRegistrationAlignment(params: {\n  frontendChartRefs: FrontendChartRegistrationRef[];\n  backendRegisteredRefs: string[];\n}): ChartRegistrationAlignmentReport {\n  const normalizedBackend = params.backendRegisteredRefs.map(normalizeChartExecutionRef);\n  const backendSet = new Set(normalizedBackend);\n  const frontendSet = new Set(\n    params.frontendChartRefs.map((r) => normalizeChartExecutionRef(r.chartDefinitionRef)),\n  );\n\n  const unregisteredFrontendCharts = params.frontendChartRefs.filter(\n    (r) => !backendSet.has(normalizeChartExecutionRef(r.chartDefinitionRef)),\n  );\n\n  const orphanBackendCharts = [\n    ...new Set(normalizedBackend.filter((ref) => !frontendSet.has(ref))),\n  ];\n\n  return { unregisteredFrontendCharts, orphanBackendCharts };\n}\n\n/**\n * Throw a verbose, locatable error if any frontend chartView is unregistered\n * backend-side. Only the FAIL channel throws; `orphanBackendCharts` (WARN) never\n * throws. Use in the `--strict` path of the CLI audit / a CI gate.\n */\nexport function assertChartRegistrationAligned(\n  report: ChartRegistrationAlignmentReport,\n  errorPrefix = 'ChartRegistrationAlignment',\n): void {\n  if (report.unregisteredFrontendCharts.length === 0) return;\n  const lines = report.unregisteredFrontendCharts.map(\n    (r) =>\n      `  - ${r.resourceType}.${r.chartViewRef} → chartDefinition.ref '${r.chartDefinitionRef}' has no backend chartDefinitions registration`,\n  );\n  throw new Error(\n    `${errorPrefix}: ${report.unregisteredFrontendCharts.length} chart view(s) reference a chart that is NOT registered backend-side (each would 404 with chart_not_found at runtime):\\n` +\n      `${lines.join('\\n')}\\n` +\n      `Fix: add the shared ChartDefinition to the owning backend module's \\`chartDefinitions\\` array.`,\n  );\n}\n"]}

package/dist/esm/config/frontend/navigation.shared.schemas.d.ts

@@ -23,7 +23,7 @@
  */
 import { z } from 'zod';
 import { ViewportBreakpoint, DisplayDirection } from '@wildo-ai/zod-decorators';
-import { CoreResourceOperation } from '../../resources/resources.shared.core.definitions.js';
+import { CoreResourceOperation } from '../../resources/resources.shared.core.definitions';
 /**
  * Navigation transition verbs — HOW content arrives at its destination.
  *
@@ -59,7 +59,7 @@ export declare enum NavigationTransition {
      */
     SPLIT = "split",
     /**
-     * Content opens in a floating layer above the entire layout (dialog or sheet).
+     * Content opens in a floating layer above the entire layout (dialog, sheet, or drawer).
      * The underlying layout remains visible but non-interactive.
      * Back navigation or Escape dismisses the overlay.
      * URL adds an overlay param/hash.
@@ -67,9 +67,9 @@ export declare enum 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.
+     * list/section transforms from one mode to another (read → edit); a CREATE
+     * materializes a new element beside the existing ones. The parent view stays,
+     * the zone stack is unchanged, and surrounding items remain visible.
      *
      * Fundamentally different from `replace` (which swaps the entire zone content).
      * `inplace` operates at the element level, not the zone level.
@@ -77,8 +77,21 @@ export declare enum NavigationTransition {
      * 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>`).
+     * **It is the one transition that does not place content in a zone**, which is
+     * why the controller hands it to the element-level host
+     * (`InPlaceOperationContext`) instead of resolving a target zone for it. That
+     * host is provided by the COLLECTION the element belongs to, so a transition
+     * resolving to `inplace` on a surface with no collection above it — a detail
+     * page, a breadcrumb, a picker — degrades to an OVERLAY.
+     *
+     * **It is TRANSIENT: no URL, and a reload returns the view to rest.** Earlier
+     * revisions of this comment promised a query param (`?editing=<childId>` /
+     * `?creating=<resourceType>`) and none was ever written. It is not written now
+     * either, and that is a decision rather than an omission: an inline row-edit is
+     * a momentary state of a listing, not a place — no comparable admin framework
+     * deep-links one, and anything that should survive a reload or a back button
+     * wants `push`. `ResourceOperationActionPresentation.INLINE`, the per-operation
+     * tier that selects the same host, is transient for the same reason.
      *
      * @example
      * // Click "edit" on a child in parent's inline section → item transforms to edit form
@@ -220,7 +233,13 @@ export declare enum OverlayAppearance {
      * Best for contextual content that benefits from seeing the underlying layout.
      * Less disruptive than dialog. Common for detail views on mobile.
      */
-    SHEET = "sheet"
+    SHEET = "sheet",
+    /**
+     * Vaul-backed mobile drawer.
+     * Use when the navigation resolver should choose a drawer directly rather
+     * than relying on a dialog appearance plus mobileShape policy.
+     */
+    DRAWER = "drawer"
 }
 /**
  * Visual presentation for split transitions.
@@ -254,8 +273,8 @@ export declare enum SplitAppearance {
  * // Viewport-discriminated — different per breakpoint
  * responsiveCollapse: { [ViewportBreakpoint.VERT_TABLET]: ResponsiveCollapseMode.PUSH, [ViewportBreakpoint.MOBILE]: ResponsiveCollapseMode.OVERLAY }
  *
- * // Overlay appearance — sheet on tablet, dialog on mobile
- * overlay: { [ViewportBreakpoint.VERT_TABLET]: OverlayAppearance.SHEET, [ViewportBreakpoint.MOBILE]: OverlayAppearance.DIALOG }
+ * // Overlay appearance — sheet on tablet, drawer on mobile
+ * overlay: { [ViewportBreakpoint.VERT_TABLET]: OverlayAppearance.SHEET, [ViewportBreakpoint.MOBILE]: OverlayAppearance.DRAWER }
  */
 export type ViewportDiscriminated<T> = T | Partial<Record<ViewportBreakpoint, T>>;
 /**
@@ -291,7 +310,7 @@ export declare const TransitionObjectSchema: z.ZodObject<{
     transition: z.ZodEnum<typeof NavigationTransition>;
     persistent: z.ZodOptional<z.ZodBoolean>;
     ephemeral: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type TransitionObject = z.infer<typeof TransitionObjectSchema>;
 /**
  * A transition configuration: either a simple verb string or an object with modifiers.
@@ -307,7 +326,7 @@ export declare const TransitionConfigSchema: z.ZodUnion<readonly [z.ZodEnum<type
     transition: z.ZodEnum<typeof NavigationTransition>;
     persistent: z.ZodOptional<z.ZodBoolean>;
     ephemeral: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip, core.$ZodObjectExtra>]>;
+}, z.core.$strip>]>;
 export type TransitionConfig = z.infer<typeof TransitionConfigSchema>;
 /**
  * Operation → transition mapping for a zone.
@@ -348,13 +367,13 @@ export type ZoneTransitions = Partial<Record<CoreResourceOperation, TransitionCo
  * @example
  * appearance: {
  *   split:   SplitAppearance.PANEL,                                                       // always side panel
- *   overlay: { [ViewportBreakpoint.VERT_TABLET]: OverlayAppearance.SHEET, [ViewportBreakpoint.MOBILE]: OverlayAppearance.DIALOG },   // sheet on tablet, dialog on mobile
+ *   overlay: { [ViewportBreakpoint.VERT_TABLET]: OverlayAppearance.SHEET, [ViewportBreakpoint.MOBILE]: OverlayAppearance.DRAWER },   // sheet on tablet, drawer on mobile
  * }
  */
 export declare const ZoneAppearanceSchema: z.ZodObject<{
     split: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof SplitAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof SplitAppearance>>]>>;
     overlay: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ZoneAppearance = z.infer<typeof ZoneAppearanceSchema>;
 /**
  * Full zone configuration.
@@ -382,13 +401,13 @@ export declare const ZoneConfigSchema: z.ZodObject<{
     appearance: z.ZodOptional<z.ZodObject<{
         split: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof SplitAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof SplitAppearance>>]>>;
         overlay: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     minWidth: z.ZodOptional<z.ZodNumber>;
     maxWidth: z.ZodOptional<z.ZodNumber>;
     defaultVisible: z.ZodOptional<z.ZodBoolean>;
     onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
     responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ZoneConfig = z.infer<typeof ZoneConfigSchema>;
 /**
  * App-level navigation configuration: from OUTSIDE the zone system.
@@ -424,11 +443,11 @@ export declare const AppLevelConfigSchema: z.ZodObject<{
     appearance: z.ZodOptional<z.ZodObject<{
         split: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof SplitAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof SplitAppearance>>]>>;
         overlay: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export type AppLevelConfig = z.infer<typeof AppLevelConfigSchema>;
 /**
- * Navigation from within an overlay (dialog or sheet).
+ * Navigation from within an overlay (dialog, sheet, or drawer).
  *
  * When already in an overlay, transitions behave differently to avoid
  * nesting overlays. Typically all operations `push` within the overlay's
@@ -456,7 +475,7 @@ export declare const FromOverlayConfigSchema: z.ZodObject<{
         persistent?: boolean;
         ephemeral?: boolean;
     }>>, unknown>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type FromOverlayConfig = z.infer<typeof FromOverlayConfigSchema>;
 /**
  * Companion-specific split geometry.
@@ -466,7 +485,7 @@ export declare const CompanionSplitConfigSchema: z.ZodObject<{
     ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
     orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
     resizable: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type CompanionSplitConfig = z.infer<typeof CompanionSplitConfigSchema>;
 /**
  * Top-level split geometry — describes the physical relationship between zones.
@@ -496,8 +515,8 @@ export declare const SplitConfigSchema: z.ZodObject<{
         ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
         orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
         resizable: z.ZodDefault<z.ZodBoolean>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export type SplitConfig = z.infer<typeof SplitConfigSchema>;
 /**
  * Global viewport override — applies across ALL zones at a given breakpoint.
@@ -525,9 +544,11 @@ export declare const ViewportOverrideSchema: z.ZodObject<{
         persistent?: boolean;
         ephemeral?: boolean;
     }>>, unknown>>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ViewportOverride = z.infer<typeof ViewportOverrideSchema>;
 /**
+ * @wildo_source:part:start saas.models.navigation.layout facet:layer:shared facet:family:navigation-config
+ *
  * The complete navigation layout configuration for an application.
  *
  * This is the single configuration object that defines the entire navigation
@@ -553,6 +574,54 @@ export type ViewportOverride = z.infer<typeof ViewportOverrideSchema>;
  *   maxDepth: 2,
  * };
  */
+/**
+ * WHICH LAYER OWNS THE BACK AFFORDANCE.
+ *
+ * Two layers can render a back control for the same navigation stack: the app
+ * SHELL (the menubar's hosted navigation control) and the current SURFACE (a
+ * resource/view header, beside the icon + title + breadcrumb). Both mount the
+ * same component, so without an explicit owner an app that hosts the shell
+ * control gets TWO back arrows on every pushed page — one floating in the bar
+ * with no context, one attached to the thing it goes back from.
+ *
+ * This is deliberately a POLICY rather than a per-surface flag: "who owns this
+ * chrome" is one application-wide decision, and expressing it as an owner makes
+ * the duplication unrepresentable instead of asking every surface to remember
+ * to suppress itself.
+ */
+export declare enum NavigationBackAffordanceOwner {
+    /**
+     * The current surface's own header owns it — the back control sits beside the
+     * surface's icon/title/breadcrumb, so it reads as "back from THIS". The shell
+     * control renders nothing even when hosted. Default: it keeps the affordance
+     * attached to its context, and matches the shell staying free of a lone,
+     * context-free arrow.
+     */
+    SURFACE = "surface",
+    /**
+     * The app shell's navigation control owns it — one fixed back control in the
+     * menubar (the Notion-style top-left placement). Surface headers render none.
+     * Requires the shell to actually host `NAVIGATION_CONTROL`; if it does not,
+     * the application has no back affordance at all.
+     */
+    SHELL = "shell",
+    /**
+     * BOTH layers render one. An explicit opt-in for layouts where the two
+     * genuinely differ — e.g. a multi-zone shell whose bar control pops the
+     * focused zone while each zone's header pops its own stack. Chosen
+     * deliberately; never a default.
+     */
+    BOTH = "both"
+}
+/** Default owner when a layout declares none — see {@link NavigationBackAffordanceOwner.SURFACE}. */
+export declare const DEFAULT_NAVIGATION_BACK_AFFORDANCE_OWNER: NavigationBackAffordanceOwner;
+/**
+ * Does `owner` grant the SHELL (menubar navigation control) a back affordance?
+ * Shared by both render sites so the two can never disagree about one policy.
+ */
+export declare function navigationBackAffordanceAdmitsShell(owner: NavigationBackAffordanceOwner | undefined): boolean;
+/** Does `owner` grant the current SURFACE's header a back affordance? */
+export declare function navigationBackAffordanceAdmitsSurface(owner: NavigationBackAffordanceOwner | undefined): boolean;
 export declare const NavigationLayoutSchema: z.ZodObject<{
     zones: z.ZodObject<{
         primary: z.ZodObject<{
@@ -569,13 +638,13 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             appearance: z.ZodOptional<z.ZodObject<{
                 split: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof SplitAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof SplitAppearance>>]>>;
                 overlay: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
-            }, z.core.$strip, core.$ZodObjectExtra>>;
+            }, z.core.$strip>>;
             minWidth: z.ZodOptional<z.ZodNumber>;
             maxWidth: z.ZodOptional<z.ZodNumber>;
             defaultVisible: z.ZodOptional<z.ZodBoolean>;
             onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
             responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
-        }, z.core.$strip, core.$ZodObjectExtra>;
+        }, z.core.$strip>;
         secondary: z.ZodOptional<z.ZodObject<{
             contentModel: z.ZodDefault<z.ZodEnum<typeof NavigationZoneContentModel>>;
             transitions: z.ZodType<Partial<Record<CoreResourceOperation, NavigationTransition | {
@@ -590,13 +659,13 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             appearance: z.ZodOptional<z.ZodObject<{
                 split: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof SplitAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof SplitAppearance>>]>>;
                 overlay: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
-            }, z.core.$strip, core.$ZodObjectExtra>>;
+            }, z.core.$strip>>;
             minWidth: z.ZodOptional<z.ZodNumber>;
             maxWidth: z.ZodOptional<z.ZodNumber>;
             defaultVisible: z.ZodOptional<z.ZodBoolean>;
             onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
             responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
         companion: z.ZodOptional<z.ZodObject<{
             contentModel: z.ZodDefault<z.ZodEnum<typeof NavigationZoneContentModel>>;
             transitions: z.ZodType<Partial<Record<CoreResourceOperation, NavigationTransition | {
@@ -611,14 +680,14 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             appearance: z.ZodOptional<z.ZodObject<{
                 split: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof SplitAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof SplitAppearance>>]>>;
                 overlay: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
-            }, z.core.$strip, core.$ZodObjectExtra>>;
+            }, z.core.$strip>>;
             minWidth: z.ZodOptional<z.ZodNumber>;
             maxWidth: z.ZodOptional<z.ZodNumber>;
             defaultVisible: z.ZodOptional<z.ZodBoolean>;
             onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
             responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     appLevel: z.ZodOptional<z.ZodObject<{
         transitions: z.ZodType<Partial<Record<CoreResourceOperation, NavigationTransition | {
             transition: NavigationTransition;
@@ -632,8 +701,8 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
         appearance: z.ZodOptional<z.ZodObject<{
             split: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof SplitAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof SplitAppearance>>]>>;
             overlay: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     fromOverlay: z.ZodOptional<z.ZodObject<{
         transitions: z.ZodType<Partial<Record<CoreResourceOperation, NavigationTransition | {
             transition: NavigationTransition;
@@ -644,7 +713,7 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             persistent?: boolean;
             ephemeral?: boolean;
         }>>, unknown>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     split: z.ZodOptional<z.ZodObject<{
         autoSplit: z.ZodDefault<z.ZodBoolean>;
         ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
@@ -654,9 +723,10 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
             orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
             resizable: z.ZodDefault<z.ZodBoolean>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     maxDepth: z.ZodOptional<z.ZodNumber>;
+    backAffordanceOwner: z.ZodOptional<z.ZodEnum<typeof NavigationBackAffordanceOwner>>;
     "<md": z.ZodOptional<z.ZodObject<{
         transitions: z.ZodOptional<z.ZodType<Partial<Record<CoreResourceOperation, NavigationTransition | {
             transition: NavigationTransition;
@@ -667,7 +737,7 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             persistent?: boolean;
             ephemeral?: boolean;
         }>>, unknown>>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     "<lg": z.ZodOptional<z.ZodObject<{
         transitions: z.ZodOptional<z.ZodType<Partial<Record<CoreResourceOperation, NavigationTransition | {
             transition: NavigationTransition;
@@ -678,7 +748,8 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             persistent?: boolean;
             ephemeral?: boolean;
         }>>, unknown>>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export type NavigationLayout = z.infer<typeof NavigationLayoutSchema>;
+/** @wildo_source:part:end saas.models.navigation.layout */
 //# sourceMappingURL=navigation.shared.schemas.d.ts.map

package/dist/esm/config/frontend/navigation.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/config/frontend/navigation.shared.schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"navigation.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/config/frontend/navigation.shared.schemas.ts"],"names":[],"mappings":"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"}

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

@@ -63,7 +63,7 @@ export var NavigationTransition;
      */
     NavigationTransition["SPLIT"] = "split";
     /**
-     * Content opens in a floating layer above the entire layout (dialog or sheet).
+     * Content opens in a floating layer above the entire layout (dialog, sheet, or drawer).
      * The underlying layout remains visible but non-interactive.
      * Back navigation or Escape dismisses the overlay.
      * URL adds an overlay param/hash.
@@ -71,9 +71,9 @@ export var NavigationTransition;
     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.
+     * list/section transforms from one mode to another (read → edit); a CREATE
+     * materializes a new element beside the existing ones. The parent view stays,
+     * the zone stack is unchanged, and surrounding items remain visible.
      *
      * Fundamentally different from `replace` (which swaps the entire zone content).
      * `inplace` operates at the element level, not the zone level.
@@ -81,8 +81,21 @@ export var NavigationTransition;
      * 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>`).
+     * **It is the one transition that does not place content in a zone**, which is
+     * why the controller hands it to the element-level host
+     * (`InPlaceOperationContext`) instead of resolving a target zone for it. That
+     * host is provided by the COLLECTION the element belongs to, so a transition
+     * resolving to `inplace` on a surface with no collection above it — a detail
+     * page, a breadcrumb, a picker — degrades to an OVERLAY.
+     *
+     * **It is TRANSIENT: no URL, and a reload returns the view to rest.** Earlier
+     * revisions of this comment promised a query param (`?editing=<childId>` /
+     * `?creating=<resourceType>`) and none was ever written. It is not written now
+     * either, and that is a decision rather than an omission: an inline row-edit is
+     * a momentary state of a listing, not a place — no comparable admin framework
+     * deep-links one, and anything that should survive a reload or a back button
+     * wants `push`. `ResourceOperationActionPresentation.INLINE`, the per-operation
+     * tier that selects the same host, is transient for the same reason.
      *
      * @example
      * // Click "edit" on a child in parent's inline section → item transforms to edit form
@@ -230,6 +243,12 @@ export var OverlayAppearance;
      * Less disruptive than dialog. Common for detail views on mobile.
      */
     OverlayAppearance["SHEET"] = "sheet";
+    /**
+     * Vaul-backed mobile drawer.
+     * Use when the navigation resolver should choose a drawer directly rather
+     * than relying on a dialog appearance plus mobileShape policy.
+     */
+    OverlayAppearance["DRAWER"] = "drawer";
 })(OverlayAppearance || (OverlayAppearance = {}));
 /**
  * Visual presentation for split transitions.
@@ -369,7 +388,7 @@ export const ZoneTransitionsSchema = z.partialRecord(z.enum(CoreResourceOperatio
  * @example
  * appearance: {
  *   split:   SplitAppearance.PANEL,                                                       // always side panel
- *   overlay: { [ViewportBreakpoint.VERT_TABLET]: OverlayAppearance.SHEET, [ViewportBreakpoint.MOBILE]: OverlayAppearance.DIALOG },   // sheet on tablet, dialog on mobile
+ *   overlay: { [ViewportBreakpoint.VERT_TABLET]: OverlayAppearance.SHEET, [ViewportBreakpoint.MOBILE]: OverlayAppearance.DRAWER },   // sheet on tablet, drawer on mobile
  * }
  */
 export const ZoneAppearanceSchema = z.object({
@@ -473,7 +492,7 @@ export const AppLevelConfigSchema = z.object({
     appearance: ZoneAppearanceSchema.optional(),
 });
 /**
- * Navigation from within an overlay (dialog or sheet).
+ * Navigation from within an overlay (dialog, sheet, or drawer).
  *
  * When already in an overlay, transitions behave differently to avoid
  * nesting overlays. Typically all operations `push` within the overlay's
@@ -602,6 +621,8 @@ export const ViewportOverrideSchema = z.object({
 // NavigationLayout — Top-Level App Configuration
 // ════════════════════════════════════════════════════════════════
 /**
+ * @wildo_source:part:start saas.models.navigation.layout facet:layer:shared facet:family:navigation-config
+ *
  * The complete navigation layout configuration for an application.
  *
  * This is the single configuration object that defines the entire navigation
@@ -627,6 +648,61 @@ export const ViewportOverrideSchema = z.object({
  *   maxDepth: 2,
  * };
  */
+/**
+ * WHICH LAYER OWNS THE BACK AFFORDANCE.
+ *
+ * Two layers can render a back control for the same navigation stack: the app
+ * SHELL (the menubar's hosted navigation control) and the current SURFACE (a
+ * resource/view header, beside the icon + title + breadcrumb). Both mount the
+ * same component, so without an explicit owner an app that hosts the shell
+ * control gets TWO back arrows on every pushed page — one floating in the bar
+ * with no context, one attached to the thing it goes back from.
+ *
+ * This is deliberately a POLICY rather than a per-surface flag: "who owns this
+ * chrome" is one application-wide decision, and expressing it as an owner makes
+ * the duplication unrepresentable instead of asking every surface to remember
+ * to suppress itself.
+ */
+export var NavigationBackAffordanceOwner;
+(function (NavigationBackAffordanceOwner) {
+    /**
+     * The current surface's own header owns it — the back control sits beside the
+     * surface's icon/title/breadcrumb, so it reads as "back from THIS". The shell
+     * control renders nothing even when hosted. Default: it keeps the affordance
+     * attached to its context, and matches the shell staying free of a lone,
+     * context-free arrow.
+     */
+    NavigationBackAffordanceOwner["SURFACE"] = "surface";
+    /**
+     * The app shell's navigation control owns it — one fixed back control in the
+     * menubar (the Notion-style top-left placement). Surface headers render none.
+     * Requires the shell to actually host `NAVIGATION_CONTROL`; if it does not,
+     * the application has no back affordance at all.
+     */
+    NavigationBackAffordanceOwner["SHELL"] = "shell";
+    /**
+     * BOTH layers render one. An explicit opt-in for layouts where the two
+     * genuinely differ — e.g. a multi-zone shell whose bar control pops the
+     * focused zone while each zone's header pops its own stack. Chosen
+     * deliberately; never a default.
+     */
+    NavigationBackAffordanceOwner["BOTH"] = "both";
+})(NavigationBackAffordanceOwner || (NavigationBackAffordanceOwner = {}));
+/** Default owner when a layout declares none — see {@link NavigationBackAffordanceOwner.SURFACE}. */
+export const DEFAULT_NAVIGATION_BACK_AFFORDANCE_OWNER = NavigationBackAffordanceOwner.SURFACE;
+/**
+ * Does `owner` grant the SHELL (menubar navigation control) a back affordance?
+ * Shared by both render sites so the two can never disagree about one policy.
+ */
+export function navigationBackAffordanceAdmitsShell(owner) {
+    const resolved = owner ?? DEFAULT_NAVIGATION_BACK_AFFORDANCE_OWNER;
+    return resolved === NavigationBackAffordanceOwner.SHELL || resolved === NavigationBackAffordanceOwner.BOTH;
+}
+/** Does `owner` grant the current SURFACE's header a back affordance? */
+export function navigationBackAffordanceAdmitsSurface(owner) {
+    const resolved = owner ?? DEFAULT_NAVIGATION_BACK_AFFORDANCE_OWNER;
+    return resolved === NavigationBackAffordanceOwner.SURFACE || resolved === NavigationBackAffordanceOwner.BOTH;
+}
 export const NavigationLayoutSchema = z.object({
     /**
      * Zone declarations. Primary is required, secondary and companion are optional.
@@ -659,6 +735,13 @@ export const NavigationLayoutSchema = z.object({
      * Prevents infinitely deep navigation stacks. Per-relationship `maxDepth` can override.
      */
     maxDepth: z.number().int().positive().optional(),
+    /**
+     * Which layer renders the back control — see {@link NavigationBackAffordanceOwner}.
+     * Omitted means {@link DEFAULT_NAVIGATION_BACK_AFFORDANCE_OWNER} (the surface's
+     * own header), which is what keeps a shell that hosts `NAVIGATION_CONTROL`
+     * from rendering a second, context-free back arrow beside every page's own.
+     */
+    backAffordanceOwner: z.enum(NavigationBackAffordanceOwner).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).
@@ -670,9 +753,10 @@ export const NavigationLayoutSchema = z.object({
      */
     [ViewportBreakpoint.VERT_TABLET]: ViewportOverrideSchema.optional(),
 });
+/** @wildo_source:part:end saas.models.navigation.layout */
 // ════════════════════════════════════════════════════════════════
 // Per-Resource Operation Override
 // ════════════════════════════════════════════════════════════════
 // DELETED — NavigationOperationOverrideSchema and NavigationOperationOverride
 // Transferred to @wildo-ai/saas-frontend-lib (resources.frontend.schemas)
-//# sourceMappingURL=navigation.shared.schemas.js.map
+//# sourceMappingURL=navigation.shared.schemas.js.map