@mohou/panel 1.0.20

package/src/storage/client.ts

@@ -0,0 +1,16 @@
+/** Storage summary the browse view can show. No route string lives here. */
+export interface StorageSummary {
+  readonly bytes: number
+  readonly tables: readonly string[]
+}
+
+export interface StorageTable {
+  readonly rows: readonly unknown[]
+}
+
+/** Storage reads. Absent means the control is hidden. */
+export interface StorageClient {
+  readStorage(appId: string): Promise<StorageSummary>
+  readTable(appId: string, table: string): Promise<StorageTable>
+  restoreStorage?(appId: string): Promise<void>
+}

package/src/storage/state.ts

@@ -0,0 +1,94 @@
+import type { StorageClient, StorageSummary, StorageTable } from './client.ts'
+
+export interface StorageState {
+  readonly summary?: StorageSummary
+  readonly failed: boolean
+  readonly table?: string
+  readonly rows?: StorageTable
+  readonly tableFailed: boolean
+  readonly noticeDismissed: boolean
+  readonly error?: string
+  readonly tableError?: string
+}
+
+export type StorageAction =
+  | { readonly type: 'loaded'; readonly summary: StorageSummary }
+  | { readonly type: 'failed'; readonly message?: string }
+  | { readonly type: 'select'; readonly table: string }
+  | { readonly type: 'table'; readonly rows: StorageTable }
+  | { readonly type: 'table-failed'; readonly message?: string }
+  | { readonly type: 'dismiss-notice' }
+
+/** Empty browse before the load. */
+export function storageState(): StorageState {
+  return { failed: false, tableFailed: false, noticeDismissed: false }
+}
+
+/**
+ * Storage browse transition. Read-only. A size notice does not block the app.
+ * @param state - current browse
+ * @param action - one client result
+ */
+export function reduceStorage(state: StorageState, action: StorageAction): StorageState {
+  switch (action.type) {
+    case 'loaded':
+      return { ...state, summary: action.summary, failed: false }
+    case 'failed':
+      return { ...omitTableError(omitError(state)), failed: true, ...action.message ? { error: action.message } : {} }
+    case 'select':
+      return { ...state, table: action.table, tableFailed: false }
+    case 'table':
+      return { ...omitTableError(state), rows: action.rows, tableFailed: false }
+    case 'table-failed':
+      return { ...omitTableError(state), tableFailed: true, ...action.message ? { tableError: action.message } : {} }
+    case 'dismiss-notice':
+      return { ...state, noticeDismissed: true }
+    default:
+      return action satisfies never
+  }
+}
+
+/** Load the file size and table names. A thrown error is not an empty database. */
+export async function loadStorage(
+  client: StorageClient,
+  appId: string,
+  dispatch: (action: StorageAction) => void,
+): Promise<void> {
+  try {
+    dispatch({ type: 'loaded', summary: await client.readStorage(appId) })
+  } catch (error) {
+    dispatch({ type: 'failed', ...thrown(error) })
+  }
+}
+
+/** Export one table. */
+export async function loadTable(
+  client: StorageClient,
+  appId: string,
+  table: string,
+  dispatch: (action: StorageAction) => void,
+): Promise<void> {
+  dispatch({ type: 'select', table })
+  try {
+    dispatch({ type: 'table', rows: await client.readTable(appId, table) })
+  } catch (error) {
+    dispatch({ type: 'table-failed', ...thrown(error) })
+  }
+}
+
+function thrown(error: unknown): { message: string } | Record<string, never> {
+  const message = error instanceof Error ? error.message : ''
+  return message.length > 0 ? { message } : {}
+}
+
+function omitError(state: StorageState): Omit<StorageState, 'error'> {
+  const { error: gone, ...rest } = state
+  void gone
+  return rest
+}
+
+function omitTableError(state: StorageState): Omit<StorageState, 'tableError'> {
+  const { tableError: gone, ...rest } = state
+  void gone
+  return rest
+}

package/src/storage/view.tsx

