@q9labsai/chalk-react-native 4.1.17 → 5.0.1

package/src/dev.ts

@@ -0,0 +1,9 @@
+/**
+ * Development-only seams for a state harness and parity checks. Import this entry behind `__DEV__`
+ * with `require`, so Metro drops it, and everything only it reaches, from release bundles.
+ */
+export { setDevScenario } from "./frame/dev-scenario";
+export type { DevScenario } from "./frame/dev-scenario";
+export type { AudioRoute, AudioRouteKind, AudioRoutes } from "./dock/audio-route";
+export { setMeasurementRegistry } from "./frame/measurement";
+export type { MeasuredFrame, Measurement, MeasurementRegistry } from "./frame/measurement";

package/src/dock/Dock.tsx

@@ -0,0 +1,95 @@
+import { memo, useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import { StyleSheet, View } from "react-native";
+import { useDevScenario } from "../frame/dev-scenario";
+import type { Arrangement } from "../frame/regions";
+import { useMeasuredRef } from "../frame/measurement";
+import { announce } from "../primitives/announce";
+import { IconButton } from "../primitives/IconButton";
+import { useToasts } from "../primitives/toast/ToastStack";
+import { routeIcons, routeName, useAudioOutput, type AudioOutput } from "./audio-route";
+import { RoutePicker } from "./RoutePicker";
+
+export type DockProps = {
+  readonly arrangement: Arrangement;
+  readonly microphoneOn: boolean;
+  readonly cameraOn: boolean;
+  readonly onToggleMicrophone: () => void;
+  readonly onToggleCamera: () => void;
+  readonly onOpenMore: () => void;
+  readonly onLeave: () => void;
+  readonly moreOpen: boolean;
+  /** Set only when Leave opens a menu (hosts), so others hear a plain button. */
+  readonly leaveOpen?: boolean;
+  readonly moreRef: RefObject<View | null>;
+  readonly leaveRef: RefObject<View | null>;
+};
+
+/**
+ * The call controls (`.dock`): microphone, camera, audio output with its name under it (R1),
+ * More and Leave. Spread across the phone in portrait, centred with 14 pt gaps in landscape.
+ */
+export const Dock = memo(function Dock({ arrangement, microphoneOn, cameraOn, onToggleMicrophone, onToggleCamera, onOpenMore, onLeave, moreOpen, leaveOpen, moreRef, leaveRef }: DockProps) {
+  const size = arrangement === "pad" ? 44 : 52;
+  const dockStyle = [styles.dock, arrangement === "pad" ? styles.pad : arrangement === "landscape" ? styles.landscape : styles.portrait];
+  const dockRef = useMeasuredRef<View>("frame.dock", dockStyle);
+  const output = useAudioOutput();
+  return (
+    <View accessibilityLabel="Call controls" accessibilityRole="toolbar" pointerEvents="box-none" ref={dockRef} style={dockStyle} testID="frame.dock">
+      <IconButton accessibilityLabel={microphoneOn ? "Mute microphone" : "Unmute microphone"} icon={microphoneOn ? "mic" : "micOff"} off={!microphoneOn} onCanvas onPress={onToggleMicrophone} size={size} testID="dock.microphone" />
+      <IconButton accessibilityLabel={cameraOn ? "Turn off camera" : "Turn on camera"} icon={cameraOn ? "cam" : "camOff"} off={!cameraOn} onCanvas onPress={onToggleCamera} size={size} testID="dock.camera" />
+      {output ? <AudioOutputButton captioned={arrangement === "portrait"} output={output} size={size} /> : null}
+      <IconButton accessibilityLabel="More options" expanded={moreOpen} icon="more" onCanvas onPress={onOpenMore} ref={moreRef} size={size} testID="dock.more" />
+      {arrangement === "pad" ? <View style={styles.gap} /> : null}
+      <IconButton accessibilityLabel="Leave call" expanded={leaveOpen} icon="hang" onPress={onLeave} ref={leaveRef} size={size} testID="dock.leave" tone="danger" />
+    </View>
+  );
+});
+
+/**
+ * With only the earpiece and the speaker, a press switches between them. Once a headset is
+ * connected there are more than two places to play, so a press opens the choice.
+ */
+function AudioOutputButton({ output, size, captioned }: { readonly output: AudioOutput; readonly size: 44 | 52; readonly captioned: boolean }): React.JSX.Element {
+  const toasts = useToasts();
+  const ref = useRef<View>(null);
+  const [open, setOpen] = useState(false);
+  const devScenario = useDevScenario();
+  useEffect(() => {
+    if (devScenario.sheet === "route" || devScenario.menu === "route") setOpen(true);
+  }, [devScenario]);
+
+  const name = routeName(output.current);
+  const choosing = output.routes.length > 2;
+  const other = output.routes.find((route) => route.id !== output.selected);
+  const select = useCallback(
+    (id: string) => {
+      setOpen(false);
+      const route = output.routes.find((candidate) => candidate.id === id);
+      output
+        .select(id)
+        .then(() => route && announce(`Audio output: ${routeName(route)}`))
+        .catch(() => toasts.show({ kind: "error", dismissible: true, message: "Couldn't switch the audio output." }));
+    },
+    [output, toasts],
+  );
+  const press = useCallback(() => {
+    if (choosing) setOpen((was) => !was);
+    else if (other) select(other.id);
+  }, [choosing, other, select]);
+
+  const hint = choosing || !other ? "Choose output" : output.current.kind === "speaker" ? `Switch to ${routeName(other)}` : "Switch to speaker";
+  return (
+    <>
+      <IconButton accessibilityLabel={`Audio output: ${name}. ${hint}`} caption={captioned ? name : undefined} expanded={choosing ? open : undefined} icon={routeIcons[output.current.kind]} onCanvas onPress={press} ref={ref} size={size} testID="dock.route" />
+      {choosing ? <RoutePicker anchorRef={ref} onClose={() => setOpen(false)} onSelect={select} open={open} output={output} /> : null}
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  dock: { flex: 1, flexDirection: "row", alignItems: "center" },
+  portrait: { justifyContent: "space-between", paddingHorizontal: 20 },
+  landscape: { justifyContent: "center", gap: 14 },
+  pad: { justifyContent: "center", gap: 8 },
+  gap: { width: 8 },
+});

package/src/dock/LeaveMenu.tsx

@@ -0,0 +1,21 @@
+import type { RefObject } from "react";
+import type { View } from "react-native";
+import { Menu, MenuItem } from "../primitives/Menu";
+
+export type LeaveMenuProps = {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly anchorRef: RefObject<View | null>;
+  readonly onLeave: () => void;
+  readonly onEnd: () => void;
+};
+
+/** A host's Leave button asks whether to leave alone or end the call for everyone. */
+export function LeaveMenu({ open, onClose, anchorRef, onLeave, onEnd }: LeaveMenuProps): React.JSX.Element | null {
+  return (
+    <Menu accessibilityLabel="Leave" anchorRef={anchorRef} onClose={onClose} open={open} testID="menu.leave">
+      <MenuItem label="Leave call" onPress={onLeave} testID="menu.leave.leave" />
+      <MenuItem danger label="End call for everyone" onPress={onEnd} testID="menu.leave.end" />
+    </Menu>
+  );
+}

package/src/dock/MoreSheet.tsx

@@ -0,0 +1,233 @@
+import type { Reaction } from "@q9labsai/chalk-client";
+import { setStringAsync } from "expo-clipboard";
+import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import { Platform, Pressable, Share, StyleSheet, Text, View } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { useSpaceClient } from "../context/space-client-context";
+import { useMeasuredRef } from "../frame/measurement";
+import { usePreferences } from "../frame/preferences";
+import { haptics } from "../haptics/haptics";
+import { useCan, useChat, useParticipants, useRecording, useSelf } from "../hooks/space-hooks";
+import { Icon } from "../icons/Icon";
+import { usePressAnimation } from "../motion/press";
+import { announce } from "../primitives/announce";
+import { BottomSheet } from "../primitives/BottomSheet";
+import { ChalkText } from "../primitives/ChalkText";
+import { SegmentedControl } from "../primitives/SegmentedControl";
+import { SheetGroup, SheetRow } from "../primitives/SheetGroup";
+import { useToasts } from "../primitives/toast/ToastStack";
+import { playSound } from "../sounds/sounds";
+import { useStageView, type StageLayoutChoice } from "../stage/stage-view";
+import { useTheme } from "../theme/theme";
+import { durations, fixed } from "../theme/tokens";
+
+export type MoreSheetProps = {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly onOpenPeople: () => void;
+  readonly onOpenChat: () => void;
+  /** The call's link; without it the sheet leaves out Copy link and Share link. */
+  readonly inviteLink?: string;
+  readonly returnFocusRef?: RefObject<View | null>;
+};
+
+/** The call's one reaction set, in the mockup's order, with the names screen readers say. */
+const REACTIONS: readonly (readonly [Reaction, string])[] = [
+  ["👍", "thumbs up"],
+  ["❤️", "heart"],
+  ["😂", "laughter"],
+  ["😮", "surprise"],
+  ["🎉", "celebration"],
+  ["😢", "sadness"],
+];
+
+/**
+ * More (`#more`): raise hand and reactions on top, then the call's link, recording for hosts,
+ * Chat, People and the stage layout. Actions that change the call close the sheet; copying keeps it open.
+ */
+export function MoreSheet({ open, onClose, onOpenPeople, onOpenChat, inviteLink, returnFocusRef }: MoreSheetProps): React.JSX.Element {
+  const client = useSpaceClient();
+  const self = useSelf();
+  const people = useParticipants().roster.length;
+  const toasts = useToasts();
+  const { soundsEnabled } = usePreferences();
+  const canRaiseHand = useCan("raiseHand");
+  const canReact = useCan("sendReaction");
+
+  const fail = useCallback((message: string) => () => toasts.show({ kind: "error", dismissible: true, message }), [toasts]);
+  const toggleHand = useCallback(() => {
+    onClose();
+    haptics.handRaise();
+    if (self.handRaised) {
+      client.participants.lowerHand().catch(fail("Couldn't lower your hand."));
+      return;
+    }
+    playSound("hand", soundsEnabled);
+    announce("You raised a hand");
+    client.participants.raiseHand().catch(fail("Couldn't raise your hand."));
+  }, [client, fail, onClose, self.handRaised, soundsEnabled]);
+  const react = useCallback(
+    (emoji: Reaction) => {
+      onClose();
+      client.reactions.send(emoji).catch(fail("Couldn't send your reaction."));
+    },
+    [client, fail, onClose],
+  );
+
+  return (
+    <BottomSheet accessibilityLabel="More options" onClose={onClose} open={open} returnFocusRef={returnFocusRef} testID="sheet.more">
+      {canRaiseHand || canReact ? (
+        <View accessibilityLabel="Reactions" accessibilityRole="toolbar" style={styles.reactions}>
+          {canRaiseHand ? <HandButton onPress={toggleHand} raised={self.handRaised} /> : null}
+          {canReact ? REACTIONS.map(([emoji, name], index) => <EmojiButton emoji={emoji} key={emoji} name={name} onPress={react} testID={`more.reaction.${index}`} />) : null}
+        </View>
+      ) : null}
+      <SheetGroup>
+        {inviteLink ? <CopyLinkRow link={inviteLink} /> : null}
+        {inviteLink ? <SheetRow icon="iosShare" label="Share link" onPress={() => shareLink(inviteLink)} testID="more.share" /> : null}
+        <RecordingRow onDone={onClose} />
+        <ChatRow onPress={onOpenChat} />
+        <SheetRow end={<PeopleCount count={people} />} icon="users" label="People" onPress={onOpenPeople} testID="more.people" />
+        <LayoutRow />
+      </SheetGroup>
+    </BottomSheet>
+  );
+}
+
+function shareLink(link: string): void {
+  // iOS shares a URL as a link with its preview; Android takes it as the message text.
+  Share.share(Platform.OS === "ios" ? { url: link } : { message: link }).catch(() => undefined);
+}
+
+/** `.hand2`: a raised hand turns the button yellow until it's lowered. */
+function HandButton({ raised, onPress }: { readonly raised: boolean; readonly onPress: () => void }): React.JSX.Element {
+  const { colors } = useTheme();
+  const press = usePressAnimation("pill");
+  const foreground = raised ? fixed.handText : colors.text;
+  return (
+    <Pressable accessibilityLabel={raised ? "Lower hand" : "Raise hand"} accessibilityRole="button" accessibilityState={{ selected: raised }} onPress={onPress} onPressIn={press.onPressIn} onPressOut={press.onPressOut} testID="more.hand">
+      <Animated.View style={[styles.hand, { backgroundColor: raised ? fixed.hand : colors.raised }, press.scaleStyle]}>
+        <Icon color={foreground} name="hand" />
+        <ChalkText color={foreground} variant="bodyStrong">
+          {raised ? "Lower hand" : "Raise hand"}
+        </ChalkText>
+      </Animated.View>
+    </Pressable>
+  );
+}
+
+function EmojiButton({ emoji, name, onPress, testID }: { readonly emoji: Reaction; readonly name: string; readonly onPress: (emoji: Reaction) => void; readonly testID: string }): React.JSX.Element {
+  const { colors } = useTheme();
+  const press = usePressAnimation("small");
+  const { down } = press;
+  const pressed = colors.hover;
+  const background = useAnimatedStyle(() => {
+    "worklet";
+    return { backgroundColor: down.value ? pressed : fixed.transparent };
+  });
+  return (
+    <Pressable accessibilityLabel={`Send ${name}`} accessibilityRole="button" onPress={() => onPress(emoji)} onPressIn={press.onPressIn} onPressOut={press.onPressOut} style={styles.emojiSlot} testID={testID}>
+      <Animated.View style={[styles.emoji, background, press.scaleStyle]}>
+        <Text allowFontScaling={false} style={styles.emojiText}>
+          {emoji}
+        </Text>
+      </Animated.View>
+    </Pressable>
+  );
+}
+
+/** Copy link: the icon turns into a check for two seconds and the screen reader hears "Link copied". */
+function CopyLinkRow({ link }: { readonly link: string }): React.JSX.Element {
+  const [copied, setCopied] = useState(false);
+  const reset = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => clearTimeout(reset.current ?? undefined), []);
+  const copy = useCallback(async () => {
+    await setStringAsync(link);
+    setCopied(true);
+    announce("Link copied");
+    clearTimeout(reset.current ?? undefined);
+    reset.current = setTimeout(() => setCopied(false), durations.copyReset);
+  }, [link]);
+  return <SheetRow icon={copied ? "check" : "copy"} label="Copy link" onPress={() => void copy()} testID="more.copy" />;
+}
+
+const LAYOUTS = [
+  { value: "spotlight", label: "Spotlight", testID: "more.layout.spotlight" },
+  { value: "grid", label: "Grid", testID: "more.layout.grid" },
+] as const;
+
+/** Layout (`#mLay`): Spotlight or Grid for the stage, switched in place without closing the sheet. */
+function LayoutRow(): React.JSX.Element {
+  const { layout, setLayout } = useStageView();
+  return <SheetRow end={<SegmentedControl<StageLayoutChoice> accessibilityLabel="Layout" onChange={setLayout} options={LAYOUTS} testID="more.layout.control" value={layout} />} icon="grid" label="Layout" testID="more.layout" />;
+}
+
+function UnreadDot(): React.JSX.Element {
+  const { colors } = useTheme();
+  const style = [styles.unread, { backgroundColor: colors.info }];
+  const ref = useMeasuredRef<View>("more.chat.unread", style);
+  return <View ref={ref} style={style} testID="more.chat.unread" />;
+}
+
+/** Chat, with the accent dot after its name while messages are unread. */
+function ChatRow({ onPress }: { readonly onPress: () => void }): React.JSX.Element {
+  const { colors } = useTheme();
+  const unread = useChat().unreadCount > 0;
+  return <SheetRow accessibilityLabel={unread ? "Chat, new messages" : "Chat"} badge={unread ? <UnreadDot /> : null} end={<Icon color={colors.textMuted} name="right" />} icon="chat" label="Chat" onPress={onPress} testID="more.chat" />;
+}
+
+function PeopleCount({ count }: { readonly count: number }): React.JSX.Element {
+  const { colors } = useTheme();
+  return (
+    <View style={styles.end}>
+      <ChalkText tabular tone="textMuted" variant="phoneRow">
+        {count}
+      </ChalkText>
+      <Icon color={colors.textMuted} name="right" />
+    </View>
+  );
+}
+
+/** Hosts start and stop recording; the header's Rec dot shows it to everyone (K5). */
+function RecordingRow({ onDone }: { readonly onDone: () => void }): React.JSX.Element | null {
+  const client = useSpaceClient();
+  const toasts = useToasts();
+  const { soundsEnabled } = usePreferences();
+  const { colors } = useTheme();
+  const canRecord = useCan("manageRecording");
+  const status = useRecording().current?.status;
+  if (!canRecord) return null;
+  const recording = status === "starting" || status === "recording";
+  const toggle = () => {
+    onDone();
+    if (recording) {
+      client.recording
+        .stop()
+        .then(() => {
+          toasts.show({ leading: <Icon color={colors.textMuted} name="rec" />, message: "Recording stopped" });
+        })
+        .catch(() => toasts.show({ kind: "error", dismissible: true, message: "Couldn't stop recording." }));
+      return;
+    }
+    client.recording
+      .start()
+      .then(() => {
+        playSound("recording", soundsEnabled);
+        toasts.show({ leading: <Icon color={colors.dangerText} name="rec" />, message: [{ strong: "Recording started." }, " Everyone in the call can see it."] });
+      })
+      .catch(() => toasts.show({ kind: "error", dismissible: true, message: "Couldn't start recording." }));
+  };
+  return <SheetRow icon="rec" label={recording ? "Stop recording" : "Start recording"} onPress={toggle} testID="more.recording" />;
+}
+
+const styles = StyleSheet.create({
+  // `.rxrow`: wraps onto a second line on narrow phones.
+  // One line on every phone: the reactions narrow from 44 pt to 32 pt before they would wrap beside the hand.
+  reactions: { flexDirection: "row", alignItems: "center", gap: 2, paddingBottom: 12 },
+  hand: { flexDirection: "row", alignItems: "center", gap: 8, height: 44, paddingLeft: 12, paddingRight: 16, marginRight: 6, borderRadius: 999 },
+  emojiSlot: { flexBasis: 44, flexShrink: 1, minWidth: 32 },
+  emoji: { height: 44, borderRadius: 22, alignItems: "center", justifyContent: "center" },
+  emojiText: { fontSize: 22 },
+  end: { flexDirection: "row", alignItems: "center", gap: 14 },
+  unread: { width: 8, height: 8, borderRadius: 4 },
+});

