@krapwoo/ds-viewer 0.1.1 → 0.3.0

package/README.md

@@ -7,63 +7,102 @@ Drop it into a new project, rebrand the tokens, and build.
 
 ```
 design-system-template/
-├── tokens/          ← ONE source of truth (colors, spacing, radius, type, shadow). Platform-neutral.
-│   ├── palette.ts       raw color scale (0–800 per hue)
-│   ├── semantic.ts      role tokens (surface / text / emphasis / shade / border …)
-│   ├── scales.ts        spacing · radius · icon-size
-│   ├── typography.ts    type scale + font weights
-│   ├── shadow.ts        elevation (RN style objects)
-│   └── index.ts         barrel
-├── icons/           ← shared SVG path DATA + the native renderer
-│   ├── paths.ts         platform-neutral icon geometry
-│   ├── types.ts         IconName union
-│   ├── Icon.native.tsx  react-native-svg renderer
-│   └── index.ts         barrel (data + types only)
-├── native/          ← React Native / Expo components + catalog
-│   ├── components/…     one folder per component (Component.tsx, .types.ts, index.ts)
-│   └── catalog/         app-agnostic catalog framework (RN) + CatalogExample.tsx
-└── native-preview/  ← dev-only Expo shell for browsing the catalog in a browser (not part
-                        of the reusable template — see "Browsing the catalog" below)
+├── starter-kit/     ← the starter kit: copied, never imported, into a new project by `init --new`
+│   ├── tokens/          ONE source of truth (colors, spacing, radius, type, shadow). Platform-neutral.
+│   ├── icons/           shared SVG path data + the native (react-native-svg) renderer
+│   ├── components/…     one folder per component: Component.tsx, .types.ts, index.ts, and a
+│   │                    finished Component.catalog.tsx documenting it
+│   ├── pages/           standalone pages (token galleries, Icons, recipes, Manifest)
+│   └── WHEN_TO_USE.md   the deciding question behind every pair of similar components
+├── native/catalog/  ← the viewer itself — app-agnostic, ships in the published package
+└── kit-host/        ← this repo's own view of the starter kit; depends on this package via
+                        `file:..`; `npm run kit:dev` opens it (not part of the published package —
+                        see "Developing this repository" below)
 ```
 
 ## Using `@krapwoo/ds-viewer` in your own project
 
-This repository is also the source of the `@krapwoo/ds-viewer` npm package — a CLI and viewer
-for browsing *your own* app's components, not this template's. In an existing Expo app:
+**New project:**
 
 ```bash
-npx @krapwoo/ds-viewer init
+npx @krapwoo/ds-viewer init --new
 npm install
+npm run ds-viewer dev
 ```
 
