@krapwoo/ds-viewer 0.4.4 → 0.4.6

package/README.md

@@ -190,13 +190,15 @@ actually apply:
   within what fits a 1280px laptop: 5 compact, 3 regular, or 2 wide columns. `states` items whose
   key matches a row or column key are not repeated below the grid.
 - `specimenSize: 'compact' | 'regular' | 'wide'` — the page's specimen width class.
-- `specimenSurface: 'neutral' | 'white' | 'dark' | 'transparent'` — the catalog-owned background
-  behind every live specimen on this page (list/grouped/grid cells, and a non-token `render()`
-  preview). Defaults to `'neutral'` (a light gray stage, visibly distinct from the surrounding
-  white card) — reach for `'dark'` to check a low-contrast component against a dark background, or
-  `'transparent'` when the surface itself would be misleading (e.g. a component whose own
-  elevation/shadow needs to read against the page, not a chip). Token galleries and sections always
-  keep their current, unstaged presentation regardless of this setting.
+- `specimenSurface: 'auto' | 'neutral' | 'white' | 'dark' | 'transparent'` — the fill of each
+  example's cell (list, grouped and grid cells, and a non-token `render()` preview). Defaults to
+  `'auto'`: after the page draws, a cell turns light gray only when its own example would vanish
+  against white (its largest coloured box is near-white with no visible border, like a white card,
+  sheet or neutral banner; a shadow alone doesn't count). Neighbouring examples keep a white cell,
+  and most pages need nothing. Override it when the guess is wrong: `'neutral'` makes every example
+  cell gray, `'white'` or `'transparent'` keeps them all white, and `'dark'` checks a light
+  component on a dark fill. Detection runs in the browser viewer; elsewhere cells stay white.
+  Token galleries and sections are never filled.
 - `variants`/`states`' own `maxColumns: 1 | 2 | 3 | 4 | 5` — caps how many columns that slot's list
   ever wraps into (e.g. a 3-item size scale that should always read as one row of exactly 3, never
   more just because a laptop is wide). A narrow window still drops below the cap when it has to —
@@ -398,9 +400,17 @@ markers or its own file.
 
 ## Updating
 
-A quiet line appears in the sidebar footer when a new version is published — a banner too, for a
-major version, dismissible per version. Either opens the update page (`#ds-viewer-update`), which
-shows what would change and one **Update now** button:
+The sidebar footer always shows the installed version ("DS Viewer 0.4.5") and opens the update
+page (`#ds-viewer-update`). With no newer version known, that page says which situation you're in —
+on the latest version, automatic checks off, or npm unreachable — and offers **Check now** (asks npm
+right away, even with automatic checks off) and a **Check for updates automatically** switch. The
+switch saves your own choice for this project on this computer (in your user settings folder, not in
+the project), overriding the project's `updateCheck` for you only; `DS_VIEWER_NO_UPDATE_CHECK=1`
+(CI) still wins over both. `doctor` follows the same setting.
+
+When a new version is published, the footer turns into "Update available · 0.5.0" — a banner too,
+for a major version, dismissible per version. Either opens the same page, which then shows what would
+change and one **Update now** button:
 
 ```
 0.4.0 → 0.5.0  Minor

package/dist/cli/dev.js

@@ -9,7 +9,7 @@ import { sync } from "./sync.js";
 import { writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
-import { checkForUpdate, isUpdateCheckEnabled, writeUpdateFile } from "./updateCheck.js";
+import { buildVersionStatus, createVersionController, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck, runUpdateCheck, statusFromCheck, writeUpdateFile, writeVersionFile, } from "./updateCheck.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { createUpdateEndpoint } from "./endpoint.js";
 import { buildUpdatePlan } from "./updatePlan.js";
@@ -70,10 +70,20 @@ export function reloadWorkspace(projectRoot, updateEndpoint) {
  *  the same way `reloadWorkspace` already is, so this plan never needs to test `dev()` itself
  *  (which spawns a real Expo process) to prove this one behavior. */
 export async function refreshUpdateFile(config, ownVersion, options = {}) {
-    const result = isUpdateCheckEnabled(config, options.env ?? process.env)
-        ? await (options.checkForUpdate ?? checkForUpdate)(ownVersion)
-        : undefined;
-    writeUpdateFile(config.projectRoot, result);
+    const env = options.env ?? process.env;
+    const personal = readPersonalAutoCheck(options.prefsDir ?? defaultPreferencesDir(), config.projectRoot);
+    const autoCheck = resolveAutoCheck(config, env, personal);
+    // An injected `checkForUpdate` (tests) stands in for the real check; it can't report "couldn't
+    // reach npm", so it always counts as answered.
+    const injected = options.checkForUpdate;
+    const status = injected
+        ? autoCheck.enabled
+            ? statusFromCheck(ownVersion, autoCheck, { result: await injected(ownVersion), reached: true })
+            : { current: ownVersion, autoCheck, lastOutcome: 'not-run', update: null }
+        : await buildVersionStatus(ownVersion, autoCheck);
+    writeUpdateFile(config.projectRoot, status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined);
+    writeVersionFile(config.projectRoot, status);
+    return status;
 }
 // Promisified, not `execFileSync` — install/migrate/doctor each take real seconds, and this now
 // runs from inside the endpoint's own request-handling process, which must keep answering
@@ -284,8 +294,19 @@ export async function performRestart(handoff, deps = {}) {
 export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
     const ownVersion = readOwnVersion(import.meta.dirname);
-    await refreshUpdateFile(initialConfig, ownVersion);
     let config = initialConfig;
+    const version = createVersionController({
+        ownVersion,
+        projectRoot: initialConfig.projectRoot,
+        prefsDir: defaultPreferencesDir(),
+        env: process.env,
+        initial: await refreshUpdateFile(initialConfig, ownVersion),
+        getConfig: () => config,
+        // **Check now** always asks npm, even with automatic checks off: you asked for this one check.
+        // The result lives only in this process; `update.json` and `version.json` are rewritten at
+        // the next start (rewriting them now would reload the page).
+        runCheck: () => runUpdateCheck(ownVersion, { force: true, timeoutMs: 5000 }),
+    });
     sync(config);
     // Restart handoff step 2/4: a status file left by the *previous* `dev` process (right before it
     // exited to restart) is read once, then deleted — a plain refresh afterward shows "idle"/"no
@@ -336,6 +357,9 @@ export async function dev(initialConfig, devOptions = {}) {
             });
         },
         getStatus: () => updateStatus,
+        getVersionStatus: version.getVersionStatus,
+        checkNow: version.checkNow,
+        setAutoCheck: version.setAutoCheck,
     };
     const endpointServer = createUpdateEndpoint(endpointDeps);
     await new Promise((resolve) => endpointServer.listen(0, '127.0.0.1', resolve));
@@ -374,6 +398,7 @@ export async function dev(initialConfig, devOptions = {}) {
         configDebounceTimer = setTimeout(() => {
             try {
                 config = reloadWorkspace(config.projectRoot, updateEndpoint);
+                version.refreshAutoCheck();
             }
             catch (error) {
                 console.warn(`Could not reload ds-viewer.config.ts after a change: ${error.message}`);

package/dist/cli/endpoint.js

@@ -14,6 +14,38 @@ function secretMatches(received, expected) {
     const expectedBuf = Buffer.from(expected);
     return receivedBuf.length === expectedBuf.length && timingSafeEqual(receivedBuf, expectedBuf);
 }
+/** Reads a small JSON request body (the switch's `{ enabled }`); anything over 1 KB is refused. */
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        let tooLarge = false;
+        req.setEncoding('utf8');
+        // Keep draining past the cap (without storing it) so the handler can still answer 400 —
+        // destroying the socket would drop that answer.
+        req.on('data', (chunk) => {
+            if (tooLarge)
+                return;
+            body += chunk;
+            if (body.length > 1024) {
+                tooLarge = true;
+                body = '';
+            }
+        });
+        req.on('end', () => {
+            if (tooLarge) {
+                reject(new Error('Body too large.'));
+                return;
+            }
+            try {
+                resolve(JSON.parse(body || 'null'));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        req.on('error', reject);
+    });
+}
 function sendJson(res, status, body, allowedOrigin) {
     res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': allowedOrigin });
     res.end(JSON.stringify(body));
@@ -33,6 +65,7 @@ export function createUpdateEndpoint(deps) {
     // every real caller), so resetting this flag right after is safe and lets a later retry (after a
     // `'failure'`, in the same process) through again.
     let starting = false;
+    let checking = false;
     return http.createServer(async (req, res) => {
         // Controller decision 1 (required, not optional): reject a request whose `Host` header is not
         // this very socket's own `127.0.0.1:<port>` — a DNS-rebinding defence, since `req.socket`'s own
@@ -55,7 +88,7 @@ export function createUpdateEndpoint(deps) {
             res.writeHead(204, {
                 'Access-Control-Allow-Origin': deps.allowedOrigin,
                 'Access-Control-Allow-Methods': 'POST, GET',
-                'Access-Control-Allow-Headers': DS_VIEWER_SECRET_HEADER,
+                'Access-Control-Allow-Headers': `${DS_VIEWER_SECRET_HEADER}, Content-Type`,
             });
             res.end();
             return;
@@ -137,6 +170,48 @@ export function createUpdateEndpoint(deps) {
             sendJson(res, 200, deps.getStatus(), deps.allowedOrigin);
             return;
         }
+        if (req.method === 'GET' && req.url === '/version' && deps.getVersionStatus) {
+            sendJson(res, 200, deps.getVersionStatus(), deps.allowedOrigin);
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/version/check' && deps.checkNow) {
+            if (checking) {
+                sendJson(res, 409, { error: 'A check is already running.' }, deps.allowedOrigin);
+                return;
+            }
+            checking = true;
+            try {
+                sendJson(res, 200, await deps.checkNow(), deps.allowedOrigin);
+            }
+            catch (error) {
+                sendJson(res, 502, { error: error.message }, deps.allowedOrigin);
+            }
+            finally {
+                checking = false;
+            }
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/version/auto-check' && deps.setAutoCheck) {
+            let body;
+            try {
+                body = await readJsonBody(req);
+            }
+            catch {
+                body = undefined;
+            }
+            const enabled = body?.enabled;
+            if (typeof enabled !== 'boolean') {
+                sendJson(res, 400, { error: 'Expected { "enabled": true | false }.' }, deps.allowedOrigin);
+                return;
+            }
+            try {
+                sendJson(res, 200, deps.setAutoCheck(enabled), deps.allowedOrigin);
+            }
+            catch (error) {
+                sendJson(res, 500, { error: error.message }, deps.allowedOrigin);
+            }
+            return;
+        }
         res.writeHead(404).end('Not found.');
     });
 }

package/dist/cli/main.js

@@ -8,7 +8,7 @@ import { sync } from "./sync.js";
 import { formatHuman, runDoctor, toDoctorJson } from "./doctor.js";
 import { explainPage, formatExplain, parseHeights } from "./explain.js";
 import { readOwnVersion } from "./packageVersion.js";
-import { checkForUpdate, isUpdateCheckEnabled } from "./updateCheck.js";
+import { checkForUpdate, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck } from "./updateCheck.js";
 import { runKitDiffCommand } from "./kitDiff.js";
 import { formatMigrateHuman, runMigrate } from "./migrate.js";
 import { runUpdate } from "./update.js";
@@ -119,7 +119,9 @@ export async function runDoctorCommand(projectRoot, rest, options = {}) {
     const result = runDoctor(config);
     // Design §4 "`--ci`: ... no update check." — `--ci` skips this whole block even when
     // `updateCheck` is otherwise enabled; `result.update` stays `null`.
-    if (!rest.includes('--ci') && isUpdateCheckEnabled(config, options.env ?? process.env)) {
+    // Same precedence as the viewer: CI's environment variable, your own switch, the project config.
+    const autoCheck = resolveAutoCheck(config, options.env ?? process.env, readPersonalAutoCheck(options.prefsDir ?? defaultPreferencesDir(), config.projectRoot));
+    if (!rest.includes('--ci') && autoCheck.enabled) {
         const ownVersion = readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
         const updateResult = await (options.checkForUpdate ?? checkForUpdate)(ownVersion);
         if (updateResult) {

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)});

package/dist/native/catalog/catalogNavigation.js

@@ -129,3 +129,14 @@ export function footerLabel(update) {
         return undefined;
     return `Update available · ${update.latest}`;
 }
+/** The sidebar's footer line: the blue "Update available" notice when a newer version is known
+ *  (from startup or **Check now**), else the installed version, quietly. `undefined` only for a
+ *  workspace generated before version status existed, which keeps the old notice-only footer. */
+export function footerLink(update, status) {
+    const notice = footerLabel(update) ?? footerLabel(status?.update);
+    if (notice)
+        return { label: notice, kind: 'update' };
+    if (status)
+        return { label: `DS Viewer ${status.current}`, kind: 'version' };
+    return undefined;
+}

package/dist/native/catalog/tokens.js

@@ -111,6 +111,8 @@ export const CATALOG_COLOR = {
     surfaceMuted: '#fafafa',
     /** Hover and pressed feedback on nav rows and buttons. */
     surfacePressed: '#f1f3f8',
+    /** An example's cell when the example itself is white (`specimenSurface`), darker than surfaceMuted so a white card's edges show. */
+    specimenStage: '#f2f2f2',
     pageBackground: '#f6f6f4',
     chip: '#eeeeee',
     /** Active nav label, prop types, scale bars. */

package/native/catalog/CatalogShell.tsx

@@ -5,8 +5,8 @@ import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_RADIU
 import { CatalogSidebar } from './CatalogSidebar';
 import { SectionBlock } from './SectionBlock';
 import { UpdatePanel } from './UpdatePanel';
-import { groupLabelFor, hashForId, neighbors, orderedIds, resolveActiveFromHash, shouldShowMajorBanner, footerLabel, UPDATE_PAGE_ID } from './catalogNavigation';
-import type { NavGroup, PreviewWidths, SectionDef, UpdateNotice } from './types';
+import { DS_VIEWER_SECRET_HEADER, footerLink, groupLabelFor, hashForId, neighbors, orderedIds, resolveActiveFromHash, shouldShowMajorBanner, UPDATE_PAGE_ID } from './catalogNavigation';
+import type { NavGroup, PreviewWidths, SectionDef, UpdateNotice, VersionStatus } from './types';
 
 /** `active` can be a real page id, or the reserved update-page id — never both a generic `TId`
  *  constraint and a hardcoded string literal type at once, which is why this is its own alias. */
@@ -111,6 +111,7 @@ export function CatalogShell<TId extends string>({
   sections,
   defaultPreviewWidths,
   update,
+  versionStatus,
   updateEndpoint,
 }: {
   /** Short product/app name — the sidebar logo and the breadcrumb root. */
@@ -129,6 +130,12 @@ export function CatalogShell<TId extends string>({
    *  or already up to date; the viewer treats all three identically: no footer, no banner, no
    *  update page content). */
   update?: UpdateNotice | null;
+  /** The installed version, whether automatic checks are on (and why), and the last check —
+   *  `dev` writes it at startup (`.ds-viewer/version.json`), and the shell refreshes it from the
+   *  local endpoint. With it, the sidebar always shows a version line and the update page offers
+   *  **Check now** and the automatic-check switch. Without it (an older generated workspace), the
+   *  footer appears only when an update is known, as before. */
+  versionStatus?: VersionStatus | null;
   /** The local endpoint's base URL and per-run secret — `dev` generates both (Task 18) and
    *  `writeWorkspace`'s generated entry file bakes them in (Task 17). Absent in a build that
    *  disables the endpoint entirely — `UpdatePanel` degrades to showing the plan/notice with no
@@ -198,28 +205,56 @@ export function CatalogShell<TId extends string>({
 
   const activeDef = active !== undefined && active !== UPDATE_PAGE_ID ? sectionsById.get(active) : undefined;
 
+  // The live version status: starts from what `dev` wrote at startup, then follows the local
+  // endpoint (a reload after **Check now** must not fall back to the startup snapshot).
+  const [liveStatus, setLiveStatus] = useState<VersionStatus | null>(versionStatus ?? null);
+  useEffect(() => {
+    if (!updateEndpoint || !isWeb()) return;
+    let cancelled = false;
+    fetch(`${updateEndpoint.baseUrl}/version`, { headers: { [DS_VIEWER_SECRET_HEADER]: updateEndpoint.secret } })
+      .then((res) => (res.ok ? (res.json() as Promise<VersionStatus>) : undefined))
+      .then((next) => {
+        if (next && !cancelled) setLiveStatus(next);
+      })
+      .catch(() => {
+        // The startup snapshot stays; the endpoint may be restarting.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [updateEndpoint]);
+  // With a live status, it is the truth (it includes a **Check now** result); otherwise the
+  // startup notice, as before.
+  const effectiveUpdate: UpdateNotice | null = liveStatus ? liveStatus.update : update ?? null;
+
   const [dismissedMajor, setDismissedMajor] = useState<string | null>(() =>
     isWeb() ? window.localStorage.getItem('ds-viewer-dismissed-major') : null,
   );
   const dismissMajorBanner = useCallback(() => {
-    if (!update) return;
-    if (isWeb()) window.localStorage.setItem('ds-viewer-dismissed-major', update.latest);
-    setDismissedMajor(update.latest);
-  }, [update]);
-  const footer = footerLabel(update)
-    ? { label: footerLabel(update)!, active: active === UPDATE_PAGE_ID, onPress: () => select(UPDATE_PAGE_ID) }
-    : undefined;
+    if (!effectiveUpdate) return;
+    if (isWeb()) window.localStorage.setItem('ds-viewer-dismissed-major', effectiveUpdate.latest);
+    setDismissedMajor(effectiveUpdate.latest);
+  }, [effectiveUpdate]);
+  const link = footerLink(effectiveUpdate, liveStatus);
+  const footer = link ? { ...link, active: active === UPDATE_PAGE_ID, onPress: () => select(UPDATE_PAGE_ID) } : undefined;
   // Design: the banner shows on every *normal* page; once you're already looking at the update
   // page there is nothing left for "Review update" to do, so it's hidden there (confirmed against
   // the approved mockup's own `frame()`: the banner only ever renders when `!isPanel`).
-  const showBanner = active !== UPDATE_PAGE_ID && shouldShowMajorBanner(update, dismissedMajor);
+  const showBanner = active !== UPDATE_PAGE_ID && shouldShowMajorBanner(effectiveUpdate, dismissedMajor);
 
   return (
     <View style={styles.root}>
       <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} labels={labels} active={active} onPress={select} footer={footer} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
         {active === UPDATE_PAGE_ID ? (
-          <UpdatePanel update={update ?? null} endpoint={updateEndpoint} appName={appName} headingRef={headingRef} />
+          <UpdatePanel
+            update={effectiveUpdate}
+            versionStatus={liveStatus}
+            onVersionStatus={setLiveStatus}
+            endpoint={updateEndpoint}
+            appName={appName}
+            headingRef={headingRef}
+          />
         ) : activeDef ? (
           <SectionBlock
             key={activeDef.id}
@@ -229,7 +264,7 @@ export function CatalogShell<TId extends string>({
             // The approved mockup's own `PAGE_BG` order: crumb, then banner, then title — the
             // banner used to render above the breadcrumb instead (Important finding, Fable
             // correction pass).
-            banner={showBanner && update ? <MajorBanner update={update} onReviewUpdate={() => select(UPDATE_PAGE_ID)} onDismiss={dismissMajorBanner} /> : undefined}
+            banner={showBanner && effectiveUpdate ? <MajorBanner update={effectiveUpdate} onReviewUpdate={() => select(UPDATE_PAGE_ID)} onDismiss={dismissMajorBanner} /> : undefined}
             pager={{
               previousId: neighbors(order, activeDef.id).previous,
               nextId: neighbors(order, activeDef.id).next,