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

package/dist/esm/components/resources/collection-view-mode.frontend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-view-mode.frontend.js","sourceRoot":"","sources":["../../../../../src/components/resources/collection-view-mode.frontend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,iEAAiE,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+DAA+D,CAAC;AAEtG,MAAM,wBAAwB,GAAG,6BAA6B,CAAC;AAE/D,SAAS,kBAAkB,CAAC,YAAoB;IAC9C,OAAO,GAAG,wBAAwB,GAAG,YAAY,EAAE,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,MAAM,GAAG,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC;IAClE,IAAI,GAAG,KAAK,qBAAqB,CAAC,KAAK,IAAI,GAAG,KAAK,qBAAqB,CAAC,KAAK,EAAE,CAAC;QAC/E,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAAC,YAAoB,EAAE,IAA2B;IAC/E,mBAAmB,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,CAAC;AAC9D,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,YAAoB,EAAE,WAAkC;IAClF,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAC3C,GAAG,EAAE,CAAC,qBAAqB,CAAC,YAAY,CAAC,IAAI,WAAW,CACzD,CAAC;IAEF,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,IAA2B,EAAQ,EAAE;QACpE,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACvB,eAAe,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAEnB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC","sourcesContent":["/**\n * Collection view-mode state — the runtime \"cards vs table\" display choice for a\n * resource collection view.\n *\n * The DEFAULT mode for a resource comes from its LIST/SEARCH operation's\n * `collectionDisplayConfig.displayMode` (authored in the resource UI behavior),\n * falling back to its registered preset seed. The user's toggle OVERRIDES that\n * default and PERSISTS per resource type, so a chosen display sticks across\n * navigations and reloads while the config still seeds the first view.\n *\n * The display vocabulary is `CollectionDisplayMode` (CARDS|TABLE), owned by the\n * frontend core schema (`resources.frontend.schemas.ts`) — these persistence\n * helpers are the runtime side of that vocabulary.\n *\n * Persistence goes through the framework's single storage abstraction\n * (`getLocalStorageItem`/`setLocalStorageItem`), which fails closed when storage\n * is unavailable (e.g. the companion's Node introspection render) — so reads fall\n * back to the supplied default and the hook never throws off-browser.\n */\n\nimport { useCallback, useState } from 'react';\nimport {\n  getLocalStorageItem,\n  setLocalStorageItem,\n} from '~wildo-frontend-lib/core/commons/local-storage.frontend.schemas';\nimport { CollectionDisplayMode } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\n\nconst VIEW_MODE_STORAGE_PREFIX = 'wildo-collection-view-mode:';\n\nfunction viewModeStorageKey(resourceType: string): string {\n  return `${VIEW_MODE_STORAGE_PREFIX}${resourceType}`;\n}\n\n/**\n * The persisted display mode for a resource type, or `null` when none is stored\n * (first visit) or storage is unavailable. Validated against the enum so a\n * tampered/legacy value never leaks through.\n */\nexport function readPersistedViewMode(resourceType: string): CollectionDisplayMode | null {\n  const raw = getLocalStorageItem(viewModeStorageKey(resourceType));\n  if (raw === CollectionDisplayMode.CARDS || raw === CollectionDisplayMode.TABLE) {\n    return raw;\n  }\n  return null;\n}\n\n/** Persist the user's display-mode choice for a resource type. */\nexport function persistViewMode(resourceType: string, mode: CollectionDisplayMode): void {\n  setLocalStorageItem(viewModeStorageKey(resourceType), mode);\n}\n\nexport interface UseViewModeResult {\n  /** The active display mode (persisted choice if any, else the seeded default). */\n  viewMode: CollectionDisplayMode;\n  /** Set + persist the display mode for this resource type. */\n  setViewMode: (mode: CollectionDisplayMode) => void;\n}\n\n/**\n * Display-mode state for a collection: seeds from the persisted choice (falling\n * back to the config-derived `defaultMode`) and persists on change.\n *\n * `resourceType` is stable per mounted collection, so the lazy initializer reads\n * storage exactly once.\n */\nexport function useViewMode(resourceType: string, defaultMode: CollectionDisplayMode): UseViewModeResult {\n  const [viewMode, setViewModeState] = useState<CollectionDisplayMode>(\n    () => readPersistedViewMode(resourceType) ?? defaultMode,\n  );\n\n  const setViewMode = useCallback((mode: CollectionDisplayMode): void => {\n    setViewModeState(mode);\n    persistViewMode(resourceType, mode);\n  }, [resourceType]);\n\n  return { viewMode, setViewMode };\n}\n"]}

package/dist/esm/components/resources/component-props.resources-layout.frontend.schemas.d.ts

@@ -1,6 +1,6 @@
 import type { NavigationTransition } from '@wildo-ai/saas-models';
-import { FrontendResourceOperationContext } from '../../core/resources/resources.frontend.schemas.js';
-import type { NavigationZone, NavigationInitiatorContext } from '../../core/navigation/navigation.schemas.js';
+import { FrontendResourceOperationContext } from '../../core/resources/resources.frontend.schemas';
+import type { NavigationZone, NavigationInitiatorContext } from '../../core/navigation/navigation.schemas';
 /**
  * Context provided to inline children when rendered within a parent view
  * by ContainerNested. Allows children to detect they're embedded inline

package/dist/esm/components/resources/component-props.resources-layout.frontend.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-props.resources-layout.frontend.schemas.d.ts","sourceRoot":"","sources":["../../../../src/components/resources/component-props.resources-layout.frontend.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,gCAAgC,EAAE,MAAM,+DAA+D,CAAC;AACjH,OAAO,KAAK,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,wDAAwD,CAAC;AAEzH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,gCAAgC,CAAC;IAClD,cAAc,EAAE,cAAc,CAAC;IAC/B,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;IACjD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED,eAAO,MAAM,sBAAsB,2BAA2B,CAAA"}
+{"version":3,"file":"component-props.resources-layout.frontend.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/components/resources/component-props.resources-layout.frontend.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,gCAAgC,EAAE,MAAM,+DAA+D,CAAC;AACjH,OAAO,KAAK,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,wDAAwD,CAAC;AAEzH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,gCAAgC,CAAC;IAClD,cAAc,EAAE,cAAc,CAAC;IAC/B,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;IACjD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED,eAAO,MAAM,sBAAsB,2BAA2B,CAAA"}

package/dist/esm/components/resources/component-props.resources-layout.frontend.schemas.js

@@ -1,2 +1,2 @@
 export const thingsToLetModuleWorks = "thingsToLetModuleWorks";
-//# sourceMappingURL=component-props.resources-layout.frontend.schemas.js.map
+//# sourceMappingURL=component-props.resources-layout.frontend.schemas.js.map

package/dist/esm/components/resources/component-props.resources-layout.frontend.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"component-props.resources-layout.frontend.schemas.js","sourceRoot":"","sources":["../../../../src/components/resources/component-props.resources-layout.frontend.schemas.ts"],"names":[],"mappings":"AAkCA,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAA"}
+{"version":3,"file":"component-props.resources-layout.frontend.schemas.js","sourceRoot":"","sources":["../../../../../src/components/resources/component-props.resources-layout.frontend.schemas.ts"],"names":[],"mappings":"AAkCA,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAA","sourcesContent":["import type { NavigationTransition } from '@wildo-ai/saas-models';\nimport { FrontendResourceOperationContext } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport type { NavigationZone, NavigationInitiatorContext } from '~wildo-frontend-lib/core/navigation/navigation.schemas';\n\n/**\n * Context provided to inline children when rendered within a parent view\n * by ContainerNested. Allows children to detect they're embedded inline\n * (parent is already visible above) and skip redundant parent references.\n */\nexport interface InlineParentContext {\n  /** The parent resource type (e.g., 'ORGANIZATIONS') */\n  parentResourceType: string;\n  /** The parent resource ID (from contextResourceIdentifiers) */\n  parentResourceId?: string;\n  /**\n   * When set, the child was opened via a navigation transition (not embedded inline).\n   * Undefined means the child is embedded inline (the v3 default).\n   */\n  transition?: NavigationTransition;\n}\n\nexport interface BaseResourcesLayoutProps {\n  resourceContext: FrontendResourceOperationContext;\n  navigationZone: NavigationZone;\n  navigationInitiator?: NavigationInitiatorContext;\n  /**\n   * Set by ContainerNested when rendering inline children (embedded, no transition).\n   * When present, the child knows it's rendered within a parent view and can:\n   * - Skip showing a redundant parent reference (parent is visible above)\n   * - Access the parent resource type and ID for relationship-aware behavior\n   */\n  inlineParentContext?: InlineParentContext;\n}\n\nexport const thingsToLetModuleWorks = \"thingsToLetModuleWorks\"\n"]}

