feat(mobile): Wave 5 sessions-list tier — TS-4 closes (Sprint 1 / PR 7 of 7)

apps/mobile/.rnstorybook/.gitignore

@@ -0,0 +1 @@
+storybook.requires.ts

apps/mobile/.rnstorybook/StorybookRouterProvider.tsx

@@ -0,0 +1,57 @@
+import {
+	PreviewRouteContext,
+	type PreviewRouteContextType,
+} from "expo-router/build/link/preview/PreviewRouteContext";
+import {
+	LinkingContext,
+	NavigationContainer,
+	NavigationContainerRefContext,
+	ThemeProvider,
+	UNSTABLE_UnhandledLinkingContext as UnhandledLinkingContext,
+} from "expo-router/react-navigation";
+import { type PropsWithChildren, useContext } from "react";
+import { NAV_THEME } from "@/lib/theme";
+
+import {
+	storybookLinkingContext,
+	storybookLinkingOptions,
+} from "./router/LinkingContext";
+import { storybookUnhandledLinkingContext } from "./router/UnhandledLinkingContext";
+
+const storybookRoute = {
+	pathname: "/storybook",
+	params: {},
+	segments: ["storybook"],
+} satisfies PreviewRouteContextType;
+
+export function StorybookRouterProvider({ children }: PropsWithChildren) {
+	const navigationRef = useContext(NavigationContainerRefContext);
+
+	const content = (
+		<ThemeProvider value={NAV_THEME.dark}>
+			<UnhandledLinkingContext.Provider
+				value={storybookUnhandledLinkingContext}
+			>
+				<LinkingContext.Provider value={storybookLinkingContext}>
+					<PreviewRouteContext.Provider value={storybookRoute}>
+						{children}
+					</PreviewRouteContext.Provider>
+				</LinkingContext.Provider>
+			</UnhandledLinkingContext.Provider>
+		</ThemeProvider>
+	);
+
+	if (navigationRef) {
+		return content;
+	}
+
+	return (
+		<NavigationContainer
+			fallback={null}
+			linking={storybookLinkingOptions}
+			theme={NAV_THEME.dark}
+		>
+			{content}
+		</NavigationContainer>
+	);
+}

apps/mobile/.rnstorybook/index.tsx

@@ -0,0 +1,26 @@
+// Entry point used by app/_layout.tsx when EXPO_PUBLIC_STORYBOOK=true.
+// `storybook.requires` is generated by `sb-rn-get-stories` at dev-time —
+// see the "storybook" script in package.json. It is gitignored.
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { StorybookRouterProvider } from "./StorybookRouterProvider";
+import { view } from "./storybook.requires";
+
+// Storybook v9 react-native requires the `storage` adapter to be passed
+// explicitly when `shouldPersistSelection: true` — it does not auto-detect
+// AsyncStorage. Without this, attempts to read the persisted story selection
+// throw `TypeError: Cannot read property 'getItem' of undefined`.
+const StorybookUIRoot = view.getStorybookUI({
+	shouldPersistSelection: true,
+	storage: {
+		getItem: AsyncStorage.getItem,
+		setItem: AsyncStorage.setItem,
+	},
+});
+
+export default function StorybookRoot() {
+	return (
+		<StorybookRouterProvider>
+			<StorybookUIRoot />
+		</StorybookRouterProvider>
+	);
+}

apps/mobile/.rnstorybook/main.js

