@salesforce/afv-skills 1.56.0 → 1.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/commerce-b2b-open-code-components-integrate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: commerce-b2b-open-code-components-integrate
 description: "Integrate Salesforce B2B Commerce open source components from GitHub into B2B Commerce stores. Use when users mention \"integrate open code components\", \"open source B2B commerce\", \"add open code components\", \"forcedotcom/b2b-commerce-open-source-components\", or want to add open source commerce components to their store. Copies all components and labels so they become available in Experience Builder."
-allowed-tools: Bash(git clone:*) Bash(cp:*) Read
+allowed-tools: Bash(git clone:*) Bash(cp:*) Bash(sf org list:*) Bash(sf config get:*) Bash(sf project retrieve start:*) Read
 metadata:
   version: "1.0"
   domains: ["Commerce", "Experience"]

package/skills/commerce-b2b-open-code-components-replace/SKILL.md

@@ -3,10 +3,10 @@ name: commerce-b2b-open-code-components-replace
 description: "Replace OOTB (out-of-the-box) B2B Commerce components with open source equivalents in site metadata content.json files, or look up the equivalent open code `site:` component for OOTB definitions. Use when users mention \"replace OOTB components\", \"replace commerce components with open code\", \"swap OOTB for open source\", \"replace commerce_builder:\", \"replace OOTB in site\", \"replace component in site metadata\", \"replace component definition\", \"find open code equivalent\", \"equivalent open code component\", \"OOTB to open code mapping\", \"what is the site component for\", components \"in this view\" or \"for a given view\", or a specific list of component names — and want to update or only discover mappings in their store metadata."
 allowed-tools: Bash(grep:*) Bash(ls:*) Read Write
 metadata:
-  relatedSkills:
-    - "commerce-b2b-open-code-components-integrate"
   version: "1.0"
   domains: ["Commerce", "Experience"]
+  relatedSkills:
+    - "commerce-b2b-open-code-components-integrate"
 ---
 
 # Replacing OOTB B2B Commerce Components with Open Code
@@ -94,10 +94,10 @@ Then present the replaceable components as a **multi-select list** so the user c
 ```text
 Which components would you like to replace?
 
-☐ commerce_builder:heading → site:productHeading
-☐ commerce_builder:cartBadge → site:cartBadge
-☐ commerce_builder:searchInput → site:searchInput
-☐ All of the above
+[ ] commerce_builder:heading → site:productHeading
+[ ] commerce_builder:cartBadge → site:cartBadge
+[ ] commerce_builder:searchInput → site:searchInput
+[ ] All of the above
 ```
 
 If user provided specific component name(s) in the original request, pre-filter to those and skip the selection prompt.
@@ -119,7 +119,7 @@ The affected files are already known from Step 1. For each file that contains se
 ### Step 3: Report
 
 ```text
-✅ Replacement Complete!
+Replacement Complete!
 
 Replaced X components across Y files:
 - commerce_builder:heading → site:productHeading (3 files)
@@ -152,9 +152,9 @@ Next Steps:
 **User:** "Replace OOTB components with open code versions"
 
 **Agent:** "Before replacing components, I need to verify that the open code components are set up in your store. Let me check..."
-- ✓ Open source repo cloned
-- ✓ Store metadata available for My_B2B_Store1
-- ✓ Open code components are integrated
+- [done] Open source repo cloned
+- [done] Store metadata available for My_B2B_Store1
+- [done] Open code components are integrated
 
 **Agent:** "I'm scanning your store's site metadata to find all OOTB commerce components and checking which have open code equivalents."
 
@@ -174,11 +174,11 @@ No mapping available (not in mapping table):
 ```text
 Which components would you like to replace?
 
-☐ commerce_builder:heading → site:productHeading
-☐ commerce_builder:cartBadge → site:cartBadge
-☐ commerce_builder:searchInput → site:searchInput
-☐ commerce_builder:cartSummary → site:cartSummary
-☐ All of the above
+[ ] commerce_builder:heading → site:productHeading
+[ ] commerce_builder:cartBadge → site:cartBadge
+[ ] commerce_builder:searchInput → site:searchInput
+[ ] commerce_builder:cartSummary → site:cartSummary
+[ ] All of the above
 ```
 
 **User:** _(selects heading and cartBadge)_
@@ -188,7 +188,7 @@ Which components would you like to replace?
 _(Files already known from scan — one Read/Write pass per affected file, all replacements batched)_
 
 ```text