package/dist/esm/components/resources/embeds/ComposedChildrenRegistry.d.ts

@@ -0,0 +1,135 @@
+import React from 'react';
+/**
+ * Records whether a view TEMPLATE composed the child region itself, so the
+ * automatic composition that follows stands down entirely.
+ *
+ * ## Whole-surface ownership, not a per-child merge
+ *
+ * If the template placed ANY child, it owns the child region and the automatic
+ * block renders nothing. This mirrors how an authored `layout.display` REPLACES
+ * the generated field template rather than being merged with it
+ * (`ResourceAutomaticDisplayer`: `if (explicitDisplayTemplate) return
+ * explicitDisplayTemplate;` — there is no per-field "the framework also appends
+ * the ones you did not place", and nobody has ever wanted one).
+ *
+ * Children behaving differently is what would FORCE a per-edge suppression flag
+ * back into the relationship: a parent placing 3 of its 33 owned children would
+ * otherwise auto-compose the other 30, and the only way to stop that is a flag
+ * on each edge. Whole-surface ownership is precisely what makes that
+ * configuration axis unnecessary — two modes (standard, or the template), never
+ * three.
+ *
+ * The signal is PLACEMENT, not the mere existence of a template. A field-only
+ * `layout.display` — Wonder Todos' `todoLists` is exactly that — places no child
+ * and must keep its standard child block. Keying on existence would silently
+ * delete content from every field-only template in the repository.
+ *
+ * ## The handshake, and why it can work at all
+ *
+ * A resource READ surface renders in one pass, in order: the header, then the
+ * displayer (inside which the authored `layout.display` template runs, and with
+ * it any child embeds it places), and only then the automatic children
+ * container. So a placement registered during the template's render is already
+ * visible when the container renders in that same pass. The ordering is not
+ * incidental — it is the whole mechanism, and moving the container above the
+ * displayer would silently break it.
+ *
+ * ## Why a ref-backed set rather than state
+ *
+ * Registration must not schedule a re-render: the template registers DURING
+ * render, and setting state there is illegal. The set is cleared at the start of
+ * every host render and refilled by that render's template, so it always
+ * describes the current pass rather than accumulating across passes — which is
+ * what makes a child REMOVED from a template stop being suppressed.
+ *
+ * ## The one case that does not resolve within a single pass
+ *
+ * A template that places a child CONDITIONALLY on loaded record data places
+ * nothing on the first pass, so the container composes that child automatically;
+ * when the data arrives the host re-renders, the template registers, and the
+ * container skips it. The child therefore renders automatically for the frames
+ * before data lands. It self-corrects, and the container already defers
+ * conditional relationships while `parentData` is undefined for the same
+ * "avoid a flash of content" reason — but a template that wants no flicker at
+ * all should place its child unconditionally and let the child's own surface
+ * handle its empty state.
+ */
+export interface ComposedChildrenRegistryValue {
+    /**
+     * Child resource types placed by the template in the CURRENT render pass.
+     * Mutable by design — see the class comment on why this is a ref and not state.
+     */
+    placed: Set<string>;
+    /**
+     * Ownership CLAIMED explicitly, independently of how many children were placed.
+     *
+     * Placement alone cannot express "this surface composes NO children": a template
+     * that places nothing is indistinguishable from one that never decided, and the
+     * latter must keep composing automatically. Real surfaces need the distinction —
+     * an embedded application READ deliberately shows none of its nine owned
+     * children, which is what nine `hidden: true` entries used to say.
+     */
+    owned: {
+        current: boolean;
+    };
+    /**
+     * Whether the automatic container actually COMPOSED children this pass.
+     *
+     * The handshake is render-phase — placements mutate `placed`/`owned` while they
+     * render, the container reads the answer while IT renders — so it only works
+     * because the container renders AFTER the template. That holds today
+     * (`ResourceLayout_Read` renders `{children}` immediately before
+     * `ResourceLayout_ContainerNested`) and nothing in the type system enforces it;
+     * swap those two JSX siblings and every child renders TWICE, silently.
+     *
+     * The detection is deliberately an OUTCOME, checked after commit, rather than a
+     * render-order tripwire. A first attempt marked the pass as soon as the question
+     * was asked and warned on any later placement — which fired spuriously the moment
+     * anything re-rendered WITHOUT the provider (an error boundary recovering, most
+     * visibly), because the flag was then left over from the previous pass. A
+     * diagnostic that cries wolf gets ignored, so this one asks the only question
+     * that is actually a defect: did the container compose children AND a template
+     * claim the region? That is duplication, whatever order they rendered in.
+     */
+    composedAutomatically: {
+        current: boolean;
+    };
+}
+export interface ComposedChildrenRegistryProviderProps {
+    children: React.ReactNode;
+}
+/**
+ * Hosts an ownership handshake for one render pass of one record surface.
+ *
+ * Clears the set on every render so the registry describes THIS pass. The
+ * context value is identity-stable across renders (the ref wrapper), so
+ * providing it costs no extra re-render of the subtree.
+ */
+export declare function ComposedChildrenRegistryProvider({ children, }: ComposedChildrenRegistryProviderProps): React.JSX.Element;
+export declare function useRegisterComposedChild(childResourceType: string | undefined): void;
+/**
+ * `true` when the template composed the child region itself, in which case the
+ * automatic container renders nothing.
+ *
+ * `false` with no host, so a surface without the handshake composes normally —
+ * the pre-existing behaviour, unchanged.
+ */
+export declare function useTemplateOwnsChildComposition(): boolean;
+/**
+ * Claim the child region for the template, whatever it ends up containing.
+ *
+ * Called by the placement primitive so that naming ZERO children is a decision
+ * ("this surface composes none") rather than an absence of one ("nobody said, so
+ * compose them all"). Without it, the only way to express "no children" is a
+ * per-edge opt-out on every relationship — the configuration axis this design
+ * exists to remove.
+ */
+export declare function useClaimChildComposition(): void;
+/**
+ * Called by the automatic container to record what it DID this pass. Paired with
+ * the provider's post-commit check: "container composed" plus "template claimed"
+ * is duplication, and is the only combination worth reporting.
+ */
+export declare function useReportAutomaticComposition(composed: boolean): void;
+export declare function useComposedChildren(): ReadonlySet<string>;
+//# sourceMappingURL=ComposedChildrenRegistry.d.ts.map

