From efac3651753aaa7104eb47981f7ff85e125fa5c3 Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Wed, 1 Jul 2026 14:51:37 -0400
Subject: [PATCH 1/2] fix(kit): grid-stack the slides deck so it cross-fades in
 normal flow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `slides` kit swapped slides with display:none — measurable but no
cross-fade — so agents hand-rolled decks with `position:absolute` slides
stacked over a `min-height` stage to fade between them. That layout is a
trap: the absolute overlay grows `scrollHeight` but not the document box,
and the surface-page height bridge's ResizeObserver watches the BOX, not
scrollHeight. So once the fixed re-measure timers stop (10s), the frame
goes blind to the deck's real height and freezes clipped — the taller
slide's content gets cut off, nondeterministically depending on whether a
timer landed after layout settled ("uncached looks smaller").

Give the kit a cross-fade that stays IN FLOW: grid-stack every `.slide`
into the same `1/1` cell (they overlap, but the container still sizes to
the tallest slide) and fade with opacity + visibility. Now the deck's true
height lives in the box the ResizeObserver can see, so it self-corrects.

Also document the out-of-flow trap in DESIGN_GUIDE alongside the existing
`position: fixed` ban, with the grid-stack recipe, and add a regression
test pinning the in-flow contract.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 guide/DESIGN_GUIDE.md | 18 ++++++++++++++----
 server/kits.ts        | 20 ++++++++++++++++----
 test/kits.test.ts     | 11 +++++++++++
 3 files changed, 41 insertions(+), 8 deletions(-)

diff --git a/guide/DESIGN_GUIDE.md b/guide/DESIGN_GUIDE.md
index f57980c..2ed00b2 100644
--- a/guide/DESIGN_GUIDE.md
+++ b/guide/DESIGN_GUIDE.md
@@ -211,8 +211,17 @@ is yours.
   height automatically.
 - `<style>` and `<script>` tags are allowed. Scripts run inside a sandboxed
   iframe with no access to the host page.
-- **Never use `position: fixed`** — the iframe sizes to content height and
-  fixed elements break that. Use normal-flow layout.
+- **Keep content in normal flow.** The frame measures your content's height from
+  the document box, so anything taken out of flow is invisible to the sizer and
+  can leave the surface clipped — or frozen at the wrong height after load.
+  - Never use `position: fixed`.
+  - Don't stack `position: absolute` layers over a fixed-`height`/`min-height`
+    box (the usual cross-fade-deck mistake): the overlay grows `scrollHeight` but
+    not the measured box, so the frame won't follow it.
+  - To **overlap** elements (e.g. a cross-fading slide deck), grid-stack them in
+    normal flow instead — `display: grid` on the container, `grid-area: 1 / 1` on
+    each child: they overlap, but the container still sizes to the tallest child.
+    (The `slides` kit does exactly this — reach for it before hand-rolling a deck.)
 
 ## Built-in kit — a head start, not a straitjacket
 
@@ -266,8 +275,9 @@ theme tokens, so kit output re-themes with the workspace.
   and text (`.dim`/`.faint`/`.mono`/`.title`) helpers. Composes an issue/PR/CI
   tree — nest a `.tree` inside a `.tree` to indent — or a status board, from
   generic primitives.
-- **`slides`** — author a `.deck` with `.slide` children; the kit shows one at a
-  time and injects prev/dots/counter/next controls. Arrow keys and PageUp/Down
+- **`slides`** — author a `.deck` with `.slide` children; the kit cross-fades one
+  at a time (grid-stacked in normal flow, so the frame always sizes to the tallest
+  slide) and injects prev/dots/counter/next controls. Arrow keys and PageUp/Down
   navigate.
 
 ```sh
diff --git a/server/kits.ts b/server/kits.ts
index 2603a54..19e88c6 100644
--- a/server/kits.ts
+++ b/server/kits.ts
@@ -60,10 +60,22 @@ const ISSUES_CSS = `
 // slides: a stepped deck. Author `.deck` with `.slide` children; the JS shows
 // one at a time and injects prev/dots/counter/next controls. Arrow keys and
 // PageUp/Down navigate (plain keys only — the host owns the meta/alt combos).