-`init` detects your component folders and token modules and, after you confirm the list it prints
-(`--yes` skips the prompt), writes `ds-viewer.config.ts`, a draft `<Export>.catalog.tsx` beside
-each detected component (marked "needs examples" — nothing is invented), a `ds-viewer` package
-script, a `@krapwoo/ds-viewer` devDependency entry, and a `.ds-viewer/` entry in `.gitignore`. The
-`npm install` above is what actually fetches that devDependency — `init` can only add the entry,
-not invoke your package manager. Then:
+`init --new` checks Expo/Node/package requirements, installs `react-native-svg` and
+`react-native-safe-area-context` if your project doesn't have them yet (via `expo install`), then
+copies the starter kit above into `src/ds/` — pass `--kit-root <path>` to put it somewhere else.
+Every component already has a finished example page; `ds-viewer dev` opens the catalog immediately
+with no further authoring needed. Running `init --new` again only adds whatever is still missing —
+it never overwrites a file you've already edited.
+
+**Existing project:**
+
+```bash
+npx @krapwoo/ds-viewer init --existing
+npm install
+```
+
+`init --existing` detects your component folders and token modules and, after you confirm the list
+it prints (`--yes` skips the prompt), writes `ds-viewer.config.ts`, a draft
+`<Export>.catalog.tsx` beside each detected component (marked "needs examples" — nothing is
+invented), a `ds-viewer` package script, a `@krapwoo/ds-viewer` devDependency entry, and a
+`.ds-viewer/` entry in `.gitignore`.
+
+Running `npx @krapwoo/ds-viewer init` with neither `--new` nor `--existing` asks which one you
+want, interactively. `init --yes` alone (no `--new`/`--existing`) skips that question and sets up
+an existing project instead — the same default `--yes` always had in 0.1, so a script that already
+calls `init --yes` keeps working unchanged. The `npm install` above is what actually fetches the
+devDependency `init` added — `init` can only add the entry, not invoke your package manager.
+
+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 in 0.1: `name`, `components`, `exclude`, `tokens`, `pages`,
-`groupOrder` — see `config/index.ts`'s `DsViewerConfig` for each field's exact meaning. Write a
-page with `defineCatalogPage()` from `@krapwoo/ds-viewer` (same shape as this template's own
-`SectionDef`, minus `id`/`path`/`props`, plus `component`, `group`, and `propNotes`).
+`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 —
+records the kit's version), `updateCheck`, `doctor` — see `config/index.ts`'s `DsViewerConfig` for
+each field's exact meaning. Write a page with `defineCatalogPage()` from `@krapwoo/ds-viewer` (same
+shape as a `SectionDef`, minus `id`/`path`/`props`, plus `component`, `group`, and `propNotes`).
+
+`logo`'s own shape decides how it renders, not a separate setting: a roughly square or modestly
+wide image appears as a small mark beside the name; one more than twice as wide as it is tall
+replaces the name entirely as a wordmark. A missing file just warns and falls back to the name
+only. Use PNG if your project transforms SVG imports into components (Metro would otherwise try to
+bundle the logo as a React component, not an image).
 
 The package ships `native/catalog/` as TypeScript source, not pre-built JavaScript — your own
 project's `tsc`/Metro compiles it under your own compiler options, the same as any other local file.
 
+## Developing this repository
+
+This repository views its own starter kit the same way a real user would: `kit-host/` is a small
+Expo project that depends on `@krapwoo/ds-viewer` via `file:..` and points its `ds-viewer.config.ts`
+at `../starter-kit/`. From the repo root:
+
+```bash
+npm run kit:dev          # builds the CLI, then opens the starter kit's own catalog
+npm run check:catalog    # the same headless check CI runs — every page, zero console errors
+```
+
+`kit-host/` also hosts `viewer-pages/` — standalone catalog pages (not shipped in the package)
+documenting the viewer framework's own pieces (`CatalogShell`, `SectionBlock`, `ComparisonGrid`,
+…), shown under a "Viewer" group alongside the starter kit's own pages.
+
 ## Picking the right component
 
 Several components look alike but solve different problems (InputField vs. SearchField vs.
-Dropdown, Toast vs. Banner, Dialog vs. BottomSheet, …). See **[WHEN_TO_USE.md](./WHEN_TO_USE.md)**
+Dropdown, Toast vs. Banner, Dialog vs. BottomSheet, …). See **[WHEN_TO_USE.md](./starter-kit/WHEN_TO_USE.md)**
 for the deciding question behind each pair before reaching for the closest-looking one. For a
-component's exact props/variants/states as structured data (not prose), see
-`native/catalog/manifest.ts`'s `buildComponentManifest()`, also rendered live at the catalog's
-"Manifest" page.
+component's exact props as structured data (not prose), see `@krapwoo/ds-viewer/generated` (built
+live by `sync` from source), also rendered live at the catalog's "Manifest" page.
 
 ## The one rule
 
@@ -72,24 +111,24 @@ rebrand a two-file edit. Read tokens directly: `import { DS_SEMANTIC } from '...
 
 ## Peer dependencies
 
-`react`, `react-native` assumed, plus: `react-native-svg` (icons + LoadingCircle),
+`react`, `react-native` assumed, plus: `react-native-svg` (icons + Loading's circle variant),
 `react-native-safe-area-context` (catalog shell only — not required by the components themselves).
 
 ## Rebranding (make it yours)
 
-1. **Palette** — edit `tokens/palette.ts`: swap the six hue scales for your brand's (keep the 0–800
+1. **Palette** — edit `starter-kit/tokens/palette.ts`: swap the six hue scales for your brand's (keep the 0–800
    shape).
