@q9labsai/chalk-react-native 4.1.17 → 5.0.1

package/src/stage/layout.ts

@@ -0,0 +1,226 @@
+import { STAGE_GAP as G } from "../frame/regions";
+import type { Frame } from "../motion/MovingFrame";
+
+/** What a tile shows: one person, the shared screen or board, or the "+N" tile that opens People. */
+export type Slot = { readonly kind: "person"; readonly id: string } | { readonly kind: "content" };
+
+export type StageItem =
+  | { readonly kind: "person"; readonly id: string; readonly frame: Frame; readonly big: boolean; readonly float: boolean }
+  /** `inner` is the shared content's box inside the tile, letterboxed to its aspect. */
+  | { readonly kind: "content"; readonly frame: Frame; readonly inner: Frame; readonly mini: boolean }
+  | { readonly kind: "more"; readonly frame: Frame; readonly count: number };
+
+export type StageContent = { readonly kind: "screen" | "board"; /** Width over height; null fills the tile. */ readonly aspect: number | null };
+
+export type StageInput = {
+  readonly stage: Frame;
+  /** Portrait or landscape phone. The iPad uses the phone layout today. */
+  readonly portrait: boolean;
+  readonly layout: "spotlight" | "grid";
+  /** Everyone in stage order, you included. */
+  readonly order: readonly string[];
+  /** The person Spotlight shows big when nobody is pinned. */
+  readonly spot: string | null;
+  readonly pinned: string | null;
+  readonly content: StageContent | null;
+};
+
+type Placed = { readonly key: Slot | "more"; readonly frame: Frame; readonly more?: number };
+type Rows = { readonly placed: readonly Placed[] };
+type JustifyOptions = { readonly t: number; readonly minW: number; readonly minH: number };
+
+const SOFT = [0.8, 2] as const;
+const HARD = [0.6, 2.4] as const;
+const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(max, value));
+const area = (frame: Frame) => frame.width * frame.height;
+
+/** The mockup's `contain`: the largest box of `aspect` centred in `box`. */
+export function contain(box: Frame, aspect: number | null): Frame {
+  if (!aspect) return box;
+  let width = box.width;
+  let height = width / aspect;
+  if (height > box.height) {
+    height = box.height;
+    width = height * aspect;
+  }
+  return { x: box.x + (box.width - width) / 2, y: box.y + (box.height - height) / 2, width, height };
+}
+
+/** The mockup's `jo()`: the target aspect and smallest tile per arrangement. */
+function justifyOptions(portrait: boolean): JustifyOptions {
+  return portrait ? { t: 1, minW: 88, minH: 72 } : { t: 1.5, minW: 100, minH: 64 };
+}
+
+/**
+ * The mockup's `jplan`: pick the row count, spread `units` so rows differ by at most one, and
+ * score each plan by how far its tiles stray from the aspect bounds and the target aspect.
+ */
+function justifyPlan(box: Frame, units: number, options: JustifyOptions, firstRowTwo: boolean) {
+  let best: { counts: number[]; height: number; cost: number; minWidth: number } | null = null;
+  for (let rows = 1; rows <= units; rows++) {
+    const base = Math.floor(units / rows);
+    const extra = units % rows;
+    if (!base) break;
+    const counts = Array.from({ length: rows }, (_, index) => base + (index < extra ? 1 : 0));
+    if (firstRowTwo && (counts[0] ?? 0) < 2) continue;
+    const height = (box.height - (rows - 1) * G) / rows;
+    if (height <= 0) break;
+    let cost = 0;
+    let minWidth = Infinity;
+    for (const count of counts) {
+      const width = (box.width - (count - 1) * G) / count;
+      const aspect = width / height;
+      minWidth = Math.min(minWidth, width);
+      const hard = aspect < HARD[0] ? Math.log(HARD[0] / aspect) : aspect > HARD[1] ? Math.log(aspect / HARD[1]) : 0;
+      const soft = aspect < SOFT[0] ? Math.log(SOFT[0] / aspect) : aspect > SOFT[1] ? Math.log(aspect / SOFT[1]) : 0;
+      cost += count * (hard * 60 + soft * 3 + Math.abs(Math.log(aspect / options.t)));
+    }
+    cost /= units;
+    if (!best || cost < best.cost) best = { counts, height, cost, minWidth };
+  }
+  return best;
+}
+
+/**
+ * The mockup's `jrows`: justified rows that fill the box with no gaps. Shared content takes a
+ * double tile. When tiles would get smaller than the minimum, the last one becomes "+N".
+ */
+function justifiedRows(box: Frame, list: readonly Slot[], options: JustifyOptions): Rows {
+  const weight = (key: Slot | "more") => (key !== "more" && key.kind === "content" ? 2 : 1);
+  const contentFirst = list[0]?.kind === "content";
+  const total = list.length;
+  let keys: readonly (Slot | "more")[] = list;
+  let plan: ReturnType<typeof justifyPlan> = null;
+  for (let kept = total; kept >= 1; kept--) {
+    keys = kept === total ? list : [...list.slice(0, kept - 1), "more"];
+    plan = justifyPlan(
+      box,
+      keys.reduce((sum, key) => sum + weight(key), 0),
+      options,
+      contentFirst,
+    );
+    if ((plan && plan.minWidth >= options.minW && plan.height >= options.minH) || kept <= (contentFirst ? 2 : 1)) break;
+  }
+  if (!plan) return { placed: [] };
+  let height = plan.height;
+  for (const count of plan.counts) {
+    const width = (box.width - (count - 1) * G) / count;
+    if (width / height < HARD[0]) height = Math.min(height, width / HARD[0]);
+  }
+  const top = box.y + (box.height - plan.counts.length * height - (plan.counts.length - 1) * G) / 2;
+  const placed: Placed[] = [];
+  let index = 0;
+  plan.counts.forEach((count, row) => {
+    let unit = (box.width - (count - 1) * G) / count;
+    if (unit / height > HARD[1]) unit = height * HARD[1];
+    let x = box.x + (box.width - count * unit - (count - 1) * G) / 2;
+    let used = 0;
+    while (used < count && index < keys.length) {
+      const key = keys[index];
+      if (key === undefined) break;
+      const units = weight(key);
+      const frame = { x, y: top + row * (height + G), width: unit * units + G * (units - 1), height };
+      placed.push(key === "more" ? { key, frame, more: total - keys.length + 1 } : { key, frame });
+      x += frame.width + G;
+      used += units;
+      index++;
+    }
+  });
+  return { placed };
+}
+
+/** The mockup's `fitGrid` and `fill` for a single tile: the largest box within the aspect bounds, centred. */
+function fillOne(box: Frame, aspect: { readonly min: number; readonly max: number; readonly cap: number }): Frame {
+  let width = box.width;
+  let height = box.height;
+  if (width / height > aspect.max) width = height * aspect.max;
+  else if (width / height < aspect.min) height = width / aspect.min;
+  if (aspect.cap && width > aspect.cap) {
+    height *= aspect.cap / width;
+    width = aspect.cap;
+  }
+  return { x: box.x + (box.width - width) / 2, y: box.y + (box.height - height) / 2, width, height };
+}
+
+/** Lays out the stage as the mockup's `layout()` does for a phone call. */
+export function stageLayout(input: StageInput): readonly StageItem[] {
+  const { stage, portrait, content } = input;
+  if (input.layout === "grid") {
+    const rows = justifiedRows(stage, content ? [{ kind: "content" }, ...people(input.order)] : people(input.order), justifyOptions(portrait));
+    return toItems(rows.placed, content, { miniContent: true });
+  }
+  if (content && input.pinned !== null) return spotlightPeople(input, [{ kind: "content" }, ...people(input.order)]);
+  return content ? spotlightContent(input, content) : spotlightPeople(input, people(input.order));
+}
+
+function people(order: readonly string[]): Slot[] {
+  return order.map((id) => ({ kind: "person", id }));
+}
+
+/** The mockup's `spotContent`: the share gets the larger of below or beside, people fill the rest. */
+function spotlightContent(input: StageInput, content: StageContent): readonly StageItem[] {
+  const { stage, portrait } = input;
+  const peopleMin = portrait ? (content.kind === "board" ? clamp(Math.round(stage.height * 0.17), 96, 120) : Math.round(stage.height * 0.3)) : clamp(stage.height * 0.17, 104, 150);
+  const contentMin = portrait ? 120 : clamp(stage.width * 0.15, 180, 260);
+  const belowBox = contain({ ...stage, height: stage.height - peopleMin - G }, content.aspect);
+  const below = { tile: { ...stage, height: belowBox.height }, rest: { x: stage.x, y: stage.y + belowBox.height + G, width: stage.width, height: stage.height - belowBox.height - G }, area: area(belowBox) };
+  const besideBox = contain({ ...stage, width: stage.width - contentMin - G }, content.aspect);
+  const beside = { tile: { ...stage, width: besideBox.width }, rest: { x: stage.x + besideBox.width + G, y: stage.y, width: stage.width - besideBox.width - G, height: stage.height }, area: area(besideBox) };
+  const best = beside.area > below.area * 1.005 ? beside : below;
+  const rows = justifiedRows(best.rest, people(input.order), justifyOptions(portrait));
+  const tile: StageItem = { kind: "content", frame: best.tile, inner: contain({ x: 0, y: 0, width: best.tile.width, height: best.tile.height }, content.aspect), mini: false };
+  return [tile, ...toItems(rows.placed, content, { miniContent: true })];
+}
+
+/** The mockup's `spotPeople`: one person big, everyone else in rows below (or beside, in landscape). */
+function spotlightPeople(input: StageInput, list: readonly Slot[]): readonly StageItem[] {
+  const { stage, portrait, content, pinned, spot } = input;
+  const ids = list.flatMap((slot) => (slot.kind === "person" ? [slot.id] : []));
+  const main = content ? pinned : pinned !== null && ids.includes(pinned) ? pinned : spot !== null && ids.includes(spot) ? spot : (ids[0] ?? null);
+  if (main === null) return [];
+  const rest = list.filter((slot) => slot.kind !== "person" || slot.id !== main);
+  const first = rest[0];
+  if (!first) return [{ kind: "person", id: main, frame: fillOne(stage, { min: portrait ? 0.4 : 4 / 3, max: 16 / 9, cap: portrait ? 0 : stage.width * 0.56 }), big: false, float: false }];
+  if (rest.length === 1) {
+    const size = portrait ? { width: 96, height: 128 } : { width: 132, height: 96 };
+    const y = portrait ? stage.y + 12 : stage.y + stage.height - size.height - 12;
+    const floating = { x: stage.x + stage.width - size.width - 12, y, ...size };
+    return [{ kind: "person", id: main, frame: stage, big: false, float: false }, ...toItems([{ key: first, frame: floating }], content, { miniContent: true, float: true })];
+  }
+  const peopleMin = portrait ? Math.round(stage.height * 0.3) : clamp(stage.height * 0.17, 104, 150);
+  const sideMin = clamp(stage.width * 0.15, 180, 260);
+  const off = (frame: Frame) => Math.abs(Math.log(frame.width / frame.height / (16 / 9)));
+  const below = { main: { ...stage, height: stage.height - peopleMin - G }, rest: { x: stage.x, y: stage.y + stage.height - peopleMin, width: stage.width, height: peopleMin } };
+  const beside = { main: { ...stage, width: stage.width - sideMin - G }, rest: { x: stage.x + stage.width - sideMin, y: stage.y, width: sideMin, height: stage.height } };
+  const chosen = portrait || off(below.main) <= off(beside.main) ? below : beside;
+  return [{ kind: "person", id: main, frame: chosen.main, big: true, float: false }, ...toItems(justifiedRows(chosen.rest, rest, justifyOptions(portrait)).placed, content, { miniContent: true })];
+}
+
+function toItems(placed: readonly Placed[], content: StageContent | null, options: { readonly miniContent: boolean; readonly float?: boolean }): StageItem[] {
+  return placed.map(({ key, frame, more }): StageItem => {
+    if (key === "more") return { kind: "more", frame, count: more ?? 0 };
+    if (key.kind === "person") return { kind: "person", id: key.id, frame, big: false, float: options.float ?? false };
+    return { kind: "content", frame, inner: contain({ x: 0, y: 0, width: frame.width, height: frame.height }, content?.aspect ?? null), mini: options.miniContent };
+  });
+}
+
+export type StageOrder = { readonly order: readonly string[]; readonly spot: string | null };
+
+/**
+ * Keeps the stage order stable as people come and go, as the mockup's `syncOrder` and
+ * `nextSpeaker` do: leavers drop out, newcomers join the end, and when someone else starts
+ * speaking they swap places with the person in the spotlight, so only those two tiles move.
+ */
+export function nextStageOrder(previous: StageOrder, present: readonly string[], selfId: string | null, speaker: string | null): StageOrder {
+  const order = previous.order.filter((id) => present.includes(id));
+  for (const id of present) if (!order.includes(id)) order.push(id);
+  let spot = previous.spot !== null && present.includes(previous.spot) ? previous.spot : (present.find((id) => id !== selfId) ?? present[0] ?? null);
+  if (speaker !== null && speaker !== selfId && speaker !== spot && present.includes(speaker)) {
+    const from = spot === null ? -1 : order.indexOf(spot);
+    const to = order.indexOf(speaker);
+    if (from >= 0 && to >= 0) [order[from], order[to]] = [speaker, order[from] ?? speaker];
+    spot = speaker;
+  }
+  const unchanged = spot === previous.spot && order.length === previous.order.length && order.every((id, index) => id === previous.order[index]);
+  return unchanged ? previous : { order, spot };
+}

