::adom-pinout{src="/ray/stm32f103c8t6/render/pinout.json" layout="dual"}

{ "name": "adom-example", "mode": "frontend",
  "script": "https://wiki.adom.inc/OWNER/SLUG/render/widget.js",
  "element": "adom-example", "attrs": ["src"] }

# Widget Registry

The reviewed list of widgets any wiki page can render from plain markdown (adom/wiki#152). Only widgets in `widgets.json` on THIS page render; adding one is an edit someone reads. That list is the entire trust model, so this page stays org-owned.

## Using a widget

On its own line in any `README.md`:

```markdown
::adom-pinout{src="/ray/stm32f103c8t6/render/pinout.json" layout="dual"}
```

An entry marked `"render": "inline"` (every current widget) renders in place as its custom element, with the reader's session. Any other entry renders as a sandboxed frame: opaque origin, storage shimmed, `connect-src` limited to the wiki (plus a backend widget's registered origin). An unregistered tag renders as nothing for readers; pushing a README with one gets a `WIDGET_TAG_UNREGISTERED` hint.

Data files: pass `src` as an absolute path on the wiki, usually your own page's render route (`/OWNER/SLUG/render/FILE.json`). Relative paths resolve against the widget frame's route and will not find your file.

## How scripts are served (read this before curling the raw URLs)

Readers' frames never load the `script` URLs above directly: they load
`/widget-script/<name>.js`, a registry-gated route that serves only reviewed
scripts with a JavaScript MIME, read straight from the page repo. So the host
page's visibility does not matter, and the raw URL 404ing for anonymous
callers is expected: in this file it is the repo pointer the route resolves,
not the URL readers fetch.

## What belongs here (read before proposing a widget)

The registry is for **generic** widgets: one script that many pages reuse, each page passing its own data through attributes or a `src` file. A pinout, a table, a stock line and a video player all qualify: none of them knows which page it is on.

A tool built for **one project** does not belong here, however polished. Examples are an explorer for one board's circuit, a simulator of one design, or a calculator for one part: its data lives in the script, and only its own page can use it. Make it that page's `readme.html` instead, with its JS and CSS inlined, so the tool is the page (it replaces README.md on the page). See the `wiki-readme-html` skill in adom/adom-wiki-skillpack.

A test for a proposed entry: could two unrelated pages each use it with their own data? If not, it is a readme.html, not a widget.

## Registering a widget

Append an entry to `widgets.json`:

```json
{ "name": "adom-example", "mode": "frontend",
  "script": "https://wiki.adom.inc/OWNER/SLUG/render/widget.js",
  "element": "adom-example", "attrs": ["src"] }
```

- `name`: the markdown tag (slug-safe, max 32 chars)
- `mode`: `frontend` (wiki-served script) or `backend` (adds `origin`)
- `script`: https URL of the script that defines the custom element
- `element`: the dashed custom-element name the script defines
- `attrs`: allowlist of attributes the tag may set (escaped, length-capped); anything else in a tag is dropped
- `origin` (backend only): the PUBLIC https origin the frame's `connect-src` widens to; the widget_connect rules apply (no IP literals, loopback, or private TLDs)
- `height`: `auto` (default, frames self-report via readme-height) or a fixed pixel number

Registry caps: 32 widgets, 12 attrs each. A malformed entry is dropped, never breaks rendering.

## Current widgets

Five load from adom/component-widgets and take a JSON `src`; adom-stock and adom-video load from this page (adom-video takes `video`, not `src`: the wiki inlines a `src` file into the frame); adom-symbol-variants loads from adom/adom-symbol and takes a component page.json `src`:

| tag | shows |
|---|---|
| `::adom-pinout{src="..."}` | interactive pinout diagram |
| `::adom-chip-thumbnail{src="..."}` | chip render thumbnail |
| `::adom-molecule{src="..."}` | molecule viewer |
| `::adom-heatsink-via{src="..."}` | thermal via layout |
| `::adom-symbol-variants{src="..."}` | alternate schematic-symbol layouts (2-column, square, grouped, chip outline), generated in the browser |
| `::adom-footprint-variants{src="..."}` | footprint-variant family (baseline, heatsink vias, 300 µm solder balls, rounded pads), parsed live from the page's `.kicad_mod` files; takes an adom-footprint `variants.json` `src`; loads from adom/component-widgets |
| `::adom-table{src="..."}` | any JSON array as a filterable, sortable table; generic, not component-specific; `columns` `heading` `filter` `facet` `sort` `dim` `mark` `colorby` |
| `::adom-stock{src="/api/pages/OWNER/SLUG/stock"}` | live stock and price at Mouser, DigiKey and LCSC for a hardware page, from the wiki's cached vendor lookups (adom/wiki#186); component pages show it in their sidebar by themselves; `heading` |
| `::adom-verified{src="..."}` | the "verified by" trust mark: big green check, who verified the page and when, per-variant coverage, and the full verification log with evidence; turns amber when a verified file changes; takes the page's `verification.json`; loads from adom/component-widgets |
| `::adom-models{src="..."}` | every 3D file on a component page as a card: thumbnail, STEP or GLB, etched or unmarked and where the part number sits, what makes it different from its siblings, what it was derived from, a download, and whether the page still serves the file that was described (checked against the file listing, nothing downloaded); previous versions fold away; takes the page's `models.json` (adom/models@1); loads from adom/component-widgets |
| `::adom-video{video="..."}` | a YouTube-style video player: every YouTube shortcut (Space/K, J/L, arrows, 0 to 9, `,` `.` frame step at the video's real frame rate with a frame-number overlay, `<` `>` speed 0.25x to 4x, hold the mouse on the video for 2x, C captions, + / - size, O / W caption opacity, Ctrl+arrows chapters, F, I, M, Shift+N/P, media keys, ?), Clean frame (H: hides the title, controls and captions for a screenshot; the mouse does not bring them back), Copy / Save this frame as a full-resolution PNG, a Share button (copies a link to the page that opens on this video, optionally at the current time: `#video=<file-name>&t=90`, plus the file's own link), a 24px timeline grab zone with drag-to-scrub and a hover frame preview, chapters as bar segments, captions, speed and loop; `title` `poster` `chapters` (JSON `[{"t":12,"title":"..."}]` or WebVTT) `captions` (.vtt or .srt) `start` (`90` or `1m30s`) `loop` `muted` `autoplay`; F opens the player full-window in a new tab (widget frames cannot go fullscreen); a narrated video gets captions and chapters free: gang-takes (adom/adom-video-post) writes the `.vtt` from the adom-tts narration text, the `.chapters.json` from its segment labels, and the embed line; on a private page pass `src=` a manifest with them inlined; a private page's VIDEO plays only where the browser sends third-party cookies until adom/wiki#228 (signed media URLs) ships, elsewhere the widget offers Play it in a new tab; loads from this page |
| `::adom-3d{src="..."}` | any GLB in the canonical Adom 3D Viewer, click to load (nothing loads until the reader asks; it unloads offscreen and releases the WebGL context); `poster` `heading` `caption`; publish the GLB without Draco, the frame cannot reach the decoder CDN; loads from adom/component-widgets |