@krapwoo/ds-viewer 0.4.8 → 0.5.0

package/native/catalog/CatalogButton.tsx

@@ -0,0 +1,46 @@
+import React, { forwardRef, useState } from 'react';
+import { Pressable, StyleSheet, Text, type View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_TYPE } from './tokens';
+
+/** The viewer's own button, for catalog chrome and demo triggers (not an app component). Same look
+ *  as the update page's buttons. */
+export const CatalogButton = forwardRef<View, {
+  label: string;
+  onPress: () => void;
+  variant?: 'primary' | 'secondary';
+  accessibilityLabel?: string;
+}>(function CatalogButton({ label, onPress, variant = 'primary', accessibilityLabel }, ref) {
+  const [focused, setFocused] = useState(false);
+  const primary = variant === 'primary';
+  return (
+    <Pressable
+      ref={ref}
+      onPress={onPress}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel ?? label}
+      style={({ pressed }) => [
+        styles.base,
+        primary ? styles.primary : styles.secondary,
+        pressed && (primary ? styles.primaryPressed : styles.secondaryPressed),
+        focused && styles.focus,
+      ]}
+    >
+      <Text style={[styles.label, primary ? styles.labelPrimary : styles.labelSecondary]}>{label}</Text>
+    </Pressable>
+  );
+});
+
+const styles = StyleSheet.create({
+  base: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: 22, alignItems: 'center', justifyContent: 'center', alignSelf: 'center' },
+  primary: { backgroundColor: CATALOG_COLOR.text },
+  primaryPressed: { opacity: 0.85 },
+  secondary: { borderWidth: 1, borderColor: CATALOG_COLOR.borderStrong, backgroundColor: CATALOG_COLOR.surface },
+  secondaryPressed: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  // Same ring as the sidebar's: an outline, so focusing never shifts the layout.
+  focus: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing } as object,
+  label: { fontSize: CATALOG_TYPE.md, fontWeight: '700' },
+  labelPrimary: { color: '#ffffff' },
+  labelSecondary: { color: CATALOG_COLOR.text },
+});

package/native/catalog/OverlayDemo.tsx

@@ -0,0 +1,52 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { PhoneFrame } from './PhoneFrame';
+import { CatalogButton } from './CatalogButton';
+import { overlayTrigger } from './overlayDemoState';
+
+// Not `StyleSheet.absoluteFill`: React Native 0.81's types reject spreading it.
+const FILL = { position: 'absolute' as const, top: 0, right: 0, bottom: 0, left: 0 };
+
+/**
+ * A phone with a catalog button that opens an overlay: a sheet, a dialog, a toast. The overlay
+ * (`children`) fills the device above the centred trigger and gets `{ open, close }`; keep it
+ * mounted and drive its own `visible` from `open`, so its open and close animations play.
+ */
+export function OverlayDemo({
+  triggerLabel,
+  initiallyOpen = false,
+  keepTrigger = false,
+  children,
+}: {
+  triggerLabel: string | ((open: boolean) => string);
+  initiallyOpen?: boolean;
+  /** Keep the trigger visible while open, as a toggle. @default false */
+  keepTrigger?: boolean;
+  children: (state: { open: boolean; close: () => void }) => React.ReactNode;
+}) {
+  const [open, setOpen] = useState(initiallyOpen);
+  const trigger = overlayTrigger(open, { triggerLabel, keepTrigger });
+  // When the overlay closes, keyboard focus returns to the trigger instead of the page body.
+  const triggerRef = useRef<View>(null);
+  const wasOpen = useRef(open);
+  useEffect(() => {
+    if (wasOpen.current && !open) (triggerRef.current as unknown as { focus?: () => void } | null)?.focus?.();
+    wasOpen.current = open;
+  }, [open]);
+  return (
+    <PhoneFrame>
+      <View style={styles.screen}>
+        {trigger.visible && (
+          <CatalogButton ref={triggerRef} label={trigger.label} onPress={() => setOpen((value) => (keepTrigger ? !value : true))} />
+        )}
+        <View style={FILL} pointerEvents="box-none">
+          {children({ open, close: () => setOpen(false) })}
+        </View>
+      </View>
+    </PhoneFrame>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, alignSelf: 'stretch', alignItems: 'center', justifyContent: 'center' },
+});