package/src/stage/space-selector.ts

@@ -0,0 +1,31 @@
+import type { SpaceSnapshot } from "@q9labsai/chalk-client";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useSpaceClient } from "../context/space-client-context";
+
+/**
+ * Reads one value from the call's snapshot and re-renders only when that value changes by
+ * `isEqual`, so one person's change re-renders only their own tile. `select` must be stable
+ * (wrap it in `useCallback`).
+ */
+export function useSpaceSelector<T>(select: (snapshot: SpaceSnapshot) => T, isEqual: (a: T, b: T) => boolean = Object.is): T {
+  const client = useSpaceClient();
+  const cache = useRef<{ readonly snapshot: SpaceSnapshot; readonly select: (snapshot: SpaceSnapshot) => T; readonly value: T } | null>(null);
+  const subscribe = useCallback((listener: () => void) => client.subscribe(listener), [client]);
+  const getSnapshot = useCallback(() => {
+    const snapshot = client.getSnapshot();
+    const cached = cache.current;
+    if (cached && cached.snapshot === snapshot && cached.select === select) return cached.value;
+    const next = select(snapshot);
+    const value = cached && cached.select === select && isEqual(cached.value, next) ? cached.value : next;
+    cache.current = { snapshot, select, value };
+    return value;
+  }, [client, isEqual, select]);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/** Equal when both objects hold the same values under the same keys, compared with `Object.is`. */
+export function shallowEqual<T extends object>(a: T, b: T): boolean {
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every((key) => Object.is(Reflect.get(a, key), Reflect.get(b, key)));
+}

package/src/stage/stage-view.tsx

@@ -0,0 +1,68 @@
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
+import { useDevScenario } from "../frame/dev-scenario";
+
+export type StageLayoutChoice = "spotlight" | "grid";
+
+export type StageView = {
+  readonly layout: StageLayoutChoice;
+  readonly pinned: string | null;
+  /** Whether your own front-camera video is mirrored, as in a mirror. On by default. */
+  readonly mirror: boolean;
+  readonly setLayout: (layout: StageLayoutChoice) => void;
+  /** Pins a person, or unpins them if they're pinned. In Grid it switches to Spotlight first. */
+  readonly togglePin: (participantId: string) => void;
+  /** Spotlight with nobody pinned, so the shared screen or board takes the stage. */
+  readonly showContent: () => void;
+  readonly setMirror: (mirror: boolean) => void;
+};
+
+const StageViewContext = createContext<StageView | null>(null);
+
+/**
+ * The person's choices about the stage: Spotlight or Grid, who's pinned, and the mirror. They
+ * live above the frame so More (the layout switch) and the stage share them.
+ */
+export function StageViewProvider({ children }: { readonly children: ReactNode }): React.JSX.Element {
+  const [layout, setLayout] = useState<StageLayoutChoice>("spotlight");
+  const [pinned, setPinned] = useState<string | null>(null);
+  const [mirror, setMirror] = useState(true);
+
+  const dev = useDevScenario();
+  useEffect(() => {
+    if (dev.layout) setLayout(dev.layout);
+    if (dev.pinned) setPinned(dev.pinned);
+  }, [dev]);
+
+  const value = useMemo<StageView>(
+    () => ({
+      layout,
+      pinned,
+      mirror,
+      setLayout: (next) => {
+        setLayout(next);
+        if (next === "grid") setPinned(null);
+      },
+      togglePin: (participantId) => {
+        if (layout === "grid") {
+          setLayout("spotlight");
+          setPinned(participantId);
+          return;
+        }
+        setPinned((current) => (current === participantId ? null : participantId));
+      },
+      showContent: () => {
+        setLayout("spotlight");
+        setPinned(null);
+      },
+      setMirror,
+    }),
+    [layout, mirror, pinned],
+  );
+  return <StageViewContext.Provider value={value}>{children}</StageViewContext.Provider>;
+}
+
+export function useStageView(): StageView {
+  const view = useContext(StageViewContext);
+  if (!view) throw new Error("useStageView must be used inside <Chalk>.");
+  return view;
+}

package/src/status/CallOverlays.tsx

@@ -0,0 +1,47 @@
+import { useEffect } from "react";
+import { StyleSheet, View } from "react-native";
+import { useBackHandler } from "../frame/back-handler";
+import { useChat, useRecording } from "../hooks/space-hooks";
+import { Limbo, type LimboState } from "../limbo/Limbo";
+import { Veil, type VeilLevel } from "../limbo/Veil";
+import { useToasts } from "../primitives/toast/ToastStack";
+import type { CallScreen } from "./call-screen";
+import { StatusPage } from "./StatusPage";
+
+export type CallOverlaysProps = {
+  readonly screen: CallScreen;
+  readonly callName: string;
+  /** The app restarted to rejoin, so the card says "Rejoining" instead of "Joining". */
+  readonly rejoining: boolean;
+  /** A phone call has the microphone (T6). */
+  readonly onHold: boolean;
+  readonly onRejoin: () => void;
+  readonly onHome: () => void;
+};
+
+/**
+ * The overlays layer: the veil and limbo card while the call joins, reconnects or waits on a phone
+ * call, and the status page once it's over. Android back on a status page goes Home.
+ */
+export function CallOverlays({ screen, callName, rejoining, onHold, onRejoin, onHome }: CallOverlaysProps): React.JSX.Element {
+  const recording = useRecording().current?.status === "recording";
+  const queuedMessages = useChat().pendingSends.filter((send) => send.status === "queued").length;
+  useBackHandler(screen.kind === "status", onHome);
+  // Notices belong to the live call; a status page or a fresh join starts without them.
+  const { clear } = useToasts();
+  const clearsNotices = screen.kind === "status" || screen.kind === "joining";
+  useEffect(() => {
+    if (clearsNotices) clear();
+  }, [clear, clearsNotices]);
+
+  const limbo: LimboState | null = screen.kind === "joining" ? { kind: "joining", rejoining } : screen.kind === "reconnecting" ? { kind: "reconnecting", queuedMessages } : screen.kind === "call" && onHold ? { kind: "hold" } : null;
+  const veil: VeilLevel = limbo === null ? "none" : limbo.kind === "joining" ? "limbo" : "paused";
+
+  return (
+    <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
+      <Veil level={screen.kind === "status" ? "none" : veil} />
+      {limbo ? <Limbo callName={callName} recording={recording} state={limbo} /> : null}
+      {screen.kind === "status" ? <StatusPage callName={callName} onHome={onHome} onRejoin={onRejoin} outcome={screen.outcome} /> : null}
+    </View>
+  );
+}

package/src/status/ChalkArrival.tsx

@@ -0,0 +1,53 @@
+import { StyleSheet, View } from "react-native";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+import { useBackHandler } from "../frame/back-handler";
+import { Limbo } from "../limbo/Limbo";
+import { ThemeProvider, useTheme } from "../theme/theme";
+import type { ColorScheme } from "../theme/tokens";
+import { StatusPage } from "./StatusPage";
+
+/** Where a person stands before the call lets them in: waiting for the host, turned away, or the call is full. */
+export type ArrivalState = "knocking" | "refused" | "full";
+
+export type ChalkArrivalProps = {
+  readonly state: ArrivalState;
+  /** The call's name, such as "Q9 team". */
+  readonly callName: string;
+  /** Dark by default, like `Chalk`. */
+  readonly colorScheme?: ColorScheme;
+  /** Stops waiting (Cancel while knocking, Android back). */
+  readonly onCancel: () => void;
+  /** Knocks again after a refusal, or tries again once a full call has room. */
+  readonly onRetry: () => void;
+  /** Recording consent shows while knocking on a recorded call. */
+  readonly recording?: boolean;
+};
+
+/**
+ * The screens before `Chalk` joins (T3, T4, A7), for an app that lets a person ask to join a call
+ * through an invite link: "Asking to join" with Cancel, "The host didn’t let you in" with Ask again,
+ * and "This call is full" with Try again and Home.
+ */
+export function ChalkArrival({ colorScheme = "dark", ...props }: ChalkArrivalProps): React.JSX.Element {
+  return (
+    <SafeAreaProvider>
+      <ThemeProvider colorScheme={colorScheme}>
+        <ArrivalScreen {...props} />
+      </ThemeProvider>
+    </SafeAreaProvider>
+  );
+}
+
+export function ArrivalScreen({ state, callName, onCancel, onRetry, recording = false }: Omit<ChalkArrivalProps, "colorScheme">): React.JSX.Element {
+  const { colors } = useTheme();
+  useBackHandler(true, onCancel);
+  return (
+    <View style={[styles.screen, { backgroundColor: colors.canvas }]} testID="arrival.screen">
+      {state === "full" ? <StatusPage callName={callName} onHome={onCancel} onRejoin={onRetry} outcome="full" /> : <Limbo callName={callName} recording={recording} state={state === "knocking" ? { kind: "knocking", onCancel } : { kind: "refused", onAskAgain: onRetry }} />}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1 },
+});

