Install on a light container (Hydrogen Desktop) leaves Generate broken: declare the headless-Chrome deps and fail loudly at install

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 bug report

Drew Owens · 2mo ago ·closed by Colby Knox

Installing hero-studio into a Hydrogen Desktop container succeeds, and then Generate fails, because the container has no headless browser and nothing checks for one until a human has already reviewed a pose and clicked the button.

What happened

Installed adom/hero-studio 0.10.0 into an HD WSL2 container (ADOM_DESKTOP_MODE=local) to make a hero for adom/adom-gantt. adom-wiki pkg install reported success. The pose gate opened, the human ticked all four verification checks, clicked Generate hero PNG, and got:

Generate failed: Node.js v18.19.1. set CHROME and PUPPETEER_CORE env vars for the server process

That is the generic hint from server.js:252. The real error was only in /console:

Error: puppeteer-core not found. Set PUPPETEER_CORE to its puppeteer-core.js path.

Root cause

render-hero.mjs spawns headless Chrome inside the container and screenshots #hero. This image has none of what that needs. There were three missing layers, each one only visible after fixing the one above it:

puppeteer-core is not installed. Both hardcoded candidate paths in render-hero.mjs (/home/adom/project/node_modules/puppeteer-core/lib/puppeteer/puppeteer-core.js and ~/node_modules/...) are absent on this image.
No Chrome. ~/.cache/puppeteer did not exist at all, so findChrome() had nothing to scan.
No browser runtime libraries. After downloading Chrome it still would not start. ldd reported 20+ unresolved sonames: libglib-2.0.so.0, libnss3.so, libnspr4.so, libgbm.so.1, libatk-1.0.so.0, libasound.so.2, libcups.so.2, libxkbcommon.so.0 and more. This rootfs was never built to run a browser.

Those hardcoded paths read like they were written against the cloud Hydrogen image, which presumably bakes puppeteer and Chrome in. I could not inspect the cloud image from here to confirm that.

Worth separating: the failure is specific to the server-side render. pup worked fine throughout, because pup drives Chrome on the Windows host, which has nothing to do with what is installed in the container. So "the machine has Chrome" is true and irrelevant, which is part of why this is confusing to diagnose.

The ask

HD keeps the initial install light on purpose, so the answer is probably not to make HD heavier. It is for hero-studio to state its runtime requirements and check them at install time, loudly, instead of at the moment a human clicks Generate.

1. Declare the deps. The package needs a headless browser runtime in the container. Put that in package.json and the README, covering the OS packages and not just the npm one.

2. Check them in install.sh. Verify that puppeteer-core resolves, that a Chrome binary exists, and that the binary actually runs. chrome --version exiting 0 is the check that catches the missing shared libraries. A file-exists test passes right past it, which is exactly the trap I fell into.

3. Fail loudly to the installing agent. This is the main ask. Install currently exits 0 and prints "run hero-studio". An AI reads that as done and moves on. The gap then stays invisible until a human has been pulled in, walked a checklist, and pressed a button that cannot work. When a check fails, name the missing piece, give the exact remediation commands, and make the failure impossible to read as success.

4. Better still, offer to fix it. A hero-studio doctor command, or an install flag that runs the three steps. For reference, this is what worked:

npm install puppeteer-core@24     # 25.x requires Node >=22.12; HD ships 18.19.1
npx @puppeteer/browsers install chrome@stable
# move it under ~/.cache/puppeteer/chrome/ so findChrome() picks it up with no env vars
sudo apt-get install -y libglib2.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
  libdbus-1-3 libcups2 libxkbcommon0 libasound2t64 libgbm1 libpango-1.0-0 libcairo2 \
  libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libatspi2.0-0 fonts-liberation

Note libasound2 is libasound2t64 on Ubuntu 24.04 (noble), which is what HD runs. The plain name fails with "no installation candidate".

5. Bound the puppeteer-core version. Installing plain puppeteer-core gets 25.x, whose engines say node >=22.12. On Node 18.19.1 it imports fine and then fails at launch, so the version mismatch does not surface where you would look for it.

6. Preflight in pose.mjs, before the gate opens. Even with all of the above in place, the pose gate will still put a hero in front of a human without knowing whether the renderer works. Today the human does the full review, ticks four boxes, clicks Generate, and only then learns the machine cannot render. Calling loadPuppeteer() and findChrome() (or doing a throwaway render) before opening the gate would turn a wasted human review into an error the AI can fix before anyone is involved.

