@appinternalleads/ui 0.2.0

package/src/widgets/output/index.ts

@@ -0,0 +1,101 @@
+/**
+ * **Output widgets — the second widget family, `tasks/OUTPUT-WIDGETS.md`.**
+ *
+ * ```
+ * document contract (document.ts)
+ *       ↓
+ * renderer registry (registry.tsx)   ← catalogue (catalog.ts) says what's allowed to appear
+ *       ↓
+ * renderer (renderers/<name>/)
+ *       ↓
+ * shared shell (OutputWidgetShell.tsx) + motion (motion.ts)
+ *       ↓
+ * presentation
+ * ```
+ *
+ * From `design_handoff_output_widgets`, `design_handoff_output_blocks_stats`, and
+ * `design_handoff_output_blockers` (the implementation-depth type sheets — the shallow
+ * `design_handoff_output_variations` doc is not one). Shell (X0), motion (X0.5), `stats` (X2) and
+ * `keyvalue` (X1) are implemented; `delta`/`comparison` (X3) are design-complete with a fixture
+ * gap short of `implemented` — see `catalog.ts` for the authoritative per-renderer status and
+ * family (`display` vs. `decision`), and `docs/OUTPUT-COMPONENTS.md` for how to add the next one.
+ */
+/* Exported as `OutputKindChip`, not `KindChip` — `src/ds/Button.tsx` already owns that name for
+   an unrelated general-purpose kind pill; `export * from './output'` one level up (in
+   `src/widgets/index.ts`) would otherwise collide with it. */
+export { OutputWidgetShell, KindChip as OutputKindChip, type OutputWidgetShellProps } from './OutputWidgetShell';
+export {
+  outputShell, outputStats, outputRow, outputKeyValue, outputDelta, outputComparison,
+  outputSequence, outputArtifact, outputRanked, outputList,
+} from './tokens';
+export {
+  OUTPUT_MOTION, useEntranceTracker, useEntrance, staggerDelay,
+  type EntranceVariant, type StreamingContract,
+} from './motion';
+export {
+  StatsCard, statsToText, STATS_STREAMING,
+  type StatsCardProps, type StatsMetric, type StatsTrend, type StatsBehaviour, type StatsPhase, type TrendTone,
+} from './renderers/stats';
+export {
+  KeyValueCard, keyValueToText,
+  type KeyValueCardProps, type KeyValueField, type KeyValueSource, type KeyValueThresholds,
+  type KeyValueMount, type KeyValueBehaviour, type KeyValuePhase,
+} from './renderers/keyvalue';
+export {
+  DeltaCard, deltaToText, type DeltaCardProps, type DeltaRow, type DeltaTone, type DeltaPhase,
+} from './renderers/delta';
+export {
+  ComparisonCard, comparisonToText, type ComparisonCardProps, type ComparisonOption, type ComparisonPhase,
+} from './renderers/comparison';
+export {
+  SequenceCard, sequenceToText, type SequenceCardProps, type SequenceStep, type SequencePhase,
+} from './renderers/sequence';
+export {
+  ArtifactCard, artifactToText, type ArtifactCardProps, type ArtifactRow, type ArtifactPhase,
+} from './renderers/artifact';
+export {
+  TextCard, textToText, routeTreatment,
+  type TextCardProps, type TextPoint, type TextTreatment, type TextPhase,
+} from './renderers/text';
+export {
+  StatusCard, statusToText,
+  type StatusCardProps, type StatusOutcome, type StatusDensity, type StatusChip,
+} from './renderers/status';
+export {
+  RankedCard, rankedToText, type RankedCardProps, type RankedItem, type RankedPhase,
+} from './renderers/ranked';
+export {
+  DeckCard, deckToText,
+  type DeckCardProps, type DeckItem, type DeckDensity, type DeckDecision, type DeckPhase,
+} from './renderers/deck';
+export {
+  DiffCard, diffToText, type DiffCardProps, type DiffField, type DiffPhase,
+} from './renderers/diff';
+export {
+  FindingsCard, findingsToText,
+  type FindingsCardProps, type Finding, type FindingSeverity, type FindingsPhase,
+} from './renderers/findings';
+export {
+  ListCard, listToText, mockAdapterFor, validateListConfig, LIST_LETTERS,
+  type ListCardProps, type ListRuntimeSnapshot, type ListConfig, type ListColumn, type ListFilterConfig, type ListSortOption,
+  type ListMock, type ListMockScenario, type ListAgentFilter, type ListFilterControl,
+} from './renderers/list';
+export {
+  useQueryMachine, createMockAdapter, createEpochGuard, toAppError, isPristine, validateFilter, FILTER_OPS,
+  type AppError, type AsyncStatus, type QueryReason, type QueryFlags, type QueryFilter, type FilterOp, type FilterAuthor, type FilterCheck, type FilterRejection, type RejectedFilter, type QuerySort,
+  type QueryPage, type QueryDescriptor, type QueryRecord, type QueryResponse, type AdapterCapabilities,
+  type DataAdapter, type MockAdapterOptions, type QueryState, type QueryConfig, type QueryMachine,
+} from './queryEngine';
+export {
+  OUTPUT_ACTION_LABELS, STANDARD_OUTPUT_ACTIONS, OUTPUT_ACTIONS_HAIRLINE_AFTER, OUTPUT_DESTRUCTIVE_ACTION,
+  isOutputDocument,
+  type OutputDocument, type OutputWidgetKind, type OutputActionId, type OutputPayloadFor,
+  type StatsPayload, type KeyValuePayload, type DeltaPayload, type ComparisonPayload,
+  type SequencePayload, type ArtifactPayload, type TextPayload, type StatusPayload,
+  type RankedPayload, type DeckPayload, type DiffPayload, type FindingsPayload, type ListPayload,
+} from './document';
+export { OUTPUT_RENDERERS, OutputRenderer, OutputChildren, outputToText, type OutputHandlers, type OutputContainerChild } from './registry';
+export {
+  OUTPUT_CATALOGUE, getOutputComponents,
+  type OutputCatalogueEntry, type OutputImplementationStatus, type OutputComponentFamily,
+} from './catalog';

