@q9labsai/chalk-react-native 4.1.17 → 5.0.1

package/src/frame/CallFrame.tsx

@@ -0,0 +1,209 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Pressable, StatusBar, StyleSheet, View } from "react-native";
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { useAndroidCallService } from "../components/useAndroidCallService";
+import { useSpaceClient } from "../context/space-client-context";
+import { Dock } from "../dock/Dock";
+import { LeaveMenu } from "../dock/LeaveMenu";
+import { MoreSheet } from "../dock/MoreSheet";
+import { haptics } from "../haptics/haptics";
+import { CallDetailsSheet } from "../header/CallDetailsSheet";
+import { Header } from "../header/Header";
+import { useCan, useConnection, useMedia } from "../hooks/space-hooks";
+import { timings } from "../motion/motion";
+import { ToastStack, useToasts } from "../primitives/toast/ToastStack";
+import { ChatNotices } from "../sheets/people-chat/ChatNotices";
+import { PeopleChatSheet } from "../sheets/people-chat/PeopleChatSheet";
+import { playSound } from "../sounds/sounds";
+import { Stage } from "../stage/Stage";
+import { CallOverlays } from "../status/CallOverlays";
+import { ArrivalScreen } from "../status/ChalkArrival";
+import { callScreen } from "../status/call-screen";
+import { useTheme } from "../theme/theme";
+import { durations } from "../theme/tokens";
+import { useCallEventToasts, type Permission } from "../toasts/CallEventToasts";
+import { useDevScenario } from "./dev-scenario";
+import { useDeviceLayout } from "./device-layout";
+import { PortalHost, usePortalCount } from "./portal";
+import { useMeasuredRef } from "./measurement";
+import { usePreferences } from "./preferences";
+import { frameRegions } from "./regions";
+
+export type CallFrameProps = {
+  readonly displayName?: string;
+  readonly callName?: string;
+  readonly inviteLink?: string;
+  readonly onLeave?: () => void;
+  readonly onOpenSettings?: (permission: Permission) => void;
+  readonly resumedAfterSettings?: Permission;
+  readonly onRejoin: () => void;
+};
+
+type OpenSheet = "more" | "people" | "chat" | "details" | null;
+
+/**
+ * The call's frame: header, stage and dock regions, then the sheets layer, the limbo and status
+ * overlays, the menus layer and the toasts layer, each inside the safe area for the current
+ * arrangement. Each region lives in its own folder so the part lanes can work in parallel.
+ */
+export function CallFrame({ displayName, callName = "Call", inviteLink, onLeave, onOpenSettings, onRejoin, resumedAfterSettings }: CallFrameProps): React.JSX.Element {
+  const client = useSpaceClient();
+  const connection = useConnection();
+  const media = useMedia();
+  const { colors, scheme } = useTheme();
+  const layout = useDeviceLayout();
+  const { soundsEnabled } = usePreferences();
+  const toasts = useToasts();
+  const callEvents = useCallEventToasts({ onOpenSettings, resumedAfterSettings });
+  const [leftByChoice, setLeftByChoice] = useState(false);
+  const [sheet, setSheet] = useState<OpenSheet>(null);
+  const moreRef = useRef<View>(null);
+  const leaveRef = useRef<View>(null);
+  const nameRef = useRef<View>(null);
+  const canEnd = useCan("endEpisode");
+  const [leaveMenuOpen, setLeaveMenuOpen] = useState(false);
+  const sheetCount = usePortalCount("sheets");
+  const menuCount = usePortalCount("menus");
+  const layered = sheetCount > 0 || menuCount > 0;
+  const regions = useMemo(() => frameRegions(layout.arrangement, layout.width, layout.height, layout.insets), [layout]);
+  const screenStyle = [styles.root, { backgroundColor: colors.canvas }];
+  const screenRef = useMeasuredRef<View>("frame.screen", screenStyle);
+
+  const join = useCallback(() => {
+    // A failed join shows up as `connection.status === "failed"` with `lastError`, which the status page reads.
+    setLeftByChoice(false);
+    client.join({ displayName, microphone: false, camera: false }).catch(() => undefined);
+  }, [client, displayName]);
+  useEffect(() => {
+    if (client.getSnapshot().connection.status === "idle") join();
+  }, [client, join]);
+  useAndroidCallService();
+
+  const microphoneOn = media.local.microphone.state === "enabled";
+  const cameraOn = media.local.camera.state === "enabled";
+  const { noteOwnMicrophoneChange, reportMediaFailure } = callEvents;
+  const toggleMicrophone = useCallback(() => {
+    haptics.mute();
+    playSound(microphoneOn ? "mute" : "unmute", soundsEnabled);
+    if (microphoneOn) noteOwnMicrophoneChange();
+    const turnOn = () => client.media.setMicrophoneEnabled(true).catch((cause: unknown) => reportMediaFailure("microphone", cause, turnOn));
+    if (microphoneOn) client.media.setMicrophoneEnabled(false).catch(() => toasts.show({ kind: "error", dismissible: true, message: "Couldn’t mute your microphone." }));
+    else void turnOn();
+  }, [client, microphoneOn, noteOwnMicrophoneChange, reportMediaFailure, soundsEnabled, toasts]);
+  const toggleCamera = useCallback(() => {
+    const turnOn = () => client.media.setCameraEnabled(true).catch((cause: unknown) => reportMediaFailure("camera", cause, turnOn));
+    if (cameraOn) client.media.setCameraEnabled(false).catch(() => toasts.show({ kind: "error", dismissible: true, message: "Couldn’t turn off your camera." }));
+    else void turnOn();
+  }, [cameraOn, client, reportMediaFailure, toasts]);
+  const exit = useCallback(
+    (how: "leave" | "end") => {
+      setSheet(null);
+      setLeaveMenuOpen(false);
+      setLeftByChoice(true);
+      // The status page (A3, A4) follows; its Home button calls `onLeave`. A failed leave is still the person's choice.
+      (how === "end" ? client.endEpisode() : client.leave()).catch(() => {
+        toasts.show({ kind: "error", dismissible: true, message: how === "end" ? "Couldn’t end the call." : "Couldn’t leave the call." });
+      });
+    },
+    [client, toasts],
+  );
+  const pressLeave = useCallback(() => {
+    haptics.leave();
+    if (canEnd) setLeaveMenuOpen((open) => !open);
+    else exit("leave");
+  }, [canEnd, exit]);
+
+  const devScenario = useDevScenario();
+  useEffect(() => {
+    if (devScenario.sheet && devScenario.sheet !== "route") setSheet(devScenario.sheet);
+    if (devScenario.menu === "leave") setLeaveMenuOpen(true);
+  }, [devScenario]);
+
+  const chrome = useLandscapeChrome(layout.arrangement === "landscape" && sheet === null && !layered);
+  const forced = devScenario.callState;
+  const screen = forced === "hold" ? { kind: "call" as const } : forced === "left" || forced === "ended" || forced === "failed" || forced === "removed" || forced === "exited" ? { kind: "status" as const, outcome: forced } : callScreen(connection, leftByChoice);
+
+  return (
+    <View ref={screenRef} style={screenStyle} testID="frame.screen">
+      <StatusBar barStyle={scheme === "dark" ? "light-content" : "dark-content"} />
+      <View accessibilityElementsHidden={layered} importantForAccessibility={layered ? "no-hide-descendants" : "auto"} style={StyleSheet.absoluteFill}>
+        <Stage frame={regions.stage} onOpenPeople={() => setSheet("people")} />
+        {chrome.hidden ? <Pressable accessibilityLabel="Show call controls" onPress={chrome.show} style={StyleSheet.absoluteFill} testID="frame.show-controls" /> : null}
+        <Animated.View pointerEvents={chrome.hidden ? "none" : "box-none"} style={[styles.region, frameStyle(regions.header), chrome.style]}>
+          <Header arrangement={layout.arrangement} callName={callName} detailsOpen={sheet === "details"} onOpenDetails={() => setSheet("details")} ref={nameRef} />
+        </Animated.View>
+        <Animated.View pointerEvents={chrome.hidden ? "none" : "box-none"} style={[styles.region, frameStyle(regions.dock), chrome.style]}>
+          <Dock
+            arrangement={layout.arrangement}
+            cameraOn={cameraOn}
+            microphoneOn={microphoneOn}
+            leaveOpen={canEnd ? leaveMenuOpen : undefined}
+            leaveRef={leaveRef}
+            moreOpen={sheet === "more"}
+            moreRef={moreRef}
+            onLeave={pressLeave}
+            onOpenMore={() => setSheet("more")}
+            onToggleCamera={toggleCamera}
+            onToggleMicrophone={toggleMicrophone}
+          />
+        </Animated.View>
+      </View>
+      <View pointerEvents="box-none" style={StyleSheet.absoluteFill} testID="frame.sheets">
+        {/* Focus goes back to More only once no sheet is open, so switching to People keeps it there. */}
+        <MoreSheet inviteLink={inviteLink} onClose={() => setSheet(null)} onOpenChat={() => setSheet("chat")} onOpenPeople={() => setSheet("people")} open={sheet === "more"} returnFocusRef={sheet === null ? moreRef : undefined} />
+        <CallDetailsSheet callName={callName} inviteLink={inviteLink} onClose={() => setSheet(null)} open={sheet === "details"} returnFocusRef={nameRef} />
+        <PeopleChatSheet onClose={() => setSheet(null)} onTabChange={setSheet} open={sheet === "people" || sheet === "chat"} returnFocusRef={sheet === null ? moreRef : undefined} tab={sheet === "chat" ? "chat" : "people"} />
+        <PortalHost layer="sheets" />
+      </View>
+      <View pointerEvents="box-none" style={StyleSheet.absoluteFill} testID="frame.overlays">
+        {forced === "knocking" || forced === "refused" || forced === "full" ? (
+          <ArrivalScreen callName={callName} onCancel={() => onLeave?.()} onRetry={join} state={forced} />
+        ) : (
+          <CallOverlays callName={callName} onHold={forced === "hold"} onHome={() => onLeave?.()} onRejoin={onRejoin} rejoining={resumedAfterSettings !== undefined} screen={screen} />
+        )}
+      </View>
+      <View pointerEvents="box-none" style={StyleSheet.absoluteFill} testID="frame.menus">
+        <LeaveMenu anchorRef={leaveRef} onClose={() => setLeaveMenuOpen(false)} onEnd={() => exit("end")} onLeave={() => exit("leave")} open={leaveMenuOpen} />
+        <PortalHost layer="menus" />
+      </View>
+      <ToastStack />
+      <ChatNotices chatVisible={sheet === "chat"} onOpenChat={() => setSheet("chat")} sheetOpen={sheet === "people" || sheet === "chat"} />
+    </View>
+  );
+}
+
+/** Phone landscape (L1): the controls fade after 4 s and come back on a tap. */
+function useLandscapeChrome(fades: boolean): { readonly hidden: boolean; readonly show: () => void; readonly style: ReturnType<typeof useAnimatedStyle> } {
+  const [hidden, setHidden] = useState(false);
+  const [shownAt, setShownAt] = useState(0);
+  const opacity = useSharedValue(1);
+  useEffect(() => {
+    opacity.value = withTiming(hidden ? 0 : 1, timings.fade);
+  }, [hidden, opacity]);
+  useEffect(() => {
+    if (!fades) {
+      setHidden(false);
+      return;
+    }
+    const timer = setTimeout(() => setHidden(true), durations.landscapeHide);
+    return () => clearTimeout(timer);
+  }, [fades, shownAt]);
+  const show = useCallback(() => {
+    setHidden(false);
+    setShownAt(Date.now());
+  }, []);
+  const style = useAnimatedStyle(() => {
+    "worklet";
+    return { opacity: opacity.value };
+  });
+  return { hidden, show, style };
+}
+
+function frameStyle(frame: { readonly x: number; readonly y: number; readonly width: number; readonly height: number }) {
+  return { left: frame.x, top: frame.y, width: frame.width, height: frame.height };
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1 },
+  region: { position: "absolute" },
+});