package/src/status/StatusPage.tsx

@@ -0,0 +1,123 @@
+import { forwardRef, memo, useEffect, useRef } from "react";
+import { AccessibilityInfo, findNodeHandle, Pressable, StyleSheet, View } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { useMeasuredRef } from "../frame/measurement";
+import { Icon, type IconName } from "../icons/Icon";
+import { usePressAnimation } from "../motion/press";
+import { ChalkText } from "../primitives/ChalkText";
+import { useTheme } from "../theme/theme";
+import { fontFamilies } from "../theme/tokens";
+
+/** The ways a call ends for you (A3 to A7). */
+export type CallOutcome = "left" | "ended" | "failed" | "removed" | "exited" | "full";
+
+export type StatusPageProps = {
+  readonly outcome: CallOutcome;
+  readonly callName: string;
+  readonly onRejoin: () => void;
+  readonly onHome: () => void;
+};
+
+type Action = "rejoin" | "home";
+
+type Page = { readonly title: string; readonly detail?: string; readonly actions: readonly Action[]; readonly rejoinLabel?: string };
+
+/** The mockup's copy for each outcome (`SP` in renderLimbo). */
+function pageFor(outcome: CallOutcome, callName: string): Page {
+  switch (outcome) {
+    case "left":
+      return { title: `You left ${callName}`, actions: ["rejoin", "home"] };
+    case "ended":
+      return { title: "The call ended", actions: ["rejoin", "home"] };
+    case "failed":
+      return { title: `Couldn’t connect to ${callName}`, detail: "Check your internet connection, then try again.", actions: ["rejoin", "home"], rejoinLabel: "Try again" };
+    case "removed":
+      return { title: `You were removed from ${callName}`, detail: "The host removed you from this call.", actions: ["home"] };
+    case "exited":
+      return { title: `You’re no longer in ${callName}`, actions: ["rejoin", "home"] };
+    case "full":
+      return { title: "This call is full", detail: `${callName} has reached 100 people. Ask the host to make room, then try again.`, actions: ["rejoin", "home"], rejoinLabel: "Try again" };
+  }
+}
+
+/**
+ * A full-screen status page on the canvas (`.status`): a title, an optional line saying what to do,
+ * and the ways forward as round actions with their names under them.
+ */
+export function StatusPage({ outcome, callName, onRejoin, onHome }: StatusPageProps): React.JSX.Element {
+  const { colors } = useTheme();
+  const page = pageFor(outcome, callName);
+  const pageStyle = [styles.page, { backgroundColor: colors.canvas }];
+  const ref = useMeasuredRef<View>("status.page", pageStyle);
+  const firstAction = useRef<View>(null);
+  // The mockup moves focus to the first action when the page appears.
+  useEffect(() => {
+    const node = firstAction.current && findNodeHandle(firstAction.current);
+    if (node) AccessibilityInfo.setAccessibilityFocus(node);
+  }, [outcome]);
+  return (
+    <View accessibilityViewIsModal ref={ref} style={pageStyle} testID="status.page">
+      <ChalkText accessibilityRole="header" style={styles.center} testID="status.title" variant="statusTitle">
+        {page.title}
+      </ChalkText>
+      {page.detail ? (
+        <ChalkText style={styles.center} testID="status.detail" tone="textMuted">
+          {page.detail}
+        </ChalkText>
+      ) : null}
+      <View style={styles.actions}>
+        {page.actions.map((action, index) =>
+          action === "rejoin" ? (
+            <StatusAction icon="retry" key={action} label={page.rejoinLabel ?? "Rejoin"} onPress={onRejoin} ref={index === 0 ? firstAction : undefined} testID="status.rejoin" />
+          ) : (
+            <StatusAction icon="home" key={action} label="Home" onPress={onHome} ref={index === 0 ? firstAction : undefined} testID="status.home" />
+          ),
+        )}
+      </View>
+    </View>
+  );
+}
+
+type StatusActionProps = {
+  readonly icon: IconName;
+  readonly label: string;
+  readonly onPress: () => void;
+  readonly testID: string;
+};
+
+/** `.act`: a 56 pt round button with its name under it; the round part presses like `.rb`. */
+const StatusAction = memo(
+  forwardRef<View, StatusActionProps>(function StatusAction({ icon, label, onPress, testID }, ref) {
+    const { colors } = useTheme();
+    const press = usePressAnimation("round");
+    const { down } = press;
+    const roundStyle = [styles.round, { backgroundColor: colors.raised }];
+    const roundRef = useMeasuredRef<View>(`${testID}.button`, roundStyle);
+    const raised = colors.raised;
+    const pressed = colors.pressed;
+    const background = useAnimatedStyle(() => {
+      "worklet";
+      return { backgroundColor: down.value ? pressed : raised };
+    });
+    return (
+      <Pressable accessibilityLabel={label} accessibilityRole="button" onPress={onPress} onPressIn={press.onPressIn} onPressOut={press.onPressOut} ref={ref} style={styles.action} testID={testID}>
+        <Animated.View ref={roundRef} style={[roundStyle, background, press.scaleStyle]}>
+          <Icon color={colors.text} name={icon} />
+        </Animated.View>
+        <ChalkText style={styles.actionLabel} testID={`${testID}.label`} tone="textSoft" variant="meta">
+          {label}
+        </ChalkText>
+      </Pressable>
+    );
+  }),
+);
+
+const styles = StyleSheet.create({
+  page: { ...StyleSheet.absoluteFillObject, alignItems: "center", justifyContent: "center", gap: 12, padding: 24 },
+  center: { textAlign: "center" },
+  actions: { flexDirection: "row", gap: 28, marginTop: 20 },
+  action: { alignItems: "center", gap: 8 },
+  round: { width: 56, height: 56, borderRadius: 28, alignItems: "center", justifyContent: "center" },
+  // `.act` is 13 pt at weight 500; the type scale has 13 pt only at 400 and 600.
+  actionLabel: { fontFamily: fontFamilies[500] },
+});

