# Component previews: show how components look in the user's use case · Issue \#64 · screen/col

[View on GitCafe](https://git.cafe/screen/col/issues/64)

Repository: [screen/col](https://git.cafe/screen/col)

Visibility: public

State: backlog

Priority: 0

## Description

[Discussion and activity](https://git.cafe/screen/col/issues/64)

---

## What to build

Developers choosing components through Col's MCP can see how each component actually looks — rendered in their project's own context: framework, styling system, theme tokens, and a scene matching their use case with plausible sample data — without leaving their agent. One shared Col preview page renders the component story with the caller's tokens and scene; the MCP delivers it progressively as an MCP Apps widget where the host supports one, a screenshot image where it renders one, and a Col preview URL everywhere, terminals included. The same previews appear on Col's own library and component pages. Previews ride the catalogue's existing verification and recorded reuse-permission rules, and every preview states its rendered source and applied theme so a render is never mistaken for compatibility evidence.

## Acceptance criteria

- [ ] A component with a recorded story renders on its Col preview page with supplied theme tokens and a use-case scene applied.
- [ ] `get_component` returns the preview URL, preview evidence markers (rendered source, applied theme, explicit gaps), and a screenshot for libraries with recorded reuse permission.
- [ ] On an MCP Apps host the same call renders the live themed preview inside a sandboxed widget; on a host without the extension the call returns the identical information as text and image with no errors.
- [ ] A terminal-only client receives the preview URL and markers in the text result, and the find → inspect → see workflow completes through the browser.
- [ ] Components of libraries without recorded reuse permission render nothing and link to the official documentation instead.
- [ ] Components Col cannot render (non-React runtimes at first) are marked preview-unavailable with their documentation link, never faked.
- [ ] Every shipped story carries a build-rendered screenshot, and the tool-layer and story-validation tests cover the new payloads.

## Blocked by

None (can start immediately).

## Ticket breakdown

1. **Preview story format and validator** — a contributor records a story (renderable code, declared dependencies, scene and sample-data flavour) for a component of a permitted library; the format is validated at contribution time like the verified component index. *Blocked by: none.*
2. **Shared preview page with token theming and scenes** — the story renders in the caller's theme tokens and a use-case scene with synthetic sample data on one Col page; this page is the single render surface every later channel consumes. *Blocked by: 1.*
3. **Build-time screenshot pipeline and site gallery** — CI renders every story to screenshots, and Col's library and component pages show the previews. *Blocked by: 2.*
4. **MCP preview payload and image blocks** — `get_component` carries the preview URL, preview evidence markers, and a screenshot as an image content block alongside the text result. *Blocked by: 2.*
5. **MCP Apps preview widget** — the tool declares the standard UI metadata pointing at one generic preview template that iframes the shared page, with the use-case context delivered through tool arguments and structured content over the standard bridge. *Blocked by: 2.*