@krapwoo/ds-viewer 0.1.0 → 0.2.0

package/dist/cli/main.js

@@ -1,14 +1,113 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { resolveConfig } from "./config.js";
-import { initExistingProject } from "./init.js";
+import { initExistingProject, initNewProject, promptInitMode } from "./init.js";
 import { dev } from "./dev.js";
 import { sync } from "./sync.js";
+const USAGE = `Usage: ds-viewer <command>
+
+Commands:
+  init     Set up the viewer in this project: config, catalog pages, and an npm script
+           --new           start from the starter kit (new project)
+           --existing      detect this project's own components/tokens (existing project)
+           --kit-root DIR  where to copy the starter kit (--new only; default src/ds)
+           --yes           accept the detected components and tokens without asking (--existing only)
+  sync     Regenerate the component, props, token, and page data from source
+  dev      Sync, then serve the catalog on a local web address and keep it current as files change
+
+Options:
+  -h, --help     Show this help
+  -v, --version  Show the installed version`;
+/** Walks up from this file (cli/ in source, dist/cli/ when installed) to the package's own package.json. */
+function packageVersion() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+            if (pkg.name === '@krapwoo/ds-viewer' && pkg.version)
+                return pkg.version;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return 'unknown';
+        dir = parent;
+    }
+}
+/** `--kit-root`'s raw CLI value, normalized to a project-root-relative, forward-slash path — or an
+ *  error when the value can't be made into one. Without this: an absolute value was silently
+ *  relocated *under* the project root by `path.join` (which never does `path.resolve`'s "a later
+ *  absolute segment replaces everything before it" — it just concatenates), a trailing slash
+ *  produced a doubled-slash glob (`src/ds//components/*`), and a quote broke the generated
+ *  config's TypeScript string literal (Minor finding, Fable's implementation review,
+ *  cli/main.ts:59-60 & cli/init.ts:231-233,257). */
+export function parseKitRoot(projectRoot, rawValue) {
+    if (rawValue.includes("'") || rawValue.includes('"')) {
+        return { error: `--kit-root cannot contain a quote (got "${rawValue}")` };
+    }
+    const relative = path.relative(projectRoot, path.resolve(projectRoot, rawValue));
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return { error: `--kit-root must stay inside the project root (got "${rawValue}")` };
+    }
+    return { value: relative.split(path.sep).join('/') };
+}
+/** Parses `init`'s flags and dispatches to `initNewProject`/`initExistingProject` — pulled out of
+ *  `main` so the dispatch (which flags pick which project path, `--yes`'s 0.1-compatible default,
+ *  `--kit-root`'s normalization) is unit-testable with an injected installer, never a real `expo
+ *  install` (Minor finding, Fable's implementation review: "No CLI test covers `--yes` defaulting
+ *  to existing, `--kit-root` parsing, or `--new` dispatch"). */
+export async function runInit(projectRoot, rest, options = {}) {
+    const kitRootIndex = rest.indexOf('--kit-root');
+    // Validated, not just indexed: a bare trailing `--kit-root` (no value) or `--kit-root --yes`
+    // (the next token is itself a flag) would otherwise silently pass `undefined`/`'--yes'` as the
+    // kit root. Both are treated as "no value given", the same as omitting the flag entirely.
+    const kitRootValue = kitRootIndex !== -1 ? rest[kitRootIndex + 1] : undefined;
+    const kitRootRaw = kitRootValue && !kitRootValue.startsWith('--') ? kitRootValue : undefined;
+    let kitRoot;
+    if (kitRootRaw !== undefined) {
+        const parsed = parseKitRoot(projectRoot, kitRootRaw);
+        if (parsed.error)
+            return { messages: [parsed.error], written: [], exitCode: 1 };
+        kitRoot = parsed.value;
+    }
+    let mode = rest.includes('--new') ? 'new' : rest.includes('--existing') ? 'existing' : undefined;
+    // 0.1 had only one `init` path (today's `initExistingProject`) and no mode question at all —
+    // `--yes` alone must keep working exactly as it did for a 0.1 user or script, so `--yes` with
+    // neither `--new` nor `--existing` defaults to `existing`, the same path 0.1's `--yes` always
+    // ran, instead of prompting (which would hang/exit 1 on non-interactive stdin and break them).
+    if (!mode && rest.includes('--yes'))
+        mode = 'existing';
+    if (!mode)
+        mode = await (options.promptMode ?? promptInitMode)();
+    if (!mode) {
+        const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY);
+        // A non-interactive stdin (CI, piped npx) never got to ask the question at all — but a TTY
+        // whose answer `promptInitMode` simply couldn't parse did ask, so it needs its own message,
+        // not the "non-interactive" one (Minor finding, Fable's implementation review).
+        const message = isTTY
+            ? 'Could not parse that answer. Specify --new or --existing directly.'
+            : 'Specify --new or --existing (non-interactive stdin cannot be asked).';
+        return { messages: [`${message}\n\n${USAGE}`], written: [], exitCode: 1 };
+    }
+    return mode === 'new'
+        ? initNewProject(projectRoot, { kitRoot, installer: options.installer })
+        : initExistingProject(projectRoot, { yes: rest.includes('--yes'), confirm: options.confirm });
+}
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const projectRoot = process.cwd();
+    if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+        console.log(USAGE);
+        return;
+    }
+    if (command === '--version' || command === '-v') {
+        console.log(packageVersion());
+        return;
+    }
     if (command === 'init') {
-        const result = await initExistingProject(projectRoot, { yes: rest.includes('--yes') });
+        const result = await runInit(projectRoot, rest);
         for (const message of result.messages)
             console.log(message);
         for (const file of result.written)
@@ -28,7 +127,7 @@ async function main() {
         await dev(config);
         return;
     }
-    console.error(`Unknown command "${command ?? ''}". Usage: ds-viewer <init|dev|sync>`);
+    console.error(`Unknown command "${command}".\n\n${USAGE}`);
     process.exitCode = 1;
 }
 main().catch((error) => {

package/dist/cli/props.js

@@ -52,7 +52,7 @@ export function createComponentReader(entryFiles, options = {}) {
         allowJs: false,
         noEmit: true,
         baseUrl: host.baseUrl,
-        paths: { ...host.paths, ...options.paths },
+        paths: { ...options.fallbackPaths, ...host.paths, ...options.paths },
         // `pathsBasePath` is @internal: it tells the compiler which folder `paths` are relative to when
         // the host tsconfig has `paths` but no `baseUrl` (the TypeScript 6 idiom).
         ...(host.pathsBasePath ? { pathsBasePath: host.pathsBasePath } : {}),
@@ -156,33 +156,23 @@ function readComponentRecord(checker, name, type, declaration, optionRoots) {
     const propsType = signature && signature.parameters.length > 0 ? checker.getTypeOfSymbolAtLocation(signature.parameters[0], declaration) : undefined;
     const implementationDefaults = defaultsFromImplementation(declaration);
     const props = [];
-    const inheritedFrom = new Set();
     if (propsType) {
         const branches = propsType.isUnion() ? propsType.types : [propsType];
         for (const merged of mergeUnionProps(checker, branches)) {
             const { symbol: prop, declaration: propDeclaration, branchCount } = merged;
             const propFile = propDeclaration?.getSourceFile().fileName ?? '';
-            if (propFile.includes('node_modules')) {
-                // `@types/react` itself (e.g. `ref` from `RefAttributes` on a `forwardRef` component) is
-                // not a meaningful "inherited from" fact — every component already uses React — so it's
-                // dropped rather than reported as "plus all react props". A host-type package's own props
-                // (e.g. react-native's `TextInput`) are still reported as before.
-                if (!/[/\\]@types[/\\]react[/\\]/.test(propFile) || /[/\\]@types[/\\]react-native[/\\]/.test(propFile)) {
-                    inheritedFrom.add(path.basename(path.dirname(propFile)));
-                }
+            // A prop declared in `node_modules` (e.g. `value` from react-native's `TextInputProps`) is
+            // never listed individually — `inheritedFrom` below (design §3) summarises the whole
+            // extended type as one row instead.
+            if (propFile.includes('node_modules'))
                 continue;
-            }
             const propType = propDeclaration ? checker.getTypeOfSymbolAtLocation(prop, propDeclaration) : checker.getAnyType();
-            // Under `strict`, an optional prop's type includes `| undefined` (that's how TypeScript
-            // represents `label?: string` when read via a symbol) — print its non-nullable type instead,
-            // keeping any alias name, so the Props table reads "string" rather than "string | undefined".
-            const displayType = prop.flags & ts.SymbolFlags.Optional ? checker.getNonNullableType(propType) : propType;
             const jsDocDefault = prop.getJsDocTags().find((tag) => tag.name === 'default');
-            const baseDesc = ts.displayPartsToString(prop.getDocumentationComment(checker));
+            const baseDesc = joinWrappedLines(ts.displayPartsToString(prop.getDocumentationComment(checker)));
             const isPartial = branchCount < branches.length;
             props.push({
                 name: prop.getName(),
-                type: checker.typeToString(displayType, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope),
+                type: displayTypeString(checker, prop, propType),
                 // A prop present in only some branches is never required overall — the caller can always
                 // pick a branch that omits it — regardless of whether it's required within the branch(es)
                 // it does appear in (that's `merged.requiredInEvery`, checked only when `!isPartial`).
@@ -193,7 +183,165 @@ function readComponentRecord(checker, name, type, declaration, optionRoots) {
             });
         }
     }
-    return { name, file: path.relative(process.cwd(), sourceFile.fileName), props, inheritedFrom: [...inheritedFrom] };
+    const inheritedFrom = propsType ? nodeModulesHeritageNames(checker, propsType.isUnion() ? propsType.types : [propsType]) : [];
+    return { name, file: path.relative(process.cwd(), sourceFile.fileName), props, inheritedFrom };
+}
+/** Design §3 — "Type column: keeps alias names, not expanded unions." An optional prop's type
+ *  (as read via its symbol) includes `undefined` — printed as `"T | undefined"` when `T` has no
+ *  alias of its own (e.g. `label?: string`), but when `T` is itself an alias whose own definition
+ *  already includes `undefined` (react-native's `StyleProp<T>`, React's `ReactNode`), the type as
+ *  declared is simply `T` with no added union member, and `checker.typeToString` already prints
+ *  just the alias name (e.g. `"StyleProp<ViewStyle>"`) — no `| undefined` to strip. Dropping a
+ *  trailing/leading `undefined` segment as *text*, rather than calling `checker.getNonNullableType`
+ *  on the type and re-printing that, is what keeps the alias in both cases: `getNonNullableType`
+ *  rebuilds a fresh, unaliased union once it has to remove a member nested inside an alias's own
+ *  definition (`StyleProp`/`ReactNode`), even though the printed string never needed that member
+ *  removed in the first place. */
+function displayTypeString(checker, prop, propType) {
+    const printed = checker.typeToString(propType, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope);
+    if (!(prop.flags & ts.SymbolFlags.Optional))
+        return printed;
+    const kept = splitTopLevelUnion(printed).filter((part) => part !== 'undefined' && part !== 'null');
+    if (kept.length === 0)
+        return printed;
+    // A single remaining part that is itself wrapped in one outer pair of parentheses (e.g. the
+    // `(() => void)` TypeScript prints around an arrow type that was a union member) no longer needs
+    // those parentheses once it is the only part left — `(t: string) => void`, not `((t: string) =>
+    // void)`.
+    if (kept.length === 1)
+        return unwrapOuterParens(kept[0]);
+    return kept.join(' | ');
+}
+/** Splits a printed type's top-level ` | ` union members — skipping any `|` nested inside
+ *  `<...>`, `(...)`, `{...}`, or `[...]` (e.g. the one inside `RecursiveArray<Falsy | ViewStyle>`)
+ *  — so `displayTypeString` can drop a top-level `undefined`/`null` member without disturbing a
+ *  union that appears only as part of a deeper type argument. An arrow type's `=>` prints a `>`
+ *  that is not a closing bracket, so it must not decrement `depth`: skip it whenever the previous
+ *  character was `=` (otherwise `(() => void) | undefined` goes to depth -1 at the arrow and the
+ *  top-level ` | ` before `undefined` is read as nested, never splitting it off). */
+function splitTopLevelUnion(typeString) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < typeString.length; i++) {
+        const ch = typeString[i];
+        if (ch === '<' || ch === '(' || ch === '{' || ch === '[')
+            depth += 1;
+        else if (ch === '>' || ch === ')' || ch === '}' || ch === ']') {
+            if (ch === '>' && typeString[i - 1] === '=')
+                continue;
+            depth -= 1;
+        }
+        else if (depth === 0 && typeString.startsWith(' | ', i)) {
+            parts.push(typeString.slice(start, i));
+            start = i + 3;
+        }
+    }
+    parts.push(typeString.slice(start));
+    return parts;
+}
+/** Strips one outer `(...)` pair from `part` when it wraps the whole string — not just any
+ *  leading `(`, e.g. `(a) => (b)` has balanced outer parens only around `a`, not around the whole
+ *  expression, so this walks depth to confirm the first `(` closes at the very last character. */
+function unwrapOuterParens(part) {
+    if (part[0] !== '(' || part[part.length - 1] !== ')')
+        return part;
+    let depth = 0;
+    for (let i = 0; i < part.length; i++) {
+        const ch = part[i];
+        if (ch === '(')
+            depth += 1;
+        else if (ch === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return i === part.length - 1 ? part.slice(1, -1) : part;
+        }
+    }
+    return part;
+}
+/** Design §3 — "Inherited props declared in `node_modules` ... are summarised as one row: 'plus
+ *  all TextInput props'." Reads each branch's own `extends` heritage clause(s) — not the flattened
+ *  property list `mergeUnionProps` builds for the table above — because a `node_modules` interface
+ *  like react-native's `TextInputProps` itself extends several more `node_modules` interfaces
+ *  (`ViewProps`, `TouchableWithoutFeedbackProps`, ...), each declared in its own file; grouping by
+ *  every inherited *property*'s own declaration file (the previous approach) reported one noisy
+ *  entry per ancestor file instead of the one name the component's own Props type actually names.
+ *  A `forwardRef` component's props type is `OwnProps & RefAttributes<T>` (an intersection, not an
+ *  interface) — `heritageInterfaceDeclarations` unwraps that to reach `OwnProps`'s own declaration. */
+function nodeModulesHeritageNames(checker, branches) {
+    const names = new Set();
+    for (const branch of branches) {
+        for (const declaration of heritageInterfaceDeclarations(branch)) {
+            const declarationFile = declaration.getSourceFile().fileName;
+            if (declarationFile.includes('node_modules')) {
+                // `declaration` was pulled in directly by the branch itself (e.g. `type Props =
+                // TextInputProps & {...}`), not named in a *local* interface's own `extends` clause —
+                // report its own name. Walking its `heritageClauses` below (as the `extends
+                // TextInputProps` case does) would instead report TextInputProps's own ancestors, e.g.
+                // "View"/"TouchableWithoutFeedback".
+                if (!isReactOnlyFile(declarationFile))
+                    names.add(declaration.name.getText().replace(/Props$/, ''));
+                continue;
+            }
+            for (const clause of declaration.heritageClauses ?? []) {
+                for (const typeNode of clause.types) {
+                    // `getTypeAtLocation` on the whole `ExpressionWithTypeArguments` node (not just its
+                    // `.expression`) is required for `resolveUtilityTypeSource` below to see `Omit`/`Pick`'s
+                    // actual instantiated type arguments — on `.expression` alone they come back as the
+                    // utility type's own unbound generic parameters ("T", "K"), not `TextInputProps`.
+                    const heritageType = resolveUtilityTypeSource(checker.getTypeAtLocation(typeNode));
+                    const heritageDeclaration = (heritageType.aliasSymbol ?? heritageType.symbol)?.declarations?.[0];
+                    if (!heritageDeclaration)
+                        continue;
+                    const file = heritageDeclaration.getSourceFile().fileName;
+                    if (!file.includes('node_modules'))
+                        continue;
+                    // `@types/react` itself (e.g. `Attributes`, reached through a `forwardRef` component's
+                    // own `RefAttributes<T>`) is not a meaningful "inherited from" fact — every component
+                    // already uses React. A host-type package's own heritage (e.g. react-native's `View`,
+                    // reached through `TextInputProps`) is still reported as before.
+                    if (isReactOnlyFile(file))
+                        continue;
+                    const rawName = (heritageType.aliasSymbol ?? heritageType.symbol)?.getName() ?? typeNode.expression.getText();
+                    names.add(rawName.replace(/Props$/, ''));
+                }
+            }
+        }
+    }
+    return [...names];
+}
+/** True for a declaration file under `@types/react` that is not also under `@types/react-native`
+ *  (react-native's own `@types` package path contains `react` as a substring). */
+function isReactOnlyFile(file) {
+    return /[/\\]@types[/\\]react[/\\]/.test(file) && !/[/\\]@types[/\\]react-native[/\\]/.test(file);
+}
+/** `Omit<T, K>`/`Pick<T, K>` of a node_modules type prints its own alias symbol ("Omit"/"Pick")
+ *  rather than `T`'s name — resolve to `T` (the type's first alias type argument) instead, so
+ *  `extends Omit<TextInputProps, 'value'>` reports "TextInput", not "Omit" (Fable's review,
+ *  cli/props.ts:270-301). */
+function resolveUtilityTypeSource(type) {
+    const aliasName = type.aliasSymbol?.getName();
+    if ((aliasName === 'Omit' || aliasName === 'Pick') && type.aliasTypeArguments?.[0]) {
+        return type.aliasTypeArguments[0];
+    }
+    return type;
+}
+/** Every `InterfaceDeclaration` backing `type` — itself if `type` is one, or (recursing) each
+ *  constituent of an intersection, so a `forwardRef` component's `OwnProps & RefAttributes<T>`
+ *  still reaches `OwnProps`'s own heritage clause. */
+function heritageInterfaceDeclarations(type) {
+    if (type.isIntersection())
+        return type.types.flatMap(heritageInterfaceDeclarations);
+    return (type.symbol?.declarations ?? []).filter(ts.isInterfaceDeclaration);
+}
+/** Design §3, finding 4: a JSDoc paragraph hard-wrapped in source (`getDocumentationComment`
+ *  preserves each line break verbatim) must read as running text — join lines within a paragraph
+ *  with a single space, but keep a blank-line paragraph break as its own line break. */
+function joinWrappedLines(text) {
+    return text
+        .split(/\n{2,}/)
+        .map((paragraph) => paragraph.replace(/\s*\n\s*/g, ' ').trim())
+        .join('\n\n');
 }
 /**
  * Design §3 — "Unions of object types (e.g. `CardProps` as two intersections) are merged into one

package/dist/cli/sync.js

@@ -33,7 +33,23 @@ export function sync(config, resolveOptions) {
     const components = [];
     const componentRefs = [];
     const seenNames = new Set();
-    const readComponent = createComponentReader(componentEntryFiles, { ...resolveOptions, optionRoots });
+    // A component entry file can live outside `config.projectRoot` (e.g. kit-host's sibling
+    // `../starter-kit/`) — `createComponentReader`'s own host-tsconfig lookup walks up from the
+    // entry file, never reaching `config.projectRoot`'s own node_modules. This fallback (lowest
+    // priority — a real host `paths`, or `resolveOptions.paths`, still wins) is what lets such a
+    // file still resolve `react`/`react-native` against the project that actually declares them.
+    // `@types/*` is listed BEFORE the plain package deliberately (confirmed by spike,
+    // `spikes/README.md` "sync-fallback-paths"): once `paths` redirects a bare specifier to an
+    // on-disk folder, TypeScript resolves it there and never falls through to a second entry just
+    // because the first has no types — the reverse order left `react`/`react-native` both
+    // resolving to "implicitly any", because the plain package folder matched first. Only computed
+    // when at least one entry file actually lies outside `config.projectRoot` — normal projects
+    // (every entry file under projectRoot) keep standard TypeScript resolution untouched.
+    const hasEntryOutsideProjectRoot = componentEntryFiles.some((file) => !file.startsWith(`${config.projectRoot}${path.sep}`));
+    const fallbackPaths = hasEntryOutsideProjectRoot
+        ? { '*': [path.join(config.projectRoot, 'node_modules', '@types', '*'), path.join(config.projectRoot, 'node_modules', '*')] }
+        : undefined;
+    const readComponent = createComponentReader(componentEntryFiles, { ...resolveOptions, optionRoots, fallbackPaths });
     for (const entryFile of componentEntryFiles) {
         try {
             for (const record of readComponent(entryFile)) {

package/dist/cli/workspace.js

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-const METRO_CONFIG = `const path = require('path');
+import { globBaseFolder } from "./glob.js";
+function metroConfigJs(extraWatchFolders) {
+    return `const path = require('path');
 const fs = require('fs');
 const workspace = __dirname;
 const projectRoot = path.resolve(workspace, '..');
@@ -16,7 +18,18 @@ if (typeof config !== 'object') {
 config.projectRoot = workspace;
 // Expo sets the server root to the folder the config was built for; bundle URLs must resolve from the workspace.
 config.server = { ...(config.server || {}), unstable_serverRoot: workspace };
-config.watchFolders = Array.from(new Set([...(config.watchFolders || []), projectRoot]));
+// Every configured components/tokens/pages glob's base folder — not just projectRoot itself — so a
+// host whose kit lives in a sibling folder (e.g. kit-host/ds-viewer.config.ts reaching
+// ../starter-kit/components) still gets its files watched and bundled. Resolved from projectRoot at
+// runtime, not baked in as an absolute path, so the generated file stays portable across machines.
+const EXTRA_WATCH_FOLDERS = ${JSON.stringify(extraWatchFolders)};
+const extraWatchFolders = EXTRA_WATCH_FOLDERS;
+// A configured components/tokens/pages glob can point at a folder that doesn't exist yet (e.g. a
+// standalone-pages folder before its first file is added) — Metro refuses to watch a nonexistent
+// folder, which otherwise makes every single bundle request fail with HTTP 500. Filtered here, at
+// workspace-generation time, not above at config-resolution time, because a folder created after
+// \`dev\` starts should start being watched on its own next run, same as every other glob folder.
+config.watchFolders = Array.from(new Set([...(config.watchFolders || []), projectRoot, ...extraWatchFolders.map((f) => path.resolve(projectRoot, f)).filter((f) => fs.existsSync(f))]));
 config.resolver.nodeModulesPaths = [path.join(projectRoot, 'node_modules')];
 // A standalone page can read generated data with \`import { components, tokens } from '@krapwoo/ds-viewer/generated'\`
 // (design §3) — redirect that one specifier to this workspace's own generated/index.ts.
@@ -31,17 +44,28 @@ config.resolver.resolveRequest = (context, moduleName, platform) => {
 };
 module.exports = config;
 `;
+}
 /** Decided here, not inside the viewer: Metro resolves `react-native-safe-area-context` statically
  *  at bundle time, so a runtime try/catch `require` cannot skip it when the optional peer is
  *  missing. Importing and wrapping must instead be baked into the generated entry (design §1
  *  "Three parts", Viewer row). */
-function entryTsx(name, hasSafeArea, groupOrder) {
+function entryTsx(name, hasSafeArea, groupOrder, logoRequirePath) {
     const safeAreaImport = hasSafeArea ? "import { SafeAreaProvider } from 'react-native-safe-area-context';\n" : '';
-    const viewer = `<CatalogShell appName={${JSON.stringify(name)}} title="Component Catalog" groups={groups} sections={sections} />`;
+    // A literal `require(...)` with a path computed at generation time: Metro resolves every import
+    // statically, so the logo's actual (arbitrary, user-configured) location must already be baked
+    // into this generated file, the same reasoning `hasSafeArea` above already follows for the
+    // optional SafeAreaProvider import.
+    // `JSON.stringify`, not a plain single-quoted template literal: `logoRequirePath` carries the
+    // user's own logo file name, which may contain a `'` (e.g. `assets/it's.png`) — a bare
+    // `'${logoRequirePath}'` breaks the generated file's syntax the moment it does (Minor finding,
+    // Fable's implementation review, cli/workspace.ts:65).
+    const logoImport = logoRequirePath ? `const logoSource = require(${JSON.stringify(logoRequirePath)});\n` : '';
+    const logoProp = logoRequirePath ? ' logoImageSource={logoSource}' : '';
+    const viewer = `<CatalogShell appName={${JSON.stringify(name)}} title="Component Catalog" groups={groups} sections={sections}${logoProp} />`;
     const root = hasSafeArea ? `<SafeAreaProvider>${viewer}</SafeAreaProvider>` : viewer;
     return `import { registerRootComponent } from 'expo';
 import { CatalogShell, buildCatalogSections } from '@krapwoo/ds-viewer';
-${safeAreaImport}import pages from './generated/pages';
+${safeAreaImport}${logoImport}import pages from './generated/pages';
 import components from './generated/components.json';
 
 function App() {
@@ -52,25 +76,22 @@ function App() {
 registerRootComponent(App);
 `;
 }
-/** The folder a glob pattern varies under — the part of the pattern before its first wildcard
- *  segment (or, for a pattern with no wildcard, its own containing folder). Same logic as
- *  `cli/sync.ts`'s `globBaseFolder` (Task 10), kept local here since it's one line and this module
- *  has no other reason to depend on `sync.ts`. */
-function globBaseFolder(pattern) {
-    const segments = pattern.split('/');
-    const wildcardIndex = segments.findIndex((segment) => segment.includes('*'));
-    const baseSegments = wildcardIndex === -1 ? segments.slice(0, -1) : segments.slice(0, wildcardIndex);
-    return baseSegments.join('/') || '.';
+/** Every configured components/tokens/pages glob's base folder, deduplicated and sorted — shared by
+ *  `projectIncludeGlobs` (tsconfig `include`, below) and `metroConfigJs`'s extra watch folders
+ *  (above). Kept as the raw relative folder (e.g. `"../starter-kit/components"`), not yet turned
+ *  into either a tsconfig glob or an absolute path — each caller does that its own way. */
+function configGlobFolders(config) {
+    const folders = new Set();
+    for (const pattern of [...config.components, ...(config.tokens ?? []), ...(config.pages ?? [])]) {
+        folders.add(globBaseFolder(pattern));
+    }
+    return [...folders].sort();
 }
 /** Folders the workspace's own `tsconfig.json` needs to type-check — derived from the config's own
  *  globs (the spike used `../src/**\/*`), instead of `../**\/*`, which would pull in the whole
  *  project, including `node_modules`. */
 function projectIncludeGlobs(config) {
-    const folders = new Set();
-    for (const pattern of [...config.components, ...(config.tokens ?? []), ...(config.pages ?? [])]) {
-        folders.add(globBaseFolder(pattern));
-    }
-    return [...folders].sort().map((folder) => `../${folder}/**/*`);
+    return configGlobFolders(config).map((folder) => `../${folder}/**/*`);
 }
 /** Writes the self-contained Expo web workspace at `.ds-viewer/` (design §2 "The preview
  *  workspace and `npx ds-viewer dev`"). Rewritten freely on every `dev` run — nothing here is
@@ -88,12 +109,19 @@ export function writeWorkspace(config) {
     if (existsSync(projectTsconfig))
         workspaceTsconfig.extends = '../tsconfig.json';
     writeFileSync(path.join(workspace, 'tsconfig.json'), `${JSON.stringify(workspaceTsconfig, null, 2)}\n`);
-    writeFileSync(path.join(workspace, 'metro.config.js'), METRO_CONFIG);
+    writeFileSync(path.join(workspace, 'metro.config.js'), metroConfigJs(configGlobFolders(config)));
     const projectBabelConfig = path.join(config.projectRoot, 'babel.config.js');
     if (existsSync(projectBabelConfig)) {
         writeFileSync(path.join(workspace, 'babel.config.js'), "module.exports = require('../babel.config.js');\n");
     }
     const hasSafeArea = existsSync(path.join(config.projectRoot, 'node_modules', 'react-native-safe-area-context', 'package.json'));
-    writeFileSync(path.join(workspace, 'entry.tsx'), entryTsx(config.name, hasSafeArea, config.groupOrder ?? []));
+    // `config.logo` is already validated by `cli/config.ts`'s `resolveConfig` (Step 3 above) — by the
+    // time `writeWorkspace` sees it, it's either a real, existing file or undefined. Computed relative
+    // to `workspace` (one level deeper than `projectRoot`), with forward slashes so the generated
+    // `require()` string is portable across machines.
+    const logoRequirePath = config.logo
+        ? path.relative(workspace, path.resolve(config.projectRoot, config.logo)).split(path.sep).join('/')
+        : undefined;
+    writeFileSync(path.join(workspace, 'entry.tsx'), entryTsx(config.name, hasSafeArea, config.groupOrder ?? [], logoRequirePath));
     return workspace;
 }

package/native/catalog/CatalogShell.tsx

@@ -1,5 +1,6 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { AccessibilityInfo, Platform, ScrollView, StyleSheet, Text, View, findNodeHandle } from 'react-native';
+import type { ImageSourcePropType } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { CatalogSidebar } from './CatalogSidebar';
 import { SectionBlock } from './SectionBlock';
@@ -43,6 +44,7 @@ function resetMainScroll(scrollView: ScrollView | null): void {
  */
 export function CatalogShell<TId extends string>({
   appName,
+  logoImageSource,
   title,
   groups,
   sections,
@@ -50,6 +52,9 @@ export function CatalogShell<TId extends string>({
 }: {
   /** Short product/app name — the sidebar logo and the breadcrumb root. */
   appName: string;
+  /** Optional logo image, validated and bundled by `cli/workspace.ts` from the project's `logo`
+   *  config field. See `CatalogSidebar`'s own doc comment for the approved layout rule. */
+  logoImageSource?: ImageSourcePropType;
   /** What this catalog is (e.g. "Component Catalog") — the sidebar caption. */
   title: string;
   groups: NavGroup<TId>[];
@@ -122,7 +127,7 @@ export function CatalogShell<TId extends string>({
 
   return (
     <View style={styles.root}>
-      <CatalogSidebar logo={appName} caption={title} groups={groups} active={active} onPress={select} />
+      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} active={active} onPress={select} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
         {activeDef ? (
           <SectionBlock