@@ -0,0 +1,190 @@
+import { useEffect, useReducer, useState, type ReactNode } from 'react'
+
+import { panelText, type PanelLabelMode, type PanelLocale } from '../labels.ts'
+import { Dialog } from '../ui/dialog.tsx'
+import type { StorageClient } from './client.ts'
+import { loadStorage, loadTable, reduceStorage, storageState } from './state.ts'
+
+/**
+ * Read-only storage browse. Hidden when Host exposes no storage client. No route string lives here.
+ * @param props - client, app, chrome locale, the pane close control, and an optional size notice
+ */
+export function PanelStorage(props: {
+  readonly client?: StorageClient
+  readonly appId: string
+  readonly locale: PanelLocale
+  readonly mode: PanelLabelMode
+  readonly onClose?: () => void
+  readonly notice?: string
+}): ReactNode {
+  const [state, dispatch] = useReducer(reduceStorage, undefined, storageState)
+  useEffect(() => {
+    if (props.client === undefined) return
+    void loadStorage(props.client, props.appId, dispatch)
+  }, [props.client, props.appId])
+  if (props.client === undefined) return null
+  const label = (key: string) => panelText(props.locale, key, props.mode)
+  const client = props.client
+  const rows = state.rows?.rows
+  const [raw, setRaw] = useState(false)
+  const [askRestore, setAskRestore] = useState(false)
+  return (
+    <section className="flex min-h-0 flex-1 flex-col bg-background text-foreground">
+      <header className="flex items-center justify-between gap-3 border-b bg-card px-4 py-3">
+        <div className="min-w-0">
+          <h3 className="text-[15px] font-semibold">{label('storage')}</h3>
+          {state.summary === undefined ? null : (
+            <p className="text-xs text-muted-foreground">{`${formatBytes(state.summary.bytes)} · ${state.summary.tables.length}`}</p>
+          )}
+        </div>
+        <div className="flex shrink-0 items-center gap-2">
+          {state.summary === undefined || client.restoreStorage === undefined ? null : (
+            <button type="button" className="h-8 rounded-lg border px-3 text-sm hover:bg-muted" onClick={() => setAskRestore(true)}>{label('restore-storage')}</button>
+          )}
+          <PaneClose label={label('pane-close')} onClose={props.onClose} />
+        </div>
+      </header>
+      <div className="min-h-0 flex-1 overflow-auto">
+        {props.notice !== undefined && !state.noticeDismissed ? (
+          <div className="mx-4 mt-4 flex items-start justify-between gap-3 rounded-xl border border-amber-500/40 bg-amber-500/10 px-3 py-2">
+            <p className="min-w-0 flex-1 text-sm">{props.notice}</p>
+            <button type="button" className="h-8 shrink-0 rounded-lg px-2 text-sm hover:bg-muted" onClick={() => dispatch({ type: 'dismiss-notice' })}>{label('dismiss')}</button>
+          </div>
+        ) : null}
+        {state.failed ? <p className="px-4 py-3 text-sm text-destructive">{state.error !== undefined && state.error.length > 0 ? state.error : label('storage-failed')}</p> : null}
+        <div className="grid min-h-0 grid-cols-1 min-[720px]:grid-cols-[14rem_minmax(0,1fr)]">
+          <ul className="flex flex-col gap-2 p-3">
+            {(state.summary?.tables ?? []).map(table => (
+              <li key={table}>
+                <button
+                  type="button"
+                  className="w-full rounded-xl border bg-card px-3 py-2 text-left font-mono text-sm data-[on=1]:border-primary"
+                  aria-pressed={state.table === table}
+                  data-on={state.table === table ? '1' : '0'}
+                  onClick={() => { void loadTable(client, props.appId, table, dispatch) }}
+                >{table}</button>
+              </li>
+            ))}
+          </ul>
+          <div className="min-w-0 p-4">
+            {state.tableFailed ? <p className="text-sm text-destructive">{state.tableError !== undefined && state.tableError.length > 0 ? state.tableError : label('storage-failed')}</p> : null}
+            {state.table === undefined ? null : (
+              <div>
+                <div className="mb-3 flex items-center justify-between gap-3">
+                  <h4 className="font-mono text-sm">{state.table}</h4>
+                  {rows === undefined || rows.length === 0 ? null : <ShapeSwitch raw={raw} label={label} onRaw={setRaw} />}
+                </div>
+                {rows === undefined ? null : rows.length === 0 ? <p className="text-sm text-muted-foreground">{label('storage-empty-rows')}</p> : raw ? (
+                  <pre className="overflow-auto rounded-xl border bg-card p-3 font-mono text-[12px] leading-5 whitespace-pre-wrap">{JSON.stringify(rows, null, 2)}</pre>
+                ) : (
+                  <div className="flex flex-col gap-3">
+                    {rows.map((row, index) => (
+                      <RecordCard key={recordKey(row, index)} row={row} />
+                    ))}
+                  </div>
+                )}
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+      {askRestore ? (
+        <Dialog width="sm" onClose={() => setAskRestore(false)}>
+          <p className="m-0 text-sm">{label('restore-storage-confirm')}</p>
+          <div className="mt-4 flex justify-end gap-2">
+            <button type="button" className="h-8 rounded-lg border px-3 text-sm" onClick={() => setAskRestore(false)}>{label('cancel')}</button>
+            <button type="button" className="h-8 rounded-lg bg-primary px-3 text-sm font-semibold text-primary-foreground" onClick={() => {
+              setAskRestore(false)
+              void client.restoreStorage?.(props.appId)
+            }}>{label('restore')}</button>
+          </div>
+        </Dialog>
+      ) : null}
+    </section>
+  )
+}
+
+function RecordCard(props: { readonly row: unknown }): ReactNode {
+  if (isRecord(props.row) && typeof props.row.key === 'string' && 'value' in props.row) {
+    return (
+      <article className="overflow-hidden rounded-xl border bg-card">
+        <header className="border-b px-3 py-2 font-mono text-xs">{props.row.key}</header>
+        <div className="p-3"><ValueView value={props.row.value} /></div>
+      </article>
+    )
+  }
+  return (
+    <pre className="overflow-auto rounded-xl border bg-card p-3 font-mono text-[12px] leading-5 whitespace-pre-wrap">{JSON.stringify(props.row, null, 2)}</pre>
+  )
+}
+
+function ValueView(props: { readonly value: unknown }): ReactNode {
+  const items = titledItems(props.value)
+  if (items !== undefined) {
+    return (
+      <ul className="flex flex-col gap-1.5">
+        {items.map(item => (
+          <li key={item.key} className="flex items-baseline justify-between gap-3 text-sm">
+            <span className={item.done ? 'text-muted-foreground line-through' : ''}>{item.title}</span>
+            {item.extra.length === 0 ? null : <span className="shrink-0 text-[11px] text-muted-foreground">{item.extra}</span>}
+          </li>
+        ))}
+      </ul>
+    )
+  }
+  if (props.value === null || typeof props.value === 'string' || typeof props.value === 'number' || typeof props.value === 'boolean') {
+    return <span className="text-sm">{props.value === null ? '—' : String(props.value)}</span>
+  }
+  return <pre className="overflow-auto font-mono text-[12px] leading-5 whitespace-pre-wrap">{JSON.stringify(props.value, null, 2)}</pre>
+}
+
+function ShapeSwitch(props: {
+  readonly raw: boolean
+  readonly label: (key: string) => string
+  readonly onRaw: (raw: boolean) => void
+}): ReactNode {
+  return (
+    <div className="flex gap-1 rounded-lg bg-muted p-1">
+      <button type="button" className="h-7 rounded-md px-2.5 text-xs data-[on=1]:bg-card data-[on=1]:font-semibold" data-on={props.raw ? '0' : '1'} aria-pressed={!props.raw} onClick={() => props.onRaw(false)}>{props.label('storage-preview')}</button>
+      <button type="button" className="h-7 rounded-md px-2.5 text-xs data-[on=1]:bg-card data-[on=1]:font-semibold" data-on={props.raw ? '1' : '0'} aria-pressed={props.raw} onClick={() => props.onRaw(true)}>{props.label('storage-raw')}</button>
+    </div>
+  )
+}
+
+function PaneClose(props: { readonly label: string; readonly onClose?: (() => void) | undefined }): ReactNode {
+  if (props.onClose === undefined) return null
+  return (
+    <button type="button" className="h-8 rounded-lg border bg-background px-3 text-sm hover:bg-muted" onClick={props.onClose}>{props.label}</button>
+  )
+}
+
+function titledItems(value: unknown): readonly { key: string; title: string; done: boolean; extra: string }[] | undefined {
+  if (!Array.isArray(value) || value.length === 0 || !value.every(isRecord)) return undefined
+  if (!value.every(item => typeof item.title === 'string')) return undefined
+  return value.map((item, index) => ({
+    key: typeof item.id === 'string' ? item.id : String(index),
+    title: item.title as string,
+    done: item.done === true,
+    extra: [typeof item.due === 'string' ? item.due : '', Array.isArray(item.tags) ? item.tags.filter(tag => typeof tag === 'string').join(' ') : ''].filter(part => part.length > 0).join(' · '),
+  }))
+}
+
+function recordKey(row: unknown, index: number): string {
+  if (isRecord(row) && typeof row.key === 'string') return row.key
+  return String(index)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  const kb = bytes / 1024
+  if (kb < 1024) return `${trim(kb)} KB`
+  return `${trim(kb / 1024)} MB`
+}
+
+function trim(value: number): string {
+  return value >= 10 ? String(Math.round(value)) : String(Math.round(value * 10) / 10)
+}

package/src/surface/state.ts

@@ -0,0 +1,72 @@
+export const panelSections = ['gallery', 'settings', 'history', 'storage'] as const
+
+export type PanelSection = (typeof panelSections)[number]
+
+export interface SurfaceState {
+  readonly section: PanelSection
+  /** Palette popover is independent of the main pane so settings stays open. */
+  readonly themeOpen: boolean
+  readonly focus?: { readonly appId: string; readonly title?: string }
+  readonly notice?: string
+  readonly unavailable?: string
+}
+
+export type SurfaceAction =
+  | { readonly type: 'section'; readonly section: PanelSection }
+  | { readonly type: 'toggle-theme' }
+  | { readonly type: 'close-theme' }
+  | { readonly type: 'show-app'; readonly appId: string; readonly title?: string }
+  | { readonly type: 'show-notice'; readonly appId: string; readonly table: string }
+  | { readonly type: 'unavailable'; readonly appId: string }
+
+/** The gallery section is first. */
+export function surfaceState(): SurfaceState {
+  return { section: 'gallery', themeOpen: false }
+}
+
+/**
+ * Which pane is visible, and which app the host asked to show.
+ * Theme popover does not replace settings / history / storage.
+ * @param state - current surface
+ * @param action - a section change or a host event applied by Shell
+ */
+export function reduceSurface(state: SurfaceState, action: SurfaceAction): SurfaceState {
+  switch (action.type) {
+    case 'section':
+      return {
+        ...state,
+        section: action.section,
+        // Opening another full pane dismisses the palette popover.
+        themeOpen: action.section === 'gallery' ? state.themeOpen : false,
+      }
+    case 'toggle-theme':
+      return { ...state, themeOpen: !state.themeOpen }
+    case 'close-theme':
+      return { ...state, themeOpen: false }
+    case 'show-app':
+      return {
+        ...withoutUnavailable(state),
+        section: 'gallery',
+        themeOpen: false,
+        focus: action.title === undefined ? { appId: action.appId } : { appId: action.appId, title: action.title },
+      }
+    case 'show-notice':
+      return {
+        ...state,
+        section: 'storage',
+        themeOpen: false,
+        notice: action.table,
+        focus: state.focus?.appId === action.appId ? state.focus : { appId: action.appId },
+      }
+    case 'unavailable':
+      return { ...state, section: 'gallery', themeOpen: false, unavailable: action.appId }
+    default:
+      return action satisfies never
+  }
+}
+
+function withoutUnavailable(state: SurfaceState): Omit<SurfaceState, 'unavailable'> {
+  const { unavailable: gone, ...rest } = state
+  void gone
+  return rest
+}

package/src/surface/view.tsx

@@ -0,0 +1,255 @@
+import { useEffect, useReducer, useState, type ReactNode } from 'react'
+import { Clock, Database } from 'lucide-react'
+
+import type { PanelClient } from '../gallery/client.ts'
+import { PanelGallery } from '../gallery/view.tsx'
+import { PanelHistory } from '../history/view.tsx'
+import type { HistoryClient } from '../history/client.ts'
+import { isPanelLocale, panelText, type PanelLabelMode, type PanelLocale } from '../labels.ts'
+import type { PanelPolicy, PanelSettingsClient, PanelUpdateCheck } from '../settings/client.ts'
+import { attemptCard, UpdateDialog, type UpdateCard } from '../settings/update-dialog.tsx'
+import { Tooltip } from '../ui/tooltip.tsx'
+import { PanelSettings } from '../settings/view.tsx'
+import type { StorageClient } from '../storage/client.ts'
+import { PanelStorage } from '../storage/view.tsx'
+import type { PaletteChip, ThemeClient } from '../theme/client.ts'
+import { ThemeMenu } from '../theme/menu.tsx'
+import { reduceSurface, surfaceState, type PanelSection } from './state.ts'
+
+/** Commands Shell can call. Same shape as the shell bridge. No route string lives here. */
+export interface PanelControls {
+  showApp(appId: string, title?: string): void
+  showNotice(appId: string, table: string): void
+  unavailable(appId: string): void
+  setWorkbench(appId: string): void
+}
+
+/**
+ * The panel as one surface. A missing client hides that section.
+ * @param props - injected clients and chrome locale
+ */
+export function PanelSurface(props: {
+  readonly client: PanelClient
+  readonly settings?: PanelSettingsClient
+  readonly history?: HistoryClient
+  readonly storage?: StorageClient
+  readonly theme?: ThemeClient
+  readonly appId?: string
+  readonly locale: PanelLocale
+  readonly mode: PanelLabelMode
+  readonly shell: 'standalone' | 'overlay'
+  readonly frame?: (appId: string) => ReactNode
+  readonly onClosePanel?: () => void
+  readonly versions?: string
+  readonly onControls?: (controls: PanelControls) => void
+}): ReactNode {
+  const [state, dispatch] = useReducer(reduceSurface, undefined, surfaceState)
+  const [palettes, setPalettes] = useState<readonly PaletteChip[]>([])
+  const [desk, setDesk] = useState<string | undefined>(undefined)
+  const [hostPolicy, setHostPolicy] = useState<PanelPolicy | undefined>(undefined)
+  const [chromeLocale, setChromeLocale] = useState<PanelLocale>(props.locale)
+  const [updateCard, setUpdateCard] = useState<UpdateCard | undefined>(undefined)
+  useEffect(() => {
+    const check = props.settings?.checkUpdate
+    if (check === undefined) return
+    void check().then((result) => {
+      const card = receiveUpdate(result, props.settings)
+      if (card !== undefined) setUpdateCard(card)
+    }, () => undefined)
+  }, [props.settings])
+  useEffect(() => {
+    setChromeLocale(props.locale)
+  }, [props.locale])
+  useEffect(() => {
+    props.onControls?.({
+      showApp: (appId, title) => dispatch({ type: 'show-app', appId, ...title === undefined ? {} : { title } }),
+      showNotice: (appId, table) => dispatch({ type: 'show-notice', appId, table }),
+      unavailable: appId => dispatch({ type: 'unavailable', appId }),
+      setWorkbench: appId => setDesk(appId === 'default' ? undefined : appId),
+    })
+  }, [props.onControls])
+  useEffect(() => {
+    if (props.settings === undefined) return
+    void props.settings.readPolicy().then(
+      policy => setDesk(policy.defaultWorkbenchId),
+      () => setDesk(undefined),
+    )
+  }, [props.settings])
+  useEffect(() => {
+    if (props.theme === undefined) return
+    void props.theme.listPalettes().then(
+      listed => setPalettes(listed.palettes),
+      () => setPalettes([]),
+    )
+  }, [props.theme])
+  const label = (key: string) => panelText(chromeLocale, key, props.mode)
+  useEffect(() => {
+    document.title = panelText(chromeLocale, 'product-name', props.mode)
+  }, [chromeLocale, props.mode])
+  const appId = state.focus?.appId ?? props.appId
+  const toggle = (section: PanelSection) => dispatch({ type: 'section', section: state.section === section ? 'gallery' : section })
+  const tool = (section: PanelSection, title: string, icon: ReactNode) => (
+    <Tooltip key={section} text={title}>
+      <button type="button" className="inline-flex size-8 items-center justify-center rounded-lg transition-colors duration-150 hover:bg-muted" aria-label={title} onClick={() => toggle(section)}>
+        <span className="sr-only">{title}</span>
+        {icon}
+      </button>
+    </Tooltip>
+  )
+  return (
+    <PanelGallery
+      client={props.client}
+      locale={chromeLocale}
+      mode={props.mode}
+      shell={props.shell}
+      {...desk === undefined ? {} : { defaultWorkbenchId: desk }}
+      {...props.settings === undefined ? {} : { onSetDefaultWorkbench: (id: string) => { void writeDefault(props.settings, id, setDesk) } }}
+      {...props.theme === undefined ? {} : {
+        themeOpen: state.themeOpen,
+        onToggleTheme: () => dispatch({ type: 'toggle-theme' }),
+      }}
+      {...props.settings === undefined ? {} : { onToggleSettings: () => toggle('settings') }}
+      theme={app => (
+        <ThemeMenu
+          locale={chromeLocale}
+          mode={props.mode}
+          {...props.theme === undefined ? {} : { theme: props.theme }}
+          {...props.settings === undefined ? {} : { settings: props.settings }}
+          {...app === undefined ? {} : { appId: app.id, appTitle: app.title }}
+          {...hostPolicy === undefined ? {} : { hostPolicy }}
+          onHostPolicy={setHostPolicy}
+        />
+      )}
+      tools={(
+        <>
+          {props.history !== undefined && appId !== undefined ? tool('history', label('history'), <Clock size={16} />) : null}
+          {props.storage !== undefined && appId !== undefined ? tool('storage', label('storage'), <Database size={16} />) : null}
+        </>
+      )}
+      overlay={chrome => (
+        <>
+          {state.unavailable === undefined ? null : <p className="px-6 py-2 text-sm text-destructive">{label('host-unreachable')}</p>}
+          {props.settings === undefined || state.section !== 'settings' ? null : (
+            <div className="mma-pane absolute inset-0 z-30 flex flex-col bg-background">
+              <PanelSettings
+                locale={chromeLocale}
+                mode={props.mode}
+                palettes={palettes}
+                cardStyle={chrome.cardStyle}
+                onCardStyle={chrome.setCard}
+                client={props.settings}
+                onPreviewLocale={setChromeLocale}
+                onUpdateOffer={(result) => {
+                  const card = receiveUpdate(result, props.settings)
+                  if (card !== undefined) setUpdateCard(card)
+                }}
+                onPolicy={(policy) => {
+                  setDesk(policy.defaultWorkbenchId)
+                  setHostPolicy(policy)
+                  if (isPanelLocale(policy.locale)) setChromeLocale(policy.locale)
+                }}
+                {...hostPolicy === undefined ? {} : { hostPolicy }}
+                onClose={() => dispatch({ type: 'section', section: 'gallery' })}
+                {...props.versions === undefined ? {} : { versions: props.versions }}
+              />
+            </div>
+          )}
+          {state.section === 'history' && appId !== undefined ? (
+            <div className="mma-pane absolute inset-0 z-20 flex min-h-0 flex-col bg-background" data-open="1">
+              <PanelHistory
+                key={appId}
+                appId={appId}
+                locale={chromeLocale}
+                mode={props.mode}
+                onClose={() => dispatch({ type: 'section', section: 'gallery' })}
+                {...props.history === undefined ? {} : { client: props.history }}
+              />
+            </div>
+          ) : null}
+          {state.section === 'storage' && appId !== undefined ? (
+            <div className="mma-pane absolute inset-0 z-20 flex min-h-0 flex-col bg-background" data-open="1">
+              <PanelStorage
+                key={appId}
+                appId={appId}
+                locale={chromeLocale}
+                mode={props.mode}
+                onClose={() => dispatch({ type: 'section', section: 'gallery' })}
+                {...props.storage === undefined ? {} : { client: props.storage }}
+                {...state.notice === undefined ? {} : { notice: label('storage-size-notice').replaceAll('{table}', state.notice) }}
+              />
+            </div>
+          ) : null}
+          {updateCard === undefined ? null : (
+            <UpdateDialog
+              locale={chromeLocale}
+              mode={props.mode}
+              card={updateCard}
+              onClose={() => {
+                if (updateCard.kind === 'offer') sessionStorage.setItem(updateDismissedKey, updateCard.latest)
+                setUpdateCard(undefined)
+              }}
+              onInstall={(version) => {
+                const install = props.settings?.installUpdate
+                if (install === undefined) return
+                setUpdateCard({ kind: 'installing', version, startedAt: Date.now() })
+                void install(version).then(() => undefined, (error: unknown) => {
+                  const detail = error instanceof Error ? error.message : ''
+                  setUpdateCard({
+                    kind: 'failed',
+                    reason: detail.length === 0 ? { text: label('update-install-failed') } : { text: detail },
+                    target: version,
+                  })
+                })
+              }}
+            />
+          )}
+        </>
+      )}
+      {...state.focus === undefined ? {} : { focus: state.focus }}
+      {...props.frame === undefined ? {} : { frame: props.frame }}
+      {...props.onClosePanel === undefined ? {} : { onClosePanel: props.onClosePanel }}
+    />
+  )
+}
+
+async function writeDefault(
+  settings: PanelSettingsClient | undefined,
+  id: string,
+  setDesk: (value: string | undefined) => void,
+): Promise<void> {
+  if (settings === undefined) return
+  const current = await settings.readPolicy()
+  const { defaultWorkbenchId: gone, ...rest } = current
+  void gone
+  const next: PanelPolicy = { ...rest, defaultWorkbenchId: id }
+  const written = await settings.writePolicy(next)
+  setDesk(written.policy.defaultWorkbenchId)
+}
+
+/** An offer the owner put away stays away for this window. */
+const updateDismissedKey = 'mini-app.update-dismissed'
+
+/**
+ * The card one check opens, if any. A recorded outcome outranks a fresh offer, and the host is told
+ * it was shown, so the next check does not open it again.
+ * @param check - the registry check, with the launcher's last attempt when one is on disk
+ * @param settings - the client the acknowledgement goes to
+ */
+function receiveUpdate(check: PanelUpdateCheck, settings: PanelSettingsClient | undefined): UpdateCard | undefined {
+  const attempt = check.lastAttempt
+  if (attempt === undefined) return offerCard(check)
+  const ack = settings?.ackUpdate
+  if (ack !== undefined) void ack(attempt.at).catch(() => undefined)
+  return attemptCard(attempt, check.current)
+}
+
+function offerCard(check: PanelUpdateCheck): UpdateCard | undefined {
+  if (!check.updateAvailable || check.installable !== true || check.latest === null) return undefined
+  if (sessionStorage.getItem(updateDismissedKey) === check.latest) return undefined
+  return {
+    kind: 'offer',
+    current: check.current,
+    latest: check.latest,
+    ...check.channel === undefined ? {} : { channel: check.channel },
+  }
+}

package/src/theme/client.ts

@@ -0,0 +1,34 @@
+/** One palette chip. Ignored files are not chips. */
+export interface PaletteChip {
+  readonly id: string
+  /** English (or sole) display name. */
+  readonly name: string
+  /** Chinese display name when the theme file provides one. */
+  readonly nameZh?: string
+  readonly swatch?: string
+  readonly style?: string
+  /** Shipped file, or a file from the themes directory. A user file that replaces a shipped id is custom. */
+  readonly origin?: 'builtin' | 'custom'
+}
+
+export interface IgnoredPalette {
+  readonly file: string
+  readonly reason: string
+}
+
+/** Pin the owner can set. Clear is `default`, not deletion of `theme.css`. */
+export type ThemePin =
+  | { readonly kind: 'default' }
+  | { readonly kind: 'follow-host' }
+  | { readonly kind: 'app-file' }
+  | { readonly kind: 'palette'; readonly id: string }
+
+/** Theme reads and pin writes. Absent means the picker is hidden. No route string lives here. */
+export interface ThemeClient {
+  listPalettes(): Promise<{ palettes: readonly PaletteChip[]; ignored: readonly IgnoredPalette[] }>
+  readPin?(appId: string): Promise<ThemePin>
+  setPin(appId: string, pin: ThemePin): Promise<ThemePin>
+  appFile?(appId: string): Promise<boolean>
+  /** Parsed `theme.css` for this app. Null when the file is missing or ignored. */
+  readAppTheme?(appId: string): Promise<{ name?: string; nameZh?: string; swatch?: string; style?: string } | null>
+}