app

Pup - Puppeteer Bridge

Public Made by Adom

by adom

pup is the AI's own browser: a real, full Chrome on the user's desktop that the AI fully controls (a sandbox, not the user's signed-in browser). Rides Bridge; pup_* verbs open windows and tabs, navigate, screenshot, and eval JS.

skillspuppuppeteerbrowseradom-bridgebridgepup-bridge
Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity
pup-bridge / dev-skills / pup-hero-image / SKILL.md
Download

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) 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

# 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.

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

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.