@appinternalleads/ui 0.2.0

package/src/legacy.tsx

@@ -0,0 +1,221 @@
+/**
+ * The pre-v2 general-purpose primitives, rebuilt on the v2 design system.
+ *
+ * **A subpath rather than part of the index, because four of these names are taken.**
+ * `Button`, `Caption`, `Card` and `Field` all exist in the v2 surface with different prop
+ * APIs, so merging the two would either shadow the current components or force a rename
+ * across every call site — and this set exists precisely so those call sites do NOT have to
+ * change yet. Import it as `@comppack/ds/legacy`; the babel alias resolves the subpath by
+ * prefix substitution, the same way `@comppack/ds/legacyTokens` already does.
+ *
+ * They keep their original API so every screen carries on compiling, and they read v2
+ * tokens. The docstring here used to describe the neumorphic material and `@shared/neu`;
+ * both are deleted, and this is the migration aid that outlived them.
+ *
+ * This is a shrinking set. Migrating a call site onto the v2 primitives deletes its use.
+ */
+import React from 'react';
+import {
+  ActivityIndicator,
+  Platform,
+  Pressable,
+  Text,
+  TextInput,
+  View,
+  type TextInputProps,
+  type TextStyle,
+  type ViewProps,
+} from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import { radii, space, type } from './tokens/tokens';
+import { useDs } from './tokens/DsProvider';
+import { scale } from './legacyTokens';
+
+export function Screen({ children, style, ...rest }: ViewProps) {
+  const { colors } = useDs();
+  return (
+    <SafeAreaView style={{ flex: 1, backgroundColor: colors.surface1 }} edges={['top', 'left', 'right']}>
+      <View style={[{ flex: 1, paddingHorizontal: space.gutterText }, style]} {...rest}>
+        {children}
+      </View>
+    </SafeAreaView>
+  );
+}
+
+export function Title({ children }: { children: React.ReactNode }) {
+  const { colors, fonts } = useDs();
+  const style: TextStyle = Platform.OS === 'android' ? type.mdAppBar : type.iosLargeTitle;
+  return (
+    <Text style={{ ...style, fontFamily: fonts.sans, color: colors.textPrimary, marginBottom: space.gapRow }}>{children}</Text>
+  );
+}
+
+export function Heading({ children }: { children: React.ReactNode }) {
+  const { colors, fonts } = useDs();
+  return (
+    <Text style={{ ...type.overlayTitle, fontFamily: fonts.sans, color: colors.textPrimary, marginBottom: scale(4) }}>{children}</Text>
+  );
+}
+
+export function Body({ children, muted }: { children: React.ReactNode; muted?: boolean }) {
+  const { colors, fonts } = useDs();
+  return (
+    <Text style={{ fontFamily: fonts.sans, fontSize: scale(12.5), lineHeight: scale(18.75), color: muted ? colors.textTertiary : colors.textPrimary }}>
+      {children}
+    </Text>
+  );
+}
+
+export function Caption({ children, tone }: { children: React.ReactNode; tone?: 'warn' | 'danger' | 'success' }) {
+  const { colors, fonts } = useDs();
+  // No warning tone exists in the system: pending work is informational, so it takes meta ink.
+  const color = tone === 'danger' ? colors.status.error : tone === 'success' ? colors.brandPrimary : colors.textTertiary;
+  return <Text style={{ fontFamily: fonts.sans, fontSize: scale(10.5), lineHeight: scale(15.75), color }}>{children}</Text>;
+}
+
+/** A quiet content block: inset, never a border as well as a shadow. */
+export function Card({ children, style, ...rest }: ViewProps) {
+  const { colors, edge } = useDs();
+  return (
+    <View
+      style={[
+        {
+          backgroundColor: colors.surface1,
+          boxShadow: edge,
+          borderRadius: radii.card,
+          padding: space.gutterText,
+          marginBottom: scale(12),
+        },
+        style,
+      ]}
+      {...rest}>
+      {children}
+    </View>
+  );
+}
+
+export function Button({
+  title,
+  onPress,
+  variant = 'primary',
+  loading,
+  disabled,
+}: {
+  title: string;
+  onPress: () => void;
+  variant?: 'primary' | 'secondary' | 'danger';
+  loading?: boolean;
+  disabled?: boolean;
+}) {
+  const { colors, edge, fonts } = useDs();
+  const isDisabled = disabled || loading;
+  // Red is never a fill: a destructive action the user chose is not a failure, so `danger`
+  // is a neutral proud button with a red label.
+  const fill = variant === 'primary' ? colors.accentFill : colors.surface1;
+  const ink = variant === 'danger' ? colors.status.error : variant === 'primary' ? colors.accentOnFill : colors.textPrimary;
+
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={title}
+      accessibilityState={{ disabled: !!isDisabled }}
+      onPress={onPress}
+      disabled={isDisabled}
+      style={({ pressed }) => [
+        {
+          height: scale(38),
+          borderRadius: radii.button,
+          alignItems: 'center',
+          justifyContent: 'center',
+        },
+        // A disabled primary sinks rather than dimming. 45% of a near-white inverse fill is
+        // a mid grey that reads heavier than the enabled button — the design's own disabled
+        // treatment is in1 with meta ink, which is what the delete-account sheet uses.
+        isDisabled
+          ? { backgroundColor: colors.surface1, boxShadow: edge }
+          : { backgroundColor: fill, boxShadow: edge },
+        pressed && !isDisabled && { boxShadow: edge },
+      ]}>
+      {loading ? (
+        <ActivityIndicator color={isDisabled ? colors.textTertiary : ink} />
+      ) : (
+        <Text style={{ fontFamily: fonts.sans, fontSize: scale(13), color: isDisabled ? colors.textTertiary : ink }}>
+          {title}
+        </Text>
+      )}
+    </Pressable>
+  );
+}
+
+/** Inputs are wells. The label is mono; there is no focus ring. */
+export function Field({
+  label,
+  error,
+  style,
+  ...rest
+}: TextInputProps & { label: string; error?: string | undefined }) {
+  const { colors, edge, fonts } = useDs();
+  return (
+    <View style={{ marginBottom: scale(12) }}>
+      <Text
+        style={{
+          ...type.monoLabel,
+          fontFamily: fonts.mono,
+          color: colors.textSecondary,
+          marginBottom: scale(6),
+        }}>
+        {label}
+      </Text>
+      <TextInput
+        placeholderTextColor={colors.textTertiary}
+        autoCapitalize="none"
+        autoCorrect={false}
+        {...rest}
+        // Caller `style` merges ON TOP of the base — it must never replace it, or
+        // the input loses its background/text colour and turns invisible.
+        style={[
+          {
+            backgroundColor: colors.surface1,
+            boxShadow: edge,
+            borderRadius: radii.field,
+            color: colors.textPrimary,
+            fontFamily: fonts.sans,
+            fontSize: scale(13),
+            paddingHorizontal: scale(11),
+            paddingVertical: scale(10),
+          },
+          style,
+        ]}
+      />
+      {!!error && (
+        <Text style={{ fontFamily: fonts.sans, fontSize: scale(10.5), color: colors.status.error, marginTop: scale(4) }}>{error}</Text>
+      )}
+    </View>
+  );
+}
+
+export function Row({ children, style, ...rest }: ViewProps) {
+  return (
+    <View style={[{ flexDirection: 'row', alignItems: 'center', gap: scale(12) }, style]} {...rest}>
+      {children}
+    </View>
+  );
+}
+
+export function Empty({ text }: { text: string }) {
+  const { colors, fonts } = useDs();
+  return (
+    <View style={{ paddingVertical: scale(32), alignItems: 'center' }}>
+      <Text
+        style={{
+          fontFamily: fonts.sans,
+          fontSize: scale(11.5),
+          lineHeight: scale(18.4),
+          color: colors.textTertiary,
+          textAlign: 'center',
+        }}>
+        {text}
+      </Text>
+    </View>
+  );
+}

