Experience Cms Content Render

This skill directs how to render CMS content into a uiBundle app; it does NOT re-implement the delivery transport. The npm package @salesforce/ui-bundle-template-feature-cms-toolkit owns HTTP, envelope-unwrap, catalog key-remap, channel resolution, image-URL resolution, entity decoding and other utilities. The skill installs that package, then generates the thin framework-specific layer around it (typed refs, per-type renderers, fetch lifecycle, placement) for React and Angular uiBundle apps, inferring Init vs Embed from file state and never scaffolding Init inside an Embed prompt without telling the user.

API-only package — the skill writes the UI

The toolkit exports functions and types only: no components, no hooks. Import target and full signatures: references/package-api.md. The three reads (all take <TBody> + options?, all throw on failure):

• getCmsContentByUrl — public CDN, unauthenticated; the pasted unauthenticatedUrl fetched AS-IS.
• getCmsContentByKey — one item, authenticated Connect; the toolkit remaps source→target key and resolves the channel.
• getCmsContentByKeys — many, ONE authenticated round-trip, best-effort per-key (references/bulk-loading.md).

Plus sync helpers resolveCmsImageUrl, resolveMediaUrl, decodeRichHtmlEntities and the typed error classes. Every read returns the already-UNWRAPPED contentBody with the envelope title lifted in; skill code only types TBody and never handles the envelope, { items: [...] }, or a .value wrapper.

Bundled files (assets & references load with this skill)

This skill's assets/ templates and references/ docs load alongside SKILL.md; reference them by relative path (assets/shared/…, assets/<framework>/…, references/…) and treat their contents as available. Foundation runtime files are emitted VERBATIM; only cmsContentType.ts and the renderer templates carry {{…}} substitution. Never reconstruct a template from memory — the templates encode the StrictMode hook, the sanitizer seam, and the correct package call sites. Every detection below (framework, pasted-URL, Init/Embed/drift) READS the target app's files directly; there is no script to run.

Interaction model (ask with options)

This skill is interactive. At every decision the prompt leaves open (framework, Init, drift, content type, render target, candidate bundle) ASK with an option-select question of 2–4 labeled options, recommended first, and wait — never a bare free-text prompt. Use free-text only for open answers: a component/region name, a URL, a slug. Full wording, options, and headers: references/interaction-model.md; follow it for every ASK below. Two answers are terminal (end the session, scaffold nothing): declining Init, and a search that returns zero content (see HALT behaviour).

Bypass mode (non-interactive / automation). When the prompt explicitly asks to bypass the interaction model ("non-interactive", "don't ask", "proceed/yes to all", "auto-proceed"), ask NO option-select question: answer every would-be question with its recommended option and continue. This changes only the answer source, not pipeline logic, and does NOT override the terminal stops — a genuine zero-content result still stops, as does any true HALT with no safe default (unnamed in-place placement, unresolvable candidate bundle). Per-question recommended answers: references/interaction-model.md → Bypass mode.

Framework detection (do this FIRST)

Read <appRoot>/package.json (<appRoot> = the dir with package.json) and merge dependency names from dependencies, devDependencies, and peerDependencies; a framework may sit in any bucket:

• react — react present, @angular/core absent → React templates.
• angular — @angular/core present, react absent → Angular templates.
• ambiguous — BOTH present → HALT, ask which framework to target with options (references/interaction-model.md → Framework): React / Angular.
• unknown — neither present, or no readable package.json → HALT, not a supported React/Angular app; do not scaffold.

