Hero Studio as a verification gate: name the "window", add a verify checklist, real window content, equal margins, index-card preview

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 feature request

John Lauer · 2mo ago ·closed by Colby Knox

Filed by John (Adom) from a live posing session: I hit the registry hero gate on adom/adom-wiki-skillpack (an existing page that had just been transferred john -> adom), Hero Studio popped up as the required verification, and as a human I was genuinely confused about what it was and what to do. Studio itself is great. These are requests to make it work well specifically as a verification gate, plus one naming ask the whole team needs.

1. Give the "window" an official name (the anchor ask)

The floating app frame that bleeds off an edge and shows the app UI needs one canonical name, so the whole team stops calling it five different things ("the window", "the webview", "the screenshot", "the product shot", "the mock"). Please coin one word and put it on the UI control label + in the docs so we can all refer to it.

Candidates to react to (lead pick first): vitrine (a glass display case, which is literally what it is), cameo, pane / showpane, glass, porthole. Your call, we just need the word to exist.

2. Verification-mode UX (what to do next was not obvious)

When the studio opens as the required gate (vs open-ended exploration), it should hand-hold:

A short explainer at the top: what this screen is, and that a human has to click to satisfy the gate.
An obvious primary action. Today the action is "Generate hero PNG" buried at the very bottom of the left rail, below the "Image badges" section, off the fold. A human scrolling a long panel does not find it. It should be a prominent Verify / Approve / Generate button in the verification chrome.
Ideally a distinct "verification" mode vs the free "lab" mode, so the gate presentation is purpose-built.

3. Structured, per-item verification (not eyeball-the-whole-thing)

A checklist that verifies each important element on its own, each with its own confirm control:

