@wildo-ai/saas-frontend-lib 1.1.4 → 1.1.5

package/dist/esm/core/guidance/GuidanceRenderer.d.ts

@@ -10,19 +10,72 @@
 import React from 'react';
 import type { GuidanceElementState, OnboardingElement } from '@wildo-ai/saas-models';
 import { OnboardingElementType } from '@wildo-ai/saas-models';
+import { FrontendComponentType } from '@wildo-ai/presets-components-models';
 export interface GuidanceElementRendererProps {
     element: OnboardingElement;
     flowRef: string;
     state: GuidanceElementState | undefined;
+    /**
+     * Record this element complete. REJECTS when a bound survey's answers could not be written
+     * (#1372), in which case nothing was recorded — a renderer that can bind must await this and
+     * surface the failure rather than leaving the person to wonder.
+     *
+     * Every element type but SURVEY, and every unbound survey, resolves without a round trip, so a
+     * renderer with nothing to bind may keep ignoring the promise.
+     */
     onComplete: (elementRef: string, data?: {
         surveyAnswers?: Record<string, unknown>;
         lastStepIndex?: number;
-    }) => void;
+        declineResourceBinding?: boolean;
+    }) => Promise<void>;
     onDismiss: (elementRef: string) => void;
     onAction: (actionRef: string) => void;
     /** i18n translate function scoped to this flow+element. Returns undefined when no translation exists. */
     t: (key: string, params?: Record<string, string | number>) => string | undefined;
 }
+/**
+ * The component-registry slot each guidance element type is replaceable through.
+ *
+ * ## Why this map exists
+ *
+ * Every `GUIDANCE_*` component type was already declared, already carried a frontend-component
+ * SPECIFICATION advertising a `DEFAULT` preset and an exported registry key, and was already used
+ * as an i18n namespace by the renderer that implements it — but nothing ever joined the element
+ * type to the slot, so the slots were addressable for labels and unreachable for COMPONENTS. Each
+ * one sat on the registry-completeness deny-list under "framework-internal … not swappable", and an
+ * application that wanted a different banner had no way to supply one short of replacing the whole
+ * `APP_LAYOUT_MAIN_CONTAINER` preset.
+ *
+ * Total over `OnboardingElementType` by construction: a new element type is a compile error here
+ * until it declares which slot replaces it, rather than silently shipping as unswappable.
+ */
+export declare const GUIDANCE_ELEMENT_COMPONENT_TYPE: Record<OnboardingElementType, FrontendComponentType>;
+/**
+ * Resolve the component that renders one element type, most specific source first.
+ *
+ * `customRenderers` (a prop) → a REGISTERED preset → the engine's built-in renderer.
+ *
+ * ## Why this is not `createComponentResolver`
+ *
+ * That helper renders `ComponentNotInjected` when a slot has no registration, which is right for a
+ * slot the framework does not implement. These ten slots DO have working framework implementations,
+ * so a missing registration must fall through to the built-in rather than blank the element — an
+ * application that registers nothing keeps exactly the behaviour it has today, and one that
+ * registers a preset gets its own component. Registration is therefore purely additive and cannot
+ * break a guidance surface by its absence.
+ *
+ * `preset` is read from the registry under `CorePresetNames.DEFAULT`, which is the name an
+ * application overrides. Named alternative presets are deliberately NOT resolved here: nothing in a
+ * flow definition selects one, so admitting them would create a second selection axis with no
+ * authoring surface behind it.
+ */
+export declare function resolveGuidanceElementRenderer(elementType: OnboardingElementType, 
+/**
+ * Optional, because the second caller — `OnboardingView` — has no equivalent prop. Leaving it
+ * required would have meant that surface passing a literal `undefined`, which reads as an
+ * oversight rather than as "this surface takes no overrides".
+ */
+customRenderers?: Partial<Record<OnboardingElementType, React.FC<GuidanceElementRendererProps>>>): React.FC<GuidanceElementRendererProps> | undefined;
 export interface GuidanceRendererProps {
     customRenderers?: Partial<Record<OnboardingElementType, React.FC<GuidanceElementRendererProps>>>;
 }