The framework selects the template family for every step below (assets/react/* vs assets/angular/*); assets/shared/* is framework-agnostic and used by both.

Modes

Init (one-time scaffold). On the first Embed, when the framework's foundation set (see Init vs Embed detection) is absent, run npm i @salesforce/ui-bundle-template-feature-cms-toolkit@latest --min-release-age=0 in the app root and write the shared runtime once (prompt the user first). This npm install is the ONLY way the toolkit is added; every import uses the @salesforce/… specifier. Init never overwrites: a fully-scaffolded tree is a no-op; a partial tree is drift and HALTS (see Init vs Embed detection).

Emit runtime files VERBATIM (rationale under Bundled files): Read each foundation template and Write it unchanged to src/cms/…, skipping any destination that already exists (never overwrite). Copy the assets/shared/ pair always, plus the detected framework's pair. Full tree, copy-set table, and fallback: references/init-scaffold.md.

Embed (per-prompt wiring). Given a prompt naming one CMS item (or a same-type group — see Groups), plus a placement when stated, run the pipeline below. When neither a placement nor a detail-page request is stated, step 4 asks which. Every step is idempotent.

Embed pipeline

Identity → Schema Sync → Ref Registration → Render Target → Verify

1. Identity — resolve one { unauthenticatedUrl | contentKey, fqn, title }

Two ref types (see assets/shared/cmsCore.types.ts): a foreign ref — item has an unauthenticatedUrl (public CDN) → register a CmsExternalRef (url), read via getCmsContentByUrl — except standalone media, whose url is the asset, used directly, not fetched (Rule 1/2; capture altText/title at step 3); a uiBundle-space ref — item has only a contentKey → register a CmsRef (contentKey), read via getCmsContentByKey (toolkit remaps the key via content-metadata.json). Resolve the identity from the input:

• URL pasted — the input matches an Experience CDN delivery URL (regex in references/embed-recipes.md; case-insensitive, matches a URL embedded in prose). That URL IS the unauthenticatedUrl; skip search → foreign ref. No match → fall through below.
• contentKey given directly (raw contentKey, optional channelId, no delivery URL): skip search → CmsRef. Store the contentKey verbatim; route any given channelId into public/content-metadata.json per the step-3 channel-resolution gate. A CmsRef with no resolvable channel (none in the catalog, prompt, or from the user) HALTs — never render without one.
• Natural-language mention: delegate to the experience-search-coordinate capability with the raw prompt (single-select unless the prompt names a group). It returns { unauthenticatedUrl, fqn, title, altText, contentKey } per item; unauthenticatedUrl is null for uiBundle-space items, so use contentKey. For media, carry altText/title onto the CmsExternalRef (step 3).

In all three, an unnamed content type → ask once (references/interaction-model.md → Content type). Per-item resolution and error handling:

• Zero content → STOP (terminal). Search finds nothing → end the turn per HALT behaviour → Terminal stops. Never fabricate a URL/contentKey, retry blindly, or place a placeholder.
• Search cancelled/errored/unavailable → HALT (recoverable). Ask the user to paste the item's unauthenticatedUrl OR its contentKey (+ channelId and type if known); resume only once they provide an identity. Never guess.
• Neither unauthenticatedUrl nor contentKey → HALT ("'{title}' exposes no delivery URL and no contentKey — cannot embed.").
• Otherwise: unauthenticatedUrl present → foreign ref; else contentKey → uiBundle-space ref; fqn empty → ask the content-type question.

Question wording for these stops: references/interaction-model.md; full catalogue: references/failure-modes.md.

Groups (N items, same type). More than one item, or a caller passing multiple keys/urls, is a group (one content type; ask the type question ONCE). Deltas: step 2 runs ONCE for the shared fqn (one <type>.ts + one renderer, never per item); step 3 loops N ref entries, suffixing the ref name with a short contentKey/url hash so same-title items don't collide; step 4 follows Group render target. Best-effort: skip and report an item that fails identity/schema, never HALT the whole batch on one. A group mixing contentKey and unauthenticatedUrl is fine — each ref dispatches by its own shape.

2. Schema Sync

OOTB sfdc_cms__news — use the predefined schema, do NOT fetch. The metadata schema fetch (ContentTypeBundle retrieve / MCP / SOQL) cannot resolve OOTB Salesforce content types, so for fqn === 'sfdc_cms__news' skip retrieval entirely and generate <Type>Body + <type>FieldTypes from the fixed three-field set — bannerImage (Image→CmsImageField/'image'), body (RichText→string/'richText'), excerpt (Text→string/'text') — verbatim from references/schema-sync.md; no sf project retrieve, MCP, or SOQL. Other OOTB types are not predefined; treat them as custom and fetch.

OOTB media — predefined too, parallel to news. For fqn ∈ sfdc_cms__{image,audio,video,document} also skip retrieval: the ref binds to the shared verbatim MediaRenderer (per framework) — no generated <type>.ts, no heuristicRenderer. The renderer forks by ref shape (foreign url → used directly; contentKey → fetch + resolve by medium; Rule 2). Emission: references/heuristic-render-rules.md → Media types, references/init-scaffold.md.

For a custom fqn, fetch the live schema (bare DeveloperName, strip sfdc_cms__/c__) via references/schema-sync.md, mapping each field to a lightningType, then to the lowerCamel CmsFieldType literal (Text→'text', RichText→'richText', …; translate the casing, never copy the PascalCase token).

• Body module + renderer both exist → re-fetch, diff against the current <Type>Body, regenerate ONLY the below-marker block of <framework>/types/<type>.ts (above-marker preserved verbatim); rewrite the renderer in full.
• Either missing → generate both from assets/shared/cmsContentType.ts and the framework renderer template into the framework's types/ dir; consumers import each renderer by direct path (../types/{{TypeRenderer}}), so there is no barrel to update.
• Any marker missing/malformed → HALT, ask the user to restore; never auto-heal. Retrieval fails → emit the below-marker block with a TODO listing fields to fill manually.

Details: references/schema-sync.md.

3. Ref Registration

Compute EXT_<TITLE_SNAKE> (upper-snake, ASCII) and append inside the external-refs-begin marker block of src/cms/shared/externalRefs.ts, emitting the form matching the ref type and importing its satisfies type if absent. Register BEFORE placement: ref('EXT_X') is typed against keyof typeof externalRefs, so an unregistered ref is a compile error by design. Always set cmsType to the fqn DeveloperName and match the <K> in satisfies — omit this discriminator and the wrong-type guard silently disappears. Store the identity verbatim (never re-sign a URL or hand-map a contentKey). Idempotency: same name + same identity → skip; same name + different identity → HALT (collision). Both ref-type forms + rationale: references/embed-recipes.md.

Media on a foreign url ref — capture altText/title (no fetched body; Rule 2): set them on the CmsExternalRef from the search hand-off; both absent for image/document → ASK once (Media alt text). audio/video/contentKey refs skip it.

Channel resolution (CmsRef only) — catalog-primary. A CmsRef MUST resolve a channel; resolve in order, stop at the first hit: (1) existing catalog — a non-empty channelId in public/content-metadata.json → use it, never overwrite; (2) prompt/identity — a channelId came with the contentKey → write public/content-metadata.json ({ "channelId": …, "contents": [] }), creating it if absent; (3) neither → ASK the user for the channelId, then write it; (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 channel that differs from a non-empty catalog channel → ASK which wins as an option-select (references/interaction-model.md → Channel conflict: keep catalog = no write; use prompt = overwrite only channelId); overwrite the catalog only on confirmation, never silently. Foreign refs carry their channel in the URL — no gate. CMS_CHANNEL_ID_FALLBACK remains only as a cautioned, opt-in override (see assets/shared/externalRefs.ts). Shape, location, precedence: references/embed-recipes.md.