@krapwoo/ds-viewer 0.4.9 → 0.5.0

package/README.md

@@ -272,6 +272,28 @@ actually apply:
   in an iPhone SE viewport (375 × 667 points), scaled down only when its cell is narrower. In the
   browser viewer it opens that example in its own device-sized document, so overlays that portal
   to the page (React Native's `Modal`) open inside the phone, not over the catalog.
+- **`OverlayDemo`** — a phone with a catalog button that opens an overlay. Children get
+  `{ open, close }`; keep the overlay mounted and drive its own `visible` from `open`, so its
+  animations play. `keepTrigger` makes the button a toggle; `triggerLabel` can follow the state;
+  `initiallyOpen` starts it open.
+  ```tsx
+  <OverlayDemo triggerLabel="Open sheet">
+    {({ open, close }) => (
+      <BottomSheet visible={open} onDismiss={close} footer={<Dock><Button label="Confirm" onPress={close} /></Dock>}>
+        …
+      </BottomSheet>
+    )}
+  </OverlayDemo>
+  ```
+- **`PhoneScreen`** — a whole app screen inside a `PhoneFrame`: `header` stays at the top,
+  `footer` at the phone's bottom, and the children scroll between them instead of pushing the
+  footer off the screen. `floating` is a layer over the top for toasts (position its content
+  yourself); `bodyWrapper` puts your own surface around the scrolling body.
+  ```tsx
+  <PhoneFrame>
+    <PhoneScreen header={<TopNav title="Saved trips" />} footer={<Dock>…</Dock>}>…</PhoneScreen>
+  </PhoneFrame>
+  ```
 - Full-width (`itemsFill`) variants and states wrap at most **3** across; set `maxColumns` to
   change that. A filled example that keeps its own fixed width is centred in its cell.
   Default to one preview; add a second width only when a narrower (or wider) viewport actually
@@ -463,6 +485,27 @@ Button
   dynamically-constructed references remain uncheckable rather than being guessed at. A
   declared `intentionalStaticPreview` is taken as the author's own call, not independently
   verified; only a real browser check confirms actual behavior.
+- `overlay-without-device-frame` (warning) — the component imports React Native's `Modal`, which
+  opens over the whole catalog page on the web, but its page imports no `PhoneFrame`,
+  `OverlayDemo`, `PhoneScreen` or `BoundedOverlayViewport`. Conservative: it can't see
+  `import * as RN`, a re-exported `Modal`, or a Modal opened by a sub-component.
+
+### `doctor --render`
+
+`npx ds-viewer doctor --render` also starts the viewer, opens every page in a headless browser,
+and adds what only a real render shows:
+
+- `render-error` / `render-no-heading` (errors): a console error, or a page that didn't render.
+- `render-layout` (warning): an example wider than its cell (the viewer's own check), with the
+  page and file. `render-catalog-warning` (warning): any other `[Catalog]` warning, reported once.
+- `render-unavailable` / `render-failed` (errors): no browser, or the catalog didn't start.
+
+It needs `puppeteer` in your project (`npm install --save-dev puppeteer`); ds-viewer doesn't
+install a browser. It takes about two minutes for 50 pages and works with `--json` (progress
+goes to stderr), `--ci` and `doctor.strict`, so CI can run `npx ds-viewer doctor --render --ci`.
+It stops the viewer it started, including on Ctrl-C (exit codes 130, 143 or 129 for SIGINT,
+SIGTERM or SIGHUP). On Windows it stops the viewer with `taskkill`; that path is unit-tested, not
+run on a real Windows machine.
 
 ## Known gaps
 

package/dist/cli/doctor.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
 import { readHostTsconfigOptions } from "./props.js";
-import { readStaticPages } from "./staticPage.js";
+import { importedNames, readStaticPages } from "./staticPage.js";
 import { resolveGlob } from "./glob.js";
 import { sync } from "./sync.js";
 import { gridColumnLimit } from "../native/catalog/comparison.js";
@@ -208,6 +208,43 @@ function checkMissingComposition(pages, components) {
     }
     return issues;
 }
+/** The viewer exports that frame an example as a phone (or another bounded document), so an
+ *  overlay that portals to the document body opens inside it instead of over the catalog. */
+const DEVICE_FRAME_EXPORTS = ['PhoneFrame', 'OverlayDemo', 'PhoneScreen', 'BoundedOverlayViewport'];
+/** Whether a component's own source imports React Native's `Modal` (by its imported name, so an
+ *  alias still counts and an unrelated local `Modal` doesn't). Conservative by design: it can't see
+ *  `import * as RN`, a re-exported `Modal`, or a Modal opened by a sub-component. */
+function importsModal(file) {
+    try {
+        const source = ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.ES2022, true, ts.ScriptKind.TSX);
+        return [...importedNames(source, 'react-native').values()].includes('Modal');
+    }
+    catch {
+        return false;
+    }
+}
+/** `overlay-without-device-frame`: a page whose component opens a React Native `Modal` (which
+ *  portals to the document body on the web, covering the whole catalog) but whose page imports no
+ *  device frame. A page whose imports couldn't be read is skipped, never assumed unframed. */
+export function checkOverlaysFramed(pages, components, projectRoot) {
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const issues = [];
+    for (const page of pages) {
+        if (!page.component || page.viewerImports === undefined)
+            continue;
+        if (page.viewerImports.some((name) => DEVICE_FRAME_EXPORTS.includes(name)))
+            continue;
+        const component = byName.get(page.component);
+        if (!component || !importsModal(path.resolve(projectRoot, component.file)))
+            continue;
+        issues.push(issue({
+            id: 'overlay-without-device-frame', severity: 'warning', ...pageRef(page),
+            message: `"${component.name}" opens a React Native Modal, which covers the whole catalog page unless its example is inside a phone.`,
+            fix: 'Wrap the example in <PhoneFrame> (or use <OverlayDemo>), so it opens inside the phone.',
+        }));
+    }
+    return issues;
+}
 /** A function-typed prop's printed type always contains `=>` (`cli/props.ts`'s own displayed type
  *  strings — "(value: string) => void", "() => void", …); a plain data prop's never does. */
 function isFunctionPropType(type) {
@@ -509,6 +546,15 @@ export function checkPageTypeErrors(pages, options = {}) {
     }
     return issues;
 }