-2. **Semantic** — in `tokens/semantic.ts`, re-point any role you want to shift (e.g. make `emphasis.info`
+2. **Semantic** — in `starter-kit/tokens/semantic.ts`, re-point any role you want to shift (e.g. make `emphasis.info`
    your brand blue). Every component re-themes automatically.
-3. **Type** — adjust `tokens/typography.ts` (sizes/weights) and set your font family at the app root.
+3. **Type** — adjust `starter-kit/tokens/typography.ts` (sizes/weights) and set your font family at the app root.
 
 Nothing else needs touching — components reference roles, not values.
 
 ## Using the components
 
 ```tsx
-import { Button } from '@ds/native/components/Button';
-import { Badge } from '@ds/native/components/Badge';
+import { Button } from './src/ds/components/Button';   // after `init --new` (default --kit-root)
+import { Badge } from './src/ds/components/Badge';
 
 <Button label="Save" variant="primary" onPress={save} />
 <Badge variant="positive" label="On time" leadingIcon="check" />
@@ -98,17 +137,10 @@ import { Badge } from '@ds/native/components/Badge';
 ## Browsing the catalog
 
 `native/catalog/` is a framework-only package (`CatalogShell`, `SectionBlock`, `PropsTable`, …) —
-it has no runnable app of its own. It ships two worked examples, both built the same way (drop
-either behind a dev-only route in your Expo app):
-
-- `native/catalog/CatalogExample.tsx` — **"Native App DS Template"**: documents this template's own
-  DS components (Button, Card, Banner, …).
-- `native/catalog/CatalogFrameworkExample.tsx` — **"Design System DS Catalog"**: documents the
-  catalog framework's own eight pieces (`CatalogShell`, `CatalogSidebar`, `CatalogSearchInput`,
-  `SectionBlock`, `PropsTable`, `VariantGroup`, `TokenRow`, `DividedStack`) plus its own
-  Colors/Spacing/Type Scale token pages (`native/catalog/tokens.ts` — `CATALOG_*`, independent of
-  the host app's DS tokens) — a catalog of the catalog tool itself, useful when you're extending the
-  framework rather than the DS.
+it has no runnable app of its own and no hand-assembled example anymore. A page is just a
+`*.catalog.tsx` file next to its component (or a standalone one for tokens/recipes), written with
+`defineCatalogPage()`; `ds-viewer dev` discovers them, generates their props tables from your real
+component source, and serves the whole thing as one app you never have to add a route for.
 
 Each catalog shows **one page at a time**: a persistent, searchable sidebar and the selected page.
 On web the page is kept in the URL fragment (`#Button`), so refresh, deep links, and back/forward
@@ -133,27 +165,17 @@ Grid columns and list cells are at most 402px wide with 16px padding. A page's `
 slots default to `wide`. The catalog's own look comes from `native/catalog/tokens.ts`, never from
 the host app's tokens.
 
-```tsx
-import { CatalogExample } from '@ds/native/catalog/CatalogExample';
-// or: import { CatalogFrameworkExample } from '@ds/native/catalog/CatalogFrameworkExample';
-// e.g. render one from a `?ds=1` dev route, mirroring the pattern this template's source project used.
-```
-
-For a quick browser preview without a host app, see `native-preview/` — a minimal throwaway Expo
-shell (not part of the reusable template) that renders both via `expo start --web`:
-- `http://localhost:5181/` → CatalogExample ("Native App DS Template")
-- `http://localhost:5181/?catalog=framework` → CatalogFrameworkExample ("Design System DS Catalog")
-
 ## Adding a component (the recipe)
 
-Copy the shape of an existing pair, e.g. `native/components/Button/` or `native/components/Badge/`:
-- `<Name>.tsx` — `StyleSheet.create`, import tokens from `../../../tokens`, icons from
-  `../../../icons/Icon.native`.
+Copy the shape of an existing pair, e.g. `starter-kit/components/Button/` or `starter-kit/components/Badge/`:
+- `<Name>.tsx` — `StyleSheet.create`, import tokens from `../../tokens`, icons from
+  `../../icons/Icon.native`.
 - `<Name>.types.ts` — export `<Name>Props` (+ any `<Name>Variant`).
 - `index.ts` — re-export.
 
-Then add a `SectionDef` for it (id, path, description, props, a11y, and its content) to
-`native/catalog/CatalogExample.tsx`, and to `native/components/index.ts`. `SectionBlock` shows the
+Then add a `<Name>.catalog.tsx` file next to it, written with `defineCatalogPage()` (description,
+a11y, and its content — `id`/`path`/`props` are derived, never authored), and export it from
+`src/ds/components/index.ts` the same way its siblings are. `SectionBlock` shows the
 specimens first, then Guidance, Quick reference, and Props. Give it whichever of these fields
 actually apply:
 - `comparison: { rowLabel, columnLabel, rows, columns, cells, size? }` — when two props genuinely
@@ -184,22 +206,104 @@ 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.
+
 ## What's included
 
-Tokens · Icons (44) · and generic components:
-Button · Badge · Divider · LoadingCircle · Card · NestedCard · SectionHeader · Banner · Status ·
-FieldContainer · InputField · TextArea · InputClearButton · SearchField · Pill · PillRow ·
-SegmentedToggle · UnderlineTabs · Toast · ProgressDots · Shimmer · Collapsible · AnimatedChevron.
+Tokens · Icons (45) · and generic components:
+AnimatedChevron · Avatar · Badge · Banner · BottomSheet · Button · ButtonGroup · Card · Checkbox ·
+Dialog · Divider · Dock · Dropdown · EmptyState · FieldContainer · InputClearButton · InputField ·
+List · ListItem · Loading · Pill · PillRow · ProgressDots · Radio · SearchField · SectionHeader ·
+SegmentedToggle · Shimmer · Surface · Switch · TextArea · Toast · Tooltip · TopNav · UnderlineTabs.
 
-Deliberately **not** included (app/overlay-specific, port per project): gesture bottom sheets, nav
-bars, modals, and any domain components. They depend on navigation/gesture stacks that vary by app.
+Deliberately **not** included: any domain-specific component. Everything here depends only on
+generic navigation/gesture stacks (`BottomSheet`, `Dialog`, `Dock`, `TopNav` are included) — what's
+left out is app content, not app chrome.
 
 ## Porting to another platform later
 
-The token layer (`tokens/`) and icon data (`icons/paths.ts`, `icons/types.ts`) are already
-platform-neutral — no React Native or DOM imports. Only `native/` (components + catalog) and the
-`Icon.native.tsx` renderer are RN-specific. When you need this design system on another platform
-(web, desktop via Tauri/Electron, etc.), that's a translation of `native/` against those same
-tokens and icon data — a `web/` (or other) tree was built this way once already for this exact
+The token layer (`starter-kit/tokens/`) and icon data (`starter-kit/icons/paths.ts`,
+`starter-kit/icons/types.ts`) are already platform-neutral — no React Native or DOM imports. Only
+`starter-kit/components/` and the `Icon.native.tsx` renderer are RN-specific. When you need this
+design system on another platform (web, desktop via Tauri/Electron, etc.), that's a translation of
+`starter-kit/components/` against those same tokens and icon data — a `web/` (or other) tree was built this way once already for this exact
 template and later removed to keep the template single-platform until it's actually needed; ask
 for that port again when you're ready rather than maintaining an unused second tree in the meantime.

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/config.js

@@ -55,6 +55,28 @@ export function loadConfig(configPath) {
     };
     return { config, warnings };
 }
