@aurostack/stacks 0.1.0

package/templates/react-app/files/src/app/router.tsx

@@ -0,0 +1,142 @@
+import { Suspense, lazy, type ReactNode } from 'react';
+import { createBrowserRouter } from 'react-router';
+import { ProtectedRoute, signOut, useAuth } from '@/shared/auth';
+import { RoleRoute } from '@/shared/auth'; // @feature admin
+import { AppShell, AppShellSkeleton, ErrorBoundary, MarketingLayout, NotFound, RouteFallback } from '@/shared/layouts';
+import { Forbidden } from '@/shared/layouts'; // @feature admin
+import { appPath } from '@/lib/paths';
+import { ADMIN_BASE } from '@/lib/paths'; // @feature admin
+import { NAV_ITEMS } from './nav';
+import { ADMIN_NAV_ITEMS } from './nav'; // @feature admin
+import { HomeRoute } from '@/routes/home';
+
+/**
+ * Everything but the first page is lazy, so the initial download is the shell
+ * plus one route. The auth screens are lazy too: a logged-in user should never
+ * pay for the login form, and a logged-out one never pays for the app.
+ */
+const SettingsRoute = lazy(() => import('@/routes/settings').then((m) => ({ default: m.SettingsRoute })));
+const TermsRoute = lazy(() => import('@/routes/legal/terms').then((m) => ({ default: m.TermsRoute })));
+const PrivacyRoute = lazy(() => import('@/routes/legal/privacy').then((m) => ({ default: m.PrivacyRoute })));
+// @feature:start marketing
+const LandingRoute = lazy(() => import('@/routes/marketing/home').then((m) => ({ default: m.HomeRoute })));
+// @feature:end
+// @feature:start auth-screens
+const LoginRoute = lazy(() => import('@/routes/auth/login').then((m) => ({ default: m.LoginRoute })));
+const SignupRoute = lazy(() => import('@/routes/auth/signup').then((m) => ({ default: m.SignupRoute })));
+const ForgotPasswordRoute = lazy(() =>
+	import('@/routes/auth/forgot-password').then((m) => ({ default: m.ForgotPasswordRoute }))
+);
+const ResetPasswordRoute = lazy(() =>
+	import('@/routes/auth/reset-password').then((m) => ({ default: m.ResetPasswordRoute }))
+);
+const VerifyEmailRoute = lazy(() =>
+	import('@/routes/auth/verify-email').then((m) => ({ default: m.VerifyEmailRoute }))
+);
+const VerifiedRoute = lazy(() => import('@/routes/auth/verified').then((m) => ({ default: m.VerifiedRoute })));
+// @feature:end
+// @feature:start admin
+const AdminHomeRoute = lazy(() => import('@/routes/admin/home').then((m) => ({ default: m.AdminHomeRoute })));
+// @feature:end
+
+const lazyRoute = (element: ReactNode) => <Suspense fallback={<RouteFallback />}>{element}</Suspense>;
+
+/**
+ * The shell reads the session itself rather than taking it as a prop —
+ * `ProtectedRoute` has already established the user is authenticated by the time
+ * this renders.
+ *
+ * `ErrorBoundary` wraps the shell rather than being passed as the route's
+ * `errorElement`: it is a plain React error boundary taking `children`, so it
+ * catches render errors anywhere below, including inside a lazy chunk.
+ */
+function Shell() {
+	const { user } = useAuth();
+	return (
+		<ErrorBoundary>
+			<AppShell nav={NAV_ITEMS} user={user ?? {}} onSignOut={() => void signOut()} />
+		</ErrorBoundary>
+	);
+}
+
+// @feature:start admin
+function AdminShell() {
+	const { user } = useAuth();
+	return (
+		<ErrorBoundary>
+			<AppShell nav={ADMIN_NAV_ITEMS} user={user ?? {}} onSignOut={() => void signOut()} />
+		</ErrorBoundary>
+	);
+}
+// @feature:end
+
+export const router = createBrowserRouter([
+	// @feature:start marketing
+	// The public marketing site. It owns `/`, which is the whole reason the
+	// authenticated app is mounted under a base path — see src/lib/paths.ts.
+	{
+		element: (
+			<ErrorBoundary>
+				<MarketingLayout />
+			</ErrorBoundary>
+		),
+		children: [{ index: true, element: lazyRoute(<LandingRoute />) }]
+	},
+	// @feature:end
+	// Legal pages ship whether or not the marketing site does: the signup consent
+	// gate links to them, so they have to resolve either way.
+	{
+		element: (
+			<ErrorBoundary>
+				<MarketingLayout />
+			</ErrorBoundary>
+		),
+		children: [
+			{ path: 'terms', element: lazyRoute(<TermsRoute />) },
+			{ path: 'privacy', element: lazyRoute(<PrivacyRoute />) }
+		]
+	},
+	// @feature:start auth-screens
+	// Public, and deliberately flat: these paths are baked into verification and
+	// password-reset emails that are already in people's inboxes, so moving one
+	// breaks links that have already been sent.
+	{ path: '/login', element: lazyRoute(<LoginRoute />) },
+	{ path: '/signup', element: lazyRoute(<SignupRoute />) },
+	{ path: '/forgot-password', element: lazyRoute(<ForgotPasswordRoute />) },
+	{ path: '/reset-password', element: lazyRoute(<ResetPasswordRoute />) },
+	{ path: '/verify-email', element: lazyRoute(<VerifyEmailRoute />) },
+	{ path: '/verified', element: lazyRoute(<VerifiedRoute />) },
+	// @feature:end
+	{
+		// `/app` with the marketing site, `/` without it. Children stay relative so
+		// they follow it either way.
+		path: appPath(),
+		// `fallback` is required and must not be blank: the session round trip takes
+		// most of a second on a cold load, and rendering nothing for that long reads
+		// as a broken app.
+		element: (
+			<ProtectedRoute fallback={<AppShellSkeleton />}>
+				<Shell />
+			</ProtectedRoute>
+		),
+		children: [
+			{ index: true, element: <HomeRoute /> },
+			{ path: 'settings', element: lazyRoute(<SettingsRoute />) }
+		]
+	},
+	// @feature:start admin
+	{
+		path: ADMIN_BASE,
+		// The role gate is UI, not security: it decides what to render from the
+		// session the browser holds. Every endpoint behind it enforces the same
+		// role server-side, or the console is an honour system.
+		element: (
+			<RoleRoute allow={['admin', 'superuser']} fallback={<AppShellSkeleton />} forbidden={<Forbidden />}>
+				<AdminShell />
+			</RoleRoute>
+		),
+		children: [{ index: true, element: lazyRoute(<AdminHomeRoute />) }]
+	},
+	// @feature:end
+	{ path: '*', element: <NotFound /> }
+]);

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