@@ -0,0 +1,39 @@
+/** @type {import('@storybook/react-native').StorybookConfig} */
+const main = {
+	stories: [
+		"./stories/**/*.stories.?(ts|tsx|js|jsx)",
+		"../components/**/*.stories.?(ts|tsx|js|jsx)",
+		// Wave 4 — chat-view view stories (pixel-perfect Phase 6 COMPOSE).
+		// Narrow glob points only at `screens/chat-view/` because nothing in
+		// that subtree imports expo-router or `useTheme`. The broader
+		// `../screens/**` glob remains disabled — adding it would re-trigger
+		// the prep-time `UnhandledLinkingContext` crash described below.
+		"../screens/chat-view/**/*.stories.?(ts|tsx|js|jsx)",
+		// Wave 5 — sessions-list view stories. Same narrow-glob constraint as
+		// chat-view (above): nothing in this subtree imports expo-router or
+		// `useTheme`, so prep-time `loadStory` is safe.
+		"../screens/sessions-list/**/*.stories.?(ts|tsx|js|jsx)",
+		// "../screens/**/*.stories.?(ts|tsx|js|jsx)",
+		// ^ Disabled 2026-05-22. Screen placeholder stories transitively import
+		// `useTheme` → `lib/theme.ts` → `expo-router/react-navigation`. Storybook 9
+		// RN's `loadStory` (called during `createPreparedStoryMapping`) evaluates
+		// each story module eagerly BEFORE decorators apply, and ends up calling
+		// expo-router's `useLinking` family which crashes accessing the default
+		// `UnhandledLinkingContext` value outside a `<NavigationContainer>`.
+		//
+		// Wrapping decorators in `<NavigationContainer>` from
+		// `expo-router/react-navigation` (kept in preview.tsx) does NOT help here
+		// because Storybook's prep-time render happens outside the decorator chain.
+		//
+		// To restore screen stories: refactor them to avoid `useTheme` / decouple
+		// from `lib/theme.ts` (mirror the pattern used in components/ScrollFade),
+		// or use `expo-router/testing-library`'s `renderRouter` helper inside a
+		// custom story `render` function.
+	],
+	addons: [
+		"@storybook/addon-ondevice-controls",
+		"@storybook/addon-ondevice-actions",
+	],
+};
+
+module.exports = main;

apps/mobile/.rnstorybook/mocks/tty.js

@@ -0,0 +1 @@
+module.exports = {};

apps/mobile/.rnstorybook/preview.tsx

@@ -0,0 +1,35 @@
+import { PortalHost } from "@rn-primitives/portal";
+import type { Preview } from "@storybook/react-native";
+import { View } from "react-native";
+import { cn } from "@/lib/utils";
+
+// NavigationContainer is provided by StorybookRouterProvider —
+// do NOT add one here or SDK 56's expo-router compat check will fail.
+const preview: Preview = {
+	decorators: [
+		(Story, context) => {
+			const isFullscreen = context.parameters?.layout === "fullscreen";
+			return (
+				<View className={cn("flex-1 bg-background", !isFullscreen && "p-4")}>
+					<Story />
+					<PortalHost />
+				</View>
+			);
+		},
+	],
+	parameters: {
+		controls: {
+			matchers: {
+				color: /(background|color|foreground)$/i,
+				date: /Date$/i,
+			},
+		},
+		moduleMock: {
+			mockingPairedModules: {
+				tty: () => require("./mocks/tty"),
+			},
+		},
+	},
+};
+
+export default preview;

apps/mobile/.rnstorybook/router/LinkingContext.ts

@@ -0,0 +1,23 @@
+import type {
+	LinkingOptions,
+	ParamListBase,
+} from "expo-router/react-navigation";
+import * as React from "react";
+
+export const storybookLinkingOptions: LinkingOptions<ParamListBase> = {
+	enabled: false,
+	prefixes: [],
+	config: {
+		screens: {
+			Storybook: "*",
+		},
+	},
+};
+
+export const storybookLinkingContext = {
+	options: storybookLinkingOptions,
+};
+
+export const LinkingContext = React.createContext(storybookLinkingContext);
+
+LinkingContext.displayName = "LinkingContext";