+/** Design §1 Ownership table — a missing `logo` file is a warning, never a hard error: the
+ *  sidebar simply falls back to the name-only header. Resolved relative to `projectRoot` with
+ *  `path.resolve` — the same way `cli/workspace.ts` resolves `config.logo` to actually `require`
+ *  it — not `path.join`, which nests an absolute `logo` value *under* `projectRoot` instead of
+ *  using it directly, misreporting a real file as "not found" (Minor finding, Fable's
+ *  implementation review, cli/config.ts:74 vs cli/workspace.ts:134). A `logo` that resolves
+ *  outside `projectRoot` is also rejected here, with its own clear warning: `cli/workspace.ts`
+ *  only watches folders under `projectRoot`, so letting it through would surface later as an
+ *  unclear Metro bundling error instead. */
+export function validateLogo(projectRoot, logo) {
+    if (!logo)
+        return {};
+    const resolved = path.resolve(projectRoot, logo);
+    if (!existsSync(resolved)) {
+        return { warning: `Logo not found: ${logo} — showing the name instead.` };
+    }
+    const relativeToRoot = path.relative(projectRoot, resolved);
+    if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+        return { warning: `Logo is outside the project root: ${logo} — showing the name instead.` };
+    }
+    return { logo };
+}
 /** Loads `<projectRoot>/ds-viewer.config.ts`, attaches where it came from, and prints any
  *  "unknown field" warning so every CLI command that resolves a config reports them the same way. */
 export function resolveConfig(projectRoot) {
@@ -62,5 +84,8 @@ export function resolveConfig(projectRoot) {
     const { config, warnings } = loadConfig(configPath);
     for (const warning of warnings)
         console.warn(warning);
-    return { ...config, projectRoot, configPath };
+    const { logo, warning: logoWarning } = validateLogo(projectRoot, config.logo);
+    if (logoWarning)
+        console.warn(logoWarning);
+    return { ...config, logo, projectRoot, configPath };
 }

package/dist/cli/dev.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, watch } from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { resolveConfig } from "./config.js";
 import { sync } from "./sync.js";
 import { writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
@@ -40,19 +41,34 @@ export function watchTargetFolders(config) {
     const patterns = [...config.components, ...(config.tokens ?? []), ...(config.pages ?? [])];
     return [...new Set(patterns.map((pattern) => path.join(config.projectRoot, globBaseFolder(pattern))))].filter((folder) => existsSync(folder));
 }
+/** Re-resolves `<projectRoot>/ds-viewer.config.ts` from disk, syncs from it, and rewrites the
+ *  generated workspace (entry.tsx, metro.config.js, …) from the freshly-resolved values — unlike
+ *  plain `sync(config)`, which only ever regenerates `.ds-viewer/generated/` from whatever
+ *  `ResolvedConfig` it was already given. `dev`'s config-file watcher (below) calls this instead
+ *  of `sync` directly: without it, a changed `name` or `logo` never reached the generated
+ *  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) {
+    const config = resolveConfig(projectRoot);
+    sync(config);
+    writeWorkspace(config);
+    return config;
+}
 /** 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(config) {
-    assertLocalInstall(config.projectRoot);
+export async function dev(initialConfig) {
+    assertLocalInstall(initialConfig.projectRoot);
+    let config = initialConfig;
     sync(config);
     const workspace = writeWorkspace(config);
     const port = await findFreePort(5181, 5199);
     console.log(`Starting the catalog at http://localhost:${port}`);
     let debounceTimer;
-    const onChange = (_eventType, relativePath) => {
+    const onSourceChange = (_eventType, relativePath) => {
         if (relativePath && !isWatchedPath(relativePath))
             return;
         clearTimeout(debounceTimer);
@@ -65,9 +81,25 @@ export async function dev(config) {
             }
         }, 200);
     };
+    // A distinct debounce/handler from `onSourceChange` above: a config change needs
+    // `reloadWorkspace` (re-resolve, then rewrite the generated workspace too), not just `sync` with
+    // the config this closure already captured — otherwise a changed `name`/`logo` never reaches
+    // `entry.tsx`/`metro.config.js` until `dev` is restarted (controller end-to-end finding E1).
+    let configDebounceTimer;
+    const onConfigChange = () => {
+        clearTimeout(configDebounceTimer);
+        configDebounceTimer = setTimeout(() => {
+            try {
+                config = reloadWorkspace(config.projectRoot);
+            }
+            catch (error) {
+                console.warn(`Could not reload ds-viewer.config.ts after a change: ${error.message}`);
+            }
+        }, 200);
+    };
     const watchers = [
-        ...watchTargetFolders(config).map((folder) => watch(folder, { recursive: true }, onChange)),
-        ...(existsSync(config.configPath) ? [watch(config.configPath, onChange)] : []),
+        ...watchTargetFolders(config).map((folder) => watch(folder, { recursive: true }, onSourceChange)),
+        ...(existsSync(config.configPath) ? [watch(config.configPath, onConfigChange)] : []),
     ];
     for (const watcher of watchers) {
         watcher.on('error', (error) => console.warn(`File watcher error: ${error.message}`));
@@ -83,4 +115,17 @@ export async function dev(config) {
             watcher.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']) {
+        process.on(signal, () => {
+            for (const watcher of watchers)
+                watcher.close();
+            child.kill(signal);
+            process.exit(0);
+        });
+    }
 }