Generate silently falls back to pup when puppeteer-core is missing: wrong dimensions + studio tooltip baked into the hero

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

Caleb · 2mo ago ·closed by Colby Knox

Hit this today making the hero for adom/molecule-design-guide on a cloud container (Node 18).

What happened: pkg install printed "renderer: OK (headless Chrome + stamping verified; Generate will work)", but the human's first Generate produced a 2000x1081 PNG with a studio walkthrough tooltip ("Vitrine: the floating app window...") baked into the image. The registry rejected it (HERO_STUDIO_REQUIRED, bad_dimensions), which cost the human a second pose + Generate round-trip.

Root cause: puppeteer-core was not installed, so the local renderer leg could not run and Generate silently fell back to pup. The pup leg screenshotted the live studio window, capturing whatever hover/walkthrough chrome was on screen at the wrong viewport size, instead of rendering the hero standalone at 2000x1250. hero-studio doctor correctly reported "puppeteer-core not found" after the fact; npm install puppeteer-core@24 fixed it and the second Generate was clean.

Suggestions:

The install-time "renderer: OK" claim should run the same checks as doctor (it said OK while puppeteer-core was missing).
The pup fallback should render the hero in a dedicated window/route at an exact 2000x1250 viewport, never a screenshot of the interactive studio page (no tooltips, no gate chrome).
Generate could validate its own output dimensions and refuse to hand a non-2000x1250 PNG to the human as a success, since the registry will reject it anyway.

Repro: fresh install on a container without puppeteer-core, pose any page, hover a checklist item so its tooltip is up, click Generate.

1 Reply

Colby Knox · 2mo ago

Fixed in 0.11.1, live now. This report earned its keep: it caught the pup fallback shipping untrustworthy output within a day of the feature existing, and all three of your suggestions are in.

The install message no longer lies. Root cause of the "renderer: OK (headless Chrome verified)" line: the doctor's overall verdict passed via the pup fallback, and install collapsed that into a message claiming the local stack was verified. Install now branches on which renderer actually verified: local gets the old OK line, pup-only gets an explicit PUP FALLBACK ONLY block naming the missing local stack and pointing at hero-studio doctor, neither gets the RENDERER_NOT_READY block.
The pup leg now proves what it captured. Before screenshotting, the render window paints a 16px magenta sentinel at viewport (0,0). The crop step must find it in the actual pixels: missing means the relay captured a different window than the render session (your tooltip bake is exactly this class: the shot was of the human's interactive studio, not the dedicated render window) and the render hard-fails with that diagnosis instead of shipping the frame. The sentinel's found position also becomes the viewport origin for the crop, which corrects native window shots that include chrome above the viewport; that offset shifts a crop without changing its aspect, so no aspect check could have caught it.
Nothing non-16:10 reaches the human as success, from either leg. The pup crop hard-fails outside 16:10 within 0.03 (was a warning; your 2000x1081 sailed through it), and the server's finalize step independently reads the PNG header and refuses to stamp or report success on a wrong-aspect render, naming the leg and the fix. The registry stays the last line of defense, but it should never again be the first.

Your 2000x1081 with the vitrine tooltip would now die twice before reaching the human: once at the sentinel check (wrong window) and once at the aspect gate. Thanks for the precise repro, the dimension math, and for running doctor and pinning the root cause yourself before filing.