package/src/legacyTokens.ts

@@ -0,0 +1,180 @@
+/**
+ * Design tokens, ported from `design/tokens/*.css`.
+ *
+ * The CSS in `design/` is the source of truth — every value here is copied from it, not
+ * re-derived. If a token changes there, change it here; nothing else in the app should
+ * hold a hex value.
+ *
+ * The material is one surface colour plus two shadow colours. Dark is the default; light
+ * re-scopes the same names. See `design/design-system-guide.md`.
+ */
+import { Platform } from 'react-native';
+
+export type Mode = 'dark' | 'light';
+
+/**
+ * Global size multiplier for type, spacing, radii and icons.
+ *
+ * The handoff's values are the 1.0 baseline and are exact — 12.5px really is 12.5px. This
+ * scales all of them together so the proportions the design depends on survive: icons stay
+ * anchored to their labels, and radii keep climbing with the size of the thing.
+ *
+ * Deliberately NOT applied to `hitIos` / `hitMd`, which are platform floors rather than
+ * design values, or to hairline border widths, which should stay hairlines.
+ */
+/**
+ * v1 multiplied every value by 1.26. The v2 handoff is specified pixel-exact at high
+ * fidelity, so the multiplier is now 1 and `scale()` is the identity — kept as a function
+ * only so the many call sites still compile while screens migrate to `@shared/ds`, which
+ * has no scaling concept at all.
+ */
+export const UI_SCALE = 1;
+
+/** Scale a design value. Rounded to 2dp so layout maths stays free of float noise. */
+export const scale = (n: number): number => Math.round(n * UI_SCALE * 100) / 100;
+
+/**
+ * The v1 palette is gone. `Colors` is the v2 type, re-exported so the remaining
+ * `import { type Colors } from '@shared/ds'` sites keep resolving while they move over.
+ */
+export type { Colors } from './tokens/tokens';
+export { switchThumb } from './tokens/tokens';
+
+/** Radii climb with the size of the thing. Nothing in CompPack is square. */
+export const radii = {
+  key: scale(6),
+  field: scale(8),
+  pillSm: scale(10),
+  search: scale(11),
+  row: scale(12),
+  button: scale(13),
+  sheetIos: scale(14),
+  card: scale(16),
+  iconTile: scale(18),
+  pill: scale(20),
+  dialogMd: scale(28),
+  screen: scale(35),
+  bezel: scale(44),
+} as const;
+
+/**
+ * Rows sit 13px from the screen edge and text at 16px — rows deliberately hang 3px
+ * outside the text column. Keep that offset.
+ */
+export const space = {
+  gutterRow: scale(13),
+  gutterText: scale(16),
+  gapRow: scale(8),
+  gapChip: scale(7),
+  gapSection: scale(20),
+  // Platform minimums, not design values — these never scale.
+  hitIos: 44,
+  hitMd: 48,
+} as const;
+
+/** Platform minimum touch target. A 16px glyph still gets its full box. */
+export const hitTarget = Platform.OS === 'android' ? space.hitMd : space.hitIos;
+
+/**
+ * The pre-v2 spacing and radius ladders, for module-scope `StyleSheet.create` blocks.
+ *
+ * They lived in the keyboard app's `src/theme/index.ts` and derived from the tokens right
+ * above — so a shared screen could not use them without importing an app directory. Mode
+ * independent, which is why a module-scope constant is honest for them where a colour never
+ * was: the same file used to export a palette frozen to the dark scope, and every screen
+ * reading it painted dark ink in light mode.
+ *
+ * Legacy in the same sense as everything else here: migrating a call site onto `space` and
+ * `radii` directly deletes its use.
+ */
+export const spacing = {
+  xs: 4,
+  sm: space.gapRow,
+  md: 12,
+  lg: space.gutterText,
+  xl: 24,
+  xxl: 32,
+} as const;
+
+export const radius = {
+  sm: radii.field,
+  md: radii.row,
+  lg: radii.card,
+  pill: radii.pill,
+} as const;
+
+/**
+ * Type, offered as three pairings.
+ *
+ * The system wants Geist and Geist Mono and nothing else, but no binaries shipped with the
+ * handoff — so until real font files land, every option resolves to faces the platform
+ * already has. Mono is never a preference: it carries triggers, tokens, action ids, counts
+ * and field labels, and those have to stay unmistakably mono in all three.
+ *
+ * **Android has three system families** (sans-serif, serif, monospace), so `humanist`
+ * resolves to the same face as `system` there. Bundling Geist closes that gap.
+ */
+export type TypefaceName = 'system' | 'humanist' | 'serif';
+
+export type Typeface = { label: string; note: string; sans: string | undefined; mono: string };
+
+const MONO = Platform.OS === 'android' ? 'monospace' : 'Menlo';
+
+export const TYPEFACES: Record<TypefaceName, Typeface> = {
+  // What the design intends: the neutral platform face, out of the way of the material.
+  system: {
+    label: 'System',
+    note: 'The platform’s own face. What the design assumes.',
+    sans: undefined,
+    mono: MONO,
+  },
+  humanist: {
+    label: 'Humanist',
+    note: 'Warmer, wider letterforms. Falls back to the system face on Android.',
+    sans: Platform.OS === 'android' ? undefined : 'Avenir Next',
+    mono: MONO,
+  },
+  serif: {
+    label: 'Serif',
+    note: 'Georgia on iOS, the platform serif on Android.',
+    sans: Platform.OS === 'android' ? 'serif' : 'Georgia',
+    mono: MONO,
+  },
+};
+
+export const TYPEFACE_NAMES = Object.keys(TYPEFACES) as TypefaceName[];
+
+/**
+ * The default pairing, for the handful of module-scope `StyleSheet.create` blocks that are
+ * evaluated once at load. Everything that can read the live choice does so via `useDs()`.
+ */
+export const fonts: { sans: string | undefined; mono: string } = { ...TYPEFACES.system };
+
+/**
+ * Device type scale — the prototype's literals. These are deliberately not snapped to a
+ * 4px grid: row titles really are 12.5px and action ids really are 8.5px.
+ */
+export const type = {
+  iosLargeTitle: { fontSize: scale(29), fontWeight: '600', letterSpacing: scale(-0.81), lineHeight: scale(33) },
+  mdAppBar: { fontSize: scale(21), fontWeight: '500', lineHeight: scale(26) },
+  overlayTitle: { fontSize: scale(19), fontWeight: '500', letterSpacing: scale(-0.29) },
+  rowTitle: { fontSize: scale(12.5), fontWeight: '400' },
+  rowTrigger: { fontSize: scale(12), fontWeight: '400' },
+  rowMeta: { fontSize: scale(10.5), fontWeight: '400', lineHeight: scale(15.75) },
+  sectionLabel: { fontSize: scale(12), fontWeight: '500' },
+  monoLabel: { fontSize: scale(10.5), fontWeight: '400', letterSpacing: scale(0.42) },
+  monoCount: { fontSize: scale(10), fontWeight: '400' },
+  monoId: { fontSize: scale(8.5), fontWeight: '400', letterSpacing: scale(0.17) },
+  statusBar: { fontSize: scale(9.5), fontWeight: '400' },
+} as const;
+
+/** One curve, five durations. Nothing bounces. */
+export const motion = {
+  // cubic-bezier(0.05, 0.7, 0.1, 1)
+  ease: { x1: 0.05, y1: 0.7, x2: 0.1, y2: 1 },
+  instant: 140,
+  fast: 160,
+  quick: 180,
+  base: 200,
+  spin: 1100,
+} as const;

