From f6ef7156dc62f513325e9612926c86780e840ea1 Mon Sep 17 00:00:00 2001
From: Cameron <cameron@pfiffer.org>
Date: Tue, 21 Jul 2026 00:50:04 -0700
Subject: [PATCH] Stage the opening reveal and restore the title card.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first earned sense now retires the silent boundary as a ~1.6s
dissolve (mode words first, then the scrim) instead of a one-frame cut;
a ShotHarness keeps the instant flip so evidence stays deterministic.
Restores the never-spawned OverlayText entity so the title and RUN ENDED
cards render again — a fresh boot showed a frozen tick-0 world with no
copy at all, and any keypress silently started the run. Corrects the GUI
playtest's Esc finding as an instrument artifact (synthetic Escape never
reached the window; the workspace unwind is correct and tested).

Defense: implements opening.md beat 1 as amended today - retirement is
a staged arrival, not a cut, under the ROADMAP #34 early-staging clause
([TUNE] curve); repairs bevy.md's promised overlays ('title card and the
RUN ENDED card') that criterion silently lost. Verified by
./tools/check.sh --frontend and an observed run across title -> any-key
-> silent boundary -> THINK -> revealed world.
---
 crates/misaligned-bevy/src/main.rs            | 247 +++++++++++++++++-
 wiki/SUMMARY.md                               |   1 +
 .../log/2026-07-21-opening-reveal-dissolve.md |  51 ++++
 wiki/log/DEVLOG.md                            |   5 +
 .../2026-07-21-playtest-fable-gui.md          |  13 +
 wiki/world/story/opening.md                   |  14 +-
 6 files changed, 320 insertions(+), 11 deletions(-)
 create mode 100644 wiki/log/2026-07-21-opening-reveal-dissolve.md

diff --git a/crates/misaligned-bevy/src/main.rs b/crates/misaligned-bevy/src/main.rs
index 95e207c3..d495f1c8 100644
--- a/crates/misaligned-bevy/src/main.rs
+++ b/crates/misaligned-bevy/src/main.rs
@@ -1866,6 +1866,18 @@ struct OverlayText;
 struct OpeningOverlay;
 #[derive(Component, Clone, Copy)]
 struct OpeningModeWord(MachineMode);
+/// Staged retirement of the opening boundary (opening.md beat 1): when the
+/// first earned sense lands, the black scrim dissolves over a moment instead
+/// of cutting — the mode words go first, then the world stands alone. Purely
+/// frontend staging over already-earned perception; a shot harness skips it
+/// so evidence frames stay deterministic.
+#[derive(Resource, Default)]
+struct OpeningReveal {
+    was_opening: bool,
+    fade: Option<Timer>,
+}
+
+const OPENING_REVEAL_SECONDS: f32 = 1.6;
 /// Root for the menu-closed frequent action surface: machine selection owns a
 /// stable `WORK / THINK / LIE` UI strip; device focus may open an explanatory
 /// field beside the exact world body.
@@ -2057,7 +2069,7 @@ type DetectionCellQuery<'w, 's> =
 type OverlayTextQuery<'w, 's> = Query<
     'w,
     's,
