@aurostack/stacks 0.1.0

package/templates/react-app/files/src/shared/api/base-query.ts

@@ -0,0 +1,29 @@
+import { fetchBaseQuery, type BaseQueryFn, type FetchArgs, type FetchBaseQueryError } from '@reduxjs/toolkit/query';
+import { getApiBaseUrl, notifyUnauthorized } from './config';
+
+const rawBaseQuery = fetchBaseQuery({
+	baseUrl: '',
+	credentials: 'include'
+});
+
+/**
+ * Shared base query: sends the Better Auth session cookie (credentials:'include'),
+ * prefixes the configured API base URL, and routes 401s to the app's re-auth
+ * handler (registered via configureApi) — the single chokepoint for session expiry.
+ */
+export const baseQueryWithReauth: BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError> = async (
+	args,
+	api,
+	extraOptions
+) => {
+	const base = getApiBaseUrl();
+	const withBase = typeof args === 'string' ? `${base}${args}` : { ...args, url: `${base}${args.url}` };
+
+	const result = await rawBaseQuery(withBase, api, extraOptions);
+
+	if (result.error && result.error.status === 401) {
+		notifyUnauthorized();
+	}
+
+	return result;
+};

package/templates/react-app/files/src/shared/api/config.ts

@@ -0,0 +1,21 @@
+// Runtime configuration for @/shared/api. The consuming app calls configureApi()
+// once at startup (before creating the store or issuing requests) to inject the
+// backend base URL and the 401 -> re-auth redirect handler (from @/shared/auth).
+
+let apiBaseUrl = '';
+let onUnauthorized: () => void = () => {};
+
+export function configureApi(options: { baseUrl: string; onUnauthorized?: () => void }): void {
+	apiBaseUrl = options.baseUrl.replace(/\/$/, '');
+	if (options.onUnauthorized) {
+		onUnauthorized = options.onUnauthorized;
+	}
+}
+
+export function getApiBaseUrl(): string {
+	return apiBaseUrl;
+}
+
+export function notifyUnauthorized(): void {
+	onUnauthorized();
+}

package/templates/react-app/files/src/shared/api/index.ts

@@ -0,0 +1,15 @@
+// @/shared/api — shared Redux store + RTK Query base + Socket.IO client.
+export { baseApi } from './base-api';
+export { baseQueryWithReauth } from './base-query';
+export { uploadBaseQuery } from './upload-query';
+export type { UploadArgs } from './upload-query';
+export { configureApi, getApiBaseUrl, notifyUnauthorized } from './config';
+export { makeStore } from './store';
+export type { AppStore } from './store';
+// @feature:start realtime
+export { connectSocket, getSocket, disconnectSocket, joinRoom, leaveRoom } from './socket';
+export { ServerEvent, ClientEvent, FEED_ROOM, channelRoom } from './realtime-events';
+// @feature:end
+
+// Convenience re-exports so apps get their Redux bindings from one place.
+export { Provider, useDispatch, useSelector, useStore } from 'react-redux';

package/templates/react-app/files/src/shared/api/realtime-events.ts

@@ -0,0 +1,34 @@
+/**
+ * Frontend mirror of the backend realtime wire contract
+ * (backend: `src/realtime/constants`). Keep these names in lockstep with the
+ * server — they are the single source of truth for what the socket speaks, and
+ * a rename on one side that is not mirrored on the other fails silently: the
+ * listener simply never fires.
+ */
+
+/** Server → client event names. */
+export const ServerEvent = {
+	/** Presence roster changed. */
+	PRESENCE_UPDATE: 'presence:update',
+	/** Someone started/stopped typing in a room. */
+	TYPING: 'activity:typing',
+	/** Someone is viewing a resource. */
+	VIEWING: 'activity:viewing',
+	/** A user-directed notification. Scoped to `user:<id>`. */
+	NOTIFICATION: 'notification',
+	/** Something in a channel changed; payload is app-defined. */
+	CHANNEL_UPDATE: 'channel:update'
+} as const;
+
+/** Client → server event names. */
+export const ClientEvent = {
+	JOIN_ROOM: 'room:join',
+	LEAVE_ROOM: 'room:leave',
+	TYPING: 'activity:typing',
+	VIEWING: 'activity:viewing'
+} as const;
+
+/** Firehose room — members see every broadcast on the default channel. */
+export const FEED_ROOM = 'feed';
+/** Room scoped to a single resource. */
+export const channelRoom = (channelId: string) => `channel:${channelId}`;

