@salesforce/afv-skills 1.46.0 → 1.47.0

package/skills/experience-cms-content-render/assets/angular/cms-content.component.ts

@@ -0,0 +1,248 @@
+/**
+ * CmsContentComponent — schema-less body renderer for Angular (Init →
+ * src/cms/angular/cms-content.component.ts). Counterpart of React's heuristicRenderer.
+ * Picks fields by priority (title/image/excerpt) or a `fields` whitelist, then
+ * classifies each by shape. Holds the ONE RichText injection path (Rule 4): decode,
+ * then `[innerHTML]` — Angular's DomSanitizer sanitizes it, so NEVER
+ * bypassSecurityTrustHtml. Rules: references/heuristic-render-rules.md.
+ */
+import { Component, Input, type OnChanges } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import {
+  decodeRichHtmlEntities,
+  resolveCmsImageUrl,
+} from '@salesforce/ui-bundle-template-feature-cms-toolkit';
+import type { CmsImageField } from '../shared/cmsCore.types';
+
+const IMAGE_PRIORITY = ['bannerImage', 'featuredImage', 'heroImage', 'coverImage', 'thumbnail', 'image'];
+const EXCERPT_PRIORITY = ['excerpt', 'summary', 'description', 'subtitle'];
+
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}/;
+const URL_RE = /^https?:\/\//;
+// Match an HTML tag-open (`<tag`, `</`, `<!`) AND entity-encoded HTML (`&lt;`) — the
+// encoded form has no literal `<`, so a `<`-only check would skip decode entirely, while
+// a bare `<` in prose ("Q4 < projected") must NOT be treated as markup (Rule 4).
+const RICH_TEXT_RE = /<[a-z!/]|&lt;|&#(?:60|x3c);/i;
+
+// ISO_DATE_RE only checks the PREFIX, so unparseable strings ("2024-13-99") and SKUs
+// ("1234-56-78") slip through; `Intl.DateTimeFormat.format` throws RangeError on an
+// Invalid Date, which would break the whole render. Return null on invalid so the
+// caller falls through to the next classifier / skips the field.
+function formatCmsDate(value: string, options: Intl.DateTimeFormatOptions): string | null {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  return new Intl.DateTimeFormat('en-US', options).format(date);
+}
+
+/** One renderable cell — a discriminated union the template switches on. */
+type Cell =
+  | { kind: 'title'; text: string }
+  | { kind: 'richText'; html: string }
+  | { kind: 'date'; iso: string; label: string }
+  | { kind: 'url'; href: string }
+  | { kind: 'image'; src: string; alt: string }
+  | { kind: 'number'; text: string }
+  | { kind: 'boolean'; label: string }
+  | { kind: 'text'; text: string };
+
+@Component({
+  selector: 'cms-content',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    @if (loading) {
+      <div role="status">Loading…</div>
+    } @else if (error) {
+      <div role="alert">{{ error.message }}</div>
+    } @else if (body) {
+      <article [class]="className">
+        @for (cell of cells; track $index) {
+          @switch (cell.kind) {
+            @case ('title') {
+              @if (layout === 'detail') { <h1>{{ cell.text }}</h1> }
+              @else { <h2>{{ cell.text }}</h2> }
+            }
+            <!-- Decoded, then Angular's DomSanitizer sanitizes the [innerHTML] binding. -->
+            @case ('richText') { <div [innerHTML]="cell.html"></div> }
+            @case ('date') { <time [attr.dateTime]="cell.iso">{{ cell.label }}</time> }
+            @case ('url') {
+              <a [href]="cell.href" target="_blank" rel="noopener noreferrer"
+                 [attr.aria-label]="'External link: ' + cell.href">{{ cell.href }}</a>
+            }
+            @case ('image') { <img [src]="cell.src" [alt]="cell.alt" loading="lazy" /> }
+            @case ('number') { <span>{{ cell.text }}</span> }
+            @case ('boolean') { <span class="badge">{{ cell.label }}</span> }
+            @case ('text') { <p>{{ cell.text }}</p> }
+          }
+        }
+      </article>
+    }
+  `,
+})
+export class CmsContentComponent implements OnChanges {
+  @Input() body: Record<string, unknown> | undefined;
+  @Input() loading = false;
+  @Input() error: Error | undefined;
+  @Input() layout: 'list' | 'detail' = 'detail';
+  /** Optional whitelist — bypasses priority lists and renders only these fields in order. */
+  @Input() fields?: ReadonlyArray<string>;
+  @Input() className?: string;
+  /** Resolve a `references`-bag contentKey to its media field (rare payload shape). */
+  @Input() resolveRef?: (contentKey: string) => CmsImageField | undefined;
+
+  /** Recomputed on every input change — the template reads this. */
+  cells: Cell[] = [];
+
+  ngOnChanges(): void {
+    this.cells = this.body ? this.buildCells(this.body) : [];
+  }
+
+  private buildCells(body: Record<string, unknown>): Cell[] {
+    // Whitelist mode — render exactly these fields, in order, by shape.
+    if (this.fields && this.fields.length > 0) {
+      const out: Cell[] = [];
+      for (const name of this.fields) {
+        const cell = this.classify(name, body[name]);
+        if (cell) out.push(cell);
+      }
+      return out;
+    }
+
+    // Heuristic mode — title, then first image, then first excerpt, then the rest.
+    const out: Cell[] = [];
+    const consumed = new Set<string>();
+
+    const title = this.pickTitle(body);
+    if (title) {
+      out.push({ kind: 'title', text: title.value });
+      consumed.add(title.name);
+    }
+
+    const imageField = this.pickFirstField(body, IMAGE_PRIORITY, isImageObject);
+    if (imageField) {
+      consumed.add(imageField.name);
+      const src = this.resolveImageSrc(imageField.value);
+      if (src) out.push({ kind: 'image', src, alt: resolveImageAlt(imageField.value) });
+    }
+
+    const excerpt = this.pickFirstField<string>(
+      body,
+      EXCERPT_PRIORITY,
+      (v) => typeof v === 'string' && v.length > 0,
+    );
+    if (excerpt) {
+      consumed.add(excerpt.name);
+      out.push({ kind: 'text', text: excerpt.value });
+    }
+
+    if (this.layout === 'detail') {
+      for (const [k, v] of Object.entries(body)) {
+        if (consumed.has(k)) continue;
+        const cell = this.classify(k, v);
+        if (cell) out.push(cell);
+      }
+    }
+
+    return out;
+  }
+
+  /** Value-shape dispatcher — the Angular parallel of RenderField. */
+  private classify(name: string, value: unknown): Cell | null {
+    if (value == null) return null;
+
+    if (typeof value === 'string') {
+      if (RICH_TEXT_RE.test(value)) {
+        // Decode first (else tags render as literal text); [innerHTML] is then
+        // sanitized by Angular's DomSanitizer. Rule 4.
+        return { kind: 'richText', html: decodeRichHtmlEntities(value) };
+      }
+      if (ISO_DATE_RE.test(value)) {
+        const label = formatCmsDate(value, { dateStyle: 'medium' });
+        // Valid date → date cell; invalid (matched the prefix but unparseable) → fall through.
+        if (label) return { kind: 'date', iso: value, label };
+      }
+      if (URL_RE.test(value)) return { kind: 'url', href: value };
+      if (/title/i.test(name)) return { kind: 'title', text: value };
+      return { kind: 'text', text: value };
+    }
+
+    if (typeof value === 'number') {
+      return { kind: 'number', text: new Intl.NumberFormat().format(value) };
+    }
+
+    if (typeof value === 'boolean') {
+      return { kind: 'boolean', label: value ? 'Yes' : 'No' };
+    }
+
+    if (typeof value === 'object') {
+      const obj = value as Record<string, unknown>;
+      // dateTime shape
+      if (typeof obj.dateTime === 'string') {
+        const label = formatCmsDate(obj.dateTime, {
+          dateStyle: 'medium',
+          timeStyle: 'short',
+          timeZone: typeof obj.timeZone === 'string' ? obj.timeZone : undefined,
+        });
+        // Invalid dateTime → skip this field rather than crash the render.
+        return label ? { kind: 'date', iso: obj.dateTime, label } : null;
+      }
+      // image-shaped object
+      if (isImageObject(obj)) {
+        const src = this.resolveImageSrc(obj);
+        return src ? { kind: 'image', src, alt: resolveImageAlt(obj) } : null;
+      }
+      // contentReference shape
+      const refObj = (obj as { ref?: { contentKey?: string } }).ref;
+      if (refObj && typeof refObj.contentKey === 'string' && this.resolveRef) {
+        const resolved = this.resolveRef(refObj.contentKey);
+        if (!resolved) return null;
+        return { kind: 'text', text: (resolved as { title?: string }).title ?? refObj.contentKey };
+      }
+      return null;
+    }
+
+    return null;
+  }
+
+  /** Delivery image field → loadable `src` via the toolkit (resolves the relative
+   *  Connect-API url; no options passed). */
+  private resolveImageSrc(field: unknown): string | undefined {
+    return resolveCmsImageUrl(field as CmsImageField | undefined);
+  }
+
+  private pickTitle(body: Record<string, unknown>): { name: string; value: string } | undefined {
+    if (typeof body['title'] === 'string') return { name: 'title', value: body['title'] };
+    for (const [k, v] of Object.entries(body)) {
+      if (typeof v === 'string' && /title/i.test(k)) return { name: k, value: v };
+    }
+    return undefined;
+  }
+
+  private pickFirstField<T = unknown>(
+    body: Record<string, unknown>,
+    priority: string[],
+    predicate: (v: unknown) => boolean,
+  ): { name: string; value: T } | undefined {
+    for (const k of priority) {
+      const v = body[k];
+      if (v != null && predicate(v)) return { name: k, value: v as T };
+    }
+    return undefined;
+  }
+}
+
+function isImageObject(v: unknown): boolean {
+  if (!v || typeof v !== 'object') return false;
+  const o = v as { url?: unknown; source?: { type?: unknown } };
+  return typeof o.url === 'string' || (o.source != null && typeof o.source.type === 'string');
+}
+
+/** Delivery image field → authored alt text. Empty string when the field carries none —
+ *  a decorative image (WCAG 1.1.1), not a missing attribute. */
+function resolveImageAlt(field: unknown): string {
+  if (field && typeof field === 'object') {
+    const alt = (field as { altText?: unknown }).altText;
+    if (typeof alt === 'string') return alt;
+  }
+  return '';
+}

package/skills/experience-cms-content-render/assets/angular/cms-item.service.ts

@@ -0,0 +1,100 @@
+/**
+ * CmsItemService — single-content data layer for Angular (Init →
+ * src/cms/angular/cms-item.service.ts). Counterpart of React's `useCmsItem`.
+ * Owns a per-ref cache + inflight dedup and dispatches on ref type (CmsExternalRef
+ * `url` → getCmsContentByUrl / CDN; CmsRef `contentKey` → getCmsContentByKey /
+ * Connect). `providedIn: 'root'` → one instance app-wide, so the maps are shared.
+ * `load()` never rejects — failures resolve with `error` set.
+ */
+import { Injectable } from '@angular/core';
+import {
+  getCmsContentByUrl,
+  getCmsContentByKey,
+  CmsDeliveryError,
+  CmsDeliveryNotFoundError,
+  ConnectApiError,
+  CmsNotFoundError,
+} from '@salesforce/ui-bundle-template-feature-cms-toolkit';
+import type { AnyCmsRef, CmsRef } from '../shared/cmsCore.types';
+import { CMS_CHANNEL_ID_FALLBACK } from '../shared/externalRefs';
+
+/** Resolved state for one ref read — the component maps this onto signals. */
+export interface CmsItemResult<TBody> {
+  body: TBody | undefined;
+  error: Error | undefined;
+}
+
+@Injectable({ providedIn: 'root' })
+export class CmsItemService {
+  // Shared across every consumer of this singleton service.
+  private readonly cache = new Map<string, unknown>();
+  private readonly inflight = new Map<string, Promise<unknown>>();
+
+  /**
+   * Read one item by ref — resolves the unwrapped body or a typed error, never
+   * rejects. Deduped by `ref.name`; the shared request carries NO AbortSignal, so a
+   * component torn down mid-flight ignores the late result rather than aborting.
+   */
+  async load<TBody = unknown>(ref: AnyCmsRef): Promise<CmsItemResult<TBody>> {
+    const name = ref.name;
+
+    const cached = this.cache.get(name) as TBody | undefined;
+    if (cached !== undefined) {
+      return { body: cached, error: undefined };
+    }
+
+    let promise = this.inflight.get(name) as Promise<TBody> | undefined;
+    if (!promise) {
+      promise = this.createItemRequest<TBody>(ref);
+      this.inflight.set(name, promise);
+      // Self-cleaning: cache on success, always drop the inflight entry.
+      promise
+        .then((body) => {
+          this.cache.set(name, body);
+        })
+        .catch(() => {
+          /* surfaced to the caller below; swallow to avoid unhandled rejection */
+        })
+        .finally(() => {
+          if (this.inflight.get(name) === promise) this.inflight.delete(name);
+        });
+    }
+
+    try {
+      const body = await promise;
+      return { body, error: undefined };
+    } catch (err: unknown) {
+      return { body: undefined, error: this.normalizeError(err) };
+    }
+  }
+
+  /** Dispatch on ref type. NO abort signal — the request is shared (see `load`). */
+  private createItemRequest<TBody>(ref: AnyCmsRef): Promise<TBody> {
+    // Foreign ref — public delivery URL fetched AS-IS (Rule 1).
+    if ('url' in ref && typeof ref.url === 'string') {
+      return getCmsContentByUrl<TBody>(ref.url);
+    }
+    // uiBundle-space ref — toolkit remaps the contentKey (fail-open) and reads Connect.
+    const channelId = CMS_CHANNEL_ID_FALLBACK || undefined;
+    return getCmsContentByKey<TBody>((ref as CmsRef).contentKey, { channelId });
+  }
+
+  /** Pass through the toolkit's typed errors as-is; wrap anything else. */
+  private normalizeError(err: unknown): Error {
+    if (
+      err instanceof CmsDeliveryNotFoundError ||
+      err instanceof CmsDeliveryError ||
+      err instanceof CmsNotFoundError ||
+      err instanceof ConnectApiError
+    ) {
+      return err;
+    }
+    return err instanceof Error ? err : new Error('Unknown CMS fetch error');
+  }
+
+  /** Test-only escape hatch — reset the cache between test runs. */
+  __resetForTests(): void {
+    this.cache.clear();
+    this.inflight.clear();
+  }
+}

package/skills/experience-cms-content-render/assets/react/DetailPage.tsx

@@ -0,0 +1,20 @@
+/**
+ * {{PageName}} — auto-generated detail page for one {{type}} item (codegen-managed;
+ * regenerated in full). Customize via {{type}}Layouts/{{type}}Slots in
+ * `src/cms/react/types/{{type}}.ts`.
+ *
+ * Tokens: {{TypeRenderer}} renderer name · {{Type}} PascalCase · {{type}} camelCase ·
+ * {{REF_CONST}} ref catalog key · {{PageName}} export name · {{urlSlug}} route slug.
+ */
+import { {{TypeRenderer}} } from '../types/{{TypeRenderer}}';
+import { ref } from '../../shared/externalRefs';
+
+export function {{PageName}}() {
+  return (
+    <main className="cms-detail-page cms-{{type}}-detail-page">
+      <{{TypeRenderer}} ref={ref('{{REF_CONST}}')} layout="detail" />
+    </main>
+  );
+}
+
+export default {{PageName}};

package/skills/experience-cms-content-render/assets/react/MediaRenderer.tsx

@@ -0,0 +1,129 @@
+/**
+ * MediaRenderer — dedicated renderer for standalone CMS media (React; Init →
+ * src/cms/react/MediaRenderer.tsx). Media is a PREDEFINED type parallel to `news`:
+ * a media ref binds here at registration time and dispatches by `ref.cmsType`
+ * (`image`/`audio`/`video`/`document`) — NEVER by body shape, so audio/video/document
+ * can't be mis-caught by the heuristic renderer's `isImageObject` path (SKILL.md §B1).
+ *
+ * Dispatch is by `cmsType` AND ref shape (Rule 1/Rule 2):
+ *  - Foreign ref (`url`): a media `unauthenticatedUrl` is the ASSET itself, so the url
+ *    goes straight onto the element `src`/`href` — NO fetch, NO toolkit resolver. Alt
+ *    text / document label ride on the ref (threaded from the search hand-off or asked
+ *    at Ref Registration), since there is no fetched body to read them from.
+ *  - uiBundle-space ref (`contentKey`): fetch the body via useCmsItem, then resolve the
+ *    src by medium (image → resolveCmsImageUrl; audio/video/document → resolveMediaUrl).
+ *
+ * A media item is a single asset, not a field bag, so neither path delegates to
+ * heuristicRenderer. Players/links are elements, never injected HTML (Rule 4).
+ */
+import type { ReactNode } from 'react';
+import {
+  resolveCmsImageUrl,
+  resolveMediaUrl,
+} from '@salesforce/ui-bundle-template-feature-cms-toolkit';
+import { useCmsItem } from './useCmsItem';
+import {
+  type AnyCmsRef,
+  type CmsMediaBody,
+  type CmsMediaType,
+} from '../shared/cmsCore.types';
+
+export interface MediaRendererProps {
+  /** A media ref — `cmsType` selects the element; a non-media ref is a compile error. */
+  ref: AnyCmsRef<CmsMediaType>;
+  className?: string;
+}
+
+/**
+ * Emit the one element for a resolved media `src`. Shared by both paths so the element
+ * markup (and its a11y contract) lives in exactly one place.
+ */
+function mediaElement(
+  cmsType: CmsMediaType,
+  src: string,
+  alt: string,
+  docLabel: string,
+  className?: string,
+): ReactNode {
+  switch (cmsType) {
+    case 'image':
+      return <img className={className} src={src} alt={alt} loading="lazy" />;
+    case 'audio':
+      // altText is typically absent on audio → aria-label only when present.
+      return <audio className={className} controls src={src} aria-label={alt || undefined} />;
+    case 'video':
+      return <video className={className} controls src={src} aria-label={alt || undefined} />;
+    case 'document':
+      // Download link only — no inline preview (SKILL.md §B3). Name the link so it
+      // identifies WHAT downloads (WCAG 2.4.4), never a bare "Download" that is
+      // ambiguous when several media links share a page.
+      return <a className={className} href={src} download>{docLabel}</a>;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Foreign media ref — the `url` IS the asset (Rule 1/Rule 2). No fetch, no resolver:
+ * set it as the element src directly. `altText`/`title` come off the ref.
+ */
+function DirectMedia(props: {
+  cmsType: CmsMediaType;
+  url: string;
+  alt: string;
+  title?: string;
+  className?: string;
+}): ReactNode {
+  const { cmsType, url, alt, title, className } = props;
+  const docLabel = alt || title || 'Download';
+  return mediaElement(cmsType, url, alt, docLabel, className);
+}
+
+/**
+ * uiBundle-space media ref — fetch the body, then resolve the src by medium. This is the
+ * authenticated-Connect path; identical behaviour to before the direct-URL fork.
+ */
+function FetchedMedia(props: { ref: AnyCmsRef<CmsMediaType>; className?: string }): ReactNode {
+  const { ref, className } = props;
+  const { body, loading, error } = useCmsItem<CmsMediaBody>(ref);
+
+  if (loading) return <div role="status">Loading…</div>;
+  if (error) return <div role="alert">{error.message}</div>;
+  if (!body) return null;
+
+  const media = body['sfdc_cms:media'];
+  const alt = body.altText ?? '';
+  const docLabel = body.altText || body.title || 'Download';
+
+  // Src resolution SPLITS by medium (Rule 2): image → resolveCmsImageUrl;
+  // audio/video/document → resolveMediaUrl. Both toolkit helpers resolve the
+  // relative Connect-API url; no options are passed.
+  const src =
+    ref.cmsType === 'image' ? resolveCmsImageUrl(media) : media?.url ? resolveMediaUrl(media.url) : undefined;
+  if (!src) return null;
+
+  return mediaElement(ref.cmsType, src, alt, docLabel, className);
+}
+
+export function MediaRenderer(props: MediaRendererProps): ReactNode {
+  const { ref, className } = props;
+
+  // Foreign media ref: the unauthenticatedUrl is the asset src directly — no fetch
+  // (Rule 1). alt/title ride on the ref (search hand-off or Ref Registration ask).
+  if ('url' in ref && typeof ref.url === 'string') {
+    return (
+      <DirectMedia
+        cmsType={ref.cmsType}
+        url={ref.url}
+        alt={ref.altText ?? ''}
+        title={ref.title}
+        className={className}
+      />
+    );
+  }
+
+  // uiBundle-space ref (contentKey): fetch + resolve by medium.
+  return <FetchedMedia ref={ref} className={className} />;
+}
+
+export default MediaRenderer;

package/skills/experience-cms-content-render/assets/react/TypeList.tsx

@@ -0,0 +1,40 @@
+/**
+ * {{Type}}List — opt-in list/grid wrapper over N same-type refs (codegen-managed;
+ * scaffolded ONLY on a list/grid prompt, not by Init). Lands in src/cms/react/types/.
+ * One `{{Type}}Renderer` per ref → each item keeps its own useCmsItem + error branch
+ * (mixed contentKey/url refs are fine). List vs grid is `className` CSS
+ * (references/styling-scopes.md). For a single-round-trip batch read, call
+ * `getCmsContentByKeys` directly instead (references/bulk-loading.md).
+ *
+ * Tokens: {{Type}} PascalCase, {{type}} camelCase, {{TypeRenderer}} renderer name.
+ */
+import type { ReactNode } from 'react';
+import type { AnyCmsRef } from '../../shared/cmsCore.types';
+import { {{TypeRenderer}} } from './{{TypeRenderer}}';
+import type { {{Type}}Layout } from './{{type}}';
+
+export interface {{Type}}ListProps {
+  /** The group to render, one renderer per entry (e.g. `[ref('EXT_A'), ref('EXT_B')]`). */
+  refs: ReadonlyArray<AnyCmsRef<'{{type}}'>>;
+  /** Per-item layout (default `list`). Grid is achieved via `className` CSS. */
+  layout?: {{Type}}Layout;
+  className?: string;
+}
+
+export function {{Type}}List({
+  refs,
+  layout = 'list',
+  className,
+}: {{Type}}ListProps): ReactNode {
+  return (
+    <div role="list" className={className ?? 'cms-{{type}}-list'}>
+      {refs.map((r) => (
+        <div role="listitem" key={r.name}>
+          <{{Type}}Renderer ref={r} layout={layout} />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default {{Type}}List;

package/skills/experience-cms-content-render/assets/react/TypeRenderer.tsx

@@ -0,0 +1,64 @@
+/**
+ * {{Type}}Renderer — per-type wrapper (codegen-managed; regenerated on schema sync).
+ * No user region — customize via {{type}}Layouts/{{type}}Slots in `./{{type}}.ts`.
+ * Delegates ALL field rendering to heuristicRenderer — do NOT inject HTML here
+ * (Rule 4). `ref` is typed `AnyCmsRef<'{{type}}'>` — a ref whose `cmsType` differs is
+ * a compile error. Fields are read directly, never `.value` (Rule 5).
+ * Tokens: {{Type}} PascalCase, {{type}} camelCase.
+ */
+import type { ReactNode, ComponentType } from 'react';
+import type { AnyCmsRef } from '../../shared/cmsCore.types';
+import { useCmsItem } from '../useCmsItem';
+import { heuristicRenderer } from '../heuristicRenderer';
+import { {{type}}Layouts, {{type}}Slots, type {{Type}}Body, type {{Type}}Layout } from './{{type}}';
+
+export interface {{Type}}RendererProps {
+  ref: AnyCmsRef<'{{type}}'>;
+  layout?: {{Type}}Layout;
+  /** Whitelist of {{Type}}Body field names. Bypasses layout's default field list. */
+  fields?: ReadonlyArray<keyof {{Type}}Body & string>;
+  components?: {
+    Title?: ComponentType<{ value: string }>;
+    Image?: ComponentType<{ src: string; alt?: string }>;
+    RichText?: ComponentType<{ html: string }>;
+  };
+  className?: string;
+}
+
+export function {{Type}}Renderer(props: {{Type}}RendererProps): ReactNode {
+  const {
+    ref,
+    layout = 'card',
+    fields,
+    components,
+    className,
+  } = props;
+
+  const { body, loading, error } = useCmsItem<{{Type}}Body>(ref);
+
+  // fields: per-embed prop → layout preset → undefined (heuristic mode).
+  const layoutPreset = {{type}}Layouts[layout];
+  const resolvedFields = fields ?? layoutPreset.fields;
+
+  // components: per-embed prop → type-level slot defaults.
+  const resolvedComponents = {
+    ...(( {{type}}Slots as unknown) as {{Type}}RendererProps['components']),
+    ...components,
+  };
+
+  const resolvedClassName = className ?? layoutPreset.className;
+
+  // 'detail' layout key routes to detail-mode rendering; every other custom
+  // layout falls through to list-mode. Add more layouts in `{{type}}.ts`.
+  const rendererLayout = layout === 'detail' ? 'detail' : 'list';
+
+  return heuristicRenderer({
+    body: body as Record<string, unknown> | undefined,
+    loading,
+    error,
+    layout: rendererLayout,
+    fields: resolvedFields as ReadonlyArray<string> | undefined,
+    components: resolvedComponents,
+    className: resolvedClassName,
+  });
+}