@krapwoo/ds-viewer 0.4.5 → 0.4.6

package/README.md

@@ -400,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/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,

package/native/catalog/CatalogSidebar.tsx

@@ -43,7 +43,7 @@ function NavItem<TId extends string>({ id, label, active, onPress }: { id: TId;
   );
 }
 
-function FooterLink({ label, active, onPress }: { label: string; active: boolean; onPress: () => void }) {
+function FooterLink({ label, kind, active, onPress }: { label: string; kind: 'update' | 'version'; active: boolean; onPress: () => void }) {
   const [hovered, setHovered] = useState(false);
   const [focused, setFocused] = useState(false);
   return (
@@ -63,7 +63,8 @@ function FooterLink({ label, active, onPress }: { label: string; active: boolean
         focused && styles.focusRing,
       ]}
     >
-      <View style={styles.footerDot} />
+      {/* The dot marks an available update; the everyday version line is quiet. */}
+      {kind === 'update' && <View style={styles.footerDot} />}
       <Text style={[styles.footerLabel, active && styles.footerLabelActive]}>{label}</Text>
     </Pressable>
   );
@@ -96,10 +97,10 @@ export function CatalogSidebar<TId extends string>({
   labels?: ReadonlyMap<string, string>;
   active: string | undefined;
   onPress: (id: TId) => void;
-  /** The quiet update-notice link below the nav list (design §5's footer line), or `undefined`
-   *  when there is no update to show. `active` is true while the update page itself is open — it
-   *  gets the same active styling a selected nav item would. */
-  footer?: { label: string; active: boolean; onPress: () => void };
+  /** The link below the nav list that opens the update page: the installed version (`'version'`),
+   *  or the update notice with a dot (`'update'`, design §5's footer line). `active` is true while
+   *  the update page itself is open — it gets the same active styling a selected nav item would. */
+  footer?: { label: string; kind?: 'update' | 'version'; active: boolean; onPress: () => void };
 }) {
   const [query, setQuery] = useState('');
   // A bundled local image (the only kind `cli/workspace.ts` ever produces — see its doc comment
@@ -201,7 +202,7 @@ export function CatalogSidebar<TId extends string>({
       </ScrollView>
       {footer && (
         <View style={styles.footerContainer}>
-          <FooterLink label={footer.label} active={footer.active} onPress={footer.onPress} />
+          <FooterLink label={footer.label} kind={footer.kind ?? 'update'} active={footer.active} onPress={footer.onPress} />
         </View>
       )}
     </View>

package/native/catalog/UpdatePanel.tsx

@@ -1,9 +1,11 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
-import { Platform, Pressable, ScrollView, StyleSheet, Text, View } from 'react-native';
+import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
-import { daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, type UpdatePlanView, type UpdateStatusView } from './updatePanelState';
-import type { UpdateNotice } from './types';
+import {
+  autoCheckHelp, bumpLabel, checkedAgoLabel, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
+} from './updatePanelState';
+import type { UpdateNotice, VersionStatus } from './types';
 
 function isWeb(): boolean {
   return Platform.OS === 'web' && typeof window !== 'undefined';
@@ -25,7 +27,7 @@ function VersionsHeader({ current, latest, breaking, releasedAt }: { current: st
         <Text style={styles.arrow}>→</Text>
         <Text style={styles.versionsText}>{latest}</Text>
         <View style={[styles.pill, breaking && styles.pillMajor]}>
-          <Text style={[styles.pillText, breaking && styles.pillTextMajor]}>{breaking ? 'Major' : 'Minor'}</Text>
+          <Text style={[styles.pillText, breaking && styles.pillTextMajor]}>{bumpLabel(current, latest, breaking)}</Text>
         </View>
       </View>
       <Text style={styles.muted}>{`You’re on ${current}.${releasedAt ? ` ${daysAgoLabel(releasedAt, Date.now())}` : ''}`}</Text>
@@ -190,6 +192,140 @@ function failureCopy(failedStep: string, current: string): { headline: string; b
   };
 }
 
+/**
+ * The update page when no newer version is known (approved mockup
+ * docs/design/2026-10-10-ds-viewer-update-page-always-approved.html, states 3, 4, 6, 7 and 8): the
+ * installed version and which situation applies, when it last checked, the automatic-check
+ * switch, and **Check now**. Without an endpoint (a static build) it shows the status only.
+ */
+function VersionDetails({
+  status,
+  endpoint,
+  onStatus,
+}: {
+  status: VersionStatus;
+  endpoint?: Endpoint;
+  onStatus: (next: VersionStatus) => void;
+}) {
+  const [checking, setChecking] = useState(false);
+  const [justChecked, setJustChecked] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [localError, setLocalError] = useState<string | undefined>(undefined);
+  const live = Boolean(endpoint) && isWeb();
+  const overview = versionOverview(status, justChecked, Date.now());
+  const help = autoCheckHelp(status.autoCheck);
+
+  const checkNow = async () => {
+    if (!endpoint || checking) return;
+    setChecking(true);
+    setJustChecked(false);
+    setLocalError(undefined);
+    try {
+      const res = await authedFetch(endpoint, '/version/check', { method: 'POST' });
+      if (!res.ok) throw new Error(String(res.status));
+      const next = (await res.json()) as VersionStatus;
+      // A newer version moves the whole page into the update flow (the parent re-renders with it).
+      setJustChecked(next.lastOutcome === 'ok' && !next.update);
+      onStatus(next);
+    } catch {
+      setLocalError('Couldn’t reach the viewer’s local server. If this keeps happening, restart npx ds-viewer dev.');
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const setAutoCheck = async (enabled: boolean) => {
+    if (!endpoint || saving) return;
+    setSaving(true);
+    setLocalError(undefined);
+    try {
+      const res = await authedFetch(endpoint, '/version/auto-check', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ enabled }),
+      });
+      if (!res.ok) throw new Error(String(res.status));
+      onStatus((await res.json()) as VersionStatus);
+    } catch {
+      setLocalError('Couldn’t save the setting. Try again.');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const unreachable = status.lastOutcome === 'unreachable';
+  return (
+    <>
+      <View style={styles.versionsRow}>
+        <Text style={styles.versionsText}>{status.current}</Text>
+        {overview.pill === 'latest' && (
+          <View style={[styles.pill, styles.pillSuccess]}>
+            <Text style={[styles.pillText, styles.pillTextSuccess]}>Latest</Text>
+          </View>
+        )}
+        {overview.pill === 'off' && (
+          <View style={[styles.pill, styles.pillOff]}>
+            <Text style={[styles.pillText, styles.pillTextOff]}>Checks off</Text>
+          </View>
+        )}
+      </View>
+      <Text style={styles.muted}>{overview.line}</Text>
+      {overview.note && (
+        <NoteBox variant={overview.note.variant}>
+          {overview.note.bold ? <Text style={styles.noteBoxBold}>{overview.note.bold}</Text> : null}
+          {overview.note.text}
+        </NoteBox>
+      )}
+      {!unreachable && (
+        <View style={styles.facts}>
+          <View style={styles.factRow}>
+            <Text style={styles.factLabel}>Last checked</Text>
+            <Text style={styles.factValue}>{checkedAgoLabel(status.lastCheckedAt, Date.now())}</Text>
+          </View>
+          <View style={styles.factRow}>
+            <View style={styles.switchText}>
+              <Text style={styles.switchLabel}>Check for updates automatically</Text>
+              <Text style={styles.switchHelp}>{help.text}</Text>
+            </View>
+            <Switch
+              value={status.autoCheck.enabled}
+              onValueChange={setAutoCheck}
+              disabled={!live || help.locked || saving || checking}
+              // React Native web passes only the label to the real input (no description), so the
+              // helper text rides in the accessible name: a screen reader hears why it's on or off.
+              accessibilityLabel={`Check for updates automatically. ${help.text}`}
+              trackColor={{ false: '#c9c9c9', true: CATALOG_COLOR.accent }}
+              thumbColor="#ffffff"
+              // The approved mockup's 44 × 26 switch; React Native web's default is 40 × 20, below
+              // the 24px minimum hit target.
+              style={styles.switch}
+              {...({ activeThumbColor: '#ffffff' } as Record<string, unknown>)}
+            />
+          </View>
+        </View>
+      )}
+      {localError && <NoteBox variant="err">{localError}</NoteBox>}
+      {live && (
+        <View style={styles.actions}>
+          <Pressable
+            onPress={checkNow}
+            disabled={checking}
+            accessibilityRole="button"
+            accessibilityState={{ disabled: checking, busy: checking }}
+            style={[styles.secondaryButton, styles.buttonRow, checking && styles.busyButton]}
+          >
+            {checking && <ActivityIndicator size="small" color={CATALOG_COLOR.textMuted} />}
+            <Text style={[styles.secondaryButtonText, checking && styles.busyButtonText]}>
+              {checking ? 'Checking…' : overview.action === 'retry' ? 'Try again' : 'Check now'}
+            </Text>
+          </Pressable>
+          {unreachable && !checking && <Text style={styles.muted}>or run <Code>npm view @krapwoo/ds-viewer version</Code></Text>}
+        </View>
+      )}
+    </>
+  );
+}
+
 /**
  * Design §5's update page (`#ds-viewer-update`), approved mockup direction "C · Update page".
  * Fetches `/update/status` once on mount, then `/plan` — `resolvePanelPhase` (Task 15) picks which
@@ -203,11 +339,16 @@ function failureCopy(failedStep: string, current: string): { headline: string; b
  */
 export function UpdatePanel({
   update,
+  versionStatus,
+  onVersionStatus,
   endpoint,
   appName,
   headingRef,
 }: {
   update: UpdateNotice | null;
+  /** When present, the no-update view shows the version, the switch and **Check now**. */
+  versionStatus?: VersionStatus | null;
+  onVersionStatus?: (next: VersionStatus) => void;
   endpoint?: Endpoint;
   appName: string;
   headingRef?: React.Ref<View>;
@@ -325,6 +466,8 @@ export function UpdatePanel({
     content =
       status.phase === 'success' ? (
         <SuccessContent status={status} />
+      ) : versionStatus ? (
+        <VersionDetails status={versionStatus} endpoint={endpoint} onStatus={onVersionStatus ?? (() => {})} />
       ) : (
         <NoteBox variant="ok">You’re already up to date.</NoteBox>
       );
@@ -486,7 +629,7 @@ export function UpdatePanel({
       {/* react-native-web reads `aria-level`; React Native's own prop types do not declare it —
        *  the same cast `SectionBlock.tsx`'s own heading target already uses. */}
       <View ref={headingRef} tabIndex={-1} role="heading" {...({ 'aria-level': 1 } as Record<string, unknown>)} style={styles.headingTarget}>
-        <Text style={styles.title}>Update DS Viewer</Text>
+        <Text style={styles.title}>DS Viewer updates</Text>
       </View>
       {content}
     </View>
@@ -517,6 +660,19 @@ const styles = StyleSheet.create({
   pillText: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.accent },
   pillTextMajor: { color: CATALOG_COLOR.warning },
   pillTextSuccess: { color: CATALOG_COLOR.success },
+  pillOff: { backgroundColor: CATALOG_COLOR.chip },
+  pillTextOff: { color: CATALOG_COLOR.textMuted },
+  facts: { marginTop: 18, borderTopWidth: 1, borderTopColor: CATALOG_COLOR.border },
+  factRow: { flexDirection: 'row', alignItems: 'center', justifyContent: 'space-between', gap: CATALOG_SPACE.md, paddingVertical: 10, borderBottomWidth: 1, borderBottomColor: CATALOG_COLOR.border },
+  factLabel: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted },
+  factValue: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text },
+  switchText: { flex: 1, gap: 2 },
+  switchLabel: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
+  switch: { width: 44, height: 26 },
+  switchHelp: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  buttonRow: { flexDirection: 'row', gap: CATALOG_SPACE.sm },
+  busyButton: { borderColor: CATALOG_COLOR.border },
+  busyButtonText: { color: CATALOG_COLOR.textMuted },
   muted: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 4 },
   block: { marginTop: 18 },
   h3: { fontSize: CATALOG_TYPE.panelHeading, textTransform: 'uppercase', letterSpacing: 0.5, color: CATALOG_COLOR.text, marginBottom: 8 },

package/native/catalog/catalogNavigation.ts

@@ -3,7 +3,7 @@
  * runner. CatalogShell, CatalogSidebar, and SectionBlock all derive page order from here, so the
  * sidebar order, previous/next order, and fragment fallback can never drift apart.
  */
-import type { NavGroup, UpdateNotice } from './types.ts';
+import type { NavGroup, UpdateNotice, VersionStatus } from './types.ts';
 
 /** THE canonical within-group ordering of section ids. */
 export function sortIds<TId extends string>(ids: readonly TId[]): TId[] {
@@ -149,3 +149,16 @@ export function footerLabel(update: UpdateNotice | null | undefined): string | u
   if (!update || !isNewerVersion(update.latest, update.current)) 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: UpdateNotice | null | undefined,
+  status: VersionStatus | null | undefined,
+): { label: string; kind: 'update' | 'version' } | undefined {
+  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/native/catalog/types.ts

@@ -256,6 +256,26 @@ export interface UpdateNotice {
   releasedAt?: string;
 }
 
+/** Where the "check automatically" setting in effect comes from, strongest first: the
+ *  `DS_VIEWER_NO_UPDATE_CHECK=1` environment variable (CI), your own switch on the update page
+ *  (saved per project on this computer), the project's `updateCheck` config, or the default (on). */
+export type AutoCheckSource = 'env' | 'personal' | 'project' | 'default';
+
+/** What the update page and the sidebar's version line show. Written by `dev` at startup
+ *  (`.ds-viewer/version.json`) and kept current by the local endpoint (`GET /version`,
+ *  `POST /version/check`, `POST /version/auto-check`). */
+export interface VersionStatus {
+  /** The installed ds-viewer version. */
+  current: string;
+  autoCheck: { enabled: boolean; source: AutoCheckSource };
+  /** The last successful check on this computer (any project), when known. */
+  lastCheckedAt?: string;
+  /** This run's most recent check: answered, npm unreachable, or not run (checks off). */
+  lastOutcome: 'ok' | 'unreachable' | 'not-run';
+  /** A newer version, when one is known. */
+  update: UpdateNotice | null;
+}
+
 /** One titled card on a token page (`SectionDef.tokenSections`). */
 export interface TokenSection {
   /** The kind of token this card holds, e.g. "Semantic colours", "Palette", "Body". */

package/native/catalog/updatePanelState.ts

@@ -1,3 +1,5 @@
+import type { AutoCheckSource, VersionStatus } from './types.ts';
+
 /** The same shape as `cli/updatePlan.ts`'s `UpdatePlan` — duplicated, not imported: `native/catalog/`
  *  is the published package root and never imports from `cli/` (the reverse is normal: `cli/`
  *  already imports `native/catalog/` throughout). The endpoint's `POST /plan` response is this
@@ -72,3 +74,73 @@ export function daysAgoLabel(releasedAt: string, nowMs: number): string {
   if (days === 1) return 'Released 1 day ago.';
   return `Released ${days} days ago.`;
 }
+
+/** "Last checked" on the update page. */
+export function checkedAgoLabel(at: string | undefined, nowMs: number): string {
+  if (!at) return 'Never';
+  const minutes = Math.floor((nowMs - Date.parse(at)) / 60_000);
+  if (minutes < 1) return 'Just now';
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  const days = Math.floor(hours / 24);
+  return `${days} day${days === 1 ? '' : 's'} ago`;
+}
+
+export interface VersionOverview {
+  pill?: 'latest' | 'off';
+  line: string;
+  note?: { variant: 'ok' | 'err'; bold?: string; text: string };
+  /** **Check now**, or **Try again** after npm didn't answer. */
+  action: 'check' | 'retry';
+}
+
+/** The update page when no newer version is known: which of "latest", "checks off", "not checked
+ *  yet" and "couldn't reach npm" applies. Only a check that actually answered may say "latest".
+ *  `justChecked` is true right after **Check now** found nothing newer. */
+export function versionOverview(status: VersionStatus, justChecked: boolean, nowMs: number): VersionOverview {
+  if (status.lastOutcome === 'unreachable') {
+    const last = status.lastCheckedAt ? ` The last successful check, ${checkedAgoLabel(status.lastCheckedAt, nowMs).toLowerCase()}, found no newer version.` : '';
+    return { line: `You’re on ${status.current}.`, action: 'retry', note: { variant: 'err', bold: 'Couldn’t reach npm.', text: ` You may be offline.${last}` } };
+  }
+  if (status.lastOutcome === 'not-run') {
+    if (!status.autoCheck.enabled) {
+      return { pill: 'off', line: `You’re on ${status.current}. Automatic checks are off, so this can’t tell whether a newer version exists.`, action: 'check' };
+    }
+    return { line: `You’re on ${status.current}. Not checked yet: automatic checks run when the viewer starts.`, action: 'check' };
+  }
+  // Turned off after a check answered (approved mockup state 7b); a fresh Check now still wins.
+  if (!status.autoCheck.enabled && !justChecked) {
+    return { pill: 'off', line: `You’re on ${status.current}. Automatic checks are off.`, action: 'check' };
+  }
+  return {
+    pill: 'latest',
+    line: 'You’re on the latest version.',
+    action: 'check',
+    ...(justChecked ? { note: { variant: 'ok' as const, text: 'Checked just now. No newer version.' } } : {}),
+  };
+}
+
+/** The switch's helper text: where the setting in effect comes from. Only CI's environment
+ *  variable locks the switch. */
+export function autoCheckHelp(autoCheck: { enabled: boolean; source: AutoCheckSource }): { text: string; locked: boolean } {
+  if (autoCheck.source === 'env') return { text: 'Off in this environment (DS_VIEWER_NO_UPDATE_CHECK=1).', locked: true };
+  if (autoCheck.source === 'personal') {
+    return { text: autoCheck.enabled ? 'Once a day, when the viewer starts. Saved for you on this computer.' : 'Turned off by you on this computer.', locked: false };
+  }
+  if (!autoCheck.enabled) {
+    return { text: 'Off for this project (updateCheck: false in ds-viewer.config.ts). Turning it on here applies to you only.', locked: false };
+  }
+  return { text: 'Once a day, when the viewer starts.', locked: false };
+}
+
+/** The update's size pill. Breaking updates are always "Major" (the CLI decides that); otherwise
+ *  a change in the second number is "Minor" and anything smaller "Patch". */
+export function bumpLabel(current: string, latest: string, breaking: boolean): 'Major' | 'Minor' | 'Patch' {
+  if (breaking) return 'Major';
+  const parts = (v: string) => /^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1, 4).map(Number);
+  const a = parts(current);
+  const b = parts(latest);
+  if (!a || !b) return 'Minor';
+  return a[0] === b[0] && a[1] === b[1] ? 'Patch' : 'Minor';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",