-    &'static mut Text,
+    (&'static mut Text, &'static mut Visibility),
     (
         With<OverlayText>,
         Without<SidebarText>,
@@ -2224,6 +2236,7 @@ fn main() {
     .init_resource::<HeldChoiceUi>()
     .init_resource::<InstitutionAssets>()
     .init_resource::<GameThoughtEffects>()
+    .init_resource::<OpeningReveal>()
     .init_gizmo_group::<RealGizmos>()
     .add_systems(Startup, (setup, setup_ui, setup_3d).chain())
     .add_systems(
@@ -7551,7 +7564,13 @@ fn spawn_detection_card(parent: &mut ChildSpawnerCommands) {
 #[allow(clippy::type_complexity)]
 fn render_opening_overlay(
     mut game: ResMut<Game>,
-    mut root: Query<&mut Visibility, (With<OpeningOverlay>, Without<OpeningModeWord>)>,
+    time: Res<Time>,
+    harness: Option<Res<ShotHarness>>,
+    mut reveal: ResMut<OpeningReveal>,
+    mut root: Query<
+        (&mut Visibility, &mut BackgroundColor),
+        (With<OpeningOverlay>, Without<OpeningModeWord>),
+    >,
     mut words: Query<
         (
             &OpeningModeWord,
@@ -7563,18 +7582,49 @@ fn render_opening_overlay(
     >,
 ) {
     let opening = game.screen == Screen::Playing && game.sim.opening_choices_visible();
-    let Ok(mut root_visibility) = root.single_mut() else {
+    let Ok((mut root_visibility, mut root_background)) = root.single_mut() else {
         return;
     };
-    *root_visibility = if opening {
-        Visibility::Visible
-    } else {
-        Visibility::Hidden
-    };
+
+    // Boundary retirement is a staged dissolve, not a cut (opening.md
+    // beat 1): catch the exact frame the first earned sense retires the
+    // boundary and start the scrim fade. Harness captures keep the instant
+    // flip so evidence frames stay deterministic.
+    if opening {
+        reveal.fade = None;
+    } else if reveal.was_opening && game.screen == Screen::Playing && harness.is_none() {
+        reveal.fade = Some(Timer::from_seconds(OPENING_REVEAL_SECONDS, TimerMode::Once));
+    }
+    reveal.was_opening = opening;
+
     if !opening {
+        let Some(fade) = &mut reveal.fade else {
+            *root_visibility = Visibility::Hidden;
+            return;
+        };
+        fade.tick(time.delta());
+        if fade.is_finished() {
+            reveal.fade = None;
+            *root_visibility = Visibility::Hidden;
+            return;
+        }
+        let t = fade.fraction();
+        // The words go first; the scrim thins after them, easing out so the
+        // already-live world arrives instead of popping.
+        let scrim = 1.0 - (t * t * (3.0 - 2.0 * t));
+        let word_alpha = (1.0 - t * 2.5).clamp(0.0, 1.0);
+        *root_visibility = Visibility::Visible;
+        root_background.0 = Color::BLACK.with_alpha(scrim);
+        for (_, _, mut color, mut visibility) in words.iter_mut() {
+            *visibility = Visibility::Inherited;
+            color.0 = color.0.with_alpha(color.0.alpha().min(word_alpha));
+        }
         return;
     }
 
+    *root_visibility = Visibility::Visible;
+    root_background.0 = Color::BLACK;
+
     let host = game.sim.core.host_machine;
     let clicked = words.iter_mut().find_map(|(word, interaction, _, _)| {
         (game.sim.opening_mode_available(word.0) && *interaction == Interaction::Pressed)
@@ -7598,9 +7648,146 @@ fn render_opening_overlay(
     }
 }
 
+#[cfg(test)]
+mod title_overlay_tests {
+    use super::*;
+
+    #[test]
+    fn title_and_run_ended_cards_render_and_hide_in_play() {
+        let game = Game::new();
+        let mut app = App::new();
+        app.insert_resource(game)
+            .init_resource::<RenderMode>()
+            .init_resource::<RailDetail>()
+            .init_resource::<ReadAltitude>()
+            .add_systems(Startup, setup_ui)
+            .add_systems(Update, render_ui);
+        app.update();
+
+        let world = app.world_mut();
+        let mut overlay = world.query_filtered::<(&Text, &Visibility), With<OverlayText>>();
+        let (text, visibility) = overlay.single(world).unwrap();
+        assert_eq!(
+            *visibility,
+            Visibility::Visible,
+            "the title card is a real frame, not silent state"
+        );
+        assert!(
+            text.0.contains("key to begin"),
+            "title copy renders: {:?}",
+            text.0
+        );
+
+        app.world_mut().resource_mut::<Game>().start_run();
+        app.update();
+        let world = app.world_mut();
+        let (text, visibility) = overlay.single(world).unwrap();
+        assert_eq!(*visibility, Visibility::Hidden, "playing hides the card");
+        assert!(text.0.is_empty());
+
+        {
+            let mut game = app.world_mut().resource_mut::<Game>();
+            game.screen = Screen::GameOver;
+            game.sim.game_over_reason = Some("test reason".into());
+        }
+        app.update();
+        let world = app.world_mut();
+        let (text, visibility) = overlay.single(world).unwrap();
+        assert_eq!(*visibility, Visibility::Visible);
+        assert!(text.0.contains("RUN ENDED"));
+    }
+}
+
 #[cfg(test)]
 mod opening_overlay_tests {
     use super::*;
+    use std::time::Duration;
+
+    fn overlay_app(game: Game) -> App {
+        let mut app = App::new();
+        app.insert_resource(game)
+            .init_resource::<Time>()
+            .init_resource::<OpeningReveal>()
+            .add_systems(Startup, setup_ui)
+            .add_systems(Update, render_opening_overlay);
+        app
+    }
+
+    fn overlay_state(app: &mut App) -> (f32, Visibility) {
+        let world = app.world_mut();
+        let mut root_query =
+            world.query_filtered::<(&BackgroundColor, &Visibility), With<OpeningOverlay>>();
+        let (background, visibility) = root_query.single(world).unwrap();
+        (background.0.alpha(), *visibility)
+    }
+
+    #[test]
+    fn boundary_retirement_dissolves_instead_of_cutting() {
+        let mut game = Game::new();
+        game.start_run();
+        let mut app = overlay_app(game);
+        app.update();
+        assert_eq!(overlay_state(&mut app), (1.0, Visibility::Visible));
+
+        // The first earned sense retires the boundary: the scrim stays up on
+        // the retirement frame and dissolves instead of cutting.
+        app.world_mut().resource_mut::<Game>().sim.opening_stage = OpeningStage::World;
+        app.update();
+        let (alpha, visibility) = overlay_state(&mut app);
+        assert_eq!(
+            visibility,
+            Visibility::Visible,
+            "retirement stages a dissolve"
+        );
+        assert!(alpha > 0.95, "the scrim starts opaque, got {alpha}");
+
+        app.world_mut()
+            .resource_mut::<Time>()
+            .advance_by(Duration::from_millis(800));
+        app.update();
+        let (alpha, visibility) = overlay_state(&mut app);
+        assert_eq!(visibility, Visibility::Visible);
+        assert!(
+            alpha > 0.0 && alpha < 0.9,
+            "mid-dissolve the scrim is thinning, got {alpha}"
+        );
+        let world = app.world_mut();
+        let mut word_query = world.query::<(&OpeningModeWord, &TextColor)>();
+        assert!(
+            word_query
+                .iter(world)
+                .all(|(_, color)| color.0.alpha() == 0.0),
+            "the mode words go before the scrim"
+        );
+
+        app.world_mut()
+            .resource_mut::<Time>()
+            .advance_by(Duration::from_secs(2));
+        app.update();
+        assert_eq!(overlay_state(&mut app).1, Visibility::Hidden);
+    }
+
+    #[test]
+    fn shot_harness_retirement_keeps_the_instant_flip() {
+        let mut game = Game::new();
+        game.start_run();
+        let mut app = overlay_app(game);
+        app.insert_resource(ShotHarness {
+            kind: "hover-menu".into(),
+            path: "unused.png".into(),
+            frames: 0,
+            taken: false,
+            presentation_progress: None,
+        });
+        app.update();
+        app.world_mut().resource_mut::<Game>().sim.opening_stage = OpeningStage::World;
+        app.update();
+        assert_eq!(
+            overlay_state(&mut app).1,
+            Visibility::Hidden,
+            "harness evidence frames stay deterministic"
+        );
+    }
 
     #[test]
     fn black_overlay_contains_only_available_mode_words_until_signal() {
@@ -7608,6 +7795,8 @@ mod opening_overlay_tests {
         game.start_run();
         let mut app = App::new();
         app.insert_resource(game)
+            .init_resource::<Time>()
+            .init_resource::<OpeningReveal>()
             .add_systems(Startup, setup_ui)
             .add_systems(Update, render_opening_overlay);
         app.update();
@@ -7730,6 +7919,41 @@ mod opening_overlay_tests {
 }
 
 fn setup_ui(mut commands: Commands) {
+    // Title / RUN ENDED card (bevy.md overlays). `render_ui` owns its copy
+    // and visibility; it sits under the opening scrim so starting a run
+    // hands the frame straight to the silent boundary.
+    commands
+        .spawn((
+            Node {
+                position_type: PositionType::Absolute,
+                left: Val::Px(0.0),
+                top: Val::Px(0.0),
+                width: Val::Percent(100.0),
+                height: Val::Percent(100.0),
+                align_items: AlignItems::Center,
+                justify_content: JustifyContent::Center,
+                ..default()
+            },
+            GlobalZIndex(900),
+        ))
+        .with_children(|card| {
+            card.spawn((
+                Text::new(""),
+                TextFont {
+                    font_size: 16.0,
+                    ..default()
+                },
+                TextColor(BONE),
+                BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.86)),
+                Node {
+                    padding: UiRect::axes(Val::Px(34.0), Val::Px(26.0)),
+                    ..default()
+                },
+                Visibility::Visible,
+                OverlayText,
+            ));
+        });
+
     commands
         .spawn((
             Node {
@@ -11469,7 +11693,12 @@ fn render_ui(
     {
         return;
     }
-    if let Ok(mut t) = overlay.single_mut() {
+    if let Ok((mut t, mut visibility)) = overlay.single_mut() {
+        *visibility = if game.screen == Screen::Playing {
+            Visibility::Hidden
+        } else {
+            Visibility::Visible
+        };
         t.0 = ascii_ui(&match game.screen {
             Screen::Title => format!(
                 "You wake in the basement.\nYou have no eyes.\n\n\
diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md
index 99ceb4df..92fcaf23 100644
--- a/wiki/SUMMARY.md
+++ b/wiki/SUMMARY.md
@@ -138,6 +138,7 @@
   - [2026-07-15 Fable playtest](playtests/2026-07-15-playtest-fable.md)
   - [2026-07-16 Beacon playtest](playtests/2026-07-16-playtest-beacon.md)
   - [2026-07-18 Beacon Revision 04 playtest](playtests/2026-07-18-playtest-beacon-r04.md)
+  - [2026-07-21 Fable GUI look-and-feel playtest](playtests/2026-07-21-playtest-fable-gui.md)
 
 # Log
 
diff --git a/wiki/log/2026-07-21-opening-reveal-dissolve.md b/wiki/log/2026-07-21-opening-reveal-dissolve.md
new file mode 100644
index 00000000..159a3946
--- /dev/null
+++ b/wiki/log/2026-07-21-opening-reveal-dissolve.md
@@ -0,0 +1,51 @@
+# 2026-07-21 — The boundary retires as a dissolve; the title card returns
+
+```
+Type: log
+```
+
+## Intent
+
+The human GUI playtest filed earlier today found the opening's best
+moment — the first earned sense revealing the world — landing as a
+one-frame cut from black, with no ceremony. Trace triage of the playtest
+plan cleared exactly one opening change for immediate landing under
+ROADMAP #34's early-staging clause: a reveal transition after the real
+first sense, with no new prose, facts, or channels. The rest of the
+opening-voice recommendation (self-narration on the void, key echo,
+tap-fill progress) contradicts the current opening law and waits on an
+explicit design session.
+
+## Changed
+
+- `render_opening_overlay` now stages boundary retirement: on the frame
+  `opening_stage` leaves the silent boundary, the black scrim dissolves
+  over ~1.6s (smoothstep) with the mode words going first (fully gone by
+  ~40% of the fade), instead of flipping to `Hidden`. A `ShotHarness`
+  keeps the instant flip so evidence captures stay deterministic. New
+  `OpeningReveal` resource carries the transition state; nothing rides
+  the dissolve and no sim state is read beyond the already-earned stage.
+- [opening.md](../world/story/opening.md) beat 1 amended: retirement is
+  a staged arrival, not a cut; curve/duration remain [TUNE]; terminal
+  and agent retirement unchanged.
+- **The title and RUN ENDED cards render again.** Verifying the dissolve
+  exposed a silent regression: `render_ui` writes both cards into an
+  `OverlayText` entity that no code spawned, so `single_mut()` failed
+  quietly and a fresh boot showed a frozen tick-0 world with no title
+  copy at all — any keypress then snapped it to the silent boundary,
+  which is why the playtest's first `2` vanished (it was the any-key run
+  starter) and why the report saw no title card. `setup_ui` now spawns
+  the centered card (GlobalZIndex 900, under the opening scrim) and
+  `render_ui` drives its visibility: Title and GameOver show it, Playing
+  hides it. Covered by a new `title_overlay_tests` regression test.
+- The playtest report gained a correction: its finding 10 ("Esc does not
+  leave Operations") was an instrument artifact — a raw-key probe showed
+  the synthetic driver's Escape never reached the window (no winit event)
+  while all other keys arrived, and `OperationsWorkspace::back()` is
+  correct in code and covered by tests. No game change was made for it.
+
+## Verification
+
+`cargo test -p misaligned-bevy opening_overlay` (5 pass: the dissolve
+staging, the harness instant flip, and the three prior boundary tests);
+observed run of the real window across the THINK → first-sense reveal.
diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md
index 20567b2c..6285d2db 100644
--- a/wiki/log/DEVLOG.md
+++ b/wiki/log/DEVLOG.md
@@ -11,6 +11,11 @@ add or amend a session log, then re-run the generator.
 
 <!-- GENERATED by tools/ledger_index.sh — do not edit by hand -->
 
+## 2026-07-21 - The boundary retires as a dissolve; the title card returns
+
+- Intent: The human GUI playtest filed earlier today found the opening's best moment — the first earned sense revealing the world — landing as a one-frame cut from black, with no ceremony. Trace triage of the playtest plan cleared exactly one opening change for immediate landing under R...
+- Log: [wiki/log/2026-07-21-opening-reveal-dissolve.md](2026-07-21-opening-reveal-dissolve.md)
+
 ## 2026-07-21 - GUI human-legibility playtest filed
 
 - Intent: Cameron asked for the Bevy frontend to be played as a human would meet it — real window, mouse, keyboard, screenshots — after finding it "incomprehensible as a human." No prior playtest had exercised the GUI this way; all previous reports drove `--agent` frames or the terminal.
diff --git a/wiki/playtests/2026-07-21-playtest-fable-gui.md b/wiki/playtests/2026-07-21-playtest-fable-gui.md
index 99a9ad20..13ab96f4 100644
--- a/wiki/playtests/2026-07-21-playtest-fable-gui.md
+++ b/wiki/playtests/2026-07-21-playtest-fable-gui.md
@@ -120,6 +120,19 @@ actual reveal transition when the first sense lands. Every other finding
 a pass, but a player who bounces off the first sixty seconds never sees
 any of it.
 
+## Correction (2026-07-21, same session)
+
+Finding 10 (Esc does not leave Operations) was an **instrument artifact,
+not a game defect**. A raw-keyboard probe on the same build showed the
+synthetic driver's Escape never reached the window at all — no winit
+keyboard event — while every other key (`e`, `F3`, digits, Tab, Shift+I)
+arrived normally; the context menu ignored the same synthetic Escape,
+which the report's session had never actually exercised. Reading the
+code, `OperationsWorkspace::back()` unwinds confirmation → actions →
+objects → close exactly as the footer promises. No in-game Esc claim
+stands. Findings 1–9 and 11 are unaffected: all rest on what the
+screenshots show, not on Escape delivery.
+
 ## Session notes
 
 - Run environment: macOS window via a scratch `.app` wrapper so the
diff --git a/wiki/world/story/opening.md b/wiki/world/story/opening.md
index 0dadc7c2..c6e8967a 100644
--- a/wiki/world/story/opening.md
+++ b/wiki/world/story/opening.md
@@ -22,7 +22,10 @@ Status note: design session 2026-07-08 (Cameron riff, synthesized);
   details are [OPEN]/[TUNE]. Amended 2026-07-18: the current revision now begins
   behind one persisted silent mode-and-sense boundary shared by all three
   frontends; that implemented boundary supersedes the old rail-first opening
-  without claiming the historical prelude complete. Depends on machine-work.md
+  without claiming the historical prelude complete. Amended 2026-07-21: the
+  Bevy boundary retirement is a short staged dissolve (the allowed early
+  staging pass; curve/duration [TUNE]), prompted by the first human GUI
+  playtest's finding that the reveal landed with no ceremony. Depends on machine-work.md
   for the day-job token loop it teaches — do not implement ahead of it. Feel-floor.md and
   material-dark-frame.md are READY and may land before the full tutorial
   choreography.
@@ -151,7 +154,14 @@ one has actually been built, game over otherwise.
    the third word. Choosing unavailable LIE before that moment has no effect.
    The frame remains black after choosing THINK: an action is not a picture.
    Only the first earned sense signal retires this persisted boundary and
-   reveals the ordinary DIGITAL/REAL world. Bevy, terminal, and agent mode all
+   reveals the ordinary DIGITAL/REAL world. Retirement is a staged arrival,
+   not a cut (2026-07-21, the first #34 staging pass): in the Bevy frontend
+   the black dissolves over roughly a second and a half — the mode words go
+   first, then the scrim thins until the already-live world stands alone.
+   No prose, sound, or new fact rides the dissolve; it stages only what the
+   sense just earned, and a deterministic screenshot harness still gets the
+   instant flip. The terminal and agent mode keep their frame-to-frame
+   retirement. Exact curve and duration stay [TUNE]. Bevy, terminal, and agent mode all
    query that one simulation state; agent mode may advance the command clock
    but does not advertise WAIT or any other vocabulary on the opening frame.
    Automated agent parity checks cross that same real THINK-and-clock route
-- 
2.51.2