apps/mobile/.rnstorybook/router/UnhandledLinkingContext.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+
+export type StorybookUnhandledLinkingContextValue = {
+	lastUnhandledLink: string | undefined;
+	setLastUnhandledLink: (lastUnhandledUrl: string | undefined) => void;
+};
+
+export const storybookUnhandledLinkingContext: StorybookUnhandledLinkingContextValue =
+	{
+		lastUnhandledLink: undefined,
+		setLastUnhandledLink: () => {},
+	};
+
+export const UnhandledLinkingContext =
+	React.createContext<StorybookUnhandledLinkingContextValue>(
+		storybookUnhandledLinkingContext,
+	);
+
+UnhandledLinkingContext.displayName = "UnhandledLinkingContext";

apps/mobile/app/_layout.tsx

@@ -1,6 +1,51 @@
 import "react-native-get-random-values"; // MUST BE FIRST IMPORT
 import "../global.css";
 
+import {
+	Geist_400Regular,
+	Geist_500Medium,
+	Geist_600SemiBold,
+	Geist_700Bold,
+	useFonts,
+} from "@expo-google-fonts/geist";
+import {
+	GeistMono_400Regular,
+	GeistMono_500Medium,
+} from "@expo-google-fonts/geist-mono";
+import * as SplashScreen from "expo-splash-screen";
+import { useEffect } from "react";
 import { RootLayout } from "@/screens/RootLayout";
 
-export default RootLayout;
+SplashScreen.preventAutoHideAsync().catch(() => {
+	/* splash already hidden — fine to swallow */
+});
+
+const StorybookRoot =
+	process.env.EXPO_PUBLIC_STORYBOOK === "true"
+		? require("../.rnstorybook").default
+		: null;
+
+export default function App() {
+	const [fontsLoaded, fontError] = useFonts({
+		Geist_400Regular,
+		Geist_500Medium,
+		Geist_600SemiBold,
+		Geist_700Bold,
+		GeistMono_400Regular,
+		GeistMono_500Medium,
+	});
+
+	useEffect(() => {
+		if (fontsLoaded || fontError) {
+			if (fontError) {
+				console.error("Font loading failed:", fontError);
+			}
+			SplashScreen.hideAsync().catch(() => {});
+		}
+	}, [fontsLoaded, fontError]);
+
+	if (!fontsLoaded && !fontError) return null;
+
+	const Root = StorybookRoot ?? RootLayout;
+	return <Root />;
+}

apps/mobile/components/AppHeader/AppHeader.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react-native";
+import { Settings } from "lucide-react-native";
+import { AppHeader } from "./AppHeader";
+
+const meta: Meta<typeof AppHeader> = {
+	title: "Molecules/AppHeader",
+	component: AppHeader,
+	parameters: {
+		docs: {
+			description: {
+				component:
+					"Top navigation header on every chat view. Three-region flex: leading back IconButton (optional) + centered title/subtitle + trailing actions IconButton (optional). `isScrolled` adds a layered shadow for separation from scrolling content. Composes first-party IconButton + Text.",
+			},
+		},
+		layout: "fullscreen",
+	},
+	args: {
+		title: "Fix auth bug",
+		subtitle: "superset · main",
+		showBack: true,
+		showActions: true,
+		isScrolled: false,
+	},
+	argTypes: {
+		title: { control: "text" },
+		subtitle: { control: "text" },
+		showBack: { control: "boolean" },
+		showActions: { control: "boolean" },
+		isScrolled: { control: "boolean", description: "Adds 1px bottom shadow" },
+	},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AppHeader>;
+
+export const Default: Story = {};
+
+export const NoSubtitle: Story = {
+	args: { subtitle: undefined },
+};
+
+export const NoBack: Story = {
+	args: { showBack: false, title: "Sessions" },
+};
+
+export const SimpleNoActions: Story = {
+	args: { subtitle: undefined, showActions: false },
+};
+
+export const Scrolled: Story = {
+	args: { isScrolled: true },
+};
+
+export const CustomActionsIcon: Story = {
+	args: { actionsIcon: Settings, actionsAccessibilityLabel: "Settings" },
+};