@krapwoo/ds-viewer 0.1.1 → 0.2.0

package/README.md

@@ -7,63 +7,100 @@ 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
 ```
 
-`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 +109,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 +135,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 +163,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
@@ -186,20 +206,22 @@ path.
 
 ## 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/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);
+        });
+    }
 }

package/dist/cli/glob.js

@@ -30,6 +30,14 @@ function walk(root, segments, consumed) {
         }
     }
     const [segment, ...rest] = segments;
+    // `readdirSync` never returns "." or ".." as entries, so without this a config glob that climbs
+    // out of its own root (e.g. kit-host's `../starter-kit/components/*/index.ts`, Task 5) would
+    // regex-match against real directory entries and silently resolve to nothing. `path.join` below
+    // already collapses "." and ".." correctly once they're part of `consumed` — this just lets them
+    // reach it instead of being treated as a literal name to search for.
+    if (segment === '..' || segment === '.') {
+        return walk(root, rest, [...consumed, segment]);
+    }
     const dir = path.join(root, ...consumed);
     let entries;
     try {

package/dist/cli/init.js

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
+import { execFileSync } from 'node:child_process';
 import { preflight } from "./preflight.js";
 import { detectComponentFolders, detectTokenFiles } from "./detect.js";
 async function promptConfirm(message) {
@@ -15,25 +16,28 @@ async function promptConfirm(message) {
     rl.close();
     return /^y(es)?$/i.test(answer.trim());
 }
-/** This package's own version — used as the `^x.y.z` devDependency version written below, since a
- *  project run via `npx @krapwoo/ds-viewer init` has no local copy to read its version from yet.
- *  Walks up from this file's own directory looking for the `package.json` named
- *  `@krapwoo/ds-viewer`, rather than a fixed relative path: this file sits one level under the
- *  repo root as `cli/init.ts` (how the test below runs it) but two levels under it once compiled,
- *  as `dist/cli/init.js` — a single `../..` would be wrong for one of the two. */
-function ownVersion() {
+/** This package's own installed root — needed both for `ownVersion()` below and (new in 0.2) to
+ *  find the bundled `starter-kit/` to copy from. Walks up from this file's own directory looking
+ *  for the `package.json` named `@krapwoo/ds-viewer`, rather than a fixed relative path: this file
+ *  sits one level under the repo root as `cli/init.ts` (how tests run it) but two levels under it
+ *  once compiled, as `dist/cli/init.js` — a single `../..` would be wrong for one of the two. */
+function packageRoot() {
     let dir = import.meta.dirname;
     for (let depth = 0; depth < 5; depth += 1) {
         const candidate = path.join(dir, 'package.json');
         if (existsSync(candidate)) {
             const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
             if (pkg.name === '@krapwoo/ds-viewer')
-                return pkg.version;
+                return dir;
         }
         dir = path.dirname(dir);
     }
     throw new Error("Could not find @krapwoo/ds-viewer's own package.json to read its version.");
 }
+function ownVersion() {
+    const pkg = JSON.parse(readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
+    return pkg.version;
+}
 /** Detects the existing indent of a JSON file's first indented line, so rewriting it (e.g.
  *  `package.json` below) doesn't reformat the user's own indentation style. Falls back to two
  *  spaces when nothing indented is found (e.g. a minified `package.json`). */
@@ -85,6 +89,25 @@ export async function initExistingProject(projectRoot, options = {}) {
             written.push(draftPath);
         }
     }
+    written.push(...ensureSharedProjectFiles(projectRoot));
+    const routerWarnings = componentFolders
+        .filter((folder) => folder.relativePath.split(path.sep)[0] === 'app')
+        .map((folder) => `Warning: ${folder.relativePath.split(path.sep).join('/')} is inside an Expo Router "app/" directory; its .catalog.tsx file will become a route.`);
+    const messages = [
+        ...warnings.map((issue) => `Warning: ${issue.package} not found. Run: ${issue.installCommand}`),
+        ...routerWarnings,
+        // "with catalog pages", not "with examples": this counts any existing `<Name>.catalog.tsx`,
+        // including init's own drafts, which explicitly say "Needs examples" — not real coverage yet.
+        `${componentFolders.length} components · ${withExamplesCount} with catalog pages`,
+        'Next: npm install, then npm run ds-viewer dev',
+    ];
+    return { messages, written };
+}
+/** Design §2, "Both paths then write what is missing": `ds-viewer.config.ts` is written by each
+ *  path separately (its contents differ), but the package script, the devDependency entry, and the
+ *  `.gitignore` entry are identical either way. */
+function ensureSharedProjectFiles(projectRoot) {
+    const written = [];
     const packageJsonPath = path.join(projectRoot, 'package.json');
     const packageJsonRaw = readFileSync(packageJsonPath, 'utf8');
     const packageJson = JSON.parse(packageJsonRaw);
@@ -106,26 +129,133 @@ export async function initExistingProject(projectRoot, options = {}) {
     const gitignorePath = path.join(projectRoot, '.gitignore');
     const gitignoreEntry = '.ds-viewer/';
     const existingGitignore = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
-    // `\r\n` line endings leave a trailing `\r` on each split line, which never equals the entry —
-    // trim it per line so a CRLF .gitignore is recognized as already having the entry on a rerun.
     if (!existingGitignore.split('\n').some((line) => line.replace(/\r$/, '') === gitignoreEntry)) {
         const separator = existingGitignore === '' || existingGitignore.endsWith('\n') ? '' : '\n';
         writeFileSync(gitignorePath, `${existingGitignore}${separator}${gitignoreEntry}\n`);
         written.push(gitignorePath);
     }
-    const routerWarnings = componentFolders
-        .filter((folder) => folder.relativePath.split(path.sep)[0] === 'app')
-        .map((folder) => `Warning: ${folder.relativePath.split(path.sep).join('/')} is inside an Expo Router "app/" directory; its .catalog.tsx file will become a route.`);
+    return written;
+}
+const KIT_REQUIRED_PACKAGES = ['react-native-svg', 'react-native-safe-area-context'];
+/** The starter kit's own intended sidebar order (the same list kit-host/ds-viewer.config.ts
+ *  declares, minus "Viewer" — that group only holds kit-host's own framework-docs pages under
+ *  `viewer-pages/`, which `init --new` never copies). Written into a fresh project's config so its
+ *  sidebar isn't left alphabetical (controller end-to-end finding E3). */
+const KIT_GROUP_ORDER = [
+    'Actions', 'Surfaces', 'Inputs', 'Controls', 'Selection', 'Feedback', 'Navigation',
+    'Overlays', 'Layout', 'Sub-Parts', 'Recipes', 'Tokens', 'Reference',
+];
+/** Default `installer` — a real `npx expo install`, run only for whichever of
+ *  `KIT_REQUIRED_PACKAGES` the project doesn't already depend on. Test-injected in every unit test
+ *  (this plan's Global Constraints: never run a real `expo install` in tests). */
+function defaultInstaller(projectRoot, missingPackages) {
+    if (missingPackages.length === 0)
+        return;
+    // Same `shell: process.platform === 'win32'` reasoning as `dev.ts`'s existing `spawn('npx', ...)`
+    // call: Windows resolves `npx` via `npx.cmd`, which `execFileSync` only finds through a shell.
+    execFileSync('npx', ['expo', 'install', ...missingPackages], { cwd: projectRoot, stdio: 'inherit', shell: process.platform === 'win32' });
+}
+/** Copies every file under `srcDir` into `destDir`, skipping any destination file that already
+ *  exists (design's "never overwrites user files" rule — Global Constraints) and reporting, not
+ *  throwing on, one unreadable source file (Error-handling rule). Also reports, rather than
+ *  throwing on, an unreadable nested folder — the same `readdirSync` call recurses, so wrapping it
+ *  here covers every depth — so files already copied before it are still returned, and skips a
+ *  symlinked entry (neither a plain file nor a directory `copyKitIfMissing` should recurse into)
+ *  instead of copying through it (Minor finding, Fable's implementation review,
+ *  cli/init.ts:205-224). Returns every path it wrote. */
+export function copyKitIfMissing(srcDir, destDir) {
+    const written = [];
+    mkdirSync(destDir, { recursive: true });
+    let entries;
+    try {
+        entries = readdirSync(srcDir, { withFileTypes: true });
+    }
+    catch (error) {
+        console.warn(`Could not read ${srcDir}: ${error.message}`);
+        return written;
+    }
+    for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            written.push(...copyKitIfMissing(srcPath, destPath));
+            continue;
+        }
+        if (existsSync(destPath))
+            continue;
+        try {
+            copyFileSync(srcPath, destPath);
+            written.push(destPath);
+        }
+        catch (error) {
+            console.warn(`Could not copy ${path.relative(srcDir, srcPath)}: ${error.message}`);
+        }
+    }
+    return written;
+}
+function newProjectConfigContents(kitRoot, starterKitVersion) {
+    return `import { defineConfig } from '@krapwoo/ds-viewer/config';
+
+export default defineConfig({
+  name: 'My App',
+  components: ['${kitRoot}/components/*/index.ts'],
+  tokens: ['${kitRoot}/tokens/index.ts'],
+  pages: ['${kitRoot}/pages/*.catalog.tsx'],
+  groupOrder: ${JSON.stringify(KIT_GROUP_ORDER)},
+  starterKit: { version: '${starterKitVersion}' },
+});
+`;
+}
+/** The new-project half of `init` (design §2's "new project" column) — existing-project `init` is
+ *  `initExistingProject`, 0.1 scope. No confirmation prompt here: unlike the existing-project path,
+ *  there is nothing to detect or confirm — the kit root is the only user choice, and it's a flag. */
+export async function initNewProject(projectRoot, options = {}) {
+    const { errors, warnings } = preflight(projectRoot);
+    if (errors.length > 0) {
+        return { messages: errors.map((issue) => `Missing ${issue.package}. Run: ${issue.installCommand}`), written: [], exitCode: 1 };
+    }
+    const packageJson = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+    const installedPackages = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    const missingKitPackages = KIT_REQUIRED_PACKAGES.filter((name) => !installedPackages[name]);
+    await (options.installer ?? defaultInstaller)(projectRoot, missingKitPackages);
+    const kitRoot = options.kitRoot ?? 'src/ds';
+    const written = copyKitIfMissing(path.join(packageRoot(), 'starter-kit'), path.join(projectRoot, kitRoot));
+    // Read before `ensureSharedProjectFiles`/the config write below add their own entries — this is
+    // only true when `copyKitIfMissing` itself wrote nothing, i.e. a rerun found every kit file
+    // already present (controller end-to-end finding E2: a second `init --new` claimed to have
+    // copied the kit even though nothing changed on disk).
+    const copiedKitFiles = written.length > 0;
+    const configPath = path.join(projectRoot, 'ds-viewer.config.ts');
+    if (!existsSync(configPath)) {
+        writeFileSync(configPath, newProjectConfigContents(kitRoot, ownVersion()));
+        written.push(configPath);
+    }
+    written.push(...ensureSharedProjectFiles(projectRoot));
     const messages = [
         ...warnings.map((issue) => `Warning: ${issue.package} not found. Run: ${issue.installCommand}`),
-        ...routerWarnings,
-        // "with catalog pages", not "with examples": this counts any existing `<Name>.catalog.tsx`,
-        // including init's own drafts, which explicitly say "Needs examples" — not real coverage yet.
-        `${componentFolders.length} components · ${withExamplesCount} with catalog pages`,
+        ...(missingKitPackages.length > 0 ? [`Installed ${missingKitPackages.join(', ')}.`] : []),
+        copiedKitFiles ? `Copied the starter kit into ${kitRoot}/.` : `Starter kit already present in ${kitRoot}/ — nothing copied.`,
         'Next: npm install, then npm run ds-viewer dev',
     ];
     return { messages, written };
 }
+/** The one new-vs-existing question (design §2's "One question") — `--new`/`--existing` (wired in
+ *  `cli/main.ts`) skip it entirely; this is only reached with neither flag. */
+export async function promptInitMode() {
+    if (!process.stdin.isTTY)
+        return undefined;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question('New or existing project? [new/existing] ');
+    rl.close();
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === 'new' || normalized === 'n')
+        return 'new';
+    if (normalized === 'existing' || normalized === 'e')
+        return 'existing';
+    return undefined;
+}
 function configFileContents(componentFolders, tokenFiles) {
     // Emits both `index.ts` and `index.tsx` globs for every detected parent folder whenever any
     // detected folder uses `.tsx` (`detect.ts` accepts either extension — Important: a project using