package/dist/esm/core/guidance/GuidanceRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GuidanceRenderer.d.ts","sourceRoot":"","sources":["../../../../src/core/guidance/GuidanceRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAA+B,MAAM,OAAO,CAAC;AAEpD,OAAO,KAAK,EAEV,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAwB/B,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACxC,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrH,SAAS,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,yGAAyG;IACzG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CAClF;AA8ED,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC;CAClG;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAqL5D,CAAC"}
+{"version":3,"file":"GuidanceRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/core/guidance/GuidanceRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAkD,MAAM,OAAO,CAAC;AAEvE,OAAO,KAAK,EAEV,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,qBAAqB,EAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAmB,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAwB7F,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACxC;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChK,SAAS,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,yGAAyG;IACzG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CAClF;AAoBD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,qBAAqB,EAAE,qBAAqB,CAWhG,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,qBAAqB;AAClC;;;;GAIG;AACH,eAAe,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,4BAA4B,CAAC,CAAC,CAAC,GAC/F,KAAK,CAAC,EAAE,CAAC,4BAA4B,CAAC,GAAG,SAAS,CAWpD;AA0KD,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC;CAClG;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAoX5D,CAAC"}

package/dist/esm/core/guidance/GuidanceRenderer.js

@@ -8,9 +8,11 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * a flow is mapped to its type-specific renderer component via
  * RENDERER_MAP.
  */
-import React, { useCallback, useMemo } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
 import ReactDOM from 'react-dom';
-import { GuidanceRenderMode, OnboardingElementType, } from '@wildo-ai/saas-models';
+import { GuidanceRenderMode, OnboardingElementType, resolveGuidanceElementRequiredLabelFields, } from '@wildo-ai/saas-models';
+import { CorePresetNames, FrontendComponentType } from '@wildo-ai/presets-components-models';
+import { ComponentRegistryService } from '../../core/components-registry/component-registry.frontend.service.js';
 import { useGuidance } from './useGuidance.js';
 import { useI18n } from '../../core/i18n/useI18n.js';
 import { useEventBus } from '../../core/events/useEventBus.js';
@@ -44,6 +46,68 @@ const RENDERER_MAP = {
     [OnboardingElementType.CARD]: GuidanceCard,
     [OnboardingElementType.SURVEY]: GuidanceSurvey,
 };
