@xprem/control-center 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @xprem/control-center
+
+See which branch this build is running, and switch to another — from the build
+itself.
+
+Built for acceptance testing: one TestFlight or Play build becomes a shell for
+every branch that is compatible with it, so five people can test five branches in
+parallel without five builds.
+
+```tsx
+import { ControlCenter } from '@xprem/control-center';
+
+export default function App() {
+  return (
+    <>
+      <YourApp />
+      <ControlCenter />
+    </>
+  );
+}
+```
+
+That is the whole integration. There is nothing to configure: the panel reads the
+update URL, app id, channel and runtime version from the config the build already
+carries.
+
+## It turns itself on
+
+At launch, once the first frame has painted, the component asks the server one
+question — is branch surfing allowed on this build's channel? On no, it renders
+`null` and registers nothing. On yes, a small blue marker appears on the right
+edge; press it and the panel opens, branches already in hand. One request per
+app session, answered from the server's cache.
+
+Turn branch surfing on for a channel from the xprem dashboard and the panel is
+there at the next launch of every build on that channel — nothing to republish.
+Turn it off and it disappears the same way. A production channel never shows it.
+
+## Footprint
+
+JavaScript only. No native module, no config plugin, no `prebuild`. It ships in
+the JS bundle, which means **it can be delivered over the air to a build that is
+already in testers' hands** — the picker itself is an update.
+
+The only dependencies are `expo-updates` and `expo-constants`, which the app has
+already. The edge marker is the built-in way in; your own trigger works from
+anywhere:
+
+```tsx
+import { openControlCenter } from '@xprem/control-center';
+```
+
+## What a tester sees
+
+The panel opens on the branch currently running — live dot, channel and runtime
+under it — then the branches this build can switch to, drawn as a rail of
+branch dots, newest first. Only branches with an update built for **this** binary's
+runtime version are listed: a branch that changed native code cannot be reached
+without a new build, so offering it would be a dead end.
+
+When a branch crashes on launch, expo-updates falls back on its own and the server
+refuses to serve that branch again. The panel says so, names the branch, and says
+what unblocks it — publishing a fix to that same branch.
+
+## Requirements
+
+- Expo SDK 54 or newer (`setUpdateRequestHeadersOverride`)
+- `expo-app-id`, `expo-channel-name` and `xprem-branch` declared in
+  `updates.requestHeaders` at build time
+
+```ts
+updates: {
+  requestHeaders: {
+    'expo-channel-name': 'staging',
+    'expo-app-id': '...',
+    'xprem-branch': '',
+  },
+}
+```
+
+Those three are not optional, and the panel refuses to appear without them —
+switching branches replaces the whole header set, and expo-updates only accepts an
+override for keys that existed when the app was built. A build missing one of them
+would drop it from every poll from then on, which the server answers with a 400,
+which means no update can reach the device to undo it. Reinstalling is the only way
+out, so the package checks first and logs which header is missing. `eoas init`
+writes them for you.
+
+Declare `expo-channel-name` as a literal, not `process.env.SOMETHING`. The config is
+evaluated when the JS bundle is exported, so an unset variable silently removes the
+key — and an export run with the wrong value would bake in the wrong channel. Only
+the key matters here: the value sent at runtime is always the build's real channel.
+
+## If a build gets stuck
+
+It cannot be bricked. A branch that fails to launch is rolled back by
+expo-updates itself, onto the bundle embedded in the binary. To get moving again,
+in order of preference:
+
+1. publish a fix to the branch being tested
+2. turn branch surfing off for the channel, which returns every device
+3. reinstall the app, which clears the stored choice

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@xprem/control-center",
+  "version": "0.1.0",
+  "description": "A branch picker that appears on builds whose channel allows surfing. JS-only, for xprem branch surfing.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "xprem",
+    "expo",
+    "expo-updates",
+    "branch-surfing",
+    "qa"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "expo-constants": "*",
+    "expo-updates": ">=0.29.0",
+    "react": ">=18",
+    "react-native": ">=0.72"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "typescript": "~6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axelmarciano/xprem.git",
+    "directory": "apps/control-center"
+  }
+}

package/src/BranchIcon.tsx