package/templates/react-app/files/src/shared/api/socket.ts

@@ -0,0 +1,41 @@
+import { io, type Socket } from 'socket.io-client';
+import { ClientEvent } from './realtime-events';
+
+let socket: Socket | null = null;
+
+/**
+ * Connect the realtime Socket.IO client. The Better Auth session cookie is
+ * carried on the handshake via withCredentials. Feature event wiring + the RTK
+ * Query cache bridge land in Phase 2+.
+ */
+export function connectSocket(url: string): Socket {
+	if (socket) {
+		if (!socket.connected) socket.connect();
+		return socket;
+	}
+	socket = io(url, {
+		withCredentials: true,
+		path: '/realtime',
+		autoConnect: true
+	});
+	return socket;
+}
+
+export function getSocket(): Socket | null {
+	return socket;
+}
+
+/** Join a server-side room (forum feed / thread). No-op until connected. */
+export function joinRoom(room: string): void {
+	socket?.emit(ClientEvent.JOIN_ROOM, { room });
+}
+
+/** Leave a previously joined room. */
+export function leaveRoom(room: string): void {
+	socket?.emit(ClientEvent.LEAVE_ROOM, { room });
+}
+
+export function disconnectSocket(): void {
+	socket?.disconnect();
+	socket = null;
+}

package/templates/react-app/files/src/shared/api/store.ts

@@ -0,0 +1,39 @@
+import { configureStore, type Middleware, type Reducer } from '@reduxjs/toolkit';
+import { setupListeners } from '@reduxjs/toolkit/query';
+import { baseApi } from './base-api';
+
+type MakeStoreOptions = {
+	/** App-specific slice reducers (e.g. authSlice, feature UI slices). */
+	reducer?: Record<string, Reducer>;
+	/** Extra middleware (e.g. the socket middleware). */
+	middleware?: Middleware[];
+};
+
+/**
+ * Create an app store wired with the shared RTK Query API + any app slices.
+ * Each app derives its own typed hooks from the returned store, e.g.:
+ *   export const useAppDispatch = useDispatch.withTypes<typeof store.dispatch>();
+ *   export const useAppSelector = useSelector.withTypes<ReturnType<typeof store.getState>>();
+ */
+export function makeStore(options: MakeStoreOptions = {}) {
+	const store = configureStore({
+		reducer: {
+			[baseApi.reducerPath]: baseApi.reducer,
+			...options.reducer
+		},
+		middleware: (getDefaultMiddleware) =>
+			getDefaultMiddleware({
+				serializableCheck: {
+					// Upload endpoints (see `uploadBaseQuery`) carry a FormData body and an
+					// `onProgress` callback in their args. Neither is serializable, and
+					// neither is ever persisted or replayed — only read once, in flight.
+					ignoredActionPaths: ['meta.arg.originalArgs.body', 'meta.arg.originalArgs.onProgress']
+				}
+			}).concat(baseApi.middleware, ...(options.middleware ?? []))
+	});
+
+	setupListeners(store.dispatch);
+	return store;
+}
+
+export type AppStore = ReturnType<typeof makeStore>;

package/templates/react-app/files/src/shared/api/upload-query.ts