package/src/dock/ReactionBurst.tsx

@@ -0,0 +1,55 @@
+import type { ActiveReaction } from "@q9labsai/chalk-client";
+import { memo, useEffect } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import Animated, { useAnimatedStyle, useReducedMotion, useSharedValue, withTiming } from "react-native-reanimated";
+import { useReactions } from "../hooks/space-hooks";
+import { easings } from "../theme/tokens";
+
+/** The mockup's `@keyframes rx`: 2 s ease-out, fading in over the first 15 % while rising 82 pt. */
+const DURATION = 2000;
+const FADE_IN = 0.15;
+
+/**
+ * Reactions a person sends (F12), floating up from the lower middle of their tile. Mount it inside
+ * the tile; it draws nothing while that person has no reaction showing.
+ */
+export const ReactionBurst = memo(function ReactionBurst({ participantId }: { readonly participantId: string }): React.JSX.Element | null {
+  const active = useReactions().active.filter((reaction) => reaction.participantId === participantId);
+  if (active.length === 0) return null;
+  return (
+    <View pointerEvents="none" style={styles.layer}>
+      {active.map((reaction) => (
+        <FloatingEmoji key={reaction.eventId} reaction={reaction} />
+      ))}
+    </View>
+  );
+});
+
+function FloatingEmoji({ reaction }: { readonly reaction: ActiveReaction }): React.JSX.Element {
+  const reduceMotion = useReducedMotion();
+  const progress = useSharedValue(0);
+  useEffect(() => {
+    progress.value = withTiming(1, { duration: DURATION, easing: easings.easeOut });
+  }, [progress]);
+  const style = useAnimatedStyle(() => {
+    "worklet";
+    const t = progress.value;
+    const opacity = t < FADE_IN ? t / FADE_IN : 1 - (t - FADE_IN) / (1 - FADE_IN);
+    // Reduced motion keeps the fade (`@keyframes rxf`) and drops the rise.
+    return { opacity, transform: [{ translateY: reduceMotion ? 0 : 12 - 82 * t }] };
+  });
+  return (
+    <Animated.View style={[styles.emoji, style]}>
+      <Text allowFontScaling={false} style={styles.text}>
+        {reaction.reaction}
+      </Text>
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  layer: { ...StyleSheet.absoluteFillObject, zIndex: 6 },
+  // `.rx`: centred, its bottom 28 % up the tile.
+  emoji: { position: "absolute", left: 0, right: 0, bottom: "28%", alignItems: "center" },
+  text: { fontSize: 44 },
+});