package/src/frame/Chalk.tsx

@@ -0,0 +1,83 @@
+import type { SpaceClient } from "@q9labsai/chalk-client";
+import { useEffect } from "react";
+import { StyleSheet } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+import { ChalkProvider } from "../context/space-client-context";
+import { ToastProvider } from "../primitives/toast/ToastStack";
+import { releaseSounds } from "../sounds/sounds";
+import { ThemeProvider } from "../theme/theme";
+import type { ColorScheme } from "../theme/tokens";
+import type { Permission } from "../toasts/CallEventToasts";
+import { StageViewProvider } from "../stage/stage-view";
+import { CallFrame } from "./CallFrame";
+import { DeviceLayoutProvider } from "./device-layout";
+import { PortalProvider } from "./portal";
+import { PreferencesProvider } from "./preferences";
+
+export type ChalkProps = {
+  /** The call's client. The app creates it with `createNativeSpaceClient` and disposes it; `Chalk` joins it. */
+  readonly client: SpaceClient;
+  /** The name others see. Without it the server's stored name is used. */
+  readonly displayName?: string;
+  /** The call's name in the header, such as "Q9 team". */
+  readonly callName?: string;
+  /** The call's link, which More and the call details offer to copy, share and show as a QR code. */
+  readonly inviteLink?: string;
+  /** Dark by default. Set it with `onColorSchemeChange` to keep the person's choice. */
+  readonly colorScheme?: ColorScheme;
+  readonly onColorSchemeChange?: (colorScheme: ColorScheme) => void;
+  /** Call sounds, on by default. Set it with `onSoundsEnabledChange` to keep the person's choice. */
+  readonly soundsEnabled?: boolean;
+  readonly onSoundsEnabledChange?: (enabled: boolean) => void;
+  /** Called when the person is done with the call: Home on the page that shows after they leave, the call ends, or it fails. */
+  readonly onLeave?: () => void;
+  /**
+   * Called just before Open Settings takes the person to the system settings to allow the microphone
+   * or camera. iOS restarts the app when a permission changes, so store the call here and, on the
+   * next launch, open it again with `resumedAfterSettings`.
+   */
+  readonly onOpenSettings?: (permission: Permission) => void;
+  /** Set when the app reopens the call after Open Settings; the call says "Rejoining" and then that it can use the device now. */
+  readonly resumedAfterSettings?: Permission;
+  /**
+   * Called when the person chooses Rejoin or Try again on the page that shows after they leave, the call
+   * ends, or it fails. That client can't join again: give the arrival back, then render `Chalk` with a new client.
+   */
+  readonly onRejoin: () => void;
+};
+
+/**
+ * The drop-in call view. It fills the screen it's given, joins the call muted and with the camera
+ * off, and draws everything inside the safe area in portrait, landscape and on iPad.
+ */
+export function Chalk({ client, colorScheme, onColorSchemeChange, soundsEnabled, onSoundsEnabledChange, ...frame }: ChalkProps): React.JSX.Element {
+  useEffect(() => releaseSounds, []);
+  return (
+    <GestureHandlerRootView style={styles.root}>
+      <SafeAreaProvider>
+        <PreferencesProvider colorScheme={colorScheme} onColorSchemeChange={onColorSchemeChange} onSoundsEnabledChange={onSoundsEnabledChange} soundsEnabled={soundsEnabled}>
+          {(preferences) => (
+            <ThemeProvider colorScheme={preferences.colorScheme}>
+              <DeviceLayoutProvider>
+                <PortalProvider>
+                  <ToastProvider>
+                    <ChalkProvider client={client}>
+                      <StageViewProvider>
+                        <CallFrame {...frame} />
+                      </StageViewProvider>
+                    </ChalkProvider>
+                  </ToastProvider>
+                </PortalProvider>
+              </DeviceLayoutProvider>
+            </ThemeProvider>
+          )}
+        </PreferencesProvider>
+      </SafeAreaProvider>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1 },
+});

