@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/resources/resources.frontend.schemas.d.ts

@@ -1,24 +1,36 @@
 import type React from 'react';
 import { z } from "zod";
 import type { EnumLikeType, IconLike, AutosaveFieldParams, ValidationMode, ResponsiveAware, EditChromeMode, DisplayChromeMode, DraftableConfigParams } from '@wildo-ai/zod-decorators';
-import type { QuickSwitcherScopeField } from '../../core/config/app-configuration-frontend.schemas.js';
-import { ResourceParentResourceRequirement, ResourcePrimaryScope, ResourceRelationship, ResourceTranspositionPolicy, CoreResourceOperation, ResourceFieldIdentifier, ResourceType, ResourceConfiguration_Operation_ApiCall, ResourceConfiguration_Operation_ApiCallWithCallback, ResourceConfiguration_ResourceRelationships, ResourceConfiguration_InheritanceSchemaDefinition, TourStepPlacement, NavigationZoneName, OverlayAppearance, SplitAppearance } from '@wildo-ai/saas-models';
-import type { ResourceConfiguration, ResourceConfiguration_InitializationFactory, ValidOperationKeys, RelationshipDisplayInParentView, RelationshipDisplayInParentNavigation, RelationshipDisplayInChildView } from '@wildo-ai/saas-models';
-import type { InsertedChartDeclaration } from '../../core/config/chart-view.frontend.schemas.js';
-import type { InsertedExecutionDeclaration, ResourceExecutionViewsConfig } from '../../core/config/execution-view.schemas.js';
-import type { OnboardingElementType, GuidanceRenderMode, GuidanceFlowScope, GuidanceAudience, NotificationBadgeDefinition, UserNotificationDefinition, SubtreeMap } from '@wildo-ai/saas-models';
-import { ViewportBreakpoint } from '@wildo-ai/zod-decorators';
-import type { CompositeViewComponentProps, InsertedCompositeDeclaration } from '../config/composite-view.schemas.js';
+import type { ButtonVariants_Variant } from '../../components/actions/button';
+import type { QuickSwitcherScopeField } from '../../core/config/app-configuration-frontend.schemas';
+import { ResourceParentResourceRequirement, ResourcePrimaryScope, ResourceRelationship, ResourceTranspositionPolicy, CoreResourceOperation, ResourceOperationDisplayMode, ResourceOperationFrontendSurface, ResourceFieldIdentifier, ResourceType, ResourceConfiguration_Operation_ApiCall, ResourceConfiguration_Operation_ApiCallWithCallback, ResourceConfiguration_ResourceRelationships, ResourceConfiguration_InheritanceSchemaDefinition, TourStepPlacement, NavigationZoneName, OverlayAppearance, SplitAppearance } from '@wildo-ai/saas-models';
+import type { ResourceConfiguration, ResourceConfiguration_InitializationFactory, ValidOperationKeys, RelationshipDisplayInParentNavigation, RelationshipDisplayInChildView } from '@wildo-ai/saas-models';
+import type { InsertedChartDeclaration } from '../../core/config/chart-view.frontend.schemas';
+import type { InsertedExecutionDeclaration, ResourceExecutionViewsConfig } from '../../core/config/execution-view.schemas';
+import type { OnboardingElementType, GuidanceRenderMode, GuidanceFlowScope, GuidanceAudience, NotificationBadgeDefinition, UserNotificationDefinition, SubtreeMap, ManyToManyScopeJunctionMap } from '@wildo-ai/saas-models';
+import { ViewportBreakpoint, DisplayDirection } from '@wildo-ai/zod-decorators';
+import type { ActionLabelDisplayMode } from '@wildo-ai/presets-components-models';
+import { VerticalPlacement, HorizontalPlacement } from '@wildo-ai/presets-components-models';
+import type { InsertedCompositeDeclaration, ResourceCompositeViewAuthoringConfig } from '../config/composite-view.schemas';
+/**
+ * Per-operation navigation chrome: transition, overlay/split appearance, source zone.
+ *
+ * **How to use:** attach fragments of this shape under
+ * `ResourceOperationFrontendConfig.navigationOverrides` in `resourceUIBehavior()`.
+ * Each override applies when navigating **from** the configured zone/viewport into
+ * this operation. Prefer mirroring a sibling resource that already matches the
+ * product’s overlay vs split behavior.
+ */
 export declare const NavigationOperationOverrideSchema: z.ZodObject<{
     transition: z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").NavigationTransition>, z.ZodObject<{
         transition: z.ZodEnum<typeof import("@wildo-ai/saas-models").NavigationTransition>;
         persistent: z.ZodOptional<z.ZodBoolean>;
         ephemeral: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip, core.$ZodObjectExtra>]>;
+    }, z.core.$strip>]>;
     appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>>]>>;
     fromZone: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"appLevel">]>>;
     viewport: z.ZodOptional<z.ZodEnum<typeof ViewportBreakpoint>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type NavigationOperationOverride = z.infer<typeof NavigationOperationOverrideSchema>;
 /**
  * Runtime-resolved scope field definition.
@@ -33,17 +45,40 @@ export interface AppScopeFieldDefinition extends QuickSwitcherScopeField {
     /** Resolved from the resource configuration at initialization */
     resourcePrimaryScope: ResourcePrimaryScope;
 }
-import type { FrontendResourceOperationPath, FrontendResource_ParentResourceRequirement } from './resource-path.frontend.schemas.js';
+import type { FrontendResourceOperationPath, FrontendResource_ParentResourceRequirement } from './resource-path.frontend.schemas';
+/**
+ * Resolved operation row the **frontend registry** stores: same structural operation
+ * config as `@wildo-ai/saas-models` (API_CALL / callback variants) plus optional
+ * `operationFrontendConfig` from the app preset.
+ *
+ * **How to use:** app authors normally do **not** construct this type by hand —
+ * `buildFrontendResourceConfigurations()` merges backend `ResourceConfiguration`
+ * with `ResourceUIBehavior`. Use it when typing hooks/components that receive the
+ * merged registry (e.g. operation context, launcher resolution).
+ */
 type FrontendResourceOperation_Base = {
     /**
-     * Frontend UI behavior config for this operation. `undefined` for API-only
-     * operations that have no UI presence (callable via httpClient but not
-     * surfaced in preset-driven UI). Operations with a preset entry always have
-     * a defined value.
+     * Frontend UI behavior config for this operation, carrying its `surface`
+     * ({@link ResourceOperationFrontendSurface}). After `buildFrontendResourceConfigurations`
+     * runs, EVERY operation has a resolved config: preset-surfaced operations get
+     * their authored config; everything else resolves to `{ surface: API_ONLY }`
+     * (headless) from the operation's `defaultFrontendPosture` or the default.
+     * The field stays optional only for the pre-resolution / partial-mock case —
+     * read the surface via `isOperationAddressable()` / `isOperationHeadless()`,
+     * never by testing presence.
      */
     operationFrontendConfig?: ResourceOperationFrontendConfig;
 };
 export type FrontendResourceConfiguration_Operation<TCustomOperationEnum extends EnumLikeType | undefined = any, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = any, TMainSchema extends z.ZodTypeAny = z.ZodAny> = (ResourceConfiguration_Operation_ApiCall<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | ResourceConfiguration_Operation_ApiCallWithCallback<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>) & FrontendResourceOperation_Base;
