@pablozaiden/webapp 0.6.1 → 0.6.3

package/README.md

@@ -23,7 +23,7 @@ Each application package must declare `react` and `react-dom`; they are peer dep
 | Export | Use |
 | --- | --- |
 | `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, request-origin helpers, SQLite store |
-| `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, sidebar types, UI controls, realtime hooks |
+| `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, `useToast`, sidebar types, UI controls, realtime hooks |
 | `@pablozaiden/webapp/contracts` | Shared auth/config/device/API-key types |
 | `@pablozaiden/webapp/cli` | One-binary command helpers, device/environment auth credentials and generic API CLI caller |
 | `@pablozaiden/webapp/build` | Bun single-binary compile helper |

package/docs/getting-started.md

@@ -122,6 +122,109 @@ renderWebApp(
 ```
 
 `renderWebApp` renders into `#root` by default and reuses the existing React root across hot reloads. Pass a custom element id or `Element` only when the app uses a different mount point.
+
+### Theme state
+
+The framework applies the local or system theme before the first React render and
+loads the signed-in user's saved preference in the background. Components
+rendered inside `WebAppRoot` can use the public hook when JavaScript needs the
+effective theme, such as for a terminal, editor, or chart:
+
+```tsx
+import { Page, useTheme } from "@pablozaiden/webapp/web";
+
+function ThemeAwareRoute() {
+  const { preference, resolvedTheme } = useTheme();
+
+  return (
+    <Page>
+      <p>Preference: {preference}</p>
+      <p>Resolved theme: {resolvedTheme}</p>
+    </Page>
+  );
+}
+```
+
+`preference` is `system`, `light`, or `dark`; `resolvedTheme` is always
+`light` or `dark` and follows operating-system changes while `preference` is
+`system`. Prefer CSS dark-mode styling when JavaScript does not need the
+resolved value. Do not inspect or mutate framework-owned root classes or
+attributes to infer theme state.
+
+### Client log-level state
+
+The framework loads the effective client log level as part of the shared
+`WebAppRoot` configuration request. Components rendered inside `WebAppRoot`
+can subscribe with `useLogLevel()`; they should not fetch framework
+configuration or `/api/preferences/log-level` in an app-local initializer:
+
+```tsx
+import { useEffect } from "react";
+import { useLogLevel } from "@pablozaiden/webapp/web";
+import type { LogLevelName } from "@pablozaiden/webapp/contracts";
+
+function LoggerAdapter({ setLevel }: { setLevel: (level: LogLevelName) => void }) {
+  const { level, fromEnv, loading, error, retry } = useLogLevel();
+
+  useEffect(() => {
+    if (level !== undefined) {
+      setLevel(level);
+    }
+  }, [level, setLevel]);
+
+  if (error) {
+    return <button type="button" onClick={() => void retry()}>Retry log-level configuration</button>;
+  }
+  if (loading || level === undefined) {
+    return null;
+  }
+
+  return <span aria-hidden="true">{fromEnv ? "Log level is environment-controlled." : null}</span>;
+}
+```
+
+`level` and `fromEnv` are unavailable until valid framework configuration has
+loaded. Do not substitute a default level when `error` is set. The framework
+Settings control owns persistence and updates the shared state without a page
+reload; `fromEnv` indicates that the server environment locks the value.
+`LoggerAdapter` remains application-owned and can adapt the state to any
+logging library.
+
+### Transient notifications
+
+The standard `renderWebApp` runtime provides the framework notification service
+to the application tree. Use the public hook for short-lived action outcomes;
+do not add an application-owned provider, queue, timer system, or notification
+CSS:
+
+```tsx
+import { useToast } from "@pablozaiden/webapp/web";
+
+function SaveButton() {
+  const toast = useToast();
+
+  async function save() {
+    await saveRecord();
+    toast.success("Saved");
+  }
+
+  return <button type="button" onClick={() => void save()}>Save</button>;
+}
+```
+
+`useToast()` exposes `success`, `error`, `warning`, and `info` helpers. Each
+returns a stable ID that can be passed to `dismiss`; `dismissAll` removes every
+active notification. Pass an `id` to replace an existing notification and
+reset its timer. Notifications dismiss after 8 seconds by default; provide a
+positive `duration` in milliseconds for a custom timeout or use
+`duration: 0` for a persistent notification that requires explicit dismissal.
+The framework keeps at most five active notifications.
+
+Use `ErrorState`, loading states, and field validation for persistent page or
+form state. Use `ConfirmDialog` for destructive confirmation. Do not report the
+same failure in both an inline error state and a toast unless both surfaces
+serve distinct, intentional purposes.
+
 `WebAppRoot` owns the shell and `.wapp-main-content`; each route component should return a `Page` wrapper so standard content margins, mobile padding and scroll behavior stay consistent. `Page` uses the padded layout by default. For routes whose child content fills the available shell viewport and owns its own spacing or scrolling, use the framework full layout instead of overriding framework CSS:
 
 ```tsx

package/docs/release.md

@@ -6,7 +6,7 @@
 
 1. Install dependencies with `bun install --frozen-lockfile`.
 2. Run `bun run tsc`.
-3. Run `bun test`.
+3. Run `bun run test`, which runs the build-binary integration tests in an isolated process before the remaining suites.
 4. Build both example apps.
 5. Start the compiled example binaries and smoke-test `/api/health` plus one app endpoint.
 

package/docs/server.md

@@ -124,6 +124,12 @@ Built-in endpoints include:
 | `/api/server/kill` | Authenticated server shutdown |
 | `/api/ws` | Realtime websocket by default |
 
+The effective log level in `GET /api/config` and `GET
+/api/preferences/log-level` is resolved identically: an environment-provided
+`{PREFIX}_LOG_LEVEL` wins over the persisted preference, and sets `fromEnv`
+to `true`. PUT remains an authenticated, same-origin admin mutation and
+returns a conflict when the environment controls the value.
+
 ## Framework-owned web document and PWA metadata
 
 `createWebAppServer` owns the browser document. Apps do not provide `index.html`; the framework generates a Bun `HTMLBundle` internally so Bun hot reload and asset rewriting keep working. By default the frontend entrypoint is `./web/main.tsx` relative to the Bun entry file. The generated document also initializes the shared `data-wapp-mobile` state before client styles load so CSS and `WebAppRoot` use the same mobile breakpoint. The generated viewport keeps the app at `initial-scale=1` with `maximum-scale=1` and `user-scalable=no`; clients and mobile browsers that honor those viewport scaling tokens, including iPhone and iPad, cannot change the app scale with pinch-to-zoom while normal scrolling remains enabled. Clients that ignore the tokens are unaffected.

package/docs/settings.md

@@ -16,6 +16,23 @@ user preference loads in the background. If that request fails, the current
 theme remains active and Display Settings shows a non-blocking error with a
 retry action; the rest of Settings remains usable.
 
+Application code rendered inside `WebAppRoot` can use `useTheme()` from
+`@pablozaiden/webapp/web` when JavaScript needs theme state. The hook exposes
+the selected `preference` and concrete `resolvedTheme`; the latter updates
+when the operating-system color scheme changes in `system` mode. Prefer CSS
+dark-mode styling when no JavaScript theme value is required, and do not infer
+theme state by observing framework-owned DOM classes or attributes.
+
+Application code can use `useLogLevel()` from `@pablozaiden/webapp/web` to
+adapt an application-owned logger to the framework's effective client setting.
+The hook exposes `level`, `fromEnv`, `loading`, `error`, and `retry`. The level
+and environment metadata are unavailable until `/api/config` has loaded and
+validated; configuration failures remain visible through `error` instead of
+falling back to a fabricated level. The framework Settings selector updates
+the shared hook state after a successful save, and `fromEnv` is true when
+`{PREFIX}_LOG_LEVEL` locks the value. Applications should not add a separate
+configuration fetch or initializer component.
+
 Security lists only show useful active credentials. Expired API keys are purged before listing, and revoked or expired device-auth refresh sessions are not shown. Revoked refresh sessions may remain in storage when needed for token-reuse protection, but they are hidden from Settings.
 
 Destructive actions in Settings use the framework `ConfirmDialog` before mutating. This includes deleting users, deleting API keys, deleting passkeys, revoking device-auth sessions, and killing the server.

package/docs/ui-guidelines.md

@@ -11,6 +11,20 @@ The framework intentionally provides a consistent base UI:
 - Main content should prefer panels, toolbars, badges and simple forms over custom one-off layouts.
 - `WebAppRoot` owns the fixed main title bar and `.wapp-main-content`; app routes should not render or style those shell elements directly.
 
+## Transient notifications
+
+Use `useToast()` from `@pablozaiden/webapp/web` for short-lived success,
+error, warning, or informational feedback. The standard `renderWebApp` runtime
+already owns the provider, queue, timers, live region, dismissal controls, and
+styling, so applications must not add a parallel toast provider, queue, or
+notification CSS. Use the returned ID with `dismiss` when an operation needs
+to close a persistent notification, or use `dismissAll` to clear the queue.
+
+Use inline `ErrorState`, loading states, and field validation when the
+information belongs to persistent page or form state. Use `ConfirmDialog` for
+destructive confirmation rather than a toast, and avoid reporting one failure
+twice without a distinct user-facing reason.
+
 ## Mobile breakpoint and viewport synchronization
 
 The framework owns the mobile shell breakpoint. `MOBILE_BREAKPOINT_PX` and `MOBILE_MEDIA_QUERY` are exported from `@pablozaiden/webapp/web` for application JavaScript that needs to coordinate with the shell; do not add an independent `innerWidth` threshold for shell behavior. The generated document initializes the `data-wapp-mobile` marker on the root element before the client and styles load, and `WebAppRoot` keeps it synchronized with media-query changes. Custom CSS that follows the framework mobile mode should use that marker rather than repeating a numeric media query.
@@ -64,7 +78,26 @@ Reference screenshots live in `artifacts/screenshots`:
 | `kitchen-dialog-dark.png` | Confirm dialog overlay |
 | `kitchen-device-light.png` | Device auth approval flow |
 
-Use the temporary Playwright harness described in `skills/webapp/SKILL.md` when new visual captures are needed. Its default output is disposable; to intentionally update these checked-in reference captures, run the application-specific temporary harness with `PLAYWRIGHT_OUT_DIR="$PWD/artifacts/screenshots"` and review every changed image before committing it. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths. The framework does not ship a screenshot command or Playwright dependency.
+Use the temporary Playwright harness described in `skills/webapp/SKILL.md` when new visual captures are needed. Its default output is disposable; to intentionally update these checked-in reference captures, run the application-specific temporary harness with `PLAYWRIGHT_OUT_DIR="$PWD/artifacts/screenshots"` and review every changed image before committing it. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths.
+
+The framework does not add Playwright to an application's dependencies or ship a
+screenshot command. Install the official Playwright package and Chromium in an
+isolated temporary directory instead:
+
+```bash
+playwright_workdir="$(mktemp -d)"
+trap 'rm -rf "$playwright_workdir"' EXIT
+cd "$playwright_workdir"
+npm init -y >/dev/null
+npm install --no-save --package-lock=false playwright
+npx playwright install chromium
+```
+
+Run the Playwright Node API from that temporary harness against the already
+running application, and keep screenshots and browser state there. Do not add
+Playwright, browser binaries, scripts, or configuration files to the
+application repository. If Linux browser system libraries are missing, run
+`npx playwright install-deps` from the same harness environment.
 
 Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles. When screenshots are captured to validate a visual change, review them against the specific goal; capturing files without checking the result is not validation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",
@@ -33,11 +33,15 @@
     "dev": "bun run --cwd examples/notes-todo dev",
     "dev:kitchen-sink": "bun run --cwd examples/kitchen-sink dev",
     "dev:notes-todo": "bun run --cwd examples/notes-todo dev",
-    "build": "bun run tsc && bun run --cwd examples/kitchen-sink build && bun run --cwd examples/notes-todo build",
+    "build": "bun run typecheck && bun run build:examples",
+    "build:examples": "bun run --cwd examples/kitchen-sink build && bun run --cwd examples/notes-todo build",
     "build:kitchen-sink": "bun run --cwd examples/kitchen-sink build",
     "build:notes-todo": "bun run --cwd examples/notes-todo build",
-    "test": "bun test",
-    "tsc": "mkdir -p .cache/tsc && bunx tsc --noEmit --pretty false --incremental --tsBuildInfoFile .cache/tsc/build.tsbuildinfo"
+    "test": "bun run test:build-binary && bun run test:remaining",
+    "test:build-binary": "bun test tests/build-binary.test.ts",
+    "test:remaining": "bun test --path-ignore-patterns=**/build-binary.test.ts",
+    "typecheck": "mkdir -p .cache/tsc && bunx tsc --noEmit --pretty false --incremental --tsBuildInfoFile .cache/tsc/build.tsbuildinfo",
+    "tsc": "bun run typecheck"
   },
   "dependencies": {
     "@simplewebauthn/browser": "13.3.0",

package/src/server/create-web-app-server.ts

@@ -1,7 +1,7 @@
 import type { Server } from "bun";
 import { sqliteWebAppStore } from "./auth/sqlite-store";
 import { createRealtimeBus } from "./realtime/bus";
-import { readRuntimeConfig } from "./runtime-config";
+import { readRuntimeConfig, resolveEffectiveLogLevel } from "./runtime-config";
 import {
   WEBAPP_SOCKET_HANDLER,
   type WebAppServer,
@@ -45,7 +45,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
   const store = input.store ?? sqliteWebAppStore({ dataDir: config.dataDir });
   store.initialize();
   const savedLogLevel = store.getLogLevelPreference();
-  const activeLogLevel = config.logLevelFromEnv ? config.logLevel : savedLogLevel ?? config.logLevel;
+  const activeLogLevel = resolveEffectiveLogLevel(config, savedLogLevel);
   setLogLevel(activeLogLevel);
   input.logLevel?.onChange?.(activeLogLevel);
   const realtime = createRealtimeBus<TEvent>();

package/src/server/framework-endpoints.ts

@@ -59,7 +59,7 @@ import {
   tokenRequestSchema,
   userRoleRequestSchema,
 } from "./request-schemas";
-import type { RuntimeConfig } from "./runtime-config";
+import { resolveEffectiveLogLevel, type RuntimeConfig } from "./runtime-config";
 import { setLogLevel } from "./logger";
 import { errorResponse, jsonResponse, notFound, parseJson, successResponse } from "./responses";
 import type { WebSocketData } from "./realtime/bus";
@@ -112,7 +112,7 @@ export function createFrameworkEndpointHandler(dependencies: FrameworkEndpointDe
         canManageUsers: Boolean(user?.isAdmin),
       },
       logLevel: {
-        level: (config.logLevelFromEnv ? config.logLevel : store.getLogLevelPreference() ?? config.logLevel) as LogLevelName,
+        level: resolveEffectiveLogLevel(config, store.getLogLevelPreference()),
         fromEnv: config.logLevelFromEnv,
       },
       apiKeys: { enabled: Boolean(apiKeysEnabled) },
@@ -416,7 +416,10 @@ export function createFrameworkEndpointHandler(dependencies: FrameworkEndpointDe
         if (auth instanceof Response) return auth;
         ensureAdmin(auth);
         if (req.method === "GET") {
-          return jsonResponse({ level: store.getLogLevelPreference() ?? config.logLevel, fromEnv: config.logLevelFromEnv });
+          return jsonResponse({
+            level: resolveEffectiveLogLevel(config, store.getLogLevelPreference()),
+            fromEnv: config.logLevelFromEnv,
+          });
         }
         if (req.method === "PUT") {
           const originFailure = checkSameOrigin(req, config, auth, "mutations");

package/src/server/runtime-config.ts

@@ -26,7 +26,22 @@ export interface RuntimeConfig {
   development: false | { hmr: true; console: true };
 }
 
-const LOG_LEVELS = new Set(["trace", "debug", "info", "warn", "error"]);
+const LOG_LEVELS = new Set<LogLevelName>(["trace", "debug", "info", "warn", "error"]);
+
+function isSupportedLogLevel(value: unknown): value is LogLevelName {
+  return typeof value === "string" && LOG_LEVELS.has(value as LogLevelName);
+}
+
+export function resolveEffectiveLogLevel(
+  config: Pick<RuntimeConfig, "logLevel" | "logLevelFromEnv">,
+  savedLogLevel?: unknown,
+): LogLevelName {
+  return config.logLevelFromEnv
+    ? config.logLevel
+    : isSupportedLogLevel(savedLogLevel)
+      ? savedLogLevel
+      : config.logLevel;
+}
 
 export function isTruthyEnv(value: string | undefined): boolean {
   const normalized = value?.trim().toLowerCase();
@@ -64,10 +79,10 @@ function parseLogLevel(raw: string | undefined, fallback: LogLevelName, name: st
   if (!raw) {
     return fallback;
   }
-  if (!LOG_LEVELS.has(raw)) {
+  if (!isSupportedLogLevel(raw)) {
     throw new Error(`${name} must be one of trace, debug, info, warn, error; received "${raw}"`);
   }
-  return raw as LogLevelName;
+  return raw;
 }
 
 function parseBoolean(raw: string | undefined, fallback: boolean, name: string): boolean {

package/src/web/WebAppRoot.tsx

@@ -1,6 +1,5 @@
 import { useCallback, useEffect, useId, useMemo, useRef, useState, type ReactNode } from "react";
-import type { ThemePreference, WebAppConfigResponse } from "../contracts";
-import { appJson } from "./api-client";
+import type { WebAppConfigResponse } from "../contracts";
 import { AppShell } from "./app-shell";
 import { DeviceVerificationScreen, PasskeyAuthScreen, UserSetupScreen } from "./auth-screens";
 import { EmptyState, Panel } from "./components";
@@ -10,35 +9,12 @@ import { flattenSidebarItems, toStoredPin, useSidebarCollapsedState, useSidebarP
 import { SettingsView } from "./settings/settings-view";
 import type { HeaderContext, WebAppRootProps } from "./root-types";
 import type { ActionMenuItem, SidebarNode, WebAppRoute } from "./sidebar/types";
+import { ThemeProvider } from "./theme";
+import { WebAppConfigProvider, useWebAppConfig } from "./webapp-config";
 
 export { replaceHashRoute, replaceWebAppRoute, routeToHash } from "./routing";
 export type { HeaderContext, SettingsAction, SettingsRow, SettingsSection, WebAppRootProps } from "./root-types";
 
-function useConfig() {
-  const [config, setConfig] = useState<WebAppConfigResponse>();
-  const [error, setError] = useState<string>();
-  const refresh = useCallback(async () => {
-    try {
-      setConfig(await appJson<WebAppConfigResponse>("/api/config"));
-      setError(undefined);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err));
-    }
-  }, []);
-  useEffect(() => void refresh(), [refresh]);
-  return { config, error, refresh };
-}
-
-function useTheme() {
-  const [theme, setTheme] = useState<ThemePreference>(() => (localStorage.getItem("webapp.theme") as ThemePreference | null) ?? "system");
-  useEffect(() => {
-    const dark = theme === "dark" || (theme === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches);
-    document.documentElement.classList.toggle("dark", dark);
-    localStorage.setItem("webapp.theme", theme);
-  }, [theme]);
-  return { theme, setTheme };
-}
-
 function routeMatches(left: WebAppRoute | undefined, right: WebAppRoute): boolean {
   if (!left) {
     return false;
@@ -46,14 +22,26 @@ function routeMatches(left: WebAppRoute | undefined, right: WebAppRoute): boolea
   return left.view === right.view && Object.entries(left).every(([key, value]) => key === "view" || right[key] === value);
 }
 
-export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRouteChange, settings, version }: WebAppRootProps) {
+function WebAppRootContent({
+  appName,
+  homeRoute,
+  sidebar,
+  routes,
+  header,
+  onRouteChange,
+  settings,
+  version,
+  config,
+  error,
+  refresh,
+}: WebAppRootProps & {
+  config?: WebAppConfigResponse;
+  error?: Error;
+  refresh: () => Promise<void>;
+}) {
   const isMobile = useMobileBreakpoint();
   useMobileViewportHeight(isMobile);
-  const { config, error, refresh } = useConfig();
   const { route, navigate } = useRoute(homeRoute);
-  const { theme, setTheme } = useTheme();
-  const [themeLoading, setThemeLoading] = useState(false);
-  const [themeLoadError, setThemeLoadError] = useState<Error>();
   const [search, setSearch] = useState("");
   const sidebarSearchId = useId();
   const sidebarSearchInputRef = useRef<HTMLInputElement>(null);
@@ -125,35 +113,12 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
   }, [augmentPinningActions, baseNodes, currentPins, filteredNodes, pinningEnabled, sidebar.pinning, sidebarSearchActive]);
   const activeActionNodes = useMemo(() => augmentPinningActions(baseNodes), [augmentPinningActions, baseNodes]);
 
-  const retryThemeLoad = useCallback(async () => {
-    if (!config?.currentUser) {
-      setThemeLoading(false);
-      setThemeLoadError(undefined);
-      return;
-    }
-
-    setThemeLoading(true);
-    setThemeLoadError(undefined);
-    try {
-      const result = await appJson<{ theme: ThemePreference }>("/api/preferences/theme");
-      setTheme(result.theme);
-    } catch (err) {
-      setThemeLoadError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setThemeLoading(false);
-    }
-  }, [config?.currentUser?.id, setTheme]);
-
-  useEffect(() => {
-    void retryThemeLoad();
-  }, [retryThemeLoad]);
-
   useEffect(() => {
     onRouteChange?.(route);
   }, [onRouteChange, route]);
 
-  if (error) {
-    return <main className="wapp-auth-screen"><Panel title="Unable to load app" description={error} /></main>;
+  if (error && !config) {
+    return <main className="wapp-auth-screen"><Panel title="Unable to load app" description={error.message} /></main>;
   }
   if (!config) {
     return <main className="wapp-auth-screen">Loading...</main>;
@@ -171,7 +136,7 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
   const effectiveVersion = version ?? config.version;
   let view: ReactNode;
   if (route.view === "settings") {
-    view = <SettingsView config={config} refresh={refresh} customSections={settings?.sections ?? []} theme={theme} setTheme={setTheme} themeLoading={themeLoading} themeLoadError={themeLoadError} retryThemeLoad={retryThemeLoad} />;
+    view = <SettingsView config={config} refresh={refresh} customSections={settings?.sections ?? []} />;
   } else {
     const registeredView = routes[route.view];
     view = typeof registeredView === "function"
@@ -220,3 +185,20 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
     />
   );
 }
+
+function WebAppRootWithConfig(props: WebAppRootProps) {
+  const { config, error, refresh } = useWebAppConfig();
+  return (
+    <ThemeProvider userId={config?.currentUser?.id}>
+      <WebAppRootContent {...props} config={config} error={error} refresh={refresh} />
+    </ThemeProvider>
+  );
+}
+
+export function WebAppRoot(props: WebAppRootProps) {
+  return (
+    <WebAppConfigProvider>
+      <WebAppRootWithConfig {...props} />
+    </WebAppConfigProvider>
+  );
+}

package/src/web/index.ts

@@ -4,6 +4,12 @@ export * from "./render";
 export * from "./api-client";
 export * from "./sidebar/types";
 export * from "./realtime/useRealtime";
+export { useToast } from "./toast";
+export type { Toast, ToastId, ToastOptions, ToastService, ToastShowOptions, ToastVariant } from "./toast";
 export { MOBILE_BREAKPOINT_PX, MOBILE_MEDIA_QUERY, MOBILE_STATE_ATTRIBUTE } from "./mobile";
+export { useTheme } from "./theme";
+export type { ResolvedTheme, WebAppThemeState } from "./theme";
+export { useLogLevel } from "./log-level";
+export type { WebAppLogLevelState } from "./log-level";
 export { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 export type { ThemePreference } from "../contracts";

package/src/web/log-level.tsx

@@ -0,0 +1,22 @@
+import { useMemo } from "react";
+import type { LogLevelName } from "../contracts";
+import { useWebAppConfig } from "./webapp-config";
+
+export interface WebAppLogLevelState {
+  level?: LogLevelName;
+  fromEnv?: boolean;
+  loading: boolean;
+  error?: Error;
+  retry: () => Promise<void>;
+}
+
+export function useLogLevel(): WebAppLogLevelState {
+  const { config, loading, error, refresh } = useWebAppConfig("useLogLevel");
+  return useMemo(() => ({
+    level: config?.logLevel.level,
+    fromEnv: config?.logLevel.fromEnv,
+    loading,
+    error,
+    retry: refresh,
+  }), [config?.logLevel.fromEnv, config?.logLevel.level, error, loading, refresh]);
+}

package/src/web/render.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { Root } from "react-dom/client";
+import { ToastProvider } from "./toast";
 
 declare global {
   var __pablozaidenWebAppRoots: WeakMap<Element, Root> | undefined;
@@ -11,6 +12,10 @@ function roots(): WeakMap<Element, Root> {
   return globalThis.__pablozaidenWebAppRoots;
 }
 
+function WebAppRuntime({ element }: { element: ReactNode }) {
+  return <ToastProvider>{element}</ToastProvider>;
+}
+
 export function configureWebAppRenderer(createRoot: (target: Element) => Root): void {
   globalThis.__pablozaidenCreateWebAppRoot = createRoot;
 }
@@ -30,6 +35,6 @@ export function renderWebApp(element: ReactNode, container: Element | string = "
     root = createRoot(target);
     registry.set(target, root);
   }
-  root.render(element);
+  root.render(<WebAppRuntime element={element} />);
   return root;
 }

package/src/web/settings/account-section.tsx

@@ -1,19 +1,44 @@
-import type { ThemePreference, WebAppConfigResponse } from "../../contracts";
+import { useState } from "react";
+import type { LogLevelName, WebAppConfigResponse } from "../../contracts";
 import { appJson } from "../api-client";
 import { Badge, Button, ErrorState, FormSection, LoadingState, SelectField } from "../components";
+import { useLogLevel } from "../log-level";
+import { isThemePreference, useTheme } from "../theme";
+
+const LOG_LEVEL_NAMES = ["trace", "debug", "info", "warn", "error"] as const satisfies readonly LogLevelName[];
+
+function isLogLevelName(value: string): value is LogLevelName {
+  return LOG_LEVEL_NAMES.some((level) => level === value);
+}
 
 export interface AccountSectionProps {
   config: WebAppConfigResponse;
-  theme: ThemePreference;
-  setTheme: (theme: ThemePreference) => void;
-  themeLoading: boolean;
-  themeLoadError?: Error;
-  retryThemeLoad: () => Promise<void>;
   refresh: () => Promise<void>;
   setError: (error: string | undefined) => void;
 }
 
-export function AccountSection({ config, theme, setTheme, themeLoading, themeLoadError, retryThemeLoad, refresh, setError }: AccountSectionProps) {
+export function AccountSection({ config, refresh, setError }: AccountSectionProps) {
+  const { preference, setPreference, loading, error, retry } = useTheme();
+  const logLevel = useLogLevel();
+  const [logLevelSaving, setLogLevelSaving] = useState(false);
+
+  async function updateLogLevel(value: string) {
+    if (!isLogLevelName(value)) {
+      setError(`Unknown log level: ${value}`);
+      return;
+    }
+    try {
+      setError(undefined);
+      setLogLevelSaving(true);
+      await appJson<unknown>("/api/preferences/log-level", { method: "PUT", body: JSON.stringify({ level: value }) });
+      await refresh();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLogLevelSaving(false);
+    }
+  }
+
   return (
     <>
       {config.currentUser ? (
@@ -22,29 +47,47 @@ export function AccountSection({ config, theme, setTheme, themeLoading, themeLoa
         </FormSection>
       ) : null}
       <FormSection title="Display Settings">
-        <SelectField label="Theme" value={theme} onChange={(event) => {
-          const next = event.currentTarget.value as ThemePreference;
-          setTheme(next);
+        <SelectField label="Theme" value={preference} onChange={(event) => {
+          const next = event.currentTarget.value;
+          if (!isThemePreference(next)) {
+            setError(`Unknown theme preference: ${next}`);
+            return;
+          }
+          setPreference(next);
           void appJson("/api/preferences/theme", { method: "PUT", body: JSON.stringify({ theme: next }) }).catch((err) => setError(String(err)));
         }}>
           <option value="system">System</option>
           <option value="light">Light</option>
           <option value="dark">Dark</option>
         </SelectField>
-        {themeLoading ? <LoadingState title="Loading saved theme" /> : null}
-        {themeLoadError ? (
+        {loading ? <LoadingState title="Loading saved theme" /> : null}
+        {error ? (
           <ErrorState
-            description={themeLoadError.message}
-            action={<Button type="button" loading={themeLoading} onClick={() => void retryThemeLoad()}>Retry</Button>}
+            description={error.message}
+            action={<Button type="button" loading={loading} onClick={() => void retry()}>Retry</Button>}
           />
         ) : null}
       </FormSection>
 
       {config.currentUser?.isAdmin ? (
         <FormSection title="Developer Settings">
-          <SelectField label={config.logLevel.fromEnv ? `Log level (${config.logLevel.level}, controlled by env)` : "Log level"} value={config.logLevel.level} disabled={config.logLevel.fromEnv} onChange={(event) => void appJson("/api/preferences/log-level", { method: "PUT", body: JSON.stringify({ level: event.currentTarget.value }) }).then(refresh)}>
-            {["trace", "debug", "info", "warn", "error"].map((level) => <option key={level} value={level}>{level}</option>)}
-          </SelectField>
+          {logLevel.error ? (
+            <ErrorState
+              description={logLevel.error.message}
+              action={<Button type="button" loading={logLevel.loading} onClick={() => void logLevel.retry()}>Retry</Button>}
+            />
+          ) : null}
+          {logLevel.loading && logLevel.level === undefined ? <LoadingState title="Loading log level" /> : null}
+          {logLevel.level !== undefined ? (
+            <SelectField
+              label={logLevel.fromEnv ? `Log level (${logLevel.level}, controlled by env)` : "Log level"}
+              value={logLevel.level}
+              disabled={logLevel.fromEnv === true || logLevel.loading || logLevelSaving}
+              onChange={(event) => void updateLogLevel(event.currentTarget.value)}
+            >
+              {LOG_LEVEL_NAMES.map((level) => <option key={level} value={level}>{level}</option>)}
+            </SelectField>
+          ) : null}
         </FormSection>
       ) : null}
     </>

package/src/web/settings/settings-view.tsx

@@ -1,5 +1,5 @@
 import { useState, type ReactNode } from "react";
-import type { ThemePreference, WebAppConfigResponse } from "../../contracts";
+import type { WebAppConfigResponse } from "../../contracts";
 import { Button, DangerZone, FormSection } from "../components";
 import type { SettingsRow, SettingsScope, SettingsSection } from "../root-types";
 import { AccountSection } from "./account-section";
@@ -64,20 +64,15 @@ export interface SettingsViewProps {
   config: WebAppConfigResponse;
   refresh: () => Promise<void>;
   customSections: SettingsSection[];
-  theme: ThemePreference;
-  setTheme: (theme: ThemePreference) => void;
-  themeLoading: boolean;
-  themeLoadError?: Error;
-  retryThemeLoad: () => Promise<void>;
 }
 
-export function SettingsView({ config, refresh, customSections, theme, setTheme, themeLoading, themeLoadError, retryThemeLoad }: SettingsViewProps) {
+export function SettingsView({ config, refresh, customSections }: SettingsViewProps) {
   const [error, setError] = useState<string>();
 
   return (
     <div className="wapp-settings">
       {error ? <p className="wapp-error">{error}</p> : null}
-      <AccountSection config={config} theme={theme} setTheme={setTheme} themeLoading={themeLoading} themeLoadError={themeLoadError} retryThemeLoad={retryThemeLoad} refresh={refresh} setError={setError} />
+      <AccountSection config={config} refresh={refresh} setError={setError} />
       <FormSection title="Security">
         <SecuritySection config={config} refresh={refresh} setError={setError} />
         <SessionsSection config={config} setError={setError} />

package/src/web/styles.css

@@ -11,6 +11,18 @@
   --wapp-muted-2: #64748b;
   --wapp-danger: #991b1b;
   --wapp-danger-bg: #991b1b;
+  --wapp-toast-success: #166534;
+  --wapp-toast-success-surface: #f0fdf4;
+  --wapp-toast-success-border: #86efac;
+  --wapp-toast-error: #991b1b;
+  --wapp-toast-error-surface: #fef2f2;
+  --wapp-toast-error-border: #fca5a5;
+  --wapp-toast-warning: #92400e;
+  --wapp-toast-warning-surface: #fffbeb;
+  --wapp-toast-warning-border: #fcd34d;
+  --wapp-toast-info: #1e40af;
+  --wapp-toast-info-surface: #eff6ff;
+  --wapp-toast-info-border: #93c5fd;
   --wapp-primary: #111827;
   --wapp-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
   --wapp-overlay-bg: rgb(0 0 0 / 0.5);
@@ -49,6 +61,18 @@
   --wapp-muted-2: #71717a;
   --wapp-danger: #fca5a5;
   --wapp-danger-bg: #7f1d1d;
+  --wapp-toast-success: #bbf7d0;
+  --wapp-toast-success-surface: #14532d;
+  --wapp-toast-success-border: #166534;
+  --wapp-toast-error: #fecaca;
+  --wapp-toast-error-surface: #7f1d1d;
+  --wapp-toast-error-border: #991b1b;
+  --wapp-toast-warning: #fde68a;
+  --wapp-toast-warning-surface: #78350f;
+  --wapp-toast-warning-border: #92400e;
+  --wapp-toast-info: #bfdbfe;
+  --wapp-toast-info-surface: #1e3a8a;
+  --wapp-toast-info-border: #1e40af;
   --wapp-primary: #f9fafb;
   --wapp-shadow: none;
 }
@@ -1453,6 +1477,110 @@ textarea::placeholder {
   color: var(--wapp-danger);
 }
 
+.wapp-toast-viewport {
+  position: fixed;
+  right: max(1rem, var(--wapp-safe-area-right));
+  bottom: max(1rem, var(--wapp-safe-area-bottom));
+  z-index: 70;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0.5rem;
+  width: min(24rem, calc(100vw - 2rem));
+  max-height: calc(var(--wapp-viewport-height) - 2rem);
+  overflow-y: auto;
+  padding: 0.25rem;
+  pointer-events: none;
+}
+
+.wapp-toast {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+  min-width: 0;
+  border: 1px solid var(--wapp-border);
+  border-radius: 0.75rem;
+  background: var(--wapp-surface);
+  color: var(--wapp-text);
+  padding: 0.75rem;
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.14);
+  pointer-events: auto;
+  animation: wapp-toast-enter 160ms ease-out;
+}
+
+.wapp-toast-success {
+  border-color: var(--wapp-toast-success-border);
+  background: var(--wapp-toast-success-surface);
+  color: var(--wapp-toast-success);
+}
+
+.wapp-toast-error {
+  border-color: var(--wapp-toast-error-border);
+  background: var(--wapp-toast-error-surface);
+  color: var(--wapp-toast-error);
+}
+
+.wapp-toast-warning {
+  border-color: var(--wapp-toast-warning-border);
+  background: var(--wapp-toast-warning-surface);
+  color: var(--wapp-toast-warning);
+}
+
+.wapp-toast-info {
+  border-color: var(--wapp-toast-info-border);
+  background: var(--wapp-toast-info-surface);
+  color: var(--wapp-toast-info);
+}
+
+.wapp-toast-message {
+  min-width: 0;
+  flex: 1 1 auto;
+  overflow-wrap: anywhere;
+  color: inherit;
+  font-size: 0.875rem;
+  line-height: 1.35;
+}
+
+.wapp-toast-dismiss {
+  display: inline-flex;
+  flex: 0 0 1.75rem;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font-size: 1.25rem;
+  line-height: 1;
+}
+
+.wapp-toast-dismiss:hover,
+.wapp-toast-dismiss:focus-visible {
+  background: rgb(0 0 0 / 0.1);
+  outline: none;
+}
+
+@keyframes wapp-toast-enter {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .wapp-toast {
+    animation: none;
+  }
+}
+
 .wapp-notice {
   color: var(--wapp-muted);
 }
@@ -1961,6 +2089,14 @@ textarea::placeholder {
   margin-top: 0.75rem;
 }
 
+:root[data-wapp-mobile] .wapp-toast-viewport {
+  right: max(0.75rem, var(--wapp-safe-area-right));
+  bottom: max(0.75rem, var(--wapp-safe-area-bottom));
+  left: max(0.75rem, var(--wapp-safe-area-left));
+  width: auto;
+  max-height: calc(var(--wapp-viewport-height) - 1.5rem);
+}
+
 @media (max-width: 640px) {
   .wapp-settings .wapp-list-row {
     display: grid;

package/src/web/theme.tsx

@@ -0,0 +1,147 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import type { ThemePreference } from "../contracts";
+import { appJson } from "./api-client";
+
+const THEME_STORAGE_KEY = "webapp.theme";
+const THEME_MEDIA_QUERY = "(prefers-color-scheme: dark)";
+
+export type ResolvedTheme = "light" | "dark";
+
+export interface WebAppThemeState {
+  preference: ThemePreference;
+  resolvedTheme: ResolvedTheme;
+  setPreference: (preference: ThemePreference) => void;
+  loading: boolean;
+  error?: Error;
+  retry: () => Promise<void>;
+}
+
+const ThemeContext = createContext<WebAppThemeState | null>(null);
+
+export function isThemePreference(value: unknown): value is ThemePreference {
+  return value === "system" || value === "light" || value === "dark";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readStoredPreference(): ThemePreference {
+  if (typeof window === "undefined") {
+    return "system";
+  }
+
+  const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
+  return isThemePreference(stored) ? stored : "system";
+}
+
+function readSystemTheme(): ResolvedTheme {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia(THEME_MEDIA_QUERY).matches ? "dark" : "light";
+}
+
+function parseThemeResponse(value: unknown): ThemePreference {
+  if (!isRecord(value) || !isThemePreference(value["theme"])) {
+    throw new Error("Theme preference response was invalid.");
+  }
+  return value["theme"];
+}
+
+function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+export function useTheme(): WebAppThemeState {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within the framework WebAppRoot.");
+  }
+  return context;
+}
+
+export function ThemeProvider({ userId, children }: { userId?: string; children: ReactNode }) {
+  const [preference, setPreferenceState] = useState<ThemePreference>(readStoredPreference);
+  const [systemTheme, setSystemTheme] = useState<ResolvedTheme>(readSystemTheme);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error>();
+  const requestIdRef = useRef(0);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+      return;
+    }
+
+    const query = window.matchMedia(THEME_MEDIA_QUERY);
+    const sync = () => setSystemTheme(query.matches ? "dark" : "light");
+    sync();
+    query.addEventListener("change", sync);
+    return () => query.removeEventListener("change", sync);
+  }, []);
+
+  const setPreference = useCallback((nextPreference: ThemePreference) => {
+    if (!isThemePreference(nextPreference)) {
+      throw new TypeError(`Unknown theme preference: ${String(nextPreference)}.`);
+    }
+    setPreferenceState(nextPreference);
+  }, []);
+
+  const resolvedTheme = preference === "system" ? systemTheme : preference;
+
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+
+    const root = document.documentElement;
+    root.classList.toggle("dark", resolvedTheme === "dark");
+    root.style.colorScheme = resolvedTheme;
+    root.dataset["theme"] = preference;
+    root.dataset["resolvedTheme"] = resolvedTheme;
+    window.localStorage.setItem(THEME_STORAGE_KEY, preference);
+  }, [preference, resolvedTheme]);
+
+  const retry = useCallback(async () => {
+    const requestId = requestIdRef.current + 1;
+    requestIdRef.current = requestId;
+    if (!userId) {
+      setLoading(false);
+      setError(undefined);
+      return;
+    }
+
+    setLoading(true);
+    setError(undefined);
+    try {
+      const response = await appJson<unknown>("/api/preferences/theme");
+      if (requestId !== requestIdRef.current) {
+        return;
+      }
+      setPreference(parseThemeResponse(response));
+    } catch (value) {
+      if (requestId === requestIdRef.current) {
+        setError(toError(value));
+      }
+    } finally {
+      if (requestId === requestIdRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [setPreference, userId]);
+
+  useEffect(() => {
+    void retry();
+  }, [retry]);
+
+  const state = useMemo<WebAppThemeState>(() => ({
+    preference,
+    resolvedTheme,
+    setPreference,
+    loading,
+    error,
+    retry,
+  }), [error, loading, preference, resolvedTheme, retry, setPreference]);
+
+  return <ThemeContext.Provider value={state}>{children}</ThemeContext.Provider>;
+}

package/src/web/toast.tsx

@@ -0,0 +1,218 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+export type ToastVariant = "success" | "error" | "warning" | "info";
+export type ToastId = string;
+
+export interface Toast {
+  id: ToastId;
+  message: string;
+  variant: ToastVariant;
+  duration: number;
+}
+
+export interface ToastOptions {
+  id?: ToastId;
+  duration?: number;
+}
+
+export interface ToastShowOptions extends ToastOptions {
+  variant?: ToastVariant;
+}
+
+export interface ToastService {
+  toasts: readonly Toast[];
+  show: (message: string, options?: ToastShowOptions) => ToastId;
+  success: (message: string, options?: ToastOptions) => ToastId;
+  error: (message: string, options?: ToastOptions) => ToastId;
+  warning: (message: string, options?: ToastOptions) => ToastId;
+  info: (message: string, options?: ToastOptions) => ToastId;
+  dismiss: (id: ToastId) => void;
+  dismissAll: () => void;
+}
+
+const DEFAULT_TOAST_DURATION_MS = 8_000;
+const MAX_TOASTS = 5;
+
+const ToastContext = createContext<ToastService | null>(null);
+
+function isToastVariant(value: unknown): value is ToastVariant {
+  return value === "success" || value === "error" || value === "warning" || value === "info";
+}
+
+function normalizeMessage(message: string): string {
+  if (typeof message !== "string") {
+    throw new TypeError("Toast messages must be strings.");
+  }
+  return message;
+}
+
+function normalizeId(id: ToastId | undefined, nextId: () => ToastId): ToastId {
+  if (id === undefined) {
+    return nextId();
+  }
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("Toast IDs must be non-empty strings.");
+  }
+  return id;
+}
+
+function normalizeDuration(duration: number | undefined): number {
+  if (duration === undefined) {
+    return DEFAULT_TOAST_DURATION_MS;
+  }
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new RangeError("Toast duration must be a finite, non-negative number.");
+  }
+  return duration;
+}
+
+function ToastViewport({ toasts, onDismiss }: { toasts: Toast[]; onDismiss: (id: ToastId) => void }) {
+  if (toasts.length === 0) {
+    return null;
+  }
+
+  return createPortal(
+    <div className="wapp-toast-viewport" role="region" aria-label="Notifications">
+      {toasts.map((toast) => {
+        const isError = toast.variant === "error";
+        return (
+          <div
+            key={toast.id}
+            className={`wapp-toast wapp-toast-${toast.variant}`}
+            data-toast-variant={toast.variant}
+            role={isError ? "alert" : "status"}
+            aria-live={isError ? "assertive" : "polite"}
+            aria-atomic="true"
+          >
+            <span className="wapp-toast-message">{toast.message}</span>
+            <button type="button" className="wapp-toast-dismiss" aria-label="Dismiss notification" onClick={() => onDismiss(toast.id)}>
+              ×
+            </button>
+          </div>
+        );
+      })}
+    </div>,
+    document.body,
+  );
+}
+
+export function useToast(): ToastService {
+  const context = useContext(ToastContext);
+  if (!context) {
+    throw new Error("useToast must be used within the framework webapp runtime.");
+  }
+  return context;
+}
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<Toast[]>([]);
+  const timersRef = useRef(new Map<ToastId, ReturnType<typeof setTimeout>>());
+  const nextIdRef = useRef(0);
+
+  const nextId = useCallback((): ToastId => {
+    nextIdRef.current += 1;
+    return `toast-${nextIdRef.current}`;
+  }, []);
+
+  const clearTimer = useCallback((id: ToastId) => {
+    const timer = timersRef.current.get(id);
+    if (timer === undefined) {
+      return;
+    }
+    clearTimeout(timer);
+    timersRef.current.delete(id);
+  }, []);
+
+  const dismiss = useCallback((id: ToastId) => {
+    clearTimer(id);
+    setToasts((current) => current.filter((toast) => toast.id !== id));
+  }, [clearTimer]);
+
+  const dismissAll = useCallback(() => {
+    for (const id of Array.from(timersRef.current.keys())) {
+      clearTimer(id);
+    }
+    setToasts([]);
+  }, [clearTimer]);
+
+  const scheduleDismiss = useCallback((toast: Toast) => {
+    clearTimer(toast.id);
+    if (toast.duration === 0) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      if (timersRef.current.get(toast.id) !== timer) {
+        return;
+      }
+      timersRef.current.delete(toast.id);
+      setToasts((current) => current.filter((item) => item.id !== toast.id));
+    }, toast.duration);
+    timersRef.current.set(toast.id, timer);
+  }, [clearTimer]);
+
+  const show = useCallback((message: string, options?: ToastShowOptions): ToastId => {
+    const normalizedMessage = normalizeMessage(message);
+    const variant = options?.variant ?? "info";
+    if (!isToastVariant(variant)) {
+      throw new TypeError(`Unknown toast variant: ${String(variant)}.`);
+    }
+    const id = normalizeId(options?.id, nextId);
+    const duration = normalizeDuration(options?.duration);
+    const toast: Toast = { id, message: normalizedMessage, variant, duration };
+
+    clearTimer(id);
+    setToasts((current) => {
+      const existingIndex = current.findIndex((item) => item.id === id);
+      if (existingIndex >= 0) {
+        const next = [...current];
+        next[existingIndex] = toast;
+        return next;
+      }
+      const next = [...current, toast];
+      return next.length > MAX_TOASTS ? next.slice(next.length - MAX_TOASTS) : next;
+    });
+    scheduleDismiss(toast);
+    return id;
+  }, [clearTimer, nextId, scheduleDismiss]);
+
+  useEffect(() => {
+    const activeIds = new Set(toasts.map((toast) => toast.id));
+    for (const id of timersRef.current.keys()) {
+      if (activeIds.has(id)) {
+        continue;
+      }
+      clearTimer(id);
+    }
+  }, [clearTimer, toasts]);
+
+  useEffect(() => () => {
+    for (const timer of timersRef.current.values()) {
+      clearTimeout(timer);
+    }
+    timersRef.current.clear();
+  }, []);
+
+  const success = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "success" }), [show]);
+  const error = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "error" }), [show]);
+  const warning = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "warning" }), [show]);
+  const info = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "info" }), [show]);
+  const service = useMemo<ToastService>(() => ({
+    toasts,
+    show,
+    success,
+    error,
+    warning,
+    info,
+    dismiss,
+    dismissAll,
+  }), [dismiss, dismissAll, error, info, show, success, toasts, warning]);
+
+  return (
+    <ToastContext.Provider value={service}>
+      {children}
+      <ToastViewport toasts={toasts} onDismiss={dismiss} />
+    </ToastContext.Provider>
+  );
+}

package/src/web/webapp-config.tsx

@@ -0,0 +1,117 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import type { WebAppConfigResponse } from "../contracts";
+import { appJson } from "./api-client";
+
+export interface WebAppConfigState {
+  config?: WebAppConfigResponse;
+  loading: boolean;
+  error?: Error;
+  refresh: () => Promise<void>;
+}
+
+const WebAppConfigContext = createContext<WebAppConfigState | null>(null);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isLogLevelName(value: unknown): boolean {
+  return value === "trace" || value === "debug" || value === "info" || value === "warn" || value === "error";
+}
+
+function isCurrentUser(value: unknown): boolean {
+  return isRecord(value)
+    && typeof value["id"] === "string"
+    && typeof value["username"] === "string"
+    && (value["role"] === "owner" || value["role"] === "admin" || value["role"] === "user")
+    && typeof value["isOwner"] === "boolean"
+    && typeof value["isAdmin"] === "boolean";
+}
+
+function hasBooleanFields(value: unknown, fields: readonly string[]): boolean {
+  return isRecord(value) && fields.every((field) => typeof value[field] === "boolean");
+}
+
+function isWebAppConfigResponse(value: unknown): value is WebAppConfigResponse {
+  return isRecord(value)
+    && typeof value["appName"] === "string"
+    && typeof value["version"] === "string"
+    && (value["currentUser"] === undefined || isCurrentUser(value["currentUser"]))
+    && hasBooleanFields(value["passkeyAuth"], [
+      "enabled",
+      "passkeyConfigured",
+      "passkeyDisabled",
+      "passkeyRequired",
+      "authenticated",
+      "bootstrapRequired",
+      "ownerPasskeySetupRequired",
+    ])
+    && hasBooleanFields(value["userManagement"], ["enabled", "canManageUsers"])
+    && isRecord(value["logLevel"])
+    && isLogLevelName(value["logLevel"]["level"])
+    && typeof value["logLevel"]["fromEnv"] === "boolean"
+    && hasBooleanFields(value["deviceAuth"], ["enabled"])
+    && hasBooleanFields(value["apiKeys"], ["enabled"]);
+}
+
+export function parseWebAppConfigResponse(value: unknown): WebAppConfigResponse {
+  if (!isWebAppConfigResponse(value)) {
+    throw new Error("Web app configuration response was invalid.");
+  }
+  return value;
+}
+
+function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+export function useWebAppConfig(consumer = "useWebAppConfig"): WebAppConfigState {
+  const context = useContext(WebAppConfigContext);
+  if (!context) {
+    throw new Error(`${consumer} must be used within the framework WebAppRoot.`);
+  }
+  return context;
+}
+
+export function WebAppConfigProvider({ children }: { children: ReactNode }) {
+  const [config, setConfig] = useState<WebAppConfigResponse>();
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error>();
+  const requestIdRef = useRef(0);
+
+  const refresh = useCallback(async () => {
+    const requestId = requestIdRef.current + 1;
+    requestIdRef.current = requestId;
+    setLoading(true);
+    setError(undefined);
+
+    try {
+      const response = parseWebAppConfigResponse(await appJson<unknown>("/api/config"));
+      if (requestId !== requestIdRef.current) {
+        return;
+      }
+      setConfig(response);
+    } catch (value) {
+      if (requestId === requestIdRef.current) {
+        setError(toError(value));
+      }
+    } finally {
+      if (requestId === requestIdRef.current) {
+        setLoading(false);
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const state = useMemo<WebAppConfigState>(() => ({
+    config,
+    loading,
+    error,
+    refresh,
+  }), [config, error, loading, refresh]);
+
+  return <WebAppConfigContext.Provider value={state}>{children}</WebAppConfigContext.Provider>;
+}