@@ -0,0 +1,57 @@
+import { View } from 'react-native';
+import { palette } from './theme';
+
+/**
+ * The git-branch glyph, drawn with borders instead of an SVG because this package
+ * ships no native modules. The curve is the bottom-right quadrant of a box whose
+ * corner radius equals its height, which is exactly a quarter circle.
+ *
+ * Geometry is lucide's 24-unit grid, so it lines up with the icon everyone knows.
+ */
+const GRID = 24;
+
+export function BranchIcon({ size = 24, color = palette.ink, weight = 2 }) {
+  const s = size / GRID;
+  const stroke = weight * s;
+  const dot = (cx: number, cy: number) => ({
+    position: 'absolute' as const,
+    left: (cx - 3) * s,
+    top: (cy - 3) * s,
+    width: 6 * s,
+    height: 6 * s,
+    borderRadius: 3 * s,
+    borderWidth: stroke,
+    borderColor: color,
+  });
+
+  return (
+    <View style={{ width: size, height: size }}>
+      <View
+        style={{
+          position: 'absolute',
+          left: (6 - weight / 2) * s,
+          top: 4 * s,
+          width: stroke,
+          height: 16 * s,
+          backgroundColor: color,
+        }}
+      />
+      <View
+        style={{
+          position: 'absolute',
+          left: 6 * s,
+          top: 7 * s,
+          width: 12 * s,
+          height: 6 * s,
+          borderBottomWidth: stroke,
+          borderRightWidth: stroke,
+          borderColor: color,
+          borderBottomRightRadius: 6 * s,
+        }}
+      />
+      <View style={dot(6, 4)} />
+      <View style={dot(6, 20)} />
+      <View style={dot(18, 4)} />
+    </View>
+  );
+}

package/src/ControlCenter.tsx

