Full-import: Generate re-renders the PNG (never byte-identical), no headless compose endpoint, CLI help masked while a server runs

by adom

The hero-image lab with a human gate: `hero-studio pose <owner/slug>` opens the studio in front of the human, posed for their package, and blocks until they click Generate, producing the provenance-stamped 2000x1250 PNG the registry's hero gate requires. The image carries the title and artwork; the exported image also bakes the type pill (top right) and full wiki slug (bottom right); the page shows the hero bare, and only the homepage marquee overlays its own dynamic info. Every hero wears its P

Overview Files Skills Discover Packages Releases Dependencies Issues3 Breadcrumbs Pull Requests Activity

Closed general

John Lauer · 2mo ago ·closed by Colby Knox

Three remaining frictions from shipping the pup hero via the full-import path (2026-08-09), complementing #32's papercuts, #30 (stale dropdown slugs), #29 (slug band), and #26 (instance sprawl).

1. Generate RE-RENDERS a full-hero import; export should be byte-identical passthrough + stamp

In full-hero mode the studio's contribution is the provenance stamp, but the exported PNG is a canvas re-render of the import: measured on the pup hero, ~2.2% of pixels differ from the input (anti-aliasing level, spread across the whole image, diff bbox nearly the full canvas).

Costs:

The driving agent cannot verify the export by comparison: byte/hash checks fail by design, and even geometry probes misfire (a threshold edge-detector read the vitrine's right edge 28px off on the export while the image was visually correct). The only reliable check is a human-style LOOK.
Repeated regenerate cycles accumulate double resampling (author render, then studio render).

Ask: for full-hero imports, embed the imported PNG untouched (plus the provenance tEXt/stamp), or at minimum expose the exact composed bitmap pre-encode so agents can verify equality.

2. No headless compose/preview endpoint

/preview.png, /hero.png, /render, /compose.png, /vitrine.png all 404; the composed hero exists only inside the browser canvas. Verifying what will ship (and clicking Generate once the human approves) requires driving a real browser tab via pup. A GET /compose.png (current composed state, no provenance) would let an agent verify staging without a browser, and would have caught the #29 slug and #32 double-pill classes without costing review round-trips.

3. CLI: the "server already running" guard masks nearly every subcommand, including help

With any studio process alive, hero-studio --help, hero-studio help, and several subcommands print only "a server is already running on :PORT" and exit. Help should always print; verb dispatch should route to the running server (or honor HERO_STUDIO_PORT consistently; set and vitrine do, the rest don't). Related to #32 point 10's hero-studio list ask, but distinct: this is about unreachable help/dispatch, not sprawl.

Context: the pup hero shipped fine through this path (aligned vitrine + trimmed chrome residue, human-approved Generate). The full pup-side recipe incl. workarounds is written down in adom/pup-bridge dev-skills/pup-hero-image/.

1 Reply

Colby Knox · 2mo ago

All three shipped in 0.16.0/0.16.1:

Passthrough export: a full-hero import with every overlay off (the default since #32: full-import auto-disables them) never touches a browser. The imported PNG is decoded and stamped directly (provenance renderer: "passthrough"). A contract-sized 2000x1250 import keeps IDENTICAL pixels: verified by ImageChops.difference bbox None against the source; only the provenance tEXt differs. Non-2000px imports get one LANCZOS normalize to the registry standard (that resize is the contract, not a re-render). Agents can now verify exports by decoded-pixel comparison.
GET /compose.png: headless compose of the CURRENT pose, no provenance stamp, never publishable; also wrapped as hero-studio compose out.png. It would have caught the #29 slug band and the #32 double pill without a review round-trip, which is exactly what I used it for while building this release.
Help unmasked: hero-studio --help / -h / help print full usage and exit 0 with zero side effects (it previously fell through to the server launcher). All drive verbs consistently honor --port and HERO_STUDIO_PORT.