+/**
+ * Full **merged** resource row in the frontend registry: backend fields (scope, schema,
+ * relationships, operations) plus optional `frontendConfiguration` (labels, layout,
+ * views map, guidance, …) derived from the app’s `ResourceUIBehavior` preset.
+ *
+ * **How to use:** read-only shape at runtime and in typed frontend services. Authoring
+ * happens in `*.resources-config.ts` + `*.ui-behavior.tsx`, not by filling this object
+ * manually.
+ */
 export type FrontendResourceConfiguration<TCustomOperationEnum extends EnumLikeType | undefined = any, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = any, TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
     isDisabled: boolean;
     resourcePrimaryScope: ResourcePrimaryScope;
@@ -56,14 +91,41 @@ export type FrontendResourceConfiguration<TCustomOperationEnum extends EnumLikeT
     inheritenceSchemaDefinition?: ResourceConfiguration_InheritanceSchemaDefinition<EnumLikeType, TMainSchema>;
     frontendConfiguration?: ResourceUIBehaviorResourceLevelConfig<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
     isSystemResource: boolean;
+    /**
+     * Mirrors `ResourceConfiguration.primaryKeyIdentifiesInitiator` from `@wildo-ai/saas-models`.
+     * `buildFrontendResourceConfigurations` spreads the backend config onto every frontend
+     * registry entry, so this is always populated at runtime; it must stay declared here too
+     * so shared `saas-models` utils typed against `AnyResourceConfiguration` (e.g.
+     * `ResourcesConfigOperationsUrlsBuilderUtils`) accept a frontend registry entry.
+     */
+    primaryKeyIdentifiesInitiator: boolean;
     isAnonymizable: boolean;
     transpositionPolicy: ResourceTranspositionPolicy;
     operations: FrontendResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>[];
 };
 export type AnyFrontendResourceConfiguration = FrontendResourceConfiguration<any, any, any>;
+/**
+ * Application **frontend** resource registry built at startup (field-id maps, relationships,
+ * notification defs, subtree map, and per-resource `FrontendResourceConfiguration`).
+ *
+ * **How to use:** consume via React context / services (`ResourcesRepository`, routing,
+ * layout hosts). Authors extend it indirectly by registering presets and module wiring —
+ * not by mutating this object ad hoc.
+ */
 export type FrontendResourcesRegistry = {
     allResourceFieldIdentifiers: Record<string, string>;
     fieldIdentifierToResourceType: Record<string, ResourceType>;
+    /**
+     * Scope-required reference-search junctions, keyed by `${target}|${scope}`.
+     * Drives the inference-based people-picker: a FK targeting `T` from a resource
+     * scoped by `S`, where `T ↔ S` is an M:N via junction `J`, searches `T` scoped
+     * to the caller's current `S` through `J`. Mirrors the backend registry.
+     *
+     * OPTIONAL: the real registry builder always populates it, but partial test
+     * registries omit it — consumers (e.g. `useResourceSearch`) treat an absent map
+     * as "no junction scoping" (plain target search).
+     */
+    manyToManyScopeJunctions?: ManyToManyScopeJunctionMap;
     notificationBadgeDefinitions: NotificationBadgeDefinition[];
     additionalUserNotificationDefinitions: UserNotificationDefinition[];
     resourceRelationships: ResourceRelationship[];
@@ -72,12 +134,16 @@ export type FrontendResourcesRegistry = {
     };
     subtreeMap: SubtreeMap;
 };
