@krapwoo/ds-viewer 0.6.7 → 0.6.9

package/README.md

@@ -65,6 +65,13 @@ npm run ds-viewer doctor   # checks every page for drift and coverage gaps (--js
 npm run ds-viewer explain <Page>   # prints why a page's specimens are laid out the way they are
 ```
 
+Only one `dev` serves a project at a time. A second one refuses, naming the port the first is on,
+because both would generate into the same `.ds-viewer/` and overwrite each other's files — the
+loser then serves a workspace that no longer describes it, which Expo reports as an unresolvable
+`main` field rather than as a second server. To run two deliberately, give one its own directory
+with `--workspace-dir .ds-viewer-second`. A lock left behind by a crashed `dev` never blocks the
+next one.
+
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
 sidebar beside the name, or in place of it for a wide wordmark; validated at `sync`/`dev` time
 and bundled into the preview workspace), `components`, `exclude`, `tokens`, `pages`, `groupOrder`, `starterKit` (new-project only —
@@ -622,6 +629,16 @@ Downloads the target version, runs its own `migrate --from <your version>`, upgr
 whichever package manager your lockfile names, re-runs `migrate` for real, then `doctor`. Changes
 are left uncommitted — review them like any other change.
 
+The upgrade keeps the package in whichever section your `package.json` already declares it in,
+rather than always writing a devDependency.
+
+If that spec is a local one — `file:`, `link:`, `workspace:`, `portal:`, or a bare path — `update`
+refuses and tells you how to proceed, because installing a published version would replace the
+checkout your project deliberately points at. The catalog would keep running while no longer
+reflecting the source you are editing, which is hard to notice. `--force` does not override this:
+it exists for uncommitted files, not for changing where the package comes from. The update page's
+**Update now** refuses the same way, reporting it as a failed install step.
+
 ### `npx ds-viewer migrate --from <version>`
 
 Runs every migration introduced after `<version>` — `update` calls this for you; run it directly

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 { workspacePath, writeWorkspace } from "./workspace.js";
+import { clearDevLock, liveDevLock, workspacePath, writeDevLock, 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";
@@ -14,10 +14,16 @@ import { readOwnVersion } from "./packageVersion.js";
 import { createUpdateEndpoint } from "./endpoint.js";
 import { buildUpdatePlan } from "./updatePlan.js";
 import { lastSummaryLine } from "./doctor.js";
-import { detectPackageManager, installUpgradeCommand, platformCommand } from "./packageManager.js";
+import { declaredDependency, detectPackageManager, installUpgradeCommand, isLocalSpec, platformCommand } from "./packageManager.js";
+import { localInstallRefusal } from "./update.js";
 import { DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR } from "./types.js";
 export class LocalInstallMissingError extends Error {
 }
+/** Another `dev` already owns this project's generated workspace. Its own class so `main` can
+ *  print the message plainly, the way it already does for a missing local install, instead of a
+ *  stack trace. */
+export class DevWorkspaceBusyError extends Error {
+}
 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
@@ -142,7 +148,22 @@ export async function performUpdate(config, currentVersion, plan, deps) {
     });
     report(startAt);
     if (startAt <= 1) {
-        const { command, args } = installUpgradeCommand(pm, '@krapwoo/ds-viewer', plan.latest);
+        // The same refusal the CLI gives: installing a registry version over a `file:`/`link:`/
+        // `workspace:` spec would replace the local checkout the project points at, and the catalog
+        // would keep serving while no longer reflecting the source being edited. Reported as a
+        // failure of the install step, so the page offers its normal recovery rather than appearing
+        // to succeed.
+        const declared = declaredDependency(config.projectRoot, '@krapwoo/ds-viewer');
+        if (declared && isLocalSpec(declared.spec)) {
+            deps.onStatus({
+                phase: 'failure',
+                log: localInstallRefusal(declared.spec, plan.latest),
+                failedStep: stepDefs[1].failLabel ?? stepDefs[1].label,
+                step: 'install',
+            });
+            return;
+        }
+        const { command, args } = installUpgradeCommand(pm, '@krapwoo/ds-viewer', plan.latest, declared?.section);
         try {
             await deps.execImpl(command, args, { cwd: config.projectRoot, encoding: 'utf8' });
         }
@@ -269,6 +290,9 @@ export async function performRestart(handoff, deps = {}) {
         if (!exited)
             killGroup(handoff.child, 'SIGKILL');
         await waitForPortFree(handoff.port, deps.probePortFree ?? defaultProbePortFree);
+        // Released before the replacement starts. This process stays alive as the new `dev`'s
+        // supervisor, so a lock still naming it would make its own replacement refuse the workspace.
+        clearDevLock({ projectRoot: handoff.projectRoot, workspaceDir: handoff.workspaceDir });
         // The old child is gone and the port is free — if a signal arrived in the window above (before
         // there was anything to forward it to), this restart is itself cancelled: the user asked to
         // stop, not to come back up on the new version.
@@ -336,6 +360,22 @@ export async function dev(initialConfig, devOptions = {}) {
         rmSync(statusFile, { force: true });
     }
     const port = await findFreePort(devOptions.pinnedPort ?? 5181, devOptions.pinnedPort ?? 5199);
+    // Refused before anything is written: a second `dev` on the same workspace rewrites entry.tsx,
+    // package.json, app.json, metro.config.js and tsconfig.json underneath the first, and the loser
+    // ends up serving a workspace that no longer describes it — Expo reports that as an unresolvable
+    // `main` field, which names neither the other server nor the shared directory.
+    const existing = liveDevLock(config);
+    if (existing) {
+        throw new DevWorkspaceBusyError([
+            `Another ds-viewer dev (pid ${existing.pid}) is already serving this project at http://localhost:${existing.port}.`,
+            '',
+            `Both would generate into ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/ and overwrite each other's files.`,
+            '',
+            'Stop that one first, or give this run its own directory:',
+            `  npx ds-viewer dev --workspace-dir .ds-viewer-second`,
+        ].join('\n'));
+    }
+    writeDevLock(config, { pid: process.pid, port });
     console.log(`Starting the catalog at http://localhost:${port}`);
     let watchersPaused = false;
     // Metro's own child process doesn't exist yet — assigned below, well before this is ever read