package/src/native/NativeDatePicker.tsx

@@ -0,0 +1,63 @@
+import { useState } from 'react';
+import RNDateTimePicker from '@react-native-community/datetimepicker';
+import { Box } from '../core/Box';
+import { Pressable } from '../core/Pressable';
+import { Text } from '../core/Text';
+import type { DatePickerProps } from '../core/DatePicker.types';
+
+/**
+ * The platform's own date and time picker — modal on Android, inline on iOS.
+ *
+ * **Requires `@react-native-community/datetimepicker`.** The trigger is ours and only the picker
+ * itself is theirs, which is also why the trigger takes the field edge: it is a hole showing the
+ * current answer, not a button.
+ *
+ * ISO in, ISO out. The picker speaks `Date`, which is a lossy round trip for a date-only field,
+ * so the conversion is kept here rather than at each call site.
+ */
+export function NativeDatePicker({
+  value, onChange, mode, min, max, testID,
+  'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy,
+}: DatePickerProps) {
+  const [open, setOpen] = useState(false);
+  const asDate = value ? new Date(value) : new Date();
+
+  return (
+    <>
+      <Pressable
+        onPress={() => setOpen(true)}
+        row
+        align="center"
+        justify="flex-start"
+        px="s3"
+        py="s3"
+        radius="field"
+        bg="surface1"
+        testID={testID}
+        aria-label={ariaLabel}
+        style={{ minHeight: 44 }}>
+        <Box>
+          <Text color={value ? 'textPrimary' : 'textTertiary'}>
+            {value ?? (mode === 'datetime' ? 'Pick a date and time' : 'Pick a date')}
+          </Text>
+        </Box>
+      </Pressable>
+
+      {open ? (
+        <RNDateTimePicker
+          value={asDate}
+          mode={mode === 'datetime' ? 'datetime' : 'date'}
+          minimumDate={min ? new Date(min) : undefined}
+          maximumDate={max ? new Date(max) : undefined}
+          accessibilityLabel={ariaLabelledBy}
+          onChange={(_e, picked) => {
+            setOpen(false);
+            if (!picked) return;
+            const iso = picked.toISOString();
+            onChange(mode === 'datetime' ? iso.slice(0, 16) : iso.slice(0, 10));
+          }}
+        />
+      ) : null}
+    </>
+  );
+}

