Adom Wiki Skill Pack

@@ -0,0 +1,198 @@+---+name: wiki-hero-glb+description: >-+  What the Adom Wiki's 3D viewer reads from a GLB, in one page: declared layers+  (extras.adomLayer: key, label, group, hidden, the built-in PCB vocabulary,+  the nearest-declaring-ancestor rule, the two-layer minimum), the intro+  preview of a hidden layer (extras.adomLayer.intro), hover tooltips+  (extras.tooltip and the tooltips policy), switchable groups and lights inside+  the GLB (extras.adomRole / Adom.* nodes, KHR_lights_punctual, the light+  budget), animation (which groups autoplay, component.viewer_3d repeat / loop /+  animate / ground / shadows / tooltips / camera and the ?repeat= ?loop=+  ?animate= ?ground= query knobs, the Replay button), which glTF extensions+  the viewer honours, materials for translucent artwork (alphaMode BLEND,+  doubleSided), quantization, Draco, GPU instancing (refused), node naming+  that survives step2glb, and how the page picks the model it shows. Read+  before authoring a hero GLB, a field-of-view cone, an LED that lights, a+  laser-etch overlay, or any GLB whose parts should be switchable or+  introduced. Trigger words: hero GLB, hero glb, adomLayer, layer intro,+  fade in the layer, highlight the toggle, field of view cone, extras.tooltip,+  adomRole, Adom.LED.State, KHR_lights_punctual, viewer_3d, repeat loop+  animate ground, replay animation, KHR_animation_pointer, alphaMode BLEND,+  doubleSided, Draco, gpu instancing warning, what does the wiki viewer read+  from a glb, glb authoring, 3D | Hero toggle.+---+Parent skill: **adom-wiki-skillpack**++# The hero GLB: what the wiki's 3D viewer reads++The 3D slot on a component page is adom/adom-3d-viewer (Babylon 9). Everything+it understands beyond geometry is declared INSIDE the GLB, in glTF `extras` and+node names, plus a few per-page defaults in page.json. This page is the+contract, collected from adom/wiki#35, #48, #55, #57, #95, #162 and+adom/adom-3d-viewer#7, #8. Working examples: adom/vl53l5cx, vl53l7cx, vl53l8cx+(`<slug>-hero.glb`: six declared layers, a hidden field-of-view cone with an+intro, a 24 s yaw animation) and the tooling that made them (`pipeline/` on+adom/vl53l5cx: `hero_step.py`, `glb_alpha.py`).++## Layers: `extras.adomLayer`++```json+{ "name": "Adom.FOV",+  "extras": { "adomLayer": { "key": "fov", "label": "Field of view", "group": "Optics", "hidden": true } } }+```++| Field | Required | Meaning |+|---|---|---|+| `key` | yes | Stable id (1 to 64 chars); what `setLayerVisible(key, ...)` takes. |+| `label` | no | Panel text; defaults to the key with each `_` shown as a space. |+| `group` | no | Section heading in the panel; layers sharing a group list together. |+| `hidden` | no | `true` starts the layer switched off. |+| `intro` | no | Introduce a hidden layer once after load (below). |++Rules that matter:++- Declare on the mesh OR an ancestor node. Babylon splits multi-material+  primitives into child meshes, so the group node that owns them is usually+  the right place. The NEAREST declaration wins per mesh: an ancestor covers+  its subtree except where a descendant declares its own, so a declared group+  and finer declarations under it compose (adom/wiki#162).+- A declared layer wins over the built-in name vocabulary at the same node.+- The built-in vocabulary, matched on node names (`silk`, `silk_top`,+  `silk_bottom`, `pad_top`, `pad_bottom`, `solder_top`, `solder_bottom`,+  `paste_top`, `paste_bottom`, `fr4_board`, `barrel`, `pin1_marker`; a name+  equal to the key or starting with `key_` / `key.`), is DATA in the same+  shape you can declare; solder and paste start hidden. Declared layers list+  after the built-in ones, in file order.+- Fewer than two layers means no panel; a DECLARED layer always surfaces,+  even alone (a lone name-matched one does not).+- Panel state is not persisted per layer; `hidden` is the resting state on+  every load.++## Intro preview of a hidden layer: `extras.adomLayer.intro`++```json+"intro": { "fadeInAt": 1.5, "fadeOutAt": 6.5, "highlightButton": true, "fadeMs": 700 }+```++After the model loads the layer fades in at `fadeInAt` seconds, holds, and+fades out from `fadeOutAt` (always at least 0.5 s later); while it shows, its+toggle in the Layers panel reads as pressed and pulses, so the reader learns+the switch exists. Afterwards the layer rests hidden and the toggle rests off.+Honoured only on a `hidden: true` layer. The fade is mesh visibility, so any+material works, translucent cones included. A click on the toggle during the+intro keeps the layer on. The panel gains a "Replay intro" button, the page's+Replay button replays it too, and `?animate=0` (or `viewer_3d.animate: false`)+holds it off with the rest of the motion. Viewer API: `getIntros()`,+`replayIntros()`, `stopIntros()`. Needs viewer 0.9.0 (wiki bundle 20260921a).++## Hover tooltips: `extras.tooltip`++`"extras": { "tooltip": "Solder ball\nDia 0.30 mm" }` on a mesh or a node up to+five levels above it; `\n` breaks lines. Without it the mesh name is the+fallback, run through the layer-label table, and auto-generated names+(`mesh_*`, `node_*`, `*_primitive3`, `__root__`) show nothing. A manufacturer+GLB full of CAD names (`BODY-SON`) is tamed per page with+`component.viewer_3d.tooltips`: `all` (default), `authored` (only+extras.tooltip), `off`; `?tooltips=` overrides per embed.++There is no pin cross-highlight contract in the GLB today: hovering a symbol+pin does not light a mesh. Name pads and leads descriptively (`pad_1`,+`lead_1`) so a future contract can key on them, but do not expect it yet.++## Switchable groups and lights inside the GLB++A node named `Adom.<Something>` or carrying `extras.adomRole` becomes a+switchable group in the panel's "Parts" section: `Adom.LED.State` holding an+emissive lens mesh and a `KHR_lights_punctual` light switches both together;+`Adom.LaserEtch.MPN` toggles the etched part number. The OUTERMOST declaring+node wins (children ride with it); `extras.defaultEnabled: false` starts a+group off; one row per role, every placement behind it (a board with eight of+the same LED gets one row, with per-placement control on the API).++Lights come in as authored (candela, metres, position from the parent+matrix) with no per-light shadows, under a budget of the nearest and+brightest 4 per view (`setLightBudget`). A light under a scaled node is called+out in the console, never rescaled: put lights under unscaled nodes. Emissive+skins keep glowing when the budget drops a light. Full detail:+adom/adom-3d-viewer#7 and the viewer's docs/CONTENT-CONVENTIONS.md.++## Animation++Every glTF animation group autoplays. The platform default is land-once:+play through once and hold the final frame (the assembled state). Per page in+page.json, and per embed by query, precedence query > page > default:++| page.json `component.viewer_3d` | query | meaning |+|---|---|---|+| `"repeat": 0..10` | `?repeat=N` | play N times then hold; 0 = loop forever |+| `"loop": true/false` | `?loop=1/0` | shorthand for repeat 0 / repeat 1 |+| `"animate": false` | `?animate=0` | hold the first frame; also holds layer intros |+| `"ground": false` | `?ground=0` | hide the ground plane |+| `"shadows": false` | `?shadows=0` | no cast shadows (a moving cast shadow pulls focus) |+| `"tooltips": "authored" / "off"` | `?tooltips=` | hover-label policy, above |+| `"camera": { "alpha", "beta", "radiusScale" }` | `?camera=a,b[,r]` | opening view in radians |++Keys the sanitizer does not know are ignored with a publish hint. A GLB with+animation groups (or a layer intro) shows a Replay button under the viewer.+A looping hero yaw (the VL53Lx `adom-hero-intro`, plus or minus 6 degrees, 24+s) reads well with `"repeat": 0` on that page.++Extensions the loader honours: `KHR_lights_punctual`, `KHR_materials_*`+(transmission, clearcoat, sheen, ior, volume, emissive_strength, ...),+`KHR_texture_transform`, `KHR_mesh_quantization`, `KHR_draco_mesh_compression`+(the decoder is vendored), `KHR_animation_pointer` (Babylon's loader supports+it, so a material `baseColorFactor` fade can be authored as animation; the+layer `intro` is still the way to fade a LAYER, because only the viewer can+highlight the toggle). `EXT_mesh_gpu_instancing` is REFUSED with a console+warning (mis-renders under the Z-up transform): build with+`gltf-transform optimize --instance false`.++## Materials and geometry++- Translucent artwork (a field-of-view cone, a glass lens): `alphaMode:+  "BLEND"`, `doubleSided: true`, a `baseColorFactor` alpha around 0.3 to 0.5.+  The wiki renders with alpha sorting; keep translucent parts few.+- Coplanar decals (silkscreen, pad labels) get z-fighting mitigation from the+  viewer, but lift them by a few micrometres anyway.+- Quantize (`KHR_mesh_quantization`) and Draco-compress freely; both load.+  Do not GPU-instance (above).+- Units are metres (glTF); a 4 mm part is 0.004 across. A wrong unit shows up+  as a light that "does nothing" or a camera that frames a speck.+- Keep the hero GLB under a few MB: it loads on every page view of the+  component (and posters cover it until the reader clicks Load).++## Node naming that survives service-step2glb++STEP to GLB keeps node names, so name the parts in CAD: `Adom.FOV`,+`Adom.LED.State`, `Adom.LaserEtch.MPN`, and instance labels (`U1`, `LED3`)+survive and become the group rows and tooltips. Generic exporter names+(`Body1`, `Mesh_014`) do not; declare `extras` after conversion when you+cannot rename in CAD (`gltf-transform` or the `glb_alpha.py` pattern on+adom/vl53l5cx).++## Which model the page shows++The 3D slot renders `component.parts.model_3d` (the page's one GLB); the+"3D | Hero" chip beside it swaps the frame for the page's hero IMAGE+(screenshots/hero.png), not a second GLB. A hero GLB (annotated: layers,+labels, intros, yaw) is therefore the page's `model_3d`; the clean board LODs+that other pages consume are separate files (see wiki-component-lod: the four+board LODs exclude footprint, pad-label and silkscreen helpers, the hero keeps+them). The 3D slot is click-gated (a poster until the reader clicks Load) and+unloads after 45 s of page inactivity, so a heavy hero costs a first click,+not a page load.++## Checklist before publishing++1. Two or more layers, or a declared one, so the panel appears; hidden layers+   marked `hidden: true`; an intro on the one worth introducing.+2. `extras.tooltip` on anything a reader would hover; `tooltips: "authored"`+   on manufacturer GLBs with CAD names.+3. Lights under unscaled nodes, inside an `Adom.*` group with their emissive+   skin.+4. `component.viewer_3d` set for the page's look (repeat 0 for a looping yaw,+   ground false for a floating part); check with `?animate=0` that the still+   frame reads too.+5. No GPU instancing; Draco or quantization is fine; open the page and read+   the browser console once: the viewer says what it refused.