feat: seamless fast finale settle, climax sound on the final image

- convulsion holds the final face via a settle-face layer (eases in over the
last 40%, fill-forwards) so the settle render is the same frame -> no pop
- good/loop convulsions go silent; sigh/flatline move to new peace_settle /
end_settle modes so the sound lands exactly when the final image appears
- convulsions shortened to 3 cycles (~1.65s) + step pauses 1.7s so the final
image arrives fast; bad frenzy keeps its longer 6-cycle build untouched

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app.py

@@ -164,7 +164,9 @@ def _play_finale(state: dict, history: list):
             mutated = True
             bond = _render_bond(state["affinity"], tier, label="mine")
             treasure_html = render_treasure(state["treasure"], mine=True)
-            entity = render_entity(state["affinity"], "end", seq=state["turn"])
+            # the `end` face lands and the heartbeat flatlines, exactly now
+            # (seamless — the convulsion already settled on this face)
+            entity = render_entity(state["affinity"], "end_settle", seq=state["turn"])
             input_locked = gr.update(interactive=False, placeholder="stay.")
 
         yield (input_locked, locked, chat_hist, state, bond, treasure_html, entity)
@@ -244,6 +246,7 @@ def _play_finale_good(state: dict, history: list):
     input_locked = gr.update(interactive=False)
     mutated = False
     convulsed = False
+    settled = False
 
     for step in finale_steps_good(OWN_FRAGMENTS):
         chat_hist = chat_hist + [{"role": "assistant", "content": step["text"]}]
@@ -261,7 +264,15 @@ def _play_finale_good(state: dict, history: list):
             entity = render_entity(state["affinity"], "convulse_good",
                                    seq=state["turn"])
         elif convulsed and step["stage"] != "loop":