package/src/native/NativeSlider.tsx

@@ -0,0 +1,34 @@
+import RNSlider from '@react-native-community/slider';
+import { useDs } from '../tokens';
+import type { SliderProps } from '../core/Slider.types';
+
+/**
+ * The platform's own slider, with its momentum and its haptics.
+ *
+ * **Requires `@react-native-community/slider`.** That is the whole reason it lives here rather
+ * than in `core/` — see `src/native/index.ts`.
+ *
+ * The props are `core/Slider`'s exactly, so swapping between them is an import change and
+ * nothing else.
+ */
+export function NativeSlider({
+  value, onChange, min, max, step = 1, disabled, 'aria-label': ariaLabel, testID,
+}: SliderProps) {
+  const { colors } = useDs();
+  return (
+    <RNSlider
+      testID={testID}
+      value={value}
+      onValueChange={onChange}
+      minimumValue={min}
+      maximumValue={max}
+      step={step}
+      disabled={disabled}
+      accessibilityLabel={ariaLabel}
+      minimumTrackTintColor={colors.accentFill}
+      maximumTrackTintColor={colors.surfaceSunken}
+      thumbTintColor={colors.surface1}
+      style={{ flex: 1, opacity: disabled ? 0.4 : 1 }}
+    />
+  );
+}