@@ -359,7 +399,7 @@ export async function dev(initialConfig, devOptions = {}) {
             },
             restart: async (result) => {
                 writeFileSync(statusFile, JSON.stringify({ phase: 'success', ...result }));
-                await performRestart({ projectRoot: config.projectRoot, port, child, watchers, endpointServer, doctorSummary: result.doctorSummary, files: result.files });
+                await performRestart({ projectRoot: config.projectRoot, workspaceDir: config.workspaceDir, port, child, watchers, endpointServer, doctorSummary: result.doctorSummary, files: result.files });
             },
         }).catch((error) => {
             // `performUpdate` only reports 'failure' from its own guarded steps; anything thrown outside
@@ -470,6 +510,10 @@ export async function dev(initialConfig, devOptions = {}) {
         for (const watcher of watchers)
             watcher.close();
         endpointServer?.close();
+        // Released so the next `dev` is not refused by a lock naming a process that has gone.
+        // `liveDevLock` already ignores a dead pid, so this is tidiness, not correctness — it keeps a
+        // stale file out of a directory a developer may well read.
+        clearDevLock(config);
         process.exitCode = code ?? 0;
     });
     // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
@@ -483,6 +527,7 @@ export async function dev(initialConfig, devOptions = {}) {
             for (const watcher of watchers)
                 watcher.close();
             endpointServer?.close();
+            clearDevLock(config);
             killGroup(child, signal);
             process.exit(0);
         });

package/dist/cli/packageManager.js

@@ -15,17 +15,52 @@ export function detectPackageManager(projectRoot) {
     }
     return 'npm'; // package-lock.json, or no lockfile at all (npm's own documented default either way).
 }