package/dist/esm/components/resources/embeds/ComposedChildrenRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComposedChildrenRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/components/resources/embeds/ComposedChildrenRegistry.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAgE,MAAM,OAAO,CAAC;AAGrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB;;;;;;;;OAQG;IACH,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBAAqB,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7C;AAID,MAAM,WAAW,qCAAqC;IACpD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,EAC/C,QAAQ,GACT,EAAE,qCAAqC,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA6B3D;AAwBD,wBAAgB,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKpF;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,IAAI,OAAO,CAIzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAK/C;AASD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAKrE;AAED,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,MAAM,CAAC,CAGzD"}

package/dist/esm/components/resources/embeds/ComposedChildrenRegistry.js

@@ -0,0 +1,110 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useRef } from 'react';
+import { LoggerFrontendService } from '../../../core/monitoring/logger.frontend.service.js';
+const ComposedChildrenRegistryContext = createContext(null);
+/**
+ * Hosts an ownership handshake for one render pass of one record surface.
+ *
+ * Clears the set on every render so the registry describes THIS pass. The
+ * context value is identity-stable across renders (the ref wrapper), so
+ * providing it costs no extra re-render of the subtree.
+ */
+export function ComposedChildrenRegistryProvider({ children, }) {
+    const ref = useRef({
+        placed: new Set(),
+        owned: { current: false },
+        composedAutomatically: { current: false },
+    });
+    // Cleared during render, before any descendant registers — descendants render
+    // strictly after this component's body, so nothing registered this pass is lost.
+    ref.current.placed.clear();
+    ref.current.owned.current = false;
+    ref.current.composedAutomatically.current = false;
+    const value = useMemo(() => ref.current, []);
+    // After commit, so render ORDER is irrelevant and only the outcome is judged.
+    useEffect(() => {
+        const registry = ref.current;
+        if (!registry.composedAutomatically.current) {
+            return;
+        }
+        if (registry.owned.current || registry.placed.size > 0) {
+            warnDuplicatedChildComposition([...registry.placed]);
+        }
+    });
+    return (_jsx(ComposedChildrenRegistryContext.Provider, { value: value, children: children }));
+}
+/**
+ * Called by an embed while it renders, to claim a child on behalf of the
+ * template that placed it. A no-op outside a registry host (an embed used in a
+ * composite view or a standalone preview claims nothing and suppresses nothing).
+ */
+/** One warning per placed set — a mis-ordered surface re-renders freely. */
+const warnedDuplications = new Set();
+function warnDuplicatedChildComposition(placed) {
+    const key = placed.slice().sort().join(',');
+    if (warnedDuplications.has(key)) {
+        return;
+    }
+    warnedDuplications.add(key);
+    LoggerFrontendService.getLogger().warn('[composed-children] A template claimed the child region AND the automatic container composed children '
+        + `in the same pass, so children render TWICE${placed.length > 0 ? ` (placed: ${placed.join(', ')})` : ''}. `
+        + 'The handshake is render-phase, so the template must render BEFORE the container — check that the '
+        + 'surface still renders its display template above <ResourceLayout_ContainerNested>.');
+}
+export function useRegisterComposedChild(childResourceType) {
+    const registry = useContext(ComposedChildrenRegistryContext);
+    if (registry && childResourceType) {
+        registry.placed.add(childResourceType);
+    }
+}
+/**
+ * `true` when the template composed the child region itself, in which case the
+ * automatic container renders nothing.
+ *
+ * `false` with no host, so a surface without the handshake composes normally —
+ * the pre-existing behaviour, unchanged.
+ */
+export function useTemplateOwnsChildComposition() {
+    const registry = useContext(ComposedChildrenRegistryContext);
+    if (!registry)
+        return false;
+    return registry.owned.current || registry.placed.size > 0;
+}
+/**
+ * Claim the child region for the template, whatever it ends up containing.
+ *
+ * Called by the placement primitive so that naming ZERO children is a decision
+ * ("this surface composes none") rather than an absence of one ("nobody said, so
+ * compose them all"). Without it, the only way to express "no children" is a
+ * per-edge opt-out on every relationship — the configuration axis this design
+ * exists to remove.
+ */
+export function useClaimChildComposition() {
+    const registry = useContext(ComposedChildrenRegistryContext);
+    if (registry) {
+        registry.owned.current = true;
+    }
+}
+/**
+ * Which child resource types were placed. Not used to SUPPRESS anything —
+ * ownership is whole-surface — but kept because it is what makes a diagnostic
+ * able to name the children a template claimed.
+ */
+const EMPTY = Object.freeze(new Set());
+/**
+ * Called by the automatic container to record what it DID this pass. Paired with
+ * the provider's post-commit check: "container composed" plus "template claimed"
+ * is duplication, and is the only combination worth reporting.
+ */
+export function useReportAutomaticComposition(composed) {
+    const registry = useContext(ComposedChildrenRegistryContext);
+    if (registry && composed) {
+        registry.composedAutomatically.current = true;
+    }
+}
+export function useComposedChildren() {
+    const registry = useContext(ComposedChildrenRegistryContext);
+    return registry?.placed ?? EMPTY;
+}
+//# sourceMappingURL=ComposedChildrenRegistry.js.map

