@appinternalleads/ui 0.2.0

package/src/widgets/output/renderers/list/ListCard.tsx

@@ -0,0 +1,576 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Icon, MotionView, Input, Pressable, Text } from '../../../../core';
+import { useDs } from '../../../../tokens';
+import { useSurface } from '../../../useSurface';
+import { OutputWidgetShell } from '../../OutputWidgetShell';
+import { outputList } from '../../tokens';
+import { staggerDelay, useEntrance, useEntranceTracker } from '../../motion';
+import type { OutputActionId } from '../../document';
+import {
+  createMockAdapter, isPristine, useQueryMachine,
+  type AdapterCapabilities, type DataAdapter, type QueryMachine, type QueryRecord, type QueryResponse, type QueryState,
+} from '../../queryEngine';
+import { KeyValueCard, type KeyValueField } from '../keyvalue';
+
+/**
+ * **`list` — the query-backed renderer.** `design_handoff_output_list` (`Widget list.dc.html` +
+ * README, which wins where they disagree). The first renderer whose content the payload does NOT
+ * contain: it composes a query and asks a `DataAdapter` for rows, owning the query *lifecycle*
+ * (`queryEngine.ts`); the builder owns the transport. See `docs/output-type-sheets/list.md`.
+ *
+ * **Three behaviours, each gated on an adapter capability:** B1 browse (the fallback render) ·
+ * B2 narrow — search/filter/sort · B3 select → detail, rendered as the existing `keyvalue`
+ * renderer (there is no detail component).
+ */
+
+export type ListColumn = {
+  key: string; label: string; searchable?: boolean;
+  /** README: columns carry per-column `filterable`. The filterable columns ARE the filter vocabulary —
+      user-configured filters and agent-added filters may only name these (N1). */
+  filterable?: boolean;
+  detail?: boolean;
+};
+/** How a column-derived filter is drawn. `chips` — a value per option; `letters` — the A–Z facet, i.e. the
+    first-letter rendering of a column (N5: one possible rendering, not a special feature). */
+export type ListFilterControl = 'chips' | 'letters';
+/** A user/builder-exposed filter. `column` must be a `filterable` column of `columns`. */
+export type ListFilterConfig = {
+  column: string; label?: string; control?: ListFilterControl;
+  /** Required for `chips`. Real values of the column. */
+  options?: { value: string; label: string }[];
+};
+/** What an agent may add during a run — the same primitive as a user filter, no more. */
+export type ListAgentFilter = { column: string; op?: string; value: string };
+export type ListSortOption = { column: string; dir: 'asc' | 'desc'; label: string };
+export type ListMockScenario = 'default' | 'empty' | 'error' | 'partial' | 'noSort' | 'noSearch' | 'noFilter' | 'noTotal' | 'failAfterFirst';
+
+/** Fixture/Storybook/Playground only: a deterministic in-memory source so a document with no host
+    adapter still renders through the REAL query engine. Never a backend. */
+export type ListMock = {
+  records: { id: string; data: Record<string, string> }[];
+  scenario?: ListMockScenario;
+  latencyMs?: number;
+};
+
+export type ListConfig = {
+  resource: string;
+  /** Plural noun for counters and empty states: "suppliers". */
+  noun: string;
+  titleColumn: string;
+  descriptionColumn?: string;
+  /** One trailing value only — "a second belongs in the detail". */
+  metaColumn?: string;
+  columns: ListColumn[];
+  filters?: ListFilterConfig[];
+  search?: { placeholder?: string };
+  sort?: { options: ListSortOption[] };
+  pageSize?: number;
+  /** README "Runtime state": `query` is "seeded from config, then user-mutated". */
+  initial?: { filters?: { column: string; value: string; op?: 'eq' | 'startsWith'; author?: 'user' | 'agent' }[]; search?: string };
+  /** README B3: `selection ≠ none` gates select → detail; otherwise rows are inert and unfocusable. */
+  selection?: 'none' | 'single';
+  /** Required by the README: empty states state a consequence, and no renderer can generate one. */
+  copy: { emptyLabel: string; consequenceLine: string };
+  mock?: ListMock;
+};
+
+export const LIST_LETTERS = Array.from({ length: 26 }, (_, i) => String.fromCharCode(65 + i));
+const NUMBER_WORDS = ['No', 'One', 'Two', 'Three', 'Four', 'Five'];
+
+export function mockAdapterFor(mock: ListMock): DataAdapter {
+  const s = mock.scenario ?? 'default';
+  return createMockAdapter({
+    records: s === 'empty' ? [] : mock.records,
+    latencyMs: mock.latencyMs ?? 0,
+    failWhen: s === 'error' ? () => true : s === 'failAfterFirst' ? (_d, i) => i >= 1 : undefined,
+    pendingCount: s === 'partial' ? 2 : undefined,
+    omitTotal: s === 'noTotal',
+    capabilities: {
+      serverSearch: s !== 'noSearch', serverFilter: s !== 'noFilter', serverSort: s !== 'noSort',
+    },
+  });
+}
+
+/**
+ * **N1 — structural validation of the data contract.** Every configured filter (and every seeded
+ * filter) must name a `filterable` column that exists in `columns`; the sort columns and the title
+ * column must exist too. Returns human-readable errors — `[]` means valid. This is what makes an
+ * invented field impossible to *configure*; `useQueryMachine` rejects one at *run* time.
+ */
+export function validateListConfig(config: ListConfig): string[] {
+  const errors: string[] = [];
+  const keys = new Set(config.columns.map(c => c.key));
+  const filterable = new Set(config.columns.filter(c => c.filterable).map(c => c.key));
+  if (!keys.has(config.titleColumn)) errors.push(`titleColumn "${config.titleColumn}" is not a column`);
+  for (const f of config.filters ?? []) {
+    if (!keys.has(f.column)) errors.push(`filter "${f.column}" is not a column of the data contract`);
+    else if (!filterable.has(f.column)) errors.push(`filter "${f.column}" names a column that is not filterable`);
+    if ((f.control ?? 'chips') === 'chips' && !(f.options && f.options.length)) errors.push(`filter "${f.column}" (chips) needs options`);
+  }
+  for (const f of config.initial?.filters ?? []) if (!filterable.has(f.column)) errors.push(`initial filter "${f.column}" is not a filterable column`);
+  for (const o of config.sort?.options ?? []) if (!keys.has(o.column)) errors.push(`sort column "${o.column}" is not a column`);
+  return errors;
+}
+
+/** The flat-text fallback (`_shared/SHELL.md` rule 1) — from the declared config, since rows are not in the payload. */
+export function listToText(config: ListConfig): string {
+  const parts = [`${config.noun} — a query-backed list`];
+  if (config.search) parts.push('search');
+  if (config.filters?.length) parts.push(`filter by ${config.filters.map(f => f.label ?? config.columns.find(c => c.key === f.column)?.label ?? f.column).join(', ')}`);
+  if (config.sort?.options.length) parts.push('sort');
+  return parts.join(' · ');
+}
+
+function Skeleton({ index }: { index: number }) {
+  const { colors } = useDs();
+  const surface = useSurface();
+  const k = outputList;
+  const w = k.skeleton.widths[index % k.skeleton.widths.length]!;
+  return (
+    <Box style={{ minHeight: k.row.minHeight[surface], paddingVertical: k.row.pad[surface], gap: 6, justifyContent: 'center' }}>
+      <Box style={{ width: `${w}%`, height: k.skeleton.barHeight, borderRadius: 6, backgroundColor: colors.hairlineStrong }} />
+      <Box style={{ width: `${w - 20}%`, height: k.skeleton.barHeight, borderRadius: 6, backgroundColor: colors.hairline }} />
+    </Box>
+  );
+}
+
+function Row({
+  record, index, seen, config, dim, onOpen, last,
+}: {
+  record: QueryRecord; index: number; seen: Set<string>; config: ListConfig; dim: boolean;
+  onOpen?: (id: string) => void; last: boolean;
+}) {
+  const { colors } = useDs();
+  const surface = useSurface();
+  const k = outputList;
+  const { opacity, translateY } = useEntrance(record.id, seen, { variant: 'rise', delayMs: staggerDelay(index, k.stagger) });
+  const d = record.data ?? {};
+  const title = d[config.titleColumn] ?? '';
+  const desc = config.descriptionColumn ? d[config.descriptionColumn] : undefined;
+  const meta = config.metaColumn ? d[config.metaColumn] : undefined;
+
+  const content = (
+    <Box
+      style={{
+        minHeight: k.row.minHeight[surface], paddingVertical: k.row.pad[surface],
+        borderBottomWidth: last ? 0 : 1, borderBottomColor: colors.hairline, gap: k.row.gap, opacity: dim ? 0.5 : 1,
+      }}>
+      <Box row={surface === 'web'} align={surface === 'web' ? 'center' : undefined} style={{ gap: 14 }}>
+        <Box flex={1} style={{ gap: k.row.gap, minWidth: 0 }}>
+          {/* The title never truncates — it is the row's identity. */}
+          <Text style={{ fontSize: surface === 'web' ? 15 : 14.5, lineHeight: 18.5, fontWeight: '600', color: colors.textPrimary }}>{title}</Text>
+          {desc ? <Text numberOfLines={2} color="textSecondary" style={{ fontSize: surface === 'web' ? 13 : 12.5, lineHeight: 17.5 }}>{desc}</Text> : null}
+        </Box>
+        {meta ? <Text mono color="textSecondary" numberOfLines={1} style={{ fontSize: 11.5, lineHeight: 11.5 }}>{meta}</Text> : null}
+      </Box>
+    </Box>
+  );
+
+  return (
+    <MotionView style={{ opacity, transform: [{ translateY }] }}>
+      {config.selection === 'single' && onOpen ? (
+        <Pressable
+          onPress={() => onOpen(record.id)}
+          aria-label={meta ? `${title}, ${meta}` : title}
+          style={{ width: '100%', alignItems: 'stretch' }}>
+          {content}
+        </Pressable>
+      ) : content}
+    </MotionView>
+  );
+}
+
+function Chip({ label, on, disabled, onPress }: { label: string; on: boolean; disabled?: boolean; onPress: () => void }) {
+  const { colors } = useDs();
+  return (
+    <Pressable
+      onPress={onPress} disabled={disabled} minHeight={44} radius="pill" bg={on ? 'accentFill' : 'surfaceSunken'}
+      aria-pressed={on} aria-label={label}
+      style={{ paddingHorizontal: 13, paddingVertical: 8 }}>
+      <Text style={{ fontSize: 12.5, lineHeight: 12.5, fontWeight: '600', color: on ? colors.accentOnFill : colors.textPrimary }}>{label}</Text>
+    </Pressable>
+  );
+}
+
+function ListBody({
+  machine, config, seen, onOpen,
+}: { machine: QueryMachine; config: ListConfig; seen: Set<string>; onOpen: (id: string) => void }) {
+  const { colors } = useDs();
+  const surface = useSurface();
+  const { state, capabilities } = machine;
+  const serverSearchInit = !!capabilities.serverSearch;
+  const k = outputList;
+  const size = config.pageSize ?? 20;
+
+  /* ── search: 300ms debounce; the spinner beats it (shown on the accepted keystroke) ── */
+  const [text, setText] = useState(state.query.search);
+  const [typing, setTyping] = useState(false);
+  const [clientQ, setClientQ] = useState(serverSearchInit ? '' : state.query.search);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+
+  const data = state.data;
+  const records = data?.records ?? [];
+  const pageOffset = state.query.page.strategy === 'offset' ? state.query.page.offset : 0;
+  /** "Client-side search renders only when the whole set is present (single page, no cursor)." */
+  const wholeSet = !!data && pageOffset === 0 && data.meta.nextCursor == null
+    && (data.meta.total === undefined ? records.length < size : data.meta.total <= size);
+  const serverSearch = !!capabilities.serverSearch;
+  const showSearch = !!config.search && (serverSearch || wholeSet);
+  const serverFilter = !!capabilities.serverFilter;
+  const serverSort = !!capabilities.serverSort;
+
+  const commit = (v: string) => { if (serverSearch) machine.setSearch(v); else setClientQ(v); };
+  const onText = (v: string) => {
+    setText(v);
+    setTyping(true);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => { setTyping(false); commit(v); }, k.searchDebounceMs);
+  };
+  const clearSearch = () => {
+    if (timer.current) clearTimeout(timer.current);
+    setText(''); setTyping(false); setClientQ(''); if (serverSearch) machine.setSearch('');
+  };
+
+  const shown: QueryRecord[] = clientQ
+    ? records.filter(r => Object.values(r.data ?? {}).some(v => v.toLowerCase().includes(clientQ.toLowerCase())))
+    : records;
+
+  const searchText = serverSearch ? state.query.search : clientQ;
+  const activeFilters = state.query.filters;
+  /* A filter is a filter: chips, the A–Z facet and an agent's addition are all the same
+     `{ column, op, value }`, so they are all worded, counted and cleared the same way. */
+  const columnLabel = (column: string) => config.filters?.find(f => f.column === column)?.label ?? config.columns.find(c => c.key === column)?.label ?? column;
+  const filterLabelFor = (f: { column: string; op: string; value: string }) =>
+    f.op === 'startsWith' ? `${columnLabel(f.column)} starting with ${f.value}`
+    : (config.filters?.find(x => x.column === f.column)?.options?.find(o => o.value === f.value)?.label ?? f.value);
+  const chipFilters = activeFilters;
+  const filterWords = chipFilters.map(filterLabelFor).join(', ');
+  const agentAdded = activeFilters.filter(f => f.author === 'agent');
+  const filterVocabulary = config.filters?.filter(f => config.columns.some(c => c.key === f.column && c.filterable)) ?? [];
+  const busy = (state.status === 'loading' && !!data) || state.flags.refreshing || typing;
+  const initialLoading = !data && (state.status === 'loading' || state.status === 'idle');
+  const sortIndex = config.sort ? config.sort.options.findIndex(o => o.column === state.query.sort?.column && o.dir === state.query.sort?.dir) : -1;
+
+  /* ── the counter line: the only aria-live region; reconciles with visible rows ── */
+  const total = data?.meta.total;
+  const baseline = state.baselineTotal;
+  let counter: string;
+  if (!data) counter = 'Loading';
+  else if (shown.length === 0) counter = `No matches${!isPristine(state.query) && baseline !== undefined ? ` · ${baseline} ${config.noun} total` : ''}`;
+  else if (total === undefined) counter = `Showing ${shown.length}`;
+  else {
+    const range = shown.length === total && pageOffset === 0 ? `${shown.length} of ${total}` : `${pageOffset + 1}–${pageOffset + shown.length} of ${total}`;
+    counter = chipFilters.length
+      ? `${range} in ${filterWords}${baseline !== undefined ? ` · ${baseline} ${config.noun} total` : ''}`
+      : `${range} ${config.noun}`;
+  }
+
+  /* ── empty / no-results are `ready` with zero rows, told apart by whether the query is pristine ── */
+  let empty: { title: string; body: string; actions: { label: string; onPress: () => void }[] } | null = null;
+  if (data && shown.length === 0 && state.status !== 'loading') {
+    if (isPristine(state.query) && !clientQ) {
+      empty = { title: config.copy.emptyLabel, body: config.copy.consequenceLine, actions: [] };
+    } else if (searchText) {
+      empty = {
+        title: `No match for '${searchText}'`,
+        body: `Clear the search to return to ${config.noun}${filterWords ? ` in ${filterWords}` : ''}.`,
+        actions: [{ label: 'Clear the search', onPress: clearSearch }],
+      };
+    } else {
+      const n = chipFilters.length;
+      const last = chipFilters[n - 1];
+      const lastLabel = last ? columnLabel(last.column).toLowerCase() : 'filter';
+      empty = {
+        title: `Nothing in ${filterWords || 'this view'}`,
+        body: `${NUMBER_WORDS[n] ?? n} ${n === 1 ? 'filter is' : 'filters are'} on. Clear ${lastLabel} to see all ${baseline ?? config.noun}.`,
+        actions: [
+          ...(last ? [{ label: `Clear ${lastLabel}`, onPress: () => machine.setFilter(last.column, null) }] : []),
+          { label: 'Clear all', onPress: () => { clearSearch(); machine.clearFilters(); } },
+        ],
+      };
+    }
+  }
+
+  const lettersKnown = wholeSet && isPristine(state.query);
+
+  const canPrev = pageOffset > 0 && state.query.page.strategy === 'offset';
+  const canNext = data
+    ? (state.query.page.strategy === 'cursor' ? data.meta.nextCursor != null
+      : total !== undefined ? pageOffset + size < total : records.length >= size)
+    : false;
+
+  const pad = k.body.pad[surface];
+  const rowsDim = state.status === 'error' && !!data;
+
+  return (
+    <Box style={{ padding: pad, gap: 12 }}>
+      {/* Control row — INSIDE the body under the hairline; the header carries identity only. */}
+      <Box row={surface === 'web'} align={surface === 'web' ? 'center' : undefined} style={{ gap: 10 }}>
+        {showSearch ? (
+          <Box flex={1} row align="center" style={{ gap: 8 }}>
+            <Box flex={1}>
+              <Input value={text} onChangeText={onText} placeholder={config.search?.placeholder ?? `Search ${config.noun}`} aria-label={config.search?.placeholder ?? `Search ${config.noun}`} />
+            </Box>
+            {busy ? <Icon name="refresh" size={18} color={colors.accentFill} spin label="Searching" /> : null}
+          </Box>
+        ) : (
+          <Box flex={1}>{busy ? <Icon name="refresh" size={18} color={colors.accentFill} spin label="Loading" /> : null}</Box>
+        )}
+        {config.sort && config.sort.options.length > 0 ? (
+          <Box style={{ gap: 3 }}>
+            <Pressable
+              disabled={!serverSort}
+              onPress={() => {
+                const opts = config.sort!.options;
+                const next = opts[(sortIndex + 1) % opts.length]!;
+                machine.setSort({ column: next.column, dir: next.dir });
+              }}
+              minHeight={44} radius="pill" bg={serverSort ? 'accentTint' : 'surfaceSunken'}
+              aria-label={serverSort ? `Sort: ${config.sort.options[Math.max(sortIndex, 0)]!.label}. Press to change` : 'Sorting is off for this source'}
+              style={{ paddingHorizontal: 14, paddingVertical: 10 }}>
+              <Text color={serverSort ? 'accentInk' : 'textSecondary'} style={{ fontSize: 13, lineHeight: 13, fontWeight: '600' }}>
+                {config.sort.options[Math.max(sortIndex, 0)]!.label} ▾
+              </Text>
+            </Pressable>
+            {!serverSort ? <Text color="textSecondary" style={{ fontSize: 11.5, lineHeight: 14 }}>Sorting is off for this source</Text> : null}
+          </Box>
+        ) : null}
+      </Box>
+
+      {filterVocabulary.map(f => {
+        const control = f.control ?? 'chips';
+        if (control === 'letters') {
+          /* N5 — A–Z is one rendering of a column-derived filter, not a hardcoded feature: any
+             filterable column can be drawn this way, and the letters come from THAT column. */
+          const present = new Set(records.map(r => (r.data?.[f.column] ?? '').charAt(0).toUpperCase()));
+          const noun = f.column === config.titleColumn ? `${config.noun.charAt(0).toUpperCase()}${config.noun.slice(1)}` : columnLabel(f.column);
+          return (
+            <Box key={f.column} style={{ gap: 4 }}>
+              <Box row wrap style={{ gap: k.rail.gap }} role="group" aria-label={`${noun} by first letter`}>
+                {LIST_LETTERS.map(L => {
+                  const on = activeFilters.some(a => a.column === f.column && a.op === 'startsWith' && a.value === L);
+                  const empty0 = lettersKnown && !present.has(L);
+                  return (
+                    <Pressable
+                      key={L} disabled={empty0 || !serverFilter} width={k.rail.boxWidth} height={k.rail.boxHeight}
+                      onPress={() => machine.setFilter(f.column, L, 'startsWith')}
+                      aria-pressed={on} aria-label={`${noun} starting with ${L}`}>
+                      <Box width={k.rail.pill} height={k.rail.pill} align="center" justify="center"
+                        style={{ borderRadius: k.rail.radius, backgroundColor: on ? colors.accentFill : 'transparent' }}>
+                        <Text style={{ fontSize: 12, lineHeight: 12, fontWeight: '600', color: on ? colors.accentOnFill : empty0 ? colors.hairlineStrong : colors.textPrimary }}>{L}</Text>
+                      </Box>
+                    </Pressable>
+                  );
+                })}
+              </Box>
+              {!serverFilter ? <Text color="textSecondary" style={{ fontSize: 11.5, lineHeight: 14 }}>Filtering is off for this source</Text> : null}
+            </Box>
+          );
+        }
+        return (
+          <Box key={f.column} style={{ gap: 4 }}>
+            <Box row wrap style={{ gap: 8 }}>
+              {(f.options ?? []).map(o => (
+                <Chip
+                  key={o.value} label={o.label} disabled={!serverFilter}
+                  on={activeFilters.some(a => a.column === f.column && a.op === 'eq' && a.value === o.value)}
+                  onPress={() => machine.setFilter(f.column, o.value)}
+                />
+              ))}
+            </Box>
+            {!serverFilter ? <Text color="textSecondary" style={{ fontSize: 11.5, lineHeight: 14 }}>Filtering is off for this source</Text> : null}
+          </Box>
+        );
+      })}
+
+      {agentAdded.length ? (
+        <Text color="textSecondary" style={{ fontSize: 11.5, lineHeight: 15 }}>
+          {`Filter added by the agent: ${agentAdded.map(f => `${columnLabel(f.column)} ${f.op === 'startsWith' ? 'starts with' : '='} ${f.value}`).join(', ')}`}
+        </Text>
+      ) : null}
+      {state.rejectedFilters.length ? (
+        <Text color="textSecondary" style={{ fontSize: 11.5, lineHeight: 15 }}>
+          {state.rejectedFilters.map(r => `Ignored ${r.author} filter on "${r.filter.column}" — ${r.reason === 'unknown-column' ? 'not an available column' : r.reason === 'filter-not-served' ? 'this source does not filter' : r.reason === 'bad-operator' ? 'unknown operator' : 'empty value'}`).join('. ')}
+        </Text>
+      ) : null}
+
+      {/* State 08 — an error never blanks rows already on screen. C7 (decided): the global alert pair —
+          `alertSoft` ground, `alertInk` text and 1px border — plus the literal word "Failed". */}
+      {state.status === 'error' ? (
+        <Box role="group" aria-label="Error"
+          style={{ backgroundColor: colors.alertSoft, borderWidth: 1, borderColor: colors.alertInk, borderRadius: 7, padding: 12, gap: 6 }}>
+          <Text mono uppercase style={{ fontSize: 10, fontWeight: '700', letterSpacing: 0.8, color: colors.alertInk }}>Failed</Text>
+          <Text style={{ fontSize: 13, lineHeight: 18, color: colors.textPrimary }}>
+            {data ? `${state.error?.message ?? 'The request failed'}. Showing earlier results.` : (state.error?.message ?? 'The request failed')}
+          </Text>
+          <Box row style={{ gap: 8 }}>
+            <Pressable onPress={machine.retry} minHeight={44} radius="pill" bg="surfaceSunken" aria-label="Retry"
+              style={{ paddingHorizontal: 14, paddingVertical: 8 }}>
+              <Text color="accentInk" style={{ fontSize: 12.5, lineHeight: 12.5, fontWeight: '600' }}>Retry</Text>
+            </Pressable>
+          </Box>
+        </Box>
+      ) : null}
+
+      {/* Rows. Reserved height: the skeleton is a real row's height exactly. */}
+      <Box role="list" style={{ paddingTop: surface === 'web' ? 5 : 4 }}>
+        {initialLoading
+          ? Array.from({ length: k.skeleton.rows }, (_, i) => <Skeleton key={i} index={i} />)
+          : empty
+          ? (
+            <Box style={{ paddingVertical: 18, gap: 6 }}>
+              <Text style={{ fontSize: 14.5, lineHeight: 19, fontWeight: '600' }}>{empty.title}</Text>
+              <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 17 }}>{empty.body}</Text>
+              {empty.actions.length ? (
+                <Box row wrap style={{ gap: 8, marginTop: 4 }}>
+                  {empty.actions.map(a => (
+                    <Pressable key={a.label} onPress={a.onPress} minHeight={44} radius="pill" bg="accentTint" aria-label={a.label}
+                      style={{ paddingHorizontal: 14, paddingVertical: 8 }}>
+                      <Text color="accentInk" style={{ fontSize: 12.5, lineHeight: 12.5, fontWeight: '600' }}>{a.label}</Text>
+                    </Pressable>
+                  ))}
+                </Box>
+              ) : null}
+            </Box>
+          )
+          : shown.map((r, i) =>
+              r.status === 'pending'
+                /* State 03 — in-flight rows shimmer beneath rows that have arrived. */
+                ? <Skeleton key={r.id} index={i} />
+                : <Row key={r.id} record={r} index={i} seen={seen} config={config} dim={rowsDim}
+                    onOpen={config.selection === 'single' ? onOpen : undefined} last={i === shown.length - 1} />)}
+      </Box>
+
+      {/* Footer: counter (aria-live, the ONLY live region) + pager, dimmed at the edge — never hidden. */}
+      <Box row={surface === 'web'} align={surface === 'web' ? 'center' : undefined} style={{ gap: 10 }}>
+        <Box flex={surface === 'web' ? 1 : undefined}>
+          <Text accessibilityLiveRegion="polite" color="textSecondary" align={surface === 'web' ? 'left' : 'center'} style={{ fontSize: surface === 'web' ? 12.5 : 12, lineHeight: 15 }}>
+            {counter}
+          </Text>
+        </Box>
+        <Box row style={{ gap: 8 }}>
+          <Pressable disabled={!canPrev} flex={surface === 'web' ? undefined : 1} minHeight={k.pager.height} radius="pill" bg="surfaceSunken"
+            onPress={() => machine.setPage(Math.max(0, pageOffset - size))} aria-label="Previous"
+            style={{ paddingHorizontal: 18, paddingVertical: 12 }}>
+            <Text style={{ fontSize: 13, lineHeight: 13, fontWeight: '600' }}>Previous</Text>
+          </Pressable>
+          <Pressable disabled={!canNext} flex={surface === 'web' ? undefined : 1} minHeight={k.pager.height} radius="pill" bg="surfaceSunken"
+            onPress={() => machine.setPage(state.query.page.strategy === 'cursor' && data?.meta.nextCursor ? Number(data.meta.nextCursor) : pageOffset + size)} aria-label="Next"
+            style={{ paddingHorizontal: 18, paddingVertical: 12 }}>
+            <Text style={{ fontSize: 13, lineHeight: 13, fontWeight: '600' }}>Next</Text>
+          </Pressable>
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+/** A read-only view of the REAL runtime — what `useQueryMachine` and the card currently hold. Reported
+    through `onState` so a host (the Playground's inspector) can show it without a second state model. */
+export type ListRuntimeSnapshot = {
+  status: QueryState['status'];
+  reason: QueryState['reason'];
+  flags: QueryState['flags'];
+  epoch: number;
+  query: QueryState['query'];
+  capabilities: AdapterCapabilities;
+  rowCount: number;
+  pendingCount: number;
+  meta: QueryResponse['meta'] | null;
+  baselineTotal: number | undefined;
+  error: QueryState['error'];
+  rejectedFilters: QueryState['rejectedFilters'];
+  selectedId: string | null;
+};
+
+export type ListCardProps = {
+  title: string;
+  chip?: string;
+  meta?: string;
+  config: ListConfig;
+  /** The host's transport. Absent → the deterministic `config.mock` source runs through the SAME engine. */
+  adapter?: DataAdapter;
+  /** Bump to ask for a refresh (README state 04): rows stay at full opacity, in place, while new ones land. */
+  refreshKey?: number;
+  /** Observability only — called whenever the runtime state or the selection changes. */
+  onState?: (snapshot: ListRuntimeSnapshot) => void;
+  /** N1 — filters the AGENT adds during a run. Same primitive as a user filter; only columns the data contract
+      declares filterable are accepted, anything else is rejected deterministically (see `rejectedFilters`). */
+  agentFilters?: ListAgentFilter[];
+  onSelect?: (id: string) => void;
+  onMenu?: () => void;
+  onAction?: (id: OutputActionId) => void;
+  testID?: string;
+};
+
+export function ListCard({ title, chip = 'list', meta, config, adapter, refreshKey, onState, agentFilters, onSelect, onMenu, onAction, testID }: ListCardProps) {
+  const fallback = useMemo(() => mockAdapterFor(config.mock ?? { records: [] }), [config.mock]);
+  const machine = useQueryMachine(
+    {
+      resource: config.resource,
+      searchColumns: config.columns.filter(c => c.searchable).map(c => c.key),
+      pageSize: config.pageSize ?? 20,
+      initial: config.initial
+        ? { filters: (config.initial.filters ?? []).map(f => ({ column: f.column, value: f.value, op: f.op ?? 'eq', author: f.author })), search: config.initial.search ?? '' }
+        : undefined,
+      filterableColumns: config.columns.filter(c => c.filterable).map(c => c.key),
+      initialSort: config.sort?.options[0] ? { column: config.sort.options[0].column, dir: config.sort.options[0].dir } : null,
+    },
+    adapter ?? fallback,
+  );
+  const seen = useEntranceTracker();
+  /* Controlled only when the prop is given; left undefined, agent-authored SEEDS (`initial.filters`) stand. */
+  const agentKey = agentFilters === undefined ? undefined : JSON.stringify(agentFilters);
+  const { setAgentFilters } = machine;
+  useEffect(() => { if (agentKey !== undefined) setAgentFilters(JSON.parse(agentKey) as ListAgentFilter[]); }, [agentKey, setAgentFilters]);
+  const firstRefresh = useRef(true);
+  const { refresh } = machine;
+  useEffect(() => {
+    if (firstRefresh.current) { firstRefresh.current = false; return; }
+    refresh();
+  }, [refreshKey, refresh]);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const { colors } = useDs();
+
+  const { state: qs, capabilities: caps } = machine;
+  useEffect(() => {
+    onState?.({
+      status: qs.status, reason: qs.reason, flags: qs.flags, epoch: qs.epoch, query: qs.query, capabilities: caps,
+      rowCount: qs.data?.records.filter(r => r.status === 'ready').length ?? 0,
+      pendingCount: qs.data?.records.filter(r => r.status === 'pending').length ?? 0,
+      meta: qs.data?.meta ?? null, baselineTotal: qs.baselineTotal, error: qs.error, rejectedFilters: qs.rejectedFilters, selectedId,
+    });
+  }, [qs, caps, selectedId, onState]);
+
+  const selected = selectedId ? machine.state.data?.records.find(r => r.id === selectedId) : undefined;
+
+  if (selected) {
+    /* B3 — no detail component. The record renders as `keyvalue`, and the chip says so: it names
+       the renderer, and lying about it breaks replay. */
+    const d = selected.data ?? {};
+    const fields: KeyValueField[] = config.columns
+      .filter(c => c.detail !== false)
+      .map(c => ({ id: c.key, label: c.label, value: d[c.key] ?? null }));
+    return (
+      <Box style={{ gap: 8 }}>
+        <Pressable onPress={() => setSelectedId(null)} minHeight={44} radius="pill" bg="surfaceSunken" alignSelf="flex-start" aria-label={`Back to ${config.noun}`}
+          style={{ paddingHorizontal: 14, paddingVertical: 8 }}>
+          <Text style={{ fontSize: 12.5, lineHeight: 12.5, fontWeight: '600', color: colors.textPrimary }}>‹ Back to {config.noun}</Text>
+        </Pressable>
+        <KeyValueCard title={d[config.titleColumn] ?? title} chip="keyvalue" fields={fields} onMenu={onMenu} onAction={onAction} testID={testID ? `${testID}-detail` : undefined} />
+      </Box>
+    );
+  }
+
+  const initial = !machine.state.data;
+  return (
+    <OutputWidgetShell kind={chip} title={title} meta={meta} onMenu={onMenu} onAction={onAction}
+      provisional={initial || machine.state.flags.partial} testID={testID}>
+      <ListBody
+        machine={machine} config={config} seen={seen}
+        onOpen={id => { setSelectedId(id); onSelect?.(id); }}
+      />
+    </OutputWidgetShell>
+  );
+}

package/src/widgets/output/renderers/list/index.ts

@@ -0,0 +1,5 @@
+export {
+  ListCard, listToText, mockAdapterFor, validateListConfig, LIST_LETTERS,
+  type ListCardProps, type ListRuntimeSnapshot, type ListConfig, type ListColumn, type ListFilterConfig, type ListSortOption,
+  type ListAgentFilter, type ListFilterControl, type ListMock, type ListMockScenario,
+} from './ListCard';