@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScMediaApproval.md

@@ -0,0 +1,301 @@
+---
+component: ScMediaApproval
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, agent, media, image, video, carousel, approval, feedback, review, dynamicform]
+related: [ScMediaSelect, ScSelectionList, ScTextArea, ScImageField, ScFileField]
+do_not_confuse_with: [ScMediaSelect, ScSelectionList, ScImageField, ScFileField, ScTodoList]
+used_by: [agent]
+---
+
+# ScMediaApproval
+
+**A one-up media carousel with a feedback box.** A 208px-tall letterboxed frame showing
+one image or video at a time (prev/next chevrons, an `n / m` counter badge and dot
+pagination when there is more than one), and beneath it a labelled textarea for
+"What should be changed?".
+
+## TL;DR for agents
+
+- **Reach for it when:** the agent generated media and the user must review it one item
+  at a time and optionally say what to change.
+- **Don't reach for it when:** the user must **pick** several items from a set
+  (→ `ScMediaSelect`), the decision is a single accept/decline on a text suggestion
+  (→ `ScSelectionList`), or the user is **uploading** media
+  (→ `ScImageField` / `ScFileField`).
+- **Four things that will bite you:**
+  1. Despite the name there are **no approve/reject buttons**. It is a viewer plus a
+     textarea; the decision buttons are yours.
+  2. `feedbackValue` is a **controlled** textarea. Without `onFeedbackChange` the user
+     cannot type.
+  3. On a video, `controls` is on **and** clicking calls `onPreview` — pressing play can
+     also open your lightbox.
+  4. Without `mediaType`, video detection is a **filename-extension regex**. Extensionless
+     CDN URLs render as `<img>` and show nothing.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScMediaApproval } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScMediaApproval
+  mediaUrls={urls}
+  mediaType="image"
+  feedbackValue={feedback}
+  onFeedbackChange={setFeedback}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `mediaUrls` | `string[]` | `[]` | Empty ⇒ a 208px black placeholder block (not nothing). |
+| `mediaType` | `"image"` \| `"video"` \| `"mixed"` | – (`undefined`) | `"video"` ⇒ every item is a `<video>`; `"image"` ⇒ every item is an `<img>`; `"mixed"` **or unset** ⇒ per-URL extension sniffing (`.mp4|.webm|.ogg|.mov|.m4v`, query string tolerated). |
+| `activeIndex` | `number` | – | Pushes the internal index via `useEffect`. Semi-controlled — see Gotcha 6. |
+| `onIndexChange` | `(i: number) => void` | – | Fires on every prev/next/dot click, with the **wrapped, clamped** index. |
+| `onPreview` | `(url: string) => void` | – | Fires when the media element itself is clicked. Wire it to your lightbox. |
+| `loading` | `boolean` | – | Forces the dark scrim + spinner overlay. ORed with the component's own load state. |
+| `feedbackLabel` | `string` | `"What should be changed?"` | ⚠️ Real default, hardcoded English. Always rendered — there is no way to hide the feedback block. |
+| `feedbackValue` | `string` | – | Controlled value (`feedbackValue ?? ""`). |
+| `onFeedbackChange` | `(v: string) => void` | – | Required for the textarea to be usable at all. |
+| `feedbackPlaceholder` | `string` | – | No default ⇒ no placeholder. |
+| `className` | `string` | – | Appended after the internal class. |
+
+⚠️ `IScMediaApprovalProps` does **not** extend `HTMLAttributes` — no `style`, `id`,
+`data-*` or root `onClick`. Wrap it.
+
+### What renders when
+
+| Region | Condition |
+|---|---|
+| `<img>` / `<video>` | `mediaUrls.length > 0` |
+| Black placeholder | `mediaUrls.length === 0` |
+| Spinner overlay | `loading` **or** the internal load state (set on navigation, cleared on `load`/`loadeddata`) |
+| Prev/next chevrons, `n / m` badge, dots | `mediaUrls.length > 1` only |
+| Feedback label + textarea | **always** |
+
+### Recipes
+
+```tsx
+// The canonical DynamicForm wiring: viewer + feedback; the form supplies the buttons
+<ScMediaApproval
+  mediaUrls={mediaUrls}
+  mediaType={field.media_type ?? "mixed"}
+  onPreview={(url) => setMediaPreview({ url, type: resolveMediaType(url) })}
+  feedbackLabel={field.feedback_label ?? "What should be changed?"}
+  feedbackValue={value.feedback || ""}
+  onFeedbackChange={(v) => setValue({ ...value, feedback: v })}
+  feedbackPlaceholder="Describe what needs to be modified."
+/>
+{/* the decision lives outside the component */}
+<div style={{ display: "flex", gap: 8 }}>
+  <ScButton text="Approve" variant="mono"  size="md" onClick={approve} />
+  <ScButton text="Request changes" variant="outline" size="md" onClick={requestChanges} />
+</div>
+
+// Tracking the visible item (e.g. to approve only the one on screen)
+const [index, setIndex] = useState(0);
+<ScMediaApproval
+  mediaUrls={urls}
+  mediaType="image"
+  activeIndex={index}
+  onIndexChange={setIndex}
+  feedbackValue={feedback}
+  onFeedbackChange={setFeedback}
+/>
+
+// Media that is still being generated server-side
+<ScMediaApproval mediaUrls={urls} loading={isGenerating} feedbackValue={fb} onFeedbackChange={setFb} />
+
+// Extensionless signed URLs — you MUST declare the type
+<ScMediaApproval mediaUrls={signedUrls} mediaType="video" feedbackValue={fb} onFeedbackChange={setFb} />
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent's in-chat DynamicForm**, `media_approval` field type — the only real
+  consumer. Live at `stream-agent packages/chat-components/src/DynamicForm.tsx`, which
+  pairs it with its own lightbox (`onPreview`) and its own submit row for the actual
+  approve/reject decision.
+- **A generation-review step in the chat transcript**, under the `ScInChatList` steps
+  that produced the media.
+- It is a **chat-surface** component: the root is `width: 100%` with a fixed 208px frame
+  and a black letterbox, tuned to sit inside a narrow panel next to `ScInChatMessage`
+  (600px), not to fill a full-page gallery.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The user reviews **one item at a time** and the items are alternatives, not a set to
+  choose from.
+- Free-text feedback ("make the background warmer") is part of the response.
+- The media may be a mix of images and video.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Pick **several** items from a grid of thumbnails | `ScMediaSelect` |
+| Accept/decline one **text** suggestion | `ScSelectionList` |
+| The user **uploads** an image | `ScImageField` |
+| The user uploads an arbitrary file | `ScFileField` |
+| A standalone feedback textarea with no media | `ScTextArea` |
+| An editable task list from the agent | `ScTodoList` |
+| A full-page asset gallery with filters and bulk actions | build it — this is a chat panel component |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScMediaSelect` — a 4-up multi-select **grid** with select-all | This is a one-up carousel |
+| A component that renders Approve/Reject | It renders neither; the name describes the *flow*, not the UI |
+| `ScImageField` — an upload/preview **form field** | This never uploads; it only displays URLs you pass |
+| `ScSelectionList` — ✓/✕ toggles | No toggles here |
+
+---
+
+## 4. Why to use it
+
+- **On-media controls that survive any image, in any theme.** The chevrons, counter and
+  dot pill deliberately use a fixed dark scrim + fixed white glyph + a subtle light
+  border and blur, rather than theme tokens, so they stay legible over a white product
+  shot, a black letterbox, and in light mode. This is the one place in the DS where
+  ignoring the tokens is correct — and it is already decided for you.
+- **Letterboxing is handled.** `object-fit: contain` on a black background at a fixed
+  208px height means a portrait and a landscape render at the same frame size, so the
+  layout doesn't jump as the user navigates.
+- **The spinner is self-managing.** Navigating sets the internal load state and `onLoad`
+  / `onLoadedData` clears it, so slow CDN fetches show a scrim without you tracking
+  per-URL load state.
+- **Index wrapping is already modulo-safe** (`((next % total) + total) % total`), and the
+  render index is clamped to `total - 1`, so a shrinking `mediaUrls` array can't produce
+  an out-of-range read.
+- **The mixed-media branch is one prop.** Sniffing per URL vs forcing a type is a
+  one-line decision instead of a per-call-site helper.
+
+---
+
+## Gotchas
+
+**1. There are no approve/reject buttons.** The component is a viewer + a feedback
+textarea. Every consumer must supply the decision affordance itself.
+
+**2. The textarea is inert without `onFeedbackChange`.** It is `value={feedbackValue ?? ""}`
+with an `onChange` that no-ops when the handler is missing — so the user types and
+nothing appears.
+
+```tsx
+// WRONG — read-only textarea that looks editable
+<ScMediaApproval mediaUrls={urls} feedbackValue={feedback} />
+
+// RIGHT
+<ScMediaApproval mediaUrls={urls} feedbackValue={feedback} onFeedbackChange={setFeedback} />
+```
+
+**3. Video: play and preview collide.** The `<video>` has `controls` **and**
+`onClick={handlePreview}`. A click on the play button also fires `onPreview`, so your
+lightbox opens over the video the user just started. Either omit `onPreview` for video,
+or have your lightbox continue playback.
+
+**4. Extension sniffing fails on extensionless URLs.** With `mediaType` unset or
+`"mixed"`, `isVideoUrl` tests `/\.(mp4|webm|ogg|mov|m4v)(\?.*)?$/i`. A signed URL like
+`…/asset/9f3c1?sig=…` renders as `<img>` → broken image, no error. If your URLs have no
+extension, pass `mediaType` explicitly.
+
+**5. `cursor: zoom-in` is unconditional.** The media always looks clickable, even when
+you didn't pass `onPreview`. There is no way to turn that off short of a `className`
+override.
+
+**6. `activeIndex` is a *push*, not a binding.** The `useEffect` only runs when
+`activeIndex` changes; internal prev/next still moves the internal index. If you pass a
+constant `activeIndex` and ignore `onIndexChange`, the user can navigate away and your
+state will be wrong.
+
+```tsx
+// WRONG — thinks it pinned the view to item 0
+<ScMediaApproval mediaUrls={urls} activeIndex={0} />
+
+// RIGHT — controlled round-trip
+<ScMediaApproval mediaUrls={urls} activeIndex={index} onIndexChange={setIndex} />
+```
+
+**7. No spinner on first paint.** The internal load state starts `false` and is only set
+to `true` on navigation. For the initial image you must pass `loading` yourself if you
+want a scrim.
+
+**8. Navigation wraps silently.** "Next" on the last item goes to the first. There is no
+disabled end-state, so users can loop without noticing they've been round.
+
+**9. `alt=""` is hardcoded.** Images are announced as decorative. If the media *is* the
+content — which it is here — a screen-reader user gets nothing but the feedback label.
+
+**10. The feedback block cannot be hidden.** No prop suppresses it; passing
+`feedbackLabel=""` leaves an empty label div and the textarea. If you only want a
+carousel, this is the wrong component.
+
+**11. Fixed 13rem (208px) media height and hardcoded `#000` backgrounds.** Not
+tokenised (deliberate, for letterboxing), and not overridable via props.
+
+**12. The textarea's resize grip is clipped.** `.textArea` is `resize: vertical` but
+`.inputContainer` is `overflow: hidden`, so the drag handle is cut off — users get a
+`min-height: 4.5rem` box that scrolls rather than one they can obviously grow.
+
+**13. No root-level props.** `IScMediaApprovalProps` doesn't extend `HTMLAttributes`, so
+`style`/`id`/`data-testid` are type errors. Wrap it.
+
+---
+
+## In the wild
+
+Rendered by the **agent runtime**, not by any of the four dashboards — the live call
+site is the chat DynamicForm's `media_approval` field in the `stream-agent` repo
+(`@streamoid/chat-components`):
+
+```tsx
+// stream-agent  packages/chat-components/src/DynamicForm.tsx:871
+<ScMediaApproval
+  mediaUrls={mediaUrls}
+  mediaType={field.media_type ?? "mixed"}
+  onPreview={(url) => setMediaPreview({ url, type: resolveMediaType(url) })}
+  feedbackLabel={field.feedback_label ?? "What should be changed?"}
+  feedbackValue={mediaValue.feedback || ""}
+  onFeedbackChange={(v) =>
+    handleFieldChange(field.id, {
+      ...mediaValue,
+      feedback: v,
+      media_urls: normalizeMediaUrls(mediaValue.media_urls ?? mediaUrls),
+      media_type: mediaValue.media_type ?? field.media_type ?? "mixed",
+    } as MediaApprovalValue)
+  }
+  feedbackPlaceholder={
+    field.feedback_placeholder ?? "Describe what needs to be modified."
+  }
+/>
+```
+
+---
+
+## Related
+
+- `ScMediaSelect` — the multi-select grid sibling; same media vocabulary, different job.
+- `ScSelectionList` — accept/decline for text suggestions.
+- `ScTextArea` — the standalone DS textarea if you need feedback without media.
+- `ScImageField` / `ScFileField` — the upload-side fields.
+- `ScButton` — what you'll use for the Approve / Request-changes pair this component omits.