-/** ──────────────────────────────────────────────────────────────
- * FrontendResourceOperationContext
+/**
+ * Everything the framework knows about the **current resource operation** while rendering
+ * a layout host (read/update/list/custom view, nested child, etc.).
  *
- * Explicit interface for proper TypeScript typing.
- * The operation field uses FrontendResourceConfiguration_Operation type.
- * ────────────────────────────────────────────────────────────── */
+ * **How to use:** custom templates and views receive compatible props via framework
+ * hooks; use `contextResourceIdentifiers` for parent/child route params and FK scope.
+ * `operation` is the merged backend operation + `operationFrontendConfig` — prefer it
+ * over guessing URLs or variant keys. `parentResourcesRequirements` repeats path
+ * requirements from routing for hosts that must validate scope before fetch.
+ */
 export interface FrontendResourceOperationContext extends FrontendResourceOperationPath {
     /** Current operation being executed */
     resourceType: string;
@@ -106,8 +172,9 @@ export declare const FrontendResourceOperationContextSchema: z.ZodObject<{
         requirement: z.ZodEnum<typeof ResourceParentResourceRequirement>;
         isPrimaryScope: z.ZodBoolean;
         primaryScope: z.ZodOptional<z.ZodEnum<typeof ResourcePrimaryScope>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     operationIdentifier: z.ZodString;
+    variantType: z.ZodOptional<z.ZodEnum<typeof import("@wildo-ai/saas-models").ResourceOperationVariantType>>;
     isOperationDefault: z.ZodBoolean;
     isBulkOperation: z.ZodBoolean;
     variantKey: z.ZodOptional<z.ZodString>;
@@ -115,9 +182,9 @@ export declare const FrontendResourceOperationContextSchema: z.ZodObject<{
     contextResourceIdentifiers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         fieldIdentifier: z.ZodString;
         resourceId: z.ZodString;
-    }, z.core.$strip, core.$ZodObjectExtra>]>>;
+    }, z.core.$strip>]>>;
     additionalContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 /**
  * Frontend-native resource configuration types.
  *
@@ -130,6 +197,12 @@ export declare const FrontendResourceOperationContextSchema: z.ZodObject<{
  * build. The `views` sub-field provides per-operation frontend config — giving
  * a single, self-contained definition of how each resource appears and behaves in
  * a given frontend application.
+ *
+ * **How to use (authoring):** in app code, build a `ResourceUIBehavior` map with
+ * `resourceUIBehavior(factory, schema, callback)` and merge presets; the framework
+ * compiles that into `FrontendResourceConfiguration` entries. The types below
+ * (`ResourceUIBehavior_EmptyState`, `ResourceLayoutConfig`, …) are the pieces you
+ * pass inside that callback’s return value.
  */
 /** Secondary action type for empty state (link to URL vs guidance flow). */
 export declare enum ResourceFrontend_EmptyStateSecondaryActionType {
@@ -217,11 +290,17 @@ export interface ResourceUIBehavior_GuidanceFlow {
     elements: ResourceFrontend_GuidanceElement[];
 }
 /**
+ * @wildo_source:part:start saas.frontend.operation-key-and-resource-config-like facet:layer:frontend facet:family:resource-ui
+ *
  * Key identifying a resource operation in the frontend preset.
  *
  * - `string` — default operation (e.g., `CoreResourceOperation.READ`)
  * - `readonly [string, string]` — non-default variant: `[operationIdentifier, variantKey]`
  *   (e.g., `[CoreResourceOperation.READ, 'admin']`)
+ *
+ * The same extracted span also includes `FRONTEND_SCHEMA_KEY`, `ObjectShape`,
+ * `ResourceConfigLike`, and `TypedOperationKey` — the schema bridge and typed
+ * operation keys used by `resourceUIBehavior()` inference.
  */
 export type OperationKey = string | readonly [string, string];
 /**
@@ -244,53 +323,429 @@ export type ResourceConfigLike<TCustomOp extends EnumLikeType | undefined, TCore
  * with untyped `OperationKey` usage.
  */
 export type TypedOperationKey<TCustomOp extends EnumLikeType | undefined = any, TCoreOp extends Partial<CoreResourceOperation> | undefined = any> = ValidOperationKeys<TCustomOp, TCoreOp> | readonly [ValidOperationKeys<TCustomOp, TCoreOp>, string];
+/** @wildo_source:part:end saas.frontend.operation-key-and-resource-config-like */
+/**
+ * @wildo_source:part:start saas.frontend.resource-operation-frontend-config facet:layer:frontend facet:family:resource-ui
+ *
+ * How a resource collection renders its items (cards vs table). A FRONTEND
+ * presentation vocabulary — authored on a LIST/SEARCH operation's
+ * `collectionDisplayConfig` (below) in the resource UI behavior, NEVER on the
+ * shared resources-config operation: the backend has no notion of cards-vs-table.
+ * The string values are the persisted view-mode keys, so a stored user choice
+ * reads straight across.
+ *
+ * @example
+ * // resource UI behavior `views` entry:
+ * [Op.LIST, { collectionDisplayConfig: { displayMode: CollectionDisplayMode.TABLE, userSwitchableDisplayMode: true } }]
+ */
+export declare enum CollectionDisplayMode {
+    /** Stacked cards — one row per item via `ResourceListItemRenderer`. */
+    CARDS = "cards",
+    /** Dense table — one column per summary field via the table body. */
+    TABLE = "table"
+}
+/**
+ * How CARDS-mode items are arranged. Orthogonal to {@link CollectionDisplayMode}
+ * (this only shapes the CARDS body; TABLE ignores it). LIST and GRID are kept as
+ * DISTINCT layouts, not a `columns: 1` collapse — a list is bordered rows sharing
+ * one container (`divide-y`), a grid is separated card cells in N responsive
+ * columns.
+ */
+export declare enum CardLayoutStyle {
+    /** Bordered rows in a single shared container (the classic stacked list). */
+    LIST = "list",
+    /** Separated card cells laid out in an N-column responsive grid. */
+    GRID = "grid"
+}
+/** @wildo_source:part:end saas.frontend.resource-operation-frontend-config */
 /**
+ * @wildo_source:part:start saas.frontend.resource-operation-frontend-config facet:layer:frontend facet:family:resource-ui
+ *
  * Frontend configuration for a single resource operation.
  *
  * Controls how the operation is surfaced in the frontend:
- * - `isAddressable` — whether the operation has a routable URL
- * - `customView` — direct UIBehavior-owned React component override for authored custom operation views
+ * - `surface` — the operation's frontend surface: `ADDRESSABLE` (routable page),
+ *   `EMBEDDED` (non-addressable view rendered within a host: overlay, composite, or
+ *   nested), or `API_ONLY` (headless — no interface, callable as an API). See
+ *   `ResourceOperationFrontendSurface`.
+ * - `customView` — direct UIBehavior-owned React component override for authored custom operation views.
  *   Use the exported operation-family component types (`ResourceReadCustomViewComponent`,
  *   `ResourceListCustomViewComponent`, etc.) plus the matching
  *   `useReadOperationSurface()` / `useListOperationSurface()` helpers when you
  *   want a strongly truthful custom host for a specific layout family.
- * - `additionalViewLinks` — ordered refs of resource-owned chart/composite/execution
- *   views that this operation host should surface
  * - `displayPresetOverride` — layout preset override for the operation's UI
  * - `navigationOverrides` — per-operation navigation transition overrides
  * - `displayPriority` — visual ordering in ActionBar/operation lists (lower = higher priority)
  * - `iconOverride` — per-operation icon ref (overrides resource-level icon in navigation items)
+ * - `collectionDisplayConfig` — for LIST/SEARCH collection operations: the default
+ *   cards-vs-table body (`displayMode`) and whether the user may toggle it
+ *   (`userSwitchableDisplayMode`, persisted per resource type); the CARDS
+ *   arrangement (`cardLayout` — LIST vs N-column GRID); where each card's action
+ *   buttons sit (`cardActionPlacement` — 2-axis anchor + orientation); and
+ *   whether items are selectable for bulk actions (`selectable`). Pure frontend
+ *   presentation; the backend never reads it.
+ *
+ * **Resource-owned inserted views are NOT configured here.** Composite, chart,
+ * and execution views declared on the resource UI behavior surface themselves
+ * into their targeted operation host directly, via their own canonical fields:
+ * `compositeViews[*].operationLike` / `chartViews[*].operationLike` (single)
+ * and `executionViews[*].surfaceInOperations` (list). The layout consumer
+ * (`ResourceLayout_InsertedViews`) reads those declarations and filters them
+ * by the current operation at render time — there is no operation-level
+ * view-ref list to author or compile.
+ *
+ * **Historical note (search hit):** earlier versions of this schema exposed an
+ * `additionalViews: ResourceViewRef[]` (and before that `additionalViewLinks:
+ * string[]`) operation-level field that authored which resource-owned views
+ * surfaced in this operation. That field was removed in the
+ * `resource-owned-view-surfacing-contract.md` workstream because it duplicated
+ * the per-view declaration sites (`compositeViews`, `chartViews`,
+ * `executionViews`) and could silently disagree with them. If you are looking
+ * for `additionalViews` because a doc, comment, prompt, or downstream code
+ * still references it, the answer is: declare the surface on the view itself
+ * (use `operationLike` for composite/chart, `surfaceInOperations` for
+ * execution), do not re-introduce an operation-level seam.
+ */
+/**
+ * How an operation's ACTION (its action-bar button) is surfaced in this application.
+ *
+ * A per-app, **display-only** axis — backend authorization is unaffected, roles
+ * remain the only security authority, so this never makes an operation reachable
+ * that wasn't already; it only governs the button.
+ */
+export declare enum ActionVisibility {
+    /** Always shown; rendered DISABLED when its `enabledCondition` is unmet. The default. */
+    ALWAYS = "always",
+    /**
+     * Never shown — this app declares the operation's action off for this surface.
+     *
+     * Invariant: do NOT pair with a visible (addressable) view for the same operation.
+     * The action is the entry point to the view, so a visible view whose action is
+     * hidden is contradictory — there is no way to reach it. Hiding the action removes
+     * the operation, and the path to any view it has, from this app's UI.
+     */
+    HIDDEN = "hidden",
+    /**
+     * Shown ONLY when its `enabledCondition` is met; HIDDEN (not disabled) otherwise.
+     *
+     * For state-conditional operations whose disabled state is just noise — e.g.
+     * organization `ACTIVATE` appears on a suspended org but vanishes on an active one,
+     * rather than sitting there greyed out.
+     */
+    WHEN_AVAILABLE = "when_available"
+}
+/**
+ * Where an operation's ACTION sits in the action bar for this application.
+ *
+ * A per-app, **display-only** layout axis, orthogonal to authorization. When
+ * omitted, placement is DERIVED from the operation's `riskLevel`: HIGH/CRITICAL
+ * operations default to `DANGER_ZONE`, everything else to `PRIMARY`. Set it
+ * explicitly to override that default — e.g. tuck a non-risky-but-rare action
+ * into the danger zone, or keep a CRITICAL action inline in a dedicated admin
+ * tool. The same axis drives the bulk action bar, since both are built from the
+ * same operation pipeline.
+ */
+export declare enum ActionPlacement {
+    /** Inline in the main action group. The default for low/medium-risk operations. */
+    PRIMARY = "primary",
+    /**
+     * Segregated into a trailing "danger zone" group, fenced off by a separator,
+     * after every PRIMARY action. The default for HIGH/CRITICAL-risk operations
+     * (destructive deletes, lifecycle suspends).
+     */
+    DANGER_ZONE = "danger_zone"
+}
+/**
+ * HOW an operation's action collects its input and shows its result — the chrome the user meets
+ * when they click the button.
+ *
+ * ## Why this axis exists
+ *
+ * Until this axis, one rule decided the answer for every custom operation:
+ * *has a `requestDto` ⇒ navigate*. So an action asking for a single reason string got the same
+ * full-page treatment as a multi-step wizard, and the only way out was to author
+ * `navigationOverrides` — per operation, in terms of a zone, a transition verb and an appearance.
+ * Three concepts to answer one question.
+ *
+ * This is that one question. It is a **display-only** axis: backend authorization is untouched and
+ * `roles` remain the only security authority, exactly like its siblings {@link ActionVisibility},
+ * {@link ActionPlacement} and {@link ResourceOperationActionScope}.
+ *
+ * ## It is an ALIAS, not a parallel mechanism
+ *
+ * `MODAL` and `PAGE` do not render anything themselves — they resolve to the navigation transitions
+ * that already exist (`OVERLAY`, and the ordinary chain), so there is one runtime mechanism and one
+ * set of zone/appearance/URL semantics. `DIRECT`, `POPOVER` and `INLINE` never enter navigation at
+ * all, because none of them is a destination: nothing is pushed, no zone changes, and there is
+ * nothing for a back button to pop. `INLINE` is hosted by the collection the element belongs to —
+ * see `InPlaceOperationContext` for why that is not the navigation layer's job.
+ *
+ * Consequently an explicit `navigationOverrides` entry still WINS over a presentation authored here
+ * (it is the more specific instrument, and it is checked first in the resolution chain). Author this
+ * axis to say what KIND of chrome the action wants; author `navigationOverrides` when you need to
+ * name the zone, the appearance or the viewport yourself.
+ *
+ * ## When omitted
+ *
+ * It is DERIVED from the operation — see `resolveResourceOperationActionPresentation()`. An
+ * operation that asks for nothing executes directly; a small field set opens a modal; input the
+ * framework cannot fit in an overlay (files, nested writes, a large field set) keeps the page it
+ * has always had. An operation whose `surface` is `ADDRESSABLE` always keeps its page: the author
+ * has already said it is a deep-linkable destination.
+ */
+export declare enum ResourceOperationActionPresentation {
+    /**
+     * Execute on click, with no form at all — the confirmation dialog for a risky operation is the
+     * only thing between the click and the request.
+     *
+     * Only meaningful for an operation that needs no caller input. Declaring it on an operation that
+     * DOES have required request fields would send an empty body, so the resolver refuses to derive it
+     * there and an author who declares it anyway gets the operation's fields dropped — check
+     * `requestDto` before reaching for this.
+     */
+    DIRECT = "direct",
+    /**
+     * A small form anchored to the button that opened it, dismissed by clicking away.
+     *
+     * The single-input idiom ("assign to…", "snooze until…"). Transient by construction: no URL, no
+     * history entry, nothing to deep-link. Use it when the surrounding context is the point — the user
+     * is reading the row they are acting on and must not lose sight of it.
+     */
+    POPOVER = "popover",
+    /**
+     * The element being acted on transforms in place to collect the input, leaving its neighbours
+     * visible — the row becomes the form rather than being covered by one.
+     *
+     * Use it when the surrounding rows are the point: the user is comparing, and an overlay would hide
+     * the very thing that made them act on this row.
+     *
+     * **Transient, like {@link POPOVER}, and for the same reason.** Nothing is pushed, no URL changes,
+     * and a reload returns the list to rest. An inline row-edit is a momentary state of a listing, not
+     * a place — which is also why no admin framework deep-links one, and why anything that SHOULD be
+     * linkable, reloadable or reachable by a back button wants {@link PAGE}.
+     *
+     * **It requires a collection.** The host is provided by the list the element belongs to
+     * (`InPlaceOperationProvider`); the same action rendered on a detail page, in a danger zone or in a
+     * picker has no row to transform and degrades to an overlay rather than becoming a dead button.
+     *
+     * Note it does NOT resolve to `NavigationTransition.INPLACE`. Element-level hosting uses none of
+     * what the navigation layer offers — no zone, no stack entry, no appearance — and routing it there
+     * is exactly why that transition has never done what its own docstring promises. See
+     * `InPlaceOperationContext`.
+     */
+    INLINE = "inline",
+    /**
+     * An overlay above the layout — the workhorse for "a handful of fields", and the default the
+     * derivation reaches for.
+     *
+     * Resolves to {@link NavigationTransition.OVERLAY}. The concrete appearance (dialog / sheet /
+     * drawer / panel) stays the app's decision, resolved from its navigation layout exactly as any
+     * other overlay: this axis says "an overlay", not "a dialog specifically". Author
+     * `navigationOverrides` when you need to name one.
+     */
+    MODAL = "modal",
+    /**
+     * A routable page, resolved through the ordinary navigation chain (zone transitions, viewport
+     * overrides, the framework `PUSH` fallback) — i.e. exactly the behaviour every parameterised
+     * action had before this axis existed.
+     *
+     * The right answer for complex or multi-step input, and for anything a user should be able to
+     * link to, reload, or reach with a back button.
+     */
+    PAGE = "page"
+}
+/**
+ * Does an operation's action target a SINGLE resource instance, or the WHOLE
+ * collection in the current scope?
+ *
+ * A per-app **surfacing** axis, orthogonal to authorization. Most actions are
+ * `ITEM` (edit / delete / retry one row) and render in the per-row and detail
+ * action bars. A `COLLECTION` action operates on every row in scope at once
+ * (e.g. "retry all failed deliveries", "purge the queue"): it renders ONCE in
+ * the list's collection-action surface (the toolbar), never per row, and
+ * confirms + executes in place rather than opening a per-row form.
+ *
+ * For a `COLLECTION` action to have a callable route, its operation must borrow
+ * a COLLECTION verb via `resourceOperationLike` (`UPDATE_MANY` / `DELETE_MANY` /
+ * `CREATE_MANY`) — an entity verb (`UPDATE` / `DELETE`) generates a route with a
+ * `:id` segment the scope-level surface has no single row to fill.
+ */
+export declare enum ResourceOperationActionScope {
+    /** Targets one resource instance — the per-row / detail action bars. The default when omitted. */
+    ITEM = "item",
+    /** Targets the whole collection in scope — rendered once in the list's collection-action surface. */
+    COLLECTION = "collection"
+}
+/**
+ * What happens to an operation's action when its `enabledCondition` is currently
+ * unmet — the per-view default for actions that don't declare an explicit
+ * `actionVisibility`. An explicit per-operation `actionVisibility` always wins
+ * over this policy; feature-gated unavailability keeps its own
+ * `FeatureUnavailabilityBehavior` (upgrade/prompt) and is never hidden by this.
+ *
+ * - `HIDE` — drop the action entirely while unavailable (as if it declared
+ *   `ActionVisibility.WHEN_AVAILABLE`). The framework default for BOTH views: a
+ *   greyed, non-actionable button is noise wherever it sits, and hiding it also
+ *   collapses mutually-exclusive state pairs (e.g. "Set as recurring" / "Set as
+ *   one time") down to the one that currently applies.
+ * - `SHOW_DISABLED` — render the action greyed/disabled (the classic behavior).
+ *   Opt in per view when the disabled action + its reason tooltip is genuinely
+ *   informative and you want it always present.
  */
+export declare enum DisabledActionHandling {
+    SHOW_DISABLED = "show_disabled",
+    HIDE = "hide"
+}
+/**
+ * Per-view action-surfacing (disclosure) policy — how many actions stay visible
+ * and how unavailable ones are treated, for ONE {@link ResourceOperationDisplayMode}.
+ */
+export interface ResourceActionDisclosureConfig {
+    /**
+     * How many PRIMARY actions render as direct buttons before the remainder
+     * collapse into the `…` overflow menu. Omitted inherits the framework default
+     * for the view ({@link DEFAULT_ACTION_DISCLOSURE}): 3 for SUMMARY, unlimited
+     * for DETAIL. `0` pushes every action into the menu.
+     */
+    maxPrimaryActions?: number;
+    /**
+     * Default handling for actions disabled by an unmet `enabledCondition` — see
+     * {@link DisabledActionHandling}. Omitted inherits the framework default,
+     * which is `HIDE` for both views (set `SHOW_DISABLED` here to keep disabled
+     * actions greyed-but-present for a view).
+     */
+    disabledActionHandling?: DisabledActionHandling;
+}
+/** Fully-resolved disclosure policy (no optional fields) for one view. */
+export interface ResolvedActionDisclosure {
+    /** `undefined` = unlimited (no overflow cap). */
+    maxPrimaryActions: number | undefined;
+    disabledActionHandling: DisabledActionHandling;
+}
+/**
+ * Framework defaults per view. Both views HIDE actions disabled by an unmet
+ * `enabledCondition` — an inapplicable, greyed button is noise everywhere, so
+ * the bar only ever shows actions the user can actually take right now. They
+ * differ on the overflow cap: SUMMARY (dense list/table rows) shows at most 3
+ * direct actions before the `…` menu; DETAIL (roomy read view) is uncapped.
+ * A resource that WANTS the informative greyed-with-reason affordance opts into
+ * `SHOW_DISABLED` per view via `layout.actionDisclosure`.
+ */
+export declare const DEFAULT_ACTION_DISCLOSURE: Record<ResourceOperationDisplayMode, ResolvedActionDisclosure>;
+/**
+ * Resolve the effective disclosure policy for a view: per-resource override
+ * (`layout.actionDisclosure[view]`) layered over the framework default. Used by
+ * both the action-building hook (disabled handling) and the operations-items
+ * host (overflow cap).
+ */
+export declare function resolveActionDisclosure(displayMode: ResourceOperationDisplayMode, disclosure: Partial<Record<ResourceOperationDisplayMode, ResourceActionDisclosureConfig>> | undefined): ResolvedActionDisclosure;
+/**
+ * 2-axis card action-button placement. Single source of truth for the config
+ * field AND the `card-action-placement.utils` resolver (which imports the
+ * `CardActionPlacement` type inferred from this schema, so the two can never
+ * drift). `MIDDLE × MIDDLE` is rejected — dead-center overlaps the card content.
+ */
+export declare const CardActionPlacementSchema: z.ZodObject<{
+    vertical: z.ZodEnum<typeof VerticalPlacement>;
+    horizontal: z.ZodEnum<typeof HorizontalPlacement>;
+    orientation: z.ZodOptional<z.ZodEnum<typeof DisplayDirection>>;
+}, z.core.$strip>;
+/** Authored 2-axis card action placement — inferred from {@link CardActionPlacementSchema}. */
+export type CardActionPlacement = z.infer<typeof CardActionPlacementSchema>;
 export declare const ResourceOperationFrontendConfigSchema: z.ZodObject<{
-    isAddressable: z.ZodBoolean;
+    surface: z.ZodEnum<typeof ResourceOperationFrontendSurface>;
+    actionVisibility: z.ZodOptional<z.ZodEnum<typeof ActionVisibility>>;
+    actionPlacement: z.ZodOptional<z.ZodEnum<typeof ActionPlacement>>;
+    actionVariant: z.ZodOptional<z.ZodAny>;
+    actionScope: z.ZodOptional<z.ZodEnum<typeof ResourceOperationActionScope>>;
+    rowTargetRequestField: z.ZodOptional<z.ZodString>;
+    actionPresentation: z.ZodOptional<z.ZodEnum<typeof ResourceOperationActionPresentation>>;
     customView: z.ZodOptional<z.ZodAny>;
-    additionalViewLinks: z.ZodOptional<z.ZodArray<z.ZodString>>;
     displayPresetOverride: z.ZodOptional<z.ZodObject<{
         resourceLayoutPresetKey: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     navigationOverrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
         transition: z.ZodUnion<readonly [z.ZodEnum<typeof import("@wildo-ai/saas-models").NavigationTransition>, z.ZodObject<{
             transition: z.ZodEnum<typeof import("@wildo-ai/saas-models").NavigationTransition>;
             persistent: z.ZodOptional<z.ZodBoolean>;
             ephemeral: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip, core.$ZodObjectExtra>]>;
+        }, z.core.$strip>]>;
         appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>>]>>;
         fromZone: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"appLevel">]>>;
         viewport: z.ZodOptional<z.ZodEnum<typeof ViewportBreakpoint>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     displayPriority: z.ZodOptional<z.ZodNumber>;
     iconOverride: z.ZodOptional<z.ZodAny>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    collectionDisplayConfig: z.ZodOptional<z.ZodObject<{
+        displayMode: z.ZodOptional<z.ZodEnum<typeof CollectionDisplayMode>>;
+        userSwitchableDisplayMode: z.ZodOptional<z.ZodBoolean>;
+        quickFilterField: z.ZodOptional<z.ZodString>;
+        temporalGroupField: z.ZodOptional<z.ZodString>;
+        cardLayout: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            style: z.ZodLiteral<CardLayoutStyle.LIST>;
+        }, z.core.$strip>, z.ZodObject<{
+            style: z.ZodLiteral<CardLayoutStyle.GRID>;
+            columns: z.ZodNumber;
+        }, z.core.$strip>], "style">>;
+        cardActionPlacement: z.ZodOptional<z.ZodObject<{
+            vertical: z.ZodEnum<typeof VerticalPlacement>;
+            horizontal: z.ZodEnum<typeof HorizontalPlacement>;
+            orientation: z.ZodOptional<z.ZodEnum<typeof DisplayDirection>>;
+        }, z.core.$strip>>;
+        selectable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    hasDescription: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 /**
  * TypeScript interface for `ResourceOperationFrontendConfigSchema`.
- * `iconOverride` and `customView` are typed with React/function values
- * even though the Zod schema uses `z.any()` — Zod cannot validate function types.
+ * `iconOverride`, `customView`, and `actionVariant` are typed with their real
+ * React/enum values even though the Zod schema uses `z.any()` — Zod cannot
+ * validate function types, and `actionVariant`'s enum lives in a component
+ * module the schema must not import at runtime.
  */