-✅ Replacement Complete!
+Replacement Complete!
 
 Replaced 2 components across 5 files:
 - commerce_builder:heading → site:productHeading (3 files)

package/skills/dx-devops-project-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dx-devops-project-manage
-description: "Use this skill to list, view, or manage DevOps Center projects in a Salesforce org — show all projects, create a new project, or update an existing project's name, description, or active status. Invoke it to run sf devops project list whenever the user wants to show, see, view, display, or list available projects, check which or how many DevOps Center projects exist, or look up a project ID — even a plain listing request should use this skill rather than a raw tool or a direct answer. Also invoke to create a project, set up a new deployment pipeline foundation, initialize DevOps Center for a new feature, update project settings like name and description, or activate/deactivate (archive) a project. Consolidates sf devops project list/create/update operations. DO NOT TRIGGER for work item, pipeline, promotion, or conflict operations — those are separate skills."
+description: "Use to list, view, or manage DevOps Center projects in a Salesforce org — show all projects, create a project, or update an existing project's name, description, or active status. Invoke to run sf devops project list on any listing request, or to create a project, set up a new pipeline foundation, initialize DevOps Center for a feature, update project settings, or activate/deactivate (archive) a project. Consolidates sf devops project list/create/update. DO NOT TRIGGER for work item, pipeline, promotion, or conflict operations — those are separate skills."
 metadata:
   version: "1.0"
   domains: ["Developer Experience"]

package/skills/experience-cms-content-generate/SKILL.md

@@ -6,8 +6,8 @@ metadata:
   domains: ["Experience"]
   minApiVersion: "64.0"
   relatedSkills:
-    - "experience-cms-content-type-generate"
     - "experience-cms-content-render"
+    - "experience-cms-content-type-generate"
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"

package/skills/experience-cms-content-render/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: experience-cms-content-render
-description: "Renders, embeds, or displays existing Salesforce CMS content in a React or Angular uiBundle app: installs the CMS toolkit package, registers a typed reference, generates a framework-matched renderer from the live schema, and wires the render path (delivery API, contentKey, RichText, image resolution). Use it — and prefer it over general UI-bundle skills like experience-ui-bundle-frontend-generate, which own only the page/layout shell — for the CMS-rendering part of a prompt, even when editing files under src/. Triggers on 'render the CMS news article on the home page', 'embed the CMS blog post', 'display the featured product in the hero', 'show the blog post on a detail page', 'render the CMS video on the home page', 'show the CMS image in the hero'; if a prompt mixes page/layout work with CMS rendering, activate for the CMS part. Do not trigger when only searching for a CMS item, or when defining a new CMS content type/schema (use experience-cms-content-type-generate)."
+description: "Renders, embeds, or displays existing Salesforce CMS content in a React or Angular uiBundle app: installs the CMS toolkit, registers a typed reference, generates a framework-matched renderer from the live schema, and wires the render path (delivery API, contentKey, RichText, image resolution). Prefer over general UI-bundle skills like experience-ui-bundle-frontend-generate (page/layout shell only) for the CMS-rendering part, even under src/. Triggers on prompts like 'render the CMS article on the home page', 'embed this CMS blog post here', 'show the CMS video in the hero', 'display the CMS image in the banner', or 'add this CMS content block to the detail page'; for mixed prompts, activate for the CMS part only. Do not trigger for searching a CMS item or defining a new CMS content type/schema (use experience-cms-content-type-generate)."
 metadata:
   version: "2.1"
   domains: ["Experience"]
@@ -168,6 +168,6 @@ Dynamic feed discovery ("latest 10 news"); cross-ref audit tooling; media/image-
 
 ## Files & references
 