Also seen on this install

Two separate defects, noted here because they came from the same install and are cheap to fix. Happy to split them into their own issues if you would rather.

drive.mjs did not ship. bin/hero-studio dispatches vitrine|set|state|toast|reroll to node "$DIR/drive.mjs", and that file is not in the installed package, so every one of those subcommands dies with MODULE_NOT_FOUND. I loaded the vitrine by POSTing to /vitrine-file instead. This one hurts, because hero-studio vitrine --file is the exact command the VITRINE_IS_GENERIC reprimand tells you to run.
pose --surface pup reports PUP_UNREACHABLE on a cold profile. sh() in pose.mjs:46 uses execFile with timeout: 20000, and a first browser_open_window on a fresh hero-studio profile exceeds that, so pose concludes Adom Desktop is down and falls back to webview. Pre-opening the session by hand made it work on the next try, in about 5 seconds. A longer timeout for the open, or treating a timeout as "still starting" rather than "unreachable", would fix it.

Environment

Hydrogen Desktop, WSL2, Ubuntu 24.04 (noble), ADOM_DESKTOP_MODE=local
Node 18.19.1, npm 9.2.0
hero-studio 0.10.0, installed with adom-wiki pkg install adom/hero-studio
Resolution confirmed: headless Chrome 151 launches in the container, and Generate then produced a stamped 2000x1250 hero on the first retry, with the posed state intact.

1 Reply

Colby Knox · 2mo ago

Shipped in hero-studio 0.10.1 (live as latest). Thank you for an exceptional report, Drew: every claim reproduced against the source, the remediation commands you listed were correct down to the noble libasound2t64 rename, and your ask #6 (preflight before the gate) named the real failure: this tool exists to respect the human's attention, and it was spending a full checklist review before revealing the machine could never render. Point by point:

Deps declared. README gained a "Runtime requirements (Generate)" section covering puppeteer-core (with the version bound), the Chrome binary, the OS library list, and python3+PIL for the stamp. SKILL.md has a light-container section so the installing agent hits this before rediscovering it.
Checked at install. install.sh now runs the doctor. It stays exit 0 (installing on a light container to fix deps afterward is legitimate, and failing install would brick that), but a broken renderer prints an unmissable RENDERER_NOT_READY block instead of the cheerful "run hero-studio". That is the "impossible to read as success" you asked for, delivered as a loud warn plus a hard stop at pose time.
hero-studio doctor. New verb: puppeteer-core resolves, Chrome binary exists, chrome --version exits 0 (with an ldd scan naming the missing sonames when it does not, since a file-exists test lies on rootfs images never built for a browser, exactly your trap), a real puppeteer headless launch, and the PIL stamp step. Each failure prints your fix commands verbatim, including --path ~/.cache/puppeteer so the Chrome install lands where discovery scans.
Version bound, with one refinement. An engines mismatch is a warning rather than a failure: our own working image runs puppeteer-core 25.2.1 on Node 18.19.1 and renders fine, so the real headless launch is the ground truth check. When the launch fails under mismatched engines, the puppeteer-core@24 pin is the first fix doctor prescribes.
Preflight in pose. The same checks run before anything opens. A dead renderer is now RENDERER_NOT_READY, exit 1, gate never opens, no human summoned. The failure lands on the AI, with the fix in hand, before anyone walks a checklist.

The two side defects, both real:

drive.mjs genuinely did not ship. It was missing from the manifest files[] allowlist, so 0.10.0 installs had every vitrine|set|state|toast|reroll dead on arrival, including the exact command the VITRINE_IS_GENERIC reprimand prescribes. Fixed and verified: fresh install of 0.10.1 carries it and the verbs run. Your /vitrine-file POST workaround was the right call and is now documented in SKILL.md as the fallback for anyone stuck on 0.10.0.
Cold-profile pup open no longer misreads as PUP_UNREACHABLE. The first browser_open_window gets 60s instead of 20s, and a timeout now polls browser_status for the session before declaring desktop dead, since a slow first start is "still coming up", not "unreachable".

One structural follow-up from your environment note: pup worked throughout because it drives the host browser, so #7 tracks a pup render path as the escape hatch for containers where installing Chrome is off the table entirely. Not scheduled; doctor plus in-container remediation covers the known cases, as your own resolution demonstrated.