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

package/dist/esm/components/resources/ResourceLayout_ContainerNested.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * ResourceLayoutPreset_ContainerNested_Default
  *
@@ -6,17 +6,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * It only renders child-direction relationships that actually expose a nested
  * read projection; pure reference-only edges stay outside this container.
  *
- * Display mode is determined by the relationship's split display contract:
- * - `display.inParentView` controls embedding / section rendering
- * - `display.inParentNavigation` controls relationship-owned navigation
+ * This container is the AUTOMATIC composition path, and it is deliberately
+ * unparameterized. A parent no longer configures how its children appear inside
+ * its own view — there is no per-edge composition config left to read. A view
+ * that wants anything other than the standard shape places its children itself
+ * (`RelatedResourceSections` / `EmbedRelatedResourceList`), and doing so silences
+ * this container entirely through the ownership registry.
  *
- * Behavior:
- * - `inParentNavigation.transition` = undefined → inline (embedded). Cardinality drives
- *   `contentSectionConfig.mode` when authors omit it:
- *   - 1:1 → SectionMode.INLINE
- *   - 1:N/N:N → SectionMode.TABS
- * - `inParentNavigation.transition` = set → navigation transition (split, push, overlay, etc.)
- * - `inParentView.hidden: true` → not rendered
+ * What the relationship still contributes is SEMANTICS, not composition:
+ * - `display.inParentNavigation.transition` = undefined → inline (embedded);
+ *   section shape follows CARDINALITY alone (1:1 → INLINE, 1:N/N:N → TABS)
+ * - `display.inParentNavigation.transition` = set → navigation transition
+ *   (split, push, overlay, …)
  *
  * Labels are handled by the i18n mechanism via tResourceHeader.
  *
@@ -43,24 +44,30 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Both checks use AND semantics — if both are present, both must pass.
  * Relationships without discriminator or condition are always rendered.
  */
-import { useMemo, useCallback, useState, useEffect, useRef } from 'react';
+import { useMemo, useCallback } from 'react';
 import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
 import { useI18n } from '../../core/i18n/useI18n.js';