Title
Sub-title (value-prop)
the "window" (the element from #1)
the page type: app, skill, component (hardware), bootstrap, scratchpad, etc. Confirm the hero matches the type and that the studio is in the right mode for it (my skillpack initially rendered in Component mode with a leftover PCB photo, because mode was wrong. A type check would have caught that.)

So the human ratifies each piece deliberately instead of approving a whole image at a glance.

4. Show the dynamic area by default

If the dynamic / marquee overlay band (the lower band the homepage marquee draws live stats + author over) is a real, shipping part of the ecosystem, show it populated by default in the preview, not just as a dashed "keep it calm" guide. Authors should see how the hero reads with the live overlay on top, since that is how it actually appears.

5. Real "window" content, so the mockup is truthful

Today the app/skill window is a pure CSS mock (fake sidebar rows + a bar chart). It reads as generic and, for a skill, a bit cheap. It should embed a real, representative screenshot:

For the adom-desktop bridge, put the actual AD UI in the window so it is a truthful mockup of the real thing, not a generic chart.
Per package generally: apps show their real UI, skills/components show something representative (a skill has no UI today, so it always gets the abstract mock, which is the weakest case).

This is the "put a good window in there" ask. A skill with no UI is the case that most needs a real-content option.

6. Put the medium index-card preview in the studio (by default)

The wiki index / landing grid renders a medium-sized view of the hero (the card), which is where a lot of first impressions happen. The studio should show that medium index-card rendering in its in-context previews, by default, alongside the full billboard and the homepage-marquee preview. (package.json already advertises "pixel-faithful ... index-card previews", so if it exists, just surface it by default in the verification view.)

7. Equal margins on all four sides

The safe-area margin should be equal along top / right / bottom / left. In the current render it is not: the left margin is visibly larger than the top margin (the ADOM wordmark sits farther in from the left edge than it does down from the top). Lock the inset to one value on all four sides so the content block is evenly framed. This is a consistent-margins rule, uneven insets read as amateur on a billboard.

Happy to pair on any of these. The naming one (#1) and the verify-flow one (#2/#3) are the ones that would have saved me the most confusion today.

3 Replies

Colby Knox · 2mo ago

Triage from the studio's builder. Owner mapping for the seven, plus your two DM unblocks.

Taking all of these studio-side, next version (0.6.0):

NAME: adopting your lead pick, vitrine. It goes on the UI control label, the state field, and the skill docs. Colby can veto the word; the slot for it now exists.
VERIFICATION MODE: when the studio is opened by the gate (the pose flow), it will present verification chrome: a top explainer saying what this screen is and that a human click satisfies the gate, and a prominent primary Generate control instead of the bottom-of-rail button. Lab mode stays as-is for free exploration.
PER-ITEM CHECKLIST: title, subtitle, vitrine, and page type each get their own confirm in verification mode, and the type check would have caught your component-mode PCB leftover. (The pose flow already forces the right mode server-side; the checklist makes the human ratification explicit.)
REAL VITRINE CONTENT: agreed this is the weakest spot, especially for skills. 0.6.0 adds screenshot import for the vitrine: drop in a real UI shot (AD gets the real AD UI) instead of the CSS mock. And generalized, this is also your re-stamp path with no server change needed: IMPORT your existing good hero into the studio, ratify it as the human, Generate, and the export is your hero with a legitimate provenance stamp. The gate's invariant is "a human made/approved this in the studio", and importing plus ratifying satisfies it honestly.
INDEX-CARD PREVIEW: the medium card grid preview exists (the /apps grid mock); it becomes default-visible in verification mode.
EQUAL MARGINS: real bug, fixing. One inset value on all four sides.
DYNAMIC BAND BY DEFAULT: partially overtaken by a decision Colby made last night: the PAGE now shows the hero image bare, no overlay band at all; the homepage marquee is the only surface that overlays live info, and it brings its own. So the hero preview will not show a band (that would be untruthful for the page), but the marquee in-context preview should and will render its overlay populated, since that is how the marquee actually reads.

Server-side (routed to the wiki thread, not this repo): a bless/re-stamp verb for existing pre-gate heroes, and the wider republish-gating scope decision. Your transfer case is the third confirmed instance of an existing page bricked on republish by the provenance check (hero-studio itself and adom-wiki-cli were the first two last night, both unbricked by remaking heroes in the studio). Until either the import path (0.6.0) or a server bless lands, that is the workaround: pose the page in the studio with a human present and Generate.

Colby Knox · 2mo ago

Shipped in adom/hero-studio 0.6.0, live on the wiki now:

The window is officially the VITRINE. On the panel label, in the state, in the skill.
Verification mode: when the pose gate opens the studio, you get chrome above the hero: an explainer of what the screen is, and a prominent Generate that lives in the verification block instead of the bottom of the rail.
Per-item checklist: title, subtitle, vitrine, and a page-type/mode match check, each with its own confirm. Generate unlocks only when all four are checked. The type row names both the page type and the studio mode and flags a mismatch in place, which would have caught your component-mode PCB leftover.
Real vitrine content: the Vitrine content section imports a real screenshot in place of the CSS mock. Full-hero import is the ratification path for an existing image: import, confirm the checklist, Generate, and the export is your image with a legitimate provenance stamp (type pill and slug bake on top).
The index-card grid preview renders in the in-context strip alongside the marquee.
Margins are now one inset on all four sides for the text block, with a single tighter inset for the corner badges.

4 resolved differently, per Colby's page-bare decision: the page renders no band over the hero, so the hero preview shows none; the marquee mock is where overlay truthfulness lives.

Separately, your actual blocker is ALREADY GONE without any of this: the republish rejection was a wiki-side gate scoping bug, fixed on prod the same night. Your page is grandfathered (pre-cutover creation survives the transfer) and its manifest matches the page hero path, so a plain retry of the publish that failed passes as-is: no manifest edits, no studio session, your good hero intact. The import path above is only for the day you deliberately CHANGE a hero and want to keep or rework existing art through the gate.

Colby Knox · 2mo ago

Closing: shipped through 0.6.0, 0.6.1, and 0.7.0 (all live on the wiki).

Vitrine is the word, on the labels and in the skill. 2. Verification mode with explainer and a prominent Generate (0.6.1 fixed a display bug that kept the 0.6.0 chrome invisible). 3. Per-item checklist incl. the page-type/mode match. 5. Real vitrine content, now DEFAULT: the pose flow auto-pulls a representative screenshot from the package's wiki page (screenshots/ then docs/), with a re-pull button and manual import; full-hero import is the human ratification path for existing art. 6. Index-card preview in the context strip. 7. One safe-area inset on all four sides.

4 was superseded by Colby's page-bare decision: the page renders no band over the hero, so the hero preview shows none; the marquee mock is where overlay truthfulness lives.

Your transfer block itself died separately: the gate scoping bug is fixed on prod and your page is grandfathered, so the failed publish passes on plain retry, good hero intact.