---
name: pup-hero-image
description: DEV skill (source-only, never shipped in the pkg) - how to rebuild, tweak, and publish pup's wiki hero image. The full recipe: the parameterized build script, the design constants matched to Bridge's hero, the hero-studio human-generate gate, and every trap that bit us (gitignore whitelist, stale studio slugs, overlay defaults, other threads' studios).
---

# pup's hero image: build, tweak, publish

The pup wiki hero ([adom/pup-bridge](https://wiki.adom.inc/adom/pup-bridge)) is a fully **baked PNG**
built by `build_hero.py` in this folder, then run through hero-studio's human Generate gate for
provenance, then applied to the page. It is NOT drawn live by hero-studio: in full-hero mode the
studio contributes nothing but the provenance stamp.

## Design spec (matched to Bridge's hero, measured not guessed)

Canvas 2000x1250 (16:10), 1cqw = 20px.

| Element | Spec |
|---|---|
| Background | #0d1117 with a soft teal glow ellipse upper-right (blur 240) |
| ADOM logo | white, 11.8cqw wide, at (4.5cqw, 3.2cqw) |
| Title "Pup" | Familjen 700, **12cqw (240px em)** - same as Bridge's and kicad's heroes |
| Subtitle | Satoshi 500 50px, "A real browser **sandbox** you fully control." - sandbox in #4aa8ff |
| BRIDGE pill | solid teal #00cec2, dark text #091418, Familjen 700, top-right inset 2.6cqw (52px) |
| Vitrine | vy=140, VH=1050, width 1062, **right edge = pill right edge (W-52)**, rounded R=22, shadow blur 30 at +10/+16 |
| Vitrine chrome | real captured Chrome titlebar strip (`assets/win_slot3.png`) |
| Vitrine content | a FRESH `pup_screenshot_full_res` of a good wiki page, cover-fit, bottom 10% faded |
| Taskbar band | 68px, 5 badged pup tiles LEFT-aligned (no start orb), active tile underlined #78c8ff |
| Jump-list | Win11-style flyout above the active tile: RECENT (3 rows, first highlighted) + TASKS ("New pup window"), teal favicons |

The vitrine-pill right-edge alignment is deliberate (John 2026-08-09: "vitrine is a bit too far to
the right and doesn't quite line up with the pill"). If you move the pill inset, the vitrine
follows automatically (`vx = (W - pill_inset) - vw`).

## Rebuild

```bash
# 1. fresh content screenshot (do NOT reuse a stale one - the wiki UI changes)
adom-bridge-cli --target <box> --ai-thread "<you>" pup_open_window '{"sessionId":"hero-shot","profile":"hero-shot","url":"https://wiki.adom.inc/adom/alex-nameplate"}'
adom-bridge-cli --target <box> --ai-thread "<you>" pup_screenshot_full_res '{"sessionId":"hero-shot"}'

# 2. build
python3 dev-skills/pup-hero-image/build_hero.py --content <that.png> --out /tmp/hero_new.png
```

Assets (fonts, logo, chrome strip, taskbar tiles, badges) live in `assets/` right here, so the
build is reproducible from a bare clone. The fonts were converted from hero-studio's woff2.

## The human Generate gate (provenance)

The registry wants a provenance-stamped hero. The stamp comes ONLY from a human clicking
**Generate** in hero-studio - do not fake it, do not skip it.

```bash
HERO_STUDIO_PORT=<free port> hero-studio            # START YOUR OWN - never take another thread's studio
HERO_STUDIO_PORT=<port> hero-studio vitrine --file /tmp/hero_new.png --full --chrome none
HERO_STUDIO_PORT=<port> hero-studio set slug=pup-bridge page=adom/pup-bridge overlay.pill=false overlay.slug=false overlay.author=false
```

Open `https://<container-slug>.adom.cloud/proxy/<port>/` in a pup tab for John, flash the taskbar
(never foreground), and let him review. The gate is his APPROVAL, not his mouse: once he says go
("generate it", "can you do that"), you may click the Generate button yourself via pup_eval on the
studio tab. Never click it without his explicit go-ahead. Then fetch
`http://localhost:<port>/generated/<file from /state _gen>` - that PNG is the final.

## Apply to the live page

```bash
cp <generated.png> hero-v9.png
adom-wiki repo push --files hero-v9.png -m "<real changelog>" adom/pup-bridge
```

Verify live bytes match (`adom-wiki page hero adom/pup-bridge --json` reports bytes), then refresh
the live page in a pup window with a cache-bust (`?v=<something new>`) and flash - standing rule,
never just say "published".

## Traps (every one of these bit us)

- **`.gitignore` whitelists heroes**: `*.png` is ignored; only `!hero-vN.png` entries push. A new
  filename needs its own whitelist line FIRST or `repo push` silently skips it (commit: null).
- **`adom-wiki page hero --image` is broken** (looks for screenshots/hero.png) - overwrite the
  tracked whitelisted hero file instead. That's why the file is still named `hero-v9.png`.
- **hero-studio defaults `overlay.slug=true`** on a fresh port - turn off pill AND slug AND author
  or the export gets a baked slug in the dynamic marquee band (hero-studio#29).
- **The studio package dropdown may list pup under the OLD slug** (`adom/adom-desktop-puppeteer-bridge`,
  hero-studio issue: renamed pages keep stale option values). If `set page=` won't bind, select the
  option in the DOM via pup_eval. The EXPORT slug follows `set slug=pup-bridge` regardless.
- **Never take over another thread's hero-studio port** - John's other build threads run their own
  studios. `hero-studio state` on an existing port tells you whose it is; start a fresh port.
- **The studio RE-RENDERS your import on Generate**: the exported PNG differs from your input by
  ~2% of pixels (canvas anti-aliasing), spread across the image. Verify the generated file by
  LOOKING at it; naive pixel probes give false readings on it (a threshold edge-detector measured
  the vitrine 28px off on the export while the image was actually correct).
- **Generated filename may carry the old slug** (from the dropdown's stale value) - harmless, the
  image is what ships, but check the composed image, not the filename.
- The full build history and the measured Bridge-hero constants came from the 2026-08-08/09 session;
  if Bridge's hero is redesigned, re-measure (title glyph block, logo width, pill inset) before
  changing the constants here.
