@gjsify/adwaita-storybook 0.38.0 → 0.39.0

package/lib/types/preview-scroll.spec.d.ts

@@ -0,0 +1,2 @@
+import '@gjsify/adwaita-web';
+export declare const AdwStorybookPreviewScrollTest: () => Promise<void>;

package/lib/types/story-element.d.ts

@@ -6,7 +6,7 @@ export type StoryArgsListener = (args: StoryArgs) => void;
  * Base class for browser story elements.
  *
  * Provides default chrome — a clamped boxed group with a title + description above a
- * centered, dashed-framed preview stage. Simple stories compose their preview by
+ * centered, tinted preview stage. Simple stories compose their preview by
  * calling {@link addContent}; a subclass needing a bespoke layout passes its own root
  * element to the constructor, and {@link addContent} is then a no-op.
  */

package/lib/types/styles.d.ts

@@ -1,3 +1,3 @@
-export declare const STORYBOOK_WEB_CSS = "\n/* Appearance dialog \u2014 round swatches with a selection ring. The web twin of the GTK\n   renderer's rules, themselves adapted from Learn6502.\n\n   The CARD is not decoration: in the dark scheme the \"dark\" swatch is a near-black\n   circle on a near-black dialog and is invisible without a lighter surface behind\n   it. Centring happens INSIDE the full-width card, so the row does not read as\n   left-aligned under the group title. */\n.sb-swatch-card {\n    display: flex;\n    flex-wrap: wrap;\n    justify-content: center;\n    gap: 8px;\n    padding: 12px;\n}\n/* Squaring the card's top alone leaves a notch: the row above lives in the group's\n   own rounded list, so BOTH sides have to be squared for the join to read as one\n   list. The attached card and the group rule below are the two halves of that. */\n.sb-swatch-card--attached {\n    border-top-left-radius: 0;\n    border-top-right-radius: 0;\n}\n.sb-attached-group .boxed-list {\n    border-bottom-left-radius: 0;\n    border-bottom-right-radius: 0;\n}\n/* Desaturated rather than merely dimmed: while the accent follows the desktop the\n   palette must read as unavailable, not as nine slightly faded choices. */\n.sb-swatch-card--disabled {\n    filter: saturate(0.4) brightness(1.05);\n    opacity: 0.7;\n}\n/* A radio input, so grouping and arrow-key navigation are the platform's. Its own\n   glyph is switched off because the swatch IS the indicator \u2014 a dot drawn on a\n   colour competes with the ring that already says which one is selected. */\n.sb-swatch {\n    appearance: none;\n    -webkit-appearance: none;\n    margin: 0;\n    width: 24px;\n    height: 24px;\n    border-radius: 9999px;\n    box-shadow: 0 0 0 3px transparent;\n    cursor: pointer;\n    /* A hairline on the fill itself. Without it the LIGHT scheme swatch is a\n       near-white circle on a near-white card and vanishes \u2014 the exact mirror of the\n       dark swatch on a dark dialog, and a card alone only fixes one direction.\n       --border-color is a currentColor mix, so it holds in both schemes. */\n    border: 1px solid var(--border-color);\n}\n.sb-swatch:checked {\n    box-shadow: 0 0 0 3px var(--accent-bg-color);\n}\n.sb-swatch:focus-visible {\n    outline: 2px solid var(--accent-color);\n    outline-offset: 3px;\n}\n.sb-swatch:disabled {\n    cursor: default;\n}\n/* The scheme swatches are larger \u2014 they are the dialog's primary choice. */\n.sb-swatch--scheme {\n    width: 44px;\n    height: 44px;\n}\n/* \"Follow system\" is the two schemes meeting on a diagonal, so the option looks like\n   what it does instead of needing a word for it. */\n/* light_2 / dark_4 from libadwaita's palette (_palette.scss:37,44), which is what\n   Learn6502's selector uses. NOT light_1 (#ffffff): pure white is invisible against\n   a light card even with the hairline, and light_2 is the shade the palette offers\n   for exactly this. */\n.sb-swatch--scheme-system {\n    background: linear-gradient(to bottom right, #f6f5f4 49.99%, #241f31 50.01%);\n}\n.sb-swatch--scheme-light {\n    background-color: #f6f5f4;\n}\n.sb-swatch--scheme-dark {\n    background-color: #241f31;\n}\n\n.sb-window {\n    width: 100%;\n    height: 100%;\n    min-width: 0;\n    min-height: 0;\n}\n\n/* Each pane in the outer split view is a flex column that fills its height. */\n.sb-sidebar-pane,\n.sb-content-pane {\n    display: flex;\n    flex-direction: column;\n    min-height: 0;\n    min-width: 0;\n    flex: 1 1 auto;\n}\n\n/* The toolbar-view content holds either a scroller (sidebar) or the split view\n   (content); the inner panes own the scrolling, so this level never scrolls. */\n.sb-sidebar-pane adw-toolbar-view > .adw-toolbar-view-content,\n.sb-content-pane adw-toolbar-view > .adw-toolbar-view-content {\n    overflow: hidden;\n}\n\n/* Background scheme: the content header + preview + controls all sit on the\n   window (story) background as one surface; only the left story-list column\n   (its header + list) keeps the distinct sidebar shade. Matches the native\n   renderer. The default adw-header-bar background is its own headerbar shade,\n   so override it per pane here. */\n.sb-content-pane adw-header-bar {\n    background-color: var(--window-bg-color);\n}\n.sb-sidebar-pane adw-header-bar {\n    background-color: var(--sidebar-bg-color);\n}\n\n.sb-sidebar-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    overflow-y: auto;\n    background-color: var(--sidebar-bg-color);\n}\n\n/* --- Story list (mirrors GTK .navigation-sidebar) --- */\n.sb-sidebar-list {\n    padding: var(--spacing-xs);\n    display: flex;\n    flex-direction: column;\n    gap: 1px;\n}\n\n.sb-category {\n    font-size: var(--font-size-small);\n    font-weight: 700;\n    opacity: var(--dim-opacity);\n    padding: 10px var(--spacing-m) 4px;\n}\n\n.sb-story-row {\n    padding: var(--spacing-xs) var(--spacing-m);\n    margin: 0 var(--spacing-xs);\n    border-radius: var(--button-radius);\n    cursor: pointer;\n    color: var(--window-fg-color);\n    font-size: var(--font-size-base);\n    white-space: nowrap;\n    overflow: hidden;\n    text-overflow: ellipsis;\n}\n\n.sb-story-row:hover {\n    background-color: var(--button-bg-color);\n}\n\n.sb-story-row.selected {\n    background-color: var(--accent-bg-color);\n    color: var(--accent-fg-color);\n}\n\n/* --- Preview area --- */\n.sb-preview-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    min-width: 0;\n    overflow: auto;\n    background-color: var(--window-bg-color);\n}\n\n.sb-story-page {\n    display: flex;\n    justify-content: center;\n    padding: var(--spacing-xl) var(--spacing-m);\n    min-height: 100%;\n    box-sizing: border-box;\n}\n\n.sb-story-clamp {\n    width: 100%;\n    max-width: 600px;\n}\n\n.sb-story-group-header {\n    padding: var(--spacing-xs) 2px;\n    display: flex;\n    flex-direction: column;\n    gap: 2px;\n}\n\n.sb-story-group-title {\n    font-size: var(--font-size-heading);\n    font-weight: 700;\n    color: var(--window-fg-color);\n}\n\n.sb-story-group-description {\n    font-size: var(--font-size-base);\n    opacity: var(--dim-opacity);\n    color: var(--window-fg-color);\n}\n\n/* Centered, dashed-framed preview stage (mirrors the native .story-stage). */\n.story-stage {\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    justify-content: center;\n    gap: var(--spacing-m);\n    padding: var(--spacing-l);\n    margin-top: var(--spacing-s);\n    border: 1px dashed rgba(127, 127, 127, 0.28);\n    border-radius: var(--card-radius);\n    min-height: 80px;\n}\n\n/* --- Controls panel --- */\n.sb-controls-scroll {\n    height: 100%;\n    overflow-y: auto;\n    background-color: var(--window-bg-color);\n}\n\n.sb-controls-page {\n    padding: var(--spacing-l);\n}\n\n/* Range-control card (mirrors the native .story-range-row). */\n.sb-range-row {\n    display: flex;\n    flex-direction: column;\n    gap: var(--spacing-xs);\n    padding: var(--spacing-m);\n    border-bottom: 1px solid var(--card-shade-color);\n}\n\n.sb-range-row:last-child {\n    border-bottom: none;\n}\n\n.sb-range-header {\n    display: flex;\n    justify-content: space-between;\n    align-items: baseline;\n    gap: var(--spacing-m);\n}\n\n.sb-range-title {\n    font-size: var(--font-size-base);\n    font-weight: 700;\n    color: var(--card-fg-color);\n}\n\n.sb-range-value {\n    font-size: var(--font-size-base);\n    font-variant-numeric: tabular-nums;\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-description {\n    font-size: var(--font-size-small);\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-input {\n    width: 100%;\n    accent-color: var(--accent-bg-color);\n}\n\n.sb-color-input {\n    width: 42px;\n    height: 28px;\n    padding: 0;\n    border: 1px solid var(--card-shade-color);\n    border-radius: var(--button-radius);\n    background: none;\n    cursor: pointer;\n}\n";
+export declare const STORYBOOK_WEB_CSS = "\n/* Appearance dialog \u2014 round swatches with a selection ring. The web twin of the GTK\n   renderer's rules, themselves adapted from Learn6502.\n\n   The CARD is not decoration: in the dark scheme the \"dark\" swatch is a near-black\n   circle on a near-black dialog and is invisible without a lighter surface behind\n   it. Centring happens INSIDE the full-width card, so the row does not read as\n   left-aligned under the group title. */\n.sb-swatch-card {\n    display: flex;\n    flex-wrap: wrap;\n    justify-content: center;\n    gap: 8px;\n    padding: 12px;\n}\n/* Squaring the card's top alone leaves a notch: the row above lives in the group's\n   own rounded list, so BOTH sides have to be squared for the join to read as one\n   list. The attached card and the group rule below are the two halves of that. */\n.sb-swatch-card--attached {\n    border-top-left-radius: 0;\n    border-top-right-radius: 0;\n}\n.sb-attached-group .boxed-list {\n    border-bottom-left-radius: 0;\n    border-bottom-right-radius: 0;\n}\n/* Desaturated rather than merely dimmed: while the accent follows the desktop the\n   palette must read as unavailable, not as nine slightly faded choices. */\n.sb-swatch-card--disabled {\n    filter: saturate(0.4) brightness(1.05);\n    opacity: 0.7;\n}\n/* A radio input, so grouping and arrow-key navigation are the platform's. Its own\n   glyph is switched off because the swatch IS the indicator \u2014 a dot drawn on a\n   colour competes with the ring that already says which one is selected. */\n.sb-swatch {\n    appearance: none;\n    -webkit-appearance: none;\n    margin: 0;\n    width: 24px;\n    height: 24px;\n    border-radius: 9999px;\n    box-shadow: 0 0 0 3px transparent;\n    cursor: pointer;\n    /* A hairline on the fill itself. Without it the LIGHT scheme swatch is a\n       near-white circle on a near-white card and vanishes \u2014 the exact mirror of the\n       dark swatch on a dark dialog, and a card alone only fixes one direction.\n       --border-color is a currentColor mix, so it holds in both schemes. */\n    border: 1px solid var(--border-color);\n}\n.sb-swatch:checked {\n    box-shadow: 0 0 0 3px var(--accent-bg-color);\n}\n.sb-swatch:focus-visible {\n    outline: 2px solid var(--accent-color);\n    outline-offset: 3px;\n}\n.sb-swatch:disabled {\n    cursor: default;\n}\n/* The scheme swatches are larger \u2014 they are the dialog's primary choice. */\n.sb-swatch--scheme {\n    width: 44px;\n    height: 44px;\n}\n/* \"Follow system\" is the two schemes meeting on a diagonal, so the option looks like\n   what it does instead of needing a word for it. */\n/* light_2 / dark_4 from libadwaita's palette (_palette.scss:37,44), which is what\n   Learn6502's selector uses. NOT light_1 (#ffffff): pure white is invisible against\n   a light card even with the hairline, and light_2 is the shade the palette offers\n   for exactly this. */\n.sb-swatch--scheme-system {\n    background: linear-gradient(to bottom right, #f6f5f4 49.99%, #241f31 50.01%);\n}\n.sb-swatch--scheme-light {\n    background-color: #f6f5f4;\n}\n.sb-swatch--scheme-dark {\n    background-color: #241f31;\n}\n\n.sb-window {\n    width: 100%;\n    height: 100%;\n    min-width: 0;\n    min-height: 0;\n}\n\n/* Each pane in the outer split view is a flex column that fills its height. */\n.sb-sidebar-pane,\n.sb-content-pane {\n    display: flex;\n    flex-direction: column;\n    min-height: 0;\n    min-width: 0;\n    flex: 1 1 auto;\n}\n\n/* The toolbar-view content holds either a scroller (sidebar) or the split view\n   (content); the inner panes own the scrolling, so this level never scrolls. */\n.sb-sidebar-pane adw-toolbar-view > .adw-toolbar-view-content,\n.sb-content-pane adw-toolbar-view > .adw-toolbar-view-content {\n    overflow: hidden;\n}\n\n/* Background scheme: the content header + preview + controls all sit on the\n   window (story) background as one surface; only the left story-list column\n   (its header + list) keeps the distinct sidebar shade. Matches the native\n   renderer. The default adw-header-bar background is its own headerbar shade,\n   so override it per pane here. */\n.sb-content-pane adw-header-bar {\n    background-color: var(--window-bg-color);\n}\n.sb-sidebar-pane adw-header-bar {\n    background-color: var(--sidebar-bg-color);\n}\n\n.sb-sidebar-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    overflow-y: auto;\n    background-color: var(--sidebar-bg-color);\n}\n\n/* --- Story list (mirrors GTK .navigation-sidebar) --- */\n.sb-sidebar-list {\n    padding: var(--spacing-xs);\n    display: flex;\n    flex-direction: column;\n    gap: 1px;\n}\n\n.sb-category {\n    font-size: var(--font-size-small);\n    font-weight: 700;\n    opacity: var(--dim-opacity);\n    padding: 10px var(--spacing-m) 4px;\n}\n\n.sb-story-row {\n    padding: var(--spacing-xs) var(--spacing-m);\n    margin: 0 var(--spacing-xs);\n    border-radius: var(--button-radius);\n    cursor: pointer;\n    color: var(--window-fg-color);\n    font-size: var(--font-size-base);\n    white-space: nowrap;\n    overflow: hidden;\n    text-overflow: ellipsis;\n}\n\n.sb-story-row:hover {\n    background-color: var(--button-bg-color);\n}\n\n.sb-story-row.selected {\n    background-color: var(--accent-bg-color);\n    color: var(--accent-fg-color);\n}\n\n/* --- Preview area --- */\n\n/* The slotted content pane has to PASS ITS BOUND DOWN, or the scroller below it has\n   nothing to scroll against.\n\n   Measured before this rule existed: .adw-osv-content bounded itself correctly at\n   697px while its content wanted 1008px, but this div \u2014 display: block,\n   min-height: auto, flex: 0 1 auto \u2014 ignored that and grew to 1008. So\n   .sb-preview-scroll inherited clientHeight === scrollHeight, had nothing to scroll,\n   and everything past the fold was clipped by the toolbar view's overflow: hidden:\n   a tall story just ended mid-page.\n\n   The sidebar never had this. Its scroller sits directly inside the toolbar view's own\n   flex content wrapper, so nothing breaks the chain there; this pane is the one place\n   a plain div sits between the bound and the scroller.\n\n   NOTE: no backticks in this file's comments \u2014 the whole stylesheet is a JS template\n   literal, so a backtick ends it and the parse error lands nine lines away. */\n.sb-preview-pane {\n    display: flex;\n    flex-direction: column;\n    flex: 1 1 auto;\n    min-height: 0;\n    min-width: 0;\n}\n\n/* The tint belongs to the whole preview AREA, not to a box inside it. On the website\n   it sits on the preview panel and the stage within is only centring; on the stage it\n   drew a grey rectangle floating in the pane with no defined edge, which is how it read.\n\n   HERE and not on .sb-preview-pane, measured: this element paints an OPAQUE\n   background-color, so a gradient one level up is covered completely. Sampling five\n   points across the pane returned the identical colour while the computed style still\n   reported a background-image \u2014 true and meaningless.\n\n   A background on a scroll container is painted against its padding box, so it stays\n   put while the content scrolls, the way a wallpaper does. */\n.sb-preview-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    min-width: 0;\n    overflow: auto;\n    background-color: var(--window-bg-color);\n    background-image:\n        radial-gradient(circle at 0% 0%, color-mix(in srgb, var(--accent-color) 7%, transparent), transparent 45%),\n        radial-gradient(circle at 100% 100%, color-mix(in srgb, #926ee4 6%, transparent), transparent 45%);\n}\n\n.sb-story-page {\n    display: flex;\n    justify-content: center;\n    padding: var(--spacing-xl) var(--spacing-m);\n    min-height: 100%;\n    box-sizing: border-box;\n}\n\n.sb-story-clamp {\n    width: 100%;\n    max-width: 600px;\n}\n\n.sb-story-group-header {\n    padding: var(--spacing-xs) 2px;\n    display: flex;\n    flex-direction: column;\n    gap: 2px;\n}\n\n.sb-story-group-title {\n    font-size: var(--font-size-heading);\n    font-weight: 700;\n    color: var(--window-fg-color);\n}\n\n.sb-story-group-description {\n    font-size: var(--font-size-base);\n    opacity: var(--dim-opacity);\n    color: var(--window-fg-color);\n}\n\n/* Centring and breathing room only \u2014 the surface is the pane's.\n\n   The stage carried the tint first, and against the pane's own background that read\n   as a grey rectangle floating with no edge rather than as a surface. It has no\n   border-radius for the same reason: nothing here is a box any more.\n\n   The requirement the tint answers is unchanged \u2014 the preview area stays locatable\n   when the widget on it is transparent or empty \u2014 it is just answered by the AREA\n   now instead of by a rectangle inside it. Scheme handling moved with it, see\n   .sb-preview-pane. */\n.story-stage {\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    justify-content: center;\n    gap: var(--spacing-m);\n    padding: var(--spacing-l);\n    margin-top: var(--spacing-s);\n    min-height: 80px;\n}\n\n/* --- Controls panel --- */\n.sb-controls-scroll {\n    height: 100%;\n    overflow-y: auto;\n    background-color: var(--window-bg-color);\n}\n\n.sb-controls-page {\n    padding: var(--spacing-l);\n}\n\n/* Range-control card (mirrors the native .story-range-row). */\n.sb-range-row {\n    display: flex;\n    flex-direction: column;\n    gap: var(--spacing-xs);\n    padding: var(--spacing-m);\n    border-bottom: 1px solid var(--card-shade-color);\n}\n\n.sb-range-row:last-child {\n    border-bottom: none;\n}\n\n.sb-range-header {\n    display: flex;\n    justify-content: space-between;\n    align-items: baseline;\n    gap: var(--spacing-m);\n}\n\n.sb-range-title {\n    font-size: var(--font-size-base);\n    font-weight: 700;\n    color: var(--card-fg-color);\n}\n\n.sb-range-value {\n    font-size: var(--font-size-base);\n    font-variant-numeric: tabular-nums;\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-description {\n    font-size: var(--font-size-small);\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-input {\n    width: 100%;\n    accent-color: var(--accent-bg-color);\n}\n\n.sb-color-input {\n    width: 42px;\n    height: 28px;\n    padding: 0;\n    border: 1px solid var(--card-shade-color);\n    border-radius: var(--button-radius);\n    background: none;\n    cursor: pointer;\n}\n";
 /** Inject the chrome stylesheet once (idempotent, browser-only). */
 export declare function injectStorybookStyles(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-storybook",
-    "version": "0.38.0",
+    "version": "0.39.0",
     "description": "Browser renderer for the @gjsify/stories contract — the web counterpart of @gjsify/storybook, built on @gjsify/adwaita-web",
     "type": "module",
     "main": "./src/index.ts",
@@ -19,7 +19,8 @@
         "clear": "gjsify clear lib tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
         "build": "gjsify run build:types",
-        "build:types": "gjsify tsc"
+        "build:types": "gjsify tsc",
+        "build:test:browser": "gjsify build src/test.browser.mts --app browser --outfile dist/test.browser.mjs"
     },
     "keywords": [
         "storybook",
@@ -29,13 +30,13 @@
         "browser"
     ],
     "dependencies": {
-        "@gjsify/adwaita-core": "^0.38.0",
-        "@gjsify/adwaita-web": "^0.38.0",
-        "@gjsify/stories": "^0.38.0",
-        "@gjsify/storybook-core": "^0.38.0"
+        "@gjsify/adwaita-core": "^0.39.0",
+        "@gjsify/adwaita-web": "^0.39.0",
+        "@gjsify/stories": "^0.39.0",
+        "@gjsify/storybook-core": "^0.39.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.38.0",
+        "@gjsify/cli": "^0.39.0",
         "typescript": "^6.0.3"
     },
     "gjsify": {

package/src/preview-scroll.spec.ts

@@ -0,0 +1,127 @@
+// Where the preview area's scroll BOUND actually lands.
+//
+// WHY THIS IS THE FIRST TEST IN THIS PACKAGE. The web preview stopped scrolling
+// entirely: a tall story ended mid-page and nothing below was reachable. Every
+// layer's CSS was individually valid — the overlay split view held itself to the
+// window height, the scroller declared overflow: auto and min-height: 0 — but the
+// slotted pane between them had no rule in this target, so it grew to the content's
+// height and handed the scroller a bound equal to its own content. clientHeight ===
+// scrollHeight, nothing to scroll, remainder clipped by an overflow: hidden further
+// up.
+//
+// Nothing could have caught that by reading state or class names, which is all the
+// sibling suites do. The rule this encodes: a layout has to be asserted by WHERE
+// things land — measure the box, not the declaration.
+//
+// Runs in the tests/browser Playwright harness, which drives FIREFOX in CI, not just
+// Chromium.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+// Registers the custom elements the storybook chrome is built from, and injects the
+// adwaita-web stylesheet. Without it the panes are unstyled inline boxes and every
+// measurement below would be meaningless rather than wrong.
+import '@gjsify/adwaita-web';
+
+import type { StoryMeta } from '@gjsify/stories';
+import { StoryElement } from './story-element.js';
+import { mountStorybook } from './app.js';
+import type { WebStoryModule } from './types.js';
+
+/** A story deliberately taller than any host we mount it in. */
+class TallStory extends StoryElement {
+    constructor() {
+        super(TallStory.getMetadata(), 'Default');
+    }
+
+    /** Part of the authoring contract the registry instantiates through. */
+    static getMetadata(): StoryMeta {
+        return { title: 'Probe/Tall', description: 'taller than its host on purpose', controls: [] };
+    }
+
+    initialize(): void {
+        const filler = document.createElement('div');
+        filler.style.height = '1600px';
+        filler.style.width = '100%';
+        this.addContent(filler);
+    }
+}
+
+const HOST_HEIGHT = 600;
+
+/** Mount the storybook in a fixed-height host and hand back its preview scroller. */
+function mountTall(): { host: HTMLElement; scroller: HTMLElement } {
+    const host = document.createElement('div');
+    // A definite height, because that is the whole question: the real page gives the
+    // window one and the chain has to carry it down.
+    host.style.height = `${HOST_HEIGHT}px`;
+    host.style.width = '900px';
+    document.body.append(host);
+
+    const module: WebStoryModule = { stories: [TallStory] };
+    mountStorybook(host, { stories: [module], title: 'Probe' });
+
+    const scroller = host.querySelector('.sb-preview-scroll') as HTMLElement | null;
+    if (!scroller) throw new Error('no .sb-preview-scroll after mount — the chrome changed shape');
+    return { host, scroller };
+}
+
+export const AdwStorybookPreviewScrollTest = async () => {
+    await describe('storybook preview scrolling', async () => {
+        await it('bounds the scroller by its host rather than by its content', () => {
+            const { host, scroller } = mountTall();
+            try {
+                // The defect in one assertion: the scroller was 1008px tall inside a
+                // 697px bound because the pane above it ignored the bound.
+                expect(scroller.clientHeight).toBeLessThan(HOST_HEIGHT);
+                expect(scroller.clientHeight).toBeGreaterThan(0);
+            } finally {
+                host.remove();
+            }
+        });
+
+        await it('can actually scroll when the story is taller than the host', () => {
+            const { host, scroller } = mountTall();
+            try {
+                expect(scroller.scrollHeight).toBeGreaterThan(scroller.clientHeight);
+            } finally {
+                host.remove();
+            }
+        });
+
+        await it('reaches the bottom of the story', () => {
+            // Being scrollable is not the same as being able to READ the end: an
+            // ancestor clipping at the fold satisfies the two assertions above while
+            // the last rows stay unreachable.
+            const { host, scroller } = mountTall();
+            try {
+                scroller.scrollTop = scroller.scrollHeight;
+                expect(scroller.scrollTop).toBeGreaterThan(0);
+                const reached = scroller.scrollTop + scroller.clientHeight;
+                expect(reached).toBeGreaterThan(scroller.scrollHeight - 2);
+            } finally {
+                host.remove();
+            }
+        });
+
+        await it('keeps every layer between the bound and the scroller collapsible', () => {
+            // The named cause, so a future regression says WHICH layer broke instead of
+            // only that scrolling stopped. min-height: auto on any of them re-creates
+            // the defect exactly.
+            const { host, scroller } = mountTall();
+            try {
+                let el: HTMLElement | null = scroller;
+                const offenders: string[] = [];
+                while (el && el !== host) {
+                    const style = getComputedStyle(el);
+                    if (style.minHeight !== '0px' && style.minHeight !== '0')
+                        offenders.push(`${el.tagName.toLowerCase()}.${String(el.className || '-').split(' ')[0]}`);
+                    el = el.parentElement;
+                }
+                expect(offenders).toStrictEqual([]);
+            } finally {
+                host.remove();
+            }
+        });
+    });
+};

package/src/story-element.ts

@@ -15,7 +15,7 @@ export type StoryArgsListener = (args: StoryArgs) => void;
  * Base class for browser story elements.
  *
  * Provides default chrome — a clamped boxed group with a title + description above a
- * centered, dashed-framed preview stage. Simple stories compose their preview by
+ * centered, tinted preview stage. Simple stories compose their preview by
  * calling {@link addContent}; a subclass needing a bespoke layout passes its own root
  * element to the constructor, and {@link addContent} is then a no-op.
  */

package/src/styles.ts

@@ -163,12 +163,51 @@ export const STORYBOOK_WEB_CSS = `
 }
 
 /* --- Preview area --- */
+
+/* The slotted content pane has to PASS ITS BOUND DOWN, or the scroller below it has
+   nothing to scroll against.
+
+   Measured before this rule existed: .adw-osv-content bounded itself correctly at
+   697px while its content wanted 1008px, but this div — display: block,
+   min-height: auto, flex: 0 1 auto — ignored that and grew to 1008. So
+   .sb-preview-scroll inherited clientHeight === scrollHeight, had nothing to scroll,
+   and everything past the fold was clipped by the toolbar view's overflow: hidden:
+   a tall story just ended mid-page.
+
+   The sidebar never had this. Its scroller sits directly inside the toolbar view's own
+   flex content wrapper, so nothing breaks the chain there; this pane is the one place
+   a plain div sits between the bound and the scroller.
+
+   NOTE: no backticks in this file's comments — the whole stylesheet is a JS template
+   literal, so a backtick ends it and the parse error lands nine lines away. */
+.sb-preview-pane {
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 auto;
+    min-height: 0;
+    min-width: 0;
+}
+
+/* The tint belongs to the whole preview AREA, not to a box inside it. On the website
+   it sits on the preview panel and the stage within is only centring; on the stage it
+   drew a grey rectangle floating in the pane with no defined edge, which is how it read.
+
+   HERE and not on .sb-preview-pane, measured: this element paints an OPAQUE
+   background-color, so a gradient one level up is covered completely. Sampling five
+   points across the pane returned the identical colour while the computed style still
+   reported a background-image — true and meaningless.
+
+   A background on a scroll container is painted against its padding box, so it stays
+   put while the content scrolls, the way a wallpaper does. */
 .sb-preview-scroll {
     flex: 1 1 auto;
     min-height: 0;
     min-width: 0;
     overflow: auto;
     background-color: var(--window-bg-color);
+    background-image:
+        radial-gradient(circle at 0% 0%, color-mix(in srgb, var(--accent-color) 7%, transparent), transparent 45%),
+        radial-gradient(circle at 100% 100%, color-mix(in srgb, #926ee4 6%, transparent), transparent 45%);
 }
 
 .sb-story-page {
@@ -203,7 +242,16 @@ export const STORYBOOK_WEB_CSS = `
     color: var(--window-fg-color);
 }
 
