@krapwoo/ds-viewer 0.4.4 → 0.4.6

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/ComparisonGrid.tsx

@@ -2,7 +2,8 @@ import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
-import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { ComparisonDef, SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
@@ -15,7 +16,7 @@ export function ComparisonGrid({
   def,
   size,
   sectionId,
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
 }: {
   def: ComparisonDef;
   size: SpecimenSize;
@@ -63,17 +64,17 @@ export function ComparisonGrid({
             {columns.map((c, ci) => {
               const cell = cells.get(cellKey(row.key, c.key));
               return (
-                <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
-                  {cell?.node !== undefined ? (
-                    <SpecimenSurface surface={surface} style={cell.fill && styles.fill}>
-                      {cell.node}
-                    </SpecimenSurface>
-                  ) : (
+                cell?.node !== undefined ? (
+                  <SpecimenSurface key={c.key} role="cell" surface={surface} style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
+                    <SpecimenContent fill={cell.fill}>{cell.node}</SpecimenContent>
+                  </SpecimenSurface>
+                ) : (
+                  <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
                     <Text style={styles.unavailable}>
                       {cell?.unavailableReason ? `Not supported — ${cell.unavailableReason}` : 'Missing example'}
                     </Text>
-                  )}
-                </View>
+                  </View>
+                )
               );
             })}
           </View>
@@ -102,7 +103,6 @@ const styles = StyleSheet.create({
   headerCell: { backgroundColor: CATALOG_COLOR.surfaceMuted, justifyContent: 'center' },
   bodyRow: { minHeight: MATRIX_LAYOUT.rowMinHeight },
   specimenCell: { alignItems: 'center', justifyContent: 'center' },
-  fill: { alignSelf: 'stretch' },
   headerText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
   rowHeaderText: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
   unavailable: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', textAlign: 'center', color: CATALOG_COLOR.textMuted },

package/native/catalog/ComparisonGroups.tsx

@@ -2,7 +2,8 @@ import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, type ListGroup } from './comparison';
-import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
@@ -16,7 +17,7 @@ export function ComparisonGroups({
   groups,
   size,
   label,
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
 }: {
   groups: ListGroup[];
   size: SpecimenSize;
@@ -46,11 +47,9 @@ export function ComparisonGroups({
                     <View style={styles.caption}>
                       <Text style={styles.captionText}>{item.label}</Text>
                     </View>
-                    <View style={styles.specimen}>
-                      <SpecimenSurface surface={surface} style={item.fill && styles.fill}>
-                        {item.node as React.ReactNode}
-                      </SpecimenSurface>
-                    </View>
+                    <SpecimenSurface surface={surface} style={styles.specimen}>
+                      <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                    </SpecimenSurface>
                   </View>
                 );
               })}
@@ -102,5 +101,4 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  fill: { alignSelf: 'stretch' },
 });

package/native/catalog/ComparisonList.tsx

@@ -2,7 +2,8 @@ import React, { useState } from 'react';
 import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { MATRIX_LAYOUT, listGeometry, type ListItem } from './comparison';
-import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
@@ -17,7 +18,7 @@ export function ComparisonList({
   size,
   label,
   maxColumns,
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
 }: {
   items: ListItem[];
   size: SpecimenSize;
@@ -60,11 +61,9 @@ export function ComparisonList({
                   <View style={styles.caption}>
                     <Text style={styles.captionText}>{item.label}</Text>
                   </View>
-                  <View style={styles.specimen}>
-                    <SpecimenSurface surface={surface} style={item.fill && styles.fill}>
-                      {item.node as React.ReactNode}
-                    </SpecimenSurface>
-                  </View>
+                  <SpecimenSurface surface={surface} style={styles.specimen}>
+                    <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                  </SpecimenSurface>
                 </View>
               );
             })}
@@ -101,5 +100,4 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  fill: { alignSelf: 'stretch' },
 });

package/native/catalog/SectionBlock.tsx

@@ -6,6 +6,7 @@ import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
 import { ReferenceDetails } from './ReferenceDetails';
 import { SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import { TokenSections } from './TokenLayouts';
 import { choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
 import type { PreviewWidths, SectionDef, SpecimenSurfaceKind } from './types';
@@ -104,21 +105,23 @@ function frameLabel(width: number): string {
  *  chrome and token galleries. Every frame is its own live instance with its own state. `surface`
  *  is omitted for token galleries, which keep their current, unstaged presentation. */
 function Preview({ render, widths, surface }: { render: () => React.ReactNode; widths: PreviewWidths; surface?: SpecimenSurfaceKind }) {
-  const stage = (node: React.ReactNode) => (surface ? <SpecimenSurface surface={surface}>{node}</SpecimenSurface> : node);
-  if (widths === 'full') return <View style={styles.previewCard}>{stage(render())}</View>;
+  // Token galleries pass no surface: their card stays white.
+  const kind = surface ?? 'transparent';
+  if (widths === 'full') return <SpecimenSurface surface={kind} style={styles.previewCard}>{render()}</SpecimenSurface>;
   return (
     <View style={styles.previewCard}>
       <View style={styles.frames}>
         {widths.map((width, i) => (
-          <View
+          <SpecimenSurface
             key={`${width}-${i}`}
+            surface={kind}
             // Two live instances of the same component: name each so assistive tech can tell them apart.
             {...(widths.length > 1 ? ({ role: 'group', 'aria-label': frameLabel(width) } as Record<string, unknown>) : null)}
             style={[styles.frame, { width }]}
           >
             {widths.length > 1 && <Text style={styles.frameLabel}>{frameLabel(width)}</Text>}
-            {stage(render())}
-          </View>
+            {render()}
+          </SpecimenSurface>
         ))}
       </View>
     </View>
@@ -246,7 +249,7 @@ export function SectionBlock<TId extends string>({
   checkCompleteness(def);
   // Memoized so Blocks' placement effect runs on real changes, not on every render.
   const blocks = useMemo(() => presentationBlocks(def, { defaultPreviewWidths }), [def, defaultPreviewWidths]);
-  const surface = def.specimenSurface ?? 'neutral';
+  const surface = def.specimenSurface ?? DEFAULT_SPECIMEN_SURFACE;
   // react-native-web reads `aria-level`; React Native's prop types do not declare it.
   const headingLevelProps = { 'aria-level': headingLevel } as Record<string, unknown>;
 

package/native/catalog/SpecimenSurface.tsx

@@ -1,46 +1,84 @@
-import React from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
-import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_SPACE } from './tokens';
-import { SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import { CATALOG_COLOR } from './tokens';
+import { DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
 import type { SpecimenSurfaceKind } from './types';
 
+type Browser = {
+  getComputedStyle?: (element: unknown) => never;
+  Element?: new () => unknown;
+  requestAnimationFrame?: (callback: () => void) => number;
+};
+
 /**
- * The catalog-owned background directly behind a live component specimen — shared by
- * `ComparisonList`, `ComparisonGroups`, `ComparisonGrid`, and `SectionBlock`'s component preview,
- * so a page's `specimenSurface` renders identically everywhere a specimen appears. Purely a fixed
- * backdrop: it never reads the wrapped component's own colors, never adds a border, and is never
- * used for token galleries/sections (those keep their existing full-width presentation). Always
- * stretches to its parent's width (see `specimenSurfaceStyle.ts`) rather than shrink-wrapping to
- * its content, centering that content itself — so a percentage-width specimen resolves against
- * the real comparison-cell width instead of collapsing to 0px.
+ * An example's whole cell area — shared by `ComparisonList`, `ComparisonGroups`,
+ * `ComparisonGrid`, and `SectionBlock`'s preview frames, so a page's `specimenSurface` fills every
+ * example cell the same way. With `'auto'` (the default) the cell measures its example after it
+ * draws and turns gray only when the example would vanish against white (a white card, sheet or
+ * neutral banner; see `specimenFill.ts`). Explicit kinds fill the cell without measuring. Adds no
+ * padding or border of its own: pass the cell's own layout in `style`. Measuring needs the
+ * browser's DOM; elsewhere `'auto'` leaves the cell white. Extra props (e.g. `role`) go to the View.
  */
 export function SpecimenSurface({
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
   style,
   children,
+  ...viewProps
 }: {
   surface?: SpecimenSurfaceKind;
   style?: StyleProp<ViewStyle>;
   children: React.ReactNode;
+  [prop: string]: unknown;
 }) {
-  return <View style={[styles.base, SURFACE_FILL[surface], style]}>{children}</View>;
+  const ref = useRef<View>(null);
+  const [blends, setBlends] = useState(false);
+
+  const measure = useCallback(() => {
+    if (surface !== 'auto') return;
+    const browser = globalThis as unknown as Browser;
+    const node = ref.current as unknown;
+    if (!browser.getComputedStyle || !browser.Element || !(node instanceof browser.Element)) return;
+    const { boxes, cellArea } = measurePaintedBoxes(node as Parameters<typeof measurePaintedBoxes>[0], (element) => browser.getComputedStyle!(element));
+    setBlends(blendsIntoCell(boxes, cellArea));
+  }, [surface]);
+
+  useEffect(() => {
+    const raf = (globalThis as unknown as Browser).requestAnimationFrame;
+    if (surface !== 'auto' || !raf) return;
+    // Two frames, so the example's own styles and fonts have applied before measuring.
+    let cancelled = false;
+    raf(() => raf(() => {
+      if (!cancelled) measure();
+    }));
+    return () => {
+      cancelled = true;
+    };
+  }, [surface, measure]);
+
+  const fill = surface === 'auto' ? (blends ? FILL.neutral : undefined) : FILL[surface];
+  return (
+    <View ref={ref} onLayout={surface === 'auto' ? measure : undefined} style={[style, fill]} {...viewProps}>
+      {children}
+    </View>
+  );
 }
 
-// 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token) rather than adding a new
-// background-specific color — the catalog chrome has no existing dark-surface token to reach for.
-const SURFACE_FILL: Record<SpecimenSurfaceKind, ViewStyle> = {
-  neutral: { backgroundColor: CATALOG_COLOR.surfaceMuted },
+/** Wraps one example inside its cell: full cell width (so a percentage-width example resolves
+ *  against the cell), centered unless the example fills the cell. */
+export function SpecimenContent({ fill, children }: { fill?: boolean; children: React.ReactNode }) {
+  return <View style={fill ? styles.fill : styles.center}>{children}</View>;
+}
+
+// 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token); there is no dark-surface token.
+const FILL = StyleSheet.create({
+  neutral: { backgroundColor: CATALOG_COLOR.specimenStage },
   white: { backgroundColor: CATALOG_COLOR.surface },
   dark: { backgroundColor: CATALOG_COLOR.text },
-  transparent: { backgroundColor: 'transparent' },
-};
+  transparent: {},
+});
 
 const styles = StyleSheet.create({
-  base: {
-    ...SPECIMEN_SURFACE_WIDTH_STYLE,
-    alignItems: 'center',
-    justifyContent: 'center',
-    borderRadius: CATALOG_RADIUS.sm,
-    padding: CATALOG_SPACE.md,
-  },
+  center: { ...SPECIMEN_SURFACE_WIDTH_STYLE, alignItems: 'center' },
+  fill: { ...SPECIMEN_SURFACE_WIDTH_STYLE },
 });

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