@krapwoo/ds-viewer 0.3.0 → 0.4.1

package/dist/cli/updateCheck.js

@@ -0,0 +1,143 @@
+// cli/updateCheck.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { compareVersions, isBreakingUpgrade, parseVersion } from "./semver.js";
+const CACHE_FILE_NAME = 'update-check.json';
+const PACKAGE_NAME = '@krapwoo/ds-viewer';
+const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME).replace('%40', '@')}/latest`;
+const GITHUB_REPO = 'krapwoo/design-system-viewer';
+const TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1000;
+/** Design §5: a user-wide (not project-wide) cache folder, shared across every project running
+ *  this CLI — one real release per package version, so there is nothing to key by project. */
+export function cacheDirFor(platform, env, homedir) {
+    if (platform === 'darwin')
+        return path.posix.join(homedir, 'Library', 'Caches', 'ds-viewer');
+    if (platform === 'win32')
+        return path.win32.join(env.LOCALAPPDATA ?? path.win32.join(homedir, 'AppData', 'Local'), 'ds-viewer');
+    return path.posix.join(env.XDG_CACHE_HOME ?? path.posix.join(homedir, '.cache'), 'ds-viewer');
+}
+export function readCache(cacheDir) {
+    const file = path.join(cacheDir, CACHE_FILE_NAME);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(cacheDir, cached) {
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(path.join(cacheDir, CACHE_FILE_NAME), JSON.stringify(cached));
+}
+export function isCacheFresh(cache, nowMs) {
+    return nowMs - Date.parse(cache.checkedAt) < TWENTY_FOUR_HOURS_MS;
+}
+/** The one place "is this actually worth showing" is decided: a cached/fetched `latest` that is
+ *  not strictly newer than the version asking (already up to date, or — this repository's own
+ *  `kit-host` before a real publish — temporarily *ahead* of what the registry reports) resolves
+ *  to `undefined`, the same uniform "no update known" every other non-case already returns
+ *  (Critical finding, Fable correction pass: without this, a stale/foreign cache entry could show
+ *  a downgrade, or keep showing an update that was already applied). */
+function toResultOrUndefined(cached, currentVersion) {
+    const current = parseVersion(currentVersion);
+    const latest = parseVersion(cached.latest);
+    if (compareVersions(latest, current) <= 0)
+        return undefined;
+    return { ...cached, current: currentVersion, breaking: isBreakingUpgrade(current, latest) };
+}
+/** `config` only ever needs its one field here — a plain object literal, not the full
+ *  `ResolvedConfig`, is deliberately accepted so this has no import-time dependency on `cli/types.ts`. */
+export function isUpdateCheckEnabled(config, env) {
+    if (env.DS_VIEWER_NO_UPDATE_CHECK === '1')
+        return false;
+    return config.updateCheck ?? true;
+}
+/** `- ` or `* ` markdown list items only, trimmed, in order, capped at 5 — a release body's prose
+ *  paragraphs are never shown as if they were bullets. */
+export function extractSummaryBullets(body) {
+    return body
+        .split('\n')
+        .map((line) => /^[-*]\s+(.*)$/.exec(line.trim())?.[1])
+        .filter((line) => Boolean(line))
+        .slice(0, 5);
+}
+/** Exported for `cli/updatePlan.ts` (Task 9), which needs the exact same "don't hang forever on
+ *  the GitHub release" behavior for its own plan-building fetch (Important finding, Fable
+ *  correction pass: that fetch had no timeout of its own before). */
+export async function fetchWithTimeout(url, fetchImpl, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, { signal: controller.signal });
+        if (!response.ok)
+            throw new Error(`${url} responded ${response.status}`);
+        return await response.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 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);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 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. */
+export function writeUpdateFile(projectRoot, result) {
+    const file = path.join(projectRoot, '.ds-viewer', 'update.json');
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(result ?? null));
+    return file;
+}

package/dist/cli/updatePlan.js

@@ -0,0 +1,211 @@
+// cli/updatePlan.ts
+import { execFile, execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { detectPackageManager, platformCommand } from "./packageManager.js";
+import { listKitFileDiffs } from "./kitDiff.js";
+import { extractSummaryBullets, fetchWithTimeout } from "./updateCheck.js";
+import { compareVersions, isBreakingUpgrade, parseVersion } from "./semver.js";
+const PACKAGE_NAME = '@krapwoo/ds-viewer';
+const OFFLINE_MESSAGE = "Couldn't prepare the update. You may be offline, or npm didn't respond. Nothing was changed.";
+function tarballFileName(version) {
+    return `krapwoo-ds-viewer-${version}.tgz`;
+}
+function lockfileName(pm) {
+    if (pm === 'pnpm')
+        return 'pnpm-lock.yaml';
+    if (pm === 'yarn-classic' || pm === 'yarn-berry')
+        return 'yarn.lock';
+    return 'package-lock.json';
+}
+/** `git status --porcelain`'s format is `XY path` (plain) or `XY old -> new` (a rename) — the
+ *  path starts at column 3 either way; a rename's own "dirty" identity is its *new* path (the one
+ *  this plan's own `files` list names), never the old one (Important finding, Fable correction
+ *  pass: `R  old -> new` was previously read as the single literal path `"old -> new"`, which
+ *  could never match a planned file). */
+function parseDirtyPaths(porcelain) {
+    return new Set(porcelain
+        .split('\n')
+        .filter((line) => line.length > 3)
+        .map((line) => {
+        const raw = line.slice(3).trim();
+        const arrow = raw.indexOf(' -> ');
+        return arrow === -1 ? raw : raw.slice(arrow + 4);
+    }));
+}
+/** Strips the repository-root prefix `git rev-parse --show-prefix` reports from every path in a
+ *  `git status --porcelain` listing (both sides of a rename), so the result reads relative to
+ *  `projectRoot` the same way every test's injected fake already does. */
+export function stripRepoPrefix(porcelain, prefix) {
+    if (!prefix)
+        return porcelain;
+    return porcelain
+        .split('\n')
+        .map((line) => {
+        if (line.length <= 3)
+            return line;
+        const status = line.slice(0, 3);
+        const rest = line.slice(3).split(' -> ').map((part) => (part.startsWith(prefix) ? part.slice(prefix.length) : part));
+        return `${status}${rest.join(' -> ')}`;
+    })
+        .join('\n');
+}
+/** Thrown by `defaultGitStatus` for any git failure that is *not* "not a git repository" (or git
+ *  missing) — `buildUpdatePlan` below catches exactly this to return a plan `{ error }`, naming
+ *  git, instead of silently treating the failure as "outside a git repository" (Minor finding,
+ *  Fable correction pass: `fatal: detected dubious ownership`, a corrupt repo, or any other
+ *  non-zero exit previously fell into the same `undefined` branch as genuinely being outside a
+ *  repository, fail-open on the feature's one core safeguard — the dirty-file check — the CLI then
+ *  printing the misleading "(Not a git repository …)" note over a real error). */
+export class GitStatusError extends Error {
+}
+function isMissingRepo(error) {
+    const e = error;
+    if (e.code === 'ENOENT')
+        return true;
+    return /not a git repository/i.test(e.stderr ?? e.message ?? '');
+}
+function defaultGitStatus(projectRoot, plannedPaths) {
+    let prefix;
+    try {
+        prefix = execFileSync('git', ['rev-parse', '--show-prefix'], { cwd: projectRoot, encoding: 'utf8' }).trim();
+    }
+    catch (error) {
+        if (isMissingRepo(error))
+            return undefined;
+        throw new GitStatusError(`git rev-parse failed: ${error.message}`);
+    }
+    try {
+        // Errata 6: pathspecs are relative to the cwd (`projectRoot`), so they are passed unprefixed
+        // — only the *output* paths (which `git status --porcelain` always reports relative to the
+        // repository root) need `stripRepoPrefix` below.
+        const porcelain = execFileSync('git', ['status', '--porcelain', '--', ...plannedPaths], { cwd: projectRoot, encoding: 'utf8' });
+        return stripRepoPrefix(porcelain, prefix);
+    }
+    catch (error) {
+        throw new GitStatusError(`git status failed: ${error.message}`);
+    }
+}
+/** "Already on the latest version" is reported through the plan's `{ error }` channel, but it is not a
+ *  failure: `update` exits 0 for it, and the viewer shows it as up to date (`isAlreadyUpToDateError`). */
+export const ALREADY_UP_TO_DATE = 'Already on the latest version';
+export function isAlreadyUpToDate(error) {
+    return error.startsWith(ALREADY_UP_TO_DATE);
+}
+/** Design §5 "Update plan", steps 1-3, in full. Every external effect is injected (Global
+ *  Constraints) — the real defaults are a real `npm view`/`npm pack`/`tar`/`node migrate` and a
+ *  real `git status --porcelain`, exactly what Task 20's own Verdaccio spike already exercised. */
+export async function buildUpdatePlan(config, currentVersion, options = {}) {
+    const execFileAsync = promisify(execFile);
+    const execImpl = options.execImpl ?? (async (cmd, args, opts) => {
+        const run = platformCommand(cmd, args);
+        return (await execFileAsync(run.command, run.args, { ...opts, shell: run.shell })).stdout;
+    });
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const tmpDirImpl = options.tmpDirImpl ?? (() => mkdtempSync(path.join(tmpdir(), 'ds-viewer-update-')));
+    const gitStatusImpl = options.gitStatusImpl ?? defaultGitStatus;
+    // Important finding, Fable correction pass: a real, unreachable registry otherwise hangs `npm
+    // view`/`npm pack` for minutes (observed: "Checking…" sat for 140s, with `/update/status` not
+    // answering at all in that time — this whole function runs inside the endpoint's own request
+    // handler). 20s is generous for a real, reachable registry, and short enough that offline reaches
+    // "Couldn't prepare" in a bounded time instead of hanging.
+    const NETWORK_TIMEOUT_MS = 20_000;
+    let targetVersion;
+    try {
+        targetVersion = (await execImpl('npm', ['view', PACKAGE_NAME, 'version'], { cwd: config.projectRoot, encoding: 'utf8', timeout: NETWORK_TIMEOUT_MS })).trim();
+    }
+    catch {
+        return { error: OFFLINE_MESSAGE };
+    }
+    // Errata 13: "Already on the latest version" when target <= current, not only on equality — an
+    // installed version ahead of the registry's own `npm view` result (e.g. a local prerelease) is
+    // not something `update` should try to "downgrade" into.
+    if (compareVersions(parseVersion(targetVersion), parseVersion(currentVersion)) <= 0) {
+        return { error: `${ALREADY_UP_TO_DATE} (${currentVersion}).` };
+    }
+    let migrateResult;
+    // M4 (Minor, Fable correction pass): compared against the *downloaded target version's* own
+    // `starter-kit/`, not the currently-installed one — the copy ("differ from {latest}'s kit") and
+    // design §5 both name the target, never what's already on disk. Computed here, before the
+    // `finally` below cleans the extracted tarball up.
+    let kitFilesDiffering = 0;
+    let tmp;
+    try {
+        tmp = tmpDirImpl();
+        // Step 1: "Download the target version into a temporary folder" — `npm pack` is an ordinary
+        // install-shaped request (it honors the project's own `.npmrc`/registry config exactly like
+        // `npm install` would), never a URL this file hardcodes.
+        await execImpl('npm', ['pack', `${PACKAGE_NAME}@${targetVersion}`, '--silent', '--pack-destination', tmp], { cwd: config.projectRoot, encoding: 'utf8', timeout: NETWORK_TIMEOUT_MS });
+        await execImpl('tar', ['-xzf', path.join(tmp, tarballFileName(targetVersion)), '-C', tmp], { cwd: tmp, encoding: 'utf8' });
+        // Step 2: the *downloaded* version's own migrations, never the currently-running one — so the
+        // plan always reflects the migrations the version being installed actually ships. This runs
+        // `migrateEntry.js`, never `main.js` (Critical finding, Fable correction pass, spiked for real
+        // in `spikes/migrate-entry/`): the extracted tarball has no `node_modules` of its own, and
+        // `main.js`'s own import chain pulls in the `typescript` npm package at module load, which
+        // would fail there with `ERR_MODULE_NOT_FOUND`; `migrateEntry.js` imports nothing but
+        // `migrate.ts`/`migrations/`/`semver.ts`, none of which may ever import `typescript`.
+        const migrateOutput = await execImpl('node', [path.join(tmp, 'package', 'dist', 'cli', 'migrateEntry.js'), '--from', currentVersion, '--dry-run', '--json'], { cwd: config.projectRoot, encoding: 'utf8' });
+        migrateResult = JSON.parse(migrateOutput);
+        kitFilesDiffering = listKitFileDiffs(config, path.join(tmp, 'package', 'starter-kit')).filter((d) => d.status !== 'identical').length;
+    }
+    catch {
+        return { error: OFFLINE_MESSAGE };
+    }
+    finally {
+        // Minor finding, Fable correction pass: every "Check again" (a fresh plan) used to leak this
+        // tarball and its extracted folder — cleaned up here regardless of success or failure.
+        if (tmp)
+            rmSync(tmp, { recursive: true, force: true });
+    }
+    const pm = detectPackageManager(config.projectRoot);
+    const files = [
+        { path: 'package.json', reason: 'version', dirty: false },
+        { path: lockfileName(pm), reason: 'version', dirty: false },
+        ...migrateResult.changes.map((change) => ({ path: change.file, reason: `migration: ${change.change}`, dirty: false })),
+    ];
+    // Scoped to exactly the files above (decision 4 (brief): "limited to planned files") — called
+    // only now that `files` is known, so the real `defaultGitStatus` can pass their paths as `git
+    // status`'s own pathspec.
+    // M9 (Minor, Fable correction pass): `gitStatusImpl` throwing (rather than returning `undefined`,
+    // reserved for "outside a git repository") means a real git failure — fail closed with a plan
+    // `{ error }` naming git, never silently fall back to "outside a git repository, nothing is
+    // dirty" the way returning `undefined` here would.
+    let porcelain;
+    try {
+        porcelain = gitStatusImpl(config.projectRoot, files.map((f) => f.path));
+    }
+    catch (error) {
+        return { error: `Couldn't check for uncommitted changes (git): ${error.message}` };
+    }
+    const outsideGitRepo = porcelain === undefined;
+    const dirtyPaths = porcelain === undefined ? new Set() : parseDirtyPaths(porcelain);
+    for (const file of files)
+        file.dirty = dirtyPaths.has(file.path);
+    let summary = [];
+    let releasedAt;
+    try {
+        // `fetchWithTimeout` (Task 4, exported) — a black-holed `api.github.com` must not hang this
+        // plan forever (Important finding, Fable correction pass: this request previously had no
+        // timeout of its own, unlike the identical request inside `checkForUpdate`).
+        const release = (await fetchWithTimeout(`https://api.github.com/repos/krapwoo/design-system-viewer/releases/tags/v${targetVersion}`, fetchImpl, 900));
+        summary = release.body ? extractSummaryBullets(release.body) : [];
+        releasedAt = release.published_at;
+    }
+    catch {
+        // Non-fatal — Task 4's identical reasoning: the version/migration half of the plan is what
+        // matters; a missing release summary degrades to an empty "What's new" list.
+    }
+    return {
+        current: currentVersion,
+        latest: targetVersion,
+        breaking: isBreakingUpgrade(parseVersion(currentVersion), parseVersion(targetVersion)),
+        summary,
+        releasedAt,
+        files,
+        dirtyFiles: files.filter((f) => f.dirty).map((f) => f.path),
+        kitFilesDiffering,
+        outsideGitRepo,
+    };
+}