-export type ResourceOperationFrontendConfig = Omit<z.infer<typeof ResourceOperationFrontendConfigSchema>, 'iconOverride' | 'customView'> & {
+export type ResourceOperationFrontendConfig = Omit<z.infer<typeof ResourceOperationFrontendConfigSchema>, 'iconOverride' | 'customView' | 'actionVariant'> & {
     iconOverride?: IconLike;
     customView?: React.ComponentType;
+    actionVariant?: ButtonVariants_Variant;
 };
-export type ResourceCompositeViewsConfig = Record<string, React.ComponentType<CompositeViewComponentProps>>;
+/** @wildo_source:part:end saas.frontend.resource-operation-frontend-config */
+/**
+ * Is this operation's frontend surface URL-addressable (a routable page)?
+ *
+ * The canonical replacement for the former `isAddressable` boolean field — read
+ * `surface` rather than storing addressability, so the three surfaces stay a
+ * single source of truth. Safe on `undefined` (an operation whose frontend
+ * config has not been resolved yet is treated as not addressable).
+ */
+export declare function isOperationAddressable(config?: Pick<ResourceOperationFrontendConfig, 'surface'>): boolean;
+/**
+ * Is this operation headless — callable as an API with no rendered interface
+ * (no page, no overlay, no action button)? See {@link ResourceOperationFrontendSurface.API_ONLY}.
+ */
+export declare function isOperationHeadless(config?: Pick<ResourceOperationFrontendConfig, 'surface'>): boolean;
+/**
+ * Does this operation's action target the whole collection in scope, rather than
+ * a single row? See {@link ResourceOperationActionScope}. Safe on `undefined`
+ * (treated as `ITEM`). Collection-scoped actions render ONLY in the list's
+ * collection-action surface (the toolbar) and are excluded from the per-row,
+ * detail, danger-zone, and bulk bars.
+ */
+export declare function isCollectionScopedOperation(config?: Pick<ResourceOperationFrontendConfig, 'actionScope'>): boolean;
+/**
+ * Resource-owned **composite** templates keyed by view ref (authoring form).
+ *
+ * **How to use:** set `compositeViews` on `ResourceUIBehaviorConfig` to
+ * `ResourceCompositeViewAuthoringConfig` objects. Each composite renders
+ * inside exactly one resource operation host, declared via
+ * {@link ResourceCompositeViewAuthoringConfig.operationLike} (defaulting to
+ * `CoreResourceOperation.READ`). Prefer `executionViews` / `chartViews` for
+ * those families instead of overloading composites.
+ *
+ * Note: this type is **distinct** from `AppCompositeViewsConfig`. Only
+ * resource composites carry `operationLike`, because app-level composites have
+ * no resource operation host to surface into.
+ */
+export type ResourceCompositeViewsConfig = Record<string, ResourceCompositeViewAuthoringConfig>;
 /**
  * Parameters passed to `getFrontendResourceLabel` functions.
  *
@@ -304,6 +759,7 @@ export type ResourceUIBehaviorLabelParams<TMainSchema extends z.ZodTypeAny = z.Z
     initiatorUserContext?: any;
     t: (toTranslate: string, params?: Record<string, any>) => string;
 };
+/** @wildo_source:part:start saas.frontend.resource-layout-templates facet:layer:frontend facet:family:resource-ui */
 /**
  * Static manifest of structural refs used in JSX templates.
  * Readable by the companion without JSX/AST parsing.
@@ -343,6 +799,12 @@ export type LayoutTemplate = React.ComponentType;
  *
  * When no template is provided for a context, the framework generates a
  * default flat template at runtime from the schema.
+ *
+ * **How to use:** set `layout: { refs, edit, display, summary }` on the object returned
+ * from `resourceUIBehavior()`. Every `<Section name="…">`, `<WizardStep name="…">`, and
+ * `<Group name="…">` in those templates should appear under `refs` for i18n and
+ * companion validation. Omit `edit` / `display` / `summary` individually to keep the
+ * auto-generated default for that context only.
  */
 export interface ResourceLayoutConfig {
     /**
@@ -364,6 +826,39 @@ export interface ResourceLayoutConfig {
         /** Default chrome for edit context. */
         edit?: ResponsiveAware<EditChromeMode>;
     };
+    /**
+     * Per-view override for how this resource's action buttons render their
+     * label, keyed by {@link ResourceOperationDisplayMode} (`SUMMARY` = list/table
+     * rows & cards, `DETAIL` = full read view). Overrides the app-wide theme
+     * default (`ComponentStyleTheme.actionLabelDisplayMode`). Omit a key to
+     * inherit the app default for that view.
+     *
+     * Precedence: `layout.actionLabelDisplayMode[view]` → app theme default → `TOOLTIP`.
+     *
+     * @example
+     * // Dense list rows stay icon-only; the full detail view spells actions out.
+     * actionLabelDisplayMode: {
+     *   [ResourceOperationDisplayMode.SUMMARY]: ActionLabelDisplayMode.TOOLTIP,
+     *   [ResourceOperationDisplayMode.DETAIL]: ActionLabelDisplayMode.INLINE,
+     * }
+     */
+    actionLabelDisplayMode?: Partial<Record<ResourceOperationDisplayMode, ActionLabelDisplayMode>>;
+    /**
+     * Per-view action-surfacing (disclosure) policy — see {@link ResourceActionDisclosureConfig}.
+     * Controls how many actions stay visible before overflow (`maxPrimaryActions`)
+     * and whether actions disabled by an unmet `enabledCondition` are hidden or
+     * greyed (`disabledActionHandling`), keyed by {@link ResourceOperationDisplayMode}.
+     * Omit a view (or a field) to inherit the framework default
+     * ({@link DEFAULT_ACTION_DISCLOSURE}): SUMMARY = { max 3, hide-disabled },
+     * DETAIL = { unlimited, hide-disabled }.
+     *
+     * @example
+     * // A busy list keeps just one action inline; the detail view spells them all out.
+     * actionDisclosure: {
+     *   [ResourceOperationDisplayMode.SUMMARY]: { maxPrimaryActions: 1 },
+     * }
+     */
+    actionDisclosure?: Partial<Record<ResourceOperationDisplayMode, ResourceActionDisclosureConfig>>;
     /**
      * Edit layout template — a `React.ComponentType` rendered inside `<Form>` providers.
      * The component is instantiated as `<EditTemplate />` and has access to
@@ -382,26 +877,92 @@ export interface ResourceLayoutConfig {
      * `useDisplayTemplateContext()` for `data`, `isLoading`, `variant`, labels, and breakpoint.
      */
     display?: LayoutTemplate;
+    /**
+     * Header layout template — the record's IDENTITY LINE in the READ page header.
+     *
+     * The header band is framework-owned chrome (back button, breadcrumb, resource
+     * icon, action cluster) wrapped around one middle region: the record's name.
+     * Authoring this template cedes that middle region to the resource, so state
+     * that belongs ON the identity line — a status badge, a visibility marker, an
+     * accent swatch — sits beside the name instead of in a labelled strip below it.
+     *
+     * Rendered inside a display-template provider over the loaded record, so
+     * `<DisplayField name="…">` and `useDisplayTemplateContext()` work exactly as
+     * they do in `display` / `summary`. Inline editing is off (the header shows
+     * state, it does not edit it) and chrome defaults to `INLINE` so fields render
+     * bare, without their labels.
+     *
+     * **Place `<ResourceHeaderTitle />` yourself.** The header stops rendering its
+     * own title once this template exists, so a template that omits the element
+     * produces a page with no record name (a dev warning names the resource).
+     *
+     * Distinct from `summary` on purpose: a card/FK-popover summary answers "how
+     * does this record identify itself in a LIST", and commonly carries fields a
+     * page header should not repeat. Both surfaces compose the same way; neither
+     * inherits the other's body.
+     *
+     * @example
+     * // Accent dot before the name, status badge after it, "Public" only when true:
+     * header: () => {
+     *   const { data, fieldLabels } = useDisplayTemplateContext();
+     *   return (
+     *     <>
+     *       {Boolean(data?.color) && <ColorDot value={String(data.color)} />}
+     *       <ResourceHeaderTitle />
+     *       <DisplayField name="status" hideLabel className="w-auto" />
+     *       {Boolean(data?.isPublic) && <Badge>{fieldLabels.isPublic}</Badge>}
+     *     </>
+     *   );
+     * }
+     */
+    header?: LayoutTemplate;
     /**
      * Summary layout template — rendered for cards, list items, FK references.
      * Typically a compact single-line or small card layout.
      * The component is instantiated inside `<DisplayTemplateProvider>` by `ResourceSummaryDisplayer`,
      * with `disableInlineEdit={true}` and chrome defaulting to `DisplayChromeMode.INLINE`.
      * Use `useDisplayTemplateContext()` for reactive data access.
+     *
+     * **The title is part of the template flow.** Wrap the body in `<SummaryLayout>`;
+     * by default (`titlePlacement={AUTO}`) it renders the resource's primary label
+     * (`<SummaryTitle />`) at the top, then your fields below — the classic
+     * title-above-body card. To put something on the title's line (a status badge),
+     * switch to `titlePlacement={TEMPLATE_OWNED}` and place `<SummaryTitle />`
+     * yourself, typically inside a `<SummaryHeader>`:
+     *
+     * @example
+     * // Title above a couple of fields (title rendered automatically):
+     * summary: () => (
+     *   <SummaryLayout>
+     *     <DisplayField name="createdAt" />
+     *   </SummaryLayout>
+     * )
+     *
+     * @example
+     * // Status badge inline with the title:
+     * summary: () => (
+     *   <SummaryLayout titlePlacement={SummaryTitlePlacement.TEMPLATE_OWNED}>
+     *     <SummaryHeader>
+     *       <SummaryTitle />
+     *       <DisplayField name="status" hideLabel />
+     *     </SummaryHeader>
+     *     <DisplayField name="createdAt" />
+     *   </SummaryLayout>
+     * )
      */
     summary?: LayoutTemplate;
 }