@@ -0,0 +1,115 @@
+import type { BaseQueryFn, FetchBaseQueryError } from '@reduxjs/toolkit/query';
+import { getApiBaseUrl, notifyUnauthorized } from './config';
+
+/** How long an upload may stall (no bytes acknowledged) before we give up. */
+const DEFAULT_STALL_TIMEOUT_MS = 45_000;
+
+export type UploadArgs = {
+	url: string;
+	body: FormData;
+	method?: 'POST' | 'PUT' | 'PATCH';
+	/** Called with 0-100 as the request body is written to the socket. */
+	onProgress?: (percent: number) => void;
+	/**
+	 * Abort if no upload progress is observed for this many ms. Guards against a
+	 * connection that opens, stalls mid-body and never errors on its own — the
+	 * common failure on slow mobile uplinks.
+	 */
+	stallTimeoutMs?: number;
+};
+
+/** RTK Query's own marker for an aborted-by-timeout request. */
+const TIMEOUT_ERROR: FetchBaseQueryError = {
+	status: 'TIMEOUT_ERROR',
+	error: 'The upload stalled. Check your connection and try again.'
+};
+
+function parseBody(xhr: XMLHttpRequest): unknown {
+	const text = xhr.responseText;
+	if (!text) return undefined;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+
+/**
+ * Multipart uploads over XMLHttpRequest instead of `fetch`.
+ *
+ * `fetchBaseQuery` cannot report request-body progress (the Fetch API exposes no
+ * upload stream events), so a large file on a slow connection is indistinguishable
+ * from a hung request — the UI can only show an indefinite spinner. XHR still
+ * emits `upload.onprogress`, which lets callers render real progress and lets us
+ * abort a stalled transfer rather than waiting on the OS socket timeout.
+ *
+ * Mirrors `baseQueryWithReauth`: prefixes the configured API base URL, sends the
+ * session cookie, and routes 401s to the shared re-auth handler.
+ */
+export const uploadBaseQuery: BaseQueryFn<UploadArgs, unknown, FetchBaseQueryError> = (args) =>
+	new Promise((resolve) => {
+		const { url, body, method = 'POST', onProgress, stallTimeoutMs = DEFAULT_STALL_TIMEOUT_MS } = args;
+		const xhr = new XMLHttpRequest();
+
+		let stallTimer: ReturnType<typeof setTimeout> | undefined;
+		let settled = false;
+
+		const cleanup = () => {
+			if (stallTimer) clearTimeout(stallTimer);
+		};
+
+		const settle = (result: { data: unknown } | { error: FetchBaseQueryError }) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(result);
+		};
+
+		// Restarted on every progress event; only fires when the socket goes quiet.
+		const armStallTimer = () => {
+			if (stallTimer) clearTimeout(stallTimer);
+			stallTimer = setTimeout(() => {
+				xhr.abort();
+				settle({ error: TIMEOUT_ERROR });
+			}, stallTimeoutMs);
+		};
+
+		xhr.open(method, `${getApiBaseUrl()}${url}`, true);
+		// Matches fetchBaseQuery's `credentials: 'include'` — Better Auth session cookie.
+		xhr.withCredentials = true;
+
+		xhr.upload.onprogress = (event) => {
+			armStallTimer();
+			if (!event.lengthComputable || !onProgress) return;
+			onProgress(Math.round((event.loaded / event.total) * 100));
+		};
+
+		// Body is fully written; the server is now working. Keep the stall guard
+		// running so a server that accepts the bytes and then hangs still fails.
+		xhr.upload.onload = () => {
+			onProgress?.(100);
+			armStallTimer();
+		};
+
+		xhr.onload = () => {
+			const data = parseBody(xhr);
+			if (xhr.status >= 200 && xhr.status < 300) {
+				settle({ data });
+				return;
+			}
+			if (xhr.status === 401) notifyUnauthorized();
+			settle({ error: { status: xhr.status, data } as FetchBaseQueryError });
+		};
+
+		xhr.onerror = () => {
+			settle({
+				error: { status: 'FETCH_ERROR', error: 'The upload failed. Check your connection and try again.' }
+			});
+		};
+
+		// Fires when the transfer is cut mid-body — the truncated-upload case.
+		xhr.onabort = () => settle({ error: TIMEOUT_ERROR });
+
+		armStallTimer();
+		xhr.send(body);
+	});

package/templates/react-app/files/src/shared/auth/client.ts

@@ -0,0 +1,27 @@
+import { createAuthClient } from 'better-auth/react';
+import { adminClient } from 'better-auth/client/plugins';
+
+function makeClient(baseURL: string) {
+	// The admin plugin adds `authClient.admin.*` (list/ban/unban/setRole). The
+	// methods are always present but the backend enforces the caller's role, so
+	// including them here is harmless for non-admin apps.
+	return createAuthClient({ baseURL, plugins: [adminClient()] });
+}
+
+let client: ReturnType<typeof makeClient> | null = null;
+
+/** Initialize the Better Auth client singleton (idempotent). */
+export function initAuthClient(baseURL: string) {
+	client ??= makeClient(baseURL);
+	return client;
+}
+
+/** The Better Auth client. Throws if not initialized (call configureAuth first). */
+export function getAuthClient() {
+	if (!client) {
+		throw new Error('Auth client not initialized. Call configureAuth({ authApiBaseUrl, ... }) at app startup.');
+	}
+	return client;
+}
+
+export type AuthClient = ReturnType<typeof makeClient>;

package/templates/react-app/files/src/shared/auth/config.ts

