@salesforce/afv-skills 1.46.0 → 1.48.0

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

@@ -0,0 +1,310 @@
+/**
+ * heuristicRenderer — schema-less body renderer (Init → src/cms/react/heuristicRenderer.tsx).
+ * Picks fields by priority (title/image/excerpt), dispatches each value by shape via
+ * RenderField, and holds the ONE RichText injection site (Rule 4). Angular parallel:
+ * cms-content.component.ts. Rules: references/heuristic-render-rules.md.
+ */
+import { type ComponentType, type ReactNode } from 'react';
+import {
+  resolveCmsImageUrl,
+  decodeRichHtmlEntities,
+} 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 crash the whole render. Return null on invalid so the
+// caller falls through to the next classifier instead of formatting.
+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);
+}
+
+let sanitizer: (html: string) => string = defaultPassThroughSanitizer;
+
+function defaultPassThroughSanitizer(html: string): string {
+  // Pass-through: Delivery RichText is trusted and already decoded to real HTML;
+  // escaping here would undo the decode (Rule 4). Apps add DOMPurify via
+  // setRichTextSanitizer for defense-in-depth.
+  return html;
+}
+
+// Swap in DOMPurify (or similar) at app entry: setRichTextSanitizer(DOMPurify.sanitize).
+export function setRichTextSanitizer(fn: (html: string) => string): void {
+  sanitizer = fn;
+}
+
+export function richTextSanitizer(html: string): string {
+  return sanitizer(html);
+}
+
+/** Delivery image field → loadable `src` via the toolkit (resolves the relative
+ *  Connect-API url; no options passed). Sync. */
+export function resolveImageSrc(field: unknown): string | undefined {
+  return resolveCmsImageUrl(field as CmsImageField | 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 '';
+}
+
+// RenderField picks a rendering from the value's SHAPE (table:
+// references/heuristic-render-rules.md) and holds the ONE RichText injection path
+// (Rule 4). Do NOT inject RichText anywhere else.
+interface RenderFieldProps {
+  name: string;
+  value: unknown;
+  layout: 'list' | 'detail';
+  /** Resolves a `references`-bag contentKey to its media field; undefined for foreign refs. */
+  resolveRef?: (contentKey: string) => CmsImageField | undefined;
+  TitleSlot?: ComponentType<{ value: string }>;
+  ImageSlot?: ComponentType<{ src: string; alt?: string }>;
+  RichTextSlot?: ComponentType<{ html: string }>;
+}
+
+function RenderField({
+  name,
+  value,
+  layout,
+  resolveRef,
+  TitleSlot,
+  ImageSlot,
+  RichTextSlot,
+}: RenderFieldProps): ReactNode {
+  if (value == null) return null;
+
+  if (typeof value === 'string') {
+    if (RICH_TEXT_RE.test(value)) {
+      // Decode entity-encoded HTML FIRST, THEN sanitize (Rule 4).
+      const html = richTextSanitizer(decodeRichHtmlEntities(value));
+      if (RichTextSlot) return <RichTextSlot html={html} />;
+      // Trusted, decoded HTML → default sanitizer is pass-through (Rule 4).
+      return <div dangerouslySetInnerHTML={{ __html: html }} />;
+    }
+    if (ISO_DATE_RE.test(value)) {
+      const label = formatCmsDate(value, { dateStyle: 'medium' });
+      // Valid date → <time>; invalid (matched the prefix but unparseable) → fall through.
+      if (label) return <time dateTime={value}>{label}</time>;
+    }
+    if (URL_RE.test(value)) {
+      return <a href={value} target="_blank" rel="noopener noreferrer" aria-label={`External link: ${value}`}>{value}</a>;
+    }
+    if (/title/i.test(name)) {
+      return TitleSlot
+        ? <TitleSlot value={value} />
+        : (layout === 'detail' ? <h1>{value}</h1> : <h2>{value}</h2>);
+    }
+    return <p>{value}</p>;
+  }
+
+  if (typeof value === 'number') {
+    return <span>{new Intl.NumberFormat().format(value)}</span>;
+  }
+
+  if (typeof value === 'boolean') {
+    return <span className="badge">{value ? 'Yes' : 'No'}</span>;
+  }
+
+  if (Array.isArray(value)) {
+    return (
+      <>
+        {value.map((v, i) => (
+          <RenderField
+            key={i}
+            name={`${name}[${i}]`}
+            value={v}
+            layout={layout}
+            resolveRef={resolveRef}
+            TitleSlot={TitleSlot}
+            ImageSlot={ImageSlot}
+            RichTextSlot={RichTextSlot}
+          />
+        ))}
+      </>
+    );
+  }
+
+  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 ? <time dateTime={obj.dateTime}>{label}</time> : null;
+    }
+
+    // image-shaped object — the toolkit resolves the src synchronously.
+    if (isImageObject(obj)) {
+      const src = resolveImageSrc(obj);
+      if (!src) return null;
+      const alt = resolveImageAlt(obj);
+      return ImageSlot
+        ? <ImageSlot src={src} alt={alt} />
+        : <img src={src} alt={alt} loading="lazy" />;
+    }
+
+    // contentReference shape
+    const refObj = (obj as { ref?: { contentKey?: string } }).ref;
+    if (refObj && typeof refObj.contentKey === 'string' && resolveRef) {
+      const resolved = resolveRef(refObj.contentKey);
+      if (!resolved) return null;
+      return <span>{(resolved as { title?: string }).title ?? refObj.contentKey}</span>;
+    }
+
+    return null;
+  }
+
+  return null;
+}
+
+export interface HeuristicRendererProps {
+  body: Record<string, unknown> | undefined;
+  loading: boolean;
+  error: Error | undefined;
+  layout?: 'list' | 'detail' | string;
+  /** Optional whitelist — bypasses priority lists and renders only these fields in order. */
+  fields?: ReadonlyArray<string>;
+  components?: {
+    Title?: ComponentType<{ value: string }>;
+    Image?: ComponentType<{ src: string; alt?: string }>;
+    RichText?: ComponentType<{ html: string }>;
+  };
+  className?: string;
+  resolveRef?: (contentKey: string) => CmsImageField | undefined;
+}
+
+export function heuristicRenderer({
+  body,
+  loading,
+  error,
+  layout = 'detail',
+  fields,
+  components,
+  className,
+  resolveRef,
+}: HeuristicRendererProps): ReactNode {
+  if (loading) return <div role="status">Loading…</div>;
+  if (error) return <div role="alert">{error.message}</div>;
+  if (!body) return null;
+
+  const normalizedLayout: 'list' | 'detail' = layout === 'list' ? 'list' : 'detail';
+  const TitleSlot = components?.Title;
+  const ImageSlot = components?.Image;
+  const RichTextSlot = components?.RichText;
+
+  // Whitelist mode.
+  if (fields && fields.length > 0) {
+    return (
+      <article className={className}>
+        {fields.map((name) => {
+          const value = body[name];
+          if (value == null) return null;
+          return (
+            <RenderField
+              key={name}
+              name={name}
+              value={value}
+              layout={normalizedLayout}
+              resolveRef={resolveRef}
+              TitleSlot={TitleSlot}
+              ImageSlot={ImageSlot}
+              RichTextSlot={RichTextSlot}
+            />
+          );
+        })}
+      </article>
+    );
+  }
+
+  // Heuristic mode.
+  const title = pickTitle(body);
+  const imageField = pickFirstField(body, IMAGE_PRIORITY, isImageObject);
+  const excerpt = pickFirstField(body, EXCERPT_PRIORITY, (v) => typeof v === 'string' && v.length > 0);
+
+  const consumed = new Set<string>();
+  if (title?.name) consumed.add(title.name);
+  if (imageField?.name) consumed.add(imageField.name);
+  if (excerpt?.name) consumed.add(excerpt.name);
+
+  return (
+    <article className={className}>
+      {title && (TitleSlot
+        ? <TitleSlot value={title.value} />
+        : (normalizedLayout === 'detail' ? <h1>{title.value}</h1> : <h2>{title.value}</h2>))}
+
+      {imageField && (() => {
+        const src = resolveImageSrc(imageField.value);
+        if (!src) return null;
+        const alt = resolveImageAlt(imageField.value);
+        return ImageSlot
+          ? <ImageSlot src={src} alt={alt} />
+          : <img src={src} alt={alt} loading="lazy" />;
+      })()}
+
+      {excerpt && <p>{excerpt.value as string}</p>}
+
+      {normalizedLayout === 'detail' && Object.entries(body)
+        .filter(([k]) => !consumed.has(k))
+        .map(([k, v]) => (
+          <RenderField
+            key={k}
+            name={k}
+            value={v}
+            layout={normalizedLayout}
+            resolveRef={resolveRef}
+            TitleSlot={TitleSlot}
+            ImageSlot={ImageSlot}
+            RichTextSlot={RichTextSlot}
+          />
+        ))}
+    </article>
+  );
+}
+
+function 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;
+}
+
+function 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;
+}