-**Templates** — `assets/shared/`: `cmsCore.types.ts`, `externalRefs.ts`, `cmsContentType.ts` (foundation + per-type body). `assets/react/`: `useCmsItem.ts`, `heuristicRenderer.tsx` (renderer + `RenderField` dispatcher), `TypeRenderer.tsx`, `TypeList.tsx`, `DetailPage.tsx`, `MediaRenderer.tsx`. `assets/angular/`: `cms-item.service.ts`, `cms-content.component.ts`, `TypeRenderer.component.ts`, `TypeList.component.ts`, `DetailPage.component.ts`, `MediaRenderer.component.ts`.
+**Templates** — `assets/shared/`: `cmsCore.types.ts`, `externalRefs.ts`, `cmsContentType.ts` (foundation + per-type body), `mediaLabels.ts`. `assets/react/`: `useCmsItem.ts`, `heuristicRenderer.tsx` (renderer + `RenderField` dispatcher), `TypeRenderer.tsx`, `TypeList.tsx`, `DetailPage.tsx`, `MediaRenderer.tsx`. `assets/angular/`: `cms-item.service.ts`, `cms-content.component.ts`, `TypeRenderer.component.ts`, `TypeList.component.ts`, `DetailPage.component.ts`, `MediaRenderer.component.ts`.
 
-**Docs** (`references/`): `package-api.md` (toolkit API + response contract — ground truth), `interaction-model.md` (question wording + terminal stops), `init-scaffold.md` (runtime tree, copy set, foundation sets), `schema-sync.md` (retrieval + regen), `verify.md` (fix policy + report), `codegen-guardrails.md` (full Rule 1–5), `embed-recipes.md` (URL regex + placement), `heuristic-render-rules.md`, `detail-pages.md`, `styling-scopes.md`, `bulk-loading.md`, `failure-modes.md`.
+**Docs** (`references/`): `package-api.md` (toolkit API + contract — ground truth), `interaction-model.md` (wording + terminal stops), `init-scaffold.md` (runtime tree, copy set, foundation sets), `schema-sync.md` (retrieval + regen), `verify.md` (fix policy + report), `codegen-guardrails.md` (full Rule 1–5), `embed-recipes.md` (URL regex + placement), `heuristic-render-rules.md`, `detail-pages.md`, `styling-scopes.md`, `bulk-loading.md`, `failure-modes.md`.

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

@@ -30,6 +30,7 @@ import {
   type CmsMediaBody,
   type CmsMediaType,
 } from '../shared/cmsCore.types';