package/dist/esm/components/resources/embeds/ComposedChildrenRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComposedChildrenRegistry.js","sourceRoot":"","sources":["../../../../../../src/components/resources/embeds/ComposedChildrenRegistry.tsx"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport React, { createContext, useContext, useEffect, useMemo, useRef } from 'react';\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\n\n/**\n * Records whether a view TEMPLATE composed the child region itself, so the\n * automatic composition that follows stands down entirely.\n *\n * ## Whole-surface ownership, not a per-child merge\n *\n * If the template placed ANY child, it owns the child region and the automatic\n * block renders nothing. This mirrors how an authored `layout.display` REPLACES\n * the generated field template rather than being merged with it\n * (`ResourceAutomaticDisplayer`: `if (explicitDisplayTemplate) return\n * explicitDisplayTemplate;` — there is no per-field \"the framework also appends\n * the ones you did not place\", and nobody has ever wanted one).\n *\n * Children behaving differently is what would FORCE a per-edge suppression flag\n * back into the relationship: a parent placing 3 of its 33 owned children would\n * otherwise auto-compose the other 30, and the only way to stop that is a flag\n * on each edge. Whole-surface ownership is precisely what makes that\n * configuration axis unnecessary — two modes (standard, or the template), never\n * three.\n *\n * The signal is PLACEMENT, not the mere existence of a template. A field-only\n * `layout.display` — Wonder Todos' `todoLists` is exactly that — places no child\n * and must keep its standard child block. Keying on existence would silently\n * delete content from every field-only template in the repository.\n *\n * ## The handshake, and why it can work at all\n *\n * A resource READ surface renders in one pass, in order: the header, then the\n * displayer (inside which the authored `layout.display` template runs, and with\n * it any child embeds it places), and only then the automatic children\n * container. So a placement registered during the template's render is already\n * visible when the container renders in that same pass. The ordering is not\n * incidental — it is the whole mechanism, and moving the container above the\n * displayer would silently break it.\n *\n * ## Why a ref-backed set rather than state\n *\n * Registration must not schedule a re-render: the template registers DURING\n * render, and setting state there is illegal. The set is cleared at the start of\n * every host render and refilled by that render's template, so it always\n * describes the current pass rather than accumulating across passes — which is\n * what makes a child REMOVED from a template stop being suppressed.\n *\n * ## The one case that does not resolve within a single pass\n *\n * A template that places a child CONDITIONALLY on loaded record data places\n * nothing on the first pass, so the container composes that child automatically;\n * when the data arrives the host re-renders, the template registers, and the\n * container skips it. The child therefore renders automatically for the frames\n * before data lands. It self-corrects, and the container already defers\n * conditional relationships while `parentData` is undefined for the same\n * \"avoid a flash of content\" reason — but a template that wants no flicker at\n * all should place its child unconditionally and let the child's own surface\n * handle its empty state.\n */\nexport interface ComposedChildrenRegistryValue {\n  /**\n   * Child resource types placed by the template in the CURRENT render pass.\n   * Mutable by design — see the class comment on why this is a ref and not state.\n   */\n  placed: Set<string>;\n  /**\n   * Ownership CLAIMED explicitly, independently of how many children were placed.\n   *\n   * Placement alone cannot express \"this surface composes NO children\": a template\n   * that places nothing is indistinguishable from one that never decided, and the\n   * latter must keep composing automatically. Real surfaces need the distinction —\n   * an embedded application READ deliberately shows none of its nine owned\n   * children, which is what nine `hidden: true` entries used to say.\n   */\n  owned: { current: boolean };\n  /**\n   * Whether the automatic container actually COMPOSED children this pass.\n   *\n   * The handshake is render-phase — placements mutate `placed`/`owned` while they\n   * render, the container reads the answer while IT renders — so it only works\n   * because the container renders AFTER the template. That holds today\n   * (`ResourceLayout_Read` renders `{children}` immediately before\n   * `ResourceLayout_ContainerNested`) and nothing in the type system enforces it;\n   * swap those two JSX siblings and every child renders TWICE, silently.\n   *\n   * The detection is deliberately an OUTCOME, checked after commit, rather than a\n   * render-order tripwire. A first attempt marked the pass as soon as the question\n   * was asked and warned on any later placement — which fired spuriously the moment\n   * anything re-rendered WITHOUT the provider (an error boundary recovering, most\n   * visibly), because the flag was then left over from the previous pass. A\n   * diagnostic that cries wolf gets ignored, so this one asks the only question\n   * that is actually a defect: did the container compose children AND a template\n   * claim the region? That is duplication, whatever order they rendered in.\n   */\n  composedAutomatically: { current: boolean };\n}\n\nconst ComposedChildrenRegistryContext = createContext<ComposedChildrenRegistryValue | null>(null);\n\nexport interface ComposedChildrenRegistryProviderProps {\n  children: React.ReactNode;\n}\n\n/**\n * Hosts an ownership handshake for one render pass of one record surface.\n *\n * Clears the set on every render so the registry describes THIS pass. The\n * context value is identity-stable across renders (the ref wrapper), so\n * providing it costs no extra re-render of the subtree.\n */\nexport function ComposedChildrenRegistryProvider({\n  children,\n}: ComposedChildrenRegistryProviderProps): React.JSX.Element {\n  const ref = useRef<ComposedChildrenRegistryValue>({\n    placed: new Set<string>(),\n    owned: { current: false },\n    composedAutomatically: { current: false },\n  });\n  // Cleared during render, before any descendant registers — descendants render\n  // strictly after this component's body, so nothing registered this pass is lost.\n  ref.current.placed.clear();\n  ref.current.owned.current = false;\n  ref.current.composedAutomatically.current = false;\n  const value = useMemo(() => ref.current, []);\n\n  // After commit, so render ORDER is irrelevant and only the outcome is judged.\n  useEffect(() => {\n    const registry = ref.current;\n    if (!registry.composedAutomatically.current) {\n      return;\n    }\n    if (registry.owned.current || registry.placed.size > 0) {\n      warnDuplicatedChildComposition([...registry.placed]);\n    }\n  });\n\n  return (\n    <ComposedChildrenRegistryContext.Provider value={value}>\n      {children}\n    </ComposedChildrenRegistryContext.Provider>\n  );\n}\n\n/**\n * Called by an embed while it renders, to claim a child on behalf of the\n * template that placed it. A no-op outside a registry host (an embed used in a\n * composite view or a standalone preview claims nothing and suppresses nothing).\n */\n/** One warning per placed set — a mis-ordered surface re-renders freely. */\nconst warnedDuplications = new Set<string>();\n\nfunction warnDuplicatedChildComposition(placed: readonly string[]): void {\n  const key = placed.slice().sort().join(',');\n  if (warnedDuplications.has(key)) {\n    return;\n  }\n  warnedDuplications.add(key);\n  LoggerFrontendService.getLogger().warn(\n    '[composed-children] A template claimed the child region AND the automatic container composed children '\n    + `in the same pass, so children render TWICE${placed.length > 0 ? ` (placed: ${placed.join(', ')})` : ''}. `\n    + 'The handshake is render-phase, so the template must render BEFORE the container — check that the '\n    + 'surface still renders its display template above <ResourceLayout_ContainerNested>.',\n  );\n}\n\nexport function useRegisterComposedChild(childResourceType: string | undefined): void {\n  const registry = useContext(ComposedChildrenRegistryContext);\n  if (registry && childResourceType) {\n    registry.placed.add(childResourceType);\n  }\n}\n\n/**\n * `true` when the template composed the child region itself, in which case the\n * automatic container renders nothing.\n *\n * `false` with no host, so a surface without the handshake composes normally —\n * the pre-existing behaviour, unchanged.\n */\nexport function useTemplateOwnsChildComposition(): boolean {\n  const registry = useContext(ComposedChildrenRegistryContext);\n  if (!registry) return false;\n  return registry.owned.current || registry.placed.size > 0;\n}\n\n/**\n * Claim the child region for the template, whatever it ends up containing.\n *\n * Called by the placement primitive so that naming ZERO children is a decision\n * (\"this surface composes none\") rather than an absence of one (\"nobody said, so\n * compose them all\"). Without it, the only way to express \"no children\" is a\n * per-edge opt-out on every relationship — the configuration axis this design\n * exists to remove.\n */\nexport function useClaimChildComposition(): void {\n  const registry = useContext(ComposedChildrenRegistryContext);\n  if (registry) {\n    registry.owned.current = true;\n  }\n}\n\n/**\n * Which child resource types were placed. Not used to SUPPRESS anything —\n * ownership is whole-surface — but kept because it is what makes a diagnostic\n * able to name the children a template claimed.\n */\nconst EMPTY: ReadonlySet<string> = Object.freeze(new Set<string>());\n\n/**\n * Called by the automatic container to record what it DID this pass. Paired with\n * the provider's post-commit check: \"container composed\" plus \"template claimed\"\n * is duplication, and is the only combination worth reporting.\n */\nexport function useReportAutomaticComposition(composed: boolean): void {\n  const registry = useContext(ComposedChildrenRegistryContext);\n  if (registry && composed) {\n    registry.composedAutomatically.current = true;\n  }\n}\n\nexport function useComposedChildren(): ReadonlySet<string> {\n  const registry = useContext(ComposedChildrenRegistryContext);\n  return registry?.placed ?? EMPTY;\n}\n"]}

