@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/experience-cms-content-render/references/bulk-loading.md

@@ -0,0 +1,60 @@
+# Bulk content loading — a direct `getCmsContentByKeys` call
+
+To read a KNOWN set of `contentKey`s in ONE authenticated Connect round-trip, call
+the toolkit's `getCmsContentByKeys` directly. There is no batch-loader seam to
+scaffold and nothing to register — the per-item hook/service (`useCmsItem` /
+`CmsItemService`) is unchanged. Rendering N `<Type>Renderer`/`cms-<type>` cards
+still works (each reads individually); reach for bulk only when the extra round-
+trips matter and you already hold the keys.
+
+## When to use it
+
+On an explicit prompt to batch a list — e.g. *"bulk/batch-load the list"*, *"load
+these in one request"*, *"optimize the list fetching"*, AND the caller already
+knows the `contentKey`s (a curated set). Otherwise render per-item.
+
+## The call
+
+```ts
+import { getCmsContentByKeys } from '@salesforce/ui-bundle-template-feature-cms-toolkit';
+import type { CmsBulkResult } from '@salesforce/ui-bundle-template-feature-cms-toolkit';
+
+// Best-effort: never throws (except on abort). Each requested key comes back as a
+// CmsBulkResult with EITHER `body` OR `error`, echoing the requested contentKey.
+const results: CmsBulkResult<NewsBody>[] = await getCmsContentByKeys<NewsBody>(
+  ['M3ASD4KHASDB73', 'MCABCDEF123456'],
+  { channelId },   // optional; omit to let the catalog supply it
+);
+
+for (const r of results) {
+  if (r.error) {
+    // unpublished / wrong-channel / absent → CmsNotFoundError (per-key isolation)
+    console.warn(r.contentKey, r.error.message);
+  } else {
+    render(r.body);   // already unwrapped, envelope title lifted in
+  }
+}
+```
+
+- **Best-effort:** only an `AbortError` (via `options.signal`) rejects; every other
+  per-key failure comes back as `r.error` (a `CmsNotFoundError`).
+- **Match BY `contentKey`, never positionally** — each result echoes the requested
+  key even though the toolkit remaps source→target internally.
+- Keys are catalog-remapped (fail-open) and the channel resolves exactly as the
+  single-key read — `references/package-api.md`.
+
+## contentKey-only + mixed pages
+
+Only `contentKey`s batch. A `CmsExternalRef` (public `unauthenticatedUrl`) has no
+contentKey and is often a different channel/org — for news/structured content read it
+with `getCmsContentByUrl` individually. A mixed list becomes 1 bulk call for the key
+subset + N individual CDN fetches; wire the results into your own components. When you
+render one card per ref instead, each card's independent read already isolates failures.
+(A foreign `url` **media** ref is not fetched at all — its url is the asset src directly,
+Rule 1 — so it neither batches nor needs an individual read.)
+
+## Out of scope
+
+No DYNAMIC feed ("latest 10 news") — `getCmsContentByKeys` reads KNOWN keys; it
+does not discover or query a collection. Endpoint + response contract:
+`references/package-api.md`. Failure rows: `references/failure-modes.md`.

package/skills/experience-cms-content-render/references/codegen-guardrails.md