@@ -0,0 +1,28 @@
+import { initAuthClient } from './client';
+import { configureRedirects } from './redirect';
+
+/**
+ * One-shot auth wiring, called once at startup (before rendering).
+ *
+ * There is no `authAppUrl` here, unlike the multi-app build of this stack: the
+ * auth screens are routes in this bundle, so login is a path within the same
+ * origin. `trustedOrigins` therefore defaults to this app's own origin — the
+ * complete answer unless you deliberately hand off to another host.
+ */
+export function configureAuth(options: {
+	/** Backend Better Auth base URL (e.g. https://api.example.com/auth). */
+	authApiBaseUrl: string;
+	/** Route the login screen is mounted at. Defaults to `/login`. */
+	loginPath?: string;
+	/** Origins allowed as a post-login redirect target. Defaults to this origin. */
+	trustedOrigins?: string[];
+	/** Where a login with no `?redirect=` lands. */
+	defaultRedirect?: string;
+}): void {
+	initAuthClient(options.authApiBaseUrl);
+	configureRedirects({
+		loginPath: options.loginPath,
+		trustedOrigins: options.trustedOrigins,
+		defaultRedirect: options.defaultRedirect
+	});
+}

package/templates/react-app/files/src/shared/auth/guards.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react';
+import { Navigate, Outlet, useLocation } from 'react-router';
+import { useAuth } from './hooks';
+import { loginRedirect } from './redirect';
+
+type GuardProps = {
+	children?: ReactNode;
+	/**
+	 * Shown while the session is resolving.
+	 *
+	 * Required on purpose. This used to default to `null`, which meant the app
+	 * rendered *nothing* for the entire session round trip — ~880 ms measured
+	 * against a deployed API, and worse on mobile. Pass the shell skeleton so the
+	 * frame is on screen while the session resolves; there is no correct case for
+	 * gating a whole app behind a blank screen.
+	 */
+	fallback: ReactNode;
+};
+
+/**
+ * Requires any authenticated session; otherwise sends the visitor to `/login`
+ * with a `?redirect=` back to where they were.
+ *
+ * `<Navigate>` rather than `window.location.assign`: the login screen is a route
+ * in this same bundle, so a full page load would re-download and re-boot the app
+ * to render a screen it already has. `replace` keeps the guarded URL out of
+ * history — without it, Back from the login screen bounces straight through the
+ * guard again.
+ */
+export function ProtectedRoute({ children, fallback }: GuardProps) {
+	const { status } = useAuth();
+	const location = useLocation();
+
+	if (status === 'loading') return <>{fallback}</>;
+	if (status === 'unauthenticated') {
+		return <Navigate to={loginRedirect(location.pathname + location.search)} replace />;
+	}
+	return <>{children ?? <Outlet />}</>;
+}
+
+type RoleRouteProps = GuardProps & {
+	/** Roles allowed to view (any match). Compared against session.user.role. */
+	allow: string[];
+	/**
+	 * Rendered when authenticated but lacking a required role (403). Required for
+	 * the same reason as `fallback` — a silent blank 403 looks like a broken app.
+	 */
+	forbidden: ReactNode;
+};
+
+/**
+ * Requires an authenticated session AND one of `allow` roles.
+ * 401 (no session) -> the login screen; 403 (wrong role) -> `forbidden`.
+ *
+ * This is a UI affordance, not a security boundary: the role it reads comes from
+ * the session the browser holds, so it decides what to *render*. Every endpoint
+ * behind it must enforce the same role server-side.
+ */
+export function RoleRoute({ allow, children, fallback, forbidden }: RoleRouteProps) {
+	const { status, user } = useAuth();
+	const location = useLocation();
+
+	if (status === 'loading') return <>{fallback}</>;
+	if (status === 'unauthenticated') {
+		return <Navigate to={loginRedirect(location.pathname + location.search)} replace />;
+	}
+
+	const roles = (user?.role ?? '')
+		.split(',')
+		.map((role) => role.trim())
+		.filter(Boolean);
+	if (!allow.some((role) => roles.includes(role))) return <>{forbidden}</>;
+
+	return <>{children ?? <Outlet />}</>;
+}

package/templates/react-app/files/src/shared/auth/hooks.ts

@@ -0,0 +1,13 @@
+import { useSelector } from 'react-redux';
+import { selectAuth } from './slice';
+
+/** Synchronous auth state for rendering/gating. Hydrated from Better Auth. */
+export function useAuth() {
+	const { user, status } = useSelector(selectAuth);
+	return {
+		user,
+		status,
+		isAuthenticated: status === 'authenticated',
+		isLoading: status === 'loading'
+	};
+}

package/templates/react-app/files/src/shared/auth/index.ts