package/dist/esm/components/resources/embeds/EmbeddedResourceDescent.d.ts

@@ -0,0 +1,83 @@
+import React from 'react';
+/**
+ * Bounds how deep embedded resource surfaces may nest, and refuses true cycles.
+ *
+ * ## Why this exists at all
+ *
+ * Before template-owned composition, nesting was bounded only by ACCIDENT: a 1:N
+ * child rendered as a LIST (which mounts no nested container) and a 1:1 child
+ * rendered through the field displayer rather than a full READ surface, so
+ * neither re-entered. Nothing chose that bound — it fell out of which component
+ * happened to render a child.
+ *
+ * Template-owned composition removes the accident: an authored template may embed
+ * a child with `operationLike: READ`, which mounts a full READ surface, which
+ * composes ITS children, and so on. On a self-referencing edge (`Category →
+ * Category`, already rendered today — `getChildDirectionRelationships` returns
+ * `[...childRelationships, ...selfRelationships]`) or a mutually recursive pair,
+ * that does not terminate.
+ *
+ * ## Why BOTH mechanisms, when either sounds sufficient
+ *
+ * They bound different things, and neither substitutes for the other:
+ *
+ * - the **depth cap** bounds hierarchy BREADTH — a legitimately deep, entirely
+ *   acyclic chain (organization → unit → team → member → …) that simply should
+ *   not render as one page;
+ * - the **visited set** catches a genuine revisit EXACTLY, at the moment it
+ *   happens, instead of letting a cycle burn `maxDepth` levels first. Those
+ *   wasted levels are not free: each mounts a surface and fires a real LIST
+ *   request.
+ *
+ * ## The key is `(edge, host row)` — not the edge alone
+ *
+ * Keying on the relationship edge alone would break the very feature this
+ * protects. A self-referencing hierarchy traverses the SAME edge at every level
+ * with DIFFERENT rows, so an edge-only set stops it at depth 1 and reports a
+ * cycle that does not exist. Keyed on the edge AND the host row, a repeat means
+ * the same record has been reached again by some path — which is a cycle, and
+ * nothing else is.
+ *
+ * ## At the limit: render nothing
+ *
+ * Deliberate product decision. The trade accepted is that the boundary is
+ * invisible to the reader — and for a 1:1 the omitted block IS the content
+ * rather than a truncated list. The mitigation adds no UI: a dev-time warning
+ * naming the edge and the depth reached, so an author sees the boundary during
+ * development while the product stays silent. Same posture as the container's
+ * existing "authored section renders nothing" warning.
+ */
+/** @wildo_source:part:start saas.frontend.embedded-resource-descent facet:layer:frontend facet:family:component */
+/** Framework default. Overridable per edge; see {@link EmbeddedResourceDescentBoundaryProps.maxDepth}. */
+export declare const DEFAULT_MAX_EMBEDDED_RESOURCE_DEPTH = 3;
+export interface EmbeddedResourceDescentValue {
+    /** How many embedded surfaces deep the current subtree already is. Root is 0. */
+    depth: number;
+    /** `${edgeKey}::${hostRowId}` for every descent already taken on this path. */
+    visited: ReadonlySet<string>;
+}
+export declare function useEmbeddedResourceDescent(): EmbeddedResourceDescentValue;
+/** @wildo_source:part:start saas.frontend.embedded-resource-descent facet:layer:frontend facet:family:component */
+export interface EmbeddedResourceDescentBoundaryProps {
+    /**
+     * Identity of the descent about to be taken, as `(edge, host row)`. Callers
+     * compose it — the automatic container from the relationship edge key plus the
+     * parent row id, an explicit embed from its target resource plus the host id.
+     */
+    descentKey: string;
+    /** Per-edge override of {@link DEFAULT_MAX_EMBEDDED_RESOURCE_DEPTH}. */
+    maxDepth?: number;
+    children: React.ReactNode;
+}
+/** @wildo_source:part:end saas.frontend.embedded-resource-descent */
+/**
+ * Admits or refuses one level of embedded descent, and provides the incremented
+ * state to whatever it admits. Refusal renders nothing.
+ *
+ * Deciding and providing are one component on purpose: a caller that could ask
+ * "may I?" without also registering the descent would let the next level down
+ * believe it is shallower than it is, which is the failure mode a hand-applied
+ * counter always eventually has.
+ */
+export declare function EmbeddedResourceDescentBoundary({ descentKey, maxDepth, children, }: EmbeddedResourceDescentBoundaryProps): React.JSX.Element | null;
+//# sourceMappingURL=EmbeddedResourceDescent.d.ts.map