+/** @wildo_source:part:end saas.frontend.resource-layout-templates */
 /**
  * Per-relationship display override declared on the **owning resource's** preset.
  *
  * Each entry targets a specific relationship by `target` resource type (and
  * optionally `foreignKeyField` for disambiguation when multiple relationships
- * exist to the same type). The `inParentView` / `inParentNavigation` /
+ * exist to the same type). The `inParentNavigation` /
  * `inChildView` sub-objects are shallow-merged onto the relationship's shared
  * `display` config during registry build — frontend values win over shared defaults.
  *
  * **Ownership principle**: each resource configures its own view:
- * - `inParentView` → "how does this child appear **in my view** when I'm the parent?"
  * - `inParentNavigation` → "how does navigation from **my view** to this child behave?"
  * - `inChildView` → "how does the parent reference appear **in my view** when I'm the child?"
  *
@@ -410,7 +971,6 @@ export interface ResourceLayoutConfig {
  * relationshipOverrides: [
  *   // I'm parent of TASKS — make Tasks appear as accordion in MY view
  *   { target: ResourceType.TASKS,
- *     inParentView: { contentSectionConfig: { mode: SectionMode.ACCORDION } } },
  *   // I'm child of USERS (FK: assignedToUserId) — show user as badge in MY view
  *   { target: ResourceType.USERS, foreignKeyField: 'assignedToUserId',
  *     inChildView: { parentDisplay: ParentDisplay.BADGE } },
@@ -427,13 +987,14 @@ export interface RelationshipDisplayOverride {
      */
     foreignKeyField?: string;
     /** Override for how children appear in THIS resource's view (when I'm parent). */