@@ -0,0 +1,20 @@
+// @/shared/auth — authentication on Better Auth.
+export { configureAuth } from './config';
+export { initAuthClient, getAuthClient } from './client';
+export type { AuthClient } from './client';
+export { AuthProvider } from './provider';
+export { useAuth } from './hooks';
+export { ProtectedRoute, RoleRoute } from './guards';
+export { redirectToLogin, loginRedirect, getSafeRedirect, configureRedirects } from './redirect';
+export { signOut, broadcastAuthEvent, AUTH_BROADCAST_CHANNEL } from './logout';
+export {
+	authReducer,
+	sessionLoading,
+	sessionLoaded,
+	sessionCleared,
+	selectAuth,
+	selectAuthUser,
+	selectAuthStatus,
+	selectIsAuthenticated
+} from './slice';
+export type { AuthUser, AuthStatus } from './slice';

package/templates/react-app/files/src/shared/auth/logout.ts

@@ -0,0 +1,23 @@
+import { getAuthClient } from './client';
+
+export const AUTH_BROADCAST_CHANNEL = 'acme-auth';
+
+/** Notify other tabs/apps of an auth event (e.g. logout) so stale UI can react. */
+export function broadcastAuthEvent(type: 'login' | 'logout'): void {
+	try {
+		const channel = new BroadcastChannel(AUTH_BROADCAST_CHANNEL);
+		channel.postMessage({ type });
+		channel.close();
+	} catch {
+		/* BroadcastChannel unsupported — no-op */
+	}
+}
+
+/** Sign out (clears the shared-domain cookie), broadcast, then optionally redirect. */
+export async function signOut(options?: { redirectTo?: string }): Promise<void> {
+	await getAuthClient().signOut();
+	broadcastAuthEvent('logout');
+	if (options?.redirectTo) {
+		window.location.assign(options.redirectTo);
+	}
+}

package/templates/react-app/files/src/shared/auth/provider.tsx

@@ -0,0 +1,52 @@
+import { type ReactNode, useEffect } from 'react';
+import { useDispatch } from 'react-redux';
+import { getAuthClient } from './client';
+import { sessionCleared, sessionLoaded, sessionLoading, type AuthUser } from './slice';
+import { AUTH_BROADCAST_CHANNEL } from './logout';
+
+function toAuthUser(user: Record<string, unknown> | null | undefined): AuthUser | null {
+	if (!user) return null;
+	return {
+		id: String(user.id),
+		email: String(user.email ?? ''),
+		name: (user.name as string | undefined) ?? null,
+		image: (user.image as string | undefined) ?? null,
+		role: (user.role as string | undefined) ?? null,
+		emailVerified: Boolean(user.emailVerified),
+		onboardingCompletedAt: (user.onboardingCompletedAt as string | undefined) ?? null
+	};
+}
+
+/**
+ * Bootstraps the Better Auth session and hydrates the authSlice. Must render
+ * inside the Redux <Provider>. Guards read the resulting status for gating.
+ * Also syncs logout across tabs via BroadcastChannel.
+ */
+export function AuthProvider({ children }: { children: ReactNode }) {
+	const dispatch = useDispatch();
+	const session = getAuthClient().useSession();
+
+	useEffect(() => {
+		if (session.isPending) {
+			dispatch(sessionLoading());
+			return;
+		}
+		const user = (session.data?.user as Record<string, unknown> | undefined) ?? null;
+		dispatch(sessionLoaded(toAuthUser(user)));
+	}, [session.isPending, session.data, dispatch]);
+
+	useEffect(() => {
+		let channel: BroadcastChannel | null = null;
+		try {
+			channel = new BroadcastChannel(AUTH_BROADCAST_CHANNEL);
+			channel.onmessage = (event: MessageEvent<{ type?: string }>) => {
+				if (event.data?.type === 'logout') dispatch(sessionCleared());
+			};
+		} catch {
+			/* BroadcastChannel unsupported — no-op */
+		}
+		return () => channel?.close();
+	}, [dispatch]);
+
+	return <>{children}</>;
+}

package/templates/react-app/files/src/shared/auth/redirect.ts

