@krapwoo/ds-viewer 0.4.5 → 0.4.7

package/dist/cli/props.js

@@ -185,7 +185,86 @@ function readComponentRecord(checker, name, type, declaration, optionRoots, comp
         }
     }
     const inheritedFrom = propsType ? nodeModulesHeritageNames(checker, propsType.isUnion() ? propsType.types : [propsType]) : [];
-    return { name, file: path.relative(process.cwd(), sourceFile.fileName), props, inheritedFrom };
+    const composedOfCandidates = readComposedOfCandidates(checker, declaration);
+    return {
+        name,
+        file: path.relative(process.cwd(), sourceFile.fileName),
+        props,
+        inheritedFrom,
+        ...(composedOfCandidates.length > 0 ? { composedOfCandidates } : {}),
+    };
+}
+/** Optional, additive source evidence (guided-intelligence design §4, plan Task 3): every other
+ *  known, project-local component this component's own implementation renders as a literal JSX
+ *  tag. Scoped to exactly the implementation function's own body (the same function
+ *  `defaultsFromImplementation` already unwraps through `React.memo`/`forwardRef`) — a same-file
+ *  helper's own JSX, or a different export's JSX, is never walked at all, since traversal never
+ *  starts there. Only a JSX tag that is a bare identifier resolving (through import aliases and
+ *  barrel re-exports) to an exported symbol satisfying `isComponentType` becomes a candidate; a
+ *  type-only import can never reach here (it cannot be used as a JSX tag at all), an import that is
+ *  never written as a JSX tag is never visited, and a locally-computed/conditional tag identifier
+ *  (not itself an import alias) is left uncertain rather than guessed at. A `node_modules`
+ *  declaration (a framework primitive, not a project component) is excluded — "known canonical
+ *  component export" means part of this project's own component surface. */
+function readComposedOfCandidates(checker, declaration) {
+    const startNode = ts.isVariableDeclaration(declaration) && declaration.initializer ? declaration.initializer : declaration;
+    const fn = resolveFunctionLike(startNode, new Set());
+    if (!fn?.body)
+        return [];
+    const candidates = [];
+    const visit = (node) => {
+        // A nested named helper (a local `function foo() {}` declaration, or a `const foo = () => {}`/
+        // `function expression` assignment) defines its own scope: its JSX belongs to it, not to this
+        // component, even when this component calls it as an ordinary function — so its body is never
+        // walked at all, matching the top-level sibling-helper behavior this already preserved.
+        if (isNestedNamedHelper(node))
+            return;
+        if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName)) {
+            const candidate = resolveComposedOfCandidate(checker, node.tagName);
+            if (candidate)
+                candidates.push(candidate);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(fn.body);
+    return candidates;
+}
+function isNestedNamedHelper(node) {
+    if (ts.isFunctionDeclaration(node) && node.name)
+        return true;
+    return (ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.initializer !== undefined &&
+        (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer)));
+}
+/** Resolves one JSX tag identifier to a composedOfCandidate, or undefined when it isn't a known,
+ *  project-local component export reached through an import alias (directly or through one or more
+ *  barrel re-exports). */
+function resolveComposedOfCandidate(checker, tagName) {
+    let symbol = checker.getSymbolAtLocation(tagName);
+    if (!symbol)
+        return undefined;
+    // Only a tag identifier that is itself bound to an import (an Alias symbol) counts — a locally
+    // computed/conditional identifier (e.g. `const Comp = cond ? A : B`) is left uncertain even if its
+    // inferred type happens to satisfy `isComponentType`.
+    if (!(symbol.flags & ts.SymbolFlags.Alias))
+        return undefined;
+    const seen = new Set();
+    while (symbol.flags & ts.SymbolFlags.Alias && !seen.has(symbol)) {
+        seen.add(symbol);
+        symbol = checker.getAliasedSymbol(symbol);
+    }
+    const resolvedDeclaration = symbol.valueDeclaration;
+    if (!resolvedDeclaration)
+        return undefined;
+    const declarationFile = resolvedDeclaration.getSourceFile().fileName;
+    if (declarationFile.includes('node_modules'))
+        return undefined;
+    const type = checker.getTypeOfSymbolAtLocation(symbol, resolvedDeclaration);
+    if (!isComponentType(checker, type))
+        return undefined;
+    const { line } = tagName.getSourceFile().getLineAndCharacterOfPosition(tagName.getStart());
+    return { component: symbol.getName(), file: path.relative(process.cwd(), tagName.getSourceFile().fileName), line: line + 1 };
 }
 /** 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

package/dist/cli/staticPage.js

@@ -140,7 +140,7 @@ function readStaticPage(file) {
         else
             page.checkable = false;
     }
-    const variants = readSlotItems(findProp(pageObject, 'variants'), consts);
+    const variants = readSlotItems(findProp(pageObject, 'variants'), consts, page.component, sourceFile);
     if (!variants.checkable)
         page.checkable = false;
     else {
@@ -148,7 +148,7 @@ function readStaticPage(file) {
         page.variantsItemsFill = variants.itemsFill;
         page.variantsMaxColumns = variants.maxColumns;
     }
-    const states = readSlotItems(findProp(pageObject, 'states'), consts);
+    const states = readSlotItems(findProp(pageObject, 'states'), consts, page.component, sourceFile);
     if (!states.checkable)
         page.checkable = false;
     else {
@@ -156,8 +156,42 @@ function readStaticPage(file) {
         page.statesItemsFill = states.itemsFill;
         page.statesMaxColumns = states.maxColumns;
     }
+    const composedOfProp = findProp(pageObject, 'composedOf');
+    page.hasComposedOf = composedOfProp !== undefined;
+    if (composedOfProp)
+        page.composedOf = readComposedOf(composedOfProp.initializer, consts);
+    const intentionalStaticPreviewProp = findProp(pageObject, 'intentionalStaticPreview');
+    if (intentionalStaticPreviewProp) {
+        const resolved = resolve(intentionalStaticPreviewProp.initializer, consts, new Set());
+        if (ts.isObjectLiteralExpression(resolved)) {
+            const reasonProp = findProp(resolved, 'reason');
+            if (reasonProp)
+                page.intentionalStaticPreviewReason = stringLiteral(resolve(reasonProp.initializer, consts, new Set()));
+        }
+    }
     return page;
 }
+/** A literal array of `ComposedOfEntry`-shaped object literals, read down to just `component`
+ *  (design §4: role/relationship are authored prose `doctor` never needs for its missing-
+ *  composition comparison). Undefined — not an empty array — for anything that isn't itself a
+ *  literal array, or whose element isn't an object literal with a literal `component`: `doctor`
+ *  must never mistake "couldn't read this" for "author declared no composition here". */
+function readComposedOf(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const entries = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const component = propertyStringLiteral(resolvedElement, 'component', consts);
+        if (component === undefined)
+            return undefined;
+        entries.push({ component });
+    }
+    return entries;
+}
 /** Local name -> imported name, for every named import from `moduleSpecifier`. */
 function importedNames(sourceFile, moduleSpecifier) {
     const names = new Map();
@@ -219,6 +253,20 @@ function resolve(node, consts, seen) {
 function stringLiteral(node) {
     return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : undefined;
 }
+/** `true`/`false` only from a known `true`/`false` literal; any other expression (a variable, a
+ *  computed value) stays `undefined` rather than being misread as `false`. Unlike the page's own
+ *  `hide.*`/`tokenGallery`/`itemsFill`/`wide` booleans — which intentionally treat "not literally
+ *  `true`" as `false`, since those already default to `false` when omitted — `fill`'s own default
+ *  is inherited (`SpecimenPresentation.fill` defaults to the slot's `itemsFill`, not to `false`),
+ *  so a non-literal value here must stay honestly unknown instead of claiming "not filling". */
+function literalBooleanOrUnknown(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (resolved.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (resolved.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
 function propertyName(name) {
     return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText();
 }
@@ -271,6 +319,34 @@ function readAxis(node, consts) {
     }
     return undefined;
 }
+/** A literal array of `ComparisonCell`-shaped object literals: `rowKey`/`columnKey` required
+ *  (string literals only), `surface`/`align`/`fill` read the same per-field-lenient way
+ *  `readListItems` reads them. `node`/`unavailableReason` are never inspected — design §4 never
+ *  evaluates a cell's specimen node. Undefined (no cell metadata at all, not "every field unset")
+ *  for anything that isn't itself a literal array, or whose element isn't itself an object literal
+ *  with literal `rowKey`/`columnKey` — a `.flatMap()`-built `cells` array (the starter kit's own
+ *  convention for a `grid()`-free literal comparison) stays unrepresented rather than guessed at. */
+function readComparisonCells(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const cells = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const rowKey = propertyStringLiteral(resolvedElement, 'rowKey', consts);
+        const columnKey = propertyStringLiteral(resolvedElement, 'columnKey', consts);
+        if (rowKey === undefined || columnKey === undefined)
+            return undefined;
+        const surface = propertyStringLiteral(resolvedElement, 'surface', consts);
+        const align = propertyStringLiteral(resolvedElement, 'align', consts);
+        const fillProp = findProp(resolvedElement, 'fill');
+        const fill = fillProp ? literalBooleanOrUnknown(fillProp.initializer, consts) : undefined;
+        cells.push({ rowKey, columnKey, surface, align, fill });
+    }
+    return cells;
+}
 /** A page's `comparison` field: either a direct `ComparisonDef`-shaped object literal, or (the
  *  starter kit's own convention since Task 1/2) a call to this package's own `grid()` helper — the
  *  one call shape this reader specially recognizes, reading its `rows`/`columns` arguments and
@@ -305,12 +381,14 @@ function readComparison(node, consts, gridNames) {
         const rowLabelProp = findProp(resolved, 'rowLabel');
         const columnLabelProp = findProp(resolved, 'columnLabel');
         const sizeProp = findProp(resolved, 'size');
+        const cellsProp = findProp(resolved, 'cells');
         return {
             rowLabel: rowLabelProp ? stringLiteral(resolve(rowLabelProp.initializer, consts, new Set())) : undefined,
             columnLabel: columnLabelProp ? stringLiteral(resolve(columnLabelProp.initializer, consts, new Set())) : undefined,
             rows,
             columns,
             size: sizeProp ? stringLiteral(resolve(sizeProp.initializer, consts, new Set())) : undefined,
+            cells: cellsProp ? readComparisonCells(cellsProp.initializer, consts) : undefined,
         };
     }
     return undefined;
@@ -318,7 +396,7 @@ function readComparison(node, consts, gridNames) {
 /** A literal array of list-item object literals — `key`/`name` required; `props` (read as a flat
  *  literal map, non-literal values simply omitted) and `group` optional. Each item's `node` field
  *  (always present, always JSX) is never inspected — reading the sibling fields never depends on it. */
-function readListItems(node, consts) {
+function readListItems(node, consts, componentName, sourceFile) {
     const resolved = resolve(node, consts, new Set());
     if (!ts.isArrayLiteralExpression(resolved))
         return undefined;
@@ -333,10 +411,154 @@ function readListItems(node, consts) {
             return undefined;
         const group = propertyStringLiteral(resolvedElement, 'group', consts);
         const propsProp = findProp(resolvedElement, 'props');
-        items.push({ key, name, group, props: propsProp ? readLiteralProps(propsProp.initializer, consts) : undefined });
+        const fillProp = findProp(resolvedElement, 'fill');
+        const fill = fillProp ? literalBooleanOrUnknown(fillProp.initializer, consts) : undefined;
+        const surface = propertyStringLiteral(resolvedElement, 'surface', consts);
+        const align = propertyStringLiteral(resolvedElement, 'align', consts);
+        const nodeProp = findProp(resolvedElement, 'node');
+        const nodeExample = nodeProp ? readNodeExample(nodeProp.initializer, consts, componentName, sourceFile) : {};
+        items.push({
+            key, name, group, props: propsProp ? readLiteralProps(propsProp.initializer, consts) : undefined, fill, surface, align,
+            ...nodeExample,
+        });
     }
     return items;
 }
+/** Generic, additive reading of one item's own `node:` JSX (design §3, plan Task 3) — used only by
+ *  `cli/doctor.ts`'s interactive-preview advisory. Never evaluates `node`; only reads its literal
+ *  AST shape. `node` matching `componentName` by plain tag-name text (not module resolution — this
+ *  reader never resolves imports) means "a direct instance of the documented component": its own
+ *  JSX attributes are read generically (`nodeAttributes`). Any other JSX tag is checked only for
+ *  whether it's a confidently-identified, genuinely stateful same-file wrapper
+ *  (`nodeStatefulWrapper`) — never asserted one way or the other when that can't be confirmed.
+ *  Anything that isn't a direct JSX element at all (`null`, a conditional, a function call, …)
+ *  leaves every field unset. */
+function readNodeExample(node, consts, componentName, sourceFile) {
+    const resolved = resolve(node, consts, new Set());
+    let element;
+    if (ts.isJsxSelfClosingElement(resolved))
+        element = resolved;
+    else if (ts.isJsxElement(resolved))
+        element = resolved.openingElement;
+    if (!element || !ts.isIdentifier(element.tagName))
+        return {};
+    const tagText = element.tagName.text;
+    if (componentName !== undefined && tagText === componentName) {
+        const nodeAttributes = {};
+        for (const attribute of element.attributes.properties) {
+            // Skips a spread attribute ({...rest}) and a namespaced name (xml:lang) — unreadable,
+            // never a reason to reject the whole item.
+            if (!ts.isJsxAttribute(attribute) || !ts.isIdentifier(attribute.name))
+                continue;
+            nodeAttributes[attribute.name.text] = readJsxAttributeValue(attribute, consts);
+        }
+        return { nodeDirectComponent: tagText, nodeAttributes };
+    }
+    return { nodeStatefulWrapper: sameFileWrapperHasUseState(sourceFile, tagText) ? true : undefined };
+}
+/** One JSX attribute's value, as a `StaticAttributeValue`. A shorthand attribute (`disabled`, no
+ *  `initializer` at all — equivalent to `disabled={true}`) is a literal `true`. */
+function readJsxAttributeValue(attribute, consts) {
+    if (!attribute.initializer)
+        return { kind: 'literal', value: true };
+    if (ts.isStringLiteral(attribute.initializer))
+        return { kind: 'literal', value: attribute.initializer.text };
+    if (!ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression)
+        return { kind: 'unknown' };
+    const resolved = resolve(attribute.initializer.expression, consts, new Set());
+    if (ts.isStringLiteral(resolved) || ts.isNoSubstitutionTemplateLiteral(resolved))
+        return { kind: 'literal', value: resolved.text };
+    if (ts.isNumericLiteral(resolved))
+        return { kind: 'literal', value: Number(resolved.text) };
+    if (resolved.kind === ts.SyntaxKind.TrueKeyword)
+        return { kind: 'literal', value: true };
+    if (resolved.kind === ts.SyntaxKind.FalseKeyword)
+        return { kind: 'literal', value: false };
+    if (ts.isIdentifier(resolved) && resolved.text === 'undefined')
+        return { kind: 'no-op-callback' };
+    if ((ts.isArrowFunction(resolved) || ts.isFunctionExpression(resolved)) && isEmptyFunctionBody(resolved.body)) {
+        return { kind: 'no-op-callback' };
+    }
+    return { kind: 'unknown' };
+}
+function isEmptyFunctionBody(body) {
+    return ts.isBlock(body) && body.statements.length === 0;
+}
+/** True only when `sourceFile` declares a top-level function (declaration, or a `const`/`let`
+ *  initialized with a function/arrow expression) named `tagName` whose own body contains a call to
+ *  a *source-backed* React `useState`/`React.useState` — a confidently-identified, genuinely
+ *  stateful wrapper. Walking only that one function's own body (never the whole file) keeps this
+ *  scoped the same way `cli/props.ts`'s composedOfCandidate reader scopes its own JSX walk to one
+ *  implementation. */
+function sameFileWrapperHasUseState(sourceFile, tagName) {
+    const bindings = reactUseStateBindings(sourceFile);
+    for (const statement of sourceFile.statements) {
+        let body;
+        if (ts.isFunctionDeclaration(statement) && statement.name?.text === tagName)
+            body = statement.body;
+        else if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name) && declaration.name.text === tagName && declaration.initializer &&
+                    (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) {
+                    body = declaration.initializer.body;
+                }
+            }
+        }
+        if (body && containsUseStateCall(body, bindings))
+            return true;
+    }
+    return false;
+}
+/** This file's own top-level `import ... from 'react'` bindings relevant to recognizing a genuine
+ *  `useState` call — never a type-checker resolution, only the same-file import syntax, matching
+ *  this reader's existing "never resolves imports across files" contract. `namedUseState` holds
+ *  every local name bound to the real named `useState` export (an alias, e.g. `import { useState as
+ *  useReactState }`, included); `reactNamespace` holds every local name bound to the whole `react`
+ *  module (a default or `* as` import) that a `React.useState(...)` call could be written through.
+ *  A locally-defined `useState` (no matching import) or an unrelated object's own `.useState` method
+ *  binds to neither set and so is never counted — left uncheckable, never asserted stateful. */
+function reactUseStateBindings(sourceFile) {
+    const namedUseState = new Set();
+    const reactNamespace = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== 'react')
+            continue;
+        const clause = statement.importClause;
+        if (!clause)
+            continue;
+        if (clause.name)
+            reactNamespace.add(clause.name.text);
+        if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings))
+            reactNamespace.add(clause.namedBindings.name.text);
+        else if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+            for (const element of clause.namedBindings.elements) {
+                if ((element.propertyName ?? element.name).text === 'useState')
+                    namedUseState.add(element.name.text);
+            }
+        }
+    }
+    return { namedUseState, reactNamespace };
+}
+function containsUseStateCall(node, bindings) {
+    let found = false;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (ts.isCallExpression(n)) {
+            const callee = n.expression;
+            const isNamedUseState = ts.isIdentifier(callee) && bindings.namedUseState.has(callee.text);
+            const isReactNamespaceUseState = ts.isPropertyAccessExpression(callee) && callee.name.text === 'useState' &&
+                ts.isIdentifier(callee.expression) && bindings.reactNamespace.has(callee.expression.text);
+            if (isNamedUseState || isReactNamespaceUseState) {
+                found = true;
+                return;
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(node);
+    return found;
+}
 function readLiteralProps(node, consts) {
     const resolved = resolve(node, consts, new Set());
     if (!ts.isObjectLiteralExpression(resolved))
@@ -365,14 +587,14 @@ function readLiteralProps(node, consts) {
  *  literal — like `previewWidths`/`fullWidthLabel`, it isn't in the original literal-checkable
  *  list, so a non-literal `itemsFill` is simply left unset. `maxColumns` does affect the geometry
  *  `explain` reports, so it must be a literal integer from 1–5 or the page is not checkable. */
-function readSlotItems(prop, consts) {
+function readSlotItems(prop, consts, componentName, sourceFile) {
     if (!prop)
         return { checkable: true };
     const resolved = resolve(prop.initializer, consts, new Set());
     const itemsProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'items') : undefined;
     if (!itemsProp)
         return { checkable: false };
-    const items = readListItems(itemsProp.initializer, consts);
+    const items = readListItems(itemsProp.initializer, consts, componentName, sourceFile);
     if (!items)
         return { checkable: false };
     const itemsFillProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'itemsFill') : undefined;

package/dist/cli/updateCheck.js

@@ -1,5 +1,5 @@
 // cli/updateCheck.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { compareVersions, isBreakingUpgrade, parseVersion } from "./semver.js";
 const CACHE_FILE_NAME = 'update-check.json';
@@ -79,59 +79,163 @@ export async function fetchWithTimeout(url, fetchImpl, timeoutMs) {
         clearTimeout(timer);
     }
 }
+/** One update check, with whether npm actually answered — `checkForUpdate` alone can't tell "no
+ *  newer version" from "couldn't reach npm", which the update page must say differently. Never
+ *  throws. `cached` is the cache as it stands afterwards (the last successful check on this
+ *  computer), when there is one. */
+export async function runUpdateCheck(currentVersion, options = {}) {
+    const now = options.now ?? Date.now;
+    const cacheDir = options.cacheDir ?? cacheDirFor(process.platform, process.env, process.env.HOME ?? process.env.USERPROFILE ?? '');
+    const cached = readCache(cacheDir);
+    // `parseVersion` (inside `toResultOrUndefined`) throws on a non-semver `latest`, whether from a
+    // malformed cache file or an unexpected registry body; this function must never throw.
+    const safeResult = (entry) => {
+        try {
+            return toResultOrUndefined(entry, currentVersion);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    if (cached && !options.force && isCacheFresh(cached, now()))
+        return { result: safeResult(cached), reached: true, cached };
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 900;
+    let latest;
+    try {
+        const registryResponse = (await fetchWithTimeout(REGISTRY_URL, fetchImpl, timeoutMs));
+        latest = registryResponse.version;
+        parseVersion(latest);
+    }
+    catch {
+        // A stale cache is still better than nothing once offline — still run through the same
+        // not-actually-newer guard, never a raw passthrough.
+        return { result: cached ? safeResult(cached) : undefined, reached: false, cached };
+    }
+    let summary = [];
+    let releasedAt;
+    try {
+        const release = (await fetchWithTimeout(`https://api.github.com/repos/${GITHUB_REPO}/releases/tags/v${latest}`, fetchImpl, timeoutMs));
+        summary = release.body ? extractSummaryBullets(release.body) : [];
+        releasedAt = release.published_at;
+    }
+    catch {
+        // The version comparison is the half that matters for the footer/banner; a missing release
+        // summary (private repo hiccup, a tag pushed slightly before its release note) degrades to an
+        // empty "What's new" list, never a failed check.
+    }
+    const fresh = { latest, summary, releasedAt, checkedAt: new Date(now()).toISOString() };
+    // A registry that (briefly, during its own propagation) reports an older "latest" than what is
+    // already cached never regresses the cache's version, but the check time still moves forward.
+    let stored = fresh;
+    try {
+        if (cached && compareVersions(parseVersion(fresh.latest), parseVersion(cached.latest)) < 0)
+            stored = { ...cached, checkedAt: fresh.checkedAt };
+    }
+    catch {
+        // An unreadable cached version is simply replaced.
+    }
+    try {
+        writeCache(cacheDir, stored);
+    }
+    catch {
+        // A read-only cache folder must not turn a successful check into a failure.
+    }
+    return { result: safeResult(fresh), reached: true, cached: stored };
+}
 /** Design §5 "Update check" in full. Never throws — every failure (a stale/missing cache with no
  *  reachable registry, a GitHub release that 404s, a request that times out) resolves to either a
  *  usable result or `undefined`, so every caller can treat "no update known" as the one, uniform
  *  outcome of being offline, blocked, or genuinely up to date with nothing cached yet. */
 export async function checkForUpdate(currentVersion, options = {}) {
-    // M5 (Minor, Fable correction pass): this function is documented — and relied on by `dev()`,
-    // which `await`s it before starting anything else — as never throwing. `parseVersion` (inside
-    // `toResultOrUndefined`) throws on a non-semver `latest`, whether from a parseable-but-malformed
-    // cache file or an unexpected 200 body with no real `version`; either would otherwise stop `dev`
-    // from starting at all.
     try {
-        const now = options.now ?? Date.now;
-        const cacheDir = options.cacheDir ?? cacheDirFor(process.platform, process.env, process.env.HOME ?? process.env.USERPROFILE ?? '');
-        const cached = readCache(cacheDir);
-        if (cached && isCacheFresh(cached, now()))
-            return toResultOrUndefined(cached, currentVersion);
-        const fetchImpl = options.fetchImpl ?? fetch;
-        const timeoutMs = options.timeoutMs ?? 900;
-        let latest;
-        try {
-            const registryResponse = (await fetchWithTimeout(REGISTRY_URL, fetchImpl, timeoutMs));
-            latest = registryResponse.version;
-        }
-        catch {
-            // A stale cache is still better than nothing once offline — still run through the same
-            // not-actually-newer guard, never a raw passthrough.
-            return cached ? toResultOrUndefined(cached, currentVersion) : undefined;
-        }
-        let summary = [];
-        let releasedAt;
-        try {
-            const release = (await fetchWithTimeout(`https://api.github.com/repos/${GITHUB_REPO}/releases/tags/v${latest}`, fetchImpl, timeoutMs));
-            summary = release.body ? extractSummaryBullets(release.body) : [];
-            releasedAt = release.published_at;
-        }
-        catch {
-            // The version comparison is the half that matters for the footer/banner; a missing release
-            // summary (private repo hiccup, a tag pushed slightly before its release note) degrades to an
-            // empty "What's new" list, never a failed check.
-        }
-        const cachedResult = { latest, summary, releasedAt, checkedAt: new Date(now()).toISOString() };
-        // compareVersions is used only to decide *whether* this is worth caching as "the latest" at all
-        // — a registry that (briefly, during its own propagation) reports an older "latest" than what
-        // is already cached never regresses the cache.
-        if (!cached || compareVersions(parseVersion(cachedResult.latest), parseVersion(cached.latest)) >= 0) {
-            writeCache(cacheDir, cachedResult);
-        }
-        return toResultOrUndefined(cachedResult, currentVersion);
+        return (await runUpdateCheck(currentVersion, options)).result;
     }
     catch {
         return undefined;
     }
 }
+/** A settings folder, not the cache folder (which the OS may clear): the personal switch must
+ *  survive. */
+export function preferencesDirFor(platform, env, homedir) {
+    if (platform === 'darwin')
+        return path.posix.join(homedir, 'Library', 'Application Support', 'ds-viewer');
+    if (platform === 'win32')
+        return path.win32.join(env.APPDATA ?? path.win32.join(homedir, 'AppData', 'Roaming'), 'ds-viewer');
+    return path.posix.join(env.XDG_CONFIG_HOME ?? path.posix.join(homedir, '.config'), 'ds-viewer');
+}
+export function defaultPreferencesDir() {
+    return preferencesDirFor(process.platform, process.env, process.env.HOME ?? process.env.USERPROFILE ?? '');
+}
+const PREFERENCES_FILE_NAME = 'preferences.json';
+function readPreferences(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(path.join(dir, PREFERENCES_FILE_NAME), 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Your own "check automatically" switch for one project on this computer, or `undefined` when you
+ *  haven't set it (the project config then decides). */
+export function readPersonalAutoCheck(dir, projectRoot) {
+    const value = readPreferences(dir).projects?.[path.resolve(projectRoot)]?.autoCheck;
+    return typeof value === 'boolean' ? value : undefined;
+}
+export function writePersonalAutoCheck(dir, projectRoot, enabled) {
+    const prefs = readPreferences(dir);
+    const projects = { ...(prefs.projects ?? {}) };
+    projects[path.resolve(projectRoot)] = { ...projects[path.resolve(projectRoot)], autoCheck: enabled };
+    mkdirSync(dir, { recursive: true });
+    // Write then rename, so a crash mid-write never leaves a half file that would read as "no
+    // settings" and silently reset every project's switch.
+    const target = path.join(dir, PREFERENCES_FILE_NAME);
+    const temp = `${target}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ ...prefs, projects }, null, 2)}\n`);
+    renameSync(temp, target);
+}
+/** Which setting decides automatic checks, strongest first: CI's environment variable, your own
+ *  switch, the project config, then on by default. */
+export function resolveAutoCheck(config, env, personal) {
+    if (env.DS_VIEWER_NO_UPDATE_CHECK === '1')
+        return { enabled: false, source: 'env' };
+    if (personal !== undefined)
+        return { enabled: personal, source: 'personal' };
+    if (config.updateCheck !== undefined)
+        return { enabled: config.updateCheck, source: 'project' };
+    return { enabled: true, source: 'default' };
+}
+function toNotice(result) {
+    if (!result)
+        return null;
+    return { current: result.current, latest: result.latest, breaking: result.breaking, summary: result.summary, releasedAt: result.releasedAt };
+}
+/** The version status `dev` starts with: runs the (cached) check only when automatic checks are on. */
+export async function buildVersionStatus(currentVersion, autoCheck, options = {}) {
+    if (!autoCheck.enabled) {
+        const cacheDir = options.cacheDir ?? cacheDirFor(process.platform, process.env, process.env.HOME ?? process.env.USERPROFILE ?? '');
+        return { current: currentVersion, autoCheck, lastCheckedAt: readCache(cacheDir)?.checkedAt, lastOutcome: 'not-run', update: null };
+    }
+    return statusFromCheck(currentVersion, autoCheck, await runUpdateCheck(currentVersion, options));
+}
+/** Folds one check's outcome into a status (startup, or **Check now**). */
+export function statusFromCheck(currentVersion, autoCheck, outcome) {
+    return {
+        current: currentVersion,
+        autoCheck,
+        lastCheckedAt: outcome.cached?.checkedAt,
+        lastOutcome: outcome.reached ? 'ok' : 'unreachable',
+        update: toNotice(outcome.result),
+    };
+}
+/** `dev` writes this next to `update.json`; the generated entry file imports it. */
+export function writeVersionFile(projectRoot, status) {
+    const file = path.join(projectRoot, '.ds-viewer', 'version.json');
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(status));
+    return file;
+}
 /** Design §5: "`dev` writes the result to `.ds-viewer/update.json`; the viewer reads it." Always
  *  writes something — `null` when there is no result — so the generated entry file (Task 17) can
  *  unconditionally `import updateNotice from './update.json'` without ever hitting a missing file. */
@@ -141,3 +245,30 @@ export function writeUpdateFile(projectRoot, result) {
     writeFileSync(file, JSON.stringify(result ?? null));
     return file;
 }
+/** The live version status behind the local endpoint (`GET /version`, **Check now**, the switch),
+ *  kept outside `dev()` so its ordering rules are testable. */
+export function createVersionController(deps) {
+    let status = deps.initial;
+    const resolveNow = () => resolveAutoCheck(deps.getConfig(), deps.env, readPersonalAutoCheck(deps.prefsDir, deps.projectRoot));
+    return {
+        getVersionStatus: () => status,
+        /** **Check now**: asks npm ignoring the cache. Reads the switch *after* the check, so a change
+         *  made while it ran is kept. */
+        checkNow: async () => {
+            const outcome = await deps.runCheck();
+            status = statusFromCheck(deps.ownVersion, status.autoCheck, outcome);
+            return status;
+        },
+        /** The switch: your own setting for this project on this computer. Takes effect for automatic
+         *  checks from the next start; the current status keeps any update already found. */
+        setAutoCheck: (enabled) => {
+            writePersonalAutoCheck(deps.prefsDir, deps.projectRoot, enabled);
+            status = { ...status, autoCheck: resolveNow() };
+            return status;
+        },
+        /** After `ds-viewer.config.ts` changes while `dev` runs. */
+        refreshAutoCheck: () => {
+            status = { ...status, autoCheck: resolveNow() };
+        },
+    };
+}

package/dist/cli/workspace.js

@@ -65,13 +65,14 @@ function entryTsx(name, hasSafeArea, groupOrder, logoRequirePath, updateEndpoint
     // (no reserved words in either key) — the same reasoning the existing `logoRequirePath` baking
     // already relies on, extended to a whole object instead of one string.
     const endpointConst = `const updateEndpoint = ${updateEndpoint ? JSON.stringify(updateEndpoint) : 'undefined'};\n`;
-    const viewer = `<CatalogShell appName={${JSON.stringify(name)}} title="Component Catalog" groups={groups} sections={sections}${logoProp} update={updateNotice} updateEndpoint={updateEndpoint} />`;
+    const viewer = `<CatalogShell appName={${JSON.stringify(name)}} title="Component Catalog" groups={groups} sections={sections}${logoProp} update={updateNotice} versionStatus={versionStatus} updateEndpoint={updateEndpoint} />`;
     const root = hasSafeArea ? `<SafeAreaProvider>${viewer}</SafeAreaProvider>` : viewer;
     return `import { registerRootComponent } from 'expo';
 import { CatalogShell, buildCatalogSections } from '@krapwoo/ds-viewer';
 ${safeAreaImport}${logoImport}import pages from './generated/pages';
 import components from './generated/components.json';
 import updateNotice from './update.json';
+import versionStatus from './version.json';
 ${endpointConst}
 function App() {
   const { sections, groups } = buildCatalogSections(pages, components, ${JSON.stringify(groupOrder)});