package/native/catalog/PhoneScreen.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { ScrollView, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+
+/**
+ * A whole app screen inside a `PhoneFrame`: `header` pinned to the top, `footer` to the bottom,
+ * and the children in a body between them that scrolls instead of pushing the footer off the
+ * device. `floating` is a layer over the top of the screen for toasts; it adds no inset of its
+ * own, so the app positions its content. `bodyWrapper` lets the app put its own surface or
+ * context provider around the scrolling body; give its root `flex: 1, minHeight: 0`.
+ */
+export function PhoneScreen({
+  header,
+  footer,
+  floating,
+  bodyWrapper,
+  scroll = true,
+  contentContainerStyle,
+  children,
+}: {
+  header?: React.ReactNode;
+  footer?: React.ReactNode;
+  floating?: React.ReactNode;
+  bodyWrapper?: (body: React.ReactNode) => React.ReactNode;
+  /** Scroll the body (default), or lay it out to fit. */
+  scroll?: boolean;
+  contentContainerStyle?: StyleProp<ViewStyle>;
+  children?: React.ReactNode;
+}) {
+  const body = scroll ? (
+    <ScrollView style={styles.flex} contentContainerStyle={contentContainerStyle}>{children}</ScrollView>
+  ) : (
+    <View style={[styles.flex, contentContainerStyle]}>{children}</View>
+  );
+  return (
+    <View style={styles.screen}>
+      {header}
+      <View style={styles.flex}>{bodyWrapper ? bodyWrapper(body) : body}</View>
+      {footer}
+      {floating ? (
+        <View style={styles.floating} pointerEvents="box-none">{floating}</View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Fills the device; `minHeight: 0` lets a flex child shrink below its content on the web.
+  screen: { flex: 1, alignSelf: 'stretch', minHeight: 0 },
+  flex: { flex: 1, minHeight: 0 },
+  floating: { position: 'absolute', top: 0, left: 0, right: 0, zIndex: 20 },
+});

package/native/catalog/UpdatePanel.tsx

@@ -3,7 +3,7 @@ import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch,
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
 import {
-  autoCheckHelp, bumpLabel, checkedAgoLabel, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
+  autoCheckHelp, bumpLabel, checkedAgoLabel, resultNote, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
 } from './updatePanelState';
 import type { UpdateNotice, VersionStatus } from './types';
 
@@ -51,20 +51,6 @@ function FilesList({ files }: { files: UpdatePlanView['files'] }) {
   );
 }
 
-/** Same shape as `FilesList`, but with no right-hand reason column — the `success` phase's
- *  `status.files` carries plain paths, never a reason (Task 16 Step 2 table: a dedicated,
- *  smaller render here is simplest rather than over-generalizing `FilesList` for one caller). */
-function PlainFilesList({ files }: { files: string[] }) {
-  return (
-    <View style={styles.filesBox}>
-      {files.map((path, i) => (
-        <View key={path} style={[styles.fileRow, i > 0 && styles.fileRowBorder]}>
-          <Text style={styles.filePath}>{path}</Text>
-        </View>
-      ))}
-    </View>
-  );
-}
 
 const NOTE_BOX_VARIANT = {
   muted: { box: { backgroundColor: CATALOG_COLOR.surfaceMuted }, text: { color: CATALOG_COLOR.text } },
@@ -139,59 +125,66 @@ function Code({ children }: { children: string }) {
   return <Text style={styles.code}>{children}</Text>;
 }
 
-/** The `success` phase's content, shared between the `update === null` path (Errata 1c — the
- *  normal case, since `update.json` becomes `null` once latest equals current) and the defensive
- *  `update` still non-null path. Reads `status.latest`/`status.files`/`status.doctorSummary`,
- *  never `update.latest`/`plan.files` — `plan` is gone by the time this renders (the page has
- *  reloaded onto the new version). */
-function SuccessContent({ status }: { status: Extract<UpdateStatusView, { phase: 'success' }> }) {
+
+
+/**
+ * The result of the last update, as a note at the top of the update page (approved mockup
+ * 2026-10-11): a bold header, a description, one detail line, and a bottom-left button in the
+ * note's colour. The rest of the page stays usable below it.
+ */
+function ResultNoteBox({
+  status,
+  current,
+  latest,
+  busy,
+  onAction,
+}: {
+  status: Extract<UpdateStatusView, { phase: 'success' | 'failure' }>;
+  current: string;
+  latest?: string;
+  busy: boolean;
+  onAction: (kind: 'dismiss' | 'retry' | 'resume') => void;
+}) {
+  const [showLog, setShowLog] = useState(false);
+  const note = resultNote(status, current, latest);
+  const ok = note.tone === 'ok';
+  const tone = ok ? CATALOG_COLOR.success : CATALOG_COLOR.danger;
   return (
-    <>
-      <View style={styles.versionsRow}>
-        <Text style={styles.versionsText}>{status.latest}</Text>
-        <View style={[styles.pill, styles.pillSuccess]}>
-          <Text style={[styles.pillText, styles.pillTextSuccess]}>Updated</Text>
-        </View>
-      </View>
-      <NoteBox variant="ok">
-        <Text style={styles.noteBoxBold}>{`Updated to ${status.latest}.`}</Text>
-        {' Changes are not committed — review them in your editor.'}
-      </NoteBox>
-      <View style={styles.block}>
-        <Text style={styles.h3}>Changed</Text>
-        <PlainFilesList files={status.files} />
-      </View>
-      <View style={styles.block}>
-        <Text style={styles.h3}>Doctor</Text>
-        <Text style={styles.muted}>{status.doctorSummary}</Text>
+    <View style={[styles.resultNote, ok ? styles.resultNoteOk : styles.resultNoteErr]} role="status">
+      <Text style={[styles.resultTitle, { color: tone }]}>{note.title}</Text>
+      <Text style={[styles.resultDescription, { color: tone }]}>{note.description}</Text>
+      <Text style={[styles.resultDetail, { color: tone }]}>
+        {note.command ? (
+          <>
+            {'You can also run '}
+            <Code>{note.command}</Code>
+            {' in your terminal.'}
+          </>
+        ) : (
+          note.detail
+        )}
+      </Text>
+      <View style={styles.resultRow}>
+        <Pressable
+          onPress={() => onAction(note.action.kind)}
+          disabled={busy}
+          accessibilityRole="button"
+          accessibilityState={{ disabled: busy }}
+          style={({ pressed }) => [styles.resultButton, { backgroundColor: tone }, (pressed || busy) && styles.resultButtonPressed]}
+        >
+          <Text style={styles.resultButtonText}>{note.action.label}</Text>
+        </Pressable>
+        {note.hasLog && status.phase === 'failure' && (
+          <Pressable onPress={() => setShowLog((v) => !v)} accessibilityRole="button" accessibilityState={{ expanded: showLog }}>
+            <Text style={[styles.resultLink, { color: tone }]}>{showLog ? 'Hide log' : 'Show log'}</Text>
+          </Pressable>
+        )}
       </View>
-    </>
+      {showLog && status.phase === 'failure' && <LogBlock>{status.log}</LogBlock>}
+    </View>
   );
 }
 
-/** The `failure` phase's headline/body copy, keyed off which step failed — `runUpdate`/
- *  `performUpdate` each name their own distinct recovery command (Important finding, Fable
- *  correction pass: one hardcoded headline/body for every failure was wrong for two of the
- *  three). */
-function failureCopy(failedStep: string, current: string): { headline: string; body: React.ReactNode } {
-  if (/install/i.test(failedStep)) {
-    return {
-      headline: 'The update stopped while installing.',
-      body: <>Your files weren’t migrated. Recover with <Code>npx ds-viewer update</Code> in your terminal.</>,
-    };
-  }
-  if (/migrat/i.test(failedStep)) {
-    return {
-      headline: 'The update installed, but migrating failed.',
-      body: <>Recover with <Code>{`npx ds-viewer migrate --from ${current}`}</Code> in your terminal.</>,
-    };
-  }
-  return {
-    headline: 'The update installed and migrated, but doctor failed to run.',
-    body: <>Recover with <Code>npx ds-viewer doctor</Code> in your terminal.</>,
-  };
-}
-
 /**
  * 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
@@ -202,10 +195,13 @@ function VersionDetails({
   status,
   endpoint,
   onStatus,
+  onCheck,
 }: {
   status: VersionStatus;
   endpoint?: Endpoint;
   onStatus: (next: VersionStatus) => void;
+  /** Called as Check now starts (clears an update result note). */
+  onCheck?: () => void;
 }) {
   const [checking, setChecking] = useState(false);
   const [justChecked, setJustChecked] = useState(false);
@@ -217,6 +213,7 @@ function VersionDetails({
 
   const checkNow = async () => {
     if (!endpoint || checking) return;
+    onCheck?.();
     setChecking(true);
     setJustChecked(false);
     setLocalError(undefined);
@@ -395,7 +392,20 @@ export function UpdatePanel({
     });
   }, [fetchStatus, fetchPlan, update]);
 
-  const phase = resolvePanelPhase(status, planResult);
+  // A finished update (success or failure) shows as a note at the top; the page under it behaves
+  // as if idle, so Check now, the switch and a newer update all keep working.
+  const result = status.phase === 'success' || status.phase === 'failure' ? status : undefined;
+  const phase = resolvePanelPhase(result ? { phase: 'idle' } : status, planResult);
+  const [noteBusy, setNoteBusy] = useState(false);
+  const dismissResult = useCallback(async () => {
+    if (!endpoint || !isWeb()) return;
+    try {
+      const res = await authedFetch(endpoint, '/update/dismiss', { method: 'POST' });
+      if (res.ok) setStatus((await res.json()) as UpdateStatusView);
+    } catch {
+      // The note stays; the next status poll or reload settles it.
+    }
+  }, [endpoint]);
 
   // Polls `/update/status` at a plain interval while an update is in flight — design §5 never
   // asks for push/websocket progress, only "the panel shows progress."
@@ -463,14 +473,14 @@ export function UpdatePanel({
   if (!update) {
     // Errata 1c: no update known (disabled, offline, or genuinely up to date). `status` still
     // reflects a just-finished update read from the (surviving) endpoint across the reload.
-    content =
-      status.phase === 'success' ? (
-        <SuccessContent status={status} />
-      ) : versionStatus ? (
-        <VersionDetails status={versionStatus} endpoint={endpoint} onStatus={onVersionStatus ?? (() => {})} />
+    content = versionStatus ? (
+        <VersionDetails status={versionStatus} endpoint={endpoint} onStatus={onVersionStatus ?? (() => {})} onCheck={result ? dismissResult : undefined} />
       ) : (
         <NoteBox variant="ok">You’re already up to date.</NoteBox>
       );
+  } else if (result?.phase === 'failure') {
+    // The failure note's own button is the recovery; don't offer Update now twice.
+    content = <VersionsHeader current={update.current} latest={update.latest} breaking={update.breaking} releasedAt={update.releasedAt} />;
   } else if (phase === 'ready' && plan) {
     content = (
       <>
@@ -587,40 +597,7 @@ export function UpdatePanel({
         <Text style={styles.muted}>If it doesn’t come back, run <Code>npx ds-viewer dev</Code> in your terminal.</Text>
       </>
     );
-  } else if (phase === 'success' && status.phase === 'success') {
-    content = <SuccessContent status={status} />;
-  } else if (phase === 'failure' && status.phase === 'failure') {
-    const { headline, body } = failureCopy(status.failedStep, update.current);
-    const failedLabel = `${status.failedStep} failed`;
-    content = (
-      <>
-        <VersionsHeader current={update.current} latest={update.latest} breaking={update.breaking} releasedAt={update.releasedAt} />
-        <NoteBox variant="err">
-          <Text style={styles.noteBoxBold}>{headline}</Text>
-          {' '}
-          {body}
-        </NoteBox>
-        <Steps
-          steps={[
-            { label: `Downloaded ${update.latest}`, state: 'done' },
-            { label: failedLabel, state: 'todo' },
-          ]}
-          failedStep={failedLabel}
-        />
-        <LogBlock>{status.log}</LogBlock>
-        <View style={styles.actions}>
-          <Pressable
-            onPress={() => {
-              if (isWeb()) navigator.clipboard?.writeText(status.log);
-            }}
-            accessibilityRole="button"
-            style={styles.secondaryButton}
-          >
-            <Text style={styles.secondaryButtonText}>Copy log</Text>
-          </Pressable>
-        </View>
-      </>
-    );
+
   }
 
   return (
@@ -631,6 +608,28 @@ export function UpdatePanel({
       <View ref={headingRef} tabIndex={-1} role="heading" {...({ 'aria-level': 1 } as Record<string, unknown>)} style={styles.headingTarget}>
         <Text style={styles.title}>DS Viewer updates</Text>
       </View>
+      {result && (
+        <ResultNoteBox
+          status={result}
+          current={update?.current ?? versionStatus?.current ?? ''}
+          latest={update?.latest}
+          busy={noteBusy || starting}
+          onAction={async (kind) => {
+            if (!endpoint) return;
+            setNoteBusy(true);
+            try {
+              if (kind === 'dismiss') await dismissResult();
+              else if (kind === 'retry') await startUpdate();
+              else {
+                await authedFetch(endpoint, '/update/resume', { method: 'POST' });
+                await fetchStatus();
+              }
+            } finally {
+              setNoteBusy(false);
+            }
+          }}
+        />
+      )}
       {content}
     </View>
   );
@@ -638,6 +637,18 @@ export function UpdatePanel({
 
 const styles = StyleSheet.create({
   wrap: { maxWidth: CATALOG_LAYOUT.updateContentMaxWidth },
+  resultNote: { borderRadius: CATALOG_RADIUS.md, padding: 14, marginTop: 12, marginBottom: 18, gap: 4 },
+  resultNoteOk: { backgroundColor: CATALOG_COLOR.successSubtle },
+  resultNoteErr: { backgroundColor: CATALOG_COLOR.dangerSubtle, borderWidth: 1, borderColor: CATALOG_COLOR.dangerBorder },
+  resultTitle: { fontSize: CATALOG_TYPE.lg, fontWeight: '800' },
+  resultDescription: { fontSize: CATALOG_TYPE.panelHeading, lineHeight: 19 },
+  resultDetail: { fontSize: CATALOG_TYPE.sm, lineHeight: 18 },
+  resultRow: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md, marginTop: 8 },
+  // The catalog's smallest control size (the major banner's close button), filled in the note's colour.
+  resultButton: { height: 32, paddingHorizontal: 14, borderRadius: 16, alignItems: 'center', justifyContent: 'center' },
+  resultButtonPressed: { opacity: 0.8 },
+  resultButtonText: { color: '#ffffff', fontSize: CATALOG_TYPE.sm, fontWeight: '700' },
+  resultLink: { fontSize: CATALOG_TYPE.panelHeading, fontWeight: '700', textDecorationLine: 'underline' },
   crumb: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
   headingTarget: { marginTop: 4, marginBottom: 6 },
   title: { fontSize: CATALOG_TYPE.pageTitle, fontWeight: '800', color: CATALOG_COLOR.text },

package/native/catalog/index.ts

@@ -31,6 +31,9 @@ export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
 export { PhoneFrame } from './PhoneFrame';
+export { PhoneScreen } from './PhoneScreen';
+export { OverlayDemo } from './OverlayDemo';
+export { CatalogButton } from './CatalogButton';
 export { BoundedOverlayViewport } from './BoundedOverlayViewport';
 export type { BoundedOverlayViewportProps } from './BoundedOverlayViewport';
 export { comparisonCellItemKey } from './overlayViewport';

package/native/catalog/overlayDemoState.ts

@@ -0,0 +1,8 @@
+/** What `OverlayDemo` shows for a given open state. Kept free of runtime imports for `node --test`. */
+export function overlayTrigger(
+  open: boolean,
+  options: { triggerLabel: string | ((open: boolean) => string); keepTrigger?: boolean },
+): { visible: boolean; label: string } {
+  const label = typeof options.triggerLabel === 'function' ? options.triggerLabel(open) : options.triggerLabel;
+  return { visible: !open || Boolean(options.keepTrigger), label };
+}

package/native/catalog/updatePanelState.ts

@@ -32,7 +32,7 @@ export type UpdateStatusView =
   | { phase: 'updating'; steps: { label: string; state: 'done' | 'now' | 'todo' }[] }
   | { phase: 'restarting' }
   | { phase: 'success'; doctorSummary: string; files: string[]; latest: string }
-  | { phase: 'failure'; log: string; failedStep: string };
+  | { phase: 'failure'; log: string; failedStep: string; step?: 'install' | 'migrate' | 'doctor' | 'other' };
 
 export type UpdatePhase = 'checking' | 'ready' | 'dirty' | 'offline' | 'updating' | 'restarting' | 'success' | 'failure';
 
@@ -144,3 +144,70 @@ export function bumpLabel(current: string, latest: string, breaking: boolean): '
   if (!a || !b) return 'Minor';
   return a[0] === b[0] && a[1] === b[1] ? 'Patch' : 'Minor';
 }
+
+export interface ResultNote {
+  tone: 'ok' | 'err';
+  title: string;
+  description: string;
+  detail: string;
+  /** The terminal fallback, shown as code inside `detail` (failures only). */
+  command?: string;
+  /** At most two words. `dismiss` clears the note; `retry` runs the whole update again; `resume`
+   *  continues from the failed migrate or doctor step. */
+  action: { label: string; kind: 'dismiss' | 'retry' | 'resume' };
+  hasLog: boolean;
+}
+
+/** The note shown at the top of the update page after an update finished (approved mockup
+ *  2026-10-11): a header, a description, one detail line, and a bottom-left button. */
+export function resultNote(
+  status: Extract<UpdateStatusView, { phase: 'success' | 'failure' }>,
+  current: string,
+  latest?: string,
+): ResultNote {
+  if (status.phase === 'success') {
+    return {
+      tone: 'ok',
+      title: `Updated to ${status.latest}`,
+      description: "The changes aren't committed yet, so review them in your editor.",
+      // Doctor's own summary line continues after an em dash with component counts; the note keeps
+      // only the error and warning counts.
+      detail: `Changed: ${status.files.join(', ') || 'nothing'} · Doctor: ${status.doctorSummary.split(' — ')[0]}`,
+      action: { label: 'Got it', kind: 'dismiss' },
+      hasLog: false,
+    };
+  }
+  const failure = (title: string, description: string, command: string, action: ResultNote['action']): ResultNote => ({
+    tone: 'err', title, description, detail: `You can also run ${command} in your terminal.`, command, action, hasLog: true,
+  });
+  switch (status.step) {
+    case 'migrate':
+      return failure(
+        'The update installed, but migrating failed',
+        `Your package is on ${latest ?? 'the new version'}, but your files still match ${current}.`,
+        `npx ds-viewer migrate --from ${current}`,
+        { label: 'Finish migration', kind: 'resume' },
+      );
+    case 'doctor':
+      return failure(
+        'The update installed, but doctor failed to run',
+        'The update itself is done. Only the page check is missing.',
+        'npx ds-viewer doctor',
+        { label: 'Rerun doctor', kind: 'resume' },
+      );
+    case 'install':
+      return failure(
+        'The update stopped while installing',
+        'Nothing was migrated. Retrying starts again from the download.',
+        'npx ds-viewer update',
+        { label: 'Retry update', kind: 'retry' },
+      );
+    default:
+      return failure(
+        'The update stopped',
+        'Something unexpected went wrong. Retrying starts again from the download.',
+        'npx ds-viewer update',
+        { label: 'Retry update', kind: 'retry' },
+      );
+  }
+}

package/package.json

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

package/starter-kit/components/BottomSheet/BottomSheet.catalog.tsx

@@ -1,6 +1,6 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Button } from '../Button';
 import { Dock } from '../Dock';
 import { TopNav } from '../TopNav';
@@ -17,53 +17,43 @@ const styles = StyleSheet.create({
 });
 
 function BottomSheetDemo() {
-  const [visible, setVisible] = useState(false);
   return (
-    <PhoneFrame>
-      {!visible && <Button label="Open sheet" onPress={() => setVisible(true)} />}
-      <BottomSheet
-        visible={visible}
-        onDismiss={() => setVisible(false)}
-        header={
-          <TopNav
-            title="Trip details"
-            trailing={
-              <Button
-                variant="secondary"
-                size="small"
-                showIcon
-                showLabel={false}
-                iconName="clear"
-                accessibilityLabel="Close"
-                onPress={() => setVisible(false)}
-              />
-            }
-          />
-        }
-        footer={
-          <Dock>
-            <Button label="Confirm" onPress={() => setVisible(false)} />
-          </Dock>
-        }
-      >
-        <View style={styles.sheetContent}>
-          <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
-          <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
-          {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
-              `elevated` shadow turning on automatically once this content area actually scrolls. */}
-          <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
-          <Text style={styles.cardBody}>
-            This line runs express between 96 St and 168 St during rush hours, skipping local stops in
-            between. Weekend service runs local along the full route, with some stations closed for
-            planned maintenance.
-          </Text>
-          <Text style={styles.cardBody}>
-            Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
-            entrances before you travel.
-          </Text>
-        </View>
-      </BottomSheet>
-    </PhoneFrame>
+    <OverlayDemo triggerLabel="Open sheet">
+      {({ open, close }) => (
+        <BottomSheet
+          visible={open}
+          onDismiss={close}
+          header={
+            <TopNav
+              title="Trip details"
+              trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={close} />}
+            />
+          }
+          footer={
+            <Dock>
+              <Button label="Confirm" onPress={close} />
+            </Dock>
+          }
+        >
+          <View style={styles.sheetContent}>
+            <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
+            <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
+            {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
+                `elevated` shadow turning on automatically once this content area actually scrolls. */}
+            <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
+            <Text style={styles.cardBody}>
+              This line runs express between 96 St and 168 St during rush hours, skipping local stops in
+              between. Weekend service runs local along the full route, with some stations closed for
+              planned maintenance.
+            </Text>
+            <Text style={styles.cardBody}>
+              Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
+              entrances before you travel.
+            </Text>
+          </View>
+        </BottomSheet>
+      )}
+    </OverlayDemo>
   );
 }