@@ -0,0 +1,111 @@
+# Codegen guardrails — Rules 1–5 (full)
+
+Five rules encoding defects a prior scaffold reproduced. Every generated app MUST
+satisfy all five; a violation is a blocking bug, not a style nit. They are baked into
+the templates under `assets/shared/`, `assets/react/`, `assets/angular/`; keep them
+true when editing. SKILL.md carries the one-line form of each rule — this file is the
+full text.
+
+## Rule 1 — Call the right toolkit read; never re-implement transport
+
+Dispatch on ref type: a `CmsExternalRef` (public `unauthenticatedUrl`) →
+`getCmsContentByUrl(url)`, fetched AS-IS; a `CmsRef` (`contentKey`) →
+`getCmsContentByKey`/`getCmsContentByKeys`, authenticated Connect. Do NOT reconstruct
+a delivery URL, prepend the instance URL / `/services/data/vXX`, hand-remap a
+`contentKey`, or route a CDN URL through Connect or vice versa; the package owns all
+of that.
+
+**Exception — standalone media on a foreign `url` ref is NOT fetched.** A media
+`unauthenticatedUrl` (`sfdc_cms__{image,audio,video,document}`) is the ASSET itself,
+not a delivery-JSON endpoint, so `MediaRenderer` sets `ref.url` directly onto the
+element `src`/`href` and calls neither `getCmsContentByUrl` nor a resolver (Rule 2).
+There is no fetched body, so alt text / document label ride on the ref (`altText` /
+`title`, threaded from the search hand-off or asked at Ref Registration). This is
+media-only: a `CmsExternalRef` for news/structured content is still fetched via
+`getCmsContentByUrl`, and a `contentKey` media ref still fetches via
+`getCmsContentByKey`.
+
+When a `CmsRef` needs a channel, **write `public/content-metadata.json`** with
+the resolved `channelId` and empty `contents: []` (create if absent; never overwrite a
+present channel). Write only a KNOWN channel (catalog / prompt / user) — **never a
+placeholder or fake `channelId`**: the toolkit fails open on a *missing* catalog, but a
+present-but-wrong one breaks every `byKey` read. The deploy pipeline regenerates the
+catalog per target org and fills the real `contents`. Endpoint + response contract +
+catalog shape: `references/package-api.md`.
+
+## Rule 2 — Resolve media `src` by ref shape, then by medium
+
+`MediaRenderer` forks first on **ref shape**, then (on the fetched path) by medium.
+
+**Foreign `url` ref — direct, no fetch, no resolver.** A media `unauthenticatedUrl`
+is the asset itself, so `ref.url` goes straight onto the element `src`/`href`. No
+`getCmsContentByUrl`, no `resolveCmsImageUrl`/`resolveMediaUrl`, no body. Alt text /
+document label come off the ref (`altText`/`title`). Emitting an `<img>` `src` from
+the resolver here is wrong — the url needs no resolution.
+
+**`contentKey` ref — fetch the body, then resolve by medium.** The `src` comes from
+the fetched body's `sfdc_cms:media` field, and the resolution SPLITS by medium — each
+side calls a toolkit SYNC resolver with ONLY its subject, no options object:
+
+- **image** → `resolveCmsImageUrl(body['sfdc_cms:media'])` — the SAME resolver the
+  heuristic renderer uses for image fields; media reuses it, not a parallel copy.
+- **audio / video / document** → `resolveMediaUrl(body['sfdc_cms:media'].url)` — the
+  toolkit's media resolver, given the body `url` string directly.
+
+The toolkit resolves the relative Connect-API url on its own — a relative media url
+works as-is and must NOT be hand-prefixed (no instance origin, no org origin, no
+`{ instanceOrigin }` option). Pass no second argument to either resolver. There is no
+local URL-prefixing helper; skill code never builds a media URL by hand. Media
+dispatch is by `ref.cmsType` and ref shape, never by body shape, so audio/video/document
+never enter the heuristic renderer's `isImageObject` path (SKILL.md §B1).
+
+## Rule 3 — Shared/deduped fetch state must survive React 19 StrictMode
+
+The React hook `useCmsItem` dedupes through a module-level `inflight` map and must
+survive mount→cleanup→remount: cleanup sets a local `cancelled` flag gating
+`setState` and MUST NOT abort the shared request; shared requests get no abort signal;
+`inflight` self-cleans via `.finally(delete)` at creation. The Angular
+`CmsItemService` uses the same shared `cache`/`inflight` maps and a stale-ref guard in
+`ngOnChanges`. Treat "works once, fails on remount" as a blocking bug.
+
+## Rule 4 — Decode RichText before injecting, through ONE path per framework
+
+Delivery returns RichText entity-encoded (`"&lt;div&gt;…"`), so injecting it raw
+renders literal tags. Decode with the toolkit's `decodeRichHtmlEntities` FIRST, then
+inject at the single site:
+
+- **React** — `richTextSanitizer(decodeRichHtmlEntities(value))` → raw-HTML injection
+  in the `RenderField` dispatcher inside `heuristicRenderer.tsx`. Delivery RichText is
+  TRUSTED, so the default `richTextSanitizer` is **pass-through**; apps add DOMPurify
+  via `setRichTextSanitizer` at entry. The default MUST NOT be escape-only: the value
+  is already decoded, so escaping undoes the decode (**never both decode AND escape**).
+  Per-type renderers MUST forward into `heuristicRenderer`, never inline their own
+  injection.
+- **Angular** — `decodeRichHtmlEntities(value)` → `[innerHTML]` in
+  `cms-content.component.ts`. Angular's `DomSanitizer` sanitizes the binding
+  automatically; do NOT `bypassSecurityTrustHtml`.
+
+Detection must catch the encoded form: match a tag-open (`<tag`/`</`/`<!`) OR `&lt;`
+(`RICH_TEXT_RE`), not `value.includes('<')`. A bare `<` in prose (`"Q4 < projected"`)
+must NOT match, or the browser's HTML parser silently drops everything after it.
+
+## Rule 5 — Type scalar fields as primitives, never `{ value }` wrappers
+
+Delivery returns SCALAR fields (Text, RichText, Date, Number, URL) as PLAIN
+primitives (`"body": "&lt;div&gt;…"`, `"title": "Berries"`), NOT `{ value: "…" }`.
+Only images arrive as objects (`CmsImageField`). A prior scaffold assumed a uniform
+`{ value: string }` and read `body.body.value`, always `undefined`, so RichText
+rendered as nothing.
+
+- **Generated `<Type>Body` uses primitives.** Text/RichText/URL → `string`;
+  Date/DateTime → `string`; Number → `number`; Boolean → `boolean`; Image →
+  `CmsImageField`. Never `{ value: T }`. Template: `assets/shared/cmsContentType.ts`.
+- **Read fields directly.** `body.body`, never `body.body.value`. The renderer
+  dispatches on the primitive's shape; per-type renderers delegate and MUST NOT unwrap
+  `.value`.
+- **Derive shapes from a real payload.** Confirm each field against an actual delivery
+  response: an inline sample in the prompt, a fetched `unauthenticatedUrl`, or the
+  schema. For a `contentKey` ref with no URL to fetch, an inline sample is the primary
+  source. Read field shapes from `contentBody`; the item `title` is at the envelope
+  ROOT, not a `contentBody` field. `references/schema-sync.md`; envelope contract in
+  `references/package-api.md`.