+/**
+ * The component-registry slot each guidance element type is replaceable through.
+ *
+ * ## Why this map exists
+ *
+ * Every `GUIDANCE_*` component type was already declared, already carried a frontend-component
+ * SPECIFICATION advertising a `DEFAULT` preset and an exported registry key, and was already used
+ * as an i18n namespace by the renderer that implements it — but nothing ever joined the element
+ * type to the slot, so the slots were addressable for labels and unreachable for COMPONENTS. Each
+ * one sat on the registry-completeness deny-list under "framework-internal … not swappable", and an
+ * application that wanted a different banner had no way to supply one short of replacing the whole
+ * `APP_LAYOUT_MAIN_CONTAINER` preset.
+ *
+ * Total over `OnboardingElementType` by construction: a new element type is a compile error here
+ * until it declares which slot replaces it, rather than silently shipping as unswappable.
+ */
+export const GUIDANCE_ELEMENT_COMPONENT_TYPE = {
+    [OnboardingElementType.CHECKLIST]: FrontendComponentType.GUIDANCE_CHECKLIST,
+    [OnboardingElementType.CHECKLIST_ITEM]: FrontendComponentType.GUIDANCE_CHECKLIST_ITEM,
+    [OnboardingElementType.TOUR]: FrontendComponentType.GUIDANCE_TOUR,
+    [OnboardingElementType.TOOLTIP]: FrontendComponentType.GUIDANCE_TOOLTIP,
+    [OnboardingElementType.MODAL]: FrontendComponentType.GUIDANCE_MODAL,
+    [OnboardingElementType.BANNER]: FrontendComponentType.GUIDANCE_BANNER,
+    [OnboardingElementType.ANNOUNCEMENT]: FrontendComponentType.GUIDANCE_ANNOUNCEMENT,
+    [OnboardingElementType.BADGE]: FrontendComponentType.GUIDANCE_BADGE,
+    [OnboardingElementType.CARD]: FrontendComponentType.GUIDANCE_CARD,
+    [OnboardingElementType.SURVEY]: FrontendComponentType.GUIDANCE_SURVEY,
+};
+/**
+ * Resolve the component that renders one element type, most specific source first.
+ *
+ * `customRenderers` (a prop) → a REGISTERED preset → the engine's built-in renderer.
+ *
+ * ## Why this is not `createComponentResolver`
+ *
+ * That helper renders `ComponentNotInjected` when a slot has no registration, which is right for a
+ * slot the framework does not implement. These ten slots DO have working framework implementations,
+ * so a missing registration must fall through to the built-in rather than blank the element — an
+ * application that registers nothing keeps exactly the behaviour it has today, and one that
+ * registers a preset gets its own component. Registration is therefore purely additive and cannot
+ * break a guidance surface by its absence.
+ *
+ * `preset` is read from the registry under `CorePresetNames.DEFAULT`, which is the name an
+ * application overrides. Named alternative presets are deliberately NOT resolved here: nothing in a
+ * flow definition selects one, so admitting them would create a second selection axis with no
+ * authoring surface behind it.
+ */
+export function resolveGuidanceElementRenderer(elementType, 
+/**
+ * Optional, because the second caller — `OnboardingView` — has no equivalent prop. Leaving it
+ * required would have meant that surface passing a literal `undefined`, which reads as an
+ * oversight rather than as "this surface takes no overrides".
+ */
+customRenderers) {
+    const custom = customRenderers?.[elementType];
+    if (custom)
+        return custom;
+    const registered = ComponentRegistryService.resolve(GUIDANCE_ELEMENT_COMPONENT_TYPE[elementType], CorePresetNames.DEFAULT);
+    if (registered)
+        return registered;
+    return RENDERER_MAP[elementType];
+}
 // ─── Error Boundary ──────────────────────────────────────────────
 class GuidanceElementErrorBoundary extends React.Component {
     constructor(props) {
@@ -72,20 +136,162 @@ function resolveTargetSelector(element) {
     }
     return null;
 }
+// ─── Presentable Elements (#539) ─────────────────────────────────
+/**
+ * Whether an element mounted by the render loop actually PUTS SOMETHING ON SCREEN.
+ *
+ * Having a renderer is not the same as being visible, and four renderers answer `null` at runtime
+ * for reasons the render loop cannot see from the element alone:
+ *
+ * - a TOOLTIP whose `targetSelector` matches no node — it renders nothing until a rect exists;
+ * - a TOUR with no steps — `currentStep` is undefined and it returns before the portal;
+ * - an INLINE element whose portal target is absent — `InlinePortal` returns `null`;
+ * - any element of a CHECKLIST-mode flow that declares items and no container — the loop's own
+ *   container scan finds nothing and the items are never mounted.
+ *
+ * Each of those was counted as presented, so the flow's once-per-user occasion was spent on a
+ * screen the user saw nothing on. The DOM lookups here are the same ones the renderers perform, and
+ * this runs from an effect, after paint, so they see what the renderers saw AT THAT INSTANT.
+ *
+ * RESIDUAL, in the other direction and deliberately accepted: the presentation effect re-runs on
+ * `activeFlows` and has no DOM signal, while `GuidanceTooltip` re-resolves its target on scroll,
+ * resize and a `ResizeObserver`. A tooltip whose target mounts AFTER this effect therefore becomes
+ * visible and is never recorded, so its flow fires again next session. That errs toward showing a
+ * flow twice rather than spending an occasion on nothing, which is the direction #539 asks for —
+ * but it is a residual, not an absence, and closing it means subscribing to the same signals the
+ * renderers use.
+ */
+/**
+ * `document.querySelector` over an AUTHOR-SUPPLIED string, which may not be a selector at all.
+ *
+ * `targetSelector` is a bare `z.string()`, so `''` or a malformed value makes `querySelector` throw
+ * `SyntaxError`. That used to be contained: the lookup lived inside `GuidanceTooltip`'s own effect,
+ * under `GuidanceElementErrorBoundary`, so one bad selector cost one element. The visibility check
+ * runs from `GuidanceRenderer`'s presentation effect, ABOVE every boundary it renders, so an
+ * unguarded throw there takes the whole guidance surface down instead.
+ *
+ * A selector that cannot be parsed matches nothing, so `false` is also the truthful answer.
+ */
+function matchesSomething(selector) {
+    try {
+        return Boolean(document.querySelector(selector));
+    }
+    catch {
+        if (!warnedInvalidSelectors.has(selector)) {
+            warnedInvalidSelectors.add(selector);
+            LoggerFrontendService.getLogger().warn(`GuidanceRenderer: "${selector}" is not a valid CSS selector, so the element targeting it can never be shown.`);
+        }
+        return false;
+    }
+}
+/** Selectors already reported as unparseable, so the warning fires once rather than per render. */
+const warnedInvalidSelectors = new Set();
+function isElementVisible(flow, element) {
+    if (typeof document === 'undefined')
+        return false;
+    if (element.type === OnboardingElementType.TOOLTIP) {
+        const selector = element.targetSelector;
+        return typeof selector === 'string' && matchesSomething(selector);
+    }
+    if (element.type === OnboardingElementType.TOUR) {
+        const steps = element.steps;
+        return Array.isArray(steps) && steps.length > 0;
+    }
+    if (flow.renderMode === GuidanceRenderMode.INLINE) {
+        // An inline element with no selector renders in place rather than through a portal, so only a
+        // DECLARED target that resolves to nothing makes it invisible.
+        const selector = resolveTargetSelector(element);
+        return selector === null || matchesSomething(selector);
+    }
+    return true;
+}
+/**
+ * The elements this renderer actually SHOWS for a flow — the population whose copy decides whether
+ * showing the flow spends its occasion.
+ *
+ * CHECKLIST mode renders only its containers and items, and only when a container exists; every
+ * other mode renders every element that has a renderer AND is visible. Kept beside the render
+ * loop's own selection so the two cannot disagree about which elements a person sees — which they
+ * did, because this function asked only whether a renderer existed. See {@link isElementVisible}.
+ */
+function selectPresentedElements(flow, renderers) {
+    const hasRenderer = (element) => {
+        const Renderer = renderers[element.type];
+        return Boolean(Renderer) && Renderer !== UnimplementedRenderer;
+    };
+    if (flow.renderMode === GuidanceRenderMode.CHECKLIST) {
+        const containers = flow.elements.filter(el => el.type === OnboardingElementType.CHECKLIST && hasRenderer(el));
+        // No container, no items: the render loop scans for containers and never reaches the items.
+        if (containers.length === 0)
+            return [];
+        return flow.elements.filter(el => (el.type === OnboardingElementType.CHECKLIST || el.type === OnboardingElementType.CHECKLIST_ITEM) && hasRenderer(el));
+    }
+    return flow.elements.filter(el => hasRenderer(el) && isElementVisible(flow, el));
+}
 // ─── Inline Portal Wrapper ───────────────────────────────────────
 const InlinePortal = ({ targetSelector, children }) => {
-    const target = typeof document !== 'undefined' ? document.querySelector(targetSelector) : null;
+    // Through the guarded lookup: this call is in the RENDER path and outside every error boundary
+    // this file mounts, so an author-supplied string that is not a valid selector would throw
+    // `SyntaxError` and take the whole guidance surface down rather than hiding one element.
+    const target = typeof document !== 'undefined' && matchesSomething(targetSelector)
+        ? document.querySelector(targetSelector)
+        : null;
     if (!target)
         return null;
     return ReactDOM.createPortal(_jsx("div", { className: "absolute z-[calc(var(--z-guidance)-2)]", children: children }), target);
 };
 export const GuidanceRenderer = ({ customRenderers }) => {
-    const { activeFlows, flowStates, completeElement, dismissFlow, completeFlow } = useGuidance();
+    const { activeFlows, flowStates, completeElement, dismissFlow, recordFlowPresented, reportFlowNotPresentable } = useGuidance();
     const guidanceI18nKeys = useMemo(() => activeFlows.map(f => `guidance.${f.ref}`), [activeFlows]);
-    const { makeTrGuidanceElement, tComponent, isReady: isGuidanceI18nReady } = useI18n({ keys: guidanceI18nKeys });
+    const { makeTrGuidanceElement, tGuidanceElement, isReady: isGuidanceI18nReady } = useI18n({ keys: guidanceI18nKeys });
     const { emit } = useEventBus();
     const portalContainer = usePortalContainer();
-    const effectiveRenderers = useMemo(() => ({ ...RENDERER_MAP, ...customRenderers }), [customRenderers]);
+    /**
+     * One resolved renderer per element type, built through
+     * {@link resolveGuidanceElementRenderer} so a registered preset participates.
+     *
+     * This was `{ ...RENDERER_MAP, ...customRenderers }` — a spread over the built-ins that gave the
+     * component registry no say at all, which is why every guidance surface was unswappable in
+     * practice while its specification advertised a preset.
+     *
+     * ## Why the registration COUNT is a dependency
+     *
+     * An earlier version deliberately took none, reasoning that "the registry is a module-level
+     * singleton populated once at startup, before anything renders". That is an assumption about every
+     * host, not a property of the registry: a lazily-loaded preset bundle, a registration inside an
+     * effect, and a code-split design system all register AFTER this memo first resolves — and the
+     * failure is silent, because the application's component simply never appears.
+     *
+     * `getRegistrationCount()` grows with every new key, so it is the cheapest available version
+     * signal and re-resolving costs one map lookup per element type. RESIDUAL: re-registering an
+     * EXISTING key replaces the value without changing the count. That cannot affect a guidance slot
+     * today — nothing in the engine registers one, so the first registration is always a new key — but
+     * a registry that published a change signal would remove the caveat as well as the polling.
+     *
+     * ## Why the resolved map keeps its identity
+     *
+     * It is a dependency of `renderedFlows`, and the overwhelmingly common `customRenderers` call
+     * shape is an inline object literal — a new identity every render. Returning the PREVIOUS object
+     * when every entry is unchanged keeps that memo effective while still letting a genuine change
+     * through.
+     */
+    const registrationCount = ComponentRegistryService.getRegistrationCount();
+    const resolvedRenderersRef = useRef(null);
+    const effectiveRenderers = useMemo(() => {
+        const resolved = {};
+        for (const elementType of Object.values(OnboardingElementType)) {
+            const renderer = resolveGuidanceElementRenderer(elementType, customRenderers);
+            if (renderer)
+                resolved[elementType] = renderer;
+        }
+        const next = resolved;
+        const previous = resolvedRenderersRef.current;
+        if (previous && Object.values(OnboardingElementType).every(type => previous[type] === next[type])) {
+            return previous;
+        }
+        resolvedRenderersRef.current = next;
+        return next;
+    }, [customRenderers, registrationCount]);
     // Emit NAVIGATION_REQUEST with the unresolved operationRef.
     // Guidance sits above ResourceRegistryProvider, so we use the
     // operationRef shorthand (same pattern as NotificationContext).
@@ -98,7 +304,9 @@ export const GuidanceRenderer = ({ customRenderers }) => {
         });
     }, [emit]);
     const handleComplete = useCallback((flowRef, elementRef, data) => {
-        completeElement(flowRef, elementRef, data);
+        // The promise is RETURNED rather than swallowed: a bound survey rejects when its write is
+        // refused, and its renderer awaits that to keep the form open (#1372).
+        return completeElement(flowRef, elementRef, data);
     }, [completeElement]);
     const handleDismiss = useCallback((flowRef, _elementRef) => {
         dismissFlow(flowRef);
@@ -121,12 +329,12 @@ export const GuidanceRenderer = ({ customRenderers }) => {
                     if (!ChecklistRenderer || ChecklistRenderer === UnimplementedRenderer)
                         continue;
                     const containerState = flowState?.elements?.[container.ref];
-                    const containerT = makeTrGuidanceElement(flow.ref, container.ref);
+                    const containerT = makeTrGuidanceElement(flow.ref, container.ref, resolveGuidanceElementRequiredLabelFields(container));
                     const ItemRenderer = effectiveRenderers[OnboardingElementType.CHECKLIST_ITEM];
                     const itemNodes = ItemRenderer && ItemRenderer !== UnimplementedRenderer
                         ? itemElements.map(item => {
                             const itemState = flowState?.elements?.[item.ref];
-                            const itemT = makeTrGuidanceElement(flow.ref, item.ref);
+                            const itemT = makeTrGuidanceElement(flow.ref, item.ref, resolveGuidanceElementRequiredLabelFields(item));
                             return (_jsx(GuidanceElementErrorBoundary, { elementRef: item.ref, children: _jsx(ItemRenderer, { element: item, flowRef: flow.ref, state: itemState, onComplete: (elRef, data) => handleComplete(flow.ref, elRef, data), onDismiss: (elRef) => handleDismiss(flow.ref, elRef), onAction: handleAction, t: itemT }) }, `${flow.ref}-${item.ref}`));
                         })
                         : null;
@@ -140,7 +348,7 @@ export const GuidanceRenderer = ({ customRenderers }) => {
                 if (!Renderer || Renderer === UnimplementedRenderer)
                     continue;
                 const elementState = flowState?.elements?.[element.ref];
-                const t = makeTrGuidanceElement(flow.ref, element.ref);
+                const t = makeTrGuidanceElement(flow.ref, element.ref, resolveGuidanceElementRequiredLabelFields(element));
                 const node = (_jsx(GuidanceElementErrorBoundary, { elementRef: element.ref, children: _jsx(Renderer, { element: element, flowRef: flow.ref, state: elementState, onComplete: (elRef, data) => handleComplete(flow.ref, elRef, data), onDismiss: (elRef) => handleDismiss(flow.ref, elRef), onAction: handleAction, t: t }) }, `${flow.ref}-${element.ref}`));
                 switch (flow.renderMode) {
                     case GuidanceRenderMode.OVERLAY:
@@ -160,7 +368,56 @@ export const GuidanceRenderer = ({ customRenderers }) => {
             }
         }
         return { overlayElements, inlineElements, checklistElements };
-    }, [activeFlows, flowStates, makeTrGuidanceElement, handleAction, handleComplete, handleDismiss]);
+        // `effectiveRenderers` is read at three sites in this block and was MISSING from these
+        // dependencies, so the memo kept the first resolution for the component's life: a
+        // `customRenderers` prop that changed — a feature flag, a lazily loaded bundle, an A/B arm —
+        // never took effect. It is identity-stable by content (see its own docblock), so including it
+        // does not defeat the memo for the common inline-literal call shape.
+    }, [activeFlows, flowStates, effectiveRenderers, makeTrGuidanceElement, handleAction, handleComplete, handleDismiss]);
+    /*
+     * PRESENTATION — the moment a flow's once-per-user occasion is spent (#539).
+     *
+     * Only this layer knows whether a flow's copy exists, so only this layer may
+     * decide that showing it counted. A flow with every required label resolved is
+     * recorded as presented. A flow missing one is still RENDERED — its required slots
+     * show their raw keys, so the gap is visible — but it is not recorded, so it fires
+     * again once the labelling pipeline has generated its copy instead of having been
+     * silently consumed by an author's first run. The console names the missing keys,
+     * once per flow and missing set, because every request in that situation is a 200.
+     *
+     * Waits for readiness: before the bundle settles every key reads as missing, and
+     * recording nothing then is correct but warning would be noise.
+     */
+    const warnedMissingLabelSignaturesRef = useRef(new Set());
+    useEffect(() => {
+        if (!isGuidanceI18nReady)
+            return;
+        for (const flow of activeFlows) {
+            const presentedElements = selectPresentedElements(flow, effectiveRenderers);
+            /*
+             * Tell the context when a flow resolves to NOTHING. An OVERLAY flow whose elements never
+             * render still occupied the single overlay slot for the session — it never reaches a terminal
+             * status, so it never leaves the active set — and permanently suppressed a lower-priority
+             * flow that would have rendered.
+             */
+            reportFlowNotPresentable(flow.ref, presentedElements.length === 0);
+            if (presentedElements.length === 0)
+                continue;
+            const missingKeys = presentedElements.flatMap(element => resolveGuidanceElementRequiredLabelFields(element)
+                .filter(field => tGuidanceElement(flow.ref, element.ref, field) === undefined)
+                .map(field => `guidance.${flow.ref}.elements.${element.ref}.${field}`));
+            if (missingKeys.length === 0) {
+                recordFlowPresented(flow.ref);
+                continue;
+            }
+            const signature = `${flow.ref}|${missingKeys.join(',')}`;
+            if (warnedMissingLabelSignaturesRef.current.has(signature))
+                continue;
+            warnedMissingLabelSignaturesRef.current.add(signature);
+            LoggerFrontendService.getLogger().warn(`GuidanceRenderer: flow "${flow.ref}" is shown but NOT recorded as presented — its required labels are unresolved `
+                + `[${missingKeys.join(', ')}]. Generate the labels; the flow will trigger again once they exist.`);
+        }
+    }, [isGuidanceI18nReady, activeFlows, effectiveRenderers, tGuidanceElement, recordFlowPresented]);
     if (!isGuidanceI18nReady)
         return null;
     if (!renderedFlows)