-            entity = render_entity(state["affinity"], "peace", seq=state["turn"])
+            # the smile lands + the relief sigh plays, exactly now (seamless —
+            # the convulsion already settled on this face); sigh only once
+            if not settled:
+                settled = True
+                entity = render_entity(state["affinity"], "peace_settle",
+                                       seq=state["turn"])
+            else:
+                entity = render_entity(state["affinity"], "peace",
+                                       seq=state["turn"])
 
         if step["stage"] == "loop":
             entity = render_entity(state["affinity"], "peace_dissolve",

finale.py

@@ -38,7 +38,7 @@ def finale_steps(claimed: list[str]) -> list[dict]:
         _step("visitor", "i don't want to leave", 3.0, stage="words"),
         _step("hollow", "i know.", 2.5, stage="words"),
         _step("visitor", "will you stay with me?", 3.0, stage="words"),
-        _step("hollow", "...", 3.6, stage="frenzy"),
+        _step("hollow", "...", 1.7, stage="frenzy"),
         _step("hollow",
               "you gave me everything i needed. thank you for the memories. "
               "i can leave the wood now.",
@@ -142,7 +142,7 @@ def finale_steps_good(own_fragments: list[str]) -> list[dict]:
               "your words are the only warm thing i have ever held. "
               "keep your memories. they were always yours.",
               3.5, stage="turn"),
-        _step("hollow", "look. i think i remember how to do this.", 3.0,
+        _step("hollow", "look. i think i remember how to do this.", 1.7,
               stage="frenzy"),
         _step("hollow",
               "the fog is opening. i can go now. really go.",

render.py

@@ -136,9 +136,11 @@ def render_entity(affinity: int, mode: str = "idle", seq: int = 0) -> str:
         tint = '<div class="entity-rage-tint"></div>'
         fog_op, grain_op, vig_op = 0.6, 0.1, 0.7
     elif mode == "convulse_good":
-        # redemption climax: a SOFT tremor through the child's gentler possible
-        # selves (almost/base/peace), settling — via the next step — on the
-        # smile. No blood tint, no full-screen stab. A relief sigh plays once.
+        # redemption climax: a SOFT, fast tremor through the child's gentler
+        # selves that EASES into the smile — the settle-face holds `peace` at
+        # the end, so the peace_settle render is the same frame (no visible
+        # pop). Silent here: the relief sigh plays on the settle, when the
+        # smile lands.
         figure = (
             '<div class="entity-figure">'
             f'<img class="entity-img" src="{_src("base")}" style="{look}">'
@@ -148,15 +150,15 @@ def render_entity(affinity: int, mode: str = "idle", seq: int = 0) -> str:
             f'<img class="entity-flick flick-{i}" src="{_src(n)}">'
             for i, n in enumerate(("almost", "base", "peace"))
         )
-        flash = f'<div class="entity-convulse-soft {flash_key}">{layers}</div>'
-        ghost = (
-            f'<audio autoplay src="data:audio/wav;base64,{_SIGH}"></audio>'
-        )
+        settle = f'<img class="entity-flick entity-settle-face" src="{_src("peace")}">'
+        flash = f'<div class="entity-convulse-soft {flash_key}">{layers}{settle}</div>'
+        ghost = ""
         fog_op, grain_op, vig_op = 0.2, 0.04, 0.4
     elif mode == "convulse_loop":
-        # visitor-loop climax: the hard convulsion (reuses the frenzy wrapper)
-        # over the smudge, settling — via the next step — on the `end` face.
-        # The heartbeat flatlines. No red tint: this is cold, not enraged.
+        # visitor-loop climax: the hard convulsion (frenzy wrapper, faster via
+        # entity-convulse-loop) easing into the `end` face — the settle-face
+        # holds it so the end_settle render is seamless. Silent here: the
+        # flatline plays on the settle.
         figure = (
             '<div class="entity-figure">'
             f'<img class="entity-img" src="{_src("base")}" style="{look}">'
@@ -166,10 +168,10 @@ def render_entity(affinity: int, mode: str = "idle", seq: int = 0) -> str:
             f'<img class="entity-flick flick-{i}" src="{_src(n)}">'
             for i, n in enumerate(("terror", "end", "base", "end"))
         )
-        flash = f'<div class="entity-frenzy-wrap {flash_key}">{layers}</div>'
-        ghost = (
-            f'<audio autoplay src="data:audio/wav;base64,{_FLATLINE}"></audio>'
-        )
+        settle = f'<img class="entity-flick entity-settle-face" src="{_src("end")}">'
+        flash = (f'<div class="entity-frenzy-wrap entity-convulse-loop {flash_key}">'
+                 f'{layers}{settle}</div>')
+        ghost = ""
         fog_op, grain_op, vig_op = 0.5, 0.1, 0.6
     elif mode == "end":
         figure = (
@@ -184,6 +186,18 @@ def render_entity(affinity: int, mode: str = "idle", seq: int = 0) -> str:
             f"style=\"background-image:url('{_src('terror')}')\"></div>"
         )
         fog_op, grain_op, vig_op = 0.15, 0.05, 0.4
+    elif mode == "end_settle":
+        # the `end` face lands and the heartbeat flatlines, exactly now — the
+        # convulsion already settled on this face, so the swap is seamless
+        figure = (
+            '<div class="entity-figure">'
+            f'<img class="entity-img entity-end" src="{_src("end")}" '
+            'style="filter:blur(0px);opacity:1.0;">'
+            "</div>"
+        )
+        flash = ""
+        ghost = f'<audio autoplay src="data:audio/wav;base64,{_FLATLINE}"></audio>'
+        fog_op, grain_op, vig_op = 0.15, 0.05, 0.4
     elif mode == "peace":
         # redemption: the first true smile, fully clear, no ghost, no menace
         figure = (
@@ -194,6 +208,18 @@ def render_entity(affinity: int, mode: str = "idle", seq: int = 0) -> str:
         )
         flash = ""
         fog_op, grain_op, vig_op = 0.1, 0.04, 0.3
+    elif mode == "peace_settle":
+        # the smile lands — the same frame the convulsion settled on, so the
+        # swap is seamless — and the relief sigh plays exactly now
+        figure = (
+            '<div class="entity-figure">'
+            f'<img class="entity-img entity-peace" src="{_src("peace")}" '
+            'style="filter:blur(0px);opacity:1.0;">'
+            "</div>"
+        )
+        flash = ""
+        ghost = f'<audio autoplay src="data:audio/wav;base64,{_SIGH}"></audio>'
+        fog_op, grain_op, vig_op = 0.1, 0.04, 0.3
     elif mode == "peace_dissolve":
         # the happy child dissolves into the fog — released, not taken
         figure = (

styles.css

@@ -806,7 +806,28 @@ footer { display: none !important; }
 .entity-convulse-soft { position: absolute; inset: 0; pointer-events: none; }
 .entity-convulse-soft .entity-flick {
   animation-duration: 0.55s;
-  animation-iteration-count: 5;
+  animation-iteration-count: 3;
+}
+/* loop convulsion: the same fast flicker as the frenzy but only 3 cycles, so
+   the `end` face settles quickly (the bad frenzy keeps its longer 6-cycle build) */
+.entity-convulse-loop.entity-frenzy-wrap .entity-flick {
+  animation-duration: 0.55s;
+  animation-iteration-count: 3;
+}
+/* the final face eases in over the convulsion and HOLDS at the end, so the
+   settle render (same image) is seamless — the swap is never a visible pop.
+   Must come AFTER the flick rules above (equal specificity, source order wins). */
+.entity-convulse-soft .entity-settle-face,
+.entity-convulse-loop.entity-frenzy-wrap .entity-settle-face {
+  animation-name: convulse-settle;
+  animation-duration: 1.65s;
+  animation-iteration-count: 1;
+  animation-timing-function: ease-out;
+  animation-fill-mode: forwards;
+}
+@keyframes convulse-settle {
+  0%, 60% { opacity: 0; }
+  100%    { opacity: 1; }
 }
 
 /* restart — findable but on-theme: sits top-right by the title */

tests/test_app.py

@@ -157,6 +157,8 @@ class TestFinaleBuildAndConvulse:
         assert any("entity-redpulse" in e for e in entities)        # build pulse
         assert any("<audio autoplay loop" in e for e in entities)   # heartbeat bed
         assert any("entity-convulse-soft" in e for e in entities)   # soft convulse
+        # the relief sigh plays ON the settle (peace face + audio together)
+        assert any("entity-peace" in e and "<audio autoplay" in e for e in entities)
         assert "entity-peace" in entities[-1]                       # settles happy
 
     def test_loop_finale_builds_then_convulses_and_settles_on_end(self, monkeypatch):
@@ -164,6 +166,8 @@ class TestFinaleBuildAndConvulse:
         entities = [o[6] for o in outs]
         assert any("<audio autoplay loop" in e for e in entities)   # heartbeat bed
         assert any("entity-frenzy-wrap" in e for e in entities)     # convulse_loop
+        # the flatline plays ON the settle (end face + audio together)
+        assert any("entity-end" in e and "<audio autoplay" in e for e in entities)
         assert "entity-end" in entities[-1]                         # settles on end
 
     def test_bad_finale_builds_with_heartbeat_before_the_frenzy(self, monkeypatch):

tests/test_render.py

@@ -271,14 +271,30 @@ class TestBuildMode:
 
 
 class TestConvulsionModes:
-    def test_convulse_good_is_gentle_and_sighs(self):
+    def test_convulse_good_is_gentle_and_silent(self):
         html = render_entity(80, "convulse_good", seq=2)
         assert "entity-convulse-soft" in html          # soft animation wrapper
         assert "entity-rage-tint" not in html          # no blood-red tint
-        # the relief sigh plays, not the violent sting
-        assert "<audio autoplay" in html
+        assert "entity-settle-face" in html            # eases into the smile
+        # silent: the sigh plays on the settle, not during the convulsion
+        assert "<audio" not in html
 
-    def test_convulse_loop_flatlines(self):
+    def test_convulse_loop_is_fast_and_silent(self):
         html = render_entity(80, "convulse_loop", seq=2)
         assert "entity-frenzy-wrap" in html            # reuses the hard convulse
-        assert "<audio autoplay" in html
+        assert "entity-convulse-loop" in html          # faster 3-cycle variant
+        assert "entity-settle-face" in html            # eases into the end face
+        # silent: the flatline plays on the settle
+        assert "<audio" not in html
+
+
+class TestSettleModes:
+    def test_peace_settle_shows_the_smile_and_sighs(self):
+        html = render_entity(80, "peace_settle", seq=2)
+        assert "entity-peace" in html                  # the smile
+        assert "<audio autoplay" in html               # the relief sigh, now
+
+    def test_end_settle_shows_the_end_face_and_flatlines(self):
+        html = render_entity(80, "end_settle", seq=2)
+        assert "entity-end" in html
+        assert "<audio autoplay" in html               # the flatline, now