package/skills/experience-cms-content-render/references/detail-pages.md

@@ -0,0 +1,87 @@
+# Detail Pages
+
+The Detail Page branch of Render Target (SKILL.md step 4). Reached when the prompt
+asks for a route/page (e.g. *"create a detail page for X"*) OR when the user picks
+"detail page" in answer to the step-4 render-target question. Never created
+implicitly — either the prompt states it or the user chooses it.
+
+For a same-type GROUP, this branch runs ONCE PER ITEM (default group target): N
+pages, N routes, each targeting its own ref, with slugs deduped across the batch so
+same-title items don't collide. The renderer + `<type>.ts` are shared (generated
+once in step 2); only pages, routes, and refs multiply.
+
+Paths below are under the detected framework's dir — `src/cms/react/` or
+`src/cms/angular/`. Templates: React `assets/react/DetailPage.tsx`, Angular
+`assets/angular/DetailPage.component.ts`.
+
+## Prerequisites (else HALT)
+
+1. `<framework>/types/{{type}}.ts` exists (markers intact).
+2. The renderer exists — React `react/types/{{Type}}Renderer.tsx`, Angular
+   `angular/types/{{Type}}Renderer.component.ts`.
+3. `{{REF_CONST}}` registered in `src/cms/shared/externalRefs.ts`.
+4. Router file has a marker-blocked route region (below).
+
+## Inputs (confirm all in ONE prompt before writing)
+
+| Input | Default |
+|-------|---------|
+| `PageName` | `<TitlePascal>DetailPage` (React) / `<TitlePascal>Component` (Angular) |
+| `urlSlug` | `<title-kebab>` |
+| target `ref` | most-recent Embed or explicit pick |
+| router file | detected (show, allow override) |
+
+If the user overrides a value, re-show the final diff and confirm again.
+
+## Generation steps
+
+1. Read the renderer — absent → HALT "run Embed for `{{type}}` first".
+2. Read `shared/externalRefs.ts` — `{{REF_CONST}}` absent → HALT "run Embed first".
+3. Page file — React `src/pages/{{type}}/{{PageName}}.tsx` from
+   `assets/react/DetailPage.tsx`; Angular `src/pages/{{type}}/{{PageName}}.component.ts`
+   from `assets/angular/DetailPage.component.ts` (token sub). Not present → write;
+   present+differs → HALT; present+matches → no-op.
+4. Insert the route (below).
+5. Verify: report file path, route entry, slug. No typecheck/build.
+
+## Router marker block
+
+Pasted once by hand, exactly once per file:
+
+**React** — inside `<Routes>` (react-router v6) OR a `RouteObject[]` literal:
+
+```tsx
+{/* <experience-cms-content-render:detail-routes-begin> */}
+{/* <experience-cms-content-render:detail-routes-end> */}
+```
+
+**Angular** — inside the `Routes` array literal (e.g. `app.routes.ts`):
+
+```ts
+// <experience-cms-content-render:detail-routes-begin>
+// <experience-cms-content-render:detail-routes-end>
+```
+
+**Detection:** grep candidates for the begin/end pair — React (`App.tsx`,
+`routes.tsx`, `router.tsx`, `main.tsx`), Angular (`app.routes.ts`, `app.config.ts`,
+`app-routing.module.ts`). Exactly one → use it. Multiple → HALT (list them). Zero →
+HALT with the snippet to paste.
+
+## Route insertion
+
+Insert inside the block, above `:end`. Append-only, idempotent, collision-safe:
+
+- React JSX: `<Route path="{{urlSlug}}" element={<{{PageName}} />} />`
+- React data-router: `{ path: '{{urlSlug}}', element: <{{PageName}} /> },`
+- Angular: `{ path: '{{urlSlug}}', component: {{PageName}} },` (lazy:
+  `{ path: '{{urlSlug}}', loadComponent: () => import('./pages/{{type}}/{{PageName}}.component').then(m => m.{{PageName}}) },`)
+
+Ensure `{{PageName}}` is imported (path recomputed per project); skip if already
+imported. If the slug already routes to a DIFFERENT component → HALT (slug
+collision). If it routes to `{{PageName}}` already → no-op.
+
+## Non-goals
+
+Static slugs only (dynamic `:id`/route params → future WI). Generated page is a
+thin wrapper (one renderer, `layout="detail"`); customize in the renderer. No route
+guards — user hand-wraps outside the marker block.

package/skills/experience-cms-content-render/references/embed-recipes.md