package/dist/esm/components/resources/embeds/EmbeddedResourceDescent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddedResourceDescent.d.ts","sourceRoot":"","sources":["../../../../../../src/components/resources/embeds/EmbeddedResourceDescent.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA6C,MAAM,OAAO,CAAC;AAIlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,mHAAmH;AACnH,0GAA0G;AAC1G,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAErD,MAAM,WAAW,4BAA4B;IAC3C,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9B;AAQD,wBAAgB,0BAA0B,IAAI,4BAA4B,CAEzE;AAoBD,mHAAmH;AACnH,MAAM,WAAW,oCAAoC;IACnD;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AACD,qEAAqE;AAErE;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,UAAU,EACV,QAA8C,EAC9C,QAAQ,GACT,EAAE,oCAAoC,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAuBjE"}

package/dist/esm/components/resources/embeds/EmbeddedResourceDescent.js

@@ -0,0 +1,103 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+import { LoggerFrontendService } from '../../../core/monitoring/logger.frontend.service.js';
+/**
+ * Bounds how deep embedded resource surfaces may nest, and refuses true cycles.
+ *
+ * ## Why this exists at all
+ *
+ * Before template-owned composition, nesting was bounded only by ACCIDENT: a 1:N
+ * child rendered as a LIST (which mounts no nested container) and a 1:1 child
+ * rendered through the field displayer rather than a full READ surface, so
+ * neither re-entered. Nothing chose that bound — it fell out of which component
+ * happened to render a child.
+ *
+ * Template-owned composition removes the accident: an authored template may embed
+ * a child with `operationLike: READ`, which mounts a full READ surface, which
+ * composes ITS children, and so on. On a self-referencing edge (`Category →
+ * Category`, already rendered today — `getChildDirectionRelationships` returns
+ * `[...childRelationships, ...selfRelationships]`) or a mutually recursive pair,
+ * that does not terminate.
+ *
+ * ## Why BOTH mechanisms, when either sounds sufficient
+ *
+ * They bound different things, and neither substitutes for the other:
+ *
+ * - the **depth cap** bounds hierarchy BREADTH — a legitimately deep, entirely
+ *   acyclic chain (organization → unit → team → member → …) that simply should
+ *   not render as one page;
+ * - the **visited set** catches a genuine revisit EXACTLY, at the moment it
+ *   happens, instead of letting a cycle burn `maxDepth` levels first. Those
+ *   wasted levels are not free: each mounts a surface and fires a real LIST
+ *   request.
+ *
+ * ## The key is `(edge, host row)` — not the edge alone
+ *
+ * Keying on the relationship edge alone would break the very feature this
+ * protects. A self-referencing hierarchy traverses the SAME edge at every level
+ * with DIFFERENT rows, so an edge-only set stops it at depth 1 and reports a
+ * cycle that does not exist. Keyed on the edge AND the host row, a repeat means
+ * the same record has been reached again by some path — which is a cycle, and
+ * nothing else is.
+ *
+ * ## At the limit: render nothing
+ *
+ * Deliberate product decision. The trade accepted is that the boundary is
+ * invisible to the reader — and for a 1:1 the omitted block IS the content
+ * rather than a truncated list. The mitigation adds no UI: a dev-time warning
+ * naming the edge and the depth reached, so an author sees the boundary during
+ * development while the product stays silent. Same posture as the container's
+ * existing "authored section renders nothing" warning.
+ */
+/** @wildo_source:part:start saas.frontend.embedded-resource-descent facet:layer:frontend facet:family:component */
+/** Framework default. Overridable per edge; see {@link EmbeddedResourceDescentBoundaryProps.maxDepth}. */
+export const DEFAULT_MAX_EMBEDDED_RESOURCE_DEPTH = 3;
+/** @wildo_source:part:end saas.frontend.embedded-resource-descent */
+const EMPTY_VISITED = Object.freeze(new Set());
+const ROOT = Object.freeze({ depth: 0, visited: EMPTY_VISITED });
+const EmbeddedResourceDescentContext = createContext(ROOT);
+export function useEmbeddedResourceDescent() {
+    return useContext(EmbeddedResourceDescentContext);
+}
+/** Dedup guard so one refused edge warns once, not once per render. */
+const warnedRefusals = new Set();
+function warnRefusal(descentKey, reason, depth, maxDepth) {
+    if (warnedRefusals.has(`${descentKey}:${reason}`)) {
+        return;
+    }
+    warnedRefusals.add(`${descentKey}:${reason}`);
+    LoggerFrontendService.getLogger().warn(reason === 'cycle'
+        ? `[embedded-resource-descent] CYCLE refused at "${descentKey}": this record was already reached on `
+            + 'this path, so rendering it again would not terminate. Nothing is rendered here.'
+        : `[embedded-resource-descent] DEPTH LIMIT refused at "${descentKey}": embedded nesting reached `
+            + `${depth} of a maximum ${maxDepth}. Nothing is rendered here. Raise the per-edge limit only if this `
+            + 'hierarchy genuinely belongs on one page — otherwise link to the child instead of embedding it.');
+}
+/** @wildo_source:part:end saas.frontend.embedded-resource-descent */
+/**
+ * Admits or refuses one level of embedded descent, and provides the incremented
+ * state to whatever it admits. Refusal renders nothing.
+ *
+ * Deciding and providing are one component on purpose: a caller that could ask
+ * "may I?" without also registering the descent would let the next level down
+ * believe it is shallower than it is, which is the failure mode a hand-applied
+ * counter always eventually has.
+ */
+export function EmbeddedResourceDescentBoundary({ descentKey, maxDepth = DEFAULT_MAX_EMBEDDED_RESOURCE_DEPTH, children, }) {
+    const parent = useEmbeddedResourceDescent();
+    const isCycle = parent.visited.has(descentKey);
+    const nextDepth = parent.depth + 1;
+    const exceedsDepth = nextDepth > maxDepth;
+    const value = useMemo(() => {
+        const visited = new Set(parent.visited);
+        visited.add(descentKey);
+        return { depth: nextDepth, visited };
+    }, [parent.visited, descentKey, nextDepth]);
+    if (isCycle || exceedsDepth) {
+        warnRefusal(descentKey, isCycle ? 'cycle' : 'depth', nextDepth, maxDepth);
+        return null;
+    }
+    return (_jsx(EmbeddedResourceDescentContext.Provider, { value: value, children: children }));
+}
+//# sourceMappingURL=EmbeddedResourceDescent.js.map

