docs(wiki): two-page splice flow + lazy-column reveal gotcha

wiki/gradio-embed-integration.md

@@ -43,15 +43,33 @@ Two bridges are in play, both proven patterns (see `fusion_ui.py` /
   `#buddy-select-submit` to stage it in slot A/B. The bridge elements carry
   `elem_classes=["buddy-bridge-box"]` (CSS-hidden, kept in the DOM); the
   `buddyBridgeSet` helper uses the native value setter + `input` event before the
-  click, exactly like the voice bridge.
-- **AI tweak is NOT a bridge — it is a plain `gr.Textbox.submit`.** The Lab has
-  one visible inline tweak box per staged slot (`tweak_a` / `tweak_b`); their
-  `.submit` handlers reshape that creature server-side and re-render the slot +
-  tree. The detail modal is **inspect-only** (no tweak form). The earlier design
-  put the tweak inside the modal and refreshed it from JS via a hidden bridge on a
-  fixed `setTimeout` — that timeout was too short for the slow real ZeroGPU model,
-  so the modal closed/refreshed before the edit returned and the change appeared
-  to vanish. Inline server-rendered submit has no timing dependency. (The old
+  click, exactly like the voice bridge. `on_select` updates ONLY state + the Pick
+  screen's slots/tree — it does NOT toggle screens (see the auto-advance bridge).
+- **Auto-advance bridge (JS → Python).** Staging the second creature opens the
+  Splice Bench. `_slots_html` marks `.buddy-slots[data-ready="1"]` when both slots
+  are filled; the 400ms voxel poll runs `buddyAutoAdvance`, which `.click()`s the
+  hidden `#buddy-adv-submit` button once (guarded by `window.__buddyAdvancing`).
+  That button's handler (`adv_open`) is a **clean, screens-only** response, with
+  the bench previews filled by a chained `.then(adv_fill)`. The guard is only
+  re-armed on a genuine deselect (slots present AND `data-ready="0"`), never when
+  the slots simply unmount — otherwise `← Back` re-shows the still-ready slots and
+  the poll bounces straight back to the bench. The reveal MUST be isolated this way
+  (see Failure Modes: lazy-mounted column reveal).
+- **Chip bridge (JS → Python).** Each suggestion chip on the bench carries
+  `data-side`/`data-prompt`; a delegated click handler calls `buddyChip`, which
+  writes `{side, prompt}` JSON into `#buddy-chip-in` and `.click()`s
+  `#buddy-chip-submit`. `on_chip` parses it and runs the AI tweak on that side —
+  one tap, no Enter.
+- **AI tweak is NOT a bridge — it is a plain `gr.Textbox.submit` (+ Apply button).**
+  The Splice Bench has one inline tweak box per side (`tweak_a` / `tweak_b`), each
+  with an explicit `Apply` button (`tweak_a_btn` / `tweak_b_btn`) bound to the same
+  handler as `.submit` (Enter still works). Handlers reshape that creature
+  server-side and re-render that bench side + the tree. The detail modal is
+  **inspect-only** (no tweak form). The earlier design put the tweak inside the
+  modal and refreshed it from JS via a hidden bridge on a fixed `setTimeout` — that
+  timeout was too short for the slow real ZeroGPU model, so the modal
+  closed/refreshed before the edit returned and the change appeared to vanish.
+  Inline server-rendered submit has no timing dependency. (The old
   `#buddy-tweak-in` / `#buddy-tweak-submit` bridge and `buddyTweak` JS were
   removed.)
 
@@ -79,6 +97,22 @@ Two bridges are in play, both proven patterns (see `fusion_ui.py` /
   visibility (mounts the component), then `.then(populate)` that writes the value
   once it is mounted. In `fusion_ui.py` the Splice click shows the reveal screen
   first, then `.then(do_fuse)` fills `reveal_view` / `card_view`.
+- **Revealing a NEVER-yet-mounted `visible=False` column is stricter still: the
+  `visible=True` is silently dropped unless the response touches ONLY the screen
+  columns.** Gradio lazily mounts a `visible=False` column (it is absent from the
+  DOM until first shown). Flipping it to visible works *only* from a handler whose
+  outputs are just the screen column(s). If the same response also writes another
+  screen's HTML children (e.g. the Pick screen's slots/tree) **or** the toggle is
+  deferred to a chained `.then`, the column mounts but stays `hide` (display:none)
+  — content present, screen invisible. Verified empirically by bisecting ~6 wiring
+  variants: a pure columns-only handler reveals it; adding state/HTML-child outputs
+  or a `.then` before it does not; a *real* button vs a programmatic `.click()`
+  makes no difference. Fix for the bench auto-advance: a dedicated bridge
+  (`#buddy-adv-submit`) whose handler `adv_open` returns only `[screen_lab,
+  screen_bench]`, with `.then(adv_fill)` writing the bench previews afterward; the
+  selection handler (`on_select`) stays separate and never touches the columns.
+  This is why the bench could not simply reuse `on_select`'s outputs or a
+  `select_btn` `.then`.
 - **Dispatching an `input` event at a Gradio textbox does not reliably fire its
   Python handler.** The JS→Python bridge via a hidden textbox alone silently
   no-ops. A programmatic real `.click()` on a hidden Gradio **button** *does*
@@ -106,9 +140,10 @@ Two bridges are in play, both proven patterns (see `fusion_ui.py` /
 ## Sources
 
 - `src/buddy_fusion/voxel_embed.py` (voxelizer, `VOXEL_JS_ON_LOAD`,
-  MutationObserver + poll, shared offscreen thumbnail renderer)
-- `src/buddy_fusion/fusion_ui.py` (hidden bridge textbox/button, `BROWSER_VOICE_JS`,
-  `buddy-bridge-box`)
+  MutationObserver + poll, shared offscreen thumbnail renderer, `buddyChip` +
+  `buddyAutoAdvance` bridges)
+- `src/buddy_fusion/fusion_ui.py` (hidden bridge textbox/button, `buddy-bridge-box`,
+  `on_select` / `adv_open` / `adv_fill` / `on_chip`, the Splice Bench layout)
 
 ## Related Pages
 

wiki/log.md

@@ -2,6 +2,18 @@
 
 ## 2026-06-14
 
+### gradio-embed-integration + system-overview: two-page splice flow & lazy-column reveal
+
+- Recorded the lazy-mounted `visible=False` column gotcha: a never-yet-mounted
+  column's `visible=True` is dropped unless the response touches only the screen
+  columns (no other screen's HTML children, not via `.then`). Documented the
+  dedicated `#buddy-adv-submit` bridge (`adv_open` + `.then(adv_fill)`) and the
+  `data-ready` / `buddyAutoAdvance` client trigger that work around it.
+- Added the chip bridge (`buddyChip` / `on_chip`) and moved the AI tweak boxes
+  (now + Apply buttons) onto the new Splice Bench in the bridges section.
+- Updated `system-overview.md` to a four-screen flow (landing → pick → bench →
+  reveal) with matching data-flow steps and a new gotcha bullet.
+
 ### deployment-strategy: response_format bug, Qwen2.5-3B default, ZeroGPU quota
 
 - Recorded the root-cause fix: `response_format` must be

wiki/system-overview.md

@@ -59,22 +59,28 @@ reliable envelope.
   bridges, the SVG pedigree connectors, and `window` export hooks. Renders each
   voxel as an `InstancedMesh` cube.
 - `formatter.py` — genome-card HTML + share text.
-- `fusion_ui.py` — the Gradio Blocks game flow: a three-screen state machine
-  (landing → lab pedigree hub → reveal) toggled by `gr.Column(visible=...)`,
-  selection slots, the landing backdrop (`LANDING_BG_JS` + `_buddy_data_uris`),
-  all CSS, and the hidden JS↔Python bridges. Exports `CSS, FUSION_HEAD, build_app`.
+- `fusion_ui.py` — the Gradio Blocks game flow: a four-screen state machine
+  (landing → lab/pick pedigree hub → splice bench → reveal) toggled by
+  `gr.Column(visible=...)`, selection slots, per-side AI tweak + quick chips on the
+  bench, the landing backdrop (`LANDING_BG_JS` + `_buddy_data_uris`), all CSS, and
+  the hidden JS↔Python bridges. Exports `CSS, FUSION_HEAD, build_app`.
 - `json_utils.py` — JSON extraction helpers. (Command input is a text box now;
   the old `asr.py` voice wrapper was deleted — see voice-input-asr.md.)
 
 ## Data flow
 
-1. Landing screen → `Start` reveals the Lab.
-2. The family pedigree is the hub: tap two creatures (any nodes, children
-   included) to stage them in the A/B slots; 🔍 opens a detail modal with a live
-   3D view + genome card + AI text-tweak (`interpret_genome_command`).
-3. Splice: one LLM call recombines the two staged genomes → child dict →
+1. Landing screen → `Start` reveals the Lab (Pick screen).
+2. Pick: the family pedigree is the hub and fills the screen — tap two creatures
+   (any nodes, children included) to stage them in the A/B slots; 🔍 opens an
+   inspect-only detail modal (live 3D + genome card). Staging the second creature
+   auto-advances to the Splice Bench.
+3. Splice Bench: the two staged creatures shown A-left / B-right with live
+   previews + genome cards; each side has an AI tweak box + Apply button + quick
+   suggestion chips (one-tap `interpret_genome_command`). `← Back` returns to Pick
+   with the picks retained.
+4. Splice: one LLM call recombines the two staged genomes → child dict →
    `repair_genome` → `Genome` (`do_fuse` reads the selection, not a fixed pair).
-4. The reveal screen shows both parents + the newborn; the child enters the
+5. The reveal screen shows both parents + the newborn; the child enters the
    `Lineage` and appears in the pedigree, ready to be staged again.
 
 ## Deployment
@@ -98,6 +104,11 @@ reliable envelope.
 - Toggling a screen visible AND writing one of its components in the same response
   leaves that component stuck in `pending`; split into a visibility event then
   `.then(populate)` — see gradio-embed-integration.md.
+- Revealing a *never-yet-mounted* `visible=False` screen is even stricter: the
+  `visible=True` is silently dropped unless the triggering response touches ONLY
+  the screen columns (no other screen's HTML children, and not via a chained
+  `.then`). The bench auto-advance uses a dedicated clean bridge for exactly this
+  — see gradio-embed-integration.md.
 - Binary assets (the landing buddy PNGs, etc.) are tracked via Git LFS
   (`.gitattributes`); pushing uploads LFS objects to the Space.
 - **AI tweak silently did nothing on the real model (fixed 2026-06-14,