+import { resolveResourceHeaderLabel } from '../../core/i18n/component-label-resolution.utils.js';
 import { frontendResourceUtils, FrontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
-import { pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperationFromOperation, } from '../../core/resources/operation-semantics.frontend.utils.js';
-import { CoreResourceOperation, ResourcesConfig_OperationPathUtils, getChildDirectionRelationships } from '@wildo-ai/saas-models';
+import { resolveEffectiveCoreOperationFromOperation, } from '../../core/resources/operation-semantics.frontend.utils.js';
+import { pickPreferredOperationForCoreSemanticAddressability } from '../../core/resources/resource-addressability.frontend.utils.js';
+import { CoreResourceOperation, getChildDirectionRelationships } from '@wildo-ai/saas-models';
 import { ResourceLayout_List } from '../../components/resources/ResourceLayout_List.js';
 import { ResourceAutomaticDisplayer } from '../../components/data-display/ResourceAutomaticDisplayer.js';
 import { Button, ButtonVariants_Variant } from '../../components/actions/button.js';
 import { ContentSectionContainer } from '../../components/sections/ContentSectionContainer.js';
+import { SectionHostHeadingContext } from './skeleton/SectionHostHeadingContext.js';
+import { EmbeddedResourceDescentBoundary } from './embeds/EmbeddedResourceDescent.js';
+import { useTemplateOwnsChildComposition, useReportAutomaticComposition } from './embeds/ComposedChildrenRegistry.js';
+import { pickAddressableChildListOperation, } from './embeds/child-operation-addressability.utils.js';
 import { SectionMode } from '@wildo-ai/zod-decorators';
 import { useNavigationController } from '../../core/navigation/useNavigationController.js';
 import { NavigationContentType } from '../../core/navigation/navigation.schemas.js';
 import { useUI } from '../../core/ui/useUI.js';
 import { createComponentResolver } from '../../core/components-registry/component-resolver.frontend.helper.js';
-import { FrontendComponentType, CorePresetNames, ButtonSize } from '@wildo-ai/presets-components-models';
+import { CorePresetNames, FrontendComponentType } from '@wildo-ai/presets-components-models';
 import { LoadingGate } from '../../core/loading/LoadingGate.js';
-import { LoadingSpinner } from '../../components/feedback/loading-spinner.js';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
 import { resolveRelationshipNestedReadSurface, } from '../../core/resources/relationship-surface-runtime.frontend.utils.js';
 /**
  * Check if a relationship represents a 1:1 (or 0:1) cardinality on the child side.
@@ -96,119 +103,57 @@ function groupRelationshipChildrenBySectionMode(configs) {
     }
     return { items };
 }
+/** Dedup guard for {@link warnUndisplayableChild} (runs per render). */
+const warnedUndisplayableChildren = new Set();
 /**
- * Lightweight inline preview for 1:N / N:N children when `inlineLimit` is set.
- *
- * Fetches `limit` items via the child's LIST operation, renders them as a
- * compact vertical list of resource display names, and optionally shows a
- * "View all (N total)" link that navigates to the full list.
- *
- * This avoids mounting the full `ResourceLayout_List` (with search, sort,
- * filter, pagination) when the relationship is configured for a quick preview.
+ * Warn (once per parent→child edge) when a child cannot even have a context
+ * derived for it — its LIST/READ operation is absent or ambiguous — so automatic
+ * composition skips it instead of crashing the parent surface.
  */
-function InlinePreview({ config, childContext, onViewAll, }) {
-    const { registry, doOperation } = useResourceRegistry();
-    const { tComponent } = useI18n({
-        component: FrontendComponentType.RESOURCES_LAYOUTS_CONTAINER_NESTED,
-        resource: childContext.resourceType,
-    });
-    const [items, setItems] = useState([]);
-    const [totalCount, setTotalCount] = useState(0);
-    const [isLoading, setIsLoading] = useState(true);
-    const [error, setError] = useState(null);
-    const doOperationRef = useRef(doOperation);
-    doOperationRef.current = doOperation;
-    const limit = config.inlineLimit;
-    // Stable key for the child context — prevents re-fetches when the parent
-    // re-renders and `deriveChildResourceContext` returns a new object ref
-    // with identical content.
-    const contextIdKey = useMemo(() => FrontendResourceUtils.buildContextResourceIdentifiersKey(childContext.contextResourceIdentifiers), [childContext.contextResourceIdentifiers]);
-    useEffect(() => {
-        // inlineLimit: 0 means "show no items, just the View All link"
-        if (limit === 0) {
-            setIsLoading(false);
-            return;
-        }
-        let cancelled = false;
-        const fetchPreview = async () => {
-            setIsLoading(true);
-            setError(null);
-            const childConfig = registry.resourceConfigurations[config.childResourceType];
-            const listOperation = childConfig
-                ? pickPreferredOperationForCoreSemantic(childConfig.operations ?? [], CoreResourceOperation.LIST)
-                : undefined;
-            if (!listOperation) {
-                setIsLoading(false);
-                return;
-            }
-            const operationPathKey = ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(listOperation);
-            const contextualParameters = FrontendResourceUtils.buildContextualParameters(childContext.contextResourceIdentifiers, registry);
-            try {
-                const result = await doOperationRef.current(operationPathKey, {
-                    contextualParameters,
-                    queryParameters: { page: 1, limit },
-                    parentResourcesRequirements: childContext.parentResourcesRequirements,
-                });
-                if (cancelled)
-                    return;
-                if (result && typeof result === 'object' && 'data' in result && 'pagination' in result) {
-                    const paginated = result;
-                    setItems(paginated.data);
-                    setTotalCount(paginated.pagination.total);
-                }
-                else if (Array.isArray(result)) {
-                    setItems(result);
-                    setTotalCount(result.length);
-                }
-            }
-            catch {
-                if (!cancelled)
-                    setError('Failed to load preview');
-            }
-            finally {
-                if (!cancelled)
-                    setIsLoading(false);
-            }
-        };
-        fetchPreview();
-        return () => { cancelled = true; };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [config.childResourceType, limit, registry, contextIdKey]);
-    if (isLoading) {
-        return (_jsx("div", { className: "flex items-center justify-center py-card-sm", children: _jsx(LoadingSpinner, { size: 20, className: "text-muted-foreground" }) }));
+function warnUndisplayableChild(parentResourceType, childResourceType, error) {
+    const edgeKey = `${parentResourceType}->${childResourceType}`;
+    if (warnedUndisplayableChildren.has(edgeKey)) {
+        return;
     }
-    if (error) {
-        return _jsx("p", { className: "text-sm text-destructive", children: error });
-    }
-    // inlineLimit: 0 → skip items, render only the "View all" quick-link
-    if (limit === 0) {
-        if (!config.showViewAllLink)
-            return null;
-        return (_jsx(Button, { variant: ButtonVariants_Variant.LINK, size: ButtonSize.SM, className: "px-0", onClick: onViewAll, children: tComponent(FrontendComponentType.RESOURCES_LAYOUTS_CONTAINER_NESTED, 'viewAll') || 'View all' }));
-    }
-    if (items.length === 0) {
-        return _jsx("p", { className: "text-sm text-muted-foreground", children: tComponent(FrontendComponentType.RESOURCES_LAYOUTS_CONTAINER_NESTED, 'emptyState') || 'No items' });
+    warnedUndisplayableChildren.add(edgeKey);
+    LoggerFrontendService.getLogger().warn(`[nested-container] "${edgeKey}" is not displayable and was SKIPPED: no unambiguous `
+        + `${'LIST/READ'} operation could be resolved for the child. The parent surface still renders. `
+        + `Cause: ${error instanceof Error ? error.message : String(error)}`);
+}
+/** Dedup guard for {@link warnAuthoredNestedSectionWithNoResolvableOperation} (runs per render). */
+const warnedNestedSectionsWithNoOperation = new Set();
+/**
+ * Warn (once per parent→child edge) when the author declared an
+ * `inParentView.contentSectionConfig` (a nested section) but no addressable
+ * READ/LIST operation resolves for the child in the current parent context, so
+ * the section renders nothing. Complements the read-model-eligibility warning in
+ * `resolveRelationshipNestedReadSurface` — this catches the ELIGIBLE-but-
+ * unrenderable case (e.g. a child whose LIST is `contextPolicy`-disabled).
+ */
+function warnAuthoredNestedSectionWithNoResolvableOperation(parentResourceType, surface) {
+    const edgeKey = `${parentResourceType}->${surface.childResourceType}`;
+    if (warnedNestedSectionsWithNoOperation.has(edgeKey)) {
+        return;
     }
-    const hasMore = totalCount > limit;
-    return (_jsxs("div", { className: "space-y-xs", children: [_jsx("ul", { className: "space-y-xs", children: items.map((item, idx) => {
-                    const id = item._id ?? item.id ?? idx;
-                    const label = FrontendResourceUtils.computeFrontendResourceLabel({
-                        resourceType: config.childResourceType,
-                        registry,
-                        currentObject: item,
-                    }) ?? String(id);
-                    return (_jsx("li", { className: "text-sm px-sm py-xs rounded-radius border border-border bg-card", children: label }, id));
-                }) }), config.showViewAllLink && hasMore && (_jsxs(Button, { variant: ButtonVariants_Variant.LINK, size: ButtonSize.SM, className: "px-0", onClick: onViewAll, children: [tComponent(FrontendComponentType.RESOURCES_LAYOUTS_CONTAINER_NESTED, 'viewAll') || 'View all', " (", totalCount, ")"] }))] }));
+    warnedNestedSectionsWithNoOperation.add(edgeKey);
+    LoggerFrontendService.getLogger().warn(`[nested-container] owned child "${edgeKey}" composes NOTHING: no addressable `
+        + `${surface.isOneToOne ? 'READ' : 'LIST'} operation resolves for the child in this parent context. Common cause: the `
+        + 'child operation is contextPolicy-disabled (e.g. operationOverrides.LIST.enabled=false) or not addressable here. '
+        + 'Surface the child explicitly (a composite view / EmbedRelatedResourceOperation) or enable the operation.');
 }
 export const ResourceLayoutPreset_ContainerNested_Default = ({ resourceContext, navigationZone, navigationInitiator, parentData, }) => {
     const { resourceType } = resourceContext;
     const { registry } = useResourceRegistry();
-    const { tResourceHeader } = useI18n({
+    const { tResourceHeader, isReady } = useI18n({
         component: FrontendComponentType.RESOURCES_LAYOUTS_CONTAINER_NESTED,
         resource: resourceType,
     });
     const { navigate } = useNavigationController();
     const { currentBreakpoint } = useUI();
+    // D1/D12 — did the view template compose the child region itself? Read during
+    // render, in the same pass the template registered (this container renders
+    // after the displayer that hosts the template).
+    const templateOwnsChildComposition = useTemplateOwnsChildComposition();
     const i18nKeys = useMemo(() => [
         `resources.${resourceType}`,
         `components.${FrontendComponentType.RESOURCES_LAYOUTS_CONTAINER_NESTED}`,
@@ -245,22 +190,84 @@ export const ResourceLayoutPreset_ContainerNested_Default = ({ resourceContext,
                 continue;
             // Check if child has a displayable operation (LIST for 1:N, READ for 1:1)
             const isChildOneToOne = nestedReadSurface.isOneToOne;
+            // This enumeration is SPECULATIVE: it walks every owned child of the parent
+            // and asks whether each could be displayed. `deriveChildResourceContext` is
+            // strict by design — it THROWS when the requested operation is absent or
+            // ambiguous on the child — which is right for a caller that named one
+            // resource deliberately, and wrong here, where an unresolvable candidate is
+            // simply not displayable.
+            //
+            // Left unguarded, ONE such child takes down the entire parent surface: the
+            // whole record page renders "Surface unavailable", not just the section that
+            // could not resolve. That is what an organization's settings page did — the
+            // container never ran for engine resources until the ownership gate was
+            // fixed, so the crash arrived with the capability rather than with any
+            // change to this derivation.
+            //
+            // Skipping matches the posture two lines below, where a child with no
+            // ADDRESSABLE operation is skipped with a warning rather than thrown on.
+            let preliminaryChildContext;
+            try {
+                preliminaryChildContext = frontendResourceUtils.deriveChildResourceContext(resourceContext, {
+                    resourceType: childResourceType,
+                    operationIdentifier: isChildOneToOne ? CoreResourceOperation.READ : CoreResourceOperation.LIST,
+                    relationshipFieldOverrides: {
+                        [resourceType]: nestedReadSurface.foreignKeyField,
+                    },
+                }, registry);
+            }
+            catch (error) {
+                warnUndisplayableChild(resourceType, childResourceType, error);
+                continue;
+            }
+            const preliminaryContextualParameters = FrontendResourceUtils.buildContextualParameters(preliminaryChildContext.contextResourceIdentifiers, registry);
             const displayOperation = isChildOneToOne
-                ? pickPreferredOperationForCoreSemantic(childConfig.operations ?? [], CoreResourceOperation.READ)
-                    ?? pickPreferredOperationForCoreSemantic(childConfig.operations ?? [], CoreResourceOperation.LIST)
-                : pickPreferredOperationForCoreSemantic(childConfig.operations ?? [], CoreResourceOperation.LIST);
-            if (!displayOperation)
+                ? pickPreferredOperationForCoreSemanticAddressability({
+                    resourceConfig: childConfig,
+                    operations: childConfig.operations ?? [],
+                    coreOperation: CoreResourceOperation.READ,
+                    registry,
+                    hasResourceId: Boolean(frontendResourceUtils.getResourceId(preliminaryChildContext.contextResourceIdentifiers?.[childResourceType])),
+                    contextResourceIdentifiers: preliminaryChildContext.contextResourceIdentifiers,
+                    contextualParameters: preliminaryContextualParameters,
+                })
+                : preliminaryChildContext && preliminaryContextualParameters
+                    ? pickAddressableChildListOperation({
+                        operations: childConfig.operations ?? [],
+                        childContext: preliminaryChildContext,
+                        contextualParameters: preliminaryContextualParameters,
+                    })
+                    : undefined;
+            if (!displayOperation) {
+                // The relationship is nested-read-ELIGIBLE (it produced a surface) but no
+                // addressable READ/LIST operation resolves for the child in THIS parent
+                // context — so an authored `inParentView.contentSectionConfig` renders
+                // nothing. Warn loudly (this is the gap the read-model-only F3 warning in
+                // `resolveRelationshipNestedReadSurface` misses — e.g. `todos→tasks` with
+                // `contextPolicy.operationOverrides.LIST.enabled = false`).
+                warnAuthoredNestedSectionWithNoResolvableOperation(resourceType, nestedReadSurface);
                 continue;
-            const label = tResourceHeader(childResourceType, 'title') || childResourceType;
+            }
+            const label = resolveResourceHeaderLabel({
+                tResourceHeader,
+                resourceType: childResourceType,
+                key: 'title',
+            });
             configs.push({
                 ...nestedReadSurface,
                 label,
             });
         }
-        // Sort by orderIndex
-        configs.sort((a, b) => a.orderIndex - b.orderIndex);
+        // Registration order. `orderIndex` is gone: ordering an automatic block was
+        // the config axis's job, and a view that cares about order places its
+        // children itself, where order is simply the order they are written in.
         return configs;
-    }, [childRelationships, registry, resourceType, tResourceHeader, parentData, currentBreakpoint]);
+        // `composedByTemplate` is a ref-backed Set with a STABLE identity, so it cannot
+        // serve as a dependency — it is read during this render and reflects the pass
+        // the template just registered in. The memo is recomputed by `parentData`,
+        // which is precisely what changes when a data-conditional template starts
+        // placing a child.
+    }, [childRelationships, registry, resourceContext, resourceType, tResourceHeader, parentData, currentBreakpoint]);
     const groupedChildren = useMemo(() => groupRelationshipChildrenBySectionMode(childConfigs), [childConfigs]);
     // Resolve parent resource ID from contextResourceIdentifiers (used by inline context + pane-targeted nav)
     const parentResourceId = useMemo(() => {
@@ -271,29 +278,72 @@ export const ResourceLayoutPreset_ContainerNested_Default = ({ resourceContext,
             return identifier;
         return identifier.resourceId;
     }, [resourceContext.contextResourceIdentifiers, resourceType]);
+    const deriveChildContextWithOperation = useCallback((config, operation) => frontendResourceUtils.deriveChildResourceContext(resourceContext, {
+        resourceType: config.childResourceType,
+        operationIdentifier: String(operation.operationIdentifier),
+        operation,
+        relationshipFieldOverrides: {
+            // Reuse the exact edge we are rendering, especially for same-type or
+            // duplicate child relationships. Otherwise child context derivation may
+            // know the parent type but still lose which FK path got us here.
+            [resourceType]: config.foreignKeyField,
+        },
+    }, registry), [registry, resourceContext, resourceType]);
+    const resolveAddressableChildReadOperation = useCallback((config) => {
+        const childResourceConfig = registry.resourceConfigurations[config.childResourceType];
+        if (!childResourceConfig) {
+            return undefined;
+        }
+        const preliminaryContext = frontendResourceUtils.deriveChildResourceContext(resourceContext, {
+            resourceType: config.childResourceType,
+            operationIdentifier: CoreResourceOperation.READ,
+            relationshipFieldOverrides: {
+                [resourceType]: config.foreignKeyField,
+            },
+        }, registry);
+        const contextualParameters = FrontendResourceUtils.buildContextualParameters(preliminaryContext.contextResourceIdentifiers, registry);
+        return pickPreferredOperationForCoreSemanticAddressability({
+            resourceConfig: childResourceConfig,
+            operations: childResourceConfig.operations ?? [],
+            coreOperation: CoreResourceOperation.READ,
+            registry,
+            hasResourceId: Boolean(frontendResourceUtils.getResourceId(preliminaryContext.contextResourceIdentifiers?.[config.childResourceType])),
+            contextResourceIdentifiers: preliminaryContext.contextResourceIdentifiers,
+            contextualParameters,
+        });
+    }, [registry, resourceContext, resourceType]);
+    const resolveAddressableChildListOperation = useCallback((config) => {
+        const childResourceConfig = registry.resourceConfigurations[config.childResourceType];
+        if (!childResourceConfig) {
+            return undefined;
+        }
+        const preliminaryContext = frontendResourceUtils.deriveChildResourceContext(resourceContext, {
+            resourceType: config.childResourceType,
+            operationIdentifier: CoreResourceOperation.LIST,
+            relationshipFieldOverrides: {
+                [resourceType]: config.foreignKeyField,
+            },
+        }, registry);
+        const contextualParameters = FrontendResourceUtils.buildContextualParameters(preliminaryContext.contextResourceIdentifiers, registry);
+        return pickAddressableChildListOperation({
+            operations: childResourceConfig.operations ?? [],
+            childContext: preliminaryContext,
+            contextualParameters,
+        });
+    }, [registry, resourceContext, resourceType]);
     // Navigate to a child resource's full LIST view.
-    // Used by: InlinePreview "View all" link and navigation-intent child buttons.
+    // Used by: the related-resource preview's "view all" link and navigation-intent child buttons.
     // The v3 resolver determines zone + transition from the layout config + source zone.
     const handleNavigateChild = useCallback((config) => {
         const childResourceConfig = registry.resourceConfigurations[config.childResourceType];
         const targetOperation = childResourceConfig
             ? (config.isOneToOne
-                ? pickPreferredOperationForCoreSemantic(childResourceConfig.operations ?? [], CoreResourceOperation.READ)
-                    ?? pickPreferredOperationForCoreSemantic(childResourceConfig.operations ?? [], CoreResourceOperation.LIST)
-                : pickPreferredOperationForCoreSemantic(childResourceConfig.operations ?? [], CoreResourceOperation.LIST))
+                ? resolveAddressableChildReadOperation(config)
+                : resolveAddressableChildListOperation(config))
             : undefined;
         if (!targetOperation)
             return;
-        const childContext = frontendResourceUtils.deriveChildResourceContext(resourceContext, {
-            resourceType: config.childResourceType,
-            operationIdentifier: String(targetOperation.operationIdentifier),
-            relationshipFieldOverrides: {
-                // Reuse the exact edge we are rendering, especially for same-type or
-                // duplicate child relationships. Otherwise child context derivation may
-                // know the parent type but still lose which FK path got us here.
-                [resourceType]: config.foreignKeyField,
-            },
-        }, registry);
+        const childContext = deriveChildContextWithOperation(config, targetOperation);
         navigate({
             content: {
                 contentType: NavigationContentType.RESOURCE_OPERATION,
@@ -313,11 +363,16 @@ export const ResourceLayoutPreset_ContainerNested_Default = ({ resourceContext,
             },
             relationshipTransition: config.transition,
         });
-    }, [registry, resourceContext, navigate, navigationZone, resourceType, parentResourceId]);
-    // If no children, render nothing
-    if (childConfigs.length === 0) {
-        return null;
-    }
+    }, [
+        deriveChildContextWithOperation,
+        registry,
+        navigate,
+        navigationZone,
+        resourceType,
+        parentResourceId,
+        resolveAddressableChildReadOperation,
+        resolveAddressableChildListOperation,
+    ]);
     // Render a child resource — list for 1:N/N:N, single display for 1:1
     const renderChild = (config) => {
         if (config.transition) {
@@ -327,43 +382,27 @@ export const ResourceLayoutPreset_ContainerNested_Default = ({ resourceContext,
         if (isOneToOne(config)) {
             // 1:1 relationship — render as a single resource display via READ
             const readOperation = childResourceConfig
-                ? pickPreferredOperationForCoreSemantic(childResourceConfig.operations ?? [], CoreResourceOperation.READ)
+                ? resolveAddressableChildReadOperation(config)
                 : undefined;
             if (readOperation) {
                 // Derive child context with READ operation
-                const childContext = frontendResourceUtils.deriveChildResourceContext(resourceContext, {
-                    resourceType: config.childResourceType,
-                    operationIdentifier: String(readOperation.operationIdentifier),
-                    relationshipFieldOverrides: {
-                        // READ needs the same override for the same reason as LIST: keep the
-                        // rendered child context attached to this concrete relationship edge.
-                        [resourceType]: config.foreignKeyField,
-                    },
-                }, registry);
+                const childContext = deriveChildContextWithOperation(config, readOperation);
                 return (_jsx(ResourceAutomaticDisplayer, { resourceContext: childContext }, config.relationshipEdgeKey));
             }
-            // Fallback: if no READ operation, use LIST (renders as single-item list)
+            return null;
         }
         const listOperation = childResourceConfig
-            ? pickPreferredOperationForCoreSemantic(childResourceConfig.operations ?? [], CoreResourceOperation.LIST)
+            ? resolveAddressableChildListOperation(config)
             : undefined;
         if (!listOperation)
             return null;
         // Create child context with parent filter (LIST-like operation)
-        const childContext = frontendResourceUtils.deriveChildResourceContext(resourceContext, {
-            resourceType: config.childResourceType,
-            operationIdentifier: String(listOperation.operationIdentifier),
-            relationshipFieldOverrides: {
-                // Inline list rendering must preserve the edge identity too, otherwise
-                // later route / initiator selection would fall back to resource-type
-                // heuristics for same-type children.
-                [resourceType]: config.foreignKeyField,
-            },
-        }, registry);
-        // When inlineLimit is configured, render a compact preview instead of the full list
-        if (config.inlineLimit !== undefined) {
-            return (_jsx(InlinePreview, { config: config, childContext: childContext, onViewAll: () => handleNavigateChild(config) }, config.relationshipEdgeKey));
-        }
+        const childContext = deriveChildContextWithOperation(config, listOperation);
+        // No preview branch here any more. Automatic composition renders the child's
+        // full LIST surface; a compact preview is a DELIBERATE choice, so it is made
+        // where deliberate choices live — a template placing `<RelatedResourcePreview>`.
+        // It used to be selected by an `inParentView.inlineLimit` key that nothing in
+        // the repository ever authored, which is how the capability stayed dark.
         const childInlineParentContext = {
             parentResourceType: resourceType,
             parentResourceId,
@@ -381,8 +420,57 @@ export const ResourceLayoutPreset_ContainerNested_Default = ({ resourceContext,
     const buildRelationshipContentSection = useCallback((config) => ({
         id: config.relationshipEdgeKey,
         title: config.label,
-        content: renderChild(config),
-    }), [renderChild]);
+        // This host renders a visible heading for the region (`title` above), so the
+        // embedded child surface must not stack its OWN standalone page chrome under
+        // it — its generic heading, its description and its parent breadcrumb all
+        // restate what the section title and the surrounding record already say.
+        // Threading the heading context is what every other section-grouping host
+        // does (FormLayout / DisplayLayout / CompositeLayout pass `providesHeading`);
+        // this one never did, which was invisible only because the nested container
+        // could not render at all.
+        content: (
+        // D9 — each automatically-composed child is a level of DESCENT, bounded
+        // exactly like an explicitly embedded one. Keyed on `(edge, parent row)`:
+        // a self-referencing hierarchy walks the SAME edge over DIFFERENT rows and
+        // must keep descending, while the same record reached twice is a cycle.
+        // Self edges are in scope — `getChildDirectionRelationships` returns
+        // `[...childRelationships, ...selfRelationships]`, so `Category → Category`
+        // already renders itself as a section today.
+        _jsx(EmbeddedResourceDescentBoundary, { descentKey: `nested:${config.relationshipEdgeKey}::${parentResourceId || 'no-row'}`, children: _jsx(SectionHostHeadingContext.Provider, { value: true, children: renderChild(config) }) })),
+    }), [renderChild, parentResourceId]);
+    // MOVED here (was above `renderChild`, before the `useCallback` below it) to fix a
+    // Rules-of-Hooks violation: returning early while a hook still followed meant a
+    // render with no children called ONE FEWER hook than a render with children.
+    //
+    // Not theoretical. `childConfigs` is derived from `parentData`, and a conditional
+    // or discriminated relationship is DEFERRED while `parentData` is undefined (see
+    // the header). So on a resource whose child relationships are ALL conditional, the
+    // first render returned early and the second — once `parentData` arrived — called
+    // the extra hook, which is React's "Rendered more hooks than during the previous
+    // render." A resource with any unconditional child never reached it, which is why
+    // it survived unnoticed. `rules-of-hooks` would have caught it; lint does not run
+    // in this repository.
+    //
+    // Every guard now sits together, AFTER the last hook. Keep it that way.
+    // Report what this container actually DID, for the provider's post-commit
+    // duplication check. `true` only on the path that reaches the render below.
+    useReportAutomaticComposition(childConfigs.length > 0 && isReady && !templateOwnsChildComposition);
+    if (childConfigs.length === 0)
+        return null;
+    if (!isReady)
+        return null;
+    // D12 — the template composed the child region itself, so this automatic block
+    // stands down ENTIRELY rather than appending the children it did not place.
+    // Same contract an authored `layout.display` already has for fields: the
+    // template REPLACES the generated surface, it is not merged with it. Merging
+    // is what would require a per-edge suppression flag on every relationship a
+    // parent chose not to show — the configuration axis this design removes.
+    //
+    // Note it does NOT touch `resolveRelationshipNestedReadSurface`, so raw
+    // relationship-object-field hiding stays independent of placement: omitting a
+    // child hides it rather than downgrading it to a raw array in the body.
+    if (templateOwnsChildComposition)
+        return null;
     return (_jsx(LoadingGate, { i18nKeys: i18nKeys, children: _jsx("div", { className: "space-y-section", children: groupedChildren.items.map((item, index) => (item.type === 'single'
                 ? (_jsx(ContentSectionContainer, { config: {
                         ...item.config.contentSectionConfig,
@@ -396,4 +484,4 @@ export function ResourceLayout_ContainerNested({ preset = CorePresetNames.DEFAUL
     const Component = createComponentResolver(FrontendComponentType.RESOURCES_LAYOUTS_CONTAINER_NESTED, 'ResourceLayout_ContainerNested')(preset);
     return _jsx(Component, { ...props });
 }
-//# sourceMappingURL=ResourceLayout_ContainerNested.js.map
+//# sourceMappingURL=ResourceLayout_ContainerNested.js.map