package/dist/esm/components/resources/embeds/EmbeddedResourceDescent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddedResourceDescent.js","sourceRoot":"","sources":["../../../../../../src/components/resources/embeds/EmbeddedResourceDescent.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAc,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,mHAAmH;AACnH,0GAA0G;AAC1G,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,CAAC;AAQrD,qEAAqE;AAErE,MAAM,aAAa,GAAwB,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,EAAU,CAAC,CAAC;AAC5E,MAAM,IAAI,GAAiC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;AAE/F,MAAM,8BAA8B,GAAG,aAAa,CAA+B,IAAI,CAAC,CAAC;AAEzF,MAAM,UAAU,0BAA0B;IACxC,OAAO,UAAU,CAAC,8BAA8B,CAAC,CAAC;AACpD,CAAC;AAED,uEAAuE;AACvE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;AAEzC,SAAS,WAAW,CAAC,UAAkB,EAAE,MAAyB,EAAE,KAAa,EAAE,QAAgB;IACjG,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,UAAU,IAAI,MAAM,EAAE,CAAC,EAAE,CAAC;QAClD,OAAO;IACT,CAAC;IACD,cAAc,CAAC,GAAG,CAAC,GAAG,UAAU,IAAI,MAAM,EAAE,CAAC,CAAC;IAC9C,qBAAqB,CAAC,SAAS,EAAE,CAAC,IAAI,CACpC,MAAM,KAAK,OAAO;QAChB,CAAC,CAAC,iDAAiD,UAAU,wCAAwC;cACjG,iFAAiF;QACrF,CAAC,CAAC,uDAAuD,UAAU,8BAA8B;cAC7F,GAAG,KAAK,iBAAiB,QAAQ,oEAAoE;cACrG,gGAAgG,CACvG,CAAC;AACJ,CAAC;AAcD,qEAAqE;AAErE;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAAC,EAC9C,UAAU,EACV,QAAQ,GAAG,mCAAmC,EAC9C,QAAQ,GAC6B;IACrC,MAAM,MAAM,GAAG,0BAA0B,EAAE,CAAC;IAE5C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IACnC,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,CAAC;IAE1C,MAAM,KAAK,GAAG,OAAO,CAA+B,GAAG,EAAE;QACvD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IACvC,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;IAE5C,IAAI,OAAO,IAAI,YAAY,EAAE,CAAC;QAC5B,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CACL,KAAC,8BAA8B,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAClD,QAAQ,GAC+B,CAC3C,CAAC;AACJ,CAAC","sourcesContent":["'use client';\n\nimport React, { createContext, useContext, useMemo } from 'react';\n\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\n\n/**\n * Bounds how deep embedded resource surfaces may nest, and refuses true cycles.\n *\n * ## Why this exists at all\n *\n * Before template-owned composition, nesting was bounded only by ACCIDENT: a 1:N\n * child rendered as a LIST (which mounts no nested container) and a 1:1 child\n * rendered through the field displayer rather than a full READ surface, so\n * neither re-entered. Nothing chose that bound — it fell out of which component\n * happened to render a child.\n *\n * Template-owned composition removes the accident: an authored template may embed\n * a child with `operationLike: READ`, which mounts a full READ surface, which\n * composes ITS children, and so on. On a self-referencing edge (`Category →\n * Category`, already rendered today — `getChildDirectionRelationships` returns\n * `[...childRelationships, ...selfRelationships]`) or a mutually recursive pair,\n * that does not terminate.\n *\n * ## Why BOTH mechanisms, when either sounds sufficient\n *\n * They bound different things, and neither substitutes for the other:\n *\n * - the **depth cap** bounds hierarchy BREADTH — a legitimately deep, entirely\n *   acyclic chain (organization → unit → team → member → …) that simply should\n *   not render as one page;\n * - the **visited set** catches a genuine revisit EXACTLY, at the moment it\n *   happens, instead of letting a cycle burn `maxDepth` levels first. Those\n *   wasted levels are not free: each mounts a surface and fires a real LIST\n *   request.\n *\n * ## The key is `(edge, host row)` — not the edge alone\n *\n * Keying on the relationship edge alone would break the very feature this\n * protects. A self-referencing hierarchy traverses the SAME edge at every level\n * with DIFFERENT rows, so an edge-only set stops it at depth 1 and reports a\n * cycle that does not exist. Keyed on the edge AND the host row, a repeat means\n * the same record has been reached again by some path — which is a cycle, and\n * nothing else is.\n *\n * ## At the limit: render nothing\n *\n * Deliberate product decision. The trade accepted is that the boundary is\n * invisible to the reader — and for a 1:1 the omitted block IS the content\n * rather than a truncated list. The mitigation adds no UI: a dev-time warning\n * naming the edge and the depth reached, so an author sees the boundary during\n * development while the product stays silent. Same posture as the container's\n * existing \"authored section renders nothing\" warning.\n */\n\n/** @wildo_source:part:start saas.frontend.embedded-resource-descent facet:layer:frontend facet:family:component */\n/** Framework default. Overridable per edge; see {@link EmbeddedResourceDescentBoundaryProps.maxDepth}. */\nexport const DEFAULT_MAX_EMBEDDED_RESOURCE_DEPTH = 3;\n\nexport interface EmbeddedResourceDescentValue {\n  /** How many embedded surfaces deep the current subtree already is. Root is 0. */\n  depth: number;\n  /** `${edgeKey}::${hostRowId}` for every descent already taken on this path. */\n  visited: ReadonlySet<string>;\n}\n/** @wildo_source:part:end saas.frontend.embedded-resource-descent */\n\nconst EMPTY_VISITED: ReadonlySet<string> = Object.freeze(new Set<string>());\nconst ROOT: EmbeddedResourceDescentValue = Object.freeze({ depth: 0, visited: EMPTY_VISITED });\n\nconst EmbeddedResourceDescentContext = createContext<EmbeddedResourceDescentValue>(ROOT);\n\nexport function useEmbeddedResourceDescent(): EmbeddedResourceDescentValue {\n  return useContext(EmbeddedResourceDescentContext);\n}\n\n/** Dedup guard so one refused edge warns once, not once per render. */\nconst warnedRefusals = new Set<string>();\n\nfunction warnRefusal(descentKey: string, reason: 'depth' | 'cycle', depth: number, maxDepth: number): void {\n  if (warnedRefusals.has(`${descentKey}:${reason}`)) {\n    return;\n  }\n  warnedRefusals.add(`${descentKey}:${reason}`);\n  LoggerFrontendService.getLogger().warn(\n    reason === 'cycle'\n      ? `[embedded-resource-descent] CYCLE refused at \"${descentKey}\": this record was already reached on `\n        + 'this path, so rendering it again would not terminate. Nothing is rendered here.'\n      : `[embedded-resource-descent] DEPTH LIMIT refused at \"${descentKey}\": embedded nesting reached `\n        + `${depth} of a maximum ${maxDepth}. Nothing is rendered here. Raise the per-edge limit only if this `\n        + 'hierarchy genuinely belongs on one page — otherwise link to the child instead of embedding it.',\n  );\n}\n\n/** @wildo_source:part:start saas.frontend.embedded-resource-descent facet:layer:frontend facet:family:component */\nexport interface EmbeddedResourceDescentBoundaryProps {\n  /**\n   * Identity of the descent about to be taken, as `(edge, host row)`. Callers\n   * compose it — the automatic container from the relationship edge key plus the\n   * parent row id, an explicit embed from its target resource plus the host id.\n   */\n  descentKey: string;\n  /** Per-edge override of {@link DEFAULT_MAX_EMBEDDED_RESOURCE_DEPTH}. */\n  maxDepth?: number;\n  children: React.ReactNode;\n}\n/** @wildo_source:part:end saas.frontend.embedded-resource-descent */\n\n/**\n * Admits or refuses one level of embedded descent, and provides the incremented\n * state to whatever it admits. Refusal renders nothing.\n *\n * Deciding and providing are one component on purpose: a caller that could ask\n * \"may I?\" without also registering the descent would let the next level down\n * believe it is shallower than it is, which is the failure mode a hand-applied\n * counter always eventually has.\n */\nexport function EmbeddedResourceDescentBoundary({\n  descentKey,\n  maxDepth = DEFAULT_MAX_EMBEDDED_RESOURCE_DEPTH,\n  children,\n}: EmbeddedResourceDescentBoundaryProps): React.JSX.Element | null {\n  const parent = useEmbeddedResourceDescent();\n\n  const isCycle = parent.visited.has(descentKey);\n  const nextDepth = parent.depth + 1;\n  const exceedsDepth = nextDepth > maxDepth;\n\n  const value = useMemo<EmbeddedResourceDescentValue>(() => {\n    const visited = new Set(parent.visited);\n    visited.add(descentKey);\n    return { depth: nextDepth, visited };\n  }, [parent.visited, descentKey, nextDepth]);\n\n  if (isCycle || exceedsDepth) {\n    warnRefusal(descentKey, isCycle ? 'cycle' : 'depth', nextDepth, maxDepth);\n    return null;\n  }\n\n  return (\n    <EmbeddedResourceDescentContext.Provider value={value}>\n      {children}\n    </EmbeddedResourceDescentContext.Provider>\n  );\n}\n"]}

