# Hero Studio

A live playground for the **hero image v2 definition**: the lower third of every hero is a
true-text overlay, rendered by the surface that shows it, never baked into the image.

The overlay carries the metadata that should stay dynamic and clickable: the type pill
(APP / SKILL / BOOTSTRAP / COMPONENT), the trending score, the star count, the title, the
author, and the wiki slug in the lower right. Because it is real text, every part of it can
be a link, and the scores update daily without re-rendering a single PNG. The image part of
the hero keeps the lower third text-free: the background gradient or brand tile simply
continues to the bottom edge, and the app screenshot may bleed under the overlay zone
knowing the scrim will cover it.

## What you can flip, live

- **Package**: real pages from `adom-wiki page trending`, with their live scores, stars,
  installs, authors, and tags.
- **Screenshot placement**: bleed bottom, bleed right, bleed top, lower-right corner,
  upper-right corner, contained, and mirror (text right, window left). Mirror flips the
  whole background composition too: glows, tiles, and corner motifs.
- **Background theme**: six on-brand looks, including the authentic Kickstand tiling
  patterns from the `adom/brand` page (concentric-arc onion corner, scattered pill field,
  outlined square grid) plus midnight dot-grid, PCB traces, and the flagship gradient.
- **Gradient angle**: rotate the base gradient to make a hero feel unique while staying
  on-brand (default 155).
- **Image-zone text**: wordmark, big title, value-prop subtitle, detail line.
- **Title placement**: overlay only, image only, or both, to settle the redundancy
  question directly.

![In-context previews](docs/contexts.png)

## In-context previews, copied from the wiki source

The studio renders the same hero into pixel-faithful copies of the surfaces that will show
it, so you judge the design where it actually lives:

- the **wiki homepage marquee** (`.ts-slide` tiles: caption scrim, badge plates, trending
  and star pills, scrolling track),
- the **wiki index page card grid** (`.page-card`: 16:10 hero slot, badge colors, meta row,
  tag chips, install row),
- an **adom-desktop right bar** showing the full v2 hero with its baked overlay.

The wiki surfaces receive the image part only, because the wiki already overlays its own
true text. That is the core of the v2 idea: the overlay is per-surface chrome, and the
homepage marquee already proves the pattern.

![Index page cards](docs/index-cards.png)

## Component heroes

A separate mode for component pages, switched at the top of the panel ("What are you
making"). A component hero leads with the physical part, not an app window:

- **Image ladder**: a real-world photo where the screenshot area would be; if none exists,
  a raytraced render; last resort, the plain phong 3D viewport shot. The ladder is the
  quality bar: the wiki's own `sm02b-srss-tb` hero is currently the bottom tier.
- **Name where the title goes**, and a plain-language spec line as the subtitle
  ("100k SMD 1% resistor").
- **MPN placement**: in the family chip row, under the name, or in the lower-third
  overlay next to the slug.
- **Family chip** ("JST · SH SERIES · 1.0 MM") in the eyebrow slot, following the
  adom-usb family-marker pattern.

![Component mode](docs/component-mode.png)

The bundled component imagery is sample material for the lab: the photo tier is cropped
from the john/adom-usb-sniffer-dap hero (a Wikimedia Commons photograph under its
respective CC license), the phong tier is cropped from the live adom/sm02b-srss-tb hero,
and the raytrace tier is an illustrative render. Swap in your own part's imagery when
designing a real hero.

## Run it

```
hero-studio            # serves on port 8846
```

Open `/proxy/8846/` in a webview (or `http://localhost:8846` locally). No dependencies,
plain Node.

Refresh the sample data from the live wiki any time:

```
./refresh-data.sh      # needs the adom-wiki CLI, then restart the server
```

## Generate

The Generate button (or `POST /generate`) renders the current hero server-side with
Puppeteer to the hero-standard 2000x1250 PNG, pops a toast and a preview modal in every
open studio, and writes `generated/latest.png`. Each PNG carries a `comment` metadata
chunk recording that hero-studio produced it, plus the exact studio state, so publish
tooling can verify a hero came through the studio rather than being hand-rolled slop.
The canonical flow for an agent: pose the studio, `POST /generate`, then
`adom-wiki page hero <owner>/<slug> --image generated/latest.png`.

## Drive it (AI-first)

State lives on the server; the UI, the CLI, and any agent stay in lockstep through a live
channel with a 1 second poll fallback (the SSE stream can be buffered by proxies).

```
GET  /state            # current studio state
POST /state            # merge a partial state, e.g. {"theme":"onion","gradAngle":245}
GET  /console          # the page's console ring buffer (no DevTools needed)
POST /ui/toast         # raise a toast: {"text":"...","kind":"info|success|error"}
GET  /api/pages        # the trending dataset the studio renders
```

Every control in the panel maps to a state field: `page`, `layout`, `theme`, `gradAngle`,
`titleMode`, `show.*`, `overlay.*`, `guides`.

![Themes and mirror mode](docs/themes.png)