package/dist/cli/workspace.js

@@ -49,7 +49,7 @@ module.exports = config;
  *  at bundle time, so a runtime try/catch `require` cannot skip it when the optional peer is
  *  missing. Importing and wrapping must instead be baked into the generated entry (design §1
  *  "Three parts", Viewer row). */
-function entryTsx(name, hasSafeArea, groupOrder, logoRequirePath) {
+function entryTsx(name, hasSafeArea, groupOrder, logoRequirePath, updateEndpoint) {
     const safeAreaImport = hasSafeArea ? "import { SafeAreaProvider } from 'react-native-safe-area-context';\n" : '';
     // A literal `require(...)` with a path computed at generation time: Metro resolves every import
     // statically, so the logo's actual (arbitrary, user-configured) location must already be baked
@@ -61,13 +61,18 @@ function entryTsx(name, hasSafeArea, groupOrder, logoRequirePath) {
     // Fable's implementation review, cli/workspace.ts:65).
     const logoImport = logoRequirePath ? `const logoSource = require(${JSON.stringify(logoRequirePath)});\n` : '';
     const logoProp = logoRequirePath ? ' logoImageSource={logoSource}' : '';
-    const viewer = `<CatalogShell appName={${JSON.stringify(name)}} title="Component Catalog" groups={groups} sections={sections}${logoProp} />`;
+    // `JSON.stringify` of a plain `{ baseUrl, secret }` object is valid JS object-literal syntax too
+    // (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 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';
+${endpointConst}
 function App() {
   const { sections, groups } = buildCatalogSections(pages, components, ${JSON.stringify(groupOrder)});
   return ${root};
@@ -96,7 +101,7 @@ function projectIncludeGlobs(config) {
 /** Writes the self-contained Expo web workspace at `.ds-viewer/` (design §2 "The preview
  *  workspace and `npx ds-viewer dev`"). Rewritten freely on every `dev` run — nothing here is
  *  user-owned. */
-export function writeWorkspace(config) {
+export function writeWorkspace(config, updateEndpoint) {
     const workspace = path.join(config.projectRoot, '.ds-viewer');
     mkdirSync(workspace, { recursive: true });
     writeFileSync(path.join(workspace, 'package.json'), `${JSON.stringify({ name: 'ds-viewer-workspace', private: true, main: 'entry.tsx' }, null, 2)}\n`);
@@ -122,6 +127,6 @@ export function writeWorkspace(config) {
     const logoRequirePath = config.logo
         ? path.relative(workspace, path.resolve(config.projectRoot, config.logo)).split(path.sep).join('/')
         : undefined;
-    writeFileSync(path.join(workspace, 'entry.tsx'), entryTsx(config.name, hasSafeArea, config.groupOrder ?? [], logoRequirePath));
+    writeFileSync(path.join(workspace, 'entry.tsx'), entryTsx(config.name, hasSafeArea, config.groupOrder ?? [], logoRequirePath, updateEndpoint));
     return workspace;
 }

package/dist/native/catalog/catalogNavigation.js

@@ -0,0 +1,129 @@
+/** THE canonical within-group ordering of section ids. */
+export function sortIds(ids) {
+    return ids.slice().sort((a, b) => a.localeCompare(b));
+}
+/** Every page id in sidebar order: groups in declared order, ids sorted within each group,
+ *  first occurrence wins, and ids without a matching section (when `availableIds` is given) are
+ *  dropped. */
+export function orderedIds(groups, availableIds) {
+    const seen = new Set();
+    const order = [];
+    for (const group of groups) {
+        for (const id of sortIds(group.ids)) {
+            if (seen.has(id))
+                continue;
+            if (availableIds && !availableIds.has(id))
+                continue;
+            seen.add(id);
+            order.push(id);
+        }
+    }
+    return order;
+}
+export function groupLabelFor(groups, id) {
+    return groups.find((group) => group.ids.includes(id))?.label;
+}
+/** Previous and next page ids. Never wraps; null marks an unavailable direction. */
+export function neighbors(order, id) {
+    const index = order.indexOf(id);
+    if (index < 0)
+        return { previous: null, next: null };
+    return {
+        previous: index > 0 ? order[index - 1] : null,
+        next: index < order.length - 1 ? order[index + 1] : null,
+    };
+}
+/** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. */
+export function filterGroups(groups, query) {
+    const q = query.trim().toLowerCase();
+    return groups
+        .map((group) => ({
+        label: group.label,
+        ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q)) : group.ids),
+    }))
+        .filter((group) => group.ids.length > 0);
+}
+export function hashForId(id) {
+    return `#${encodeURIComponent(id)}`;
+}
+/** The page named by a URL fragment, or the first page when the fragment is empty, malformed, or
+ *  unknown. Undefined only when there are no pages. */
+export function idFromHash(hash, order) {
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    let decoded = '';
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        decoded = '';
+    }
+    const match = order.find((id) => id === decoded);
+    return match ?? order[0];
+}
+/** Design §5: the update panel is its own catalog page at this fragment, "not listed in the
+ *  sidebar groups" — it is therefore never a member of `order`, so `idFromHash` alone would treat
+ *  it as an unknown fragment and fall back to the first real page. */
+export const UPDATE_PAGE_ID = 'ds-viewer-update';
+/** The request header both the local endpoint (Task 12, which checks it) and the panel's own
+ *  fetch calls (Task 16, which send it) use for the per-`dev`-run secret (design §5 "Local
+ *  endpoint safeguards"). Defined once, here, rather than as a literal string repeated in both the
+ *  `cli/` and `native/catalog/` halves of the package, which may never import from each other in
+ *  the other direction (`cli/` imports `native/catalog/`; `native/catalog/` imports nothing from
+ *  `cli/`). */
+export const DS_VIEWER_SECRET_HEADER = 'x-ds-viewer-secret';
+/** A minimal `major.minor.patch` comparison, duplicated from `cli/semver.ts`'s own
+ *  `compareVersions` rather than imported — `native/catalog/` is the published package root and
+ *  never imports from `cli/` (the same reasoning `native/catalog/updatePanelState.ts`'s own
+ *  `UpdatePlanView`/`UpdateStatusView`, Task 15, already established for duplicated types). Used
+ *  only as a defense-in-depth guard (Critical finding, Fable correction pass) alongside
+ *  `checkForUpdate`'s own newer-than-current check (Task 4) — not a general-purpose semver
+ *  comparator, the same scope note `cli/semver.ts`'s own `Version` interface already carries.
+ *  Errata 5: parses with a regex rather than `split('.').map(Number)` so a prerelease suffix on
+ *  either string (e.g. `0.4.1-verify`) doesn't turn the patch component into `NaN`; a string that
+ *  doesn't match at all is treated as not newer. */
+function isNewerVersion(a, b) {
+    const ma = a.match(/^(\d+)\.(\d+)\.(\d+)/);
+    const mb = b.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!ma || !mb)
+        return false;
+    for (let i = 1; i <= 3; i += 1) {
+        const na = Number(ma[i]);
+        const nb = Number(mb[i]);
+        if (na !== nb)
+            return na > nb;
+    }
+    return false;
+}
+export function resolveActiveFromHash(hash, order) {
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    let decoded = '';
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        decoded = '';
+    }
+    if (decoded === UPDATE_PAGE_ID)
+        return UPDATE_PAGE_ID;
+    return idFromHash(hash, order);
+}
+/** Design §5: "Major: ... dismissible per version; the footer line remains." `dismissedVersion`
+ *  is whatever a previous dismissal recorded (`CatalogShell`'s own `localStorage` read, Task 14) —
+ *  any value other than the *current* `update.latest` (including `null`, or an older dismissed
+ *  major) still shows the banner, so dismissing 1.0.0 does not also suppress a later 2.0.0. */
+export function shouldShowMajorBanner(update, dismissedVersion) {
+    if (!update || !update.breaking)
+        return false;
+    if (!isNewerVersion(update.latest, update.current))
+        return false;
+    return update.latest !== dismissedVersion;
+}
+/** The quiet footer line's exact copy (design §5: `"Update available · 0.5.0"`), or `undefined`
+ *  when there is nothing to show. Independent of `shouldShowMajorBanner` — design: the footer line
+ *  shows for *every* available update, minor or major, and stays even once the major banner is
+ *  dismissed. */
+export function footerLabel(update) {
+    if (!update || !isNewerVersion(update.latest, update.current))
+        return undefined;
+    return `Update available · ${update.latest}`;
+}

package/dist/native/catalog/tokens.js

@@ -59,6 +59,10 @@ export const CATALOG_LAYOUT = {
     logoMark: 32,
     logoWordmarkHeight: 28,
     logoCaptionGap: 6,
+    /** Max width of the update page's content column (approved mockup: direction "C · Update
+     *  page", content at most 512px) — independent of `CATALOG_MAX_CONTENT_WIDTH` (1200px), which
+     *  is every other page's column width. */
+    updateContentMaxWidth: 512,
 };
 /** Max width of the main content column. */
 export const CATALOG_MAX_CONTENT_WIDTH = 1200;
@@ -116,4 +120,15 @@ export const CATALOG_COLOR = {
     /** 3px keyboard focus ring on every catalog control. */
     focusRing: '#c9d7ff',
     code: 'Menlo',
+    /** Major-update banner background/border/text (design §5 "Viewer notice"). */
+    warning: '#8a4b00',
+    warningSubtle: '#fff4e0',
+    warningBorder: '#f0cf97',
+    /** "Can't prepare"/failure note-boxes on the update page. */
+    danger: '#b3261e',
+    dangerSubtle: '#fdecea',
+    dangerBorder: '#f2b8b5',
+    /** The update page's post-update success note-box and "Updated" pill. */
+    success: '#1e6b3a',
+    successSubtle: '#e8f5ec',
 };