package/skills/experience-cms-content-render/assets/react/useCmsItem.ts

@@ -0,0 +1,129 @@
+/**
+ * useCmsItem — single-content React hook (Init → src/cms/react/useCmsItem.ts).
+ * Owns fetch state + a per-ref cache + inflight dedup (keyed by `ref.name`; never
+ * throws — errors → state). Dispatches on ref type: CmsExternalRef (`url`) →
+ * getCmsContentByUrl (CDN); CmsRef (`contentKey`) → getCmsContentByKey (Connect).
+ *
+ * StrictMode-safe (Rule 3): the request is SHARED, so cleanup only sets a local
+ * `cancelled` flag gating setState — it never aborts; shared requests get no
+ * AbortSignal; `inflight` self-cleans via `.finally(delete)`.
+ */
+import { useEffect, useState, useRef } from 'react';
+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';
+
+interface UseCmsItemState<TBody> {
+  body: TBody | undefined;
+  loading: boolean;
+  error: Error | undefined;
+}
+
+// Module-scoped: shared across every consumer of the hook in the app.
+const cache = new Map<string, unknown>();
+const inflight = new Map<string, Promise<unknown>>();
+
+/** Shared request for a ref — NO abort signal. `CMS_CHANNEL_ID_FALLBACK` is passed
+ *  as `options.channelId` only when set (empty → catalog supplies it). */
+function 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 });
+}
+
+export function useCmsItem<TBody = unknown>(
+  ref: AnyCmsRef,
+): UseCmsItemState<TBody> {
+  const [state, setState] = useState<UseCmsItemState<TBody>>(() => {
+    const cached = cache.get(ref.name) as TBody | undefined;
+    return {
+      body: cached,
+      loading: cached === undefined,
+      error: undefined,
+    };
+  });
+
+  // Track the ref name so object-identity churn doesn't re-fetch.
+  const nameRef = useRef(ref.name);
+  nameRef.current = ref.name;
+
+  useEffect(() => {
+    // Local guard only — cleanup suppresses stale setState, never the shared
+    // request (Rule 3).
+    let cancelled = false;
+    const name = ref.name;
+
+    const cached = cache.get(name) as TBody | undefined;
+    if (cached !== undefined) {
+      setState({ body: cached, loading: false, error: undefined });
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    setState((prev) => ({ ...prev, loading: true, error: undefined }));
+
+    // In-flight dedup: reuse a pending promise for this ref (shared, no signal).
+    let promise = inflight.get(name) as Promise<TBody> | undefined;
+    if (!promise) {
+      promise = createItemRequest<TBody>(ref);
+      inflight.set(name, promise);
+      // Self-cleaning: settled or failed, the entry is always removed so an
+      // unmounted consumer can't leave a dead promise to poison retries.
+      promise
+        .then((body) => {
+          cache.set(name, body);
+        })
+        .catch(() => {
+          /* surfaced per-consumer below; swallow to avoid unhandled rejection */
+        })
+        .finally(() => {
+          if (inflight.get(name) === promise) inflight.delete(name);
+        });
+    }
+
+    promise
+      .then((body) => {
+        if (cancelled) return;
+        setState({ body, loading: false, error: undefined });
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return;
+        // Pass the toolkit's typed errors through as-is; wrap anything else.
+        const error =
+          err instanceof CmsDeliveryNotFoundError ||
+          err instanceof CmsDeliveryError ||
+          err instanceof CmsNotFoundError ||
+          err instanceof ConnectApiError
+            ? err
+            : err instanceof Error
+              ? err
+              // Retain the original non-Error rejection as the cause for debugging.
+              : new Error('Unknown CMS fetch error', { cause: err });
+        setState({ body: undefined, loading: false, error });
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [ref.name]); // Ref-name is the identity — object churn is ignored.
+
+  return state;
+}
+
+/** Test-only — reset the module cache between runs. */
+export function __resetCmsCacheForTests(): void {
+  cache.clear();
+  inflight.clear();
+}

package/skills/experience-cms-content-render/assets/shared/cmsContentType.ts

@@ -0,0 +1,49 @@
+/**
+ * {{Type}} — per-type typed module (codegen-managed). ABOVE marker: user-editable
+ * (layouts, slots, className presets), preserved verbatim. BELOW marker: generated
+ * from the schema, rewritten on every Schema Sync. Missing/malformed markers → the
+ * skill HALTs (never auto-heals). Algorithm: references/schema-sync.md.
+ *
+ * Tokens: {{Type}} PascalCase · {{type}} camelCase · {{TYPE}} UPPER_SNAKE.
+ */
+import type { CmsFieldType, CmsImageField } from '../../shared/cmsCore.types';
+
+// <experience-cms-content-render:above-begin>
+// User-editable — layouts, slot overrides, className presets.
+// Preserved across regeneration.
+
+export const {{type}}Layouts = {
+  card: { fields: ['title', 'bannerImage', 'excerpt'] as const, className: 'cms-{{type}}-card' },
+  detail: { fields: undefined, className: 'cms-{{type}}-detail' },
+} as const;
+
+export type {{Type}}Layout = keyof typeof {{type}}Layouts;
+
+export const {{type}}Slots: {
+  Title?: unknown;
+  Image?: unknown;
+  RichText?: unknown;
+} = {};
+
+// <experience-cms-content-render:above-end>
+
+
+// <experience-cms-content-render:below-begin>
+// GENERATED — do not edit. Regenerated on schema sync.
+//
+// One field per schema entry. Scalars are PLAIN PRIMITIVES (Rule 5) — Text/RichText/
+// URL/Date/DateTime → string, Number → number, Boolean → boolean; only Image →
+// CmsImageField. NEVER `{ value: T }`.
+
+export interface {{Type}}Body {
+  // One typed property per schema field; the index keeps off-schema fields open.
+  [field: string]: string | number | boolean | CmsImageField | undefined;
+}
+
+export const {{type}}FieldTypes: Readonly<Record<string, CmsFieldType>> = {
+  // One entry per field, mapping lightningType → lowerCamel CmsFieldType literal
+  // (Text→'text', RichText→'richText', … — translate the casing, never copy the
+  // PascalCase token). E.g.: body: 'richText', excerpt: 'text', bannerImage: 'image'.
+};
+
+// <experience-cms-content-render:below-end>

package/skills/experience-cms-content-render/assets/shared/cmsCore.types.ts

@@ -0,0 +1,96 @@
+/**
+ * CMS identity + field-type primitives (FRAMEWORK-AGNOSTIC). Scaffolded once at
+ * `src/cms/shared/cmsCore.types.ts`; safe to import, not regenerated. Owns ONLY the
+ * app-level ref identity and the codegen field-type enum — delivery/runtime shapes
+ * (CmsImageField, CmsContentBody, errors, …) live in the toolkit; do NOT redeclare.
+ */
+
+// Re-exported so generated `<type>.ts` import the image shape from one local path
+// (relative to `<framework>/types/`) rather than the package specifier.
+export type { CmsImageField } from "@salesforce/ui-bundle-template-feature-cms-toolkit";
+
+/** Foreign-ref identity — content addressed by a public unauthenticatedUrl (CDN). */
+export interface CmsExternalRef<K extends string = string> {
+  /** Unique catalog name. Convention: EXT_<TITLE_SNAKE>. */
+  readonly name: string;
+  /** Fully-formed unauthenticatedUrl; immutable across deploys. */
+  readonly url: string;
+  /** Content-type discriminator (the fqn DeveloperName). REQUIRED and populated on
+   *  every entry — it binds the ref to its renderer, so a wrong-typed ref is a
+   *  compile error. Optional/absent would erase K and defeat that guard. */
+  readonly cmsType: K;
+  /** MEDIA-ONLY, direct-URL path. For standalone media (`image`/`audio`/`video`/
+   *  `document`) a foreign `url` is the ASSET itself, so MediaRenderer sets it as the
+   *  element `src`/`href` WITHOUT fetching — there is no body to read `altText`/`title`
+   *  from. The skill threads these off the search hand-off (or asks the user) at Ref
+   *  Registration so the accessible name survives. Ignored on non-media refs (news
+   *  reads its title from the fetched envelope). Both optional; `altText` absent → `''`
+   *  (decorative image, WCAG 1.1.1); `title` names the document download link. */
+  readonly altText?: string;
+  readonly title?: string;
+}
+
+/**
+ * uiBundle-space identity — a `contentKey` read via the authenticated Connect API.
+ * The baked-in value is the `sourceContentKey`; the toolkit remaps it to the org's
+ * `targetContentKey` via content-metadata.json (fail-open to the baked-in key).
+ */
+export interface CmsRef<K extends string = string> {
+  /** Unique catalog name. Convention: EXT_<TITLE_SNAKE>. */
+  readonly name: string;
+  /** sourceContentKey baked into app code; the catalog's remap fallback. */
+  readonly contentKey: string;
+  /** Content-type discriminator (the fqn DeveloperName). REQUIRED and populated on
+   *  every entry — it binds the ref to its renderer, so a wrong-typed ref is a
+   *  compile error. Optional/absent would erase K and defeat that guard. */
+  readonly cmsType: K;
+}
+
+/** Union of every fetchable ref — branch on `url` (foreign) vs `contentKey`. */
+export type AnyCmsRef<K extends string = string> = CmsExternalRef<K> | CmsRef<K>;
+
+/** Codified Lightning field types — feeds the below-marker fieldTypes map per type. */
+export type CmsFieldType =
+  | "text"
+  | "richText"
+  | "image"
+  | "date"
+  | "dateTime"
+  | "number"
+  | "boolean"
+  | "url"
+  | "reference"
+  | "unknown";
+
+/**
+ * Standalone-media discriminator — the fqn DeveloperName of a PREDEFINED CMS media
+ * item (`sfdc_cms__{image,audio,video,document}`), stored on the ref as `cmsType`.
+ * Media is a predefined type parallel to `news`: the ref binds to `MediaRenderer` at
+ * registration time, so dispatch is by `cmsType`, NEVER by body shape (SKILL.md §B1).
+ */
+export type CmsMediaType = "image" | "audio" | "video" | "document";
+
+/** The `sfdc_cms:media` field every media body carries (key is LITERALLY
+ *  "sfdc_cms:media", colon, across all four types). `url` is a loadable src; `source`
+ *  describes the underlying file (`mimeType` picks finer intra-medium choices). */
+export interface CmsMediaField {
+  readonly url?: string;
+  readonly source?: {
+    readonly mimeType?: string;
+    readonly ref?: string;
+    readonly type?: string;
+    readonly fileSize?: number;
+  };
+}
+
+/**
+ * Predefined body for standalone CMS media — UNIFORM across all four media types;
+ * they differ only by the envelope fqn (→ `cmsType`) and `source.mimeType`. `title`
+ * is envelope-level, lifted into the body by the toolkit (as news); `altText` is
+ * optional and absent on audio. The `<TBody>` for `getCmsContentByKey<CmsMediaBody>`.
+ */
+export interface CmsMediaBody {
+  readonly altText?: string;
+  readonly title?: string;
+  readonly "sfdc_cms:media": CmsMediaField;
+}

package/skills/experience-cms-content-render/assets/shared/externalRefs.ts

@@ -0,0 +1,55 @@
+/**
+ * Ref catalog for CMS content (FRAMEWORK-AGNOSTIC). Holds both ref types
+ * (CmsExternalRef by `url`, CmsRef by `contentKey`). Scaffolded once at
+ * src/cms/shared/externalRefs.ts; each embed appends one entry inside the marker block.
+ * Names are EXT_<TITLE_SNAKE>, unique — object-literal keys collide at compile time.
+ *
+ * ⚠ Do NOT edit the marker block by hand. Add entries via the skill.
+ */
+// Only `AnyCmsRef` is used in the empty template; Ref Registration adds
+// CmsExternalRef/CmsRef when it appends an entry (importing them eagerly trips
+// noUnusedLocals TS6196 on a fresh scaffold).
+import type { AnyCmsRef } from './cmsCore.types';
+
+// channelId OVERRIDE for CmsRef reads — CAUTION, opt-in only. Prefer the catalog
+// (public/content-metadata.json), which is primary and travels per-org. This constant
+// is baked into SOURCE, so it does NOT travel per-org and will point at the WRONG
+// channel after a cross-org deploy — set it only at your discretion for a local
+// override. The skill does NOT auto-fill it (leave ''); the catalog supplies the
+// channel. Precedence: explicit option > this override > catalog channelId > toolkit
+// throws. Passed as options.channelId only when non-empty.
+// <experience-cms-content-render:channel-fallback-begin>
+export const CMS_CHANNEL_ID_FALLBACK = '';
+// <experience-cms-content-render:channel-fallback-end>
+
+// <experience-cms-content-render:external-refs-begin>
+// Skill-managed. Each embed appends one entry here of the form:
+//
+//   Foreign ref (public unauthenticatedUrl):
+//   EXT_FOOD_BERRIES: {
+//     name: 'EXT_FOOD_BERRIES',
+//     url: 'https://orgfarm-XXX.cdn.example.salesforce-experience.com/cms/delivery/v64.0/0apSG.../contents/MCABC...?oid=00D...&language=en_US',
+//     cmsType: 'news',
+//   } satisfies CmsExternalRef<'news'>,
+//
+//   uiBundle-space ref (contentKey — remapped via content-metadata.json):
+//   EXT_LAUNCH_NEWS: {
+//     name: 'EXT_LAUNCH_NEWS',
+//     contentKey: 'M3ASD4KHASDB73',
+//     cmsType: 'news',
+//   } satisfies CmsRef<'news'>,
+//
+// `cmsType` MUST match the `<K>` in `satisfies` — it binds the ref to a per-type
+// renderer at compile time, so a wrong-typed ref is a compile error.
+export const externalRefs = {} as const satisfies Record<string, AnyCmsRef>;
+// <experience-cms-content-render:external-refs-end>
+
+/**
+ * Typed accessor — prefer over `externalRefs['EXT_X']`: the `cmsType` discriminator
+ * flows through, so a wrong-typed ref to a renderer fails at compile time.
+ */
+export function ref<Name extends keyof typeof externalRefs>(
+  name: Name,
+): (typeof externalRefs)[Name] {
+  return externalRefs[name];
+}