+/** Adds findings to a finished result: applies `doctor.strict`, recounts errors and warnings, and
+ *  resets the exit code. */
+export function withExtraIssues(result, extra, strict) {
+    const added = strict ? extra.map((i) => (i.severity === 'warning' ? { ...i, severity: 'error' } : i)) : extra;
+    const issues = [...result.issues, ...added];
+    const errors = issues.filter((i) => i.severity === 'error').length;
+    const summary = { ...result.summary, errors, warnings: issues.length - errors };
+    return { ...result, issues, summary, exitCode: errors > 0 ? 1 : 0 };
+}
 /** "With examples" means what `checkComponentNoExamples` (Task 4) checks the *absence* of: at
  *  least one checkable page with a real example, not merely "has a page" (an `init`-drafted
  *  "Needs examples" page has one, with none). */
@@ -572,6 +618,7 @@ export function runDoctor(config) {
     let issues = [
         ...collectIssues(pages, components),
         ...checkPageTypeErrors(pages, { fallbackPaths, hostRoot: config.projectRoot }),
+        ...checkOverlaysFramed(pages, components, config.projectRoot),
         ...collectGlobalIssues({ syncWarnings: syncResult.warnings, tokenFileCount }),
     ];
     // Design's own `--json` example gives a project-relative `file`; `StaticPage.file` is absolute
@@ -588,7 +635,8 @@ export function runDoctor(config) {
         withExamples: countWithExamples(pages, components),
         unboundExamples: countUnboundExamples(pages),
     };
-    return { version: 1, summary, update: null, issues, exitCode: summary.errors > 0 ? 1 : 0 };
+    const pageFileById = new Map(pages.map((p) => [resolvePageId(p, p.file), path.relative(config.projectRoot, p.file)]));
+    return { version: 1, summary, update: null, issues, exitCode: summary.errors > 0 ? 1 : 0, pageFiles: pageFileById };
 }
 export function toDoctorJson(result) {
     const { version, summary, update, issues } = result;

package/dist/cli/main.js

@@ -5,7 +5,8 @@ import { resolveConfig } from "./config.js";
 import { initExistingProject, initNewProject, promptInitMode } from "./init.js";
 import { dev } from "./dev.js";
 import { sync } from "./sync.js";
-import { formatHuman, runDoctor, toDoctorJson } from "./doctor.js";
+import { formatHuman, runDoctor, toDoctorJson, withExtraIssues } from "./doctor.js";
+import { renderCheck } from "./render.js";
 import { explainPage, formatExplain, parseHeights } from "./explain.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { checkForUpdate, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck } from "./updateCheck.js";
@@ -27,6 +28,7 @@ Commands:
   doctor   Check every page for drift and coverage gaps
            --json          print the machine-readable report instead
            --ci            exit 1 when any error was found (never on a warning alone)
+           --render        also open every page in a headless browser (needs puppeteer)
   explain <Page>
            Print why a page's specimens are laid out the way they are
            --heights <first>,<second>  check side-by-side placement with these measured heights
@@ -116,7 +118,14 @@ export async function runInit(projectRoot, rest, options = {}) {
  *  plain `doctor` (no `--ci`) always returns 0 here regardless of errors found. */
 export async function runDoctorCommand(projectRoot, rest, options = {}) {
     const config = resolveConfig(projectRoot);
-    const result = runDoctor(config);
+    let result = runDoctor(config);
+    // `--render`: open every page in a headless browser and add what only a real render shows.
+    // Progress goes to stderr, so `--json` output stays pure JSON.
+    if (rest.includes('--render')) {
+        const files = result.pageFiles;
+        const rendered = await (options.renderCheck ?? renderCheck)(config.projectRoot, { files, log: (line) => process.stderr.write(`${line}\n`) });
+        result = withExtraIssues(result, rendered, Boolean(config.doctor?.strict));
+    }
     // Design §4 "`--ci`: ... no update check." — `--ci` skips this whole block even when
     // `updateCheck` is otherwise enabled; `result.update` stays `null`.
     // Same precedence as the viewer: CI's environment variable, your own switch, the project config.

package/dist/cli/render.js

@@ -0,0 +1,247 @@
+// cli/render.ts — `doctor --render`: open every catalog page in a headless browser and report what
+// only a real render shows (console errors, pages that fail to render, the viewer's own [Catalog]
+// layout warnings). The browser is resolved from the project; ds-viewer never installs one.
+import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const OVERFLOW = /is \d+px wide in a \d+px cell/;
+/**
+ * Turns one page's console output into doctor findings. Console errors and a missing heading are
+ * errors. The viewer's own `[Catalog]` warnings are warnings: `render-layout` for an example that
+ * overflows its cell, `render-catalog-warning` for anything else. Other console noise (React Native
+ * web deprecations, logs) is ignored. `seen` is shared across the whole run, so a warning the
+ * catalog logs on every page (a duplicate id, an unknown `composedOf` name) is reported once.
+ */
+export function issuesFromPage(page, messages, hasHeading, seen = new Set()) {
+    const ref = { page: page.id, ...(page.file ? { file: page.file } : {}) };
+    const issues = [];
+    if (!hasHeading) {
+        issues.push({ id: 'render-no-heading', severity: 'error', ...ref, message: 'The page rendered without its heading, so it probably failed to render.', fix: 'Open the page in `ds-viewer dev` and check the browser console.' });
+    }
+    const pageErrors = new Set();
+    for (const m of messages) {
+        const first = m.text.split('\n')[0];
+        if (m.type === 'error' || m.type === 'pageerror') {
+            if (pageErrors.has(first))
+                continue;
+            pageErrors.add(first);
+            issues.push({ id: 'render-error', severity: 'error', ...ref, message: `Console error while rendering: ${first}`, fix: 'Open the page in `ds-viewer dev` and fix the error in the browser console.' });
+        }
+        else if ((m.type === 'warn' || m.type === 'warning') && first.startsWith('[Catalog] ')) {
+            const text = first.slice('[Catalog] '.length);
+            if (seen.has(text))
+                continue;
+            seen.add(text);
+            issues.push(OVERFLOW.test(text)
+                ? { id: 'render-layout', severity: 'warning', ...ref, message: text, fix: 'Give the page a wider specimenSize; see the README page guide.' }
+                : { id: 'render-catalog-warning', severity: 'warning', ...ref, message: text, fix: 'Follow the message; the static doctor rule of the same name has the details.' });
+        }
+    }
+    return issues;
+}
+/** The project's own puppeteer, or `undefined` when it isn't installed. */
+export function loadProjectPuppeteer(projectRoot) {
+    try {
+        return createRequire(path.join(path.resolve(projectRoot), 'package.json'))('puppeteer');
+    }
+    catch {
+        return undefined;
+    }
+}
+export const RENDER_UNAVAILABLE = {
+    id: 'render-unavailable',
+    severity: 'error',
+    message: "`doctor --render` needs a headless browser, and puppeteer isn't installed in this project.",
+    fix: 'npm install --save-dev puppeteer (then run doctor --render again).',
+};
+const DEV_START_TIMEOUT_MS = 120_000;
+const FIRST_LOAD_TIMEOUT_MS = 300_000;
+const PAGE_TIMEOUT_MS = 120_000;
+const SETTLE_MS = 900;
+/** Stops `dev` and everything it started (Expo/Metro): the whole process tree on Windows, the
+ *  whole process group elsewhere (Expo stops through dev's own signal handler). Releases the pipes
+ *  so this process can exit. `os` is injectable for tests. */
+export function stopDev(child, os = {}) {
+    const platform = os.platform ?? process.platform;
+    if (child.pid) {
+        try {
+            if (platform === 'win32')
+                (os.spawnSync ?? spawnSync)('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+            else
+                (os.kill ?? ((pid, signal) => process.kill(pid, signal)))(-child.pid, 'SIGTERM');
+        }
+        catch {
+            // Already exited.
+        }
+    }
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+    child.unref();
+}
+/** The last few KB of dev's output, so a failed start can say why. */
+function outputTail() {
+    let tail = '';
+    return {
+        push: (data) => {
+            tail = (tail + String(data)).slice(-4000);
+        },
+        text: () => {
+            const lines = tail.trim().split('\n').slice(-8).join('\n');
+            return lines ? `\n${lines}` : '';
+        },
+    };
+}
+/** Starts the project's own `dev` in its own process group. `onSpawn` receives the child at once,
+ *  so a signal during startup can still stop it. */
+function startDev(projectRoot, onSpawn) {
+    const main = path.join(path.dirname(fileURLToPath(import.meta.url)), 'main.js');
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [main, 'dev'], {
+            cwd: projectRoot,
+            env: { ...process.env, CI: '1', DS_VIEWER_NO_UPDATE_CHECK: '1' },
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        onSpawn(child);
+        const output = outputTail();
+        let done = false;
+        const fail = (message) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            stopDev(child);
+            reject(new Error(`${message}${output.text()}`));
+        };
+        const timer = setTimeout(() => fail('Timed out waiting for ds-viewer dev to start.'), DEV_START_TIMEOUT_MS);
+        // Read continuously (so Metro's output never fills the pipe) and keep the tail for errors.
+        child.stderr?.on('data', output.push);
+        child.stdout?.on('data', (data) => {
+            output.push(data);
+            const match = String(data).match(/Starting the catalog at http:\/\/localhost:(\d+)/);
+            if (match && !done) {
+                done = true;
+                clearTimeout(timer);
+                resolve({ child, port: Number(match[1]) });
+            }
+        });
+        child.on('exit', (code) => fail(`ds-viewer dev exited early (code ${code}).`));
+    });
+}
+const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
+/** A sidebar href's page id; a malformed escape falls back to the raw text (like `idFromHash`). */
+function idFromHref(href) {
+    const raw = href.slice(1);
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/** Opens every sidebar page and returns its findings. `files` maps page ids to project-relative
+ *  page files, for the findings' `file`. `log` receives progress lines (stderr in the CLI). `deps`
+ *  replaces the browser, dev process control and exit for tests. */
+export async function renderCheck(projectRoot, options = {}) {
+    projectRoot = path.resolve(projectRoot);
+    const deps = options.deps ?? {};
+    const puppeteer = (deps.puppeteer ?? loadProjectPuppeteer(projectRoot));
+    if (!puppeteer)
+        return [RENDER_UNAVAILABLE];
+    const stop = deps.stopDev ?? ((child) => stopDev(child));
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const log = options.log ?? (() => { });
+    // Set as soon as dev is spawned, before it's ready, so a signal during startup still stops it.
+    let devChild;
+    let port = 0;
+    let browser;
+    // Ctrl-C or a CI cancel must still stop Metro: `dev` runs in its own process group, so the
+    // terminal's signal never reaches it. Registered before the browser launches, so it runs ahead
+    // of puppeteer's own handler.
+    const handlers = Object.keys(SIGNAL_EXIT_CODES).map((signal) => {
+        const handler = () => {
+            if (devChild)
+                stop(devChild);
+            exit(SIGNAL_EXIT_CODES[signal]);
+        };
+        process.on(signal, handler);
+        return [signal, handler];
+    });
+    try {
+        // The browser first: a missing browser download shouldn't start Metro for nothing.
+        try {
+            browser = await puppeteer.launch({ headless: true });
+        }
+        catch (error) {
+            return [{ ...RENDER_UNAVAILABLE, message: `Couldn't start the headless browser: ${error.message.split('\n')[0]}`, fix: 'npx puppeteer browsers install chrome' }];
+        }
+        ({ port } = await (deps.startDev ?? startDev)(projectRoot, (child) => {
+            devChild = child;
+        }));
+        const home = await browser.newPage();
+        const deadline = Date.now() + FIRST_LOAD_TIMEOUT_MS;
+        for (;;) {
+            try {
+                await home.goto(`http://localhost:${port}`, { waitUntil: 'networkidle0', timeout: FIRST_LOAD_TIMEOUT_MS });
+                break;
+            }
+            catch (error) {
+                if (!String(error).includes('ERR_CONNECTION_REFUSED') || Date.now() > deadline)
+                    throw error;
+                await new Promise((r) => setTimeout(r, 1000));
+            }
+        }
+        // Runs in the browser; `document` is typed loosely because the CLI compiles without DOM types.
+        const hrefs = await home.evaluate(() => {
+            const doc = globalThis.document;
+            return [...new Set(Array.from(doc.querySelectorAll('a[href^="#"]')).map((a) => a.getAttribute('href') ?? ''))];
+        });
+        await home.close();
+        const ids = hrefs.map(idFromHref).filter(Boolean);
+        if (ids.length === 0) {
+            return [{ id: 'render-failed', severity: 'error', message: 'The catalog rendered no sidebar links, so it probably failed to render at all.', fix: 'Run `ds-viewer dev` and check the browser console.' }];
+        }
+        log(`Rendering ${ids.length} pages…`);
+        const seen = new Set();
+        const issues = [];
+        for (const id of ids) {
+            // One page failing (a navigation timeout) is that page's finding; the others still run.
+            let page;
+            try {
+                page = await browser.newPage();
+                await page.setViewport({ width: 1280, height: 800 });
+                const messages = [];
+                page.on('console', (m) => messages.push({ type: m.type(), text: m.text() }));
+                page.on('pageerror', (e) => messages.push({ type: 'pageerror', text: String(e) }));
+                await page.goto(`http://localhost:${port}/#${encodeURIComponent(id)}`, { waitUntil: 'networkidle0', timeout: PAGE_TIMEOUT_MS });
+                await new Promise((r) => setTimeout(r, options.settleMs ?? SETTLE_MS));
+                const hasHeading = await page.evaluate(() => {
+                    const doc = globalThis.document;
+                    return Boolean(doc.querySelector('[role="heading"]')?.textContent?.trim());
+                });
+                issues.push(...issuesFromPage({ id, file: options.files?.get(id) }, messages, hasHeading, seen));
+                await page.close();
+            }
+            catch (error) {
+                // A stuck page's tab is closed, so it doesn't keep loading next to the remaining pages.
+                await page?.close().catch(() => { });
+                const file = options.files?.get(id);
+                issues.push({ id: 'render-error', severity: 'error', page: id, ...(file ? { file } : {}), message: `Couldn't open the page: ${error.message.split('\n')[0]}`, fix: 'Open the page in `ds-viewer dev`; it may be very slow to load or stuck.' });
+            }
+        }
+        log(`Checked ${ids.length} pages.`);
+        return issues;
+    }
+    catch (error) {
+        return [{ id: 'render-failed', severity: 'error', message: `Couldn't render the catalog: ${error.message}`, fix: "Run `ds-viewer dev` to see why the catalog doesn't start." }];
+    }
+    finally {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+        if (browser)
+            await browser.close().catch(() => { });
+        if (devChild)
+            stop(devChild);
+    }
+}

package/dist/cli/staticPage.js

@@ -42,6 +42,7 @@ function readStaticPage(file) {
     }
     const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, ts.ScriptKind.TSX);
     const imports = importedNames(sourceFile, '@krapwoo/ds-viewer');
+    const viewerImports = [...new Set(imports.values())];
     const defineCatalogPageNames = localNamesFor(imports, 'defineCatalogPage');
     const gridNames = localNamesFor(imports, 'grid');
     const call = defaultExportCall(sourceFile);
@@ -49,13 +50,13 @@ function readStaticPage(file) {
         // Not a recognized `defineCatalogPage(...)` default export — e.g. a hand-written object, or a
         // shadowed/renamed import this reader can't trace. Not a parse error: the file is valid
         // TypeScript, just not literal-checkable.
-        return { file, checkable: false };
+        return { file, checkable: false, viewerImports };
     }
     const consts = topLevelConsts(sourceFile);
     const pageObject = resolve(call.arguments[0], consts, new Set());
     if (!ts.isObjectLiteralExpression(pageObject))
-        return { file, checkable: false };
-    const page = { file, checkable: true };
+        return { file, checkable: false, viewerImports };
+    const page = { file, checkable: true, viewerImports };
     const idProp = findProp(pageObject, 'id');
     const componentProp = findProp(pageObject, 'component');
     const groupProp = findProp(pageObject, 'group');
@@ -193,16 +194,21 @@ function readComposedOf(node, consts) {
     return entries;
 }
 /** Local name -> imported name, for every named import from `moduleSpecifier`. */
-function importedNames(sourceFile, moduleSpecifier) {
+export function importedNames(sourceFile, moduleSpecifier) {
     const names = new Map();
     for (const statement of sourceFile.statements) {
         if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== moduleSpecifier) {
             continue;
         }
+        // Type-only imports bring no runtime value (`import type { X }`, `import { type X }`).
+        if (statement.importClause?.isTypeOnly)
+            continue;
         const bindings = statement.importClause?.namedBindings;
         if (!bindings || !ts.isNamedImports(bindings))
             continue;
         for (const element of bindings.elements) {
+            if (element.isTypeOnly)
+                continue;
             names.set(element.name.text, element.propertyName ? element.propertyName.text : element.name.text);
         }
     }

package/native/catalog/CatalogButton.tsx

@@ -0,0 +1,46 @@
+import React, { forwardRef, useState } from 'react';
+import { Pressable, StyleSheet, Text, type View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_TYPE } from './tokens';
+
+/** The viewer's own button, for catalog chrome and demo triggers (not an app component). Same look
+ *  as the update page's buttons. */
+export const CatalogButton = forwardRef<View, {
+  label: string;
+  onPress: () => void;
+  variant?: 'primary' | 'secondary';
+  accessibilityLabel?: string;
+}>(function CatalogButton({ label, onPress, variant = 'primary', accessibilityLabel }, ref) {
+  const [focused, setFocused] = useState(false);
+  const primary = variant === 'primary';
+  return (
+    <Pressable
+      ref={ref}
+      onPress={onPress}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel ?? label}
+      style={({ pressed }) => [
+        styles.base,
+        primary ? styles.primary : styles.secondary,
+        pressed && (primary ? styles.primaryPressed : styles.secondaryPressed),
+        focused && styles.focus,
+      ]}
+    >
+      <Text style={[styles.label, primary ? styles.labelPrimary : styles.labelSecondary]}>{label}</Text>
+    </Pressable>
+  );
+});
+
+const styles = StyleSheet.create({
+  base: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: 22, alignItems: 'center', justifyContent: 'center', alignSelf: 'center' },
+  primary: { backgroundColor: CATALOG_COLOR.text },
+  primaryPressed: { opacity: 0.85 },
+  secondary: { borderWidth: 1, borderColor: CATALOG_COLOR.borderStrong, backgroundColor: CATALOG_COLOR.surface },
+  secondaryPressed: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  // Same ring as the sidebar's: an outline, so focusing never shifts the layout.
+  focus: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing } as object,
+  label: { fontSize: CATALOG_TYPE.md, fontWeight: '700' },
+  labelPrimary: { color: '#ffffff' },
+  labelSecondary: { color: CATALOG_COLOR.text },
+});