+import { deriveDownloadLabel, effectiveAudioLabel } from '../shared/mediaLabels';
 
 @Component({
   selector: 'cms-media',
@@ -48,10 +49,21 @@ import {
           @if (src) { <img [class]="className" [src]="src" [alt]="alt" loading="lazy" /> }
         }
         @case ('audio') {
-          @if (src) { <audio [class]="className" controls [src]="src" [attr.aria-label]="alt || null"></audio> }
+          <!-- [attr.aria-label]="alt || null" would REMOVE the attribute when alt is
+               empty (Angular attribute-binding semantics) — audioLabel always has a
+               value, so the control never loses its accessible name. -->
+          @if (src) { <audio [class]="className" controls [src]="src" [attr.aria-label]="audioLabel"></audio> }
         }
         @case ('video') {
-          @if (src) { <video [class]="className" controls [src]="src" [attr.aria-label]="alt || null"></video> }
+          <!-- Captions render only when the ref supplies `captionsSrc` (SKILL.md §B4)
+               — there is no fetched-body field to derive real caption text from. -->
+          @if (src) {
+            <video [class]="className" controls [src]="src" [attr.aria-label]="alt || null">
+              @if (captionsSrc) {
+                <track kind="captions" [src]="captionsSrc" [label]="captionsLabel" default />
+              }
+            </video>
+          }
         }
         @case ('document') {
           <!-- Download link only — no inline preview (SKILL.md §B3). Named with the
@@ -75,13 +87,25 @@ export class MediaRendererComponent implements OnChanges {
   /** Resolved src + alt for the template (recomputed after each load). */
   src: string | undefined;
   alt = '';
-  /** Accessible name for the document download link (altText → title → "Download"). */
-  docLabel = 'Download';
+  /** Accessible name for the document download link (altText → title → derived
+   *  filename → "Download file"; see `deriveDownloadLabel`). */
+  docLabel = 'Download file';
+  /** Caller-supplied captions-track URL/label for `<video>` (foreign ref only —
+   *  see `CmsExternalRef.captionsSrc` in cmsCore.types.ts). Absent on the
+   *  contentKey path, since the fetched media body carries no captions field. */
+  captionsSrc: string | undefined;
+  captionsLabel = 'Captions';
 
   private loadedRefName?: string;
 
   constructor(private readonly cms: CmsItemService) {}
 
+  /** Accessible name for `<audio>` when `altText` is empty — never falls back to
+   *  `null`/removed, unlike `[attr.aria-label]="alt || null"`. */
+  get audioLabel(): string {
+    return effectiveAudioLabel(this.alt, this.src);
+  }
+
   ngOnChanges(): void {
     const ref = this.ref;
     // Only (re)load when the ref identity changes (mirrors TypeRendererComponent).
@@ -92,14 +116,18 @@ export class MediaRendererComponent implements OnChanges {
     this.error = undefined;
     this.src = undefined;
     this.alt = '';
-    this.docLabel = 'Download';
+    this.docLabel = 'Download file';
+    this.captionsSrc = undefined;
+    this.captionsLabel = 'Captions';
 
     // Foreign media ref: the unauthenticatedUrl is the asset src directly — no load
     // (Rule 1). alt/title ride on the ref (search hand-off or Ref Registration ask).
     if ('url' in ref && typeof ref.url === 'string') {
       this.src = ref.url;
       this.alt = ref.altText ?? '';
-      this.docLabel = ref.altText || ref.title || 'Download';
+      this.docLabel = deriveDownloadLabel(ref.url, ref.altText, ref.title);
+      this.captionsSrc = ref.captionsSrc;
+      this.captionsLabel = ref.captionsLabel || 'Captions';
       this.loading = false;
       return;
     }
@@ -123,7 +151,7 @@ export class MediaRendererComponent implements OnChanges {
   private resolveSrc(cmsType: CmsMediaType, body: CmsMediaBody): void {
     const media = body['sfdc_cms:media'];
     this.alt = body.altText ?? '';
-    this.docLabel = body.altText || body.title || 'Download';
+    this.docLabel = deriveDownloadLabel(media?.url, body.altText, body.title);
     if (cmsType === 'image') {
       this.src = resolveCmsImageUrl(media);
       return;

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

@@ -18,6 +18,15 @@ import {
 import type { AnyCmsRef, CmsRef } from '../shared/cmsCore.types';
 import { CMS_CHANNEL_ID_FALLBACK } from '../shared/externalRefs';
 
+/** Runtime guard before the cache's `as TBody` cast: a CMS body is always an
+ *  object/array, so this screens out a stale primitive from a `ref.name` reused
+ *  under a different, incompatible `TBody` — it cannot verify the object's shape
+ *  actually matches `TBody` (no schema is available here), so callers must still
+ *  keep `ref.name` unique per content shape. */
+function isCacheableBody(value: unknown): boolean {
+  return value !== null && typeof value === 'object';
+}
+
 /** Resolved state for one ref read — the component maps this onto signals. */
 export interface CmsItemResult<TBody> {
   body: TBody | undefined;
@@ -38,9 +47,9 @@ export class CmsItemService {
   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 };
+    const rawCached = this.cache.get(name);
+    if (isCacheableBody(rawCached)) {
+      return { body: rawCached as TBody, error: undefined };
     }
 
     let promise = this.inflight.get(name) as Promise<TBody> | undefined;
@@ -89,7 +98,7 @@ export class CmsItemService {
     ) {
       return err;
     }
-    return err instanceof Error ? err : new Error('Unknown CMS fetch error');
+    return err instanceof Error ? err : new Error('Unknown CMS fetch error', { cause: err });
   }
 
   /** Test-only escape hatch — reset the cache between test runs. */

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

@@ -27,6 +27,7 @@ import {
   type CmsMediaBody,
   type CmsMediaType,
 } from '../shared/cmsCore.types';
+import { deriveDownloadLabel, effectiveAudioLabel } from '../shared/mediaLabels';
 
 export interface MediaRendererProps {
   /** A media ref — `cmsType` selects the element; a non-media ref is a compile error. */
@@ -43,16 +44,30 @@ function mediaElement(
   src: string,
   alt: string,
   docLabel: string,
+  captionsSrc: string | undefined,
+  captionsLabel: string | undefined,
   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} />;
+      // `aria-label={alt || undefined}` would drop the attribute entirely when alt
+      // is empty (same JSX-prop-omission semantics as Angular's `|| null` binding) —
+      // effectiveAudioLabel always returns a value, so the control never loses its
+      // accessible name.
+      return <audio className={className} controls src={src} aria-label={effectiveAudioLabel(alt, src)} />;
     case 'video':
-      return <video className={className} controls src={src} aria-label={alt || undefined} />;
+      // Captions require a caller-supplied `captionsSrc` (SKILL.md §B4) — the CMS
+      // media body/ref carries no captions-track field, so there is no data to
+      // fabricate a `<track>` from when the caller hasn't provided one.
+      return (
+        <video className={className} controls src={src} aria-label={alt || undefined}>
+          {captionsSrc && (
+            <track kind="captions" src={captionsSrc} label={captionsLabel || 'Captions'} default />
+          )}
+        </video>
+      );
     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
@@ -72,11 +87,13 @@ function DirectMedia(props: {
   url: string;
   alt: string;
   title?: string;
+  captionsSrc?: string;
+  captionsLabel?: string;
   className?: string;
 }): ReactNode {
-  const { cmsType, url, alt, title, className } = props;
-  const docLabel = alt || title || 'Download';
-  return mediaElement(cmsType, url, alt, docLabel, className);
+  const { cmsType, url, alt, title, captionsSrc, captionsLabel, className } = props;
+  const docLabel = deriveDownloadLabel(url, alt, title);
+  return mediaElement(cmsType, url, alt, docLabel, captionsSrc, captionsLabel, className);
 }
 
 /**
@@ -93,7 +110,7 @@ function FetchedMedia(props: { ref: AnyCmsRef<CmsMediaType>; className?: string
 
   const media = body['sfdc_cms:media'];
   const alt = body.altText ?? '';
-  const docLabel = body.altText || body.title || 'Download';
+  const docLabel = deriveDownloadLabel(media?.url, body.altText, body.title);
 
   // Src resolution SPLITS by medium (Rule 2): image → resolveCmsImageUrl;
   // audio/video/document → resolveMediaUrl. Both toolkit helpers resolve the
@@ -102,7 +119,10 @@ function FetchedMedia(props: { ref: AnyCmsRef<CmsMediaType>; className?: string
     ref.cmsType === 'image' ? resolveCmsImageUrl(media) : media?.url ? resolveMediaUrl(media.url) : undefined;
   if (!src) return null;
 
-  return mediaElement(ref.cmsType, src, alt, docLabel, className);
+  // No fetched-body field carries a captions-track URL today (SKILL.md §B4), so the
+  // contentKey path never has real caption data to pass — only a foreign ref with a
+  // caller-supplied `captionsSrc` (see DirectMedia) can render a `<track>`.
+  return mediaElement(ref.cmsType, src, alt, docLabel, undefined, undefined, className);
 }
 
 export function MediaRenderer(props: MediaRendererProps): ReactNode {
@@ -117,6 +137,8 @@ export function MediaRenderer(props: MediaRendererProps): ReactNode {
         url={ref.url}
         alt={ref.altText ?? ''}
         title={ref.title}
+        captionsSrc={ref.captionsSrc}
+        captionsLabel={ref.captionsLabel}
         className={className}
       />
     );

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

@@ -30,6 +30,15 @@ interface UseCmsItemState<TBody> {
 const cache = new Map<string, unknown>();
 const inflight = new Map<string, Promise<unknown>>();
 
+/** Runtime guard before the cache's `as TBody` cast: a CMS body is always an
+ *  object/array, so this screens out a stale primitive from a `ref.name` reused
+ *  under a different, incompatible `TBody` — it cannot verify the object's shape
+ *  actually matches `TBody` (no schema is available here), so callers must still
+ *  keep `ref.name` unique per content shape. */
+function isCacheableBody(value: unknown): boolean {
+  return value !== null && typeof value === 'object';
+}
+
 /** 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> {
@@ -46,7 +55,8 @@ export function useCmsItem<TBody = unknown>(
   ref: AnyCmsRef,
 ): UseCmsItemState<TBody> {
   const [state, setState] = useState<UseCmsItemState<TBody>>(() => {
-    const cached = cache.get(ref.name) as TBody | undefined;
+    const rawCached = cache.get(ref.name);
+    const cached = isCacheableBody(rawCached) ? (rawCached as TBody) : undefined;
     return {
       body: cached,
       loading: cached === undefined,
@@ -64,9 +74,9 @@ export function useCmsItem<TBody = unknown>(
     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 });
+    const rawCached = cache.get(name);
+    if (isCacheableBody(rawCached)) {
+      setState({ body: rawCached as TBody, loading: false, error: undefined });
       return () => {
         cancelled = true;
       };

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

@@ -25,9 +25,19 @@ export interface CmsExternalRef<K extends string = string> {
    *  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. */
+   *  (decorative image, WCAG 1.1.1); `title` names the document download link.
+   *
+   *  `captionsSrc` is MEDIA-ONLY (video), also foreign-ref only: a caller who has a
+   *  captions/subtitles track (e.g. a VTT file) for this video supplies its URL here
+   *  so MediaRenderer can render an accessible `<track kind="captions">`. There is no
+   *  fetched-body equivalent for the uiBundle-space (`contentKey`) path today — the
+   *  predefined media body carries no captions field — so captions render only when
+   *  a caller populates this on a foreign ref. `captionsLabel` names the track
+   *  (defaults to "Captions" when omitted). */
   readonly altText?: string;
   readonly title?: string;
+  readonly captionsSrc?: string;
+  readonly captionsLabel?: string;
 }
 
 /**

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

@@ -4,7 +4,7 @@
  * 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.
+ * Warning: 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

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

@@ -0,0 +1,62 @@
+/**
+ * Accessible-name derivation for MediaRenderer (FRAMEWORK-AGNOSTIC). Shared by the
+ * React and Angular renderers so the document-download label and the audio
+ * fallback label are computed identically regardless of framework.
+ *
+ * The CMS media body/ref (`CmsMediaField`/`CmsExternalRef`) carries no filename
+ * field and no captions-track field — only `url`. These helpers derive a label
+ * from real, already-present data (the URL itself) rather than fabricating text
+ * that isn't there.
+ */
+
+/** Last path segment of `url`, URL-decoded, kept only when it looks like a filename
+ *  (has an extension). Returns `undefined` when `url` is absent or unparsable, or
+ *  when the last segment has no extension to trust as a filename. */
+function deriveFilenameFromUrl(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  let pathname: string;
+  try {
+    pathname = url.includes('://') ? new URL(url).pathname : url.split(/[?#]/)[0];
+  } catch {
+    return undefined;
+  }
+  const lastSegment = pathname.split('/').filter(Boolean).pop();
+  if (!lastSegment) return undefined;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(lastSegment);
+  } catch {
+    decoded = lastSegment;
+  }
+  return /\.[a-zA-Z0-9]+$/.test(decoded) ? decoded : undefined;
+}
+
+/**
+ * Accessible name for the document download link (WCAG 2.4.4) — identifies WHAT
+ * downloads instead of a bare, ambiguous "Download". Prefers `altText`/`title`
+ * when present; otherwise derives the real filename off the URL; otherwise falls
+ * back to the still-more-specific-than-bare-"Download" literal `'Download file'`.
+ */
+export function deriveDownloadLabel(
+  url: string | undefined,
+  altText?: string,
+  title?: string,
+): string {
+  if (altText) return altText;
+  if (title) return title;
+  const filename = deriveFilenameFromUrl(url);
+  return filename ? `Download ${filename}` : 'Download file';
+}
+
+/**
+ * Accessible name for an `<audio>` element when `altText` is absent. Angular's
+ * `[attr.aria-label]="alt || null"` REMOVES the attribute when `alt` is falsy
+ * (unlike a JSX `undefined` prop, which is the same removal but explicitly
+ * intended there); this default keeps the attribute present so the control
+ * always has an accessible name.
+ */
+export function effectiveAudioLabel(altText: string | undefined, url?: string): string {
+  if (altText) return altText;
+  const filename = deriveFilenameFromUrl(url);
+  return filename ? `Audio: ${filename}` : 'Audio';
+}

package/skills/experience-cms-content-render/references/init-scaffold.md

@@ -78,21 +78,28 @@ renderer (skip if it already exists — never overwrite):
 |-------------------------|------------------------------|
 | `assets/react/MediaRenderer.tsx` *(react)* | `src/cms/react/MediaRenderer.tsx` |
 | `assets/angular/MediaRenderer.component.ts` *(angular)* | `src/cms/angular/MediaRenderer.component.ts` |
+| `assets/shared/mediaLabels.ts` | `src/cms/shared/mediaLabels.ts` |
+
+Both `MediaRenderer.tsx` and `MediaRenderer.component.ts` import `deriveDownloadLabel`/
+`effectiveAudioLabel` from `../shared/mediaLabels`, so `mediaLabels.ts` MUST be copied
+in the same pass as the renderer — copying the renderer without it leaves an
+unresolved import and breaks the app's build. Skip if it already exists, exactly like
+the renderer files.
 
 The media types (`CmsMediaBody`, `CmsMediaField`, `CmsMediaType`) ship inside the
 always-written `shared/cmsCore.types.ts`, so a media embed onto an existing runtime
-needs only the one renderer file plus the ref entry — provided the runtime's
+needs only the renderer, `mediaLabels.ts`, and the ref entry — provided the runtime's
 `cmsCore.types.ts` carries the media exports (a pre-media scaffold that lacks them is
 Init drift on that file; HALT, don't silently patch). On the `contentKey` path URL
 resolution is entirely toolkit-owned (`resolveCmsImageUrl` / `resolveMediaUrl`); no
 local prefix helper ships. On the foreign `url` path the renderer uses `ref.url`
 directly — no resolver, no fetch (Rule 1/Rule 2).
 
-**The media renderer is NOT in the foundation sets below.** Init/Embed detection is
-unchanged: a runtime scaffolded before media existed is still a complete `embed`
-runtime, and the media renderer is written lazily on the first media embed exactly
-like a per-type `<type>.ts`. Do not add `MediaRenderer.*` to the detection sets, or
-every pre-media app would mis-classify as drift.
+**The media renderer and `mediaLabels.ts` are NOT in the foundation sets below.**
+Init/Embed detection is unchanged: a runtime scaffolded before media existed is still
+a complete `embed` runtime, and both files are written lazily on the first media embed
+exactly like a per-type `<type>.ts`. Do not add `MediaRenderer.*` or `mediaLabels.ts`
+to the detection sets, or every pre-media app would mis-classify as drift.
 
 ## Foundation sets (used by Init vs Embed detection)
 

package/skills/experience-content-media-stock-image-search/SKILL.md

@@ -4,7 +4,6 @@ description: "Searches for and downloads ethically-licensed stock images via the
 metadata:
   version: "1.0"
   domains: ["Experience"]
-  accessCheck: []
   relatedSkills:
     - "experience-search-coordinate"
   cliTools:

package/skills/experience-lwc-design-generate/SKILL.md

@@ -175,7 +175,7 @@ A new component built from this workflow is "done" only when **every** item belo
   - Optional: add o11y instrumentation as a separate pass once the component stabilizes.
   - `experience-lwc-typescript-migrate` — optional once JS is green.
   - When the new component ships behind a flag, gate it with a feature flag during rollout.
-  - `experience-lwc-api-docs-generate` — once the public API surface is stable.
+  - Generate API-surface documentation once the public API is stable (no dedicated skill for this yet).
 - Org-aware inputs used by this workflow:
   - Figma URL + screenshot (and, if available, the developer's Dev Mode metadata export) — Phase 1.2 Figma input.
   - `experience-lds-data-requirements-generate` owns the org-schema introspection and data-spec validation used in Phase 1 when the component needs org-backed data — hand off to that skill rather than duplicating its work here.