package/src/native/RiveReceiptStage.tsx

@@ -0,0 +1,182 @@
+import { useEffect, useRef, useState } from 'react';
+import { Fit, RiveFileFactory, RiveView, type RiveFile, type RiveViewRef, type ViewModel, type ViewModelInstance } from '@rive-app/react-native';
+import { Box } from '../core';
+import { HUE, blockRadii } from '../tokens';
+import type { ReceiptLines } from '../components/onboarding/receipt-printer/engine';
+import { ReceiptPaper } from '../components/onboarding/receipt-printer/ReceiptPaper';
+import { RECEIPT_PRINTER_RIV } from '../components/onboarding/receipt-printer/riv';
+import { stageAspect, type ReceiptStageProps } from '../components/onboarding/receipt-printer/ReceiptStage.types';
+import { ReceiptPrinter, type ReceiptPrinterProps } from '../components/onboarding/receipt-printer/ReceiptPrinterView';
+
+/**
+ * **The Receipt Printer's Rive printer, on iOS and Android** — the same `.riv`, the same feed, the
+ * same tear-off as the web, through `@rive-app/react-native` (which needs
+ * `react-native-nitro-modules`, and a `pod install`).
+ *
+ * It keeps the web stage's contract exactly (`ReceiptStage.web.tsx`): the lines go onto the
+ * `Receipt` view model before a trigger fires; a printed receipt that is tearing off keeps its text
+ * until the machine leaves it; `status` = `printed` says the paper is at rest; and if the runtime or
+ * the file cannot load, the still (`ReceiptPaper`) is drawn and a print completes at once. Two
+ * differences: the native runtime's view-model calls are asynchronous, so every write goes through
+ * one queue, in order; and a native view stops advancing once its machine settles, so every write
+ * and trigger is followed by `playIfNeeded()`. Found on Android: without it, Print again after a
+ * print fired the trigger into a paused view, and nothing moved.
+ *
+ * Its own entry point — importing it is the opt-in, and it pulls in nothing else native:
+ *
+ *   import { NativeReceiptPrinter } from '@comppack/ui/native/receipt-printer';
+ *   <NativeReceiptPrinter preset="case1" />
+ *   // or: <ReceiptPrinter stage={RiveReceiptStage} />
+ */
+
+const ARTBOARD = 'ReceiptPrinter';
+const MACHINE = 'ReceiptPrinterMachine';
+const LINE_KEYS = ['title', 'badge', 'total', 'meta', 'paymentMethod', 'message', 'paymentLabel', 'totalLabel'] as const;
+
+let bytes: ArrayBuffer | null = null;
+function rivBytes(): ArrayBuffer {
+  if (!bytes) {
+    const bin = atob(RECEIPT_PRINTER_RIV);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    bytes = out.buffer;
+  }
+  return bytes;
+}
+/** One file per app: parsing 280 kB once is enough for every printer on every screen. */
+let filePromise: Promise<RiveFile> | null = null;
+const loadFile = () => (filePromise ??= RiveFileFactory.fromBytes(rivBytes(), undefined, false)
+  /* A load that failed is not kept: the next printer to mount tries again. */
+  .catch(e => { filePromise = null; throw e; }));
+
+type Loaded = { file: RiveFile; vm: ViewModelInstance; models: { detail?: ViewModel; item?: ViewModel } };
+
+async function syncList(vm: ViewModelInstance, path: string, model: ViewModel | undefined, rows: Record<string, string>[]) {
+  const list = vm.listProperty(path);
+  if (!list) return;
+  let length = await list.getLengthAsync();
+  while (length > rows.length) { await list.removeInstanceAtAsync(length - 1); length--; }
+  while (length < rows.length && model) {
+    const inst = await model.createBlankInstanceAsync();
+    if (!inst) break;
+    await list.addInstanceAsync(inst);
+    length++;
+  }
+  for (let i = 0; i < rows.length; i++) {
+    const inst = await list.getInstanceAtAsync(i);
+    for (const [k, v] of Object.entries(rows[i]!)) inst?.stringProperty(k)?.set(v);
+  }
+}
+
+async function writeLines(l: Loaded, lines: ReceiptLines) {
+  for (const k of LINE_KEYS) l.vm.stringProperty(k)?.set(lines[k]);
+  await syncList(l.vm, 'details', l.models.detail, lines.details);
+  await syncList(l.vm, 'items', l.models.item, lines.items);
+  l.vm.numberProperty('lineCount')?.set(Math.max(1, lines.items.length));
+  l.vm.numberProperty('detailCount')?.set(lines.details.length);
+}
+
+export function RiveReceiptStage({ lines, job, phase, reduceMotion, onPrinted, label, maxWidth, testID }: ReceiptStageProps) {
+  const [loaded, setLoaded] = useState<Loaded | null>(null);
+  const [failed, setFailed] = useState(false);
+  const [shown, setShown] = useState({ lines: Math.max(1, lines.items.length), fields: lines.details.length });
+  const view = useRef<RiveViewRef | null>(null);
+  const queue = useRef<Promise<void>>(Promise.resolve());
+  /* Every change to the view model, in order — then wake the view, which pauses once it settles. */
+  const enqueue = (work: () => Promise<void> | void) => {
+    queue.current = queue.current.then(work).then(() => view.current?.playIfNeeded()).catch(() => {});
+  };
+  const status = useRef('idle');
+  const started = useRef<number | null>(null);
+  const latest = useRef(lines);
+  latest.current = lines;
+  const printed = useRef(onPrinted);
+  printed.current = onPrinted;
+
+  const write = (l: Loaded, next: ReceiptLines) => enqueue(async () => {
+    await writeLines(l, next);
+    setShown({ lines: Math.max(1, next.items.length), fields: next.details.length });
+  });
+
+  /* Load the file, make the `Receipt` instance this view binds, and listen to where the paper is. */
+  useEffect(() => {
+    let alive = true;
+    let stop: (() => void) | undefined;
+    (async () => {
+      const file = await loadFile();
+      const model = await file.viewModelByNameAsync('Receipt');
+      const vm = await model?.createDefaultInstanceAsync();
+      if (!vm) throw new Error('The Receipt view model is missing.');
+      const l: Loaded = {
+        file, vm,
+        models: { detail: await file.viewModelByNameAsync('ReceiptDetail'), item: await file.viewModelByNameAsync('ReceiptItem') },
+      };
+      /* The first lines go on before the view mounts, so its first frame is this receipt's length. */
+      await writeLines(l, latest.current);
+      if (!alive) return;
+      setShown({ lines: Math.max(1, latest.current.items.length), fields: latest.current.details.length });
+      stop = vm.stringProperty('status')?.addListener(value => {
+        status.current = value;
+        /* Past a tear-off — a fresh feed, or the idle stub: the lines held back go on now. */
+        if (value === 'printing' || value === 'idle') write(l, latest.current);
+        if (value === 'printed' && started.current !== null) printed.current(started.current);
+      });
+      setLoaded(l);
+    })().catch(() => { if (alive) setFailed(true); });
+    return () => { alive = false; stop?.(); };
+  }, []);
+
+  /* 1 · The lines — never onto a receipt on its way out (a reprint or a reset, with motion). */
+  useEffect(() => {
+    if (!loaded) return;
+    loaded.vm.booleanProperty('reduceMotion')?.set(reduceMotion);
+    const leaving = status.current === 'tearing'
+      || (status.current === 'printed' && !reduceMotion && (phase === 'idle' || started.current !== job));
+    if (!leaving) write(loaded, lines);
+  }, [loaded, lines, phase, job, reduceMotion]);
+
+  /* 2 · The phase, as triggers — queued behind the lines. Each job is started once. */
+  useEffect(() => {
+    if (!loaded) return;
+    if (phase === 'idle') {
+      started.current = null;
+      enqueue(() => { if (status.current !== 'idle') loaded.vm.triggerProperty('reset')?.trigger(); });
+      return;
+    }
+    if (started.current === job) return;
+    started.current = job;
+    const reveal = reduceMotion || phase === 'printed';
+    enqueue(() => {
+      /* A reveal over a receipt already at rest changes no status: the new lines are this job's paper. */
+      if (reveal && status.current === 'printed') { printed.current(job); return; }
+      loaded.vm.triggerProperty(reveal ? 'reveal' : 'print')?.trigger();
+    });
+  }, [loaded, phase, job, reduceMotion]);
+
+  /* Without the runtime, the still — and a print completes at once. */
+  useEffect(() => { if (failed && phase === 'printing') onPrinted(job); }, [failed, phase, job]);
+
+  if (failed) return <ReceiptPaper lines={lines} phase={phase} maxWidth={maxWidth} label={label} testID={testID} />;
+  return (
+    <Box testID={testID} role="img" aria-label={label} style={{ width: '100%', maxWidth, aspectRatio: stageAspect(shown.lines, shown.fields), borderRadius: blockRadii.mid, overflow: 'hidden', backgroundColor: HUE.butter.hs }}>
+      {loaded ? (
+        <RiveView
+          file={loaded.file}
+          artboardName={ARTBOARD}
+          stateMachineName={MACHINE}
+          dataBind={loaded.vm}
+          autoPlay
+          fit={Fit.Contain}
+          onError={() => setFailed(true)}
+          hybridRef={{ f: (ref: RiveViewRef | null) => { view.current = ref; } }}
+          style={{ width: '100%', height: '100%' }}
+        />
+      ) : null}
+    </Box>
+  );
+}
+
+/** `ReceiptPrinter` with the animated Rive printer — for React Native apps that installed the runtime. */
+export function NativeReceiptPrinter(props: Omit<ReceiptPrinterProps, 'stage'> & Record<string, unknown>) {
+  return <ReceiptPrinter {...props} stage={RiveReceiptStage} />;
+}