package/native/catalog/OverlayDemo.tsx

@@ -0,0 +1,52 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { PhoneFrame } from './PhoneFrame';
+import { CatalogButton } from './CatalogButton';
+import { overlayTrigger } from './overlayDemoState';
+
+// Not `StyleSheet.absoluteFill`: React Native 0.81's types reject spreading it.
+const FILL = { position: 'absolute' as const, top: 0, right: 0, bottom: 0, left: 0 };
+
+/**
+ * A phone with a catalog button that opens an overlay: a sheet, a dialog, a toast. The overlay
+ * (`children`) fills the device above the centred trigger and gets `{ open, close }`; keep it
+ * mounted and drive its own `visible` from `open`, so its open and close animations play.
+ */
+export function OverlayDemo({
+  triggerLabel,
+  initiallyOpen = false,
+  keepTrigger = false,
+  children,
+}: {
+  triggerLabel: string | ((open: boolean) => string);
+  initiallyOpen?: boolean;
+  /** Keep the trigger visible while open, as a toggle. @default false */
+  keepTrigger?: boolean;
+  children: (state: { open: boolean; close: () => void }) => React.ReactNode;
+}) {
+  const [open, setOpen] = useState(initiallyOpen);
+  const trigger = overlayTrigger(open, { triggerLabel, keepTrigger });
+  // When the overlay closes, keyboard focus returns to the trigger instead of the page body.
+  const triggerRef = useRef<View>(null);
+  const wasOpen = useRef(open);
+  useEffect(() => {
+    if (wasOpen.current && !open) (triggerRef.current as unknown as { focus?: () => void } | null)?.focus?.();
+    wasOpen.current = open;
+  }, [open]);
+  return (
+    <PhoneFrame>
+      <View style={styles.screen}>
+        {trigger.visible && (
+          <CatalogButton ref={triggerRef} label={trigger.label} onPress={() => setOpen((value) => (keepTrigger ? !value : true))} />
+        )}
+        <View style={FILL} pointerEvents="box-none">
+          {children({ open, close: () => setOpen(false) })}
+        </View>
+      </View>
+    </PhoneFrame>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, alignSelf: 'stretch', alignItems: 'center', justifyContent: 'center' },
+});

