@krapwoo/ds-viewer 0.6.2 → 0.6.4

package/README.md

@@ -526,6 +526,11 @@ and adds what only a real render shows:
 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 starts its own `dev` server, with `--no-update-endpoint` and its own generated directory
+(`.ds-viewer-render/`, gitignored by `init` alongside `.ds-viewer/`). Nothing it generates touches
+the workspace a running `dev` owns, so you can run it beside a catalog you already have open and
+that catalog is unaffected — including its update page's actions.
 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.

package/dist/cli/dev.js

@@ -6,7 +6,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { resolveConfig } from "./config.js";
 import { sync } from "./sync.js";
-import { writeWorkspace } from "./workspace.js";
+import { workspacePath, writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
 import { buildVersionStatus, createVersionController, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck, runUpdateCheck, statusFromCheck, writeUpdateFile, writeVersionFile, } from "./updateCheck.js";
@@ -15,9 +15,10 @@ import { createUpdateEndpoint } from "./endpoint.js";
 import { buildUpdatePlan } from "./updatePlan.js";
 import { lastSummaryLine } from "./doctor.js";
 import { detectPackageManager, installUpgradeCommand, platformCommand } from "./packageManager.js";
+import { DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR } from "./types.js";
 export class LocalInstallMissingError extends Error {
 }
-const IGNORED_WATCH_SEGMENTS = new Set(['.ds-viewer', 'node_modules', '.git']);
+const IGNORED_WATCH_SEGMENTS = new Set([DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR, 'node_modules', '.git']);
 /** False for a changed path under `.ds-viewer/` (package-owned output — reacting to it would make
  *  `dev`'s own `sync` retrigger itself), `node_modules/`, or `.git/`; true for everything else, so
  *  `dev`'s watcher (below) only re-syncs on a project source change. */
@@ -58,8 +59,13 @@ export function watchTargetFolders(config) {
  *  workspace until `dev` was restarted, because `writeWorkspace` was never called again with the
  *  new value (controller end-to-end finding E1). Returns the freshly-resolved config so `dev` can
  *  keep watching with it. */
-export function reloadWorkspace(projectRoot, updateEndpoint) {
-    const config = resolveConfig(projectRoot);
+export function reloadWorkspace(projectRoot, updateEndpoint, 
+// `resolveConfig` reads the user's file, which never names a workspace directory, so a run that
+// owns a non-default one has to put it back — otherwise a config change moves every generated
+// file into `.ds-viewer`, which is the collision this parameter exists to prevent.
+workspaceDir) {
+    const resolved = resolveConfig(projectRoot);
+    const config = workspaceDir ? { ...resolved, workspaceDir } : resolved;
     sync(config);
     writeWorkspace(config, updateEndpoint);
     return config;
@@ -81,8 +87,8 @@ export async function refreshUpdateFile(config, ownVersion, options = {}) {
             ? statusFromCheck(ownVersion, autoCheck, { result: await injected(ownVersion), reached: true })
             : { current: ownVersion, autoCheck, lastOutcome: 'not-run', update: null }
         : await buildVersionStatus(ownVersion, autoCheck);
-    writeUpdateFile(config.projectRoot, status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined);
-    writeVersionFile(config.projectRoot, status);
+    writeUpdateFile(config.projectRoot, status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined, config.workspaceDir);
+    writeVersionFile(config.projectRoot, status, config.workspaceDir);
     return status;
 }
 // Promisified, not `execFileSync` — install/migrate/doctor each take real seconds, and this now
@@ -246,7 +252,7 @@ export async function performRestart(handoff, deps = {}) {
     try {
         for (const watcher of handoff.watchers)
             watcher.close();
-        handoff.endpointServer.close();
+        handoff.endpointServer?.close();
         killGroup(handoff.child, 'SIGTERM');
         // Errata 7d: race the old child's exit against a 10s timer, then SIGKILL the group — a wedged
         // Expo/Metro process must never block the restart forever.
@@ -299,13 +305,15 @@ export async function performRestart(handoff, deps = {}) {
 export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
     const ownVersion = readOwnVersion(import.meta.dirname);
-    let config = initialConfig;
+    // Carried on the config so every writer (sync, writeWorkspace, the update files) lands in this
+    // run's own directory, and so a config reload cannot silently drop it.
+    let config = devOptions.workspaceDir ? { ...initialConfig, workspaceDir: devOptions.workspaceDir } : initialConfig;
     const version = createVersionController({
         ownVersion,
         projectRoot: initialConfig.projectRoot,
         prefsDir: defaultPreferencesDir(),
         env: process.env,
-        initial: await refreshUpdateFile(initialConfig, ownVersion),
+        initial: await refreshUpdateFile(config, ownVersion),
         getConfig: () => config,
         // **Check now** always asks npm, even with automatic checks off: you asked for this one check.
         // The result lives only in this process; `update.json` and `version.json` are rewritten at
@@ -316,7 +324,7 @@ export async function dev(initialConfig, devOptions = {}) {
     // Restart handoff step 2/4: a status file left by the *previous* `dev` process (right before it
     // exited to restart) is read once, then deleted — a plain refresh afterward shows "idle"/"no
     // update known" instead of replaying a stale success/failure forever.
-    const statusFile = path.join(config.projectRoot, '.ds-viewer', 'update-status.json');
+    const statusFile = workspacePath(config, 'update-status.json');
     let updateStatus = { phase: 'idle' };
     if (existsSync(statusFile)) {
         try {
@@ -390,14 +398,24 @@ export async function dev(initialConfig, devOptions = {}) {
         checkNow: version.checkNow,
         setAutoCheck: version.setAutoCheck,
     };
-    const endpointServer = createUpdateEndpoint(endpointDeps);
-    await new Promise((resolve) => endpointServer.listen(0, '127.0.0.1', resolve));
-    const endpointPort = endpointServer.address().port;
-    // Printed for the same reason the Metro port above is printed: a developer (or Task 20's own
-    // verification) checking the endpoint directly (e.g. with curl) needs its port — the secret
-    // itself is never printed; the endpoint rejects anything that doesn't already have it.
-    console.log(`Update endpoint listening on 127.0.0.1:${endpointPort}`);
-    const updateEndpoint = { baseUrl: `http://127.0.0.1:${endpointPort}`, secret };
+    // A throwaway server (a render check's own `dev`) takes no update actions, and creating an
+    // endpoint would bake its short-lived port into the shared workspace — pointing an already-open
+    // catalog at a port that dies with this process. See `writeWorkspace`.
+    let updateEndpoint;
+    let endpointServer;
+    if (!devOptions.noUpdateEndpoint) {
+        endpointServer = createUpdateEndpoint(endpointDeps);
+        await new Promise((resolve) => endpointServer.listen(0, '127.0.0.1', resolve));
+        const endpointPort = endpointServer.address().port;
+        // Printed for the same reason the Metro port above is printed: a developer (or Task 20's own
+        // verification) checking the endpoint directly (e.g. with curl) needs its port — the secret
+        // itself is never printed; the endpoint rejects anything that doesn't already have it.
+        console.log(`Update endpoint listening on 127.0.0.1:${endpointPort}`);
+        updateEndpoint = { baseUrl: `http://127.0.0.1:${endpointPort}`, secret };
+    }
+    else {
+        console.log('Update endpoint disabled for this run (--no-update-endpoint).');
+    }
     const workspace = writeWorkspace(config, updateEndpoint);
     let debounceTimer;
     const onSourceChange = (_eventType, relativePath) => {
@@ -426,7 +444,7 @@ export async function dev(initialConfig, devOptions = {}) {
         clearTimeout(configDebounceTimer);
         configDebounceTimer = setTimeout(() => {
             try {
-                config = reloadWorkspace(config.projectRoot, updateEndpoint);
+                config = reloadWorkspace(config.projectRoot, updateEndpoint, config.workspaceDir);
                 version.refreshAutoCheck();
             }
             catch (error) {
@@ -451,7 +469,7 @@ export async function dev(initialConfig, devOptions = {}) {
     child.on('exit', (code) => {
         for (const watcher of watchers)
             watcher.close();
-        endpointServer.close();
+        endpointServer?.close();
         process.exitCode = code ?? 0;
     });
     // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
@@ -464,7 +482,7 @@ export async function dev(initialConfig, devOptions = {}) {
         process.on(signal, () => {
             for (const watcher of watchers)
                 watcher.close();
-            endpointServer.close();
+            endpointServer?.close();
             killGroup(child, signal);
             process.exit(0);
         });
@@ -476,7 +494,7 @@ export async function dev(initialConfig, devOptions = {}) {
         console.error(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
         for (const watcher of watchers)
             watcher.close();
-        endpointServer.close();
+        endpointServer?.close();
         killGroup(child, 'SIGTERM');
         process.exit(1);
     };

package/dist/cli/endpoint.js

@@ -50,6 +50,17 @@ function sendJson(res, status, body, allowedOrigin) {
     res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': allowedOrigin });
     res.end(JSON.stringify(body));
 }
+/** For a refusal the page is *allowed* to read: a wrong secret or an unknown route, where the
+ *  Origin check has already passed. Without the allow-origin header the browser blocks the
+ *  response and the page cannot tell "wrong secret" from "server not running" — both arrive as
+ *  the same opaque network failure, which is how a stale secret looked like a dead server.
+ *
+ *  A rejected or absent Origin deliberately gets no CORS headers at all (see the Origin checks
+ *  below): a page from somewhere else is told nothing, not even which origin is allowed. */
+function sendText(res, status, body, allowedOrigin) {
+    res.writeHead(status, { 'Content-Type': 'text/plain', 'Access-Control-Allow-Origin': allowedOrigin });
+    res.end(body);
+}
 /** Design §5 "Local endpoint safeguards", every one of them, in the exact order this plan's own
  *  `spikes/cors-endpoint/` spike proved: Origin (including `OPTIONS`) → secret → route. Does not
  *  call `.listen()` itself — Task 18's `dev.ts` owns the real port (`0` → OS-assigned, `127.0.0.1`
@@ -102,7 +113,7 @@ export function createUpdateEndpoint(deps) {
             return;
         }
         if (!secretMatches(req.headers[DS_VIEWER_SECRET_HEADER], deps.secret)) {
-            res.writeHead(401).end('Missing or wrong secret.');
+            sendText(res, 401, 'Missing or wrong secret.', deps.allowedOrigin);
             return;
         }
         if (req.method === 'POST' && req.url === '/plan') {
@@ -245,6 +256,6 @@ export function createUpdateEndpoint(deps) {
             }
             return;
         }
-        res.writeHead(404).end('Not found.');
+        sendText(res, 404, 'Not found.', deps.allowedOrigin);
     });
 }

package/dist/cli/init.js

@@ -7,6 +7,7 @@ import { detectComponentFolders, detectTokenFiles } from "./detect.js";
 import { ensureAgentsFileSection } from "./agentsFile.js";
 import { ensureGithubAction } from "./githubAction.js";
 import { readOwnVersion } from "./packageVersion.js";
+import { DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR } from "./types.js";
 async function promptConfirm(message) {
     // A closed, non-interactive stdin (CI, piped npx) would reject `question` with an AbortError;
     // say how to proceed instead.
@@ -129,11 +130,15 @@ function ensureSharedProjectFiles(projectRoot) {
         written.push(packageJsonPath);
     }
     const gitignorePath = path.join(projectRoot, '.gitignore');
-    const gitignoreEntry = '.ds-viewer/';
+    // Both generated workspaces: the one `dev` owns, and the one `doctor --render`'s own server uses
+    // so it never writes the files `dev` is serving.
+    const gitignoreEntries = [`${DEFAULT_WORKSPACE_DIR}/`, `${RENDER_WORKSPACE_DIR}/`];
     const existingGitignore = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
-    if (!existingGitignore.split('\n').some((line) => line.replace(/\r$/, '') === gitignoreEntry)) {
+    const presentLines = new Set(existingGitignore.split('\n').map((line) => line.replace(/\r$/, '')));
+    const missing = gitignoreEntries.filter((entry) => !presentLines.has(entry));
+    if (missing.length > 0) {
         const separator = existingGitignore === '' || existingGitignore.endsWith('\n') ? '' : '\n';
-        writeFileSync(gitignorePath, `${existingGitignore}${separator}${gitignoreEntry}\n`);
+        writeFileSync(gitignorePath, `${existingGitignore}${separator}${missing.join('\n')}\n`);
         written.push(gitignorePath);
     }
     written.push(...ensureAgentsFileSection(projectRoot));

package/dist/cli/main.js

@@ -7,6 +7,7 @@ import { dev } from "./dev.js";
 import { sync } from "./sync.js";
 import { formatHuman, runDoctor, toDoctorJson, withExtraIssues } from "./doctor.js";
 import { renderCheck } from "./render.js";
+import { RENDER_WORKSPACE_DIR } from "./types.js";
 import { explainPage, formatExplain, parseHeights } from "./explain.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { checkForUpdate, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck } from "./updateCheck.js";
@@ -25,6 +26,10 @@ Commands:
   dev      Sync, then serve the catalog on a local web address and keep it current as files change
            [--port <number>]
            Pin the catalog (and its update endpoint's restart handoff) to this port
+           [--no-update-endpoint]
+           Serve with no local update endpoint, leaving the one a running dev server recorded alone
+           [--workspace-dir <name>]
+           Generate into this directory instead of .ds-viewer, so two servers never share files
   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)
@@ -243,7 +248,22 @@ async function main() {
         const portIndex = rest.indexOf('--port');
         const parsedPort = portIndex !== -1 ? Number(rest[portIndex + 1]) : undefined;
         const pinnedPort = parsedPort !== undefined && Number.isInteger(parsedPort) ? parsedPort : undefined;
-        await dev(config, { pinnedPort });
+        // `--no-update-endpoint`: run the catalog without the local update endpoint, and leave the
+        // endpoint an already-running `dev` recorded in the shared workspace alone. `doctor --render`
+        // starts its own server this way.
+        const noUpdateEndpoint = rest.includes('--no-update-endpoint');
+        // `--workspace-dir <name>`: which generated directory this run owns, so a second server (a
+        // render check's own) never writes the files the first one is serving. A bare directory name
+        // only — anything with a path separator, or a parent reference, would let an argument write
+        // outside the project.
+        const dirIndex = rest.indexOf('--workspace-dir');
+        const requestedDir = dirIndex !== -1 ? rest[dirIndex + 1] : undefined;
+        if (requestedDir !== undefined && (requestedDir === '' || requestedDir !== path.basename(requestedDir) || requestedDir.startsWith('.') === false)) {
+            console.error(`--workspace-dir must be a single hidden directory name such as ${RENDER_WORKSPACE_DIR}.`);
+            process.exitCode = 1;
+            return;
+        }
+        await dev(config, { pinnedPort, noUpdateEndpoint, workspaceDir: requestedDir });
         return;
     }
     console.error(`Unknown command "${command}".\n\n${USAGE}`);

package/dist/cli/render.js

@@ -2,9 +2,11 @@
 // 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 { get as httpGet } from 'node:http';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { RENDER_WORKSPACE_DIR } from "./types.js";
 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
@@ -173,10 +175,34 @@ function outputTail() {
 }
 /** 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. */
+/** Polls `http://localhost:<port>/` until it answers, so a caller never navigates to a port Metro
+ *  has not bound yet. Any HTTP reply counts — the page's own content is checked afterwards. */
+async function waitForServer(port, timeoutMs = DEV_START_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const answered = await new Promise((resolve) => {
+            const request = httpGet({ host: 'localhost', port, path: '/', timeout: 2000 }, () => resolve(true));
+            request.on('error', () => resolve(false));
+            request.on('timeout', () => {
+                request.destroy();
+                resolve(false);
+            });
+        });
+        if (answered)
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`Timed out waiting for the catalog to answer on port ${port}.`);
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+}
 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'], {
+        // Its own workspace directory and no update endpoint: this server exists to render pages, and
+        // every file it generates would otherwise overwrite the ones an already-running `dev` is
+        // serving — including that developer's endpoint, pointing their open catalog at a port that
+        // dies with this check.
+        const child = spawn(process.execPath, [main, 'dev', '--no-update-endpoint', '--workspace-dir', RENDER_WORKSPACE_DIR], {
             cwd: projectRoot,
             env: { ...process.env, CI: '1', DS_VIEWER_NO_UPDATE_CHECK: '1' },
             detached: process.platform !== 'win32',
@@ -202,7 +228,13 @@ function startDev(projectRoot, onSpawn) {
             if (match && !done) {
                 done = true;
                 clearTimeout(timer);
-                resolve({ child, port: Number(match[1]) });
+                // `dev` prints that line before it spawns Expo, so the port is known well before Metro is
+                // listening on it. Resolving here raced the bundler: the first navigation could land on a
+                // port nothing was bound to yet. Wait for the server to actually answer.
+                const port = Number(match[1]);
+                waitForServer(port)
+                    .then(() => resolve({ child, port }))
+                    .catch((error) => fail(`${error.message} `));
             }
         });
         child.on('exit', (code) => fail(`ds-viewer dev exited early (code ${code}).`));
@@ -272,10 +304,18 @@ export async function renderCheck(projectRoot, options = {}) {
             }
         }
         // Runs in the browser; `document` is typed loosely because the CLI compiles without DOM types.
-        const hrefs = await home.evaluate(() => {
+        const readHrefs = () => home.evaluate(() => {
             const doc = globalThis.document;
             return [...new Set(Array.from(doc.querySelectorAll('a[href^="#"]')).map((a) => a.getAttribute('href') ?? ''))];
         });
+        // The server answers before the bundle has run, and a workspace Metro has never bundled before
+        // (a fresh `.ds-viewer-render`) is slow the first time. Keep asking until the sidebar is there,
+        // rather than reading once and calling an empty page a failed render.
+        let hrefs = await readHrefs();
+        while (hrefs.length === 0 && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 500));
+            hrefs = await readHrefs();
+        }
         await home.close();
         const ids = hrefs.map(idFromHref).filter(Boolean);
         if (ids.length === 0) {

package/dist/cli/sync.js

@@ -4,13 +4,14 @@ import { globBaseFolder, resolveGlob } from "./glob.js";
 import { createComponentReader } from "./props.js";
 import { readTokenModules } from "./tokens.js";
 import { discoverPages, writePageIndex } from "./pageIndex.js";
+import { workspacePath } from "./workspace.js";
 const GENERATED_INDEX = "export { default as components } from './components.json';\nexport { default as tokens } from './tokens.json';\n";
 /** Reads detection, props, and tokens from source, then writes `.ds-viewer/generated/`
  *  (design §3 — "Output and speed": `components.json`, `tokens.json`, and the page import list,
  *  sorted and deterministic). Nothing from the project is executed. `resolveOptions` is test-only
  *  (see this task's Interfaces note) — production callers omit it. */
 export function sync(config, resolveOptions) {
-    const generatedDir = path.join(config.projectRoot, '.ds-viewer', 'generated');
+    const generatedDir = workspacePath(config, 'generated');
     mkdirSync(generatedDir, { recursive: true });
     const excluded = new Set((config.exclude ?? []).flatMap((pattern) => resolveGlob(config.projectRoot, pattern)));
     const componentEntryFiles = config.components.flatMap((pattern) => resolveGlob(config.projectRoot, pattern)).filter((file) => !excluded.has(file));

package/dist/cli/types.js

@@ -1 +1,8 @@
-export {};
+/** `DsViewerConfig` plus where it came from. Every CLI command after config loading works with
+ *  this, not the raw `DsViewerConfig`, so paths are always resolved against the right project. */
+/** The generated Expo workspace's directory name, relative to `projectRoot`. The default is the
+ *  only one a user ever sees; a throwaway server (a render check's own `dev`) uses its own so the
+ *  two never write the same files. */
+export const DEFAULT_WORKSPACE_DIR = '.ds-viewer';
+/** Used by `doctor --render`'s own `dev`. Gitignored next to the default. */
+export const RENDER_WORKSPACE_DIR = '.ds-viewer-render';

package/dist/cli/updateCheck.js

@@ -2,6 +2,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { compareVersions, isBreakingUpgrade, parseVersion } from "./semver.js";
+import { DEFAULT_WORKSPACE_DIR } from "./types.js";
 const CACHE_FILE_NAME = 'update-check.json';
 const PACKAGE_NAME = '@krapwoo/ds-viewer';
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME).replace('%40', '@')}/latest`;
@@ -229,9 +230,10 @@ export function statusFromCheck(currentVersion, autoCheck, outcome) {
         update: toNotice(outcome.result),
     };
 }
-/** `dev` writes this next to `update.json`; the generated entry file imports it. */
-export function writeVersionFile(projectRoot, status) {
-    const file = path.join(projectRoot, '.ds-viewer', 'version.json');
+/** `dev` writes this next to `update.json`; the generated entry file imports it. `workspaceDir`
+ *  is the run's own generated directory — see `workspacePath`. */
+export function writeVersionFile(projectRoot, status, workspaceDir = DEFAULT_WORKSPACE_DIR) {
+    const file = path.join(projectRoot, workspaceDir, 'version.json');
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(status));
     return file;
@@ -239,8 +241,8 @@ export function writeVersionFile(projectRoot, status) {
 /** Design §5: "`dev` writes the result to `.ds-viewer/update.json`; the viewer reads it." Always
  *  writes something — `null` when there is no result — so the generated entry file (Task 17) can
  *  unconditionally `import updateNotice from './update.json'` without ever hitting a missing file. */
-export function writeUpdateFile(projectRoot, result) {
-    const file = path.join(projectRoot, '.ds-viewer', 'update.json');
+export function writeUpdateFile(projectRoot, result, workspaceDir = DEFAULT_WORKSPACE_DIR) {
+    const file = path.join(projectRoot, workspaceDir, 'update.json');
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(result ?? null));
     return file;

package/dist/cli/workspace.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { globBaseFolder } from "./glob.js";
+import { DEFAULT_WORKSPACE_DIR } from "./types.js";
 function metroConfigJs(extraWatchFolders) {
     return `const path = require('path');
 const fs = require('fs');
@@ -99,11 +100,23 @@ function configGlobFolders(config) {
 function projectIncludeGlobs(config) {
     return configGlobFolders(config).map((folder) => `../${folder}/**/*`);
 }
+/** This run's generated workspace directory. Every writer goes through here, so a run that owns a
+ *  different directory (a render check's throwaway server) cannot touch another server's files. */
+export function workspacePath(config, ...segments) {
+    return path.join(config.projectRoot, config.workspaceDir ?? DEFAULT_WORKSPACE_DIR, ...segments);
+}
 /** Writes the self-contained Expo web workspace at `.ds-viewer/` (design §2 "The preview
  *  workspace and `npx ds-viewer dev`"). Rewritten freely on every `dev` run — nothing here is
- *  user-owned. */
+ *  user-owned.
+ *
+ *  `updateEndpoint` is the caller's own, inlined into `entry.tsx`. Without one (a render check's
+ *  throwaway server, `--no-update-endpoint`) the catalog is served with no endpoint at all, so it
+ *  makes no calls: the shell polls `/version` from every page, so inlining a *different* server's
+ *  endpoint here would have every page call it from the wrong origin. Two `dev` servers share this
+ *  one directory, so the last writer decides — see the README on running a render check beside an
+ *  open catalog. */
 export function writeWorkspace(config, updateEndpoint) {
-    const workspace = path.join(config.projectRoot, '.ds-viewer');
+    const workspace = workspacePath(config);
     mkdirSync(workspace, { recursive: true });
     writeFileSync(path.join(workspace, 'package.json'), `${JSON.stringify({ name: 'ds-viewer-workspace', private: true, main: 'entry.tsx' }, null, 2)}\n`);
     writeFileSync(path.join(workspace, 'app.json'), `${JSON.stringify({ expo: { name: config.name, slug: 'ds-viewer-workspace', platforms: ['web'] } }, null, 2)}\n`);

package/package.json

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

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

@@ -6,6 +6,7 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'AnimatedChevron',
   group: 'Components',
+  whenToUse: 'An expand/collapse affordance that should animate its own state change — it flips vertically in place, so it never points sideways mid-transition. Where a chevron never changes state, a plain icon is enough.',
   description: 'A chevron that morphs between down (collapsed) and up (expanded) — flipping vertically in place instead of rotating through a sideways-pointing angle, and instead of swapping icons. The morph Banner\'s own collapsible header uses for its disclosure indicator. Not commonly used on its own; exported for building a custom disclosure/accordion toggle.',
   a11y: 'Purely decorative — no accessibility role of its own. Wrap it in an accessible parent (the way Banner\'s own header Pressable does) if the toggle needs to be announced.',
   variants: {

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

@@ -32,6 +32,7 @@ const AVATAR_COMPARISON = grid(
 export default defineCatalogPage({
   component: 'Avatar',
   group: 'Components',
+  whenToUse: 'A person or place\'s identity in a circle. Pass whatever you have: image, icon, or initials are tried in that order, so a missing image degrades to initials without leaving a gap.',
   specimenSize: 'compact',
   comparison: AVATAR_COMPARISON,
   description: 'A circular image, or an initials fallback on a solid fill when there\'s no image (or it fails to load).',

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

@@ -8,48 +8,41 @@ import { BottomSheet } from './BottomSheet';
 import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
 
 const styles = StyleSheet.create({
-  // BottomSheet/Dropdown demos render inside the shared `PhoneFrame` (./PhoneFrame.tsx) so their
-  // absolute overlays stay contained instead of covering the whole catalog page. No padding here —
-  // BottomSheet's own content area already supplies the standard 16px.
-  sheetContent: {},
+  // No padding here — BottomSheet's own content area already supplies the standard 16px.
   cardTitle: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
   cardBody: { ...DS_TYPOGRAPHY.bodySm, color: DS_SEMANTIC.text.muted, marginTop: DS_SPACING[200] },
 });
 
-function BottomSheetDemo() {
+const EXTRA_PARAGRAPHS = [
+  'Board at the front car for a faster transfer at Union Sq.',
+  '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.',
+  'Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible entrances before you travel.',
+];
+
+/** Every example is a real sheet inside a phone: the trigger opens it, the backdrop dismisses it.
+ *  `OverlayDemo` supplies the phone, so the sheet's absolute overlay stays in its own cell. */
+function Sheet({
+  header,
+  footer,
+  /** Extra paragraphs; enough of them and the content area passes 90% height and starts scrolling. */
+  paragraphs = 0,
+}: {
+  header?: (close: () => void) => React.ReactNode;
+  footer?: (close: () => void) => React.ReactNode;
+  paragraphs?: number;
+}) {
   return (
-    <OverlayDemo triggerLabel="Open sheet">
+    // Open from the start: closed, every example is the same empty phone behind the same trigger,
+    // and what each one is named for — the header, the footer, the scrolling — is invisible.
+    <OverlayDemo triggerLabel="Open sheet" initiallyOpen>
       {({ 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>
+        <BottomSheet visible={open} onDismiss={close} header={header?.(close)} footer={footer?.(close)}>
+          <View>
+            <Text style={styles.cardTitle}>Uptown &amp; 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>
+            {EXTRA_PARAGRAPHS.slice(0, paragraphs).map((line) => (
+              <Text key={line} style={styles.cardBody}>{line}</Text>
+            ))}
           </View>
         </BottomSheet>
       )}
@@ -57,6 +50,18 @@ function BottomSheetDemo() {
   );
 }
 
+const topNav = (close: () => void) => (
+  <TopNav
+    title="Trip details"
+    trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={close} />}
+  />
+);
+const dock = (close: () => void) => (
+  <Dock>
+    <Button label="Confirm" onPress={close} />
+  </Dock>
+);
+
 export default defineCatalogPage({
   component: 'BottomSheet',
   group: 'Components',
@@ -67,5 +72,19 @@ export default defineCatalogPage({
   description: 'A sheet that slides up over a dismissible backdrop. Height is driven by its content (not fixed snap points) up to 90% of the available height, then the content area scrolls. Compose header with TopNav and footer with Dock.',
   whenToUse: 'For longer, browsable content, or anything that benefits from a TopNav/Dock header-footer structure. For a short, focused decision that interrupts the flow, use Dialog.',
   a11y: 'The backdrop is a Pressable with accessibilityRole="button" and accessibilityLabel="Dismiss"; header/content/footer carry their own accessibility (e.g. TopNav\'s title as accessibilityRole="header").',
-  render: () => <BottomSheetDemo />,
+  variants: {
+    items: [
+      // Both slots empty: the sheet is only as tall as its content, above its own drag handle.
+      { key: 'content-only', name: 'Content only', node: <Sheet /> },
+      { key: 'header', name: 'With a TopNav header', node: <Sheet header={topNav} /> },
+      { key: 'header-footer', name: 'Header and a Dock footer', node: <Sheet header={topNav} footer={dock} /> },
+    ],
+  },
+  states: {
+    items: [
+      // Past 90% of the phone's height the content area scrolls, which is what turns on the Dock
+      // footer's shadow — overflowing it is the only way to see that happen.
+      { key: 'scrolling', name: 'Content long enough to scroll', node: <Sheet header={topNav} footer={dock} paragraphs={3} /> },
+    ],
+  },
 });

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

@@ -6,6 +6,7 @@ import { Button } from '../Button';
 export default defineCatalogPage({
   component: 'ButtonGroup',
   group: 'Components',
+  whenToUse: 'Two or three Buttons that should read as one family — horizontal for a trailing-aligned pair (a dialog\'s Cancel and Confirm), vertical for up to three stretched full width. Keep one variant tier and one size across the group. For a screen\'s bottom action area, use Dock.',
   composedOf: [
     { component: 'Button', role: "Its children: up to two Buttons side by side, or three stacked.", relationship: 'slot' },
   ],

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

@@ -12,19 +12,18 @@ const styles = StyleSheet.create({
   dialogActions: { marginTop: DS_SPACING[800] },
 });
 
-function DialogDemo() {
+/** Every example is a real dialog inside a phone, so the backdrop covers the screen it belongs to
+ *  rather than the catalog page. `OverlayDemo` supplies the phone and the trigger. */
+function Demo({ title, body, actions }: { title: string; body?: string; actions: (close: () => void) => React.ReactNode }) {
   return (
-    <OverlayDemo triggerLabel="Open dialog">
+    // Open from the start: a closed dialog is just a trigger, so the card each example is named
+    // for would never be on screen.
+    <OverlayDemo triggerLabel="Open dialog" initiallyOpen>
       {({ 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>
+          <Text style={styles.cardTitle}>{title}</Text>
+          {body ? <Text style={styles.cardBody}>{body}</Text> : null}
+          <View style={styles.dialogActions}>{actions(close)}</View>
         </Dialog>
       )}
     </OverlayDemo>
@@ -34,8 +33,58 @@ function DialogDemo() {
 export default defineCatalogPage({
   component: 'Dialog',
   group: 'Components',
+  composedOf: [
+    { component: 'ButtonGroup', role: "Lays out the dialog's actions; a dialog's own children decide this, not Dialog.", relationship: 'related' },
+  ],
   description: 'A card centred on screen over a dismissible backdrop — fades and scales in, distinct from BottomSheet\'s bottom-anchored slide. Named Dialog (not Modal) to avoid shadowing React Native\'s own built-in Modal.',
   whenToUse: 'A short, focused decision that interrupts the flow (confirm/cancel, a single form). For anything longer, browsable, or that needs its own internal scrolling, use BottomSheet.',
   a11y: 'The backdrop is a Pressable with accessibilityRole="button" and accessibilityLabel="Dismiss"; content you pass as children carries its own accessibility.',
-  render: () => <DialogDemo />,
+  variants: {
+    items: [
+      {
+        key: 'confirm',
+        name: 'A confirmation, two actions',
+        node: (
+          <Demo
+            title="Delete this trip?"
+            body="This can't be undone."
+            actions={(close) => (
+              <ButtonGroup>
+                <Button label="Cancel" variant="tertiary" onPress={close} />
+                <Button label="Delete" onPress={close} />
+              </ButtonGroup>
+            )}
+          />
+        ),
+      },
+      {
+        key: 'acknowledge',
+        name: 'One action to acknowledge',
+        node: (
+          <Demo
+            title="Trip saved"
+            body="You'll find it under Saved trips."
+            actions={(close) => <Button label="Got it" onPress={close} />}
+          />
+        ),
+      },
+      {
+        // Title alone: Dialog adds no body of its own, so a question that needs no explanation
+        // keeps the card to two lines.
+        key: 'title-only',
+        name: 'Title and actions only',
+        node: (
+          <Demo
+            title="Discard changes?"
+            actions={(close) => (
+              <ButtonGroup>
+                <Button label="Keep editing" variant="tertiary" onPress={close} />
+                <Button label="Discard" onPress={close} />
+              </ButtonGroup>
+            )}
+          />
+        ),
+      },
+    ],
+  },
 });

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

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'Divider',
   group: 'Components',
+  whenToUse: 'A single hairline between two pieces of content you are laying out yourself. List already puts one between each pair of its rows, so adding your own there would double them.',
   specimenSize: 'regular',
   description: 'A 1px hairline separator at the divider token colour.',
   a11y: 'A plain, non-interactive View — purely decorative.',

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

@@ -6,6 +6,7 @@ import { Dock } from './Dock';
 export default defineCatalogPage({
   component: 'Dock',
   group: 'Components',
+  whenToUse: 'A screen\'s bottom action area: up to three full-width buttons above the home indicator, with an optional caption. It is not positioned absolutely itself — the composing screen decides whether to pin it or lay it out inline at the end of a column. For actions inside a card or dialog, use ButtonGroup.',
   composedOf: [
     { component: 'Button', role: "Its children: up to three full-width Buttons, stacked.", relationship: 'slot' },
   ],

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

@@ -13,6 +13,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'FieldContainer',
   group: 'Components',
+  whenToUse: 'Building a new kind of field. It carries the shared field chrome and reads the ambient Surface tone, so it stays visible on white and on muted backgrounds alike. For the fields that already exist, use InputField or TextArea instead of wrapping this yourself.',
   composedOf: [
     { component: 'Surface', role: "Reads the surrounding Surface tone: a recessed fill on white, opaque white inside a muted Surface.", relationship: 'related' },
   ],

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

@@ -5,6 +5,7 @@ import { InputClearButton } from './InputClearButton';
 export default defineCatalogPage({
   component: 'InputClearButton',
   group: 'Components',
+  whenToUse: 'The clear control inside a text field. InputField and SearchField already include one, so reach for it directly only when building another field type that needs the same affordance.',
   description: 'The clear (×) button InputField and SearchField both show once a field is active and holds a value — a filled circle-x icon sized to reach the 44pt touch target via hitSlop, not visual size.',
   a11y: 'A Pressable with accessibilityRole="button" and the given (or default "Clear field") accessibilityLabel; hitSlop of 10 on every side pads its 24×24 visual size out to the 44pt minimum.',
   variants: {

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

@@ -9,6 +9,7 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'List',
   group: 'Components',
+  whenToUse: 'A set of ListItem rows as one rounded surface, with dividers between rows and never after the last. For a single row standing on its own, use ListItem directly.',
   specimenSize: 'regular',
   composedOf: [
     { component: 'Divider', role: "The hairline between consecutive items (none after the last).", relationship: 'built-in' },

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

@@ -6,6 +6,7 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'Loading',
   group: 'Components',
+  whenToUse: 'An indeterminate wait of unknown length — `circle` inline, `linear` where a bar suits the layout better. Button and Pill already show this in their own loading states, so don\'t nest one inside them. For a known number of steps, use ProgressDots.',
   specimenSize: 'regular',
   description: 'An indeterminate loader — the shape fills up, empties out, then fills again, seamlessly. Two variants: circle (used internally by Button and Pill for their own loading states) and linear.',
   a11y: 'Exposed to assistive tech as accessibilityRole="progressbar" with accessibilityLabel="Loading" — no extra wiring needed at the call site.',

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

@@ -5,6 +5,7 @@ import { ProgressDots } from './ProgressDots';
 export default defineCatalogPage({
   component: 'ProgressDots',
   group: 'Components',
+  whenToUse: 'A short sequence of steps whose length is known, with the current step widened into a pill. For a wait of unknown length, use Loading.',
   description: 'A row of dots for a stepped flow; the active dot widens into a pill.',
   a11y: 'Decorative progress indicator; convey the "step X of Y" position in text for screen readers.',
   // No `variant` prop exists on ProgressDots — its "Variants" column just shows the one default

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

@@ -1,29 +1,50 @@
 import React, { useState } from 'react';
 import { defineCatalogPage } from '@krapwoo/ds-viewer';
-import { SegmentedToggle } from './SegmentedToggle';
+import { SegmentedToggle, type SegmentedToggleOption } from './SegmentedToggle';
 
-function SegmentedToggleDemo() {
-  const [value, setValue] = useState('map');
-  return (
-    <SegmentedToggle
-      value={value}
-      onChange={setValue}
-      options={[
-        { value: 'map', label: 'Map', iconName: 'map' },
-        { value: 'list', label: 'List', iconName: 'menu' },
-        { value: 'saved', label: 'Saved', iconName: 'bell', badge: 3 },
-        // Label-only segment (no iconName) — the layout every other option's icon would otherwise hide.
-        { value: 'settings', label: 'Settings' },
-      ]}
-    />
-  );
+/** Each example owns its own selection, so the thumb really slides when a segment is pressed. */
+function Demo({ options, initial }: { options: SegmentedToggleOption[]; initial?: string }) {
+  const [value, setValue] = useState(initial ?? options[0].value);
+  return <SegmentedToggle value={value} onChange={setValue} options={options} />;
 }
 
+const TWO: SegmentedToggleOption[] = [
+  { value: 'map', label: 'Map' },
+  { value: 'list', label: 'List' },
+];
+const ICONS: SegmentedToggleOption[] = [
+  { value: 'map', label: 'Map', iconName: 'map' },
+  { value: 'list', label: 'List', iconName: 'menu' },
+  { value: 'saved', label: 'Saved', iconName: 'bell' },
+];
+const MIXED: SegmentedToggleOption[] = [
+  { value: 'map', label: 'Map', iconName: 'map' },
+  { value: 'list', label: 'List', iconName: 'menu' },
+  { value: 'saved', label: 'Saved', iconName: 'bell', badge: 3 },
+  // Label-only, beside segments that have icons: the row keeps one height either way.
+  { value: 'settings', label: 'Settings' },
+];
+
 export default defineCatalogPage({
   component: 'SegmentedToggle',
   group: 'Components',
   description: 'A row of mutually-exclusive options on a recessed track, with a white thumb that slides to the selected segment. Two or more options.',
   whenToUse: 'A filled, heavier-weight control for a primary, prominent choice on the screen. For quieter secondary navigation, use UnderlineTabs.',
   a11y: 'The row is accessibilityRole="tablist"; each segment is a "tab" with accessibilityState.selected reflecting the current value.',
-  render: () => <SegmentedToggleDemo />,
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'two', name: 'Two options', node: <Demo options={TWO} /> },
+      { key: 'icons', name: 'An icon per segment', node: <Demo options={ICONS} /> },
+      { key: 'badge', name: 'A badge, and a label-only segment', node: <Demo options={MIXED} /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      // Where the thumb sits is the component's whole job, so show both ends of the track.
+      { key: 'first', name: 'First segment selected', node: <Demo options={ICONS} initial="map" /> },
+      { key: 'last', name: 'Last segment selected', node: <Demo options={ICONS} initial="saved" /> },
+    ],
+  },
 });

package/starter-kit/components/Shimmer/Breathing.catalog.tsx

@@ -11,6 +11,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'Breathing',
   group: 'Components',
+  whenToUse: 'The raw pulsing block behind Shimmer, exported so a composite skeleton can pulse in lockstep with plain Shimmers off the one shared clock. For an ordinary loading placeholder, use Shimmer.',
   specimenSize: 'regular',
   description:
     "The shared animated primitive behind Shimmer — a solid block that breathes between a low and high colour on one shared, module-level clock, so every Breathing/Shimmer instance on screen stays phase-locked instead of drifting out of sync. Exported so a custom composite skeleton can reuse the same pulse directly instead of going through Shimmer's fixed text/circle/container shapes.",

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

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'Surface',
   group: 'Components',
+  a11y: 'No semantics of its own: it renders a plain filled View and passes its tone down through context, so it adds nothing to the accessibility tree and neither groups nor labels what sits inside it.',
   specimenSize: 'regular',
   description:
     "Declares \"this subtree's background is tone\" — renders a plain View filled with the matching token (surface.white or surface.main) and provides that tone to descendants via context, so a tone-aware component inside (e.g. FieldContainer/InputField) can automatically pick a fill that contrasts with it instead of assuming white.",

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

@@ -10,6 +10,7 @@ function TextAreaDemo() {
 export default defineCatalogPage({
   component: 'TextArea',
   group: 'Components',
+  whenToUse: 'Multiline free text that grows from a minimum height. For a single-line labelled row use InputField — both share FieldContainer\'s chrome.',
   specimenSize: 'regular',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the multi-line input.", relationship: 'built-in' },

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

@@ -32,6 +32,7 @@ function TooltipDemo() {
 export default defineCatalogPage({
   component: 'Tooltip',
   group: 'Components',
+  whenToUse: 'A brief floating label for a control whose purpose an icon alone doesn\'t carry. It measures the trigger\'s real screen position, so the bubble stays inside the screen\'s edges and the arrow still points at the trigger\'s true centre. For something the reader must acknowledge, use Dialog.',
   specimenSize: 'regular',
   description: 'A small floating label anchored above or below its wrapped trigger. Fully controlled — drive `visible` from the trigger\'s own onLongPress/onPressIn, since mobile has no hover.',
   a11y: 'The bubble is a plain, non-interactive View; the trigger you wrap it around carries its own accessibility.',

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

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'TopNav',
   group: 'Components',
+  whenToUse: 'A screen\'s top bar, and BottomSheet\'s header slot. Its leading and trailing slots reserve their width even when empty, so the title stays centred whether one, both, or neither side has content. For actions at the bottom of a screen, use Dock.',
   composedOf: [
     { component: 'Button', role: "The leading and trailing slots, typically small icon Buttons (back, close, an action).", relationship: 'slot' },
   ],

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

@@ -1,28 +1,50 @@
 import React, { useState } from 'react';
 import { defineCatalogPage } from '@krapwoo/ds-viewer';
-import { UnderlineTabs } from './UnderlineTabs';
+import { UnderlineTabs, type UnderlineTabOption } from './UnderlineTabs';
 
-function UnderlineTabsDemo() {
-  const [value, setValue] = useState('all');
-  return (
-    <UnderlineTabs
-      value={value}
-      onChange={setValue}
-      options={[
-        { value: 'all', label: 'All' },
-        // Leading-icon tab — the layout every other option (icon-less) would otherwise hide.
-        { value: 'nearby', label: 'Nearby', iconName: 'pin' },
-        { value: 'favorites', label: 'Favorites', badge: 2 },
-      ]}
-    />
-  );
+/** Each example owns its own selection, so the underline really slides when a tab is pressed. */
+function Demo({ options, initial }: { options: UnderlineTabOption[]; initial?: string }) {
+  const [value, setValue] = useState(initial ?? options[0].value);
+  return <UnderlineTabs value={value} onChange={setValue} options={options} />;
 }
 
+const LABELS: UnderlineTabOption[] = [
+  { value: 'all', label: 'All' },
+  { value: 'nearby', label: 'Nearby' },
+  { value: 'favorites', label: 'Favorites' },
+];
+const WITH_ICON: UnderlineTabOption[] = [
+  { value: 'all', label: 'All' },
+  // A leading icon beside tabs that have none: the row still aligns on one baseline.
+  { value: 'nearby', label: 'Nearby', iconName: 'pin' },
+  { value: 'favorites', label: 'Favorites' },
+];
+const WITH_BADGE: UnderlineTabOption[] = [
+  { value: 'all', label: 'All' },
+  { value: 'nearby', label: 'Nearby', iconName: 'pin' },
+  { value: 'favorites', label: 'Favorites', badge: 2 },
+];
+
 export default defineCatalogPage({
   component: 'UnderlineTabs',
   group: 'Components',
   description: 'A quieter tab switcher — left-aligned labels over a hairline rule, with a sliding underline indicator. Same options/value/onChange API as SegmentedToggle.',
   whenToUse: "Quiet, secondary navigation within a screen that already has a clear primary focus. For a prominent, primary choice, use SegmentedToggle.",
   a11y: 'Each tab is a Pressable label; the underline is a visual indicator only, so selection is also conveyed by the active label weight.',
-  render: () => <UnderlineTabsDemo />,
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'labels', name: 'Labels only', node: <Demo options={LABELS} /> },
+      { key: 'icon', name: 'A leading icon on one tab', node: <Demo options={WITH_ICON} /> },
+      { key: 'badge', name: 'A badge on a tab', node: <Demo options={WITH_BADGE} /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      // The underline's position is the selection, so show it at both ends of the row.
+      { key: 'first', name: 'First tab selected', node: <Demo options={LABELS} initial="all" /> },
+      { key: 'last', name: 'Last tab selected', node: <Demo options={LABELS} initial="favorites" /> },
+    ],
+  },
 });