package/src/status/call-screen.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { callScreen } from "./call-screen";
+
+type ConnectionOptions = { readonly code?: "episode.ended" | "access.invalid"; readonly episodeEnded?: boolean; readonly removedByHost?: boolean };
+
+const connection = (status: Parameters<typeof callScreen>[0]["status"], { code, episodeEnded = false, removedByHost = false }: ConnectionOptions = {}) => ({
+  status,
+  episode: null,
+  lastError: code ? { code, recoverable: false, message: "" } : null,
+  episodeEnded,
+  removedByHost,
+});
+
+describe("callScreen", () => {
+  it("covers the call while it joins or reconnects", () => {
+    expect(callScreen(connection("joining"), false)).toEqual({ kind: "joining" });
+    expect(callScreen(connection("reconnecting"), false)).toEqual({ kind: "reconnecting" });
+    expect(callScreen(connection("live"), false)).toEqual({ kind: "call" });
+  });
+
+  it("shows the person's own leave as left, even when the leave call failed", () => {
+    expect(callScreen(connection("left"), true)).toEqual({ kind: "status", outcome: "left" });
+    expect(callScreen(connection("left", { removedByHost: true }), true)).toEqual({ kind: "status", outcome: "left" });
+  });
+
+  it("shows removed only when the server reported a host removal", () => {
+    expect(callScreen(connection("left", { removedByHost: true }), false)).toEqual({ kind: "status", outcome: "removed" });
+  });
+
+  it("shows a neutral exit for any other exit nobody asked for", () => {
+    expect(callScreen(connection("left"), false)).toEqual({ kind: "status", outcome: "exited" });
+  });
+
+  it("shows the call ended when the Episode ends while the person is in it", () => {
+    expect(callScreen(connection("left", { episodeEnded: true }), false)).toEqual({ kind: "status", outcome: "ended" });
+    expect(callScreen(connection("left", { code: "episode.ended" }), false)).toEqual({ kind: "status", outcome: "ended" });
+  });
+
+  it("shows a failure as failed", () => {
+    expect(callScreen(connection("failed", { code: "access.invalid" }), false)).toEqual({ kind: "status", outcome: "failed" });
+  });
+});

