@krapwoo/ds-viewer 0.2.0 → 0.4.0

package/dist/native/catalog/comparison.js

@@ -0,0 +1,283 @@
+/** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
+ *  content width is a 1280px viewport minus the 264px sidebar and 32px side padding. */
+export const MATRIX_LAYOUT = {
+    rowHeaderWidth: 120,
+    columnMaxWidth: 402,
+    cellPadding: 16,
+    rowMinHeight: 150,
+    laptopContentWidth: 952,
+};
+/** Component previews never render wider than a phone. */
+export const PREVIEW_MAX_WIDTH = 402;
+/** Two blocks share a row only when that saves at least this much page height. */
+export const PLACEMENT_MIN_SAVING = 120;
+/** A Props column is never narrower than this; below it the Props box uses one column. */
+export const PROPS_MIN_COLUMN_WIDTH = 360;
+/** Gap between the two Props columns (CATALOG_SPACE['2xl']). */
+export const PROPS_COLUMN_GAP = 32;
+/** Smallest column or cell width per specimen size. Wide specimens are fixed at phone width. */
+export const COLUMN_MIN_WIDTH = { compact: 160, regular: 240, wide: 402 };
+/** `Array.isArray`'s built-in type guard narrows to a mutable `any[]`, which a `readonly T[]`
+ *  union member is never assignable to — so the `else` branch of `Array.isArray(axis) ? ... :
+ *  ...` keeps `axis`'s full union type instead of narrowing away the array member. This explicit
+ *  predicate sidesteps that (never caught before Task 4: this file had never been typechecked by
+ *  `tsc` until `cli/doctor.ts`'s import pulled it into the root `tsconfig.json`'s program). */
+function isBoundAxis(axis) {
+    return !Array.isArray(axis);
+}
+/** A `GridAxis`'s own items, whether it's a plain array or bound to a prop — every reader of
+ *  `ComparisonDef.rows`/`columns` goes through this (never `Array.isArray` directly), so a future
+ *  third axis shape only needs to change this one function. */
+export function axisItems(axis) {
+    return isBoundAxis(axis) ? [...axis.items] : [...axis];
+}
+/** The prop name a `GridAxis` is bound to, or undefined for a plain, unbound axis. */
+export function axisProp(axis) {
+    return isBoundAxis(axis) ? axis.prop : undefined;
+}
+/**
+ * Shared page-authoring helper (design §1 "Page shape", §4 "Binding examples to props"). Every
+ * grid comparison in the starter kit builds its `ComparisonDef` with this instead of its own local
+ * copy, so `cli/staticPage.ts`'s static reader has exactly one call shape to recognize anywhere a
+ * page's `comparison` field is produced by a function call rather than written as a plain object
+ * literal. `rows`/`columns` accept either a plain item array (unbound) or `{ prop, items }` (bound)
+ * — the cell grid itself is unaffected either way, since cells are always keyed by each axis's own
+ * items regardless of whether that axis names a prop. Lives here, beside `axisItems`/`axisProp`,
+ * rather than in its own `grid.ts` — every other file in this module has only *type-only* relative
+ * imports; a bare, no-extension value import would be the first of its kind in `native/catalog`.
+ *
+ * Each cell is a real instance with exactly the props its row and column name. Never build these by
+ * multiplying `variants` with `states` — those are pre-rendered nodes and cannot be combined.
+ */
+export function grid(rowLabel, columnLabel, rows, columns, cell, size) {
+    const rowItems = axisItems(rows);
+    const columnItems = axisItems(columns);
+    return {
+        rowLabel,
+        columnLabel,
+        rows,
+        columns,
+        cells: rowItems.flatMap((row) => columnItems.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+        size,
+    };
+}
+/** How many grid columns fit beside the row header on a 1280px laptop without scrolling. */
+export function gridColumnLimit(size) {
+    return Math.floor((MATRIX_LAYOUT.laptopContentWidth - MATRIX_LAYOUT.rowHeaderWidth) / COLUMN_MIN_WIDTH[size]);
+}
+export function gridWidthBounds(columnCount, size) {
+    const n = Math.max(0, columnCount);
+    return {
+        minWidth: MATRIX_LAYOUT.rowHeaderWidth + n * COLUMN_MIN_WIDTH[size],
+        maxWidth: MATRIX_LAYOUT.rowHeaderWidth + n * MATRIX_LAYOUT.columnMaxWidth,
+    };
+}
+/** Balanced wrapping for a one-axis list inside a single bordered card (1px outer border). Each
+ *  cell's 1px divider sits inside its own width, so no cell is ever wider than 402px. Uses as few
+ *  rows as fit, then spreads items evenly across them so a short last row leaves as little empty
+ *  space as possible. `fillers` blank cells complete the last row. */
+export function listGeometry(itemCount, availableWidth, size) {
+    if (itemCount <= 0)
+        return { columns: 0, rows: 0, fillers: 0, cellWidth: 0, containerWidth: 0 };
+    const inner = Math.max(0, availableWidth - 2);
+    const min = COLUMN_MIN_WIDTH[size];
+    const maxColumns = Math.max(1, Math.min(itemCount, Math.floor(inner / min)));
+    const rows = Math.ceil(itemCount / maxColumns);
+    const columns = Math.ceil(itemCount / rows);
+    const fitted = Math.floor(inner / columns);
+    const cellWidth = size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : Math.max(min, Math.min(MATRIX_LAYOUT.columnMaxWidth, fitted));
+    return {
+        columns,
+        rows,
+        fillers: rows * columns - itemCount,
+        cellWidth,
+        containerWidth: columns * cellWidth + 2,
+    };
+}
+export function cellKey(rowKey, columnKey) {
+    return `${rowKey}\u0000${columnKey}`;
+}
+export function indexCells(def) {
+    const index = new Map();
+    for (const cell of def.cells) {
+        const key = cellKey(cell.rowKey, cell.columnKey);
+        if (!index.has(key))
+            index.set(key, cell);
+    }
+    return index;
+}
+/** Human-readable problems in a stable order: axis duplicates, column fit, each cell in
+ *  declaration order, then missing coordinates in row-major order. Empty when valid. */
+export function validateComparison(def) {
+    const rowItems = axisItems(def.rows);
+    const columnItems = axisItems(def.columns);
+    if (rowItems.length === 0 || columnItems.length === 0) {
+        return ['Comparison needs at least one row and one column.'];
+    }
+    const issues = [];
+    const rowKeys = new Set();
+    for (const row of rowItems) {
+        if (rowKeys.has(row.key))
+            issues.push(`Duplicate row key "${row.key}".`);
+        rowKeys.add(row.key);
+    }
+    const columnKeys = new Set();
+    for (const column of columnItems) {
+        if (columnKeys.has(column.key))
+            issues.push(`Duplicate column key "${column.key}".`);
+        columnKeys.add(column.key);
+    }
+    const size = def.size ?? 'regular';
+    const limit = gridColumnLimit(size);
+    if (columnKeys.size > limit) {
+        issues.push(`Grid has ${columnKeys.size} columns; at most ${limit} ${size} columns fit a 1280px laptop. Swap the axes or use two lists.`);
+    }
+    const seen = new Set();
+    for (const cell of def.cells) {
+        const key = cellKey(cell.rowKey, cell.columnKey);
+        if (seen.has(key)) {
+            issues.push(`Duplicate cell for row "${cell.rowKey}" and column "${cell.columnKey}".`);
+            continue;
+        }
+        seen.add(key);
+        if (!rowKeys.has(cell.rowKey)) {
+            issues.push(`Cell references undeclared row "${cell.rowKey}".`);
+            continue;
+        }
+        if (!columnKeys.has(cell.columnKey)) {
+            issues.push(`Cell references undeclared column "${cell.columnKey}".`);
+            continue;
+        }
+        const hasNode = cell.node !== undefined;
+        const hasReason = typeof cell.unavailableReason === 'string' && cell.unavailableReason.length > 0;
+        if (hasNode === hasReason) {
+            issues.push(`Cell for row "${cell.rowKey}" and column "${cell.columnKey}" must provide exactly one of node or unavailableReason.`);
+        }
+    }
+    for (const rowKey of rowKeys) {
+        for (const columnKey of columnKeys) {
+            if (!seen.has(cellKey(rowKey, columnKey))) {
+                issues.push(`Missing cell for row "${rowKey}" and column "${columnKey}".`);
+            }
+        }
+    }
+    return issues;
+}
+/** `states` minus items whose key is already a grid row or column. */
+export function remainingStates(states, comparison) {
+    if (!states)
+        return undefined;
+    if (!comparison)
+        return states;
+    const covered = new Set([...axisItems(comparison.rows).map((row) => row.key), ...axisItems(comparison.columns).map((column) => column.key)]);
+    const items = states.items.filter((item) => !covered.has(item.key));
+    return items.length > 0 ? { ...states, items } : undefined;
+}
+/** Specimen size for a one-axis slot: the section's explicit size, else wide for full-width
+ *  (itemsFill) slots, else regular. */
+export function slotSize(def, slot) {
+    return def.specimenSize ?? (slot.itemsFill ? 'wide' : 'regular');
+}
+function slotItems(slot) {
+    return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill || slot.itemsFill }));
+}
+/** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
+function previewWidths(requested, fallback) {
+    const widths = requested ?? fallback ?? [PREVIEW_MAX_WIDTH];
+    return widths === 'full' ? 'full' : widths.map((w) => Math.min(w, PREVIEW_MAX_WIDTH));
+}
+/** Grouped rows when at least one state names a variant through `group`. Every variant gets a row:
+ *  its grouped states, or the variant's own example when it has none. States without a matching
+ *  group are returned as leftovers for "Other configurations". */
+function groupStates(variants, states) {
+    const variantKeys = new Set(variants.items.map((v) => v.key));
+    if (!states.items.some((s) => s.group !== undefined && variantKeys.has(s.group)))
+        return undefined;
+    const fill = (item, slot) => item.fill || slot.itemsFill;
+    const groups = variants.items.map((variant) => {
+        const own = states.items.filter((s) => s.group === variant.key);
+        const items = own.length > 0
+            ? own.map((s) => ({ key: s.key, label: s.name, node: s.node, fill: fill(s, states) }))
+            : [{ key: variant.key, label: variant.name, node: variant.node, fill: fill(variant, variants) }];
+        return { key: variant.key, label: variant.name, items };
+    });
+    const rest = states.items.filter((s) => s.group === undefined || !variantKeys.has(s.group));
+    for (const s of rest) {
+        if (s.group !== undefined && globalThis.__DEV__) {
+            console.warn(`[Catalog] state "${s.key}" names group "${s.group}", which matches no variant key; it is shown under "Other configurations".`);
+        }
+    }
+    return { groups, leftovers: rest.length > 0 ? { ...states, items: rest } : undefined };
+}
+/** The visual blocks of one page, in reading order. Reference details are not included. A page
+ *  never shows an empty block next to a real one; with nothing documented at all it shows one
+ *  "No examples documented." block. */
+export function presentationBlocks(def, options = {}) {
+    if (def.tokenGallery) {
+        const title = def.fullWidthLabel ?? 'Tokens';
+        return [def.render ? { kind: 'preview', title, widths: 'full' } : { kind: 'empty', title, message: 'Nothing to preview.' }];
+    }
+    const hide = def.hide ?? {};
+    const blocks = [];
+    let states = hide.states ? undefined : remainingStates(def.states, def.comparison);
+    if (!hide.variants) {
+        const grouped = !def.comparison && def.variants && states ? groupStates(def.variants, states) : undefined;
+        if (def.comparison) {
+            blocks.push({
+                kind: 'grid',
+                title: `${def.comparison.rowLabel} × ${def.comparison.columnLabel}`,
+                size: def.comparison.size ?? def.specimenSize ?? 'regular',
+                comparison: def.comparison,
+            });
+        }
+        else if (grouped && def.variants) {
+            // Grouped rows place several cells beside a row header, so full-width (itemsFill) slots do
+            // not force 402px cells here; a cell's own `fill` still stretches its specimen.
+            blocks.push({ kind: 'grouped', title: 'Variant × configuration', size: def.specimenSize ?? 'regular', groups: grouped.groups });
+            states = grouped.leftovers;
+        }
+        else if (def.variants) {
+            blocks.push({ kind: 'list', title: 'Variants', size: slotSize(def, def.variants), items: slotItems(def.variants) });
+        }
+        else if (def.render) {
+            blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
+        }
+    }
+    if (states) {
+        const secondary = blocks.length > 0 && blocks[0].kind !== 'list';
+        blocks.push({
+            kind: 'list',
+            title: secondary ? 'Other configurations' : 'States / configurations',
+            size: slotSize(def, states),
+            items: slotItems(states),
+        });
+    }
+    if (blocks.length === 0 && !hide.variants && !hide.states) {
+        blocks.push({ kind: 'empty', title: 'Examples', message: 'No examples documented.' });
+    }
+    return blocks;
+}
+/** Side by side or stacked, for a page with exactly two blocks. Tries both and keeps the shorter;
+ *  stays stacked unless side by side saves at least PLACEMENT_MIN_SAVING. Only a list can move
+ *  beside a first block that hugs its content, and only when its cells keep their minimum width. */
+export function choosePlacement({ available, gap, first, second }) {
+    if (second.kind !== 'list' || !second.itemCount || !second.size)
+        return 'stacked';
+    const firstWidth = first.width ?? available;
+    if (firstWidth > available * 0.7)
+        return 'stacked';
+    const room = available - firstWidth - gap;
+    const minCell = second.size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : COLUMN_MIN_WIDTH[second.size];
+    if (room < minCell + 2)
+        return 'stacked';
+    const stackedRows = listGeometry(second.itemCount, available, second.size).rows;
+    const sideRows = listGeometry(second.itemCount, room, second.size).rows;
+    const rowHeight = second.height / Math.max(1, stackedRows);
+    const sideHeight = Math.max(first.height, sideRows * rowHeight);
+    const stackedHeight = first.height + gap + second.height;
+    return sideHeight <= stackedHeight - PLACEMENT_MIN_SAVING ? 'side' : 'stacked';
+}
+/** Props box columns: two, filled across first, for 4+ props when each column keeps its minimum. */
+export function propsColumns(count, width) {
+    return count >= 4 && width >= 2 * PROPS_MIN_COLUMN_WIDTH + PROPS_COLUMN_GAP ? 2 : 1;
+}

