npm - @aurostack/stacks - Versions diffs - 0.1.0 - Mend

@aurostack/stacks 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (601) hide show

package/templates/react-app/files/src/shared/ui/meta/page-meta.tsx ADDED Viewed

@@ -0,0 +1,69 @@
+import { formatTitle } from './meta-context';
+import { useMetaConfig } from './use-meta-config';
+export type PageMetaProps = {
+	/**
+	 * Page segment, not the whole title — the app's suffix is appended by
+	 * `MetaProvider`. Pass `exact` to opt out.
+	 */
+	title?: string;
+	/** Use `title` verbatim, without the app suffix. */
+	exact?: boolean;
+	/** Overrides the base description from `index.html` while mounted. */
+	description?: string;
+	/** e.g. `noindex, nofollow` for the private apps. */
+	robots?: string;
+	/** Absolute URL. */
+	canonical?: string;
+};
+/**
+ * Per-route document metadata. Render it anywhere inside a route — React 19
+ * hoists `<title>`, `<meta>` and `<link>` into `<head>` natively, so there is no
+ * head-management dependency and no effect involved.
+ *
+ * **Being effect-free is the point**: it is what makes the tags appear in
+ * server-rendered output, which an effect-based `document.title` hook can never
+ * do. Do not "optimise" this into a `useEffect`.
+ *
+ * Omit a field to inherit it: a route with no `description` keeps the base one
+ * from `index.html`, and React removes the tag again on unmount.
+ *
+ * ## Nesting
+ *
+ * Client-side, the innermost render wins for free — React claims the first
+ * existing `<title>` (so the static one from `index.html` is overwritten), and
+ * for any subsequent one it does `head.insertBefore(new, existing)`. Later
+ * renders therefore land *earlier* in `<head>`, and `document.title` is defined
+ * as the first `<title>` in tree order.
+ *
+ * ## Server-side rendering — read before wiring a prerender
+ *
+ * Order inverts on the server. `react-dom/server` emits tags in render order,
+ * so a document renders as:
+ *
+ * ```html
+ * <head><title>base from index.html</title><title>Route · Brand</title></head>
+ * ```
+ *
+ * and the **base** title wins, because it comes first. React does not
+ * deduplicate `<title>` or `<meta>` (only stylesheets get resource dedupe), so
+ * a prerender step MUST post-process the emitted HTML: keep the **last**
+ * `<title>` and the **last** `<meta name="description">`, dropping earlier
+ * duplicates. Without that, every prerendered page ships the base title and
+ * hydration silently corrects it — invisible in a browser, wrong for crawlers.
+ * Tracked on MAI-88.
+ */
+export function PageMeta({ title, exact, description, robots, canonical }: PageMetaProps) {
+	const config = useMetaConfig();
+	const resolved = title === undefined ? undefined : exact ? title : formatTitle(title, config);
+	return (
+		<>
+			{resolved === undefined ? null : <title>{resolved}</title>}
+			{description === undefined ? null : <meta name="description" content={description} />}
+			{robots === undefined ? null : <meta name="robots" content={robots} />}
+			{canonical === undefined ? null : <link rel="canonical" href={canonical} />}
+		</>
+	);
+}

package/templates/react-app/files/src/shared/ui/meta/use-meta-config.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { MetaContext } from './meta-context';
+/**
+ * The app's title template. Falls back to the un-suffixed default rather than
+ * throwing, so a component rendering `PageMeta` outside a `MetaProvider` still
+ * produces a usable title instead of blanking the tab.
+ */
+export function useMetaConfig() {
+	return useContext(MetaContext);
+}

package/templates/react-app/files/src/shared/ui/styles/globals.css ADDED Viewed