@@ -170,8 +427,93 @@ export const GuidanceRenderer = ({ customRenderers }) => {
     if (!hasContent)
         return null;
     const portalTarget = typeof document !== 'undefined' ? portalContainer ?? document.body : undefined;
+    /**
+     * The guidance layers position against the CONTENT AREA, not the viewport.
+     *
+     * ## What was wrong, measured in a running application
+     *
+     * Both layers were `fixed`. A fixed element resolves against the VIEWPORT and ignores whatever
+     * containing block it was portalled into — so with the app shell's `<main>` at
+     * `left: 256, top: 52` (sidebar 256 wide, header 52 tall), the overlay layer still covered
+     * `0,0 → 1440×1000` and `GuidanceBanner`'s `absolute top-0 inset-x-0` landed on the viewport's top
+     * edge. `document.elementFromPoint` at the header's own centre returned the BANNER's title: the
+     * logo, the resource selector, global search, notifications and the user avatar were all covered,
+     * and since the banner sets `pointer-events-auto` it took their clicks too. A dismissible notice
+     * was hiding the application's primary navigation for as long as it was up.
+     *
+     * ## Why `absolute` is the fix rather than an offset
+     *
+     * The shell already publishes the right anchor and makes it work: `app-layout-main-container`
+     * renders `<main ref={portalRef} className="flex-1 relative min-w-0">` and hands that element to
+     * `PortalContainerContext`, so it is BOTH the portal target and a containing block. `fixed` was
+     * the one thing standing between that arrangement and the correct result; `absolute inset-0` fills
+     * the content area exactly, and every self-positioning child — the banner's `top-0`, the
+     * checklist's `bottom-6 end-6` — then means the top and bottom of the content area, which is what
+     * those authoring values have always claimed to mean. No offset to keep in step with a header
+     * height, and an END sidebar or a bottom status bar is respected for free.
+     *
+     * ## The fallback, and the contract
+     *
+     * With no portal container — the public and auth layouts, and unit tests — the target is
+     * `document.body`, which is not positioned, so the layers stay `fixed` and behave exactly as
+     * before. The contract this relies on: **a guidance portal container must be a containing block**
+     * (`position` other than `static`). One provider sets it today and it satisfies that; a host that
+     * sets its own must too.
+     */
+    const layerPosition = portalContainer ? 'absolute' : 'fixed';
     return (_jsxs(_Fragment, { children: [overlayElements.length > 0 && portalTarget &&
-                ReactDOM.createPortal(_jsx("div", { "data-guidance-layer": "overlay", className: "fixed inset-0 z-(--z-guidance) pointer-events-none", children: overlayElements }), portalTarget), inlineElements, checklistElements.length > 0 && portalTarget &&
-                ReactDOM.createPortal(_jsx("div", { "data-guidance-layer": "checklist", className: "fixed bottom-6 end-6 z-[calc(var(--z-guidance)-1)]", children: checklistElements }), portalTarget)] }));
+                ReactDOM.createPortal(
+                /**
+                 * The OVERLAY layer positions the elements that do not position THEMSELVES.
+                 *
+                 * It was a bare `fixed inset-0 … pointer-events-none` with no layout at all. Modal, tour
+                 * and tooltip portal out of it and banner self-positions (`absolute top-0 inset-x-0`), so
+                 * those four were fine — but CARD, SURVEY, ANNOUNCEMENT and BADGE are ordinary in-flow
+                 * children, and an in-flow child of a `fixed inset-0` box with no layout renders
+                 * full-viewport-width, pinned to the top-left corner, stacked on top of any banner. That
+                 * is what `renderMode: OVERLAY` with any of those four element types actually produced,
+                 * and it is the default authoring path.
+                 *
+                 * Centred with a readable cap rather than stretched: an overlay card is a focal message,
+                 * and `max-w-md` is the width `GuidanceModal` already uses for the same kind of content,
+                 * so the two read as one system.
+                 *
+                 * ## No padding and no `overflow-y-auto` on THIS element, and both were here and wrong
+                 *
+                 * `GuidanceBanner` is `absolute top-0 inset-x-0` — NOT `fixed`, which an earlier version of
+                 * this comment asserted and reasoned from. An absolutely positioned child resolves against
+                 * the nearest positioned ancestor's PADDING BOX, and this layer is that ancestor, so a
+                 * `p-element` here inset the banner from all four viewport edges — visibly breaking the one
+                 * overlay element that had always positioned itself correctly. Edge spacing therefore lives
+                 * on the per-element wrapper below, which is static and so is not a containing block.
+                 *
+                 * `overflow-y-auto` was added claiming it made a third card reachable. It does not: content
+                 * overflowing the START edge of a centred flex container cannot be scrolled to, and the
+                 * layer is `pointer-events-none`, so a wheel event never targets it. Overflow with several
+                 * simultaneously eligible overlay flows is a real limitation and is left honestly
+                 * unaddressed rather than papered over by a class that does nothing.
+                 *
+                 * `pointer-events-none` stays — every renderer that is interactive sets
+                 * `pointer-events-auto` on its own root.
+                 */
+                _jsx("div", { "data-guidance-layer": "overlay", className: `${layerPosition} inset-0 z-(--z-guidance) pointer-events-none flex flex-col items-center justify-center gap-element`, children: overlayElements.map(node => (
+                    /**
+                     * Capped and padded per element rather than by a rule on the layer, because this
+                     * wrapper is STATIC: it establishes no containing block, so the absolutely positioned
+                     * banner resolves against the layer and ignores this box entirely, while
+                     * card/survey/announcement/badge are laid out by it. A `[&>*]` rule or padding on the
+                     * layer would reach the banner and did.
+                     *
+                     * `empty:hidden` because modal, tour, tooltip and banner all portal their DOM
+                     * elsewhere, leaving this wrapper with no child nodes. A childless flex item still
+                     * consumes a `gap`, so without this each portalling element added a slice of empty
+                     * space that pushed the genuinely centred cards off-centre.
+                     *
+                     * The node's OWN key is reused rather than the array index — these are keyed
+                     * `${flowRef}-${elementRef}` at construction, and several flows can be eligible at
+                     * once, so an index would remount the wrong subtree whenever eligibility reorders.
+                     */
+                    _jsx("div", { className: "w-full max-w-md shrink-0 px-element empty:hidden", children: node }, node.key))) }), portalTarget), inlineElements, checklistElements.length > 0 && portalTarget &&
+                ReactDOM.createPortal(_jsx("div", { "data-guidance-layer": "checklist", className: `${layerPosition} bottom-6 end-6 z-[calc(var(--z-guidance)-1)]`, children: checklistElements }), portalTarget)] }));
 };
 //# sourceMappingURL=GuidanceRenderer.js.map