+//
+// The slides are GRID-STACKED (every `.slide` in the same `1/1` cell), not
+// swapped with display:none or overlaid with position:absolute. That keeps them
+// in normal flow — so the deck (and the document) sizes to the TALLEST slide and
+// the height the surface reports stays stable — while still letting them overlap
+// so inactive slides can cross-fade under the active one. An absolute overlay
+// would grow scrollHeight without growing the measured box, and the frame's
+// ResizeObserver (which watches the box, not scrollHeight) would go blind to it
+// and clip the deck; grid-stacking avoids that trap. Inactive slides stay laid
+// out (so they keep sizing the track) but are visibility:hidden — out of the tab
+// order and the a11y tree — until they become `.on`.
 const SLIDES_CSS = `
-.deck{display:block}
-.deck>.slide{display:none}
-.deck>.slide.on{display:block;min-height:140px}
+.deck{display:grid;min-height:140px}
+.deck>.slide{grid-area:1/1;opacity:0;visibility:hidden;pointer-events:none;transition:opacity .3s ease,visibility 0s linear .3s}
+.deck>.slide.on{opacity:1;visibility:visible;pointer-events:auto;transition:opacity .3s ease}
+@media (prefers-reduced-motion:reduce){.deck>.slide{transition:none}}
 .deck>.slide h2{font:500 22px/1.3 var(--font-sans);margin:0 0 14px}
 .deck-ctl{display:flex;align-items:center;justify-content:center;gap:14px;margin-top:18px;padding-top:14px;border-top:1px solid var(--color-border-secondary)}
 .deck-dots{display:inline-flex;gap:7px}
@@ -110,7 +122,7 @@ export const KITS: Kit[] = [
   {
     id: "slides",
     label: "Slides",
-    summary: "a stepped deck with prev/next controls and a counter",
+    summary: "a stepped, cross-fading deck with prev/next controls and a counter",
     classes: "deck · slide (+ injected controls)",
     css: SLIDES_CSS,
     js: SLIDES_JS,
diff --git a/test/kits.test.ts b/test/kits.test.ts
index c39b613..87bdb2f 100644
--- a/test/kits.test.ts
+++ b/test/kits.test.ts
@@ -36,6 +36,17 @@ test("only behavior kits ship js", () => {
   assert.equal(kitAssets(["issues"]).js, "");
 });
 
+test("slides kit grid-stacks in normal flow (measurable height), never an absolute overlay", () => {
+  // A cross-fade deck must overlap its slides IN FLOW (grid-stack) so the deck
+  // sizes to the tallest slide and the frame's box-watching ResizeObserver can
+  // see it. An absolute overlay grows scrollHeight without growing the box, so
+  // the frame goes blind and clips the deck — the exact regression this guards.
+  const { css } = kitAssets(["slides"]);
+  assert.match(css, /\.deck\{[^}]*display:grid/); // container grid-stacks
+  assert.match(css, /\.deck>\.slide\{[^}]*grid-area:1\/1/); // children share one cell
+  assert.doesNotMatch(css, /\.deck>\.slide[^}]*position:absolute/); // never out of flow
+});
+
 test("isKnownKit gates on the registry", () => {
   assert.ok(isKnownKit("issues"));
   assert.ok(!isKnownKit("issue"));

From 67636b241716acca9f59a53dd4e9e9cb54a18424 Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Wed, 1 Jul 2026 18:03:28 -0400
Subject: [PATCH 2/2] chore: add changeset for slides-kit cross-fade fix

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/slides-kit-crossfade.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 .changeset/slides-kit-crossfade.md

diff --git a/.changeset/slides-kit-crossfade.md b/.changeset/slides-kit-crossfade.md
new file mode 100644
index 0000000..120c589
--- /dev/null
+++ b/.changeset/slides-kit-crossfade.md
@@ -0,0 +1,12 @@
+---
+"sideshow": patch
+---
+
+Slides kit now grid-stacks its deck so it cross-fades in normal flow. Previously
+it swapped slides with `display:none`, which can't fade — so decks were hand-rolled
+with `position:absolute` slides over a `min-height` stage, an out-of-flow layout the
+surface-page height bridge can't measure (the overlay grows `scrollHeight` but not
+the box its ResizeObserver watches), leaving the frame clipped/frozen. The kit now
+stacks slides in one grid cell (in flow, sized to the tallest slide) and fades with
+opacity/visibility, so the frame follows it. DESIGN_GUIDE documents the out-of-flow
+trap and the grid-stack recipe alongside the existing `position: fixed` ban.