@krapwoo/ds-viewer 0.2.0 → 0.4.0

package/README.md

@@ -61,6 +61,8 @@ Either way, then:
 ```bash
 npm run ds-viewer dev    # opens the catalog in a browser, re-syncing on every file change
 npm run ds-viewer sync   # regenerates component/token/page data without starting a server
+npm run ds-viewer doctor   # checks every page for drift and coverage gaps (--json, --ci)
+npm run ds-viewer explain <Page>   # prints why a page's specimens are laid out the way they are
 ```
 
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
@@ -204,6 +206,155 @@ data, not a component — see `ColorsGallery`/`SpacingGallery`/`TypographyGaller
 output full width under a "Tokens" label and shows only a Quick reference card with the source
 path.
 
+## Keeping the catalog current
+
+### Binding examples to props
+
+A grid's row or column axis can name the real prop it demonstrates:
+
+```tsx
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
+
+comparison: grid(
+  'Variant', 'State',
+  { prop: 'variant', items: [
+    { key: 'primary', label: 'Primary' },
+    { key: 'ghost', label: 'Ghost' },
+  ] },
+  [{ key: 'default', label: 'Default' }, { key: 'disabled', label: 'Disabled' }],
+  (row, column) => <Button variant={row} disabled={column === 'disabled'} onPress={() => {}} />,
+),
+```
+
+Only a prop typed as a string-literal union (2 or more options) can be bound this way; each item's
+`key` must then be a real option of that prop. An axis that doesn't name a single real prop (e.g.
+"which of three optional props is set," or a continuous `number`) stays a plain array of
+`{ key, label }` — just as valid, and never flagged by `doctor`. `variants`/`states` list items use
+the existing `props` tag (`{ key: 'ghost', props: { variant: 'ghost' }, node: ... }`) the same way.
+Binding is what lets `doctor` tell you precisely when a renamed or removed option leaves a stale
+example behind, instead of you finding out by reading the diff.
+
+### `npx ds-viewer doctor`
+
+Reads every page with the TypeScript compiler — it never imports a page file or runs app code.
+Human output is grouped by page, each issue with a one-line fix:
+
+```
+Button
+  [error] bound-option-removed: The row "outline" is bound to "variant", which no longer has that option.
+    Fix: Delete this row, or update its key to a current option of "variant".
+
+0 errors, 1 warning — 38 components (37 with examples), 2 unbound examples.
+```
+
+- `--json` prints the same report as stable, versioned data: `{ version: 1, summary: { errors, warnings, components, withExamples, unboundExamples }, update: null, issues: [{ id, severity, page?, file?, line?, message, fix }] }`. `update` is always `null` in this release (filled in starting 0.4's update check); `file` is always relative to the project root. `line` is populated for a `page-parse-error` found by typechecking a page file (see below), and always `undefined` for every other issue id — threading a real position through every rule is future work.
+- `--ci` exits 1 only when an error was found — a warning alone never fails CI, and `--ci` never makes a network call.
+- `doctor.strict: true` in `ds-viewer.config.ts` promotes every warning to an error, for both the summary counts and `--ci`'s exit code.
+- A page whose layout data (`specimenSize`, `group`, grid `rows`/`columns`, list items' `key`/`name`/`props`/`group`, `propNotes` keys) isn't a literal — written as something other than a literal value, array, object, or a same-file `const` reference — gets one "page not statically checkable" warning. A page file that fails to parse *or typecheck* is `page-parse-error` instead: every page file is also run through the TypeScript type checker (the same way a component file already is), so a genuine syntax or type error in a page is reported with its line.
+
+## Known gaps
+
+- The viewer's own dev-mode console warnings only cover `duplicate-page-id` (design §4's "the same rules appear as development warnings naming the page" — scoped to that one rule in 0.3). Bound-axis drift (`bound-option-removed`, `bound-axis-prop-removed`) has no viewer-side warning yet; `npx ds-viewer doctor` (and its `--ci` workflow) is the only place that catches it today.
+
+### `npx ds-viewer explain <Page>`
+
+Prints each layout decision with its reason, using the exact same pure functions the catalog itself
+renders with:
+
+```
+Button
+Grid (Variant × State)
+  5 rows × 3 columns (regular); 3 of 3 max regular columns used — fits a 1280px laptop.
+```
+
+Side-by-side placement depends on a real measured height, so by default `explain` reports it as
+"decided in the viewer." Pass `--heights <firstBlockPx>,<secondBlockPx>` to check that decision here
+too, assuming a 1280px laptop (952px content width) the same way `doctor`'s own column-limit check
+does. `--json` is available on `explain` as well.
+
+### The `AGENTS.md` section and GitHub Action
+
+`npx @krapwoo/ds-viewer init` (either path) appends a short section to `AGENTS.md` between
+`<!-- ds-viewer:start v1 -->`/`<!-- ds-viewer:end -->` markers — creating the file if it doesn't
+exist — telling an AI working on the project to update a page alongside its component, bind
+examples to props, never invent grid cells or groups, and run `doctor`/`explain` before finishing.
+It also writes `.github/workflows/ds-viewer.yml`, a SHA-pinned Action that installs dependencies
+(picking `npm ci`, `pnpm install --frozen-lockfile`, or `yarn install --immutable` from whichever
+lockfile the project has at that moment) and then runs `npx ds-viewer doctor --ci` on every pull
+request. Both are written once; re-running `init` adds
+either one only if it's missing (an `AGENTS.md` without the start marker counts as missing the
+section, even if the file already has other content) and never touches anything outside its own
+markers or its own file.
+
+## Updating
+
+A quiet line appears in the sidebar footer when a new version is published — a banner too, for a
+major version, dismissible per version. Either opens the update page (`#ds-viewer-update`), which
+shows what would change and one **Update now** button:
+
+```
+0.4.0 → 0.5.0  Minor
+You're on 0.4.0. Released 2 days ago.
+
+What's new
+  •  Faster sync for large kits
+  •  New Tabs component in the starter kit
+
+Files that would change
+  package.json               version
+  package-lock.json          version
+
+[ Update now ]  or run npx ds-viewer update
+```
+
+**Update now** asks the running `dev` process to apply the same steps `update` runs below, over a
+local endpoint that only ever answers the viewer's own page (random port, a per-run secret, exact
+origin match). The secret itself is baked into the generated viewer bundle alongside it — it's the
+endpoint's own Host and exact-Origin checks, not the secret being unguessable, that stop any other
+web page from using it. The viewer restarts itself on the new version and reloads automatically;
+nothing is committed.
+
+If any file the update would touch has uncommitted changes, the panel refuses and names them —
+there's no override in the viewer; commit or stash first, or use `update --force` below. Outside a
+git repository, every file is treated as not dirty (there's nothing to check).
+
+### `npx ds-viewer update`
+
+```
+npx ds-viewer update              # shows the plan, asks to confirm, then updates
+npx ds-viewer update --dry-run    # shows the plan and stops
+npx ds-viewer update --yes        # skip the confirmation prompt
+npx ds-viewer update --force      # update even with uncommitted changes in a planned file
+```
+
+Downloads the target version, runs its own `migrate --from <your version>`, upgrades with
+whichever package manager your lockfile names, re-runs `migrate` for real, then `doctor`. Changes
+are left uncommitted — review them like any other change.
+
+### `npx ds-viewer migrate --from <version>`
+
+Runs every migration introduced after `<version>` — `update` calls this for you; run it directly
+only to catch up a project that upgraded its `package.json` some other way. `--dry-run` reports the
+changes without writing them; `--json` for the machine-readable version. 0.4 ships this framework
+with an empty migration list — it introduces no breaking change of its own.
+
+### `npx ds-viewer kit diff <Component>`
+
+Starter-kit files are copied once by `init` and never touched again — not even by `update`, which
+only ever counts how many differ from the version you're installing. `kit diff <Component>` shows
+your copy against the installed kit's, as a plain diff:
+
+```
+npx ds-viewer kit diff Button
+--- components/Button/Button.catalog.tsx (installed kit)
++++ components/Button/Button.catalog.tsx (yours)
+  ...
+```
+
+Set `starterKit.root` in `ds-viewer.config.ts` if you moved the kit after `init --new` wrote it
+(default `src/ds`); a config from before 0.4 with no `root` field still works — it's inferred from
+your first `components` glob.
+
 ## What's included
 
 Tokens · Icons (45) · and generic components:

package/config/index.ts

@@ -16,8 +16,10 @@ export interface DsViewerConfig {
   pages?: string[];
   /** Sidebar group display order; groups not listed here follow alphabetically. */
   groupOrder?: string[];
-  /** Starter-kit projects only. */
-  starterKit?: { version: string };
+  /** Starter-kit projects only. `root` is the folder `init --new` copied the kit into (default
+   *  `src/ds`); absent on a config written before 0.4, in which case `cli/kitRoot.ts` infers it
+   *  from the first `components` glob instead. */
+  starterKit?: { version: string; root?: string };
   /** @default true */
   updateCheck?: boolean;
   /** `strict: true` promotes `doctor` warnings to errors. */

package/dist/cli/agentsFile.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+const START_MARKER = '<!-- ds-viewer:start v1 -->';
+const END_MARKER = '<!-- ds-viewer:end -->';
+// Design §4's four numbered lines, verbatim — no heading added: the design names only these four
+// lines as the section's content.
+const SECTION_BODY = [
+    "1. When you add or change a component's props or a token, update its \`*.catalog.tsx\` in the same change.",
+    "2. Bind examples to props (\`prop\` on grid axes, \`props\` on list items) so drift is detected.",
+    '3. Never invent grid cells or groups; author only combinations that exist.',
+    "4. Run \`npx ds-viewer doctor\` before finishing and fix every error. Use \`npx ds-viewer explain <Page>\` to check layout; see the README's page-authoring guide.",
+].join('\n');
+/** Design §4 "AGENTS.md section", §1 Ownership, §2 step 3. Appends between the exact markers,
+ *  creating the file when absent — never touches a byte outside them, and never runs at all once
+ *  the start marker is already present, even if the rest of the file looks nothing like what this
+ *  function would have written (design: "An AGENTS.md without the markers counts as missing the
+ *  section" — the converse is also true: a file WITH the marker is never rewritten in 0.3). */
+export function ensureAgentsFileSection(projectRoot) {
+    const agentsPath = path.join(projectRoot, 'AGENTS.md');
+    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
+    if (existing.includes(START_MARKER))
+        return [];
+    // Minor finding (Fable's review): a CRLF `AGENTS.md` must not end up with mixed line endings
+    // after the append — the separator and the whole section below use whichever newline the
+    // existing file already uses.
+    const newline = existing.includes('\r\n') ? '\r\n' : '\n';
+    const separator = existing === '' ? '' : existing.endsWith(`${newline}${newline}`) ? '' : existing.endsWith(newline) ? newline : `${newline}${newline}`;
+    const body = newline === '\n' ? SECTION_BODY : SECTION_BODY.replace(/\n/g, newline);
+    writeFileSync(agentsPath, `${existing}${separator}${START_MARKER}${newline}${body}${newline}${END_MARKER}${newline}`);
+    return [agentsPath];
+}

package/dist/cli/dev.js

@@ -1,11 +1,20 @@
-import { existsSync, readFileSync, watch } from 'node:fs';
+import { existsSync, readFileSync, rmSync, watch, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+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 { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
+import { checkForUpdate, isUpdateCheckEnabled, writeUpdateFile } from "./updateCheck.js";
+import { readOwnVersion } from "./packageVersion.js";
+import { createUpdateEndpoint } from "./endpoint.js";
+import { buildUpdatePlan } from "./updatePlan.js";
+import { lastSummaryLine } from "./doctor.js";
+import { detectPackageManager, installUpgradeCommand } from "./packageManager.js";
 export class LocalInstallMissingError extends Error {
 }
 const IGNORED_WATCH_SEGMENTS = new Set(['.ds-viewer', 'node_modules', '.git']);
@@ -49,26 +58,295 @@ 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) {
+export function reloadWorkspace(projectRoot, updateEndpoint) {
     const config = resolveConfig(projectRoot);
     sync(config);
-    writeWorkspace(config);
+    writeWorkspace(config, updateEndpoint);
     return config;
 }
+/** Design §5: `dev` writes `.ds-viewer/update.json` every run, from a fresh check (respecting the
+ *  24h cache inside `checkForUpdate`) or `null` when checks are disabled — never left unwritten,
+ *  since the generated entry file (Task 17) always imports it. Exported and test-only-injectable
+ *  the same way `reloadWorkspace` already is, so this plan never needs to test `dev()` itself
+ *  (which spawns a real Expo process) to prove this one behavior. */
+export async function refreshUpdateFile(config, ownVersion, options = {}) {
+    const result = isUpdateCheckEnabled(config, options.env ?? process.env)
+        ? await (options.checkForUpdate ?? checkForUpdate)(ownVersion)
+        : undefined;
+    writeUpdateFile(config.projectRoot, result);
+}
+// Promisified, not `execFileSync` — install/migrate/doctor each take real seconds, and this now
+// runs from inside the endpoint's own request-handling process, which must keep answering
+// `/update/status` polls throughout (Critical finding, Fable correction pass: the synchronous
+// version blocked the entire event loop until the whole update finished).
+const execFileAsync = promisify(execFile);
+const defaultExecImpl = async (command, args, options) => (await execFileAsync(command, args, options)).stdout;
+function installedMainJs(projectRoot) {
+    return path.join(projectRoot, 'node_modules', '@krapwoo', 'ds-viewer', 'dist', 'cli', 'main.js');
+}
+function packageManagerLabel(pm) {
+    return pm === 'npm' ? 'npm' : pm === 'pnpm' ? 'pnpm' : 'yarn';
+}
+/** Design §5 "`npx ds-viewer update`" steps 3-5, run from inside `dev` instead of a one-shot CLI
+ *  invocation — every external effect injected (Global Constraints), exactly like `cli/update.ts`'s
+ *  `runUpdate`. The plan's own dirty-file refusal already happened before this was ever called
+ *  (the endpoint, Task 12, refuses `POST /update` itself); this function only ever runs a plan it
+ *  has already been told is safe to apply. */
+export async function performUpdate(config, currentVersion, plan, deps) {
+    const migrationCount = plan.files.filter((f) => f.reason.startsWith('migration:')).length;
+    const pm = detectPackageManager(config.projectRoot);
+    // Names the detected package manager and the real migration count (Important finding, Fable
+    // correction pass: the approved mockup's own `updating` state reads "Installed with npm" and
+    // "Applying 1 migration…", never a generic placeholder). The install step carries its own
+    // present-tense `progressLabel` (Minor finding, Fable correction pass: the in-flight step
+    // previously read "Installed with npm…" — already past tense — while still running) and its own
+    // `failLabel` (the mockup's failure state reads "Install with npm failed", not "Installed with
+    // npm failed" — a different, plain-present phrasing from either the done or in-flight label).
+    const stepDefs = [
+        { label: `Downloaded ${plan.latest}` },
+        { label: `Installed with ${packageManagerLabel(pm)}`, progressLabel: `Installing with ${packageManagerLabel(pm)}`, failLabel: `Install with ${packageManagerLabel(pm)}` },
+        { label: migrationCount > 0 ? `Applying ${migrationCount} migration${migrationCount === 1 ? '' : 's'}` : 'No migrations to apply' },
+        { label: 'Checking pages (doctor)' },
+        { label: 'Restarting the viewer' },
+    ];
+    // `completedCount` steps are 'done', the next one is 'now' (in flight), the rest 'todo' — a
+    // three-way state, not a boolean (Important finding, Fable correction pass; Task 12/15 share
+    // this exact shape). Step 0 (download) is already done — `buildUpdatePlan` already downloaded
+    // the tarball while building the plan this function was handed.
+    const report = (completedCount) => deps.onStatus({
+        phase: 'updating',
+        steps: stepDefs.map((def, i) => ({
+            label: i === completedCount && def.progressLabel ? def.progressLabel : def.label,
+            state: i < completedCount ? 'done' : i === completedCount ? 'now' : 'todo',
+        })),
+    });
+    report(1);
+    const { command, args } = installUpgradeCommand(pm, '@krapwoo/ds-viewer', plan.latest);
+    try {
+        await deps.execImpl(command, args, { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        deps.onStatus({ phase: 'failure', log: error.message, failedStep: stepDefs[1].failLabel ?? stepDefs[1].label });
+        return;
+    }
+    report(2);
+    try {
+        await deps.execImpl('node', [installedMainJs(config.projectRoot), 'migrate', '--from', currentVersion], { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        deps.onStatus({ phase: 'failure', log: error.message, failedStep: stepDefs[2].label });
+        return;
+    }
+    report(3);
+    let doctorOutput;
+    try {
+        doctorOutput = await deps.execImpl('node', [installedMainJs(config.projectRoot), 'doctor'], { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        deps.onStatus({ phase: 'failure', log: error.message, failedStep: stepDefs[3].label });
+        return;
+    }
+    report(4);
+    // Fable Minor finding, raised to Important by the controller: the success page showed the whole
+    // doctor report (30+ lines for a real project) — the mockup's own success state shows one line.
+    const doctorSummary = lastSummaryLine(doctorOutput);
+    deps.onStatus({ phase: 'restarting' });
+    // Errata 2c: wait before actually restarting, so the browser's next `/update/status` poll can
+    // observe the `'restarting'` phase instead of the connection just dropping.
+    await new Promise((resolve) => setTimeout(resolve, deps.delayMs ?? 1500));
+    // `files` lets the `success` status (Task 12/15/16) show what changed after the reload, once
+    // `plan` itself is gone (Important finding, Fable correction pass). `latest` (Errata 1b) lets
+    // the panel render the success state once `update.json` has gone back to `null`.
+    await deps.restart({ doctorSummary, files: plan.files.map((f) => f.path), latest: plan.latest });
+}
+/** Errata 7c: Metro listens on `[::1]` only, so a plain `127.0.0.1` connect probe always reports
+ *  the port as free even while Metro is still bound to it (observed with `lsof`) — `findFreePort`
+ *  itself already tries to bind the port, which fails correctly either way. */
+function defaultProbePortFree(port) {
+    return findFreePort(port, port).then(() => true, () => false);
+}
+async function waitForPortFree(port, probe) {
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        if (await probe(port))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+/** Kills `pid`'s whole process group with `signal` — a negative pid, except on `win32` (Errata
+ *  7e), where there is no process-group concept and `child.kill(signal)` is the only option. */
+function killGroup(child, signal) {
+    if (!child.pid)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            child.kill(signal);
+        }
+        else {
+            process.kill(-child.pid, signal);
+        }
+    }
+    catch {
+        // Already exited.
+    }
+}
+/** Design §5 "Restart handoff" steps 3-5, rewritten in full (Critical finding, Fable correction
+ *  pass — the original version was detached-but-unrefed-and-immediately-exited, which this
+ *  repository's own `scripts/checkCatalogConsole.mjs` already documents as leaving the Expo
+ *  grandchild running on the port): closes everything this `dev` process owns; kills the *whole
+ *  process group* Expo/Metro spawned into (`dev()`, below, now spawns it with `detached: true`,
+ *  the same convention `checkCatalogConsole.mjs`'s own `killDevGroup` already established — a
+ *  negative pid targets the group, not just the one pid `child.kill()` alone would reach); waits
+ *  for the old child to actually exit (or 10s, whichever comes first — Errata 7d) and the port to
+ *  actually free before re-spawning `dev --port <same port>` — this time *not* detached, with
+ *  inherited stdio, so this very process becomes a thin supervisor that forwards
+ *  `SIGINT`/`SIGTERM`/`SIGHUP` to the new child and exits with its code, printing a recovery
+ *  command (and the result this update already recorded) if it exits non-zero, or if anything in
+ *  this function itself throws. Has no unit test (see this task's own note) — proven end-to-end
+ *  in Task 20. */
+export async function performRestart(handoff, deps = {}) {
+    // Errata 7a: remove `dev()`'s own SIGINT/SIGTERM/SIGHUP listeners (Step 5, below) first, before
+    // anything else — otherwise a signal sent to this supervisor mid-restart exits through that old
+    // handler (which tries to kill the already-exiting old child and calls `process.exit(0)`),
+    // orphaning the restarted `dev` and its Metro. `targetChild` starts `undefined`; a signal
+    // delivered before `newChild` exists below used to be silently swallowed instead of cancelling
+    // the restart (Minor finding, Fable correction pass: Ctrl-C in that up-to-15s window brought the
+    // viewer back up instead of stopping it) — `cancelledBeforeSpawn` remembers it instead, so the
+    // new `dev` is never spawned once the old child is gone.
+    let targetChild;
+    let cancelledBeforeSpawn = false;
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+        process.removeAllListeners(signal);
+    const forward = (signal) => {
+        if (targetChild)
+            targetChild.kill(signal);
+        else
+            cancelledBeforeSpawn = true;
+    };
+    process.on('SIGINT', forward);
+    process.on('SIGTERM', forward);
+    process.on('SIGHUP', forward);
+    try {
+        for (const watcher of handoff.watchers)
+            watcher.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.
+        const exited = await Promise.race([
+            new Promise((resolve) => {
+                if (handoff.child.exitCode !== null) {
+                    resolve(true);
+                    return;
+                }
+                handoff.child.once('exit', () => resolve(true));
+            }),
+            new Promise((resolve) => setTimeout(() => resolve(false), 10_000)),
+        ]);
+        if (!exited)
+            killGroup(handoff.child, 'SIGKILL');
+        await waitForPortFree(handoff.port, deps.probePortFree ?? defaultProbePortFree);
+        // 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.
+        if (cancelledBeforeSpawn) {
+            process.exit(0);
+            return;
+        }
+        const newChild = spawn(process.execPath, [...process.execArgv, process.argv[1], 'dev', '--port', String(handoff.port)], { cwd: handoff.projectRoot, stdio: 'inherit' });
+        newChild.on('error', (error) => console.error(`Could not restart the viewer: ${error.message}`));
+        targetChild = newChild;
+        const exitCode = await new Promise((resolve) => newChild.on('exit', (code) => resolve(code ?? 0)));
+        if (exitCode !== 0) {
+            console.error(`The restarted viewer exited unexpectedly (code ${exitCode}).`);
+            console.error('Recover with: npx ds-viewer dev');
+            // Important finding, Fable correction pass: design §5 restart step 5 asks for "the recovery
+            // command and the result of the update" — previously only the recovery command printed here,
+            // losing the install/migrate/doctor result (never shown anywhere else; it ran in-process).
+            console.error(`The update itself finished: ${handoff.doctorSummary}; changed: ${handoff.files.join(', ') || '(none)'}.`);
+        }
+        process.exit(exitCode);
+    }
+    catch (error) {
+        console.error(`Restart failed: ${error.message}`);
+        console.error('Recover with: npx ds-viewer dev');
+        console.error(`The update itself finished: ${handoff.doctorSummary}; changed: ${handoff.files.join(', ') || '(none)'}.`);
+        process.exit(1);
+    }
+}
 /** Design §2 "`dev`": checks the local install, runs `sync`, writes the workspace, starts Expo
  *  web on the first free port from 5181 bound to localhost only, and watches the project for
  *  component/token/page changes to re-run `sync`. Metro's own HMR updates the rendered component
  *  when its source changes, but not the generated props table or page list (Task 17 Step 4 relies
  *  on this: editing `Button.tsx` must update its props table, not just hot-reload the component). */
-export async function dev(initialConfig) {
+export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
+    const ownVersion = readOwnVersion(import.meta.dirname);
+    await refreshUpdateFile(initialConfig, ownVersion);
     let config = initialConfig;
     sync(config);
-    const workspace = writeWorkspace(config);
-    const port = await findFreePort(5181, 5199);
+    // 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');
+    let updateStatus = { phase: 'idle' };
+    if (existsSync(statusFile)) {
+        try {
+            updateStatus = JSON.parse(readFileSync(statusFile, 'utf8'));
+        }
+        catch {
+            // A partial/corrupt write from a process that crashed mid-write — stay idle.
+        }
+        rmSync(statusFile, { force: true });
+    }
+    const port = await findFreePort(devOptions.pinnedPort ?? 5181, devOptions.pinnedPort ?? 5199);
     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
+    // (performUpdate's `restart` callback, which is the only reader, can only run after a real
+    // browser has already loaded the page and clicked "Update now").
+    let child;
+    const secret = randomBytes(24).toString('hex');
+    const allowedOrigin = `http://localhost:${port}`;
+    const endpointDeps = {
+        secret,
+        allowedOrigin,
+        buildPlan: () => buildUpdatePlan(config, ownVersion),
+        startUpdate: (plan) => {
+            watchersPaused = true;
+            void performUpdate(config, ownVersion, plan, {
+                execImpl: defaultExecImpl,
+                onStatus: (status) => {
+                    updateStatus = status;
+                    if (status.phase === 'failure')
+                        watchersPaused = false; // the update stopped — keep developing on the old version.
+                },
+                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 });
+                },
+            }).catch((error) => {
+                // Minor finding, Fable correction pass: `performUpdate` only ever reports `'failure'` from
+                // its own guarded steps — a throw outside them (e.g. `writeFileSync(statusFile)` itself
+                // failing) previously became an unhandled rejection with nothing watching for it.
+                updateStatus = { phase: 'failure', log: error.message, failedStep: 'Updating' };
+                watchersPaused = false;
+            });
+        },
+        getStatus: () => updateStatus,
+    };
+    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 };
+    const workspace = writeWorkspace(config, updateEndpoint);
     let debounceTimer;
     const onSourceChange = (_eventType, relativePath) => {
+        if (watchersPaused)
+            return;
         if (relativePath && !isWatchedPath(relativePath))
             return;
         clearTimeout(debounceTimer);
@@ -87,10 +365,12 @@ export async function dev(initialConfig) {
     // `entry.tsx`/`metro.config.js` until `dev` is restarted (controller end-to-end finding E1).
     let configDebounceTimer;
     const onConfigChange = () => {
+        if (watchersPaused)
+            return;
         clearTimeout(configDebounceTimer);
         configDebounceTimer = setTimeout(() => {
             try {
-                config = reloadWorkspace(config.projectRoot);
+                config = reloadWorkspace(config.projectRoot, updateEndpoint);
             }
             catch (error) {
                 console.warn(`Could not reload ds-viewer.config.ts after a change: ${error.message}`);
@@ -104,28 +384,45 @@ export async function dev(initialConfig) {
     for (const watcher of watchers) {
         watcher.on('error', (error) => console.warn(`File watcher error: ${error.message}`));
     }
-    const child = spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
+    child = spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
         cwd: workspace,
         stdio: 'inherit',
         shell: process.platform === 'win32',
+        detached: true,
     });
     child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
     child.on('exit', (code) => {
         for (const watcher of watchers)
             watcher.close();
+        endpointServer.close();
         process.exitCode = code ?? 0;
     });
-    // Node's default SIGTERM/SIGINT behavior exits this process without touching its children —
-    // left alone, a signal sent only to `dev`'s own pid (not its process group) would leave the
-    // spawned `expo start` running, still bound to its port (Important finding, Fable correction
-    // pass: this is exactly what would hang `check:catalog`'s driving script, Task 11, if `dev`
-    // didn't clean up on its own).
-    for (const signal of ['SIGTERM', 'SIGINT']) {
+    // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
+    // children — left alone, a signal sent only to `dev`'s own pid (not its process group) would
+    // leave the spawned `expo start` running, still bound to its port (Important finding, Fable
+    // correction pass: this is exactly what would hang `check:catalog`'s driving script, Task 11, if
+    // `dev` didn't clean up on its own). SIGHUP (Errata 7b) matters here too: detached Expo is in
+    // its own session, so closing the terminal otherwise leaves Metro bound to the port.
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
         process.on(signal, () => {
             for (const watcher of watchers)
                 watcher.close();
-            child.kill(signal);
+            endpointServer.close();
+            killGroup(child, signal);
             process.exit(0);
         });
     }
+    // Minor finding, Fable correction pass: with Expo now spawned `detached: true`, any uncaught
+    // throw or unhandled rejection in this process (outside the guarded steps above) would otherwise
+    // crash `dev` with no terminal left to send Metro a signal, leaving it bound to the port.
+    const killExpoAndExit = (error) => {
+        console.error(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
+        for (const watcher of watchers)
+            watcher.close();
+        endpointServer.close();
+        killGroup(child, 'SIGTERM');
+        process.exit(1);
+    };
+    process.on('uncaughtException', killExpoAndExit);
+    process.on('unhandledRejection', killExpoAndExit);
 }