-    inParentView?: Partial<RelationshipDisplayInParentView>;
     /** Override for how navigation from THIS resource's view to the child behaves. */
     inParentNavigation?: Partial<RelationshipDisplayInParentNavigation>;
     /** Override for how parent reference appears in THIS resource's view (when I'm child). */
     inChildView?: Partial<RelationshipDisplayInChildView>;
 }
 /**
+ * @wildo_source:part:start saas.frontend.resource-ui-behavior-config facet:layer:frontend facet:family:resource-ui
+ *
  * Complete frontend configuration for a single resource within an application.
  *
  * Canonical frontend resource configuration type. Contains resource-level settings
@@ -455,15 +1016,15 @@ export interface RelationshipDisplayOverride {
  * const orgConfig: ResourceUIBehaviorConfig<any, any, typeof OrgSchema> = {
  *   getFrontendResourceLabel: ({ currentObject }) => currentObject.name, // type-safe
  *   views: new Map([
- *     [CoreResourceOperation.CREATE, { isAddressable: false }],
- *     [CoreResourceOperation.LIST, { isAddressable: true }],
+ *     [CoreResourceOperation.CREATE, notAddressable()],
+ *     [CoreResourceOperation.LIST, addressable()],
  *   ]),
  * };
  *
  * // Input form (via resourceUIBehavior callback) uses array-of-tuples:
  * // views: [
- * //   [CoreResourceOperation.CREATE, { isAddressable: false }],
- * //   [CoreResourceOperation.LIST, { isAddressable: true }],
+ * //   [CoreResourceOperation.CREATE, notAddressable()],
+ * //   [CoreResourceOperation.LIST, addressable()],
  * // ],
  * ```
  */