package/src/frame/back-handler.ts

@@ -0,0 +1,19 @@
+import { useEffect, useRef } from "react";
+import { BackHandler } from "react-native";
+
+/**
+ * While `active`, Android's back gesture calls `onBack` and stops there. Handlers run newest
+ * first, so the sheet or menu opened last closes first.
+ */
+export function useBackHandler(active: boolean, onBack: () => void): void {
+  const latest = useRef(onBack);
+  latest.current = onBack;
+  useEffect(() => {
+    if (!active) return;
+    const subscription = BackHandler.addEventListener("hardwareBackPress", () => {
+      latest.current();
+      return true;
+    });
+    return () => subscription.remove();
+  }, [active]);
+}

package/src/frame/dev-scenario.ts

@@ -0,0 +1,48 @@
+import { useSyncExternalStore, type ReactNode } from "react";
+import type { ArrivalState } from "../status/ChalkArrival";
+import type { CallOutcome } from "../status/StatusPage";
+import type { AudioRoutes } from "../dock/audio-route";
+
+/** UI-only state a development harness forces on the call. Nothing sets it in a real call. */
+export type DevScenario = {
+  /** Opens this sheet as if the user had opened it; the user can still close it. */
+  readonly sheet?: "more" | "people" | "chat" | "details" | "route";
+  /** Opens this menu as if the user had opened it. */
+  readonly menu?: "leave" | "route";
+  /** Content drawn in a tile in place of the camera, keyed by participant id. */
+  readonly videoSlots?: Readonly<Record<string, ReactNode>>;
+  /** Shows a call state the fixture client can't reach: a screen before joining, a status page, or a phone call holding the call. */
+  readonly callState?: ArrivalState | CallOutcome | "hold";
+  /** Content drawn in place of a person's shared screen, keyed by the sharer's participant id. */
+  readonly screenSlots?: Readonly<Record<string, ReactNode>>;
+  /** The shared screen's width over height (S1 to S4). A real share is drawn as 16:9. */
+  readonly shareAspect?: number;
+  /** Spotlight (G1) or Grid (G2), as if the user had chosen it. */
+  readonly layout?: "spotlight" | "grid";
+  /** Pins this participant, as if the user had pinned them. */
+  readonly pinned?: string;
+  /** Audio outputs in place of the device's, such as a Bluetooth headset on a simulator (K3). */
+  readonly audioRoutes?: AudioRoutes;
+};
+
+const empty: DevScenario = {};
+let scenario = empty;
+const listeners = new Set<() => void>();
+
+export function setDevScenario(next: DevScenario | null): void {
+  scenario = next ?? empty;
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function useDevScenario(): DevScenario {
+  return useSyncExternalStore(
+    subscribe,
+    () => scenario,
+    () => scenario,
+  );
+}

package/src/frame/device-layout.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { useWindowDimensions } from "react-native";
+import { useSafeAreaInsets, type EdgeInsets } from "react-native-safe-area-context";
+import { arrangementFor, type Arrangement } from "./regions";
+
+export type DeviceLayout = {
+  readonly arrangement: Arrangement;
+  /** True for `portrait` and `landscape`: the phone look (bottom sheets, 52 pt dock, 48 pt menu rows). */
+  readonly phone: boolean;
+  readonly width: number;
+  readonly height: number;
+  readonly insets: EdgeInsets;
+};
+
+const DeviceLayoutContext = createContext<DeviceLayout | null>(null);
+
+export function DeviceLayoutProvider({ children }: { readonly children: ReactNode }): React.JSX.Element {
+  const { width, height } = useWindowDimensions();
+  const insets = useSafeAreaInsets();
+  const value = useMemo<DeviceLayout>(() => {
+    const arrangement = arrangementFor(width, height);
+    return { arrangement, phone: arrangement !== "pad", width, height, insets };
+  }, [height, insets, width]);
+  return <DeviceLayoutContext.Provider value={value}>{children}</DeviceLayoutContext.Provider>;
+}
+
+export function useDeviceLayout(): DeviceLayout {
+  const layout = useContext(DeviceLayoutContext);
+  if (!layout) throw new Error("Chalk primitives must be rendered inside <Chalk>.");
+  return layout;
+}

package/src/frame/measurement.ts

@@ -0,0 +1,44 @@
+import { useEffect, useRef, type RefObject } from "react";
+import { StyleSheet, type StyleProp, type TextStyle, type ViewStyle } from "react-native";
+
+export type MeasuredFrame = { readonly x: number; readonly y: number; readonly width: number; readonly height: number };
+
+/** A host view's frame in window points and the style it declares at rest (animated values excluded). */
+export type Measurement = { readonly frame: MeasuredFrame; readonly style: TextStyle };
+
+/** Receives each measured testID while it's mounted; returns the function that forgets it. */
+export type MeasurementRegistry = (testID: string, measure: () => Promise<Measurement>) => () => void;
+
+type MeasurableNode = { measureInWindow: (callback: (x: number, y: number, width: number, height: number) => void) => void };
+
+let registry: MeasurementRegistry | null = null;
+
+/**
+ * Development tooling only: the app's parity harness installs a registry before it renders
+ * `Chalk`, and the call's regions and primitives report their frames and declared styles to it.
+ * Nothing is measured while no registry is installed.
+ */
+export function setMeasurementRegistry(next: MeasurementRegistry | null): void {
+  registry = next;
+}
+
+/** A ref for the host view that carries `testID`; attach it to that view. */
+export function useMeasuredRef<TNode extends MeasurableNode>(testID: string | undefined, style: StyleProp<ViewStyle | TextStyle>): RefObject<TNode | null> {
+  const ref = useRef<TNode>(null);
+  useEffect(() => {
+    if (!registry || !testID) return;
+    const declared = StyleSheet.flatten(style) ?? {};
+    return registry(
+      testID,
+      () =>
+        new Promise((resolve, reject) => {
+          if (!ref.current) {
+            reject(new Error(`Unmounted testID: ${testID}`));
+            return;
+          }
+          ref.current.measureInWindow((x, y, width, height) => resolve({ frame: { x, y, width, height }, style: declared }));
+        }),
+    );
+  }, [style, testID]);
+  return ref;
+}

package/src/frame/portal.tsx

@@ -0,0 +1,107 @@
+import { createContext, Fragment, useContext, useLayoutEffect, useRef, useState, useSyncExternalStore, type ReactNode } from "react";
+
+/** Layers above the call, bottom to top. Sheets sit under the limbo and status overlays; menus and toasts sit above everything. */
+export type PortalLayer = "sheets" | "menus" | "toasts";
+
+type Entry = { readonly key: number; readonly node: ReactNode };
+
+type PortalStore = {
+  readonly set: (layer: PortalLayer, key: number, node: ReactNode) => void;
+  readonly remove: (layer: PortalLayer, key: number) => void;
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly entries: (layer: PortalLayer) => readonly Entry[];
+};
+
+function createPortalStore(): PortalStore {
+  let layers: Readonly<Record<PortalLayer, readonly Entry[]>> = { sheets: [], menus: [], toasts: [] };
+  const listeners = new Set<() => void>();
+  const publish = (layer: PortalLayer, next: readonly Entry[]) => {
+    layers = { ...layers, [layer]: next };
+    for (const listener of listeners) listener();
+  };
+  return {
+    set(layer, key, node) {
+      const current = layers[layer];
+      const index = current.findIndex((entry) => entry.key === key);
+      publish(layer, index < 0 ? [...current, { key, node }] : current.map((entry) => (entry.key === key ? { key, node } : entry)));
+    },
+    remove(layer, key) {
+      publish(
+        layer,
+        layers[layer].filter((entry) => entry.key !== key),
+      );
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    entries: (layer) => layers[layer],
+  };
+}
+
+const PortalContext = createContext<PortalStore | null>(null);
+
+export function PortalProvider({ children }: { readonly children: ReactNode }): React.JSX.Element {
+  const [store] = useState(createPortalStore);
+  return <PortalContext.Provider value={store}>{children}</PortalContext.Provider>;
+}
+
+function usePortalStore(): PortalStore {
+  const store = useContext(PortalContext);
+  if (!store) throw new Error("Chalk portals must be rendered inside <Chalk>.");
+  return store;
+}
+
+let nextKey = 0;
+
+/**
+ * Renders its children in one of the frame's layers, so a sheet or menu opened deep in the tree
+ * draws above the whole call. Context providers between `<Chalk>` and the portal don't reach the
+ * children; pass what they need as props.
+ */
+export function Portal({ layer, children }: { readonly layer: PortalLayer; readonly children: ReactNode }): null {
+  const store = usePortalStore();
+  const key = useRef(-1);
+  if (key.current < 0) key.current = nextKey++;
+  useLayoutEffect(() => {
+    store.set(layer, key.current, children);
+  });
+  useLayoutEffect(() => {
+    const own = key.current;
+    return () => store.remove(layer, own);
+  }, [layer, store]);
+  return null;
+}
+
+export function PortalHost({ layer }: { readonly layer: PortalLayer }): React.JSX.Element {
+  const entries = usePortalEntries(layer);
+  return (
+    <>
+      {entries.map((entry) => (
+        <Fragment key={entry.key}>{entry.node}</Fragment>
+      ))}
+    </>
+  );
+}
+
+function usePortalEntries(layer: PortalLayer): readonly Entry[] {
+  const store = usePortalStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    () => store.entries(layer),
+    () => store.entries(layer),
+  );
+}
+
+/**
+ * How many portals a layer holds. Portals publish on every render, so an ancestor of a portal must
+ * read this count, not the entries, or each publish re-renders the portal and loops.
+ */
+export function usePortalCount(layer: PortalLayer): number {
+  const store = usePortalStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    () => store.entries(layer).length,
+    () => store.entries(layer).length,
+  );
+}