-/* Centered, dashed-framed preview stage (mirrors the native .story-stage). */
+/* Centring and breathing room only — the surface is the pane's.
+
+   The stage carried the tint first, and against the pane's own background that read
+   as a grey rectangle floating with no edge rather than as a surface. It has no
+   border-radius for the same reason: nothing here is a box any more.
+
+   The requirement the tint answers is unchanged — the preview area stays locatable
+   when the widget on it is transparent or empty — it is just answered by the AREA
+   now instead of by a rectangle inside it. Scheme handling moved with it, see
+   .sb-preview-pane. */
 .story-stage {
     display: flex;
     flex-direction: column;
@@ -212,8 +260,6 @@ export const STORYBOOK_WEB_CSS = `
     gap: var(--spacing-m);
     padding: var(--spacing-l);
     margin-top: var(--spacing-s);
-    border: 1px dashed rgba(127, 127, 127, 0.28);
-    border-radius: var(--card-radius);
     min-height: 80px;
 }
 

package/src/test.browser.mts

@@ -0,0 +1,12 @@
+// Browser test entry for @gjsify/adwaita-storybook. Discovered and run by the
+// tests/browser Playwright harness (see AGENTS.md → Browser tests), which drives
+// Firefox in CI.
+//
+// This package had no test entry at all until the preview stopped scrolling — its
+// output is layout, and layout is the one thing a state-and-class-names assertion
+// cannot see.
+import { run } from '@gjsify/unit';
+
+import { AdwStorybookPreviewScrollTest } from './preview-scroll.spec.js';
+
+run({ AdwStorybookPreviewScrollTest });