@@ -0,0 +1,127 @@
+# Embed Recipes
+
+## Pasted delivery-URL detection (Identity, step 1)
+
+The input carries a CMS delivery URL when it matches an Experience CDN delivery URL
+`https://<host>.salesforce-experience.com/cms/delivery/<ver>/<channel>/contents/<id>`.
+Match with this case-insensitive regex; the whitespace-free host segment lets a URL
+embedded in surrounding prose still match:
+
+```text
+https:\/\/[^\s/]+\.salesforce-experience\.com\/cms\/delivery\/[^\s]*\/contents\/[^\s]+
+```
+
+On a match, that URL IS the `unauthenticatedUrl` → skip search, foreign ref. No match
+→ fall through to the contentKey / natural-language paths.
+
+---
+
+Placement patterns for the in-place branch of Render Target (SKILL.md step 4).
+Every recipe assumes the ref is registered and the renderer exists (earlier
+pipeline steps), and that a placement target was stated in the prompt or answered
+to the step-4 question.
+
+Base snippet — the per-type renderer takes a `ref`:
+
+**React** (`react/types/{{TypeRenderer}}.tsx`, selector-less component):
+
+```tsx
+import { {{Type}}Renderer } from '../cms/react/types/{{TypeRenderer}}';
+import { ref } from '../cms/shared/externalRefs';
+
+<{{Type}}Renderer ref={ref('{{REF_CONST}}')} />
+```
+
+**Angular** (`angular/types/{{Type}}Renderer.component.ts`, selector `cms-{{type}}`):
+import `{{Type}}RendererComponent` into the host component's `imports`, then:
+
+```html
+<cms-{{type}} [ref]="itemRef"></cms-{{type}}>   <!-- itemRef = ref('{{REF_CONST}}') on the host class -->
+```
+
+Idempotency (all recipes): if the same renderer for the same `{{REF_CONST}}`
+already exists inside the anchor element, skip.
+
+| Recipe | Prompt shape | Anchor | Extra prop |
+|--------|--------------|--------|------------|
+| Named component/page | "add X to `<Component>`" | JSX/template return: `cms:embed` placeholder comment, else append to top element's children | — |
+| List/grid item | "add X as a card in the list" | static sibling list → append; **dynamic `.map`/`@for` list → HALT** (add to data source instead) | `layout="card"` |
+| Sidebar | "put X in the sidebar" | first `<aside>`; none → HALT for a target | `layout="card"` |
+| Hero | "show X as the hero" | top-level element or first `<header>` | `layout="detail"` |
+| Custom layout | "use my `card-large` layout" | as named; layout must exist in `{{type}}Layouts` else HALT | `layout="card-large"` |
+| Fields whitelist | "only show title and image" | as named | React `fields={['title','bannerImage']}` / Angular `[fields]="['title','bannerImage']"` |
+| Slot override (React only) | "render the title as a link" | as named; **always HALTs to show diff first** (creates a component in parent scope) | `components={{ Title: … }}` |
+
+Angular has no `components` slot prop — for a custom title/image treatment, style
+via the class hooks (`references/styling-scopes.md`) or customize the renderer.
+
+## Ref-registration forms (Embed step 3)
+
+Append inside the `external-refs-begin` marker block of `src/cms/shared/externalRefs.ts`;
+emit the form matching the ref type and ensure the `satisfies` type is imported:
+
+```ts
+// Foreign ref (unauthenticatedUrl):
+EXT_FOOD_BERRIES: { name: 'EXT_FOOD_BERRIES', url: 'https://…/cms/delivery/…/contents/…?oid=…', cmsType: 'news' } satisfies CmsExternalRef<'news'>,
+// uiBundle-space ref (contentKey — remapped at runtime via content-metadata.json):
+EXT_LAUNCH_NEWS: { name: 'EXT_LAUNCH_NEWS', contentKey: 'M3ASD4KHASDB73', cmsType: 'news' } satisfies CmsRef<'news'>,
+// Foreign MEDIA ref (unauthenticatedUrl IS the asset — not fetched; alt/title on the ref):
+EXT_HERO_PHOTO: { name: 'EXT_HERO_PHOTO', url: 'https://…cdn….salesforce-experience.com/…/hero.jpg?oid=…', cmsType: 'image', altText: 'Team on launch day' } satisfies CmsExternalRef<'image'>,
+```
+
+`cmsType` MUST equal the fqn DeveloperName and match the `<K>` in `satisfies` — this
+discriminator is what makes a wrong-typed `ref` a compile error against the renderer;
+omit it and the guard silently disappears. Store the identity verbatim: a foreign
+`url` (never re-sign, strip `oid`, or bump version) or the `sourceContentKey` (the
+toolkit owns source→target remap).
+
+**Media on a foreign `url` ref carries `altText`/`title`.** The direct-URL media path
+does not fetch a body, so the accessible name lives on the ref: `altText` (image alt /
+audio-video aria-label) and `title` (document download-link label), sourced from the
+search hand-off or the *Media alt text* ask (`references/interaction-model.md`).
+`audio`/`video` need no `altText`. These fields are ignored on non-media refs and on
+`contentKey` media refs (which read alt/title from the fetched body).
+
+### Channel resolution (CmsRef only)
+
+A `CmsRef` MUST resolve a channel — the catalog is primary. Resolve in order, stop at
+the first hit:
+
+1. **Existing catalog** — read `public/content-metadata.json`; a non-empty `channelId`
+   → use it, do NOT overwrite.
+2. **Prompt / identity** — a `channelId` accompanied the `contentKey` → write it into
+   `public/content-metadata.json`, creating the file if absent:
+   ```jsonc
+   { "channelId": "0apSG0000000ExampleChannel", "contents": [] }
+   ```
+   (`public/` is Vite's web root, so the toolkit's default `${BASE_URL}content-metadata.json`
+   resolves to `<appRoot>/public/content-metadata.json`. Empty `contents: []` is safe —
+   per-entry remap fails open; the deploy pipeline fills the real pairs.)
+3. **Neither → ASK** the user for the channelId (`references/interaction-model.md` →
+   *Channel ID*), then write it per step 2.
+4. **Still unresolved → HALT**: *"'{title}' is a contentKey with no resolvable channel;
+   rendering will fail. Provide the channelId or add it to public/content-metadata.json."*
+   Never write a placeholder/fake channel.
+
+**Conflict:** a prompt-provided channel that DIFFERS from a non-empty channel already in
+the catalog → ASK which wins with an option-select (`references/interaction-model.md` →
+*Channel conflict*), never a silent overwrite. On **keep the catalog** → leave
+`content-metadata.json` unchanged (no write). On **use the prompt channel** → overwrite
+ONLY the `channelId` (preserve the existing `contents` array). Same/empty → use/write.
+Idempotent: present channel → skip; absent → create; present-but-empty → fill.
+
+`CMS_CHANNEL_ID_FALLBACK` in `externalRefs.ts` is a **cautioned, opt-in override** only
+(the skill no longer auto-fills it; it is baked into source and does not travel per-org).
+Precedence when the toolkit reads: explicit option > `CMS_CHANNEL_ID_FALLBACK` > catalog
+`channelId` > the toolkit throws. Foreign refs carry their channel in the URL — no gate.
+
+## Anchor detection failure
+
+No recipe applies (no top-level component, JSX/template return, list, or aside) →
+HALT and report the file's markup structure so the user names a concrete anchor.
+
+## Non-goals
+
+No Storybook, no test scaffolding, no wrapper components (`<Suspense>`,
+`<CmsBoundary>`) — the renderer handles loading/error internally (React
+`useCmsItem`, Angular `CmsItemService`).