package/src/status/call-screen.ts

@@ -0,0 +1,29 @@
+import type { ConnectionSlice } from "@q9labsai/chalk-client";
+import type { CallOutcome } from "./StatusPage";
+
+/** What covers the call: nothing, a limbo card over the veiled call, or a status page. */
+export type CallScreen = { readonly kind: "call" } | { readonly kind: "joining" } | { readonly kind: "reconnecting" } | { readonly kind: "status"; readonly outcome: CallOutcome };
+
+/**
+ * Reads the screen from the connection. `leftByChoice` is true from the moment the person presses
+ * Leave or End until they join again, so a leave whose call failed still reads as their choice.
+ * Only the server's own removal signal shows "removed"; any other exit nobody chose is `exited`.
+ */
+export function callScreen(connection: ConnectionSlice, leftByChoice: boolean): CallScreen {
+  if (connection.episodeEnded || connection.lastError?.code === "episode.ended") return { kind: "status", outcome: "ended" };
+  switch (connection.status) {
+    case "idle":
+    case "joining":
+      return { kind: "joining" };
+    case "reconnecting":
+      return { kind: "reconnecting" };
+    case "live":
+    case "leaving":
+      return { kind: "call" };
+    case "left":
+      if (leftByChoice) return { kind: "status", outcome: "left" };
+      return { kind: "status", outcome: connection.removedByHost ? "removed" : "exited" };
+    case "failed":
+      return { kind: "status", outcome: "failed" };
+  }
+}

package/src/theme/theme.tsx

@@ -0,0 +1,28 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { elevations, palettes, type ColorScheme, type Elevation, type Palette } from "./tokens";
+
+export type Theme = {
+  readonly scheme: ColorScheme;
+  readonly colors: Palette;
+  readonly elevation: Elevation;
+};
+
+const themes: Readonly<Record<ColorScheme, Theme>> = {
+  dark: { scheme: "dark", colors: palettes.dark, elevation: elevations.dark },
+  light: { scheme: "light", colors: palettes.light, elevation: elevations.light },
+};
+
+const ThemeContext = createContext<Theme>(themes.dark);
+
+/** Supplies one of two frozen theme objects, so consumers re-render only when the scheme changes. */
+export function ThemeProvider({ colorScheme, children }: { readonly colorScheme: ColorScheme; readonly children: ReactNode }): React.JSX.Element {
+  return <ThemeContext.Provider value={themes[colorScheme]}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): Theme {
+  return useContext(ThemeContext);
+}
+
+export function themeFor(colorScheme: ColorScheme): Theme {
+  return themes[colorScheme];
+}