@@ -0,0 +1,65 @@
+// Redirect helpers with open-redirect protection.
+//
+// The multi-app build of this stack puts the auth screens on their own origin,
+// so an unauthenticated user is bounced across hosts and back. Here they are
+// routes in this same bundle, so login is a *path*, not a host — but the
+// allowlist stays exactly as it was: `?redirect=` is still attacker-controllable
+// and a monolith is no less vulnerable to being used as an open redirect than
+// four apps were.
+
+let loginPath = '/login';
+let trustedOrigins: string[] = [];
+let defaultRedirect = '/';
+
+export function configureRedirects(options: {
+	/** Route the auth screens are mounted at. */
+	loginPath?: string;
+	/**
+	 * Origins allowed as a post-login redirect target. Defaults to this app's
+	 * own origin, which is the whole answer for a single deployment; add to it
+	 * only if you deliberately hand off to another host.
+	 */
+	trustedOrigins?: string[];
+	/** Where a login with no `?redirect=` lands. */
+	defaultRedirect?: string;
+}): void {
+	if (options.loginPath) loginPath = options.loginPath;
+	trustedOrigins = (options.trustedOrigins ?? [window.location.origin]).map((origin) => origin.replace(/\/$/, ''));
+	if (options.defaultRedirect) defaultRedirect = options.defaultRedirect;
+}
+
+/** Validate a redirect target against the trusted-origin allowlist. */
+export function getSafeRedirect(target: string | null | undefined, fallback: string = defaultRedirect): string {
+	if (!target) return fallback;
+	try {
+		const url = new URL(target, window.location.origin);
+		if (trustedOrigins.includes(url.origin)) return url.toString();
+	} catch {
+		/* not a valid URL — fall through to fallback */
+	}
+	return fallback;
+}
+
+/**
+ * The login route, carrying where the user was heading.
+ *
+ * Returned as a path rather than navigated to, so the caller can decide: the
+ * route guard renders `<Navigate>` with it (a client-side transition), while the
+ * 401 handler below does a hard load.
+ */
+export function loginRedirect(returnTo: string = window.location.pathname + window.location.search): string {
+	const params = new URLSearchParams({ redirect: returnTo });
+	return `${loginPath}?${params.toString()}`;
+}
+
+/**
+ * Hard navigation to the login screen.
+ *
+ * This is the 401 chokepoint (`configureApi({ onUnauthorized })`), which fires
+ * from outside React — there is no router context to navigate with. A full load
+ * is also the right behaviour here: a 401 means the session died mid-session, so
+ * discarding in-memory state is the point, not a cost.
+ */
+export function redirectToLogin(returnTo?: string): void {
+	window.location.assign(loginRedirect(returnTo));
+}

package/templates/react-app/files/src/shared/auth/slice.ts

@@ -0,0 +1,54 @@
+import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
+
+export type AuthUser = {
+	id: string;
+	email: string;
+	name?: string | null;
+	image?: string | null;
+	role?: string | null;
+	emailVerified: boolean;
+	/** ISO timestamp set when onboarding is finished/skipped; null = not yet onboarded. */
+	onboardingCompletedAt?: string | null;
+};
+
+export type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+
+type AuthState = {
+	user: AuthUser | null;
+	status: AuthStatus;
+};
+
+const initialState: AuthState = {
+	user: null,
+	status: 'loading'
+};
+
+// Minimal projection of the Better Auth session for synchronous, app-wide reads.
+// Better Auth remains the source of truth; this slice is hydrated FROM it (AuthProvider).
+const authSlice = createSlice({
+	name: 'auth',
+	initialState,
+	reducers: {
+		sessionLoading(state) {
+			state.status = 'loading';
+		},
+		sessionLoaded(state, action: PayloadAction<AuthUser | null>) {
+			state.user = action.payload;
+			state.status = action.payload ? 'authenticated' : 'unauthenticated';
+		},
+		sessionCleared(state) {
+			state.user = null;
+			state.status = 'unauthenticated';
+		}
+	}
+});
+
+export const { sessionLoading, sessionLoaded, sessionCleared } = authSlice.actions;
+export const authReducer = authSlice.reducer;
+
+type WithAuth = { auth: AuthState };
+
+export const selectAuth = (state: WithAuth) => state.auth;
+export const selectAuthUser = (state: WithAuth) => state.auth.user;
+export const selectAuthStatus = (state: WithAuth) => state.auth.status;
+export const selectIsAuthenticated = (state: WithAuth) => state.auth.status === 'authenticated';

package/templates/react-app/files/src/shared/hooks/index.ts

@@ -0,0 +1,6 @@
+// @/shared/hooks — cross-cutting React hooks.
+//
+// Deliberately empty. A hook that belongs to one feature belongs *in* that
+// feature; this is for the ones two features would otherwise each grow their own
+// copy of — a media query, a debounce, a BroadcastChannel wrapper.
+export {};