package/skills/experience-cms-content-render/references/failure-modes.md

@@ -0,0 +1,96 @@
+# Failure Modes
+
+## Rich-text sanitizer plug (React only)
+
+The RichText mechanics (decode-then-inject, why the default is pass-through) live in
+Rule 4 / `references/heuristic-render-rules.md`. The one actionable extra: apps add
+DOMPurify for defense-in-depth by registering a sanitizer once at entry — a runtime
+plug, not a hard dep, so the choice is visible at the app boundary:
+
+```ts
+import DOMPurify from 'dompurify';
+import { setRichTextSanitizer } from './cms/react/heuristicRenderer';
+setRichTextSanitizer(DOMPurify.sanitize);
+```
+
+Angular has no such seam — `[innerHTML]` runs through `DomSanitizer` automatically.
+
+## Terminal stops (session ends — nothing scaffolded)
+
+Distinct from the recoverable HALTs below: these END the session. See
+`references/interaction-model.md` → *Terminal stops*.
+
+| Trigger | What the skill does |
+|---------|---------------------|
+| **Init declined** — user answers "No" to the *Run Init?* option question | State Init was declined → skill HALTS and the session ends. Nothing installed or written; end the turn. Do not fall through to Embed. |
+| **Zero search content** — experience-search-coordinate succeeds but returns zero content for the phrase | The item isn't authored in this uiBundle space yet. Stop and tell the user to generate the content there first (author + publish, e.g. via experience-cms-content-generate / experience-cms-content-type-generate), then re-run. Do not guess an identity or scaffold. |
+
+## HALT catalogue
+
+| Trigger | Fix |
+|---------|-----|
+| Missing/malformed marker in managed file | User restores the marker line. Skill never auto-heals. |
+| Ref name collision, different URL/key | User renames or removes the existing entry. |
+| Init drift (scaffold differs from template) | User accepts (regenerate) or keeps their edit. |
+| Foundation drift — some foundation files present, some missing | User restores the missing files or removes the partial set; the skill never Embeds onto a partial runtime. |
+| Ambiguous framework — both `react` and `@angular/core` are deps | User names which framework to target. |
+| Unknown framework — neither `react` nor `@angular/core` (or no `package.json`) | Not a supported React/Angular app; skill does not scaffold. |
+| Router marker ambiguous / missing | User removes stale markers, or pastes the marker block. |
+| Slug collision | User picks a different slug or removes the existing route. |
+| Render target unanswered (step 4) — "in place" chosen but no placement named, or no anchor found | User names a component/page/region to render into. Skill never guesses a placement. |
+| Detail-page prerequisite missing (renderer/ref) | User runs Embed for the type first. |
+| Detail-page file exists with different content | User deletes or renames. |
+| Content has neither `unauthenticatedUrl` nor `contentKey` | User pastes a public delivery URL or picks another item. (A `contentKey`-only item is supported — register a `CmsRef`.) |
+| Multi-item selection when Embed needs one | User re-runs and picks a single item. |
+| `CmsRef` with no resolvable channel — none in `public/content-metadata.json`, none in the prompt, and (bypass) no user to ask | User provides the channelId or adds it to `public/content-metadata.json`. The skill never invents or placeholders a channel; a `CmsRef` cannot render without one. |
+| channelId conflict — a prompt-provided channel differs from a non-empty `channelId` already in `public/content-metadata.json` | ASK which wins as an option-select (`references/interaction-model.md` → *Channel conflict*): keep the catalog channel (no write) or use the prompt channel (overwrite only `channelId`, preserve `contents`). The skill overwrites the catalog only on confirmation, never silently. |
+
+## Runtime failures (renderer-level)
+
+Surfaced via `useCmsItem`'s `error` state (React) / `CmsItemService.load`'s
+returned `error` (Angular), and the renderer's `role="alert"` branch. The toolkit
+raises typed errors — `CmsDeliveryError` / `CmsDeliveryNotFoundError` (public CDN)
+and `ConnectApiError` / `CmsNotFoundError` (authenticated Connect) — which the
+hook/service pass through unchanged.
+
+| Symptom | Cause | User action |
+|---------|-------|-------------|
+| HTTP 404 on a foreign ref | Unpublished, truncated URL, OR URL rewritten (doubled version, wrong host — Rule 1) | Verify the `unauthenticatedUrl`; the toolkit's `getCmsContentByUrl` fetches it AS-IS. |
+| HTTP 401 on a foreign ref | Foreign-ref URL not actually public | For public delivery it must be truly public; a non-public uiBundle item should be a `CmsRef` (`contentKey`) read via `getCmsContentByKey`, not a `CmsExternalRef`. |
+| `CmsNotFoundError` on a `CmsRef` | `contentKey` not published in this org, or the catalog remapped to a stale `targetContentKey` | Verify the item is published; check `content-metadata.json` maps the source key to a live target (or omit the entry to fall back to the baked-in key). |
+| `CmsNotFoundError` / Connect error on EVERY `CmsRef` | Channel could not be resolved — no `channelId` in `public/content-metadata.json`, empty `CMS_CHANNEL_ID_FALLBACK`, AND no explicit option | Add `channelId` to `public/content-metadata.json` (the primary, cross-org-safe seam); the cautioned `CMS_CHANNEL_ID_FALLBACK` in `externalRefs.ts` is an opt-in override only. Precedence: explicit option > fallback > catalog > the toolkit throws. |
+| "No content found." / empty render, either transport | Body typed wrong — the toolkit returns the already-UNWRAPPED `contentBody` (envelope `title` lifted in), NOT `{ items: [...] }` or the raw envelope | Type the read as `getCmsContentBy*<TBody>` where `TBody` is the `contentBody` shape. Never re-implement unwrap or read `items[0]`. Contract: `references/package-api.md`. |
+| Content renders but the TITLE is missing | `<Type>Body` read `contentBody.title`, but delivery returns `title` at the ENVELOPE ROOT | The toolkit lifts the root `title` into the returned body (when the body lacks one) so `pickTitle`/layouts see it. Do not emit `title` as a `<Type>Body` schema field. Contract: `references/package-api.md`. |
+| Image silently missing, url IS present in the payload | The field was used directly as `src` instead of going through the resolver | Never use an image field as a `src`. Pass it to `resolveCmsImageUrl(field)` (React `resolveImageSrc`; Angular's `resolveImageSrc` method) — it handles both the top-level-`url` (CMS `imageReference`) and `source.ref`-string (foreign `url`) variants, with no options. Shape: `CmsImageField`; contract: `references/package-api.md`. |
+| CMS image doesn't load | An image field was used directly as `src` instead of going through the resolver | Resolve via `resolveCmsImageUrl(field)` — it resolves a relative Connect-API url on its own and passes absolute urls through. Pass NO options; it is SYNC, so resolve inline (no async image component). |
+| Standalone media (audio/video/document) 404s **on a `contentKey` ref** | The body `sfdc_cms:media.url` was used directly as the element `src` instead of going through the resolver | Resolve via `resolveMediaUrl(sfdc_cms:media.url)` (Rule 2) — the toolkit resolves a relative Connect-API url itself. Pass NO options and never hand-prefix the url. Images use `resolveCmsImageUrl` instead. (This is the CONTENTKEY path only — a foreign `url` media ref uses `ref.url` directly with no fetch and no resolver; see the next row.) |
+| Standalone media on a foreign `url` ref renders blank / doesn't load | The renderer fetched the `unauthenticatedUrl` (or ran it through a resolver) instead of using it directly | A media `unauthenticatedUrl` is the ASSET itself — set `ref.url` straight onto the element `src`/`href`, NO `getCmsContentByUrl` and NO resolver (Rule 1/Rule 2). If the url genuinely 404s, verify it is the direct asset url (all query params intact) and the item is published. |
+| Media image on a foreign `url` ref has no alt text / a document link reads "Download" | `altText`/`title` weren't threaded onto the `CmsExternalRef` (direct-URL path has no body to read them from) | Capture `altText`/`title` at Ref Registration from the search hand-off, or ASK the user (`references/interaction-model.md` → *Media alt text*). `audio`/`video` need no alt. |
+| Public-CDN fetch fails in dev (either framework) | Something OTHER than CORS — the CMS delivery backend serves CORS headers, so a direct cross-origin fetch from `localhost` works with no proxy | No dev proxy is needed or scaffolded (the former proxy rule was removed). Check the `unauthenticatedUrl` is correct and reachable, and that the item is published; a genuine failure here is a 404/401 or a network error, not a CORS block. |
+| RichText renders as literal `<tags>` | Entity-encoded HTML injected without decoding; OR (React) the default `richTextSanitizer` was made escape-only and re-escaped already-decoded HTML | Decode via the toolkit's `decodeRichHtmlEntities` before injecting; React keeps the default sanitizer pass-through; never both decode AND escape the same string (Rule 4). |
+| Malformed body | Schema drift | Re-run Embed (Schema Sync detects drift). |
+| Empty render | Field names don't match priority lists | Pass a `fields={[…]}` (React) / `[fields]="[…]"` (Angular) whitelist. |
+| One card in a bulk list is missing / errors | A `getCmsContentByKeys` best-effort read returns a per-key `error` (e.g. `CmsNotFoundError`) for an unpublished/wrong-channel key | Expected — `getCmsContentByKeys` isolates per-key failures rather than throwing; render the `error` rows distinctly. `references/bulk-loading.md`. |
+| A `unauthenticatedUrl` card won't batch | Foreign CDN ref has no `contentKey` and often a different channel — structurally can't join a bulk read | Expected: foreign refs degrade to their individual `getCmsContentByUrl` fetch; only `CmsRef` keys batch (`references/bulk-loading.md`). |
+
+## React 19 StrictMode
+
+StrictMode intentionally mounts → cleans up → remounts. A hook that dedupes
+through a shared `inflight` map (`useCmsItem`) must survive this. The classic
+regression: cleanup aborts the SHARED in-flight request, the remount reuses the
+now-dead promise, and every double-mount fails. Fix (baked into
+`assets/react/useCmsItem.ts`, Rule 3): cleanup sets a `cancelled` flag and gates
+`setState` (never aborts the shared request); shared requests get no abort
+signal; `inflight` is self-cleaning via `.finally()` at creation. Treat "works
+once, fails on remount" as a blocking bug. The Angular `CmsItemService`
+(`assets/angular/cms-item.service.ts`) uses the same shared `cache`/`inflight`
+maps and a stale-ref guard in `ngOnChanges`.
+
+## Not failure modes
+
+- StrictMode double-mount → single network request (dedup + suppress-not-abort). By design.
+- Undefined per-embed `layout="…"` → falls through to `detail`/`list`; not a HALT.
+- Stale ref after source content removed → runtime 404; skill does not prune refs.
+- `content-metadata.json` missing / 404 / invalid JSON / entry absent → the toolkit
+  fails open to the baked-in `contentKey` (and no catalog channel). A missing
+  catalog is the normal local-dev state, not an error.

package/skills/experience-cms-content-render/references/heuristic-render-rules.md

@@ -0,0 +1,131 @@
+# Heuristic Render Rules
+
+Field-selection + value-shape rules for rendering an already-fetched, already-
+unwrapped `contentBody` when there's no typed renderer. The SAME rules run in both
+frameworks, in parallel implementations:
+
+- **React** — `heuristicRenderer.tsx`: field selection (which fields, in what
+  order) plus the internal `RenderField` dispatcher (how one value renders), in one
+  file.
+- **Angular** — one standalone `CmsContentComponent` (`cms-content`); `buildCells`
+  picks fields, `classify` maps each value to a `Cell` the `@switch` template
+  renders.
+
+Neither fetches — a container (`useCmsItem` / `CmsItemService`) passes `body`,
+`loading`, `error` in. Image-URL resolution is the toolkit's job
+(`resolveCmsImageUrl`, SYNCHRONOUS), so images render as a plain `<img>` with no
+async component in either framework.
+
+## Field selection
+
+**Whitelist mode** — caller passes `fields` (React `fields={[…]}`, Angular
+`[fields]="[…]"`): iterate in order, render one field each, nothing else.
+
+**Heuristic mode** — no whitelist, pick by priority list:
+
+```text
+IMAGE_PRIORITY   = ['bannerImage','featuredImage','heroImage','coverImage','thumbnail','image']
+EXCERPT_PRIORITY = ['excerpt','summary','description','subtitle']
+```
+
+1. Title — field named `title`, else first string key matching `/title/i`.
+2. Image — first `IMAGE_PRIORITY` field with an image shape.
+3. Excerpt — first `EXCERPT_PRIORITY` string.
+4. Overflow — `layout='detail'` renders remaining fields in order; `list` drops them.
+
+Layout: `list` → `<h2>` title, no overflow; `detail` → `<h1>` title, overflow
+shown. In React, slot overrides `components={{ Title, Image, RichText }}` win over
+defaults (per-embed prop > type slot > default); Angular has no slot props (style
+via class hooks + the container).
+
+## Value-shape decision table
+
+React `RenderField(name, value, layout, resolveRef, …slots)` / Angular
+`classify(name, value)` → `Cell`:
+
+| Value shape | Rendering |
+|-------------|-----------|
+| `null`/`undefined` | skip |
+| string matching `RICH_TEXT_RE` (`<tag`/`</`/`<!` OR `&lt;` OR `&#60;`/`&#x3c;`) | rich text — see below |
+| `^\d{4}-\d{2}-\d{2}` AND parseable | `<time>` via `Intl.DateTimeFormat({dateStyle:'medium'})`; unparseable → fall through |
+| `^https?://` | `<a target=_blank rel="noopener noreferrer">` |
+| string, name `/title/i` | heading (h1 detail / h2 list); React TitleSlot wins |
+| string (else) | `<p>` |
+| number | `<span>` via `Intl.NumberFormat` |
+| boolean | `<span class="badge">` Yes/No |
+| array (React) | recurse each element as `${name}[${i}]` |
+| object `.dateTime` | `<time>` dateStyle+timeStyle, optional `.timeZone` |
+| object image-shaped | `resolveCmsImageUrl` → `src`, `field.altText ?? ''` → `alt` → `<img loading=lazy>` (React ImageSlot wins) |
+| object `.ref.contentKey` | `resolveRef` → title, else contentKey |
+| else | skip |
+
+An object is "image-shaped" when it has a top-level string `url` OR a `source`
+with a string `type` (`isImageObject`).
+
+## RichText — decode, then inject through ONE path
+
+Delivery sends RichText entity-encoded (`&lt;div&gt;…`), so the match MUST include
+`&lt;` — a `<`-only test never fires and tags render as literal text. The literal
+side matches a tag-open (`<` followed by a letter, `/`, or `!`), NOT a bare `<`, so
+plain prose like `"Q4 < projected"` stays a `<p>` instead of being dropped by the
+browser's HTML parser. Decode with
+the toolkit's `decodeRichHtmlEntities` BEFORE injecting; never HTML-escape a
+decoded string (decode + escape cancel out). Injection is a single site per
+framework:
+
+- **React** — `richTextSanitizer(decodeRichHtmlEntities(value))` → `dangerouslySet
+  InnerHTML` in the `RenderField` dispatcher inside `heuristicRenderer.tsx`.
+  Delivery RichText is TRUSTED, so the default
+  sanitizer is pass-through; apps add DOMPurify via `setRichTextSanitizer` for
+  defense-in-depth (an escape-only default would undo the decode).
+- **Angular** — `decodeRichHtmlEntities(value)` → `[innerHTML]` in
+  `cms-content.component.ts`. Angular's `DomSanitizer` sanitizes the binding
+  automatically — do NOT `bypassSecurityTrustHtml`.
+
+Rule 4 in `SKILL.md`; symptoms in `references/failure-modes.md`.
+
+## Image URL resolution (toolkit-owned)
+
+Never use an image field directly as a `src` — pass it to the toolkit's
+`resolveCmsImageUrl(field)` (React helper `resolveImageSrc`; the Angular component's
+private `resolveImageSrc`). It handles both variants and the references-bag fallback,
+and resolves a relative CMS media url on its own; absolute/CDN urls pass through.
+Pass NO options object — the resolver needs no instance origin. The call is
+synchronous — resolve inline, render nothing when it returns `undefined`. Field shape
++ the two variants: `references/package-api.md`.
+
+For the `alt` attribute, read the field's authored `altText` (`resolveImageAlt`);
+`resolveCmsImageUrl` returns only the `src` string and drops the field, so read
+`altText` from the original field object, not the resolved URL. Fall back to `''` 
+
+## Media types — a dedicated renderer, NOT the heuristic path
+
+Standalone CMS media (`sfdc_cms__{image,audio,video,document}`) is a PREDEFINED type
+parallel to `news`, and a single asset rather than a field bag — so it does NOT run
+through this heuristic renderer at all. A media ref (`cmsType` ∈ `image`/`audio`/
+`video`/`document`) binds to the shared **`MediaRenderer`** (React
+`assets/react/MediaRenderer.tsx`; Angular `assets/angular/MediaRenderer.component.ts`),
+which switches on `cmsType` to one element. It **forks first by ref shape** for how the
+`src` is obtained (Rule 1/Rule 2):
+
+- **Foreign `url` ref** — `ref.url` IS the asset, so it goes directly onto the element
+  `src`/`href`: NO fetch, NO resolver. `alt`/document-label come off the ref
+  (`ref.altText` / `ref.title`), since there is no body to read them from.
+- **`contentKey` ref** — fetch the uniform `CmsMediaBody` (`sfdc_cms:media` + optional
+  `altText`) via `useCmsItem` / `CmsItemService`, then resolve the src by medium.
+
+| cmsType | Element | Src — `url` ref | Src — `contentKey` ref |
+|---|---|---|---|
+| `image` | `<img src alt loading="lazy">` | `ref.url` | `resolveCmsImageUrl(sfdc_cms:media)` |
+| `audio` | `<audio controls src>` (no `altText`) | `ref.url` | `resolveMediaUrl(url)` |
+| `video` | `<video controls src>` | `ref.url` | `resolveMediaUrl(url)` |
+| `document` | `<a href download>` — download link only, no inline preview | `ref.url` | `resolveMediaUrl(url)` |
+
+Dispatch is by `cmsType` (known at ref-registration time) and ref shape, **never by body
+shape** — so audio/video/document never enter this file's `isImageObject` branch and
+can't be mis-rendered as an `<img>`. On the `contentKey` path, src resolution splits by
+medium: image reuses the toolkit image resolver; audio/video/document pass the body `url`
+to the toolkit's `resolveMediaUrl`. Both take only the subject and no options — the
+toolkit resolves a relative Connect-API url itself (Rule 2,
+`references/codegen-guardrails.md`). `mimeType` inside `source` is available for finer
+intra-medium choices but is NOT the type discriminator.