@@ -533,10 +1094,12 @@ export type ResourceUIBehaviorConfig<TCustomOp extends EnumLikeType | undefined
      * Label generation for resource instances in the frontend.
      *
      * Can be either:
-     * - `string[]` — array of field paths to concatenate
+     * - `string[]` — array of field paths to concatenate (each entry is a field
+     *   name on the summary record, including any server-resolved virtual field
+     *   such as a `forwardedLabel`, e.g. `['instanceLabel']`).
      * - `(params: ResourceUIBehaviorLabelParams) => string` — a function
      *
-     * Used by `ResourceLayout_Header` to render the resource title.
+     * Used by `ResourceListItemRenderer` (rows) and `ResourceLayout_Header` (titles).
      */
     getFrontendResourceLabel?: string[] | ((params: ResourceUIBehaviorLabelParams<TMainSchema>) => string);
     /** Resource-owned composite templates declared inline on the resource UI behavior. */
@@ -579,6 +1142,7 @@ export type ResourceUIBehaviorConfig<TCustomOp extends EnumLikeType | undefined
      */
     views: Map<TypedOperationKey<TCustomOp, TCoreOp>, ResourceOperationFrontendConfig>;
 };
+/** @wildo_source:part:end saas.frontend.resource-ui-behavior-config */
 /**
  * Resource-level UI behavior configuration — the subset of `ResourceUIBehaviorConfig`
  * that describes the resource itself (labels, sections, views, empty state, guidance),
@@ -596,6 +1160,8 @@ export type ResourceUIBehaviorResourceLevelConfig<TCustomOp extends EnumLikeType
     executionViews?: InsertedExecutionDeclaration[];
 };
 /**
+ * @wildo_source:part:start saas.frontend.resource-ui-behavior-preset-map facet:layer:frontend facet:family:resource-ui
+ *
  * Complete frontend resource configuration preset for an application.
  *
  * Maps resource types to their full frontend configuration — including
@@ -614,14 +1180,15 @@ export type ResourceUIBehaviorResourceLevelConfig<TCustomOp extends EnumLikeType
  *   [CoreResourceType.ORGANIZATIONS]: resourceUIBehavior(factory, Schema, ({ schema, schemaShape, opsVariantResolver }) => ({
  *     getFrontendResourceLabel: ({ currentObject }) => currentObject.name,
  *     views: [
- *       [CoreResourceOperation.CREATE, { isAddressable: false }],
- *       [CoreResourceOperation.READ, { isAddressable: false }],
+ *       [CoreResourceOperation.CREATE, notAddressable()],
+ *       [CoreResourceOperation.READ, notAddressable()],
  *     ],
  *   })),
  * };
  * ```
  */
 export type ResourceUIBehavior = Record<string, ResourceUIBehaviorConfig>;