package/dist/esm/components/resources/embeds/EmbeddedResourceHostContext.d.ts

@@ -0,0 +1,63 @@
+import React from 'react';
+import type { NavigationInitiatorContext, NavigationZone } from '../../../core/navigation/navigation.schemas';
+/**
+ * The context an EMBEDDED resource surface needs from whatever is hosting it.
+ *
+ * This is deliberately host-NEUTRAL. Two different kinds of host provide it:
+ *
+ * - a **composite view**, through `CompositeViewProvider`, which layers its own
+ *   composite-only concerns (`viewDefinition`, `breakpoint`) on top; and
+ * - a **resource layout** — a READ/custom operation surface whose authored
+ *   template places a child directly.
+ *
+ * ## Why it exists
+ *
+ * The embed family (`EmbedRelatedResourceOperation` and its siblings) resolves
+ * everything it needs from the resource REGISTRY: nothing in its operation
+ * resolution, addressability or context derivation is composite-specific. Only
+ * its PLUMBING was — it read `useCompositeViewContext()`, which throws outside a
+ * `CompositeViewProvider`, and `CompositeViewContextValue` mandates a
+ * `viewDefinition` that a resource layout does not have and must not fabricate.
+ *
+ * Splitting that plumbing out is what lets one embed family serve composite
+ * views, custom operation hosts and resource layout templates alike, instead of
+ * a second family growing up beside it for the resource plane.
+ *
+ * ## What belongs here, and what does not
+ *
+ * Only facts about the HOST RECORD and the navigation the embed inherits.
+ * `viewDefinition` and `breakpoint` stay on the composite context because they
+ * describe a composite view, not a host record — a resource layout has neither.
+ *
+ * Note `parentResourcesRequirements` is deliberately absent: it is DERIVED from
+ * `hostResourceType` + `contextResourceIdentifiers` against the registry, and
+ * carrying it as well would create a second, drifting authority for the same fact.
+ */
+export interface EmbeddedResourceHostContextValue {
+    /**
+     * Resource type of the record the embed hangs off. Optional because a host may
+     * legitimately be app-scoped rather than resource-scoped; the embed's own
+     * `buildOperationContext` fails closed when it is absent, which is correct —
+     * a related-resource embed is meaningless without a host record.
+     */
+    hostResourceType?: string;
+    /** Context identifiers of the host record and its ancestors, keyed by resource type. */
+    contextResourceIdentifiers?: Record<string, string>;
+    /** Navigation zone the embedded surface inherits from its host. */
+    navigationZone: NavigationZone;
+    /** Initiator carried into navigations the embedded surface starts. */
+    navigationInitiator?: NavigationInitiatorContext;
+}
+export interface EmbeddedResourceHostProviderProps extends EmbeddedResourceHostContextValue {
+    children: React.ReactNode;
+}
+export declare function EmbeddedResourceHostProvider({ hostResourceType, contextResourceIdentifiers, navigationZone, navigationInitiator, children, }: EmbeddedResourceHostProviderProps): React.JSX.Element;
+/**
+ * Throws when no host provides the context. The message names BOTH hosts on
+ * purpose: the previous error said only "must be used within a
+ * CompositeViewProvider", which sent anyone embedding from a resource layout
+ * looking for a composite view they neither have nor need.
+ */
+export declare function useEmbeddedResourceHostContext(): EmbeddedResourceHostContextValue;
+export declare function useOptionalEmbeddedResourceHostContext(): EmbeddedResourceHostContextValue | null;
+//# sourceMappingURL=EmbeddedResourceHostContext.d.ts.map

package/dist/esm/components/resources/embeds/EmbeddedResourceHostContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddedResourceHostContext.d.ts","sourceRoot":"","sources":["../../../../../../src/components/resources/embeds/EmbeddedResourceHostContext.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA6C,MAAM,OAAO,CAAC;AAElE,OAAO,KAAK,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,wDAAwD,CAAC;AAEzH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wFAAwF;IACxF,0BAA0B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,mEAAmE;IACnE,cAAc,EAAE,cAAc,CAAC;IAC/B,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;CAClD;AAID,MAAM,WAAW,iCAAkC,SAAQ,gCAAgC;IACzF,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,4BAA4B,CAAC,EAC3C,gBAAgB,EAChB,0BAA0B,EAC1B,cAAc,EACd,mBAAmB,EACnB,QAAQ,GACT,EAAE,iCAAiC,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAmBvD;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,IAAI,gCAAgC,CASjF;AAED,wBAAgB,sCAAsC,IAAI,gCAAgC,GAAG,IAAI,CAEhG"}