# Widgets — two paths

Articles ship interactive widgets. There are two ways to get them in:

## Path 1 — PoCo embeds (iframe)

DC's team owns 354 polished React widgets in the PokerQuiz library, served at `https://poco-web.aceguardian.workers.dev/widgets/<id>`. You pick a shape, clone the YAML content blob with your article's data, and embed via `<iframe>`. No React code, no porting.

**Pick this when:**
- The shape exists in the PoCo catalog (or close enough to clone-and-adjust)
- You want production-polish + consistency with the wider QuintAce product
- The interaction is canonical (quiz / dial / grid / arcade)

→ Catalog: **[`poco-catalog.md`](poco-catalog.md)** — 354 widgets organized by generation/theme

## Path 2 — Ad-hoc vanilla HTML (per-article `embed/`)

Write a standalone HTML file under `articles/<slug>/embed/<widget-name>.html` using QuintAce DS tokens + Chart.js. No build step, no React. All 130 existing article embeds are this style.

**Pick this when:**
- PoCo doesn't have your shape (Squid token economy, Big Antes matrix, custom spot card)
- The widget is one-off for this article only
- You need full styling control or iframe friction is a blocker

→ Catalog: **[`ad-hoc-catalog.md`](ad-hoc-catalog.md)** — 130 existing widgets grouped by shape, with "copy from" pointers per shape
→ Authoring section is at the bottom of the catalog (formal `AUTHORING.md` TBD)

## Choice matrix

| Need | Path |
|---|---|
| Shape exists in PoCo + canonical interaction | **Path 1 (PoCo iframe)** |
| Bespoke article-specific shape | **Path 2 (ad-hoc HTML)** |
| Production-polish + reusable across articles | **Path 1** |
| Quick custom widget, this article only | **Path 2** |
| Hand replay / spot card / position-grid heatmap | **Path 2** (PoCo doesn't cover these yet) |
| Quiz / dial / range funnel / game-theory concept | **Path 1** (v2 or v12 has it) |

## What's here

- **[`index.html`](index.html)** — live visual gallery. Both paths in one page, with lazy-loaded iframe thumbnails for the 130 ad-hoc widgets + name cards for the 354 PoCo widgets. Filter by shape, search by name. **Live at https://quintace-external.github.io/articles/widgets/**.
- `poco-catalog.md` — text catalog of 354 PoCo widgets (DC's React library), grouped by v-generation.
- `ad-hoc-catalog.md` — text catalog of 130 vanilla HTML widgets, grouped by shape. Copy any one as a template.
- `README.md` — this file.
- `AUTHORING.md` — TBD. Authoring section currently at the bottom of `ad-hoc-catalog.md`.

## The skill

Run `/add-widget` in Claude Code. It walks you through picking a template (or starting fresh), adapts the data + labels, places it under `articles/<slug>/embed/`, and inserts the iframe in `v1.md`. Three paths: copy-existing (default), write-new, or request-PoCo.

## Status

- **Ad-hoc path: ready to go.** Catalog of 130 widgets in `ad-hoc-catalog.md`, copy + adapt any one as a template.
- **PoCo path: catalog ready, deploy pipeline owned by DC's team.** Browse `poco-catalog.md` to pick a widget; the deploy / YAML-load workflow is DC's to resolve.