package/src/widgets/output/motion.ts

@@ -0,0 +1,122 @@
+import { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { useReduceMotion } from '../../core';
+import { OUTPUT_MOTION_TIMINGS as T } from '../../tokens';
+
+/**
+ * **The output-widget motion system — X0.5.** `tasks/OUTPUT-WIDGETS.md` X0.5, from
+ * `design_handoff_output_blocks_stats/README.md` Part 2.
+ *
+ * Twelve named motions. Only three have a runtime hook here — `rise`, `countUp`, `pop` — because
+ * they are the only ones any built widget can call yet (the shell's own entrance, and the two
+ * X2 `stats` needs). The rest are recorded as data so their values are traceable and a future
+ * renderer building `sheetUp`/`slideIn`/`grow`/`fill`/`caret`/`pulse` reads them from one place
+ * rather than re-transcribing the handoff. `shimmer` and `pulse` need no dedicated hook at all —
+ * `useLoop` in `core/Motion.tsx`, already built for the input widgets, is the generic 0→1 driver
+ * both of them are.
+ */
+
+/* Timings live in the token layer (`OUTPUT_MOTION_TIMINGS`); this file turns them into easing
+   functions and hooks. The values are this family's own handoff's, not the Blocks profiles'. */
+const EASE = Easing.bezier(...T.ease);
+
+export const OUTPUT_MOTION = {
+  rise: { duration: T.rise.duration, easing: EASE, distance: T.rise.distance, transform: 'translateY(9px) → none, opacity 0→1' },
+  countUp: { duration: T.countUp.duration, easing: EASE, distance: T.countUp.distance, transform: 'translateY(6px) → none, opacity 0→1' },
+  shimmer: { duration: T.shimmer.duration, easing: Easing.linear, transform: 'background-position sweep' },
+  pop: { duration: T.pop.duration, easing: EASE, transform: 'scale(.84) → 1.06 → 1' },
+  sheetUp: { duration: T.sheetUp.duration, easing: EASE, transform: 'translateY(100%) → none' },
+  slideIn: { duration: T.slideIn.duration, easing: EASE, transform: 'translateX(14px) → none' },
+  slideInBack: { duration: T.slideInBack.duration, easing: EASE, transform: 'translateX(-14px) → none' },
+  grow: { duration: T.grow.duration, easing: EASE, transform: 'max-height 0 → open, opacity 0→1' },
+  fill: { duration: T.fill.duration, easing: EASE, transform: 'scaleX(0 → 1), origin left' },
+  caret: { duration: T.caret.duration, easing: Easing.step0, transform: 'opacity 1/0' },
+  pulse: { duration: T.pulse.duration, easing: Easing.inOut(Easing.ease), transform: 'opacity 1 → .45 → 1' },
+  /** Documentation only. Never call `useLoop`/`useEntrance` with this — it never ships. */
+  countcycle: { duration: T.countcycle.duration, easing: EASE, transform: 'as countUp, looped' },
+} as const;
+
+/** **The rule.** Bind entrance to a stable item id, never to array index or render count. */
+export type EntranceVariant = 'rise' | 'countUp' | 'pop';
+
+/**
+ * One `Set` per list, shared by every item's `useEntrance` call, so a played entrance stays
+ * played across the list's re-renders — including the re-renders streaming causes on every
+ * partial payload.
+ */
+export function useEntranceTracker(): Set<string> {
+  return useRef(new Set<string>()).current;
+}
+
+/**
+ * **Stagger arithmetic** — 70ms between rows, 80ms between `stats` tiles, capped at 8 items.
+ * Past the cap every item shares one un-delayed `rise`, because a twenty-row list staggered at
+ * 70ms takes 1.6s to finish arriving, which reads as slow loading rather than as motion.
+ */
+export function staggerDelay(index: number, stepMs: number = T.staggerStep, cap: number = T.staggerCap): number {
+  return index < cap ? index * stepMs : 0;
+}
+
+/**
+ * Fires `rise` / `countUp` / `pop` once per item identity, on first appearance, never on
+ * re-render. `seen` is `useEntranceTracker()`'s `Set`, shared across the list.
+ *
+ * Reduced motion snaps straight to the settled value — the item still counts as "seen," so a
+ * later re-render (a streaming partial resolving the same id again) does not attempt to play it.
+ */
+export function useEntrance(
+  id: string,
+  seen: Set<string>,
+  opts: { variant: EntranceVariant; delayMs?: number; enabled?: boolean } = { variant: 'rise' },
+): { opacity: Animated.Value; translateY: Animated.Value; scale: Animated.Value } {
+  const { variant, delayMs = 0, enabled = true } = opts;
+  const reduced = useReduceMotion();
+  const distance = variant === 'countUp' ? OUTPUT_MOTION.countUp.distance : OUTPUT_MOTION.rise.distance;
+  const opacity = useRef(new Animated.Value(variant === 'pop' ? 1 : seen.has(id) ? 1 : 0)).current;
+  const translateY = useRef(new Animated.Value(seen.has(id) ? 0 : distance)).current;
+  const scale = useRef(new Animated.Value(seen.has(id) ? 1 : variant === 'pop' ? 0.84 : 1)).current;
+
+  useEffect(() => {
+    if (seen.has(id) || !enabled) {
+      opacity.setValue(1);
+      translateY.setValue(0);
+      scale.setValue(1);
+      return;
+    }
+    seen.add(id); // marked before the animation runs, so a mid-flight re-render never restarts it
+
+    if (reduced) {
+      opacity.setValue(1);
+      translateY.setValue(0);
+      scale.setValue(1);
+      return;
+    }
+
+    const spec = OUTPUT_MOTION[variant];
+    if (variant === 'pop') {
+      Animated.sequence([
+        Animated.timing(scale, { toValue: 1.06, duration: spec.duration * 0.6, delay: delayMs, easing: spec.easing, useNativeDriver: false }),
+        Animated.timing(scale, { toValue: 1, duration: spec.duration * 0.4, easing: spec.easing, useNativeDriver: false }),
+      ]).start();
+      return;
+    }
+    Animated.parallel([
+      Animated.timing(opacity, { toValue: 1, duration: spec.duration, delay: delayMs, easing: spec.easing, useNativeDriver: false }),
+      Animated.timing(translateY, { toValue: 0, duration: spec.duration, delay: delayMs, easing: spec.easing, useNativeDriver: false }),
+    ]).start();
+    /* Deliberately `[id]` alone: this must run exactly once per identity, not on every change to
+       `seen` (a shared, mutated-in-place Set), `delayMs`, or `enabled`. */
+  }, [id]);
+
+  return { opacity, translateY, scale };
+}
+
+/**
+ * **Two streaming numbers, declared before any renderer draws a partial payload.**
+ * `minimumViablePartial` is the smallest field set the renderer will draw at all;
+ * `reservedHeight` is fixed before the first partial arrives so content below never moves.
+ */
+export type StreamingContract = {
+  minimumViablePartial: string;
+  reservedHeight: number;
+};

package/src/widgets/output/queryEngine.ts

@@ -0,0 +1,7 @@
+/**
+ * **Moved.** The query runtime now lives in `src/runtime/query/` — it is shared infrastructure,
+ * not an output-family private (`docs/architecture/COMPONENT-FAMILIES.md` §3; the second consumer
+ * is `components/directory`). This file stays as a re-export so `list`'s imports, the output
+ * barrel and the package's public surface are untouched.
+ */
+export * from '../../runtime/query';

package/src/widgets/output/registry.tsx

@@ -0,0 +1,251 @@
+import type { ReactElement } from 'react';
+import { StatsCard, statsToText } from './renderers/stats';
+import { KeyValueCard, keyValueToText } from './renderers/keyvalue';
+import { DeltaCard, deltaToText } from './renderers/delta';
+import { ComparisonCard, comparisonToText } from './renderers/comparison';
+import { SequenceCard, sequenceToText } from './renderers/sequence';
+import { ArtifactCard, artifactToText } from './renderers/artifact';
+import { TextCard, textToText } from './renderers/text';
+import { StatusCard, statusToText } from './renderers/status';
+import { RankedCard, rankedToText } from './renderers/ranked';
+import { DeckCard, deckToText } from './renderers/deck';
+import { DiffCard, diffToText } from './renderers/diff';
+import { FindingsCard, findingsToText } from './renderers/findings';
+import { ListCard, listToText, type ListAgentFilter, type ListRuntimeSnapshot } from './renderers/list';
+import type { DataAdapter } from './queryEngine';
+import { outputKeyValue } from './tokens';
+import type { OutputActionId, OutputDocument, OutputWidgetKind } from './document';
+
+/**
+ * **The output renderer registry — Phase 6.**
+ *
+ * `output type → registry → OutputWidgetShell → specific renderer`. Adding the next renderer
+ * means one line here and one in `OutputWidgetKind` (`document.ts`) — CompPack, the Playground
+ * and Storybook all read through this file rather than switching on `widget` themselves.
+ *
+ * **`status` is the one exception** — it never mounts `OutputWidgetShell` (see
+ * `docs/output-type-sheets/status.md`), so `statusRenderer` below calls `StatusCard` directly
+ * rather than going through the shell the other twelve all share. Every other renderer function
+ * in this file follows the same `OutputWidgetShell`-wrapping shape; this is the single disclosed
+ * exception, not a precedent to extend casually.
+ */
+
+export type OutputHandlers = {
+  onSelect?: (id: string) => void;
+  onAction?: (id: OutputActionId) => void;
+  /** `keyvalue` — fires when a field's edit commits to a new value. Observational: `KeyValueCard`
+      owns `corrected` state itself (it must survive later partials unprompted), so a host does
+      not need to feed the value back in for the card to reflect it. */
+  onCorrect?: (fieldId: string, value: string) => void;
+  /** `deck` (write mode) — fires when the top card is kept or passed. */
+  onDecide?: (itemId: string, decision: 'kept' | 'passed') => void;
+  /** `artifact` — fires when "Open full document" is pressed. The renderer does not itself open
+      a viewer; the host owns that (`docs/output-type-sheets/artifact.md`). */
+  onOpen?: () => void;
+  /** `status` (density `'actions'`) — fires when a next-action chip is pressed. */
+  onChip?: (chipId: string) => void;
+  /** `list` — the host's transport. The component owns the query lifecycle; this owns the fetch.
+      Absent → the payload's deterministic `mock` source runs through the same engine. */
+  listAdapter?: DataAdapter;
+  /** `list` — bump to request a refresh. */
+  listRefreshKey?: number;
+  /** `list` — observe the real runtime state (inspector/devtools). */
+  listOnState?: (snapshot: ListRuntimeSnapshot) => void;
+  /** `list` — filters the AGENT adds during a run: same primitive as a user filter, columns of the data contract only. */
+  listAgentFilters?: ListAgentFilter[];
+};
+
+type OutputRendererFn<K extends OutputWidgetKind> = (doc: OutputDocument<K>, handlers: OutputHandlers) => ReactElement;
+
+const statsRenderer: OutputRendererFn<'stats'> = (doc, { onSelect, onAction }) => (
+  <StatsCard
+    title={doc.title}
+    chip={doc.chip}
+    meta={doc.meta}
+    metrics={doc.payload.metrics}
+    behaviour={doc.payload.behaviour}
+    heroId={doc.payload.heroId}
+    loadingCount={doc.payload.loadingCount}
+    selected={doc.payload.selected}
+    onSelect={onSelect}
+    phase={doc.phase}
+    onAction={onAction}
+    testID={doc.slug}
+  />
+);
+
+const keyValueRenderer: OutputRendererFn<'keyvalue'> = (doc, { onCorrect, onAction }) => (
+  <KeyValueCard
+    title={doc.title}
+    chip={doc.chip}
+    meta={doc.meta}
+    fields={doc.payload.fields}
+    mount={doc.payload.mount}
+    thresholds={doc.payload.thresholds}
+    phase={doc.phase}
+    onCorrect={onCorrect}
+    onAction={onAction}
+    testID={doc.slug}
+  />
+);
+
+const deltaRenderer: OutputRendererFn<'delta'> = (doc, { onAction }) => (
+  <DeltaCard
+    title={doc.title} chip={doc.chip} meta={doc.meta} rows={doc.payload.rows}
+    phase={doc.phase} loadingCount={doc.payload.loadingCount}
+    onAction={onAction} testID={doc.slug}
+  />
+);
+
+const comparisonRenderer: OutputRendererFn<'comparison'> = (doc, { onSelect, onAction }) => (
+  <ComparisonCard
+    title={doc.title}
+    chip={doc.chip}
+    meta={doc.meta}
+    options={doc.payload.options}
+    mount={doc.mount}
+    selected={doc.payload.selected}
+    phase={doc.phase}
+    onSelect={onSelect}
+    onAction={onAction}
+    testID={doc.slug}
+  />
+);
+
+const sequenceRenderer: OutputRendererFn<'sequence'> = (doc, { onAction }) => (
+  <SequenceCard
+    title={doc.title} chip={doc.chip} meta={doc.meta}
+    steps={doc.payload.steps} activeIndex={doc.payload.activeIndex}
+    phase={doc.phase} onAction={onAction} testID={doc.slug}
+  />
+);
+
+const artifactRenderer: OutputRendererFn<'artifact'> = (doc, { onOpen, onAction }) => (
+  <ArtifactCard
+    title={doc.title} chip={doc.chip} meta={doc.meta} rows={doc.payload.rows}
+    phase={doc.phase === 'loading' ? 'loading' : 'settled'}
+    onOpen={onOpen} onAction={onAction} testID={doc.slug}
+  />
+);
+
+const textRenderer: OutputRendererFn<'text'> = (doc, { onAction }) => (
+  <TextCard
+    title={doc.title} chip={doc.chip} meta={doc.meta}
+    points={doc.payload.points} treatment={doc.payload.treatment} attribution={doc.payload.attribution}
+    phase={doc.phase === 'loading' ? 'loading' : 'settled'}
+    onAction={onAction} testID={doc.slug}
+  />
+);
+
+const statusRenderer: OutputRendererFn<'status'> = (doc, { onChip }) => (
+  <StatusCard
+    outcome={doc.payload.outcome} action={doc.payload.action} density={doc.payload.density}
+    meta={doc.payload.meta} chips={doc.payload.chips} onChip={onChip} testID={doc.slug}
+  />
+);
+
+const rankedRenderer: OutputRendererFn<'ranked'> = (doc, { onAction }) => (
+  <RankedCard
+    title={doc.title} chip={doc.chip} meta={doc.meta} items={doc.payload.items}
+    mount={doc.mount} loadingCount={doc.payload.loadingCount}
+    phase={doc.phase} onAction={onAction} testID={doc.slug}
+  />
+);
+
+const deckRenderer: OutputRendererFn<'deck'> = (doc, { onDecide, onAction }) => (
+  <DeckCard
+    title={doc.title} chip={doc.chip} meta={doc.meta} items={doc.payload.items}
+    decided={doc.payload.decided ?? {}} density={doc.payload.density} mount={doc.mount}
+    phase={doc.phase === 'loading' ? 'loading' : 'settled'}
+    onDecide={onDecide} onAction={onAction} testID={doc.slug}
+  />
+);
+
+const diffRenderer: OutputRendererFn<'diff'> = (doc, { onAction }) => (
+  <DiffCard
+    title={doc.title} chip={doc.chip} meta={doc.meta}
+    fields={doc.payload.fields} before={doc.payload.before} after={doc.payload.after}
+    phase={doc.phase === 'loading' ? 'loading' : 'settled'}
+    onAction={onAction} testID={doc.slug}
+  />
+);
+
+const findingsRenderer: OutputRendererFn<'findings'> = (doc, { onAction }) => (
+  <FindingsCard
+    title={doc.title} chip={doc.chip} meta={doc.meta} findings={doc.payload.findings}
+    phase={doc.phase === 'loading' ? 'loading' : 'settled'}
+    onAction={onAction} testID={doc.slug}
+  />
+);
+
+const listRenderer: OutputRendererFn<'list'> = (doc, { onSelect, onAction, listAdapter, listRefreshKey, listOnState, listAgentFilters }) => (
+  <ListCard
+    title={doc.title} chip={doc.chip} meta={doc.meta} config={doc.payload}
+    adapter={listAdapter} refreshKey={listRefreshKey} onState={listOnState} agentFilters={listAgentFilters} onSelect={onSelect} onAction={onAction} testID={doc.slug}
+  />
+);
+
+export const OUTPUT_RENDERERS: { [K in OutputWidgetKind]: OutputRendererFn<K> } = {
+  stats: statsRenderer,
+  keyvalue: keyValueRenderer,
+  delta: deltaRenderer,
+  comparison: comparisonRenderer,
+  sequence: sequenceRenderer,
+  artifact: artifactRenderer,
+  text: textRenderer,
+  status: statusRenderer,
+  ranked: rankedRenderer,
+  deck: deckRenderer,
+  diff: diffRenderer,
+  findings: findingsRenderer,
+  list: listRenderer,
+};
+
+/**
+ * **X5 — the container child contract, DECIDED 2026-09-18 (option A: shell + payload).**
+ *
+ * When a container holds children, each child receives the full widget shell/context AND its own
+ * widget payload: a child is a complete `output/1` document, rendered exactly as it would be on
+ * its own — own kind chip, own title, own ⋮ menu, own payload, own runtime (a `list` child keeps
+ * its own query lifecycle). There is no presentation-only child and no payload drawn into someone
+ * else's shell. `collection`, `tabbed`, `fallback` and any composition of `list` follow this one
+ * model; the container decides arrangement and which child shows, never how a child is drawn.
+ */
+export type OutputContainerChild = OutputDocument;
+
+/** The whole contract, executable: every child goes through the same registry dispatch a
+    standalone document does. Containers are built on this, not on a second render path. */
+export function OutputChildren({ documents, ...handlers }: { documents: OutputContainerChild[] } & OutputHandlers): ReactElement {
+  return <>{documents.map(child => <OutputRenderer key={child.slug} document={child} {...handlers} />)}</>;
+}
+
+export function OutputRenderer({
+  document, onSelect, onAction, onCorrect, onDecide, onOpen, onChip, listAdapter, listRefreshKey, listOnState, listAgentFilters,
+}: { document: OutputDocument } & OutputHandlers): ReactElement {
+  const render = OUTPUT_RENDERERS[document.widget] as OutputRendererFn<OutputWidgetKind>;
+  return render(document, { onSelect, onAction, onCorrect, onDecide, onOpen, onChip, listAdapter, listRefreshKey, listOnState, listAgentFilters });
+}
+
+/**
+ * **The flat-text fallback, dispatched by widget — `_shared/SHELL.md` rule 1: "not optional."**
+ * One function CompPack and the Playground both call instead of special-casing `stats` (which is
+ * what the first pass did, and is exactly the "every widget has one" rule being half-followed).
+ */
+export function outputToText(document: OutputDocument): string {
+  switch (document.widget) {
+    case 'stats': return statsToText(document.payload.metrics);
+    case 'keyvalue': return keyValueToText(document.payload.fields, { ...outputKeyValue.thresholds, ...document.payload.thresholds });
+    case 'delta': return deltaToText(document.payload.rows);
+    case 'comparison': return comparisonToText(document.payload.options);
+    case 'sequence': return sequenceToText(document.payload.steps, document.payload.activeIndex);
+    case 'artifact': return artifactToText(document.payload.rows);
+    case 'text': return textToText(document.payload.points);
+    case 'status': return statusToText(document.payload.outcome, document.payload.action, document.payload.meta);
+    case 'ranked': return rankedToText(document.payload.items);
+    case 'deck': return deckToText(document.payload.items, document.payload.decided ?? {});
+    case 'diff': return diffToText(document.payload.fields, document.payload.before, document.payload.after);
+    case 'findings': return findingsToText(document.payload.findings);
+    case 'list': return listToText(document.payload);
+    default: return '';
+  }
+}

package/src/widgets/output/renderers/artifact/ArtifactCard.tsx

@@ -0,0 +1,143 @@
+import { Box, MotionView, Pressable, Text } from '../../../../core';
+import { useDs } from '../../../../tokens';
+import { OutputWidgetShell } from '../../OutputWidgetShell';
+import { outputArtifact } from '../../tokens';
+import { staggerDelay, useEntrance, useEntranceTracker } from '../../motion';
+import type { OutputActionId } from '../../document';
+
+/**
+ * **`artifact` — X3.** `docs/output-type-sheets/artifact.md`, variation B, "clipped, with a
+ * fade" — the only variation the sheet found safe against unbounded document length.
+ *
+ * Deliberately generic content (`rows: {label, value}[]`) rather than per-kind markup (agenda,
+ * receipt, …) — the type sheet is explicit that each real content kind needs its own follow-up
+ * addendum before it ships; this is the frame, built once, content-shape-agnostic.
+ *
+ * **Known simplification, disclosed rather than silently skipped**: the real fade/"Open full
+ * document" affordance should only appear when content actually exceeds the frame (measured), not
+ * merely when a row count crosses a guess. This renderer uses `rows.length > outputArtifact.maxRowsBeforeClip`
+ * as a stand-in for real height measurement — correct at the extremes, approximate near the
+ * boundary. Swap for `useMeasuredSurface`-style measurement if that gap matters later.
+ */
+
+export type ArtifactRow = { id: string; label: string; value: string };
+export type ArtifactPhase = 'loading' | 'settled';
+
+function ArtifactSkeleton() {
+  const { colors } = useDs();
+  return (
+    <Box style={{ padding: outputArtifact.frame.pad, gap: 8 }}>
+      {[0, 1, 2].map(i => (
+        <Box key={i} row justify="space-between">
+          <Box style={{ width: 96, height: 10, borderRadius: 5, backgroundColor: colors.hairlineStrong }} />
+          <Box style={{ width: 64, height: 10, borderRadius: 5, backgroundColor: colors.hairlineStrong }} />
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+function ArtifactRowView({ row, index, seen }: { row: ArtifactRow; index: number; seen: Set<string> }) {
+  const { colors } = useDs();
+  const { opacity, translateY } = useEntrance(row.id, seen, { variant: 'rise', delayMs: staggerDelay(index, 70) });
+  return (
+    <MotionView style={{ opacity, transform: [{ translateY }] }}>
+      <Box row justify="space-between" style={{ paddingVertical: 6 }}>
+        <Text color="textSecondary" mono style={{ fontSize: 11.5 }}>{row.label}</Text>
+        <Text style={{ fontSize: 12.5, fontWeight: '600', color: colors.textPrimary }}>{row.value}</Text>
+      </Box>
+    </MotionView>
+  );
+}
+
+export type ArtifactCardProps = {
+  title: string;
+  chip?: string;
+  meta?: string;
+  rows: ArtifactRow[] | null;
+  phase?: ArtifactPhase;
+  onOpen?: () => void;
+  onMenu?: () => void;
+  onAction?: (id: OutputActionId) => void;
+  testID?: string;
+};
+
+export function ArtifactCard({
+  title, chip = 'artifact', meta, rows, phase = 'settled', onOpen, onMenu, onAction, testID,
+}: ArtifactCardProps) {
+  const { colors } = useDs();
+  const seen = useEntranceTracker();
+  const f = outputArtifact.frame;
+
+  if (phase === 'loading') {
+    return (
+      <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} provisional testID={testID}>
+        <Box style={{ padding: 14 }}>
+          <Box style={{ borderRadius: 14, backgroundColor: colors.surfaceSunken, overflow: 'hidden' }}>
+            <ArtifactSkeleton />
+          </Box>
+        </Box>
+      </OutputWidgetShell>
+    );
+  }
+
+  if (rows === null) {
+    return (
+      <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} testID={testID}>
+        <Box style={{ padding: 14, gap: 8 }}>
+          <Box style={{ borderRadius: 14, backgroundColor: colors.surfaceSunken, padding: f.pad }}>
+            <Text color="textSecondary" style={{ fontSize: 12.5 }}>Document unavailable</Text>
+          </Box>
+        </Box>
+      </OutputWidgetShell>
+    );
+  }
+
+  const clipped = rows.length > outputArtifact.maxRowsBeforeClip;
+  const visible = clipped ? rows.slice(0, outputArtifact.maxRowsBeforeClip) : rows;
+
+  return (
+    <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} testID={testID}>
+      <Box style={{ padding: 14, gap: 10 }}>
+        <Box style={{ position: 'relative' }}>
+          <Box style={{ borderRadius: 14, backgroundColor: colors.surfaceSunken, padding: f.pad, maxHeight: clipped ? outputArtifact.clipHeight : undefined, overflow: 'hidden' }}>
+            {visible.length === 0 ? (
+              <Text color="textSecondary" style={{ fontSize: 12.5 }}>No content</Text>
+            ) : (
+              visible.map((r, i) => <ArtifactRowView key={r.id} row={r} index={i} seen={seen} />)
+            )}
+          </Box>
+          {clipped ? (
+            /* A true CSS gradient needs `experimental_backgroundImage` plumbing this pass didn't
+               take on — approximated with three stacked, decreasing-opacity bands of the same
+               `surfaceSunken` fill the frame itself uses (the sheet's own "must derive from the
+               well value" rule, honoured even in this simplified form). Disclosed, not silent. */
+            <Box style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: outputArtifact.fadeHeight }} aria-hidden>
+              <Box style={{ flex: 1, backgroundColor: colors.surfaceSunken, opacity: 0.35 }} />
+              <Box style={{ flex: 1, backgroundColor: colors.surfaceSunken, opacity: 0.7 }} />
+              <Box style={{ flex: 1, backgroundColor: colors.surfaceSunken, opacity: 0.95 }} />
+            </Box>
+          ) : null}
+        </Box>
+        {clipped ? (
+          <Pressable
+            onPress={onOpen}
+            hit={44}
+            bg="accentTint"
+            radius="pill"
+            align="center"
+            aria-label="Open full document"
+            style={{ paddingVertical: 12, paddingHorizontal: 14, alignSelf: 'flex-start' }}>
+            <Text color="accentInk" style={{ fontSize: 12, fontWeight: '600' }}>Open full document</Text>
+          </Pressable>
+        ) : null}
+      </Box>
+    </OutputWidgetShell>
+  );
+}
+
+export function artifactToText(rows: ArtifactRow[] | null): string {
+  if (rows === null) return 'Document unavailable';
+  if (rows.length === 0) return 'No content';
+  return rows.map(r => `${r.label}: ${r.value}`).join('\n');
+}

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

@@ -0,0 +1,4 @@
+export {
+  ArtifactCard, artifactToText,
+  type ArtifactCardProps, type ArtifactRow, type ArtifactPhase,
+} from './ArtifactCard';