@@ -0,0 +1,285 @@
+/**
+ * @/shared/ui global stylesheet — the single CSS entry every app imports:
+ *   import '@/shared/ui/styles/globals.css';
+ *
+ * Layers: self-hosted font -> Tailwind v4 -> brand tokens (theme.css) ->
+ * shadcn semantic tokens (light/dark) mapped for utilities. Design language =
+ * Wise: flat surfaces, no shadows, 1px ink hairlines, 24px radii, green CTA only.
+ */
+@import 'tailwindcss';
+@import './theme.css';
+/**
+ * Inter, self-hosted. This was a `@import url(fonts.googleapis.com/...)` on the
+ * first line of this file, which is the slowest possible way to load a font: a
+ * CSS @import is only discovered after this stylesheet has been parsed, so it
+ * cost three SERIALIZED round trips across two extra origins (googleapis ->
+ * gstatic -> woff2) before text could paint. Worse for the installed PWA — the
+ * service worker cannot precache a cross-origin URL, so fonts hit the network on
+ * every cold start and failed outright offline, despite the shell being cached.
+ *
+ * One variable file replaces the six static weights that were being requested.
+ * 47 KB covers the whole 100-900 axis, and all six weights are in use
+ * (400/500/600/700/800/900). Latin only, and upright only — there is no italic
+ * anywhere in the codebase. Add `wght-italic` here if that ever changes.
+ *
+ * Declared by hand rather than `@import '@fontsource-variable/inter/wght.css'`
+ * because that pulls in all seven subsets (cyrillic, greek, vietnamese, ...).
+ * Vite would emit every one into dist, and `woff2` is in the PWA precache glob.
+ *
+ * Named `Inter` so the `--font-sans` / `--font-display` stacks need no change; an
+ * @font-face shadows a same-named system font, so this file always wins.
+ */
+@font-face {
+	font-family: 'Inter';
+	font-style: normal;
+	font-weight: 100 900;
+	font-display: swap;
+	src: url('@fontsource-variable/inter/files/inter-latin-wght-normal.woff2') format('woff2');
+	unicode-range:
+		U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC,
+		U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+/* Scan workspace component packages for utility classes (they live under
+   node_modules in consumers, which Tailwind skips by default). The consuming
+   app's own src is auto-detected by Tailwind. Add a line here for any new
+   component package. */
+@source '../**/*.{ts,tsx}';
+@source '../../../layouts/src/**/*.{ts,tsx}';
+@custom-variant dark (&:is(.dark *));
+:root {
+	--radius: 0.75rem; /* 12px base (inputs); cards/buttons use explicit 24px */
+	--background: #eceee9;
+	--foreground: #0e0f0c;
+	--card: #ffffff;
+	--card-foreground: #0e0f0c;
+	--popover: #ffffff;
+	--popover-foreground: #0e0f0c;
+	--primary: #9fe870;
+	--primary-foreground: #0e0f0c;
+	--secondary: #f2f4ef;
+	--secondary-foreground: #0e0f0c;
+	--muted: #f2f4ef;
+	--muted-foreground: #7d7f7a;
+	--accent: #e2f6d5;
+	--accent-foreground: #163300;
+	--destructive: #c0242b;
+	--destructive-foreground: #ffffff;
+	--border: rgba(14, 15, 12, 0.09);
+	--input: rgba(14, 15, 12, 0.28);
+	--ring: rgba(159, 232, 112, 0.55);
+	--brand-panel: #e8ebe6;
+	/*
+	 * Secondary text + link colours. These start life as fixed brand tokens in
+	 * theme.css, which means they never changed with the theme — #454745
+	 * body text sits at ~2:1 on a dark card, and the #163300 link is effectively
+	 * invisible. Redeclared here (light values identical to the brand ones, so
+	 * light mode is unchanged) and overridden in .dark below.
+	 * Dark values are the design's own palette from `Client App.dc.html`.
+	 */
+	--body: #454745;
+	--mute: #868685;
+	--link: #163300;
+	/*
+	 * Status colours, same problem: the brand hexes are tuned for a white card and
+	 * are muddy on a dark one. Light values match the brand tokens exactly; the
+	 * dark ones are the design's own `--gain`/`--loss` (plus a lifted warning).
+	 * These feed both the `text-*` and the translucent `bg-*` tint utilities.
+	 */
+	--positive: #2ead4b;
+	--negative: #d03238;
+	--warning: #ffd11a;
+	/*
+	 * Foreground for the `bg-warning/20` pill. The fixed brand `--color-warning-deep`
+	 * (#b86700) was being used here, which is the classic pairing bug: the tint
+	 * follows the theme, the text does not. On a dark card it measured 2.43:1 —
+	 * unreadable. These are the design's own warning-pill foregrounds
+	 * (`--pill-warn-fg`), and they measure 8.8–10:1 light / 6.5–8.6:1 dark.
+	 */
+	--warning-content: #4a3b1c;
+	/*
+	 * Active-tab underline (admin console tab bars). The design uses a literal
+	 * #579b2e in both themes, which measures 2.93:1 on the light page background —
+	 * under the 3:1 WCAG 1.4.11 needs for a non-text indicator. Darkened along the
+	 * same hue (97.4°) to 3.55:1; the dark value is the same hue lifted for an ink
+	 * canvas. Deliberately NOT `--primary`: Wise Green is the CTA accent, and an
+	 * active tab is a state, not a call to action.
+	 */
+	--tab-active: #4e8b29;
+	/*
+	 * Categorical chart palette — for encoding *identity* (which holding is which),
+	 * never magnitude. Six slots because a donut stops being readable past ~6
+	 * slices, and because the hue budget is genuinely that small: excluding the
+	 * gain (~144°) and loss (~30°) hue neighbourhoods removes ~100° of the wheel,
+	 * and what's left can't hold 8 mutually distinguishable hues that also stay
+	 * clear of those two colours in both themes. Verified min pairwise ΔE 40 (light)
+	 * / 36 (dark) against Tableau10's 30 as the benchmark, every slot ≥32 ΔE from
+	 * `--positive`/`--negative`/`--primary` so no slice reads as a gain, a loss or
+	 * a CTA, and hue drift ≤3° between themes so a slice keeps its identity on
+	 * toggle. Lightness is deliberately held in a narrow band per theme so no slice
+	 * outweighs another.
+	 *
+	 * `--chart-other` is the "and the rest" bucket: neutral on purpose, so it
+	 * recedes instead of reading as another holding. Adding a 7th hue here will
+	 * break the guarantees above — collapse into Other instead.
+	 */
+	/*
+	 * Single magnitude hue for bar charts. Bar rows are ONE series — identity comes
+	 * from the row label, so every bar is the same colour; colouring them by value
+	 * would double-encode the length. Separate from `--chart-1` despite sharing the
+	 * light value: that slot is tuned for small donut slices, and its dark value
+	 * (#55bca4, OKLCH L 0.727) sits outside the 0.48–0.67 lightness band a dark-mode
+	 * bar fill needs. Both values pass the dataviz validator on all five checks.
+	 */
+	--chart-bar: #009e84;
+	--chart-1: #009e84;
+	--chart-2: #0096c7;
+	--chart-3: #6767c7;
+	--chart-4: #ac7e9a;
+	--chart-5: #c27c2d;
+	--chart-6: #737548;
+	--chart-other: #8f958e;
+	/*
+	 * Modal / drawer backdrop. Needs to be darker on a dark page to still read as
+	 * a separation layer — the design specifies exactly this pair.
+	 */
+	--scrim: rgba(14, 15, 12, 0.45);
+}
+.dark {
+	--background: #0e0f0c;
+	--foreground: #f4f6f1;
+	--card: #191b16;
+	--card-foreground: #f4f6f1;
+	--popover: #191b16;
+	--popover-foreground: #f4f6f1;
+	--primary: #9fe870;
+	--primary-foreground: #0e0f0c;
+	--secondary: #23261f;
+	--secondary-foreground: #f4f6f1;
+	--muted: #23261f;
+	--muted-foreground: #8b8d88;
+	--accent: rgba(159, 232, 112, 0.15);
+	--accent-foreground: #9fe870;
+	--destructive: #ff8085;
+	--destructive-foreground: #0e0f0c;
+	--border: rgba(232, 235, 230, 0.11);
+	--input: rgba(232, 235, 230, 0.3);
+	--ring: rgba(159, 232, 112, 0.4);
+	--brand-panel: #14160f;
+	--body: #c4c7c0;
+	--mute: #8b8d88;
+	/* Links become the brand green on dark — ink-deep is unreadable there. */
+	--link: #9fe870;
+	--positive: #6fdd8b;
+	--negative: #ff8085;
+	--warning: #ffd95e;
+	/* On a dark tint the deep olive inverts to the warning colour itself. */
+	--warning-content: #ffd95e;
+	/* Same 97.4° hue as light, lifted for the ink canvas (9.1:1 on --background). */
+	--tab-active: #74c742;
+	/* Same hue as light, stepped into the dark band (see the light block for why). */
+	--chart-bar: #35a68d;
+	/* Same hues as light, lifted for the dark card (see the light block for why). */
+	--chart-1: #55bca4;
+	--chart-2: #43c8ff;
+	--chart-3: #a7a1fc;
+	--chart-4: #eab8d6;
+	--chart-5: #e29d56;
+	--chart-6: #c9c998;
+	--chart-other: #7f857e;
+	--scrim: rgba(0, 0, 0, 0.6);
+}
+@theme inline {
+	--color-background: var(--background);
+	--color-foreground: var(--foreground);
+	--color-card: var(--card);
+	--color-card-foreground: var(--card-foreground);
+	--color-popover: var(--popover);
+	--color-popover-foreground: var(--popover-foreground);
+	--color-primary: var(--primary);
+	--color-primary-foreground: var(--primary-foreground);
+	--color-secondary: var(--secondary);
+	--color-secondary-foreground: var(--secondary-foreground);
+	--color-muted: var(--muted);
+	--color-muted-foreground: var(--muted-foreground);
+	--color-accent: var(--accent);
+	--color-accent-foreground: var(--accent-foreground);
+	--color-destructive: var(--destructive);
+	--color-destructive-foreground: var(--destructive-foreground);
+	--color-border: var(--border);
+	--color-input: var(--input);
+	--color-ring: var(--ring);
+	--color-brand-panel: var(--brand-panel);
+	/*
+	 * Re-point the secondary-text utilities (`text-body`, `text-mute`,
+	 * `text-ink-deep`) at the theme-aware vars above. theme.css defines these
+	 * as fixed brand hexes, and this layer wins — so `text-body` finally responds
+	 * to the theme instead of staying #454745 on a dark card.
+	 */
+	--color-body: var(--body);
+	--color-mute: var(--mute);
+	--color-ink-deep: var(--link);
+	--color-positive: var(--positive);
+	--color-negative: var(--negative);
+	--color-warning: var(--warning);
+	/* Pair `bg-warning/20` with `text-warning-content`, never `text-warning-deep`. */
+	--color-warning-content: var(--warning-content);
+	/*
+	 * `bg-chart-bar` for CSS bar fills. The `--chart-1..6` donut slots are
+	 * deliberately NOT mapped to utilities — the donut reads them through
+	 * `readVar()` in JS — so this is the only chart colour with a class.
+	 */
+	--color-chart-bar: var(--chart-bar);
+	/* Enables `border-tab-active` on the selected tab's 2px underline. */
+	--color-tab-active: var(--tab-active);
+	/* Enables `bg-scrim` — already carries its own alpha, so no /45 modifier. */
+	--color-scrim: var(--scrim);
+}
+@layer base {
+	* {
+		border-color: var(--color-border);
+	}
+	/*
+	 * Tells the browser which palette its own UI should use — native scrollbars,
+	 * form controls, autofill backgrounds and the text caret. Without it these
+	 * stay light-styled over a dark page. The theme provider also sets this
+	 * inline on <html> so it flips instantly with the class.
+	 */
+	:root {
+		color-scheme: light;
+	}
+	.dark {
+		color-scheme: dark;
+	}
+	body {
+		background-color: var(--color-background);
+		color: var(--color-foreground);
+		font-family: var(--font-sans);
+		-webkit-font-smoothing: antialiased;
+		text-rendering: optimizeLegibility;
+	}
+}

package/templates/react-app/files/src/shared/ui/styles/theme.css ADDED Viewed

@@ -0,0 +1,48 @@
+/**
+ * Acme Corp — shared Tailwind v4 brand tokens (Wise-derived design system).
+ * Source of truth: Claude Design "Acme Corp Design System" (colors_and_type.css).
+ *
+ * Consume in an app's main CSS entry (via @/shared/ui/styles/globals.css):
+ *   @import 'tailwindcss';
+ *   @import './theme.css';
+ *
+ * These are the BRAND tokens (palette shades, ink, semantic, fonts). The shadcn
+ * semantic layer (--background/--foreground/--primary/...) is layered on top by
+ * @/shared/ui/styles/globals.css, which owns light/dark theming.
+ *
+ * Brand rule: Wise Green (#9fe870) is the CTA accent ONLY — never a success color.
+ */
+@theme {
+	/* Brand green shades (primary itself is owned by the shadcn layer) */
+	--color-primary-active: #cdffad;
+	--color-primary-neutral: #c5edab;
+	--color-primary-pale: #e2f6d5;
+	--color-on-primary: #0e0f0c;
+	/* Surfaces & ink */
+	--color-sage: #e8ebe6;
+	--color-ink: #0e0f0c;
+	--color-ink-deep: #163300;
+	--color-body: #454745;
+	--color-mute: #868685;
+	/* Semantic — status only, never the brand green */
+	--color-positive: #2ead4b;
+	--color-positive-deep: #054d28;
+	--color-warning: #ffd11a;
+	--color-warning-deep: #b86700;
+	--color-negative: #d03238;
+	--color-negative-deep: #a72027;
+	/* Illustrative accents (inside illustrations only, never UI fills) */
+	--color-accent-orange: #ffc091;
+	--color-accent-cyan: #38c8ff;
+	/* Typography — Inter stands in for proprietary Wise Sans */
+	/* 'Manrope' was listed here but never loaded — and sat *after* Inter, so it
+	   could never have been used even if it were. Removed as dead. If the design
+	   really wants Manrope for display type it needs its own @font-face AND to be
+	   ordered ahead of Inter — a deliberate visual change, not a cleanup. */
+	--font-display: 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif;
+	--font-sans: 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif;
+}

package/templates/react-app/files/src/shared/ui/theme/init-script.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import { THEME_COLORS } from './theme-colors';
+/**
+ * Blocking snippet for each app's `index.html`, placed in `<head>` **before**
+ * the stylesheet link.
+ *
+ * Without it the page paints light, then React mounts and flips it to dark —
+ * a visible flash on every load, worst on a slow mobile connection where the
+ * bundle takes seconds to arrive. It duplicates a few lines of `theme-context`
+ * on purpose: it must run before any module loads, so it cannot import them.
+ *
+ * The colours are interpolated from `THEME_COLORS` so this isn't another copy to
+ * keep in sync. `THEME_STORAGE_KEY` still is one — it has to be a literal here.
+ */
+export const themeInitScript = `(function(){try{
+var m=localStorage.getItem('acme-theme');
+var d=m==='dark'||((m===null||m==='system')&&matchMedia('(prefers-color-scheme: dark)').matches);
+var r=document.documentElement;
+r.classList.toggle('dark',d);
+r.style.colorScheme=d?'dark':'light';
+var t=document.querySelector('meta[name="theme-color"]');
+if(t)t.setAttribute('content',d?'${THEME_COLORS.dark}':'${THEME_COLORS.light}');
+}catch(e){}})();`;

package/templates/react-app/files/src/shared/ui/theme/theme-colors.ts ADDED Viewed

@@ -0,0 +1,14 @@
+/**
+ * The page background per theme, as a raw value.
+ *
+ * This module deliberately has **no imports**. Build-time config needs these
+ * values too — `apps/client/vite.config.ts` bakes them into the PWA manifest —
+ * and importing `theme-context` there would pull React into the Vite config.
+ * Keep it dependency-free so both the runtime and the build can read it.
+ *
+ * Must match `--background` in `globals.css` for each theme.
+ */
+export const THEME_COLORS = {
+	light: '#eceee9',
+	dark: '#0e0f0c'
+} as const;

package/templates/react-app/files/src/shared/ui/theme/theme-context.ts ADDED Viewed

@@ -0,0 +1,60 @@
+import { createContext } from 'react';
+import { THEME_COLORS } from './theme-colors';
+/** What the user chose. `system` follows the OS and keeps following it. */
+export type ThemeMode = 'system' | 'light' | 'dark';
+/** What is actually on screen once `system` is resolved. */
+export type ResolvedTheme = 'light' | 'dark';
+export type ThemeContextValue = {
+	mode: ThemeMode;
+	resolved: ResolvedTheme;
+	setMode: (mode: ThemeMode) => void;
+	/** Cycles light → dark → system. */
+	toggle: () => void;
+};
+/**
+ * Shared across every app. Kept in its own module (no components) so the
+ * provider and the hook can live in separate files without tripping
+ * `react-refresh/only-export-components`.
+ */
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+/** localStorage key. Per-origin, so each app remembers its own choice. */
+export const THEME_STORAGE_KEY = 'acme-theme';
+/**
+ * Re-exported so consumers keep importing theme colours from one place. The
+ * values live in `theme-colors.ts`, which has no imports so the Vite config can
+ * read them at build time (see the PWA manifest in `apps/client/vite.config.ts`).
+ */
+export { THEME_COLORS };
+export function isThemeMode(value: unknown): value is ThemeMode {
+	return value === 'system' || value === 'light' || value === 'dark';
+}
+/** Read the stored preference. Safe on the server and in private-mode browsers. */
+export function readStoredMode(): ThemeMode {
+	if (typeof window === 'undefined') return 'system';
+	try {
+		const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
+		return isThemeMode(stored) ? stored : 'system';
+	} catch {
+		return 'system';
+	}
+}
+/**
+ * Apply a resolved theme to the document: the `dark` class that Tailwind's
+ * `@custom-variant dark` keys off, `color-scheme` so native scrollbars, form
+ * controls and autofill follow, and the PWA status-bar colour.
+ */
+export function applyTheme(resolved: ResolvedTheme): void {
+	if (typeof document === 'undefined') return;
+	const root = document.documentElement;
+	root.classList.toggle('dark', resolved === 'dark');
+	root.style.colorScheme = resolved;
+	document.querySelector('meta[name="theme-color"]')?.setAttribute('content', THEME_COLORS[resolved]);
+}

package/templates/react-app/files/src/shared/ui/theme/theme-provider.tsx ADDED Viewed

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import {
+	ThemeContext,
+	THEME_STORAGE_KEY,
+	applyTheme,
+	isThemeMode,
+	readStoredMode,
+	type ResolvedTheme,
+	type ThemeMode
+} from './theme-context';
+const QUERY = '(prefers-color-scheme: dark)';
+function systemTheme(): ResolvedTheme {
+	if (typeof window === 'undefined') return 'light';
+	return window.matchMedia(QUERY).matches ? 'dark' : 'light';
+}
+function resolve(mode: ThemeMode): ResolvedTheme {
+	return mode === 'system' ? systemTheme() : mode;
+}
+/**
+ * Theme provider for every app. Wrap the app root once, above the router.
+ *
+ * The initial class is set by the inline snippet in `index.html` (see
+ * `themeInitScript`) so there is no flash of the wrong theme before React
+ * mounts; this provider then takes over and keeps the DOM in sync.
+ */
+export function ThemeProvider({ children }: { children: ReactNode }) {
+	const [mode, setModeState] = useState<ThemeMode>(readStoredMode);
+	const [resolved, setResolved] = useState<ResolvedTheme>(() => resolve(readStoredMode()));
+	const setMode = useCallback((next: ThemeMode) => {
+		setModeState(next);
+		const nextResolved = resolve(next);
+		setResolved(nextResolved);
+		applyTheme(nextResolved);
+		try {
+			window.localStorage.setItem(THEME_STORAGE_KEY, next);
+		} catch {
+			// Private mode / storage disabled — the theme still applies for this session.
+		}
+	}, []);
+	// Follow the OS while in `system` mode.
+	useEffect(() => {
+		if (mode !== 'system') return;
+		const media = window.matchMedia(QUERY);
+		const sync = () => {
+			const next: ResolvedTheme = media.matches ? 'dark' : 'light';
+			setResolved(next);
+			applyTheme(next);
+		};
+		media.addEventListener('change', sync);
+		// The `change` event alone is not enough for an installed PWA. It can sit
+		// frozen for days, and the OS flipping theme while it is backgrounded — an
+		// automatic sunset switch, typically — delivers no event, so the app resumes
+		// on the stale theme until a full reload. A browser tab hides this because it
+		// gets navigated and discarded far more often. Re-read on resume as well;
+		// `pageshow` additionally covers a back/forward-cache restore.
+		const onVisible = () => {
+			if (document.visibilityState === 'visible') sync();
+		};
+		document.addEventListener('visibilitychange', onVisible);
+		window.addEventListener('pageshow', sync);
+		return () => {
+			media.removeEventListener('change', sync);
+			document.removeEventListener('visibilitychange', onVisible);
+			window.removeEventListener('pageshow', sync);
+		};
+	}, [mode]);
+	// Keep other tabs of the same app in step.
+	useEffect(() => {
+		const onStorage = (event: StorageEvent) => {
+			if (event.key !== THEME_STORAGE_KEY || !isThemeMode(event.newValue)) return;
+			setModeState(event.newValue);
+			const next = resolve(event.newValue);
+			setResolved(next);
+			applyTheme(next);
+		};
+		window.addEventListener('storage', onStorage);
+		return () => window.removeEventListener('storage', onStorage);
+	}, []);
+	const value = useMemo(
+		() => ({
+			mode,
+			resolved,
+			setMode,
+			toggle: () => setMode(mode === 'light' ? 'dark' : mode === 'dark' ? 'system' : 'light')
+		}),
+		[mode, resolved, setMode]
+	);
+	return <ThemeContext value={value}>{children}</ThemeContext>;
+}

package/templates/react-app/files/src/shared/ui/theme/theme-toggle.tsx ADDED Viewed

@@ -0,0 +1,40 @@
+import { Monitor, Moon, Sun } from 'lucide-react';
+import { cn } from '../lib/utils';
+import { useTheme } from './use-theme';
+import type { ThemeMode } from './theme-context';
+const NEXT_LABEL: Record<ThemeMode, string> = {
+	light: 'Switch to dark theme',
+	dark: 'Switch to system theme',
+	system: 'Switch to light theme'
+};
+const ICONS: Record<ThemeMode, React.ReactNode> = {
+	light: <Sun className="size-4" aria-hidden="true" />,
+	dark: <Moon className="size-4" aria-hidden="true" />,
+	system: <Monitor className="size-4" aria-hidden="true" />
+};
+/**
+ * Single-button theme control that cycles light → dark → system. The icon shows
+ * the *current* mode, while the accessible name says what pressing it will do —
+ * an icon-only control has to announce its action, not just its state.
+ */
+export function ThemeToggle({ className }: { className?: string }) {
+	const { mode, toggle } = useTheme();
+	return (
+		<button
+			type="button"
+			onClick={toggle}
+			title={NEXT_LABEL[mode]}
+			aria-label={NEXT_LABEL[mode]}
+			className={cn(
+				'flex size-9 items-center justify-center rounded-full bg-secondary text-foreground transition-colors hover:bg-accent',
+				className
+			)}
+		>
+			{ICONS[mode]}
+		</button>
+	);
+}

package/templates/react-app/files/src/shared/ui/theme/use-theme.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { ThemeContext, type ThemeContextValue } from './theme-context';
+/** Current theme + setters. Throws if used outside <ThemeProvider>. */
+export function useTheme(): ThemeContextValue {
+	const value = useContext(ThemeContext);
+	if (!value) {
+		throw new Error('useTheme must be used inside a <ThemeProvider>.');
+	}
+	return value;
+}

package/templates/react-app/files/src/vite-env.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/// <reference types="vite/client" />
+/// <reference types="vite-plugin-pwa/react" /> // @feature pwa
+interface ImportMetaEnv {
+	VITE_APP_API_URL: string;
+	VITE_APP_ALLOWED_HOSTS: string;
+	VITE_APP_SITE_URL: string; // @feature marketing
+	VITE_APP_SUPPORT_EMAIL: string; // @feature marketing
+}
+interface ImportMeta {
+	readonly env: ImportMetaEnv;
+}