package/src/dock/RoutePicker.tsx

@@ -0,0 +1,42 @@
+import type { RefObject } from "react";
+import { Platform, type View } from "react-native";
+import { Icon } from "../icons/Icon";
+import { BottomSheet } from "../primitives/BottomSheet";
+import { Menu, MenuItem } from "../primitives/Menu";
+import { SheetGroup, SheetRow } from "../primitives/SheetGroup";
+import { useTheme } from "../theme/theme";
+import { routeIcons, routeName, type AudioOutput } from "./audio-route";
+
+export type RoutePickerProps = {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly onSelect: (id: string) => void;
+  readonly output: AudioOutput;
+  readonly anchorRef: RefObject<View | null>;
+};
+
+/**
+ * The audio output choice once a headset joins the earpiece and the speaker: a menu next to the
+ * button on iOS, where the mockup draws the system route menu, and a sheet on Android.
+ */
+export function RoutePicker({ open, onClose, onSelect, output, anchorRef }: RoutePickerProps): React.JSX.Element | null {
+  const { colors } = useTheme();
+  if (Platform.OS === "ios") {
+    return (
+      <Menu accessibilityLabel="Audio output" anchorRef={anchorRef} onClose={onClose} open={open} testID="menu.route">
+        {output.routes.map((route) => (
+          <MenuItem checked={route.id === output.selected} icon={routeIcons[route.kind]} key={route.id} label={routeName(route)} onPress={() => onSelect(route.id)} testID={`menu.route.${route.kind}`} />
+        ))}
+      </Menu>
+    );
+  }
+  return (
+    <BottomSheet accessibilityLabel="Audio output" onClose={onClose} open={open} returnFocusRef={anchorRef} testID="sheet.route" title="Audio output">
+      <SheetGroup>
+        {output.routes.map((route) => (
+          <SheetRow end={route.id === output.selected ? <Icon color={colors.text} name="check" /> : null} icon={routeIcons[route.kind]} key={route.id} label={routeName(route)} onPress={() => onSelect(route.id)} testID={`sheet.route.${route.kind}`} />
+        ))}
+      </SheetGroup>
+    </BottomSheet>
+  );
+}