package/src/frame/preferences.tsx

@@ -0,0 +1,48 @@
+import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from "react";
+import type { ColorScheme } from "../theme/tokens";
+
+/** Choices the person makes inside the call. The app stores them; `Chalk` reports every change. */
+export type CallPreferences = {
+  readonly colorScheme: ColorScheme;
+  readonly setColorScheme: (scheme: ColorScheme) => void;
+  readonly soundsEnabled: boolean;
+  readonly setSoundsEnabled: (enabled: boolean) => void;
+};
+
+const PreferencesContext = createContext<CallPreferences | null>(null);
+
+type ProviderProps = {
+  readonly colorScheme?: ColorScheme;
+  readonly onColorSchemeChange?: (scheme: ColorScheme) => void;
+  readonly soundsEnabled?: boolean;
+  readonly onSoundsEnabledChange?: (enabled: boolean) => void;
+  readonly children: (preferences: CallPreferences) => ReactNode;
+};
+
+/** Each preference is controlled when its prop is set, and kept inside the call otherwise. */
+export function PreferencesProvider({ colorScheme, onColorSchemeChange, soundsEnabled, onSoundsEnabledChange, children }: ProviderProps): React.JSX.Element {
+  const [ownScheme, setOwnScheme] = useState<ColorScheme>("dark");
+  const [ownSounds, setOwnSounds] = useState(true);
+  const setColorScheme = useCallback(
+    (scheme: ColorScheme) => {
+      setOwnScheme(scheme);
+      onColorSchemeChange?.(scheme);
+    },
+    [onColorSchemeChange],
+  );
+  const setSoundsEnabled = useCallback(
+    (enabled: boolean) => {
+      setOwnSounds(enabled);
+      onSoundsEnabledChange?.(enabled);
+    },
+    [onSoundsEnabledChange],
+  );
+  const value = useMemo<CallPreferences>(() => ({ colorScheme: colorScheme ?? ownScheme, setColorScheme, soundsEnabled: soundsEnabled ?? ownSounds, setSoundsEnabled }), [colorScheme, ownScheme, ownSounds, setColorScheme, setSoundsEnabled, soundsEnabled]);
+  return <PreferencesContext.Provider value={value}>{children(value)}</PreferencesContext.Provider>;
+}
+
+export function usePreferences(): CallPreferences {
+  const preferences = useContext(PreferencesContext);
+  if (!preferences) throw new Error("usePreferences must be used inside <Chalk>.");
+  return preferences;
+}