+/** How `pkg` is declared in this project, or undefined when it is not declared at all.
+ *  `dependencies` wins when both sections name it, matching npm's own resolution. */
+export function declaredDependency(projectRoot, pkg) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (!existsSync(packageJsonPath))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    }
+    catch {
+        return undefined; // An unreadable package.json is not this function's error to report.
+    }
+    const fromDeps = parsed.dependencies?.[pkg];
+    if (typeof fromDeps === 'string')
+        return { section: 'dependencies', spec: fromDeps };
+    const fromDevDeps = parsed.devDependencies?.[pkg];
+    if (typeof fromDevDeps === 'string')
+        return { section: 'devDependencies', spec: fromDevDeps };
+    return undefined;
+}
+/** A spec that resolves to something other than a published version: the local source tree, a
+ *  linked folder, or another package in the same workspace. Installing a registry version over one
+ *  of these replaces the thing the project is deliberately pointing at, so `update` refuses rather
+ *  than doing it silently. `npm:` aliases and plain ranges are registry-backed and not local. */
+export function isLocalSpec(spec) {
+    const value = spec.trim();
+    if (/^(file|link|workspace|portal):/i.test(value))
+        return true;
+    // A bare relative or absolute path is a file dependency too — npm accepts `../pkg` unprefixed.
+    return value.startsWith('./') || value.startsWith('../') || value.startsWith('/') || value.startsWith('~/');
+}
 /** The one command `cli/update.ts`'s "Upgrades with the project's package manager" step (design
  *  §5 "`npx ds-viewer update`" step 3) runs, for whichever manager `detectPackageManager` found.
- *  Yarn (classic and Berry both) use the same `yarn add --dev` syntax for upgrading a single
- *  package to an exact version. */
-export function installUpgradeCommand(pm, pkg, version) {
+ *  Yarn (classic and Berry both) use the same `yarn add` syntax for upgrading a single package to
+ *  an exact version. `section` keeps the package in the section it is already declared in; it
+ *  defaults to `devDependencies`, which is where `init` puts it. */
+export function installUpgradeCommand(pm, pkg, version, section = 'devDependencies') {
     const spec = `${pkg}@${version}`;
+    const dev = section === 'devDependencies';
     if (pm === 'npm')
-        return { command: 'npm', args: ['install', '--save-dev', spec] };
+        return { command: 'npm', args: ['install', dev ? '--save-dev' : '--save-prod', spec] };
     if (pm === 'pnpm')
-        return { command: 'pnpm', args: ['add', '--save-dev', spec] };
-    return { command: 'yarn', args: ['add', '--dev', spec] };
+        return { command: 'pnpm', args: ['add', dev ? '--save-dev' : '--save-prod', spec] };
+    // Yarn has no --save-prod: a plain `yarn add` is already a production dependency.
+    return { command: 'yarn', args: dev ? ['add', '--dev', spec] : ['add', spec] };
 }
 const WINDOWS_SHIMS = new Set(['npm', 'npx', 'pnpm', 'yarn']);
 /** On Windows, `npm`, `npx`, `pnpm` and `yarn` are `.cmd` shims, which Node refuses to run

package/dist/cli/update.js

@@ -4,7 +4,7 @@ import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildUpdatePlan, isAlreadyUpToDate } from "./updatePlan.js";
-import { detectPackageManager, installUpgradeCommand, platformCommand } from "./packageManager.js";
+import { declaredDependency, detectPackageManager, installUpgradeCommand, isLocalSpec, platformCommand } from "./packageManager.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { lastSummaryLine } from "./doctor.js";
 function formatPlanHuman(plan) {
@@ -32,6 +32,22 @@ async function defaultConfirm(message) {
 function installedMainJs(projectRoot) {
     return path.join(projectRoot, 'node_modules', '@krapwoo', 'ds-viewer', 'dist', 'cli', 'main.js');
 }
+/** Why an update cannot run over a local checkout, and what to do instead. Shared by the CLI and
+ *  the update page so both refuse in the same words. */
+export function localInstallRefusal(spec, latest) {
+    return [
+        `Refusing: @krapwoo/ds-viewer is installed from "${spec}", not from the registry.`,
+        '',
+        'Updating would install the published package over it, replacing the local checkout this',
+        'project deliberately points at — the catalog would keep running while no longer reflecting',
+        'the source being edited.',
+        '',
+        `To move this project onto the published ${latest}, change the dependency yourself:`,
+        `  npm install --save-dev @krapwoo/ds-viewer@${latest}`,
+        '',
+        'To stay on local source, pull and rebuild it instead.',
+    ].join('\n');
+}
 /** Design §5 "`npx ds-viewer update`", steps 1-6. */
 export async function runUpdate(config, options = {}) {
     const currentVersion = options.currentVersion ?? readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
@@ -41,6 +57,14 @@ export async function runUpdate(config, options = {}) {
     const planText = formatPlanHuman(plan);
     if (options.dryRun)
         return { output: planText, exitCode: 0 };
+    // Refused before the dirty-file check and before any prompt: a `--yes --force` script must not
+    // be able to swap a local checkout for a registry copy either. `--force` deliberately does not
+    // override this — it exists for uncommitted files, not for changing where the package comes
+    // from, which is a decision the project's own package.json already recorded.
+    const declared = declaredDependency(config.projectRoot, '@krapwoo/ds-viewer');
+    if (declared && isLocalSpec(declared.spec)) {
+        return { output: `${planText}\n\n${localInstallRefusal(declared.spec, plan.latest)}`, exitCode: 1 };
+    }
     // Step 2: refuses on any dirty planned file, unless --force — checked before the confirmation
     // prompt, so a script passing --yes without --force still gets refused instead of silently
     // overwriting uncommitted work.
@@ -59,7 +83,9 @@ export async function runUpdate(config, options = {}) {
         const run = platformCommand(cmd, args);
         return execFileSync(run.command, run.args, { ...opts, encoding: 'utf8', shell: run.shell });
     });
-    const { command, args } = installUpgradeCommand(detectPackageManager(config.projectRoot), '@krapwoo/ds-viewer', plan.latest);
+    const { command, args } = installUpgradeCommand(detectPackageManager(config.projectRoot), '@krapwoo/ds-viewer', plan.latest, 
+    // Keep it in the section the project already declared, instead of forcing devDependencies.
+    declared?.section);
     try {
         execImpl(command, args, { cwd: config.projectRoot, encoding: 'utf8' });
     }

package/dist/cli/workspace.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { globBaseFolder } from "./glob.js";
 import { DEFAULT_WORKSPACE_DIR } from "./types.js";
@@ -105,6 +105,52 @@ function projectIncludeGlobs(config) {
 export function workspacePath(config, ...segments) {
     return path.join(config.projectRoot, config.workspaceDir ?? DEFAULT_WORKSPACE_DIR, ...segments);
 }
+const LOCK_FILE = 'dev-lock.json';
+/** Records which `dev` owns this workspace, so a second one can refuse instead of writing over it.
+ *  Two servers sharing one directory both rewrite `entry.tsx`, `package.json`, `app.json`,
+ *  `metro.config.js` and `tsconfig.json`, and the loser is left serving a workspace that no longer
+ *  describes it — reported by Expo as an unresolvable `main` field, which names neither cause. */
+export function writeDevLock(config, lock) {
+    mkdirSync(workspacePath(config), { recursive: true });
+    writeFileSync(workspacePath(config, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`);
+}
+export function clearDevLock(config) {
+    rmSync(workspacePath(config, LOCK_FILE), { force: true });
+}
+/** True when `pid` is a process this user can signal. Signal 0 performs the permission and
+ *  existence checks without delivering anything. EPERM means it exists but belongs to someone
+ *  else, which still counts as alive. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** The live `dev` already serving this workspace, or undefined when there isn't one.
+ *
+ *  A lock left behind by a crashed process is not live, so it never blocks a restart: the pid is
+ *  gone and the file is ignored. `ownPid` is excluded so a process cannot find itself — `dev`'s own
+ *  restart path re-enters this with the lock it just wrote. */
+export function liveDevLock(config, ownPid = process.pid) {
+    const lockPath = workspacePath(config, LOCK_FILE);
+    if (!existsSync(lockPath))
+        return undefined;
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        return undefined; // A partial write from a process that died mid-write owns nothing.
+    }
+    if (typeof lock.pid !== 'number' || typeof lock.port !== 'number')
+        return undefined;
+    if (lock.pid === ownPid || !processAlive(lock.pid))
+        return undefined;
+    return lock;
+}
 /** 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.

package/package.json

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

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

@@ -5,7 +5,9 @@ import { Banner } from './Banner';
 export default defineCatalogPage({
   component: 'Banner',
   group: 'Components',
-  specimenSize: 'regular',
+  // Spans the screen: 'wide' keeps a 402px minimum, so two blocks never share a row and each
+  // specimen keeps a width the component is actually used at.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'AnimatedChevron', role: "The expand/collapse chevron in the header of a collapsible banner.", relationship: 'built-in' },
   ],

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

@@ -13,9 +13,9 @@ 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.',
+  whenToUse: 'Building a new kind of field. It carries the shared field chrome and reads the ambient SurfaceScope 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' },
+    { component: 'SurfaceScope', role: "Publishes the tone this reads: a recessed fill on white, opaque white inside a muted SurfaceScope.", relationship: 'related' },
   ],
   specimenSize: 'regular',
   description: 'The shared field chrome — white surface, medium radius, a 1px border that darkens on focus and mutes when disabled — behind InputField, TextArea, Dropdown, and SearchField, so all four share one visually-consistent field look instead of each re-implementing it.',

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

@@ -1,16 +1,16 @@
 import React from 'react';
 import { View, Pressable, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
 import { DS_SEMANTIC, DS_RADIUS } from '../../tokens';
-import { useSurfaceTone } from '../Surface';
+import { useSurfaceTone } from '../SurfaceScope';
 import type { FieldContainerProps } from './FieldContainer.types';
 
 /**
  * The shared "field" chrome: medium radius, a 1px subtle border that darkens to border.dark on
  * focus, and a fill that contrasts with whatever it's actually placed on — reads the ambient
- * `useSurfaceTone()` (see `Surface`) rather than assuming one fixed background. On the default
+ * `useSurfaceTone()` (see `SurfaceScope`) rather than assuming one fixed background. On the default
  * white tone it's a translucent recessed fill (the same adaptive-overlay mechanism SegmentedToggle's
  * track and Button's own `secondary` variant use); on a `muted` surface (wrapped in
- * `<Surface tone="muted">`) it flips to opaque white instead, so it never goes invisible against
+ * `<SurfaceScope tone="muted">`) it flips to opaque white instead, so it never goes invisible against
  * whatever's behind it either way. It owns *only* the container look — consumers (InputField,
  * TextArea, SearchField) supply their own layout (height, padding, content) via `style` and
  * children, so a single-line row and a multiline area stay visually consistent.

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

@@ -21,7 +21,7 @@ export default defineCatalogPage({
   specimenSize: 'regular',
   composedOf: [
     { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while the field has a value and is focused (or active, when not editable).", relationship: 'built-in' },
-    { component: 'Surface', role: 'Reads the surrounding Surface tone so the field stays visible on a muted Surface.', relationship: 'related' },
+    { component: 'SurfaceScope', role: 'Publishes the tone this reads, so the field stays visible on a muted background.', relationship: 'related' },
   ],
   description: 'A floating-label field. Resting: a centred, body-sized label with no border. Active (focused, or picker with active set) or filled: the label floats to a small top caption, row 2 shows the value/input, and a border fades in while active.',
   whenToUse: 'A named field with a fixed identity ("To", "Arrive by") across the interaction. For free-text search with no floating label, use SearchField; for one of a small known set of choices, use Dropdown.',

package/starter-kit/components/InputField/InputField.tsx

@@ -12,7 +12,7 @@ import {
   type TextInputProps,
 } from 'react-native';
 import { InputClearButton } from '../InputClearButton';
-import { useSurfaceTone } from '../Surface';
+import { useSurfaceTone } from '../SurfaceScope';
 import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_TYPOGRAPHY, DS_FONT_WEIGHT } from '../../tokens';
 import { Icon } from '../../icons/Icon.native';
 import type { IconName } from '../../icons';

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

@@ -0,0 +1,78 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { SurfaceScope } from './SurfaceScope';
+import { InputField } from '../InputField';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  surfaceDemo: { height: 96, justifyContent: 'center', alignItems: 'center', padding: DS_SPACING[800] },
+  surfaceText: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
+  fieldDemo: { padding: DS_SPACING[800], gap: DS_SPACING[400] },
+});
+
+export default defineCatalogPage({
+  component: 'SurfaceScope',
+  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 publishes that tone to everything inside it. Publishing is the half a token cannot do — DS_SEMANTIC.surface.* already holds the values, but a value cannot tell a descendant what it is sitting on.",
+  whenToUse:
+    "Wrap a screen (or any region) wherever its background isn't the default white. Reach for it whenever something inside needs to contrast with the background rather than assume white — that is what makes this a component rather than just the surface.* tokens it paints with.",
+  composedOf: [
+    { component: 'InputField', role: 'One of the components that reads the published tone, via useSurfaceTone(), to pick a fill that stays visible on it.', relationship: 'related' },
+    { component: 'FieldContainer', role: 'The shared field chrome that actually does the reading, on behalf of every field built from it.', relationship: 'related' },
+  ],
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'white',
+        name: 'White',
+        props: { tone: 'white' },
+        node: (
+          <SurfaceScope tone="white" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.white</Text>
+          </SurfaceScope>
+        ),
+      },
+      {
+        key: 'muted',
+        name: 'Muted',
+        props: { tone: 'muted' },
+        node: (
+          <SurfaceScope tone="muted" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.main</Text>
+          </SurfaceScope>
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    // The two cells above only show which token gets painted, which a swatch could do. These show
+    // the part that needs a component: the same field, told nothing, picking a different fill
+    // because of the scope it happens to be inside.
+    items: [
+      {
+        key: 'field-on-white',
+        name: 'A field inside tone="white"',
+        node: (
+          <SurfaceScope tone="white" style={styles.fieldDemo}>
+            <InputField label="Name" value="Recessed fill" />
+          </SurfaceScope>
+        ),
+      },
+      {
+        key: 'field-on-muted',
+        name: 'The same field inside tone="muted"',
+        node: (
+          <SurfaceScope tone="muted" style={styles.fieldDemo}>
+            <InputField label="Name" value="Opaque white" />
+          </SurfaceScope>
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/SurfaceScope/SurfaceScope.tsx

@@ -0,0 +1,51 @@
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC } from '../../tokens';
+
+export type SurfaceTone = 'white' | 'muted';
+
+// Defaults to 'white' — a screen with no explicit <SurfaceScope> ancestor is assumed to sit on a
+// white background, the common case (matches e.g. Card's own default fill).
+const SurfaceToneContext = createContext<SurfaceTone>('white');
+
+/** What background tone the nearest ancestor `<SurfaceScope>` declared (or 'white' if there isn't
+ *  one). Components that need to contrast with whatever's actually behind them — FieldContainer/
+ *  InputField today — read this instead of assuming one fixed background. */
+export function useSurfaceTone(): SurfaceTone {
+  return useContext(SurfaceToneContext);
+}
+
+export interface SurfaceScopeProps {
+  /** Which background this scope renders. Descendants read this via `useSurfaceTone()` to
+   *  automatically pick a fill that contrasts with it (e.g. a field goes white on a muted page,
+   *  recessed on a white one) instead of needing to be told individually. */
+  tone: SurfaceTone;
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+}
+
+/**
+ * Declares "this subtree's background is `tone`": renders a plain View filled with the matching
+ * token (`surface.white` or `surface.main`) **and** publishes that tone to everything inside it.
+ *
+ * The second half is the reason this is a component and not just a token. `DS_SEMANTIC.surface.*`
+ * already holds the values; what a value cannot do is tell a descendant what it is sitting on.
+ * `FieldContainer` and `InputField` call `useSurfaceTone()` to choose between a translucent
+ * recessed fill and an opaque white one, so a field stays visible either way — that only works
+ * because something above them declared the tone. This is a scoped background declaration, which
+ * is why it is named for the scope rather than for the surface itself.
+ *
+ * Wrap a screen (or any region) wherever its background isn't the default white.
+ */
+export function SurfaceScope({ tone, style, children }: SurfaceScopeProps) {
+  return (
+    <SurfaceToneContext.Provider value={tone}>
+      <View style={[tone === 'white' ? styles.white : styles.muted, style]}>{children}</View>
+    </SurfaceToneContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  white: { backgroundColor: DS_SEMANTIC.surface.white },
+  muted: { backgroundColor: DS_SEMANTIC.surface.main },
+});

package/starter-kit/components/SurfaceScope/index.ts

@@ -0,0 +1,2 @@
+export { SurfaceScope, useSurfaceTone } from './SurfaceScope';
+export type { SurfaceScopeProps, SurfaceTone } from './SurfaceScope';

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

@@ -28,7 +28,9 @@ function ToastDemo() {
 export default defineCatalogPage({
   component: 'Toast',
   group: 'Components',
-  specimenSize: 'regular',
+  // Spans the screen: 'wide' keeps a 402px minimum, so two blocks never share a row and each
+  // specimen keeps a width the component is actually used at.
+  specimenSize: 'wide',
   description: 'A transient confirmation bar. Without a variant it renders the dark surface with inverse text; a variant shifts to a pastel status color.',
   whenToUse: "Transient and self-contained, floating over the screen, expected to go away on its own or via its own action. For a persistent, in-flow message about a standing condition, use Banner.",
   a11y: 'Rendered with accessibilityRole="alert" so screen readers announce it when it appears.',

package/starter-kit/components/index.ts

@@ -27,7 +27,7 @@ export * from './SearchField';
 export * from './SectionHeader';
 export * from './SegmentedToggle';
 export * from './Shimmer';
-export * from './Surface';
+export * from './SurfaceScope';
 export * from './Switch';
 export * from './TextArea';
 export * from './Toast';

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

@@ -14,7 +14,7 @@ import { PillRow, type PillRowItem } from '../components/PillRow';
 import { SearchField } from '../components/SearchField';
 import { SectionHeader } from '../components/SectionHeader';
 import { SegmentedToggle } from '../components/SegmentedToggle';
-import { Surface } from '../components/Surface';
+import { SurfaceScope } from '../components/SurfaceScope';
 import { Toast } from '../components/Toast';
 import { Tooltip } from '../components/Tooltip';
 import { TopNav } from '../components/TopNav';
@@ -123,7 +123,7 @@ function SavedTripsDemo() {
             }
           />
         }
-        bodyWrapper={(body) => <Surface tone="muted" style={styles.savedTripsBody}>{body}</Surface>}
+        bodyWrapper={(body) => <SurfaceScope tone="muted" style={styles.savedTripsBody}>{body}</SurfaceScope>}
         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.
@@ -239,7 +239,7 @@ export default defineCatalogPage({
   composedOf: [
     { component: 'TopNav', role: "The screen header, titled Saved trips, with a Filters button.", relationship: 'built-in' },
     { component: 'Tooltip', role: "The Filter by mode hint on the Filters button.", relationship: 'built-in' },
-    { component: 'Surface', role: "The muted background behind the search, toggles and list.", relationship: 'built-in' },
+    { component: 'SurfaceScope', role: "Declares the muted background behind the search, toggles and list, so the fields inside it pick a fill that stays visible on it.", relationship: 'built-in' },
     { component: 'SearchField', role: "Searches stations.", relationship: 'built-in' },
     { component: 'SegmentedToggle', role: "Switches between List and Map views.", relationship: 'built-in' },
     { component: 'UnderlineTabs', role: "The All, Nearby and Favorites tabs.", relationship: 'built-in' },

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

@@ -1,46 +0,0 @@
-import React from 'react';
-import { Text, StyleSheet } from 'react-native';
-import { defineCatalogPage } from '@krapwoo/ds-viewer';
-import { Surface } from './Surface';
-import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
-
-const styles = StyleSheet.create({
-  surfaceDemo: { height: 96, justifyContent: 'center', alignItems: 'center', padding: DS_SPACING[800] },
-  surfaceText: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
-});
-
-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.",
-  whenToUse:
-    "Wrap a screen (or any region) wherever its background isn't the default white — a page with a muted/grey background, for instance — so anything inside that needs to contrast with its background picks the right fill automatically.",
-  variants: {
-    itemsFill: true,
-    items: [
-      {
-        key: 'white',
-        name: 'White',
-        props: { tone: 'white' },
-        node: (
-          <Surface tone="white" style={styles.surfaceDemo}>
-            <Text style={styles.surfaceText}>surface.white</Text>
-          </Surface>
-        ),
-      },
-      {
-        key: 'muted',
-        name: 'Muted',
-        props: { tone: 'muted' },
-        node: (
-          <Surface tone="muted" style={styles.surfaceDemo}>
-            <Text style={styles.surfaceText}>surface.main</Text>
-          </Surface>
-        ),
-      },
-    ],
-  },
-});

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

@@ -1,45 +0,0 @@
-import React, { createContext, useContext, type ReactNode } from 'react';
-import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
-import { DS_SEMANTIC } from '../../tokens';
-
-export type SurfaceTone = 'white' | 'muted';
-
-// Defaults to 'white' — a screen with no explicit <Surface> ancestor is assumed to sit on a white
-// background, the common case (matches e.g. Card's own default fill).
-const SurfaceToneContext = createContext<SurfaceTone>('white');
-
-/** What background tone the nearest ancestor `<Surface>` declared (or 'white' if there isn't one).
- *  Components that need to contrast with whatever's actually behind them — FieldContainer/
- *  InputField today — read this instead of assuming one fixed background. */
-export function useSurfaceTone(): SurfaceTone {
-  return useContext(SurfaceToneContext);
-}
-
-export interface SurfaceProps {
-  /** Which background this surface renders. Descendants read this via `useSurfaceTone()` to
-   *  automatically pick a fill that contrasts with it (e.g. a field goes white on a muted page,
-   *  recessed on a white one) instead of needing to be told individually. */
-  tone: SurfaceTone;
-  style?: StyleProp<ViewStyle>;
-  children?: ReactNode;
-}
-
-/**
- * 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.
- * Wrap a screen (or any region) in this wherever its background isn't the default white — a page
- * with a muted/grey background, for instance — so anything inside that needs to contrast with its
- * background picks the right fill automatically rather than assuming white.
- */
-export function Surface({ tone, style, children }: SurfaceProps) {
-  return (
-    <SurfaceToneContext.Provider value={tone}>
-      <View style={[tone === 'white' ? styles.white : styles.muted, style]}>{children}</View>
-    </SurfaceToneContext.Provider>
-  );
-}
-
-const styles = StyleSheet.create({
-  white: { backgroundColor: DS_SEMANTIC.surface.white },
-  muted: { backgroundColor: DS_SEMANTIC.surface.main },
-});

package/starter-kit/components/Surface/index.ts

@@ -1,2 +0,0 @@
-export { Surface, useSurfaceTone } from './Surface';
-export type { SurfaceProps, SurfaceTone } from './Surface';