package/src/dock/audio-route.ts

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useState } from "react";
+import { NativeEventEmitter, NativeModules, Platform } from "react-native";
+import { useDevScenario } from "../frame/dev-scenario";
+import type { IconName } from "../icons/Icon";
+
+export type AudioRouteKind = "earpiece" | "speaker" | "bluetooth" | "wired";
+
+/** One place the call's sound can play. Bluetooth and wired headsets carry their device name. */
+export type AudioRoute = { readonly id: string; readonly kind: AudioRouteKind; readonly name: string };
+
+export type AudioRoutes = { readonly routes: readonly AudioRoute[]; readonly selected: string };
+
+export type AudioOutput = AudioRoutes & {
+  readonly current: AudioRoute;
+  readonly select: (id: string) => Promise<void>;
+};
+
+type NativeAudioRouteModule = {
+  readonly eventName: string;
+  readonly addListener: (eventName: string) => void;
+  readonly removeListeners: (count: number) => void;
+  readonly getRoutes: () => Promise<AudioRoutes>;
+  readonly selectRoute: (id: string) => Promise<AudioRoutes>;
+};
+
+const nativeModule: NativeAudioRouteModule | undefined = NativeModules.ChalkAudioRouteModule;
+const emitter = nativeModule ? new NativeEventEmitter(nativeModule) : null;
+
+export const routeIcons: Readonly<Record<AudioRouteKind, IconName>> = { earpiece: "earpiece", speaker: "vol", bluetooth: "buds", wired: "buds" };
+
+/** The mockup's `ROUTEN`: the phone's own speaker is "iPhone" on iOS and "Phone" on Android. */
+export function routeName(route: AudioRoute): string {
+  if (route.kind === "speaker") return "Speaker";
+  if (route.kind === "earpiece") return Platform.OS === "ios" ? "iPhone" : "Phone";
+  return route.name;
+}
+
+/**
+ * The audio output button's state (R1), from the SDK's native route module. Null when the app's
+ * native build doesn't include the module yet, so the dock leaves the button out.
+ */
+export function useAudioOutput(): AudioOutput | null {
+  const scenario = useDevScenario().audioRoutes;
+  const [state, setState] = useState<AudioRoutes | null>(null);
+  // In the harness, picking a route moves the check like a real switch would.
+  const [scenarioSelected, setScenarioSelected] = useState<string | null>(null);
+  useEffect(() => {
+    if (!nativeModule || !emitter) return;
+    let live = true;
+    nativeModule
+      .getRoutes()
+      .then((next) => live && setState(next))
+      .catch(() => undefined);
+    const subscription = emitter.addListener(nativeModule.eventName, (next: AudioRoutes) => setState(next));
+    return () => {
+      live = false;
+      subscription.remove();
+    };
+  }, []);
+  const select = useCallback(async (id: string) => {
+    if (!nativeModule) return;
+    setState(await nativeModule.selectRoute(id));
+  }, []);
+  const routes = scenario ? { ...scenario, selected: scenarioSelected ?? scenario.selected } : state;
+  if (!routes) return null;
+  const current = routes.routes.find((route) => route.id === routes.selected) ?? routes.routes[0];
+  if (!current) return null;
+  return { ...routes, current, select: scenario ? async (id) => setScenarioSelected(id) : select };
+}