package/src/frame/regions.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { arrangementFor, frameRegions } from "./regions";
+
+describe("frameRegions", () => {
+  it("matches the mockup's D1 iPhone portrait stage", () => {
+    const { header, stage, dock } = frameRegions("portrait", 393, 852, { top: 59, bottom: 34, left: 0, right: 0 });
+    expect(header).toEqual({ x: 0, y: 59, width: 393, height: 52 });
+    expect(stage).toEqual({ x: 8, y: 111, width: 377, height: 852 - 111 - (34 + 8 + 52 + 14) - 8 });
+    expect(dock.y + dock.height).toBe(852 - 34 - 14);
+  });
+
+  it("gives the phone stage the whole screen in landscape, inside the side insets", () => {
+    const { stage } = frameRegions("landscape", 852, 393, { top: 0, bottom: 21, left: 59, right: 59 });
+    expect(stage).toEqual({ x: 67, y: 8, width: 852 - 118 - 16, height: 393 - 8 - 21 - 4 });
+  });
+
+  it("starts the landscape header and stage below the top inset, as portrait does", () => {
+    const { header, stage } = frameRegions("landscape", 852, 393, { top: 24, bottom: 0, left: 0, right: 0 });
+    expect(header.y).toBe(32);
+    expect(stage).toEqual({ x: 8, y: 32, width: 852 - 16, height: 393 - 32 - 0 - 4 });
+  });
+
+  it("narrows the iPad stage when the side card is open", () => {
+    const closed = frameRegions("pad", 820, 1180, { top: 24, bottom: 20, left: 0, right: 0 });
+    const open = frameRegions("pad", 820, 1180, { top: 24, bottom: 20, left: 0, right: 0 }, true);
+    expect(closed.stage.width - open.stage.width).toBe(352);
+    expect(closed.stage.y).toBe(84);
+  });
+});
+
+describe("arrangementFor", () => {
+  it("gives the iPad the phone layout today, like a phone", () => {
+    expect(arrangementFor(820, 1180)).toBe("portrait");
+    expect(arrangementFor(1180, 820)).toBe("landscape");
+    expect(arrangementFor(375, 820)).toBe("portrait");
+    expect(arrangementFor(852, 393)).toBe("landscape");
+  });
+});