package/dist/docs/ScMediaSelect.md

@@ -0,0 +1,310 @@
+---
+component: ScMediaSelect
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, agent, media, image, video, grid, multi-select, thumbnails, gallery, dynamicform]
+related: [ScMediaApproval, ScCheckField, ScImageField, ScTodoList, ScSelectionList]
+do_not_confuse_with: [ScMediaApproval, ScImageField, ScSelectionList, ScCheckField, ScStoreCard]
+used_by: [agent]
+---
+
+# ScMediaSelect
+
+**A 4-up thumbnail grid for picking several generated assets.** A count line
+("3 of 12 selected (min 1)") with "Select all | Deselect all" above a bordered,
+internally-scrolling square grid; selected tiles get a strong border and a white check
+badge, and a hover-only maximize button opens your lightbox.
+
+## TL;DR for agents
+
+- **Reach for it when:** the agent produced a batch of images/videos and the user must
+  choose a subset.
+- **Don't reach for it when:** the user reviews one item at a time with free-text
+  feedback (→ `ScMediaApproval`), the choice is textual (→ `ScCheckField` /
+  `ScSelectionList`), or the user is **uploading** (→ `ScImageField`).
+- **Four things that will bite you:**
+  1. `min` and `max` are **labels only**. The component does not enforce them —
+     `onToggle` fires regardless.
+  2. Selection identity is the **URL string**. Duplicate URLs in `items` select and
+     deselect together.
+  3. `mediaType` defaults to `"image"`, and only the exact value `"video"` renders
+     `<video>`. **`"mixed"` renders `<img>` for everything**, including your `.mp4`s.
+  4. Tiles are `div[role="button"] tabIndex={0}` with **no key handler**, and the preview
+     button is `display: none` until `:hover` — focusable but not operable, and invisible
+     on touch.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScMediaSelect } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScMediaSelect items={urls} selected={picked} onToggle={toggle} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `items` | `string[]` | `[]` | Media URLs, in grid order. Empty ⇒ an empty bordered box, but the header and both link buttons still render. |
+| `selected` | `string[]` | `[]` | Controlled. Compared by URL via a `Set` (memoised on the array identity — pass a new array, not a mutated one). |
+| `onToggle` | `(url: string) => void` | – | Fires on any tile click. **You** add/remove and **you** enforce `max`. |
+| `onSelectAll` | `() => void` | – | The "Select all" link. The component does not compute the selection for you. |
+| `onDeselectAll` | `() => void` | – | The "Deselect all" link. |
+| `min` | `number` | `0` | **Display only.** `> 0` appends `" (min N)"` to the count label. |
+| `max` | `number` | – (⇒ `items.length`) | **Display only.** Appends `" (max N)"` **only when** the resolved max is less than `items.length`. |
+| `mediaType` | `"image"` \| `"video"` \| `"mixed"` | `"image"` | ⚠️ Only `"video"` renders `<video muted playsInline>`. `"image"` **and** `"mixed"` both render `<img>`. |
+| `onPreview` | `(url: string) => void` | – | **Gates the maximize button** — omit it and no preview affordance renders at all. |
+| `className` | `string` | – | Appended after the internal class. |
+
+⚠️ `IScMediaSelectProps` does **not** extend `HTMLAttributes` — no `style`, `id`,
+`data-*` or root `onClick`. Wrap it.
+
+### The count label, exactly
+
+`` `${selected.size} of ${items.length} selected` `` then `" (min N)"` if `min > 0`,
+then `" (max N)"` if `resolvedMax < items.length`. All hardcoded English.
+
+### Recipes
+
+```tsx
+// The canonical DynamicForm wiring — note that MAX IS ENFORCED HERE, not in the DS
+const toggle = (url: string) => {
+  const next = new Set(selectedUrls);
+  if (next.has(url)) next.delete(url);
+  else {
+    if (next.size >= maxSelect) return;      // <- the component will not do this
+    next.add(url);
+  }
+  setSelectedUrls(Array.from(next));
+};
+
+<ScMediaSelect
+  items={allMediaUrls}
+  selected={selectedUrls}
+  min={minSelect}
+  max={maxSelect}
+  mediaType="image"
+  onToggle={toggle}
+  onSelectAll={() => setSelectedUrls(allMediaUrls.slice(0, maxSelect))}
+  onDeselectAll={() => setSelectedUrls([])}
+  onPreview={(url) => setLightbox(url)}
+/>
+
+// Video thumbnails — "mixed" would render <img> and show broken tiles
+<ScMediaSelect items={clipUrls} selected={picked} mediaType="video" onToggle={toggle} />
+
+// De-duplicate before rendering: selection is keyed on the URL
+<ScMediaSelect items={Array.from(new Set(urls))} selected={picked} onToggle={toggle} />
+
+// Gate a submit on the min the component only *displays*
+<ScButton
+  text="Use selected"
+  variant="mono"
+  size="md"
+  state={picked.length >= minSelect ? "default" : "disabled"}
+  onClick={submit}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent's in-chat DynamicForm**, `media_select` field type — the only real
+  consumer. Live at `stream-agent packages/chat-components/src/DynamicForm.tsx`, which
+  owns the max enforcement, the select-all slice and the lightbox.
+- **A batch-review step in the chat transcript**, after a generation run — "here are 12,
+  which do you want?".
+- Tuned for a **narrow chat panel**: 4 columns (3 below 360px), square tiles, and an
+  internal `max-height: 18.75rem` scroll region rather than growing the transcript.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The user picks **a subset** of a batch, and seeing all candidates at once matters.
+- The tiles are square-croppable and the count is the feedback the user needs.
+- The set is large enough that an internal scroll region is preferable to a growing panel.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Review one item at a time, with free-text feedback | `ScMediaApproval` |
+| Accept/decline one **text** suggestion | `ScSelectionList` |
+| Multi-select over **labels**, not media | `ScCheckField` (or `ScCheckbox` for one) |
+| The user **uploads** an image | `ScImageField` |
+| Pick exactly one media item | `ScMediaApproval` (carousel + your own confirm), or this with your own max=1 |
+| An editable task list | `ScTodoList` |
+| A full-page asset library with filters, pagination, bulk ops | build it — this is a chat panel component |
+| Cards representing entities rather than media | `ScStoreCard` / `ScDefaultCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScMediaApproval` — one-up carousel + feedback textarea | This is a multi-select grid with no feedback field |
+| `ScImageField` — an upload/preview **form field** | This never uploads |
+| `ScCheckField` — checkbox group with a field label | No labels here, only thumbnails |
+| A component that enforces min/max | It only prints them |
+
+---
+
+## 4. Why to use it
+
+- **The selected affordance is doubled.** A 2px `--alias-border-strong` frame *and* a
+  filled check badge, so selection survives greyscale and doesn't depend on a colour the
+  thumbnail might already contain.
+- **The check badge is token-paired** (`--alias-fill-base-base` circle,
+  `--alias-text-and-icons-inverse` tick), so it inverts correctly in light mode instead
+  of becoming a white blob on a bright product shot.
+- **The grid can't blow out the panel.** `max-height: 18.75rem` + `overflow-y: auto`
+  means a 200-item batch scrolls inside its own box rather than pushing the chat
+  transcript around, and the 4→3 column breakpoint at 360px keeps tiles tappable on a
+  phone.
+- **Square-cropped tiles scan as a set.** `aspect-ratio: 1/1` + `object-fit: cover` on a
+  black background gives a uniform grid whatever the source aspect ratios are.
+- **Hover-revealed preview keeps the tile clean** — the maximize button `stopPropagation`s
+  so previewing never toggles selection, which is the single most common bug when this is
+  hand-rolled.
+
+---
+
+## Gotchas
+
+**1. `min`/`max` are not enforced.** They only decorate the count label. `onToggle` fires
+on every click and the component will happily let the user select all 50 when `max={3}`.
+
+```tsx
+// WRONG — believes max is a constraint
+<ScMediaSelect items={urls} selected={picked} max={3} onToggle={(u) => setPicked([...picked, u])} />
+
+// RIGHT — enforce it in your handler (see the first recipe)
+```
+
+**2. `"mixed"` renders `<img>`, not a per-URL guess.** Unlike `ScMediaApproval` — which
+sniffs the extension for `"mixed"` — this component branches on `mediaType === "video"`
+only. Passing `field.media_type ?? "mixed"` for a mixed batch gives you broken `<img>`
+tiles for the videos.
+
+```tsx
+// WRONG for a mixed batch — videos render as broken images
+<ScMediaSelect items={urls} mediaType="mixed" selected={picked} onToggle={toggle} />
+
+// RIGHT — split the batch, or render two grids
+<ScMediaSelect items={images} mediaType="image" … />
+<ScMediaSelect items={clips}  mediaType="video" … />
+```
+
+**3. Selection is keyed on the URL string.** Duplicate URLs in `items` are visually
+distinct tiles that select and deselect **together**, and `onToggle` cannot tell them
+apart. De-duplicate before rendering. (React keys use `url + "-" + index`, so keys are
+fine — the selection model is what breaks.)
+
+**4. `selected` is memoised on array identity.** The internal `Set` is
+`useMemo(..., [selected])`. Mutating the same array in place (`picked.push(url)`) will
+not refresh the highlight; always pass a new array.
+
+**5. Tiles are keyboard-focusable but not keyboard-operable.** They are
+`div[role="button"] tabIndex={0} aria-pressed` with **no `onKeyDown`**. Tab lands on
+them, Enter and Space do nothing. There is no way to fix this from the outside — treat it
+as a DS bug for accessible surfaces.
+
+**6. The preview button is hover-only.** `.previewButton { display: none }` → `flex` on
+`.item:hover`. There is no hover on touch, so preview is unreachable on mobile.
+
+**7. No `onPreview` ⇒ no preview button at all.** The button is conditionally rendered on
+the handler's presence, which is good — but means "the maximize icon is missing" is
+usually a missing prop, not a CSS problem.
+
+**8. "Select all" / "Deselect all" compute nothing.** They just call your handlers. If
+you wire `onSelectAll` to `setSelected(items)` while `max` is smaller, you have silently
+broken your own limit — slice it (`items.slice(0, max)`).
+
+**9. The header renders even with zero items.** "0 of 0 selected" plus two live link
+buttons over an empty box. Guard on `items.length` and render your own empty state.
+
+**10. Thumbnails are cropped.** `object-fit: cover` on a square tile — a tall portrait
+loses its top and bottom. If the composition matters for the choice, `ScMediaApproval`
+(which uses `contain`) is the better fit.
+
+**11. Video tiles have no poster and no controls.** `<video muted playsInline>` with no
+`poster` shows a black frame until metadata loads and never plays inline. Provide poster
+images and use `mediaType="image"` if the first frame matters.
+
+**12. `alt=""` is hardcoded.** Tiles are announced as decorative; a screen-reader user
+gets a run of unlabelled pressed/unpressed buttons.
+
+**13. Hardcoded English.** `"N of M selected"`, `" (min N)"`, `" (max N)"`,
+`"Select all"`, `"Deselect all"`, and the `"Preview"` aria-label. No label props.
+
+**14. No root-level props.** `IScMediaSelectProps` doesn't extend `HTMLAttributes`, so
+`style`/`id`/`data-testid` are type errors. Wrap it.
+
+---
+
+## In the wild
+
+Rendered by the **agent runtime**, not by any of the four dashboards — the live call
+site is the chat DynamicForm's `media_select` field in the `stream-agent` repo
+(`@streamoid/chat-components`):
+
+```tsx
+// stream-agent  packages/chat-components/src/DynamicForm.tsx:916
+<ScMediaSelect
+  items={allMediaUrls}
+  selected={selectValue.selected_urls}
+  min={field.min_select ?? 0}
+  max={maxSelect}
+  mediaType={field.media_type ?? "mixed"}
+  onToggle={toggleSelect}
+  onSelectAll={() =>
+    handleFieldChange(field.id, {
+      ...selectValue,
+      selected_urls: allMediaUrls.slice(0, maxSelect),
+    } as MediaSelectValue)
+  }
+  onDeselectAll={() =>
+    handleFieldChange(field.id, {
+      ...selectValue,
+      selected_urls: [],
+    } as MediaSelectValue)
+  }
+  onPreview={(url) =>
+    setMediaPreview({
+      url,
+      type:
+        field.media_type && field.media_type !== "mixed"
+          ? field.media_type
+          : inferMediaTypeFromUrl(url),
+    })
+  }
+/>
+```
+
+Note that this call site passes `mediaType="mixed"` — which, per Gotcha 2, renders
+`<img>` for every item. That is a live bug worth fixing in the runtime (or by teaching
+this component to sniff like `ScMediaApproval` does).
+
+---
+
+## Related
+
+- `ScMediaApproval` — the one-up carousel sibling, with a feedback textarea and `contain` fit.
+- `ScCheckField` / `ScCheckbox` — multi-select over labels rather than thumbnails.
+- `ScSelectionList` — accept/decline one text suggestion.
+- `ScImageField` — the upload-side field.
+- `ScTodoList` — the other "user edits what the agent produced" in-chat component.