package/dist/native/catalog/tokens.js

@@ -0,0 +1,134 @@
+/**
+ * Catalog-only design tokens — the visual system of the catalog interface itself.
+ *
+ * Deliberately independent of any host app's design-system tokens (DS_SEMANTIC / DS_PALETTE /
+ * DS_SPACING): the catalog documents a design system, it does not consume one. Keeping its chrome
+ * on its own tokens means a change to the host app's tokens never restyles the catalog, and this
+ * folder can be copied into another app's repo unchanged.
+ *
+ * Values match the approved Studio Matrix references
+ * (docs/design/2026-10-06-catalog-studio-matrix-*.html), with one deliberate exception:
+ * `textMuted` stays #666666 because the references' #777777 fails WCAG AA contrast.
+ */
+export const CATALOG_TYPE = {
+    xs: 10,
+    tableHeader: 11,
+    sm: 12,
+    panelHeading: 13,
+    md: 14,
+    lg: 16,
+    brand: 17,
+    xl: 20,
+    '2xl': 24,
+    pageTitle: 28,
+    '3xl': 32,
+    '4xl': 40,
+};
+export const CATALOG_SPACE = {
+    xs: 4,
+    sm: 8,
+    md: 12,
+    lg: 16,
+    xl: 24,
+    '2xl': 32,
+    '3xl': 40,
+};
+export const CATALOG_RADIUS = {
+    sm: 8,
+    control: 9,
+    md: 12,
+    card: 14,
+};
+/** Exact chrome measurements from the approved references that are not spacing-scale steps. */
+export const CATALOG_LAYOUT = {
+    sidebarWidth: 264,
+    sidebarPaddingTop: 24,
+    sidebarPaddingX: 18,
+    mainPaddingTop: 28,
+    mainPaddingX: 32,
+    controlSize: 44,
+    focusRingWidth: 3,
+    navItemPaddingY: 8,
+    navItemPaddingX: 10,
+    panelPadding: 20,
+    factPaddingY: 9,
+    blockLabelGap: 14,
+    blockGap: 28,
+    /** Sidebar logo header (design `docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html`,
+     *  "C · Adaptive", approved 2026-10-08) — see `native/catalog/logoLayout.ts`. */
+    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;
+/** When to reach for each catalog-chrome type size. Rendered in the framework catalog's Type
+ *  Scale page. */
+export const CATALOG_TYPE_USE = {
+    xs: 'Sidebar group labels (uppercase); a prop\'s type annotation.',
+    tableHeader: 'Grid column headers and list cell captions (uppercase).',
+    sm: 'Breadcrumb, catalog caption, block labels, prop names and descriptions.',
+    panelHeading: 'Reference-panel headings: Guidance, Quick reference, Props (uppercase).',
+    md: 'Default body text: descriptions, nav links, grid row headers, quick-reference rows, the filter field.',
+    lg: 'Pager arrows and the filter field\'s clear (×) glyph.',
+    brand: 'The app name at the top of the sidebar.',
+    xl: 'Reserved — no current consumer.',
+    '2xl': 'Reserved — no current consumer.',
+    pageTitle: 'The selected page\'s title.',
+    '3xl': 'Reserved — no current consumer.',
+    '4xl': 'Reserved — no current consumer.',
+};
+/** When to reach for each catalog-chrome spacing step. Rendered in the framework catalog's
+ *  Spacing page. */
+export const CATALOG_SPACE_USE = {
+    xs: 'Tight gap — e.g. between a token\'s rendered value and its use-note.',
+    sm: 'Small gap — below the filter field; between a preview frame\'s label and its demo.',
+    md: 'Medium gap — between a card\'s contents; token-row divider padding.',
+    lg: 'Grid and list cell padding (16px); row gap in scale galleries.',
+    xl: 'Preview-card padding; gap between preview frames.',
+    '2xl': 'Gap between the reference panel\'s Guidance and Quick reference columns.',
+    '3xl': 'Bottom padding of the main column.',
+};
+export const CATALOG_COLOR = {
+    text: '#181818',
+    // #666666, not the references' #777777: #777 is 4.14–4.48:1 on this file's surfaces (WCAG AA
+    // needs 4.5:1); #666 is 5.3–5.7:1.
+    textMuted: '#666666',
+    /** Dividers inside grids, lists, props tables, token rows. */
+    border: '#e4e4e4',
+    /** Sidebar edge, reference card, filter field. */
+    borderHairline: '#dddddd',
+    /** Grid, list, and preview cards; pager buttons. */
+    borderStrong: '#d7d7d7',
+    /** Quick-reference row dividers. */
+    borderSubtle: '#eeeeee',
+    surface: '#ffffff',
+    /** Table headers, row headers, cell captions, filter field. */
+    surfaceMuted: '#fafafa',
+    /** Hover and pressed feedback on nav rows and buttons. */
+    surfacePressed: '#f1f3f8',
+    pageBackground: '#f6f6f4',
+    chip: '#eeeeee',
+    /** Active nav label, prop types, scale bars. */
+    accent: '#174dc6',
+    /** Active nav row background. */
+    accentSubtle: '#e9efff',
+    /** 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',
+};

package/dist/native/catalog/types.js

@@ -0,0 +1 @@
+export {};

package/native/catalog/CatalogShell.tsx

@@ -1,11 +1,16 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { AccessibilityInfo, Platform, ScrollView, StyleSheet, Text, View, findNodeHandle } from 'react-native';
+import { AccessibilityInfo, Platform, Pressable, ScrollView, StyleSheet, Text, View, findNodeHandle } from 'react-native';
 import type { ImageSourcePropType } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { CatalogSidebar } from './CatalogSidebar';
 import { SectionBlock } from './SectionBlock';
-import { groupLabelFor, hashForId, idFromHash, neighbors, orderedIds } from './catalogNavigation';
-import type { NavGroup, PreviewWidths, SectionDef } from './types';
+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';
+
+/** `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. */
+type ShellPageId<TId extends string> = TId | typeof UPDATE_PAGE_ID;
 
 function isWeb(): boolean {
   return Platform.OS === 'web' && typeof window !== 'undefined';
@@ -36,6 +41,62 @@ function resetMainScroll(scrollView: ScrollView | null): void {
   scrollView.scrollTo({ y: 0, animated: false });
 }
 
+/** The approved mockup's exact copy shape: `"⚠ DS Viewer <version> is available — includes
+ *  breaking changes · Migration guide · Review update"`, dismissible with an `×` labeled "Dismiss
+ *  for <version>". The release's own GitHub page stands in for a dedicated migration-guide URL,
+ *  which this plan's design text does not otherwise name.
+ *
+ *  Important finding, Fable correction pass: both links now carry a real `href` — `role="link"`
+ *  with only `onPress` (as `CatalogSidebar.tsx`'s own finding already documents) never activates on
+ *  Enter under react-native-web unless the element is a genuine anchor. `role="status"` (not
+ *  `"alert"`, the mockup's own choice) — a non-urgent notice should not interrupt assistive tech. */
+function MajorBanner({ update, onReviewUpdate, onDismiss }: { update: UpdateNotice; onReviewUpdate: () => void; onDismiss: () => void }) {
+  const releaseUrl = `https://github.com/krapwoo/design-system-viewer/releases/tag/v${update.latest}`;
+  return (
+    <View style={bannerStyles.banner} role="status">
+      <Text style={bannerStyles.text}>
+        {'⚠ '}
+        <Text style={bannerStyles.bold}>{`DS Viewer ${update.latest} is available`}</Text>
+        {' — includes breaking changes · '}
+        <Text
+          role="link"
+          style={bannerStyles.link}
+          {...({ href: releaseUrl, hrefAttrs: { target: '_blank', rel: 'noopener noreferrer' } } as Record<string, unknown>)}
+        >
+          Migration guide
+        </Text>
+        {' · '}
+        <Text role="link" style={bannerStyles.link} onPress={onReviewUpdate} {...({ href: hashForId(UPDATE_PAGE_ID) } as Record<string, unknown>)}>
+          Review update
+        </Text>
+      </Text>
+      <Pressable onPress={onDismiss} accessibilityRole="button" accessibilityLabel={`Dismiss for ${update.latest}`} style={bannerStyles.close}>
+        <Text style={bannerStyles.closeGlyph}>×</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const bannerStyles = StyleSheet.create({
+  banner: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: CATALOG_SPACE.md,
+    backgroundColor: CATALOG_COLOR.warningSubtle,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.warningBorder,
+    borderRadius: CATALOG_RADIUS.md,
+    paddingVertical: 10,
+    paddingHorizontal: 14,
+    marginBottom: 18,
+  },
+  text: { flex: 1, fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.warning },
+  bold: { fontWeight: '700' },
+  link: { color: CATALOG_COLOR.warning, fontWeight: '700', textDecorationLine: 'underline' },
+  close: { width: 32, height: 32, borderRadius: CATALOG_RADIUS.sm, alignItems: 'center', justifyContent: 'center' },
+  closeGlyph: { fontSize: 18, color: CATALOG_COLOR.warning },
+});
+
 /**
  * The whole catalog: a persistent, searchable sidebar plus ONE selected page. Selecting a page
  * replaces the main content (no long scrolling document, no scroll-spy). On web the page lives in
@@ -49,6 +110,8 @@ export function CatalogShell<TId extends string>({
   groups,
   sections,
   defaultPreviewWidths,
+  update,
+  updateEndpoint,
 }: {
   /** Short product/app name — the sidebar logo and the breadcrumb root. */
   appName: string;
@@ -62,11 +125,20 @@ export function CatalogShell<TId extends string>({
   /** Preview widths for component pages without their own `previewWidths`. Default: `[402]`
    *  (phone width). Pass 'full' for a catalog whose previews are not phone components. */
   defaultPreviewWidths?: PreviewWidths;
+  /** Design §5's update notice — `null`/`undefined` when no update is known (disabled, offline,
+   *  or already up to date; the viewer treats all three identically: no footer, no banner, no
+   *  update page content). */
+  update?: UpdateNotice | 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
+   *  **Update now** button when this is missing. */
+  updateEndpoint?: { baseUrl: string; secret: string };
 }) {
   const sectionsById = useMemo(() => new Map(sections.map((def) => [def.id, def])), [sections]);
   const order = useMemo(() => orderedIds(groups, new Set(sectionsById.keys())), [groups, sectionsById]);
-  const [active, setActive] = useState<TId | undefined>(() =>
-    isWeb() ? idFromHash(window.location.hash, order) : order[0],
+  const [active, setActive] = useState<ShellPageId<TId> | undefined>(() =>
+    isWeb() ? resolveActiveFromHash(window.location.hash, order) : order[0],
   );
 
   const scrollRef = useRef<ScrollView>(null);
@@ -76,7 +148,7 @@ export function CatalogShell<TId extends string>({
   const pushHistoryNext = useRef(false);
   const focusHeadingNext = useRef(false);
 
-  const select = useCallback((id: TId) => {
+  const select = useCallback((id: ShellPageId<TId>) => {
     if (id === activeRef.current) {
       focusElement(headingRef.current);
       return;
@@ -90,7 +162,7 @@ export function CatalogShell<TId extends string>({
   useEffect(() => {
     if (!isWeb()) return;
     const onHashChange = () => {
-      const id = idFromHash(window.location.hash, order);
+      const id = resolveActiveFromHash(window.location.hash, order);
       if (id === undefined) return;
       if (id !== activeRef.current) {
         focusHeadingNext.current = true;
@@ -123,18 +195,40 @@ export function CatalogShell<TId extends string>({
     if (focus) focusElement(headingRef.current);
   }, [active]);
 
-  const activeDef = active !== undefined ? sectionsById.get(active) : undefined;
+  const activeDef = active !== undefined && active !== UPDATE_PAGE_ID ? sectionsById.get(active) : undefined;
+
+  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;
+  // 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);
 
   return (
     <View style={styles.root}>
-      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} active={active} onPress={select} />
+      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} active={active} onPress={select} footer={footer} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
-        {activeDef ? (
+        {active === UPDATE_PAGE_ID ? (
+          <UpdatePanel update={update ?? null} endpoint={updateEndpoint} appName={appName} headingRef={headingRef} />
+        ) : activeDef ? (
           <SectionBlock
             key={activeDef.id}
             def={activeDef}
             groupLabel={groupLabelFor(groups, activeDef.id)}
             breadcrumbRoot={appName}
+            // 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}
             pager={{
               previousId: neighbors(order, activeDef.id).previous,
               nextId: neighbors(order, activeDef.id).next,