@@ -0,0 +1,20 @@
+import { makeStore } from '@/shared/api';
+import { authReducer } from '@/shared/auth';
+import { useDispatch, useSelector } from 'react-redux';
+
+/**
+ * The one store. `makeStore` wires the shared RTK Query `baseApi`; slices are
+ * added here. Feature endpoint slices do *not* register themselves — they extend
+ * `baseApi` via `injectEndpoints`, which needs no change in this file.
+ */
+export const store = makeStore({
+	reducer: {
+		auth: authReducer
+	}
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+
+export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
+export const useAppSelector = useSelector.withTypes<RootState>();

package/templates/react-app/files/src/features/auth/components/auth-card.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/shared/ui';
+
+type AuthCardProps = {
+	title: string;
+	description?: ReactNode;
+	children: ReactNode;
+	footer?: ReactNode;
+};
+
+/** Standard auth surface: white 24px card, 900-weight heading, optional footer. */
+export function AuthCard({ title, description, children, footer }: AuthCardProps) {
+	return (
+		<Card>
+			<CardHeader>
+				<CardTitle className="font-black">{title}</CardTitle>
+				{description ? <CardDescription className="text-body">{description}</CardDescription> : null}
+			</CardHeader>
+			<CardContent>{children}</CardContent>
+			{footer ? <p className="text-center text-sm text-body">{footer}</p> : null}
+		</Card>
+	);
+}

package/templates/react-app/files/src/features/auth/components/checkbox-field.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+import { useField } from 'formik';
+import { Checkbox, FormError } from '@/shared/ui';
+
+/**
+ * Formik-bound checkbox with the design's inline label treatment.
+ *
+ * `label` is a node, not a string, because the signup consent needs links to
+ * Terms and Privacy inside it. Clicking one does not toggle the box: HTML
+ * defines a label's activation behaviour as doing nothing for events targeted
+ * at interactive descendants.
+ *
+ * `items-start` rather than the design's `center`: the design only has this on
+ * the single-line "Remember me", and consent copy wraps to two or three lines on
+ * a phone — centring would then float the box against the middle of the block.
+ * `mt-0.5` puts it on the first line's optical centre, so the single-line case
+ * looks unchanged.
+ */
+export function CheckboxField({ name, label }: { name: string; label: ReactNode }) {
+	const [field, meta] = useField({ name, type: 'checkbox' });
+	const showError = meta.touched && Boolean(meta.error);
+
+	return (
+		<div className="flex flex-col gap-1.5">
+			<label className="flex cursor-pointer items-start gap-2.5">
+				<Checkbox {...field} checked={field.value} aria-invalid={showError || undefined} className="mt-0.5" />
+				<span className="text-sm text-body">{label}</span>
+			</label>
+			{showError ? <FormError>{meta.error}</FormError> : null}
+		</div>
+	);
+}

package/templates/react-app/files/src/features/auth/components/google-button.tsx

@@ -0,0 +1,41 @@
+import { Button } from '@/shared/ui';
+
+function GoogleIcon() {
+	return (
+		<svg width="16" height="16" viewBox="0 0 24 24" aria-hidden="true">
+			<path
+				fill="#4285F4"
+				d="M23.5 12.3c0-.9-.1-1.5-.3-2.2H12v4.1h6.5c-.1 1.1-.8 2.7-2.4 3.8l3.7 2.9c2.3-2.1 3.7-5.1 3.7-8.6z"
+			/>
+			<path
+				fill="#34A853"
+				d="M12 24c3.2 0 6-1.1 7.9-2.9l-3.7-2.9c-1 .7-2.4 1.2-4.2 1.2-3.2 0-6-2.1-6.9-5.1L1.2 17.2C3.2 21.2 7.3 24 12 24z"
+			/>
+			<path
+				fill="#FBBC05"
+				d="M5.1 14.3c-.2-.7-.4-1.5-.4-2.3s.2-1.6.4-2.3L1.2 6.8C.4 8.4 0 10.1 0 12s.4 3.6 1.2 5.2l3.9-2.9z"
+			/>
+			<path
+				fill="#EA4335"
+				d="M12 4.6c1.8 0 3 .8 3.7 1.4l3.3-3.2C17 1 14.2 0 12 0 7.3 0 3.2 2.8 1.2 6.8l3.9 2.9c1-3 3.7-5.1 6.9-5.1z"
+			/>
+		</svg>
+	);
+}
+
+export function GoogleButton({
+	onClick,
+	disabled,
+	label = 'Continue with Google'
+}: {
+	onClick: () => void;
+	disabled?: boolean;
+	label?: string;
+}) {
+	return (
+		<Button type="button" variant="outline" className="w-full" onClick={onClick} disabled={disabled}>
+			<GoogleIcon />
+			{label}
+		</Button>
+	);
+}

package/templates/react-app/files/src/features/auth/components/or-divider.tsx

@@ -0,0 +1,9 @@
+export function OrDivider({ label = 'or continue with' }: { label?: string }) {
+	return (
+		<div className="flex items-center gap-3">
+			<span className="h-px flex-1 bg-border" />
+			<span className="text-xs font-medium text-mute">{label}</span>
+			<span className="h-px flex-1 bg-border" />
+		</div>
+	);
+}

package/templates/react-app/files/src/features/auth/components/password-field.tsx

@@ -0,0 +1,70 @@
+import { type ReactNode, useState } from 'react';
+import { useField } from 'formik';
+import { FormError, Input, Label, cn } from '@/shared/ui';
+import { scorePassword } from '../lib/password-strength';
+
+function StrengthMeter({ score }: { score: number }) {
+	const activeColor = ['bg-border', 'bg-negative', 'bg-warning', 'bg-positive'][score];
+	return (
+		<div className="mt-1 flex gap-1" aria-hidden="true">
+			{[1, 2, 3].map((bar) => (
+				<span key={bar} className={cn('h-1 flex-1 rounded-full', bar <= score ? activeColor : 'bg-border')} />
+			))}
+		</div>
+	);
+}
+
+type PasswordFieldProps = {
+	name: string;
+	label?: string;
+	placeholder?: string;
+	autoComplete?: string;
+	showStrength?: boolean;
+	/** Replaces the show/hide toggle in the label row (e.g. a "Forgot password?" link). */
+	action?: ReactNode;
+};
+
+export function PasswordField({
+	name,
+	label = 'Password',
+	placeholder,
+	autoComplete = 'current-password',
+	showStrength = false,
+	action
+}: PasswordFieldProps) {
+	const [field, meta] = useField(name);
+	const [visible, setVisible] = useState(false);
+	const showError = meta.touched && Boolean(meta.error);
+	const strength = showStrength ? scorePassword((field.value as string) ?? '') : null;
+
+	return (
+		<div className="flex flex-col gap-1.5">
+			<div className="flex items-center justify-between">
+				<Label htmlFor={name}>{label}</Label>
+				{action ?? (
+					<button
+						type="button"
+						onClick={() => setVisible((value) => !value)}
+						className="text-xs font-semibold text-ink-deep"
+					>
+						{visible ? 'Hide' : 'Show'}
+					</button>
+				)}
+			</div>
+			<Input
+				id={name}
+				type={visible ? 'text' : 'password'}
+				placeholder={placeholder}
+				autoComplete={autoComplete}
+				aria-invalid={showError || undefined}
+				{...field}
+			/>
+			{strength ? <StrengthMeter score={strength.score} /> : null}
+			{showError ? (
+				<FormError>{meta.error}</FormError>
+			) : strength ? (
+				<p className="text-xs text-mute">{strength.label}</p>
+			) : null}
+		</div>
+	);
+}

package/templates/react-app/files/src/features/auth/components/submit-button.tsx

@@ -0,0 +1,16 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { Button, Spinner, cn } from '@/shared/ui';
+
+type SubmitButtonProps = ComponentProps<typeof Button> & {
+	loading?: boolean;
+	children: ReactNode;
+};
+
+export function SubmitButton({ loading, children, className, disabled, ...props }: SubmitButtonProps) {
+	return (
+		<Button type="submit" className={cn('w-full', className)} disabled={disabled || loading} {...props}>
+			{loading ? <Spinner /> : null}
+			{children}
+		</Button>
+	);
+}

package/templates/react-app/files/src/features/auth/lib/auth-actions.ts

@@ -0,0 +1,68 @@
+import { getAuthClient } from '@/shared/auth';
+
+type ActionResult = { error?: string };
+
+function messageOf(error: { message?: string } | null | undefined, fallback: string): string {
+	return error?.message ?? fallback;
+}
+
+export async function loginWithEmail(input: {
+	email: string;
+	password: string;
+	remember?: boolean;
+}): Promise<ActionResult> {
+	const { error } = await getAuthClient().signIn.email({
+		email: input.email,
+		password: input.password,
+		rememberMe: input.remember ?? true
+	});
+	return error ? { error: messageOf(error, 'Could not log in. Check your details and try again.') } : {};
+}
+
+export async function signupWithEmail(input: {
+	name: string;
+	email: string;
+	password: string;
+	callbackURL?: string;
+}): Promise<ActionResult> {
+	const { error } = await getAuthClient().signUp.email({
+		name: input.name,
+		email: input.email,
+		password: input.password,
+		callbackURL: input.callbackURL
+	});
+	return error ? { error: messageOf(error, 'Could not create your account.') } : {};
+}
+
+export async function signInWithGoogle(options: {
+	/** Where existing users land after sign-in (usually the client app). */
+	callbackURL?: string;
+	/** Where first-time users land (the onboarding wizard). */
+	newUserCallbackURL?: string;
+}): Promise<void> {
+	await getAuthClient().signIn.social({
+		provider: 'google',
+		callbackURL: options.callbackURL,
+		newUserCallbackURL: options.newUserCallbackURL
+	});
+}
+
+export async function requestPasswordReset(input: { email: string; redirectTo?: string }): Promise<ActionResult> {
+	const { error } = await getAuthClient().requestPasswordReset({ email: input.email, redirectTo: input.redirectTo });
+	return error ? { error: messageOf(error, 'Could not send the reset link.') } : {};
+}
+
+export async function resetPasswordWithToken(input: { newPassword: string; token: string }): Promise<ActionResult> {
+	const { error } = await getAuthClient().resetPassword({ newPassword: input.newPassword, token: input.token });
+	return error ? { error: messageOf(error, 'Could not reset your password. The link may have expired.') } : {};
+}
+
+export async function resendVerification(input: { email: string; callbackURL?: string }): Promise<ActionResult> {
+	const { error } = await getAuthClient().sendVerificationEmail({ email: input.email, callbackURL: input.callbackURL });
+	return error ? { error: messageOf(error, 'Could not resend the email.') } : {};
+}
+
+export async function verifyEmailToken(token: string): Promise<ActionResult> {
+	const { error } = await getAuthClient().verifyEmail({ query: { token } });
+	return error ? { error: messageOf(error, 'Could not verify your email. The link may have expired.') } : {};
+}

package/templates/react-app/files/src/features/auth/lib/password-strength.ts

@@ -0,0 +1,20 @@
+export type PasswordStrength = {
+	/** 0 (empty/too short) … 3 (strong) */
+	score: 0 | 1 | 2 | 3;
+	label: string;
+};
+
+/** Lightweight strength heuristic driving the 3-bar meter on the signup screen. */
+export function scorePassword(password: string): PasswordStrength {
+	if (!password) {
+		return { score: 0, label: 'Use 8+ characters with a mix of letters and numbers.' };
+	}
+	let points = 0;
+	if (password.length >= 8) points += 1;
+	if (/[a-z]/.test(password) && /[A-Z]/.test(password)) points += 1;
+	if (/\d/.test(password) || /[^A-Za-z0-9]/.test(password)) points += 1;
+
+	const score = Math.min(points, 3) as 0 | 1 | 2 | 3;
+	const labels = ['Too short', 'Weak — add more variety', 'Getting there', 'Strong password'];
+	return { score, label: labels[score] };
+}

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

@@ -0,0 +1,6 @@
+/** Append the current `redirect` param to an in-app path (threads it across screens). */
+export function withRedirect(path: string, redirect: string | null): string {
+	if (!redirect) return path;
+	const separator = path.includes('?') ? '&' : '?';
+	return `${path}${separator}redirect=${encodeURIComponent(redirect)}`;
+}

package/templates/react-app/files/src/features/auth/lib/schemas.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+
+export const loginSchema = z.object({
+	email: z.string().min(1, 'Email is required').email('Enter a valid email'),
+	password: z.string().min(1, 'Password is required'),
+	remember: z.boolean().optional()
+});
+export type LoginValues = z.infer<typeof loginSchema>;
+
+export const signupSchema = z.object({
+	name: z.string().min(1, 'Enter your name'),
+	email: z.string().min(1, 'Email is required').email('Enter a valid email'),
+	password: z.string().min(8, 'At least 8 characters'),
+	// Consent is a gate, not a preference, so it is validated rather than merely
+	// displayed. It is stripped before the payload reaches the API — see
+	// `SignupRoute`; nothing on the server takes it.
+	acceptedTerms: z.boolean().refine((accepted) => accepted, {
+		message: 'Please accept the terms to continue'
+	})
+});
+export type SignupValues = z.infer<typeof signupSchema>;
+
+export const forgotSchema = z.object({
+	email: z.string().min(1, 'Email is required').email('Enter a valid email')
+});
+export type ForgotValues = z.infer<typeof forgotSchema>;
+
+export const resetSchema = z
+	.object({
+		password: z.string().min(8, 'At least 8 characters'),
+		confirm: z.string().min(1, 'Confirm your password')
+	})
+	.refine((values) => values.password === values.confirm, {
+		message: "Passwords don't match yet.",
+		path: ['confirm']
+	});
+export type ResetValues = z.infer<typeof resetSchema>;

package/templates/react-app/files/src/features/seo/routes.ts

@@ -0,0 +1,65 @@
+/**
+ * Every indexable route, with the metadata that describes it.
+ *
+ * **This is the single source.** `PageSeo` renders per-route tags from it and
+ * the build emits `sitemap.xml` from it (see `vite.config.ts`), so the sitemap
+ * cannot list a route that does not exist or miss one that does — the classic
+ * way a sitemap rots. Add a route here on the same commit that adds it to
+ * `app/router.tsx`, and remove it the same way; a sitemap advertising a 404
+ * stays invisible until a crawler finds it.
+ *
+ * Kept free of React imports: `vite.config.ts` imports this directly, and the
+ * config is bundled with esbuild.
+ */
+export type SeoRoute = {
+	/** Path as it appears in the router, leading slash, no trailing slash. */
+	path: string;
+	/** Page segment only — `MetaProvider` appends the brand suffix. */
+	title: string;
+	description: string;
+	/** Relative priority for the sitemap; the homepage leads. */
+	priority: string;
+	changefreq: 'daily' | 'weekly' | 'monthly' | 'yearly';
+};
+
+export const SEO_ROUTES: SeoRoute[] = [
+	{
+		path: '/',
+		title: 'Home',
+		description: 'Replace with the description search results should show.',
+		priority: '1.0',
+		changefreq: 'weekly'
+	}
+];
+
+/**
+ * The one origin that may be indexed. Staging and preview builds compare
+ * unequal and are served `noindex`, so a preview deploy cannot outrank
+ * production for its own content.
+ */
+export const PRODUCTION_ORIGIN = 'https://example.com';
+
+export const seoRouteFor = (path: string) => SEO_ROUTES.find((route) => route.path === path);
+
+/**
+ * Absolute URL for a path — canonical, `og:url` and sitemap entries all need one.
+ *
+ * `origin` is passed in rather than read here so this file stays free of
+ * `import.meta.env`: it is imported by `vite.config.ts`, where `import.meta.env`
+ * does not exist. App code gets the origin from its env, the build from its own
+ * `loadEnv`.
+ */
+export const absoluteUrl = (path: string, origin: string) => (path === '/' ? `${origin}/` : `${origin}${path}`);
+
+/** Strip a trailing slash so joins don't produce `//about`. */
+export const normalizeOrigin = (origin: string) => origin.replace(/\/$/, '');
+
+/*
+ * Not included here: **prerendering**. `vite build` emits a single SPA shell,
+ * so a crawler that does not execute JavaScript sees an empty `#root` for every
+ * route. `robots.txt` and `sitemap.xml` are emitted from this table at build
+ * time (see `vite.config.ts`), which is the half that matters for discovery —
+ * but if these pages need to rank on their content, add a post-build pass that
+ * renders each `SEO_ROUTES` entry to `dist/<path>/index.html`. Drive it from
+ * this table, not a second list, or the sitemap and the prerendered set drift.
+ */

package/templates/react-app/files/src/lib/env.ts

@@ -0,0 +1,28 @@
+const env = import.meta.env;
+
+/** Backend base URL. Better Auth lives at `${API_URL}/auth`. */
+export const API_URL = env.VITE_APP_API_URL as string;
+
+/**
+ * This app's own origin, read from the browser rather than from a build-time
+ * variable.
+ *
+ * One deployment means one origin, so there is nothing a `VITE_APP_URL` could
+ * add here and plenty it could get wrong: Vite inlines env at build time, so a
+ * stale value baked into an image sends every verification link to the previous
+ * environment — and that failure is invisible until a user clicks one.
+ *
+ * The only place an absolute URL is genuinely needed is a link that lands in an
+ * email, and by then the browser has already told us where we are.
+ */
+export const APP_ORIGIN = window.location.origin;
+
+// @feature:start marketing
+/**
+ * Canonical public origin, for SEO tags only — the one origin that may be
+ * indexed. Unset (previews, staging) means "not production", and the build
+ * emits `noindex` plus a disallowing robots.txt rather than letting a preview
+ * deploy outrank production for its own content. See `vite.config.ts`.
+ */
+export const SITE_URL = (env.VITE_APP_SITE_URL as string | undefined) ?? '';
+// @feature:end

package/templates/react-app/files/src/lib/paths.ts

@@ -0,0 +1,58 @@
+/**
+ * Where things live in the URL space.
+ *
+ * One deployment serves the marketing pages, the auth screens and the
+ * authenticated app, so unlike a multi-app build these cannot each own `/` on
+ * their own host — the split has to happen in the path, and it has to happen in
+ * one place or the router, the nav and the post-login redirect will disagree.
+ */
+
+/**
+ * The mount point of the authenticated app, as a path split on `/`.
+ *
+ * A list rather than two competing `const` declarations because a generated
+ * project has to compile in *every* feature combination, and only one of two
+ * declarations of the same name can survive the strip. Drop `marketing` and only
+ * the leading empty segment is left, putting the app back at the root.
+ *
+ * The `''` is not filler: an absolute path's first segment *is* empty —
+ * `'/app'.split('/')` is `['', 'app']`. It also keeps this array non-empty in
+ * every build, which matters because a literal that strips down to `[\n]` is no
+ * longer formatted the way Prettier wants it, and `format:check` runs in CI.
+ */
+const BASE_SEGMENTS: string[] = [
+	'', // the leading slash
+	'app' // @feature marketing
+];
+
+/** `/app` when the marketing site owns `/`; otherwise `''`. */
+export const APP_BASE = BASE_SEGMENTS.join('/');
+
+/**
+ * Absolute path to a route inside the authenticated app.
+ *
+ *   appPath()            ->  '/app'  (or '/')
+ *   appPath('settings')  ->  '/app/settings'  (or '/settings')
+ *
+ * Use it for anything that has to name a route from outside the router — nav
+ * items, redirect targets, links in emails. Routes *inside* the app shell can
+ * keep using relative paths and need none of this.
+ */
+export const appPath = (path = '') => `${APP_BASE}/${path}`.replace(/\/+/g, '/').replace(/(.)\/$/, '$1');
+
+/**
+ * Legal pages ship whether or not the marketing site does: the signup consent
+ * gate links to them, and a consent checkbox pointing at a 404 is worse than no
+ * checkbox at all.
+ */
+export const TERMS_PATH = '/terms';
+export const PRIVACY_PATH = '/privacy';
+
+// @feature:start admin
+/**
+ * The admin console. A separate branch of the router rather than a route inside
+ * the app shell, so the role check wraps the whole section instead of being
+ * repeated per page — and so an admin-only nav never renders for anyone else.
+ */
+export const ADMIN_BASE = '/admin';
+// @feature:end

package/templates/react-app/files/src/main.tsx

@@ -0,0 +1,19 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from 'react-router';
+import '@/shared/ui/styles/globals.css';
+import { Providers } from './app/providers';
+import { router } from './app/router';
+
+// If the first screen needs data immediately, kick its query off here rather
+// than in a component effect: by this point every module above has finished
+// evaluating and `providers` has already called `configureApi` at module scope,
+// so the fetch races the session check instead of queueing behind it.
+
+createRoot(document.getElementById('root')!).render(
+	<StrictMode>
+		<Providers>
+			<RouterProvider router={router} />
+		</Providers>
+	</StrictMode>
+);