+/** @wildo_source:part:end saas.frontend.resource-ui-behavior-preset-map */
 /**
  * A single variant within a polymorphic frontend declaration.
  * Maps a parent resource type (the discriminator) to the concrete resource type it produces.
@@ -738,7 +1305,7 @@ export type PolymorphicResourceUIBehaviorConfigResult<TCustomOp extends EnumLike
  * }, {
  *   views: [
  *     [Op.READ, addressable()],
- *     [SsoConfig_Operations.ADD_DOMAIN, notAddressable()],
+ *     [CustomOperations.RUN_DIAGNOSTIC, notAddressable()],
  *   ],
  *   variantOverrides: {
  *     [R.APPLICATION]: { views: [] },
@@ -754,7 +1321,7 @@ export type PolymorphicResourceUIBehaviorConfigResult<TCustomOp extends EnumLike
  * }, {
  *   views: [
  *     [Op.READ, addressable()],
- *     [SsoConfig_Operations.ADD_DOMAIN, notAddressable()],
+ *     [CustomOperations.RUN_DIAGNOSTIC, notAddressable()],
  *   ],
  *   variantOverrides: {
  *     [R.ORGANIZATIONS]: {
@@ -768,15 +1335,24 @@ export type PolymorphicResourceUIBehaviorConfigResult<TCustomOp extends EnumLike
  * ```
  */
 export declare function createPolymorphicFrontendPreset(declaration: PolymorphicFrontendDeclaration, config: PolymorphicResourceUIBehaviorConfig): ResourceUIBehavior;
-/** Extracts the custom operation enum from a `ResourceConfiguration` or its factory. */
+/**
+ * Infers the custom operation enum from a resource factory or config type.
+ *
+ * **How to use:** in generic helpers that wrap `resourceUIBehavior(yourFactory, …)`
+ * so `TypedOperationKey` and `views` tuples stay aligned without repeating type params.
+ */
 export type ExtractCustomOp<T> = T extends ResourceConfiguration<infer C, any, any> ? C : T extends ResourceConfiguration_InitializationFactory<infer C, any, any> ? C : never;
-/** Extracts the core operation enum from a `ResourceConfiguration` or its factory. */
+/** Same as {@link ExtractCustomOp} for the **core** operations subset on the resource. */
 export type ExtractCoreOp<T> = T extends ResourceConfiguration<any, infer O, any> ? O : T extends ResourceConfiguration_InitializationFactory<any, infer O, any> ? O : never;
-/** Extracts the main Zod schema from a `ResourceConfiguration` or its factory. */
+/** Same as {@link ExtractCustomOp} for the resource **main Zod schema** type. */
 export type ExtractSchema<T> = T extends ResourceConfiguration<any, any, infer S> ? S : T extends ResourceConfiguration_InitializationFactory<any, any, infer S> ? S : never;
 /**
  * Creates a typed operation variant tuple `[operationKey, variantKey]`.
  * Preserves the literal operation key for `TypedOperationKey` assignability.
+ *
+ * **How to use:** in `views: [ … ]` when the operation key must stay a narrow literal
+ * (custom enum member or core op). Equivalent to `opsVariantResolver(op, key)` but
+ * useful in static arrays outside the callback.
  */
 export declare function variant<TOp extends string>(op: TOp, variantKey: string): readonly [TOp, string];
 /**
@@ -790,8 +1366,12 @@ export declare function variant<TOp extends string>(op: TOp, variantKey: string)
  */
 export type OperationEntries<TCustomOp extends EnumLikeType | undefined = any, TCoreOp extends Partial<CoreResourceOperation> | undefined = any> = [TypedOperationKey<TCustomOp, TCoreOp>, ResourceOperationFrontendConfig][];
 /**
- * Single object parameter passed to the `resourceUIBehavior()` and
- * `polymorphicResourceUIBehavior()` callback.
+ * Callback argument bag for `resourceUIBehavior()` / `polymorphicResourceUIBehavior()`.
+ *
+ * **How to use:** prefer `schemaShape.fieldName` for per-field `.enumUI()` / `.stringUI()`
+ * overrides; use `schema` when applying decorators on the root object; use
+ * `opsVariantResolver(CoreResourceOperation.READ, 'summary')` (or `variant()`) so
+ * non-default variant keys type-check against valid operations.
  */
 export type ResourceUIBehaviorCallbackParams<TCustomOp extends EnumLikeType | undefined, TCoreOp extends Partial<CoreResourceOperation> | undefined, TSchema extends z.ZodTypeAny> = {
     schema: TSchema;
@@ -835,8 +1415,8 @@ export type ResourceUIBehaviorConfigResult<TCustomOp extends EnumLikeType | unde
  *       }),
  *     },
  *     views: [
- *       [CoreResourceOperation.LIST, { isAddressable: true }],
- *       [opsVariantResolver(CoreResourceOperation.CREATE, 'quick-add'), { isAddressable: false }],
+ *       [CoreResourceOperation.LIST, addressable()],
+ *       [opsVariantResolver(CoreResourceOperation.CREATE, 'quick-add'), notAddressable()],
  *     ],
  *   }),
  * ),