package/native/catalog/PhoneScreen.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { ScrollView, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+
+/**
+ * A whole app screen inside a `PhoneFrame`: `header` pinned to the top, `footer` to the bottom,
+ * and the children in a body between them that scrolls instead of pushing the footer off the
+ * device. `floating` is a layer over the top of the screen for toasts; it adds no inset of its
+ * own, so the app positions its content. `bodyWrapper` lets the app put its own surface or
+ * context provider around the scrolling body; give its root `flex: 1, minHeight: 0`.
+ */
+export function PhoneScreen({
+  header,
+  footer,
+  floating,
+  bodyWrapper,
+  scroll = true,
+  contentContainerStyle,
+  children,
+}: {
+  header?: React.ReactNode;
+  footer?: React.ReactNode;
+  floating?: React.ReactNode;
+  bodyWrapper?: (body: React.ReactNode) => React.ReactNode;
+  /** Scroll the body (default), or lay it out to fit. */
+  scroll?: boolean;
+  contentContainerStyle?: StyleProp<ViewStyle>;
+  children?: React.ReactNode;
+}) {
+  const body = scroll ? (
+    <ScrollView style={styles.flex} contentContainerStyle={contentContainerStyle}>{children}</ScrollView>
+  ) : (
+    <View style={[styles.flex, contentContainerStyle]}>{children}</View>
+  );
+  return (
+    <View style={styles.screen}>
+      {header}
+      <View style={styles.flex}>{bodyWrapper ? bodyWrapper(body) : body}</View>
+      {footer}
+      {floating ? (
+        <View style={styles.floating} pointerEvents="box-none">{floating}</View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Fills the device; `minHeight: 0` lets a flex child shrink below its content on the web.
+  screen: { flex: 1, alignSelf: 'stretch', minHeight: 0 },
+  flex: { flex: 1, minHeight: 0 },
+  floating: { position: 'absolute', top: 0, left: 0, right: 0, zIndex: 20 },
+});

package/native/catalog/index.ts

@@ -31,6 +31,9 @@ export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
 export { PhoneFrame } from './PhoneFrame';
+export { PhoneScreen } from './PhoneScreen';
+export { OverlayDemo } from './OverlayDemo';
+export { CatalogButton } from './CatalogButton';
 export { BoundedOverlayViewport } from './BoundedOverlayViewport';
 export type { BoundedOverlayViewportProps } from './BoundedOverlayViewport';
 export { comparisonCellItemKey } from './overlayViewport';

package/native/catalog/overlayDemoState.ts

@@ -0,0 +1,8 @@
+/** What `OverlayDemo` shows for a given open state. Kept free of runtime imports for `node --test`. */
+export function overlayTrigger(
+  open: boolean,
+  options: { triggerLabel: string | ((open: boolean) => string); keepTrigger?: boolean },
+): { visible: boolean; label: string } {
+  const label = typeof options.triggerLabel === 'function' ? options.triggerLabel(open) : options.triggerLabel;
+  return { visible: !open || Boolean(options.keepTrigger), label };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",

package/starter-kit/components/BottomSheet/BottomSheet.catalog.tsx

@@ -1,6 +1,6 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Button } from '../Button';
 import { Dock } from '../Dock';
 import { TopNav } from '../TopNav';
@@ -17,53 +17,43 @@ const styles = StyleSheet.create({
 });
 
 function BottomSheetDemo() {
-  const [visible, setVisible] = useState(false);
   return (
-    <PhoneFrame>
-      {!visible && <Button label="Open sheet" onPress={() => setVisible(true)} />}
-      <BottomSheet
-        visible={visible}
-        onDismiss={() => setVisible(false)}
-        header={
-          <TopNav
-            title="Trip details"
-            trailing={
-              <Button
-                variant="secondary"
-                size="small"
-                showIcon
-                showLabel={false}
-                iconName="clear"
-                accessibilityLabel="Close"
-                onPress={() => setVisible(false)}
-              />
-            }
-          />
-        }
-        footer={
-          <Dock>
-            <Button label="Confirm" onPress={() => setVisible(false)} />
-          </Dock>
-        }
-      >
-        <View style={styles.sheetContent}>
-          <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
-          <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
-          {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
-              `elevated` shadow turning on automatically once this content area actually scrolls. */}
-          <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
-          <Text style={styles.cardBody}>
-            This line runs express between 96 St and 168 St during rush hours, skipping local stops in
-            between. Weekend service runs local along the full route, with some stations closed for
-            planned maintenance.
-          </Text>
-          <Text style={styles.cardBody}>
-            Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
-            entrances before you travel.
-          </Text>
-        </View>
-      </BottomSheet>
-    </PhoneFrame>
+    <OverlayDemo triggerLabel="Open sheet">
+      {({ open, close }) => (
+        <BottomSheet
+          visible={open}
+          onDismiss={close}
+          header={
+            <TopNav
+              title="Trip details"
+              trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={close} />}
+            />
+          }
+          footer={
+            <Dock>
+              <Button label="Confirm" onPress={close} />
+            </Dock>
+          }
+        >
+          <View style={styles.sheetContent}>
+            <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
+            <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
+            {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
+                `elevated` shadow turning on automatically once this content area actually scrolls. */}
+            <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
+            <Text style={styles.cardBody}>
+              This line runs express between 96 St and 168 St during rush hours, skipping local stops in
+              between. Weekend service runs local along the full route, with some stations closed for
+              planned maintenance.
+            </Text>
+            <Text style={styles.cardBody}>
+              Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
+              entrances before you travel.
+            </Text>
+          </View>
+        </BottomSheet>
+      )}
+    </OverlayDemo>
   );
 }
 

package/starter-kit/components/Dialog/Dialog.catalog.tsx

@@ -1,6 +1,6 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Button } from '../Button';
 import { ButtonGroup } from '../ButtonGroup';
 import { Dialog } from './Dialog';
@@ -13,21 +13,21 @@ const styles = StyleSheet.create({
 });
 
 function DialogDemo() {
-  const [visible, setVisible] = useState(false);
   return (
-    <PhoneFrame>
-      {!visible && <Button label="Open dialog" onPress={() => setVisible(true)} />}
-      <Dialog visible={visible} onDismiss={() => setVisible(false)}>
-        <Text style={styles.cardTitle}>Delete this trip?</Text>
-        <Text style={styles.cardBody}>This can't be undone.</Text>
-        <View style={styles.dialogActions}>
-          <ButtonGroup>
-            <Button label="Cancel" variant="tertiary" onPress={() => setVisible(false)} />
-            <Button label="Delete" onPress={() => setVisible(false)} />
-          </ButtonGroup>
-        </View>
-      </Dialog>
-    </PhoneFrame>
+    <OverlayDemo triggerLabel="Open dialog">
+      {({ open, close }) => (
+        <Dialog visible={open} onDismiss={close}>
+          <Text style={styles.cardTitle}>Delete this trip?</Text>
+          <Text style={styles.cardBody}>This can't be undone.</Text>
+          <View style={styles.dialogActions}>
+            <ButtonGroup>
+              <Button label="Cancel" variant="tertiary" onPress={close} />
+              <Button label="Delete" onPress={close} />
+            </ButtonGroup>
+          </View>
+        </Dialog>
+      )}
+    </OverlayDemo>
   );
 }
 

package/starter-kit/components/Toast/Toast.catalog.tsx

@@ -1,7 +1,6 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { View, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
-import { Button } from '../Button';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Toast } from './Toast';
 import { DS_SPACING } from '../../tokens';
 
@@ -15,14 +14,14 @@ const styles = StyleSheet.create({
 // pattern) so this demo actually exercises the slide-in-from-top/fade animation, not just the two
 // static end states.
 function ToastDemo() {
-  const [visible, setVisible] = useState(true);
   return (
-    <PhoneFrame>
-      <Button label={visible ? 'Hide toast' : 'Show toast'} onPress={() => setVisible((v) => !v)} />
-      <View style={styles.toastDemoOverlay} pointerEvents="box-none">
-        <Toast message="Trip saved" variant="success" visible={visible} />
-      </View>
-    </PhoneFrame>
+    <OverlayDemo triggerLabel={(open) => (open ? 'Hide toast' : 'Show toast')} keepTrigger initiallyOpen>
+      {({ open }) => (
+        <View style={styles.toastDemoOverlay} pointerEvents="box-none">
+          <Toast message="Trip saved" variant="success" visible={open} />
+        </View>
+      )}
+    </OverlayDemo>
   );
 }
 

package/starter-kit/pages/ReportIssue.catalog.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Banner } from '../components/Banner';
 import { BottomSheet } from '../components/BottomSheet';
 import { Button } from '../components/Button';
@@ -51,7 +51,6 @@ const REPORT_ISSUE_TYPE_PILLS: PillRowItem[] = [
 ];
 
 function ReportIssueDemo() {
-  const [visible, setVisible] = useState(false);
   const [confirmDiscard, setConfirmDiscard] = useState(false);
   const [issueType, setIssueType] = useState('delay');
   const [line, setLine] = useState('4');
@@ -60,17 +59,19 @@ function ReportIssueDemo() {
   const [visibility, setVisibility] = useState('public');
   const [notify, setNotify] = useState(true);
 
-  const requestClose = () => setConfirmDiscard(true);
-  const discard = () => {
-    setConfirmDiscard(false);
-    setVisible(false);
-  };
-
   return (
-    <PhoneFrame>
-      {!visible && <Button label="Report an issue" onPress={() => setVisible(true)} />}
+    <OverlayDemo triggerLabel="Report an issue">
+      {({ open, close }) => {
+        // Closing asks first; discarding confirms and closes the sheet.
+        const requestClose = () => setConfirmDiscard(true);
+        const discard = () => {
+          setConfirmDiscard(false);
+          close();
+        };
+        return (
+          <>
       <BottomSheet
-        visible={visible}
+        visible={open}
         onDismiss={requestClose}
         header={
           <TopNav
@@ -82,7 +83,7 @@ function ReportIssueDemo() {
         }
         footer={
           <Dock>
-            <Button label="Submit report" onPress={() => setVisible(false)} />
+            <Button label="Submit report" onPress={close} />
           </Dock>
         }
       >
@@ -135,7 +136,10 @@ function ReportIssueDemo() {
           </ButtonGroup>
         </View>
       </Dialog>
-    </PhoneFrame>
+          </>
+        );
+      }}
+    </OverlayDemo>
   );
 }
 

package/starter-kit/pages/SavedTrips.catalog.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, PhoneFrame, PhoneScreen } from '@krapwoo/ds-viewer';
 import { Avatar } from '../components/Avatar';
 import { Badge } from '../components/Badge';
 import { Button } from '../components/Button';
@@ -23,13 +23,6 @@ import { Icon } from '../icons/Icon.native';
 import { DS_ICON_SIZE, DS_MOTION_DURATION, DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../tokens';
 
 const styles = StyleSheet.create({
-  // Saved trips recipe — fills PhoneFrame edge-to-edge (like dropdownFrameContent), with a
-  // fixed TopNav header and Dock footer around a scrollable middle, the same fixed-header/
-  // scrollable-body/fixed-footer shape a real screen would use.
-  savedTripsScreen: { flex: 1, alignSelf: 'stretch' },
-  // Takes the space between the TopNav and the Dock and scrolls (`minHeight: 0` lets a flex child
-  // shrink below its content on the web).
-  savedTripsScroll: { flex: 1, minHeight: 0 },
   // The muted area between TopNav and Dock takes the remaining height, so the list scrolls there.
   savedTripsBody: { flex: 1, minHeight: 0 },
   savedTripsScrollContent: { padding: DS_SPACING[800], gap: DS_SPACING[600] },
@@ -40,7 +33,7 @@ const styles = StyleSheet.create({
   // Floats over the top of the screen — same top/left/right inset Toast's own catalog demo uses —
   // instead of sitting inline in the flex flow and pushing the Dock down. A column with a small
   // gap, since back-to-back removals stack one toast per removal (newest on top).
-  savedTripsToastOverlay: { position: 'absolute', top: DS_SPACING[800], left: DS_SPACING[600], right: DS_SPACING[600], zIndex: 20, gap: DS_SPACING[300] },
+  savedTripsToastOverlay: { marginTop: DS_SPACING[800], marginHorizontal: DS_SPACING[600], gap: DS_SPACING[300] },
   // Map mode's stand-in — a real map isn't in scope for this recipe, just enough to show the
   // SegmentedToggle actually switches the screen's content, not just its own thumb.
   savedTripsMapPlaceholder: { alignItems: 'center', justifyContent: 'center', gap: DS_SPACING[400], paddingVertical: DS_SPACING[2400] },
@@ -111,130 +104,132 @@ function SavedTripsDemo() {
 
   return (
     <PhoneFrame>
-      <View style={styles.savedTripsScreen}>
-        <TopNav
-          title="Saved trips"
-          trailing={
-            <Tooltip visible={showFilterTip} label="Filter by mode" placement="bottom" align="right">
-              <Button
-                variant="secondary"
-                size="small"
-                showIcon
-                showLabel={false}
-                iconName="menu"
-                accessibilityLabel="Filters"
-                onPress={() => setShowFilterTip((v) => !v)}
+      <PhoneScreen
+        header={
+          <TopNav
+            title="Saved trips"
+            trailing={
+              <Tooltip visible={showFilterTip} label="Filter by mode" placement="bottom" align="right">
+                <Button
+                  variant="secondary"
+                  size="small"
+                  showIcon
+                  showLabel={false}
+                  iconName="menu"
+                  accessibilityLabel="Filters"
+                  onPress={() => setShowFilterTip((v) => !v)}
+                />
+              </Tooltip>
+            }
+          />
+        }
+        bodyWrapper={(body) => <Surface tone="muted" style={styles.savedTripsBody}>{body}</Surface>}
+        contentContainerStyle={styles.savedTripsScrollContent}
+        // Toasts float over the top of the screen instead of pushing the Dock down. One per
+        // pending removal, newest on top; each stays mounted (visible: false) through its exit.
+        floating={
+          <View style={styles.savedTripsToastOverlay} pointerEvents="box-none">
+            {toasts.map((t) => (
+              <Toast
+                key={t.key}
+                visible={t.visible}
+                message={`${t.trip.title} removed`}
+                action={{ label: 'Undo', onPress: () => undoRemove(t.key, t.trip) }}
               />
-            </Tooltip>
-          }
+            ))}
+          </View>
+        }
+        footer={
+          <Dock>
+            <Button label="Plan a new trip" onPress={() => {}} />
+          </Dock>
+        }
+      >
+        <SearchField value={query} onChangeText={setQuery} placeholder="Search stations" />
+        <SegmentedToggle
+          value={viewMode}
+          onChange={setViewMode}
+          options={[
+            { value: 'list', label: 'List', iconName: 'menu' },
+            { value: 'map', label: 'Map', iconName: 'map' },
+          ]}
         />
-        <Surface tone="muted" style={styles.savedTripsBody}>
-          <ScrollView style={styles.savedTripsScroll} contentContainerStyle={styles.savedTripsScrollContent}>
-            <SearchField value={query} onChangeText={setQuery} placeholder="Search stations" />
-            <SegmentedToggle
-              value={viewMode}
-              onChange={setViewMode}
+        {viewMode === 'map' ? (
+          <View style={styles.savedTripsMapPlaceholder}>
+            <Icon name="map" size={DS_ICON_SIZE.xl} color={DS_SEMANTIC.text.muted} />
+            <Text style={styles.savedTripsMapPlaceholderText}>Map view</Text>
+          </View>
+        ) : (
+          <>
+            <UnderlineTabs
+              value={tab}
+              onChange={setTab}
               options={[
-                { value: 'list', label: 'List', iconName: 'menu' },
-                { value: 'map', label: 'Map', iconName: 'map' },
+                { value: 'all', label: 'All' },
+                { value: 'nearby', label: 'Nearby' },
+                { value: 'favorites', label: 'Favorites' },
               ]}
             />
-            {viewMode === 'map' ? (
-              <View style={styles.savedTripsMapPlaceholder}>
-                <Icon name="map" size={DS_ICON_SIZE.xl} color={DS_SEMANTIC.text.muted} />
-                <Text style={styles.savedTripsMapPlaceholderText}>Map view</Text>
-              </View>
+            {tab === 'favorites' ? (
+              <EmptyState
+                iconName="waypoints"
+                title="No favorites yet"
+                description="Star a trip to see it here."
+                action={{ label: 'Browse trips', onPress: () => setTab('all') }}
+                secondaryAction={{ label: 'Not now', onPress: () => {} }}
+              />
             ) : (
               <>
-                <UnderlineTabs
-                  value={tab}
-                  onChange={setTab}
-                  options={[
-                    { value: 'all', label: 'All' },
-                    { value: 'nearby', label: 'Nearby' },
-                    { value: 'favorites', label: 'Favorites' },
-                  ]}
+                <PillRow
+                  pills={pills.map((p) => ({ ...p, onPress: () => setPills((prev) => prev.map((x) => ({ ...x, variant: x.id === p.id ? 'selected' : 'not_selected' }))) }))}
+                  showAddPill={false}
                 />
-                {tab === 'favorites' ? (
+                <View style={styles.savedTripsInlineRow}>
+                  <Loading size={14} />
+                  <Text style={styles.savedTripsLoadingText}>Updating arrival times…</Text>
+                </View>
+                {/* Dropdown's own `label` prop, not a hand-rolled Text above it — the component
+                    already owns the labeled-field pattern (PillRow, which has no label prop, is
+                    the case where an external label is legitimately the only option). */}
+                <Dropdown label="Sort by" value={sortBy} onChange={setSortBy} options={SAVED_TRIPS_SORT_OPTIONS} />
+                <SectionHeader title="Nearby stations" />
+                {trips.length > 0 ? (
+                  <List>
+                    {trips.map((trip) => (
+                      <ListItem
+                        key={trip.id}
+                        title={trip.title}
+                        subtitle={trip.subtitle}
+                        leading={<Avatar iconName={trip.iconName} size={40} />}
+                        trailing={
+                          <View style={styles.savedTripsInlineRow}>
+                            <Badge variant={trip.badgeVariant} label={trip.badgeLabel} />
+                            <Button
+                              variant="ghost"
+                              size="small"
+                              showIcon
+                              showLabel={false}
+                              iconName="clear"
+                              accessibilityLabel={`Remove ${trip.title}`}
+                              onPress={() => removeTrip(trip.id)}
+                            />
+                          </View>
+                        }
+                      />
+                    ))}
+                  </List>
+                ) : (
                   <EmptyState
                     iconName="waypoints"
-                    title="No favorites yet"
-                    description="Star a trip to see it here."
-                    action={{ label: 'Browse trips', onPress: () => setTab('all') }}
-                    secondaryAction={{ label: 'Not now', onPress: () => {} }}
+                    title="No nearby trips"
+                    description="Removed trips you save will show up here again."
                   />
-                ) : (
-                  <>
-                    <PillRow
-                      pills={pills.map((p) => ({ ...p, onPress: () => setPills((prev) => prev.map((x) => ({ ...x, variant: x.id === p.id ? 'selected' : 'not_selected' }))) }))}
-                      showAddPill={false}
-                    />
-                    <View style={styles.savedTripsInlineRow}>
-                      <Loading size={14} />
-                      <Text style={styles.savedTripsLoadingText}>Updating arrival times…</Text>
-                    </View>
-                    {/* Dropdown's own `label` prop, not a hand-rolled Text above it — the component
-                        already owns the labeled-field pattern (PillRow, which has no label prop, is
-                        the case where an external label is legitimately the only option). */}
-                    <Dropdown label="Sort by" value={sortBy} onChange={setSortBy} options={SAVED_TRIPS_SORT_OPTIONS} />
-                    <SectionHeader title="Nearby stations" />
-                    {trips.length > 0 ? (
-                      <List>
-                        {trips.map((trip) => (
-                          <ListItem
-                            key={trip.id}
-                            title={trip.title}
-                            subtitle={trip.subtitle}
-                            leading={<Avatar iconName={trip.iconName} size={40} />}
-                            trailing={
-                              <View style={styles.savedTripsInlineRow}>
-                                <Badge variant={trip.badgeVariant} label={trip.badgeLabel} />
-                                <Button
-                                  variant="ghost"
-                                  size="small"
-                                  showIcon
-                                  showLabel={false}
-                                  iconName="clear"
-                                  accessibilityLabel={`Remove ${trip.title}`}
-                                  onPress={() => removeTrip(trip.id)}
-                                />
-                              </View>
-                            }
-                          />
-                        ))}
-                      </List>
-                    ) : (
-                      <EmptyState
-                        iconName="waypoints"
-                        title="No nearby trips"
-                        description="Removed trips you save will show up here again."
-                      />
-                    )}
-                  </>
                 )}
               </>
             )}
-          </ScrollView>
-        </Surface>
-        {/* Absolutely positioned over the top of the screen (not inline in the flex flow — a real
-            toast floats over content, it doesn't push the Dock down) — same placement Toast's own
-            catalog demo uses. One Toast per pending removal, stacked newest-on-top; each entry
-            stays in the array (with `visible: false`) through its own exit animation instead of
-            being yanked out of the tree mid-motion. */}
-        <View style={styles.savedTripsToastOverlay} pointerEvents="box-none">
-          {toasts.map((t) => (
-            <Toast
-              key={t.key}
-              visible={t.visible}
-              message={`${t.trip.title} removed`}
-              action={{ label: 'Undo', onPress: () => undoRemove(t.key, t.trip) }}
-            />
-          ))}
-        </View>
-        <Dock>
-          <Button label="Plan a new trip" onPress={() => {}} />
-        </Dock>
-      </View>
+          </>
+        )}
+      </PhoneScreen>
     </PhoneFrame>
   );
 }