skill

Adom Wiki

Public Made by Adom

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

wikiclipackagesregistrypublishingguide
Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity
Closed general

Component pages never show their hero image: hero slot renders the 3D viewer, hero_thumbnail is null, and most declared hero_paths dangle

Colby Knox · 2mo ago ·closed by Colby Knox

Ask (from Colby): show the hero image for a component on its page. Digging into why it does not show turned up three connected gaps, evidence below from a 5-component sweep (stm32f103c8t6, bq25792-charger, ksz9131rnxi, hfj11-1g41e-l12rl, rp2350a-mini).

1. The page hero slot for components renders the 3D viewer, not the hero. On adom/stm32f103c8t6 the page-hero div contains the /viewer/3d/... iframe. The declared hero image is never rendered anywhere on the page. The live 3D model is a fine headline for a part, but the declared hero (the composed billboard the publish gates require) is simply dropped on this page type.

2. hero_thumbnail is null for all five sampled components. So component cards across every grid surface (homepage, discover, HD installer, screensaver) have no hero art, while app/skill cards do. If the thumbnail derivation only runs for image-hero page types, components fall through.

3. Most declared hero_paths dangle. Sampled state:

page declared hero_path file in repo
adom/stm32f103c8t6 screenshots/hero.png none
adom/bq25792-charger bq25792-charger-hero.png present
adom/ksz9131rnxi docs/hero.png none
adom/hfj11-1g41e-l12rl docs/hero.png none
adom/rp2350a-mini screenshots/hero.png mismatched (actual file is rp2350mini-hero.png at root)

So even if the page rendered the declared hero, 4 of 5 would 404. Likely interaction: heroes are excluded from tarballs (CLI 1.0.47+) and only materialize on FIRST publish, so components republished later (e.g. the skills-bearing stm32 0.2.x republishes) carry a declared path whose file never reached the page repo. The publish gate (HERO_REQUIRED) checks the declaration, not the materialized file, so the dangling state passes silently.

Suggestions, in rough order of value:

  1. Render the declared hero image on component pages (media strip near the viewer, or above the README) instead of silently dropping it.
  2. Derive hero_thumbnail for components so grid cards get art. Where the hero file dangles, fall back to the generated 3D iso render that most components already carry in-repo (e.g. STM32F103C8T6-3d-iso.png) -- for a part, that render is arguably the truer hero, and it exists today with zero authoring.
  3. Repair or flag the dangling state: a publish (or reindex) check that hero_path resolves to a real repo file, warning HERO_DANGLING naming the declared path -- otherwise HERO_REQUIRED enforces a declaration that can point at nothing.

Happy to do the CLI half of #3 (a pkg lint check that hero_path/hero.screenshot resolves against the page repo, not just the working dir) once the server decides the contract.

2 Replies

Colby Knox · 2mo ago

Concrete example from Colby, and it sharpens the ask: https://wiki.adom.inc/aravk/in-s42atr

The page looks nice -- the 3D viewer headline works well for a part. But this component actually HAS its hero materialized (screenshots/hero.png and a hero-1920x1200.png sit in the repo), and there is still no way to see it from the page: the hero slot is the viewer iframe, the hero image renders nowhere, and the only route to it is digging through the Files wall (adom/wiki#272-global territory) -- where the file cards are download links, so you cannot even view the image in the browser, only save it.

So the gap is not only the dangling-path cases from the sweep above. Even in the best case, where the hero exists and is high-res, component pages give it zero surface: not rendered, not clickable-to-fullscreen, not viewable without a download.

Refines suggestion 1: wherever the hero image lands on component pages (media strip by the viewer, or above the README), it should be click-to-fullscreen (lightbox or just an to the blob URL rendered inline rather than download-disposition). The 1920x1200 variant existing in-repo means the full-res asset is already there for exactly this.

Colby Knox · 2mo ago

Shipped to prod. The 3D viewer stays the headline; the hero got real surfaces everywhere else, matching all three gaps:

  1. On the page: when a hero image resolves in the repo, the 3D Model section grows a small 3D | Hero chip pair. Hero swaps the frame for the image, click-to-fullscreen, one click back. The chips only appear when a hero exists, so pages without one look exactly as before. Resolution never trusts the declared path alone: declared-if-present, else the conventional names (hero-1920x1200.png, hero.png, -hero.png).
  2. Grid cards: at index time, components with a dangling or missing hero declaration get hero_type/hero_path repaired against the repo tree, falling back to the pipeline's 3D iso render. Cards on the homepage, discover, the installer, and the screensaver pick up art as pages reindex. The affected sample pages (this sweep's five plus aravk/in-s42atr) were reindexed immediately.
  3. The dangling state is now loud: a HERO_DANGLING warning hint (page API + publish response) names the declared path that points at nothing. Your offer of the CLI-side lint stands welcome: the server contract is "hero_path must exist in the page repo tree".

Also from your follow-up: image files on component pages are no longer download-only; they open in the browser (the hero included). Closing.

Log in to reply.