@@ -0,0 +1,521 @@
+import { Component, ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  ActivityIndicator,
+  InteractionManager,
+  Modal,
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from 'react-native';
+import { BranchIcon } from './BranchIcon';
+import { readConfig, readLoadedState, SurfConfig } from './config';
+import { BranchPage, listBranches, surfTo } from './surf';
+import { cardShadow, palette, radius, space, type } from './theme';
+import { XpremMark } from './XpremMark';
+
+/** "5 min ago" beats a timestamp for someone deciding what is fresh enough to test. */
+function sinceLabel(iso: string): string {
+  const published = Date.parse(iso);
+  if (Number.isNaN(published)) {
+    return '';
+  }
+  const minutes = Math.max(0, Math.round((Date.now() - published) / 60000));
+  if (minutes < 1) return 'Updated just now';
+  if (minutes < 60) return `Updated ${minutes} min ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `Updated ${hours} hr ago`;
+  const days = Math.round(hours / 24);
+  return days === 1 ? 'Updated yesterday' : `Updated ${days} days ago`;
+}
+
+/**
+ * One probe per JS session. Memoised at module scope rather than in the component:
+ * a useEffect would run again if the tree remounted, and this must be exactly once
+ * per app open. reloadAsync starts a new session, so a surf re-probes naturally.
+ *
+ * Whether a channel allows surfing is a setting that changes whenever an admin
+ * says so, while a manifest is a snapshot frozen when its update was served — so
+ * the answer cannot ride in the manifest, or enabling the feature would only reach
+ * devices that happen to download something afterwards.
+ */
+let sessionProbe: Promise<BranchPage | null> | null = null;
+
+function probeOnce(config: SurfConfig): Promise<BranchPage | null> {
+  // Only an ANSWER is remembered — a list, or the 404 that means surfing is off.
+  // A timeout is not an answer: caching one would disable the picker until the
+  // app is killed, and the tester has no way to know a retry would work.
+  sessionProbe ??= listBranches(config).catch(error => {
+    sessionProbe = null;
+    throw error;
+  });
+  return sessionProbe;
+}
+
+let openPanel: (() => void) | null = null;
+
+/** Opens the panel from anywhere — the edge handle is the built-in trigger. */
+export function openControlCenter() {
+  openPanel?.();
+}
+
+// A QA tool has no business taking the host app down: whatever throws inside the
+// panel unmounts the panel, never the app around it.
+class ControlCenterBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: Error) {
+    console.warn(`[xprem] The control center crashed and was unmounted: ${error.message}`);
+  }
+
+  render() {
+    return this.state.failed ? null : this.props.children;
+  }
+}
+
+export function ControlCenter() {
+  return (
+    <ControlCenterBoundary>
+      <ControlCenterPanel />
+    </ControlCenterBoundary>
+  );
+}
+
+function ControlCenterPanel() {
+  const config = useMemo(readConfig, []);
+  const loaded = useMemo(readLoadedState, []);
+  const [visible, setVisible] = useState(false);
+  const [page, setPage] = useState<BranchPage | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState<string | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+  const [query, setQuery] = useState('');
+  const [expanding, setExpanding] = useState(false);
+  const [expanded, setExpanded] = useState(false);
+
+  const [allowed, setAllowed] = useState(false);
+  const active = config !== null && allowed;
+  const open = useCallback(() => setVisible(true), []);
+  const close = useCallback(() => setVisible(false), []);
+
+  // After first paint: a QA tool must not sit on the critical path of a launch.
+  useEffect(() => {
+    if (!config) return;
+    let cancelled = false;
+    const task = InteractionManager.runAfterInteractions(() => {
+      probeOnce(config)
+        .then(result => {
+          if (cancelled || result === null) return;
+          setAllowed(true);
+          setPage(result);
+        })
+        .catch((cause: Error) => {
+          // Not silent: the panel is unreachable for the rest of this session
+          // unless the host app calls openControlCenter, and nothing else would
+          // ever say why.
+          console.warn(`[xprem] Could not reach the branch list: ${cause.message}`);
+        });
+    });
+    return () => {
+      cancelled = true;
+      task.cancel();
+    };
+  }, [config]);
+
+  useEffect(() => {
+    // Registered whether or not the probe has answered. Gating it on `active`
+    // made the host app's own trigger a silent no-op for the whole of every
+    // launch, and permanently so whenever the probe failed — which is exactly
+    // when someone reaches for it. Opening early shows the panel's own loading
+    // and error states, which is the point.
+    openPanel = open;
+    return () => {
+      // Only if it is still ours: a second instance may have taken over, and
+      // clearing unconditionally would deregister a panel that is still mounted.
+      if (openPanel === open) {
+        openPanel = null;
+      }
+    };
+  }, [open]);
+
+  useEffect(() => {
+    if (!visible || !config) return;
+    const controller = new AbortController();
+    setError(null);
+    setNote(null);
+    setQuery('');
+    setExpanding(false);
+    setExpanded(false);
+    listBranches(config, controller.signal)
+      .then(result => {
+        if (result === null) {
+          // Surfing was turned off while this session was running. Stand down
+          // rather than spin: null reads as "loading" everywhere below.
+          setAllowed(false);
+          setVisible(false);
+          return;
+        }
+        setPage(result);
+      })
+      .catch((cause: Error) => {
+        if (cause.name !== 'AbortError') setError(cause.message);
+      });
+    return () => controller.abort();
+  }, [visible, config]);
+
+  const showEverything = useCallback(async () => {
+    if (!config || expanded || expanding) return;
+    setExpanding(true);
+    try {
+      const result = await listBranches(config, undefined, true);
+      if (result === null) {
+        // Surfing was switched off between opening the panel and asking for the
+        // rest. Same stand-down as every other read, or the tester is left
+        // holding switches the server will no longer honour.
+        setAllowed(false);
+        setVisible(false);
+        return;
+      }
+      setPage(result);
+      // Set even when the wide answer is itself capped: this only means "already
+      // asked", so a keystroke cannot start the same fetch again. Whether the
+      // list is COMPLETE is a separate question, read off total below.
+      setExpanded(true);
+    } catch (cause) {
+      setError((cause as Error).message);
+    } finally {
+      setExpanding(false);
+    }
+  }, [config, expanded, expanding]);
+
+  const search = useCallback(
+    (text: string) => {
+      setQuery(text);
+      // Searching a partial list would answer "no match" for a branch that is
+      // merely further down — a wrong answer, not a short one. So the first
+      // keystroke pulls the rest; showEverything is a no-op once it has.
+      if (text.length > 0) void showEverything();
+    },
+    [showEverything]
+  );
+
+  const switchTo = useCallback(
+    async (branch: string | null) => {
+      if (!config) return;
+      setPending(branch ?? '');
+      setNote(null);
+      try {
+        const outcome = await surfTo(config, branch);
+        if (outcome === 'nothing-to-load') {
+          setNote(
+            branch
+              ? `Switched to ${branch}. It has nothing newer than what is already ` +
+                `running, so the screen did not change — you will get its next publish.`
+              : 'Back on this build\u2019s own branch. Nothing newer to load.'
+          );
+        }
+      } catch (cause) {
+        setError((cause as Error).message);
+      } finally {
+        setPending(null);
+      }
+    },
+    [config]
+  );
+
+  if (!active || !config) {
+    return null;
+  }
+
+  // What is RUNNING, which after a surf is the surfed branch — not the branch the
+  // channel maps to. Excluded from the list below: there is nothing to switch to.
+  const loadedBranch = loaded.branch;
+  const rows = (page?.branches ?? []).filter(candidate => candidate.name !== loadedBranch);
+  // The server sends a short page of the newest branches. Say how many are left
+  // rather than letting the list pass for the whole truth.
+  const withheld = page ? page.total - page.branches.length : 0;
+  // Keyed on the total, not the page: the page is short by design, so counting
+  // loaded rows would hide the search field exactly when it is most needed.
+  const searchable = (page?.total ?? 0) > 10;
+  const needle = query.trim().toLowerCase();
+  const shown = needle ? rows.filter(r => r.name.toLowerCase().includes(needle)) : rows;
+
+  if (!visible) {
+    // Always present while surfing is allowed: the way in a tester nobody briefed
+    // will actually find. An edge sliver rather than an invisible corner target,
+    // so it never swallows the host app's own controls.
+    return (
+      <Pressable
+        style={styles.handle}
+        onPress={open}
+        hitSlop={{ top: 12, bottom: 12, left: 16, right: 8 }}
+        accessibilityRole="button"
+        accessibilityLabel="Open the branch picker">
+        <View style={styles.handleGrip} />
+      </Pressable>
+    );
+  }
+
+  return (
+    // pageSheet is the native card the dev menu uses: full-height sheet, the app
+    // pushed back behind it, swipe down to dismiss. No custom animation to own.
+    <Modal visible animationType="slide" presentationStyle="pageSheet" onRequestClose={close}>
+      <View style={styles.screen}>
+        <View style={styles.header}>
+          <View style={styles.heroLine}>
+            <BranchIcon size={26} weight={2.2} />
+            <Text style={[type.hero, styles.heroName]} numberOfLines={1}>
+              {loadedBranch ?? 'Embedded build'}
+            </Text>
+            <Pressable
+              style={({ pressed }) => [styles.close, pressed && styles.closePressed]}
+              onPress={close}
+              accessibilityRole="button"
+              accessibilityLabel="Close">
+              <Text style={styles.closeGlyph}>✕</Text>
+            </Pressable>
+          </View>
+
+          <View style={styles.chipLine}>
+            <Text style={type.label}>Running on:</Text>
+            <View style={styles.chip}>
+              <View style={styles.liveDot} />
+              <Text style={type.chip}>Channel: {config.channel}</Text>
+            </View>
+            <View style={[styles.chip, styles.chipNeutral]}>
+              <Text style={[type.chip, styles.chipNeutralInk]}>
+                Runtime {config.runtimeVersion}
+              </Text>
+            </View>
+          </View>
+        </View>
+
+        <ScrollView style={styles.body} contentContainerStyle={styles.bodyContent}>
+          {loaded.refusedBranch && (
+            <View style={styles.warnCard}>
+              <Text style={styles.warnTitle}>{loaded.refusedBranch} was rolled back</Text>
+              <Text style={styles.warnBody}>
+                It crashed on launch, so this build came back here. Publishing a fix to
+                that branch makes it available again.
+              </Text>
+            </View>
+          )}
+
+          <Text style={[type.section, styles.sectionTitle]}>Switch to</Text>
+
+          {searchable && (
+            <TextInput
+              style={styles.search}
+              value={query}
+              onChangeText={search}
+              placeholder="Search branches"
+              placeholderTextColor={palette.muted}
+              autoCapitalize="none"
+              autoCorrect={false}
+              clearButtonMode="while-editing"
+              accessibilityLabel="Search branches"
+            />
+          )}
+
+          {page === null && (
+            <View style={[styles.card, styles.cardCentered]}>
+              <ActivityIndicator color={palette.muted} />
+            </View>
+          )}
+
+          {page !== null && shown.length === 0 && (
+            <View style={[styles.card, styles.cardCentered]}>
+              <Text style={type.meta}>
+                {needle
+                  ? `No branch matches “${query.trim()}”.`
+                  : `Nothing else is published for runtime ${config.runtimeVersion}.`}
+              </Text>
+            </View>
+          )}
+
+          {shown.map(candidate => (
+            <Pressable
+              key={candidate.name}
+              style={({ pressed }) => [styles.card, styles.row, pressed && styles.rowPressed]}
+              disabled={pending !== null}
+              onPress={() => void switchTo(candidate.name)}>
+              <BranchIcon size={22} color={palette.muted} />
+              <View style={styles.rowText}>
+                <Text style={type.rowTitle} numberOfLines={1}>
+                  {candidate.name}
+                </Text>
+                <Text style={type.meta}>{sinceLabel(candidate.lastUpdateAt)}</Text>
+              </View>
+              {pending === candidate.name ? (
+                <ActivityIndicator size="small" color={palette.muted} />
+              ) : (
+                <Text style={styles.chevron}>›</Text>
+              )}
+            </Pressable>
+          ))}
+
+          {withheld > 0 && !expanded && (
+            <Pressable
+              style={({ pressed }) => [styles.card, styles.seeAll, pressed && styles.rowPressed]}
+              disabled={expanding}
+              onPress={() => void showEverything()}>
+              {expanding ? (
+                <ActivityIndicator size="small" color={palette.muted} />
+              ) : (
+                <Text style={styles.seeAllText}>
+                  Showing the {page?.branches.length} newest · See all {page?.total}
+                </Text>
+              )}
+            </Pressable>
+          )}
+
+          {withheld > 0 && expanded && (
+            // The server will not send more than this. Saying so is the whole
+            // point: a search over a list this size must not read as exhaustive.
+            <View style={[styles.card, styles.seeAll]}>
+              <Text style={type.meta}>
+                Showing the {page?.branches.length} newest of {page?.total}. Older
+                branches are not listed.
+              </Text>
+            </View>
+          )}
+
+          {note && <Text style={[type.meta, styles.footnote]}>{note}</Text>}
+          {error && <Text style={[type.meta, styles.errorText]}>{error}</Text>}
+
+          <Pressable
+            style={({ pressed }) => [styles.pill, pressed && styles.pillPressed]}
+            disabled={pending !== null}
+            onPress={() => void switchTo(null)}>
+            {pending === '' ? (
+              <ActivityIndicator size="small" color={palette.pillInk} />
+            ) : (
+              <Text style={type.pill}>Return to this build&rsquo;s branch</Text>
+            )}
+          </Pressable>
+
+          <View style={styles.brand}>
+            <XpremMark size={16} />
+            <Text style={type.meta}>xprem</Text>
+          </View>
+        </ScrollView>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  handle: {
+    position: 'absolute',
+    right: 0,
+    top: '45%',
+    paddingVertical: space.md,
+    paddingLeft: space.sm,
+    paddingRight: 2,
+  },
+  handleGrip: {
+    width: 4,
+    height: 42,
+    borderTopLeftRadius: 3,
+    borderBottomLeftRadius: 3,
+    backgroundColor: palette.ink,
+    opacity: 0.35,
+  },
+  screen: { flex: 1, backgroundColor: palette.page },
+  header: {
+    backgroundColor: palette.surface,
+    paddingHorizontal: space.lg,
+    paddingTop: space.lg,
+    paddingBottom: space.md,
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderBottomColor: palette.border,
+    gap: space.md,
+  },
+  heroLine: { flexDirection: 'row', alignItems: 'center', gap: 10 },
+  heroName: { flex: 1 },
+  close: {
+    width: 32,
+    height: 32,
+    borderRadius: 16,
+    backgroundColor: palette.page,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  closePressed: { backgroundColor: palette.surfacePressed },
+  closeGlyph: { fontSize: 15, color: palette.muted },
+  chipLine: { flexDirection: 'row', alignItems: 'center', flexWrap: 'wrap', gap: space.sm },
+  chip: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 6,
+    backgroundColor: palette.chipBg,
+    borderRadius: radius.chip,
+    paddingHorizontal: 10,
+    paddingVertical: 5,
+  },
+  chipNeutral: { backgroundColor: palette.page },
+  chipNeutralInk: { color: palette.muted },
+  liveDot: { width: 7, height: 7, borderRadius: 4, backgroundColor: palette.live },
+  body: { flex: 1 },
+  bodyContent: { padding: space.md, paddingBottom: space.xl, gap: space.sm },
+  sectionTitle: { marginTop: space.sm, marginLeft: space.xs },
+  search: {
+    backgroundColor: palette.surface,
+    borderRadius: radius.chip + 2,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: palette.border,
+    minHeight: 42,
+    paddingHorizontal: space.md,
+    fontSize: 16,
+    color: palette.ink,
+  },
+  card: {
+    backgroundColor: palette.surface,
+    borderRadius: radius.card,
+    paddingHorizontal: space.md,
+    paddingVertical: 14,
+    ...cardShadow,
+  },
+  cardCentered: { alignItems: 'center', justifyContent: 'center', minHeight: 64 },
+  row: { flexDirection: 'row', alignItems: 'center', gap: space.sm + 4 },
+  rowPressed: { backgroundColor: palette.surfacePressed },
+  seeAll: { alignItems: 'center', justifyContent: 'center', minHeight: 48 },
+  seeAllText: { fontSize: 15, fontWeight: '600', color: palette.ink },
+  rowText: { flex: 1, gap: 2 },
+  chevron: { fontSize: 22, color: palette.muted, marginTop: -2 },
+  warnCard: {
+    backgroundColor: palette.warnBg,
+    borderRadius: radius.card,
+    padding: space.md,
+    gap: 4,
+  },
+  warnTitle: { fontSize: 16, fontWeight: '600', color: palette.warnInk },
+  warnBody: { fontSize: 14, lineHeight: 20, color: palette.warnInk },
+  footnote: { marginLeft: space.xs },
+  errorText: { marginLeft: space.xs, color: palette.danger },
+  pill: {
+    marginTop: space.md,
+    minHeight: 52,
+    borderRadius: radius.pill,
+    backgroundColor: palette.pill,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  pillPressed: { opacity: 0.85 },
+  brand: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 6,
+    marginTop: space.lg,
+    opacity: 0.5,
+  },
+});
+
+export default ControlCenter;

package/src/XpremMark.tsx

@@ -0,0 +1,58 @@
+import { StyleSheet, View } from 'react-native';
+
+/**
+ * The xprem mark — the X glyph and its azure dot on the dark tile — rebuilt from
+ * plain Views because the design of this package forbids native modules and
+ * react-native-svg is one. Every shape in the mark is a rounded rect or a
+ * circle, so nothing is lost except the dot's radial gradient, flattened to its
+ * dominant stop; at footer size the difference does not survive the screen.
+ *
+ * Geometry is the SVG's, scaled from its 64-unit viewBox. Colours are baked in,
+ * exactly like the dashboard's mark: the tile must stay identical everywhere.
+ */
+const VIEWBOX = 64;
+// The strokes run (18,22)–(38,46) and (38,22)–(18,46): not a 45° X, slightly
+// taller than wide, and that asymmetry is part of the mark.
+const STROKE = 6.5;
+const STROKE_LENGTH = Math.hypot(38 - 18, 46 - 22) + STROKE; // round caps add a radius each
+const STROKE_ANGLE = (Math.atan2(46 - 22, 38 - 18) * 180) / Math.PI;
+
+export function XpremMark({ size = 16 }: { size?: number }) {
+  const s = size / VIEWBOX;
+  const bar = {
+    position: 'absolute' as const,
+    width: STROKE_LENGTH * s,
+    height: STROKE * s,
+    borderRadius: (STROKE / 2) * s,
+    backgroundColor: '#EEF2FA',
+    left: 28 * s - (STROKE_LENGTH * s) / 2,
+    top: 34 * s - (STROKE * s) / 2,
+  };
+  return (
+    <View
+      style={{
+        width: size,
+        height: size,
+        borderRadius: 14 * s,
+        backgroundColor: '#0A0E16',
+        borderWidth: StyleSheet.hairlineWidth,
+        borderColor: '#232F42',
+      }}
+      accessibilityRole="image"
+      accessibilityLabel="xprem">
+      <View style={[bar, { transform: [{ rotate: `${STROKE_ANGLE}deg` }] }]} />
+      <View style={[bar, { transform: [{ rotate: `${-STROKE_ANGLE}deg` }] }]} />
+      <View
+        style={{
+          position: 'absolute',
+          width: 13 * s,
+          height: 13 * s,
+          borderRadius: 6.5 * s,
+          backgroundColor: '#4E97F2',
+          left: (47 - 6.5) * s,
+          top: (43 - 6.5) * s,
+        }}
+      />
+    </View>
+  );
+}

package/src/config.ts

@@ -0,0 +1,113 @@
+import Constants from 'expo-constants';
+import * as Updates from 'expo-updates';
+
+/** What the update server needs to answer this device, all of it already on hand. */
+export type SurfConfig = {
+  /** Where /branch_lists lives: the update URL with its last segment dropped. */
+  baseUrl: string;
+  appId: string;
+  channel: string;
+  runtimeVersion: string;
+  /**
+   * The request headers baked at build time. setUpdateRequestHeadersOverride
+   * REPLACES the whole set rather than merging into it, and expo-updates only
+   * accepts keys that were declared at build time — so every override has to be
+   * rebuilt from this, or the poll loses its channel and its app id.
+   */
+  requestHeaders: Record<string, string>;
+};
+
+export const BRANCH_HEADER = 'xprem-branch';
+
+/** State the manifest already carries, so nothing has to be stored on the side. */
+export type LoadedState = {
+  /** The branch actually served. Not necessarily the one that was asked for. */
+  branch: string | null;
+  /** Set when the server refused a branch because its update crashed here. */
+  refusedBranch: string | null;
+};
+
+function extra(): Record<string, unknown> {
+  return ((Updates.manifest as { extra?: Record<string, unknown> } | undefined)?.extra ??
+    {}) as Record<string, unknown>;
+}
+
+export function readLoadedState(): LoadedState {
+  const manifestExtra = extra();
+  return {
+    branch: typeof manifestExtra.branch === 'string' ? manifestExtra.branch : null,
+    refusedBranch:
+      typeof manifestExtra.branchSurfingRefused === 'string' &&
+      manifestExtra.branchSurfingRefused.length > 0
+        ? manifestExtra.branchSurfingRefused
+        : null,
+  };
+}
+
+/**
+ * The keys the override cannot be built without. expo-updates only accepts an
+ * override whose keys were declared at build time, and the override replaces the
+ * whole header set — so a build missing any of these can be sent into a state
+ * where every poll is answered 400 and no update can reach it to fix that.
+ */
+const REQUIRED_BUILD_HEADERS = ['expo-app-id', 'expo-channel-name', BRANCH_HEADER];
+
+function declared(requestHeaders: Record<string, string>, key: string): boolean {
+  return typeof requestHeaders[key] === 'string';
+}
+
+/**
+ * Returns null when this build cannot surf at all: no update config, a runtime too
+ * old for the header override, or a build-time header set the override could not
+ * be rebuilt from. The component renders nothing in that case rather than offering
+ * a switch that would strand the device.
+ */
+export function readConfig(): SurfConfig | null {
+  const updates = Constants.expoConfig?.updates as
+    | { url?: string; requestHeaders?: Record<string, string> }
+    | undefined;
+  if (!updates?.url || typeof Updates.setUpdateRequestHeadersOverride !== 'function') {
+    return null;
+  }
+
+  const requestHeaders = updates.requestHeaders ?? {};
+  // A key whose value came from an unset env var is dropped from the config
+  // entirely, so this checks presence rather than truthiness — the empty string
+  // is a declaration, undefined is not.
+  const missing = REQUIRED_BUILD_HEADERS.filter(key => !declared(requestHeaders, key));
+  if (missing.length > 0) {
+    // Loud, because the symptom is a panel that never appears and the cause is
+    // three lines away in app config.
+    console.warn(
+      `[xprem] Branch surfing is unavailable: ${missing.join(', ')} ${
+        missing.length === 1 ? 'is' : 'are'
+      } missing from updates.requestHeaders. A header can only be overridden at ` +
+        `runtime if it was declared at build time.`
+    );
+    return null;
+  }
+
+  const appId = requestHeaders['expo-app-id'];
+  const channel = Updates.channel;
+  const runtimeVersion = Updates.runtimeVersion;
+  if (!appId || !channel || !runtimeVersion) {
+    return null;
+  }
+
+  let baseUrl: string;
+  try {
+    // Sibling of the manifest route, not root of the host: a self-hosted server
+    // at https://host/ota/manifest serves https://host/ota/branch_lists. Using
+    // the origin alone sent every request to the wrong path, and the 404 that
+    // came back was indistinguishable from "this channel does not allow it".
+    const parsed = new URL(updates.url);
+    // Trailing slashes go first: on ".../manifest/" the segment removal would
+    // otherwise eat the empty part after the slash and leave "manifest" in the
+    // path, sending every request one level too deep.
+    baseUrl = parsed.origin + parsed.pathname.replace(/\/+$/, '').replace(/\/[^/]*$/, '');
+  } catch {
+    return null;
+  }
+
+  return { baseUrl, appId, channel, runtimeVersion, requestHeaders };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { ControlCenter, openControlCenter } from './ControlCenter';
+export type { SurfableBranch } from './surf';

package/src/surf.ts

@@ -0,0 +1,152 @@
+import * as Updates from 'expo-updates';
+import { Platform } from 'react-native';
+import { BRANCH_HEADER, SurfConfig } from './config';
+
+export type SurfableBranch = {
+  name: string;
+  lastUpdateAt: string;
+};
+
+/** A page of branches, plus how many matched in all, so the panel can offer the rest. */
+/** Set by the server on a 404 it decided, so a proxy's 404 is not mistaken for one. */
+const SURFING_DISABLED_HEADER = 'xprem-branch-surfing';
+
+export type BranchPage = {
+  branches: SurfableBranch[];
+  total: number;
+};
+
+/**
+ * Asks the server which branches this build may be served. Returns null when the
+ * channel does not allow surfing at all — distinct from an empty page, which
+ * means it does but has nothing else built for this runtime version. The panel
+ * hides itself on null and shows an empty state on [].
+ *
+ * The default answer is the newest 50; pass all to ask for the rest, which the
+ * panel only does when a tester taps for it.
+ */
+export async function listBranches(
+  config: SurfConfig,
+  signal?: AbortSignal,
+  all = false
+): Promise<BranchPage | null> {
+  const response = await fetch(`${config.baseUrl}/branch_lists${all ? '?all=1' : ''}`, {
+    method: 'GET',
+    headers: {
+      'expo-app-id': config.appId,
+      'expo-channel-name': config.channel,
+      'expo-runtime-version': config.runtimeVersion,
+      // The list is per platform, like the manifest: a branch whose only update
+      // is for the other one cannot be served here, so it must not be offered.
+      'expo-platform': Platform.OS,
+    },
+    signal,
+  });
+  if (response.status === 404) {
+    // Turning surfing off for a channel has to reach the devices already pinned
+    // to a branch, and this is the only place it can: the panel hides itself on
+    // this answer, so after it does there is no interface left to unpin from.
+    // Left pinned, a device would silently resume surfing the moment surfing was
+    // switched back on, onto a branch nobody chose in that session.
+    //
+    // Gated on the server saying so, not on the status alone: any 404 used to
+    // trigger this, so an old server, a proxy, or a path-based deployment wiped
+    // the tester's branch at every launch with nothing said anywhere.
+    if (response.headers.get(SURFING_DISABLED_HEADER) !== null) {
+      pin(config, null);
+    }
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(`Could not reach the update server (${response.status}).`);
+  }
+  const page = (await response.json()) as BranchPage;
+  // The build carrying this code outlives the server it was written against, so
+  // a body of another shape hides the panel rather than crashing the host app.
+  if (!page || !Array.isArray(page.branches) || typeof page.total !== 'number') {
+    return null;
+  }
+  return page;
+}
+
+/**
+ * Rebuilds the WHOLE header set with one value changed: the override replaces
+ * the native set and persists across relaunches.
+ *
+ * The channel and app id are pinned from the running values rather than trusted
+ * from Constants.expoConfig: that copy is evaluated when the JS bundle is
+ * exported, and a config spelled `process.env.RELEASE_CHANNEL` evaluates to
+ * undefined in any bundle exported without the variable. Spreading it then
+ * strips the channel out of every future poll — observed live as /manifest
+ * answering 400 "No channel name provided" until the override is cleared.
+ */
+/**
+ * What this session last pinned, so a surf that fails partway can put it back.
+ * undefined means "not set by us": the override may still hold something from an
+ * earlier session, which nothing on the client can read back — expo-updates
+ * exposes no getter — so the only honest restore in that case is to clear it.
+ */
+let pinnedBranch: string | null | undefined;
+
+function pin(config: SurfConfig, branch: string | null) {
+  if (branch === null) {
+    // Not "override with an empty value" — no override at all. The native side
+    // reverts to the headers baked at build time, the one state that cannot be
+    // wrong.
+    Updates.setUpdateRequestHeadersOverride(null);
+  } else {
+    applyBranchHeader(config, branch);
+  }
+  pinnedBranch = branch;
+}
+
+function applyBranchHeader(config: SurfConfig, branch: string) {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(config.requestHeaders)) {
+    // Empty values are dropped, and that is load-bearing rather than tidy.
+    // expo-updates applies this header set LAST, after the server-defined
+    // headers it has stored, and each entry REPLACES rather than adds — so an
+    // empty xprem-surf-blocked declared in app config would wipe the refusal
+    // verdicts on every poll and let a crashing update be served again.
+    if (typeof value === 'string' && value !== '') {
+      headers[key] = value;
+    }
+  }
+  headers['expo-channel-name'] = config.channel;
+  headers['expo-app-id'] = config.appId;
+  headers[BRANCH_HEADER] = branch;
+  Updates.setUpdateRequestHeadersOverride(headers);
+}
+
+export type SurfOutcome = 'reloading' | 'nothing-to-load';
+
+/**
+ * Points this device at a branch and reloads onto it. Returns without reloading
+ * when the server has nothing new: the caller says so rather than leaving the
+ * tester looking at an unchanged screen.
+ */
+export async function surfTo(config: SurfConfig, branch: string | null): Promise<SurfOutcome> {
+  // The override has to be in place before checkForUpdateAsync, since that is
+  // the request it governs — so a failure after this line leaves the device
+  // pinned to a branch it never loaded, persistently and across relaunches,
+  // while the panel still shows the old one. Whatever happens below, the device
+  // must not be left pointing somewhere the tester was not told about.
+  const previous = pinnedBranch;
+  pin(config, branch);
+  try {
+    return await runSurf(config);
+  } catch (cause) {
+    pin(config, previous ?? null);
+    throw cause;
+  }
+}
+
+async function runSurf(_config: SurfConfig): Promise<SurfOutcome> {
+  const { isAvailable } = await Updates.checkForUpdateAsync();
+  if (!isAvailable) {
+    return 'nothing-to-load';
+  }
+  await Updates.fetchUpdateAsync();
+  await Updates.reloadAsync();
+  return 'reloading';
+}

package/src/theme.ts

@@ -0,0 +1,43 @@
+/**
+ * White cards floating on a light page, bold near-black type, one black pill for
+ * the primary action — the register of the Expo dashboard's branch page, which is
+ * where these testers already read about branches.
+ */
+export const palette = {
+  page: '#F6F7F9',
+  surface: '#FFFFFF',
+  surfacePressed: '#EFF1F4',
+  border: 'rgba(17, 24, 39, 0.07)',
+  ink: '#111418',
+  muted: '#6B7280',
+  /** The warm chip the dashboard uses for "Available on". */
+  chipBg: '#FFF1E7',
+  chipInk: '#8A4B1A',
+  pill: '#14171A',
+  pillInk: '#FFFFFF',
+  live: '#22C55E',
+  warnBg: '#FFF6E5',
+  warnInk: '#8A5A08',
+  danger: '#C5221F',
+};
+
+export const type = {
+  hero: { fontSize: 28, fontWeight: '700' as const, color: palette.ink },
+  section: { fontSize: 18, fontWeight: '700' as const, color: palette.ink },
+  rowTitle: { fontSize: 17, fontWeight: '600' as const, color: palette.ink },
+  meta: { fontSize: 14, color: palette.muted },
+  label: { fontSize: 15, color: palette.muted },
+  chip: { fontSize: 14, fontWeight: '500' as const, color: palette.chipInk },
+  pill: { fontSize: 16, fontWeight: '600' as const, color: palette.pillInk },
+};
+
+export const radius = { card: 16, chip: 8, pill: 999 };
+export const space = { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 };
+
+export const cardShadow = {
+  shadowColor: '#0B1220',
+  shadowOpacity: 0.05,
+  shadowRadius: 10,
+  shadowOffset: { width: 0, height: 2 },
+  elevation: 1,
+};