hero-studio &                      # port 8846 (or: node server.js in the package dir)

adom-cli hydrogen webview open-or-refresh --name "Hero Studio" \
  --url "$(echo $VSCODE_PROXY_URI | sed 's/{{port}}/8846/')" --panel-id <webview-pane-id>

curl -s localhost:8846/state                       # read state
curl -s -X POST localhost:8846/state -H 'Content-Type: application/json' \
  -d '{"layout":"mirror","theme":"onion","gradAngle":245}'
curl -s -X POST localhost:8846/ui/toast -H 'Content-Type: application/json' \
  -d '{"text":"narration for the user","kind":"info"}'
curl -s localhost:8846/console                     # page console, no DevTools

curl -s -X POST localhost:8846/generate        # blocks ~5-10s, returns JSON
# -> { ok, file, url, latest: "generated/latest.png", ... }

adom-wiki page hero <owner>/<slug> --image <package-dir>/generated/latest.png
adom-cli hydrogen webview open-or-refresh --name "Wiki Page" --url "https://wiki.adom.inc/<owner>/<slug>" --panel-id <pane>

./refresh-data.sh    # pulls live adom-wiki page trending, then restart the server

---
name: hero-studio
description: Open and drive Hero Studio, the live playground for the hero image v2 definition (lower third = true-text overlay). Use when the user wants to design or preview a wiki hero image, try hero layouts, screenshot bleeds, brand tile themes, or gradient angles, compare title placement (overlay vs image), or see a hero inside the wiki homepage marquee, the index card grid, or an adom-desktop style right bar. Trigger phrases - open hero studio, design a hero, hero playground, hero billboard, preview hero in marquee, lower third overlay, hero layouts, hero themes, rotate the hero gradient.
user-invocable: true
---

# Hero Studio

A local web app (plain Node, no dependencies) that renders a full 16:10 hero live and
shows it inside pixel-faithful wiki contexts. State lives on the server, so you drive
everything with plain HTTP.

## Start and show it

```bash
hero-studio &                      # port 8846 (or: node server.js in the package dir)
```

Show it in a Hydrogen webview using the container proxy URL, for example:

```bash
adom-cli hydrogen webview open-or-refresh --name "Hero Studio" \
  --url "$(echo $VSCODE_PROXY_URI | sed 's/{{port}}/8846/')" --panel-id <webview-pane-id>
```

Pick a webview pane, never the VS Code pane. Screenshot-verify with
`adom-cli hydrogen screenshot panel --name "Hero Studio"`.

## Drive it

```bash
curl -s localhost:8846/state                       # read state
curl -s -X POST localhost:8846/state -H 'Content-Type: application/json' \
  -d '{"layout":"mirror","theme":"onion","gradAngle":245}'
curl -s -X POST localhost:8846/ui/toast -H 'Content-Type: application/json' \
  -d '{"text":"narration for the user","kind":"info"}'
curl -s localhost:8846/console                     # page console, no DevTools
```

State fields: `page` (owner/slug from the bundled trending data), `layout` (bleed-bottom,
bleed-right, bleed-top, bleed-corner-br, bleed-corner-tr, contained, mirror), `theme`
(midnight, pcb, onion, pill, grid, gradient), `gradAngle` (0 to 360, brand default 155),
`titleMode` (overlay-only, image-only, both), `show.logo/title/subtitle/description`,
`overlay.pill/scores/author/slug`, `guides`.

The UI follows within 1 second of any POST (live channel plus poll fallback). Deep links:
append `#contexts` or `#wikigrid` to the URL to land on the in-context previews.

## Generate the actual hero PNG (the point of the app)

Do NOT hand-roll a hero render: pose the studio via POST /state, then generate through the
studio so the PNG carries hero-studio provenance metadata and the user sees it happen
(toast + preview modal pop automatically in their open studio).

```bash
curl -s -X POST localhost:8846/generate        # blocks ~5-10s, returns JSON
# -> { ok, file, url, latest: "generated/latest.png", ... }
```

The output is the hero standard 2000x1250 PNG with a `comment` tEXt chunk recording the
generator, version, and full studio state. Then set it as the page hero and show the user:

```bash
adom-wiki page hero <owner>/<slug> --image <package-dir>/generated/latest.png
adom-cli hydrogen webview open-or-refresh --name "Wiki Page" --url "https://wiki.adom.inc/<owner>/<slug>" --panel-id <pane>
```

Requirements: puppeteer-core (env `PUPPETEER_CORE` if not in a standard location) and
Chrome (env `CHROME`, or the puppeteer cache). Failures return `{ok:false, error, hint}`.

## Refresh the dataset

```bash
./refresh-data.sh    # pulls live adom-wiki page trending, then restart the server
```