@pablozaiden/webapp 0.6.0 → 0.6.2

package/README.md

@@ -22,8 +22,8 @@ Each application package must declare `react` and `react-dom`; they are peer dep
 
 | Export | Use |
 | --- | --- |
-| `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, SQLite store |
-| `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, sidebar types, UI controls, realtime hooks |
+| `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, request-origin helpers, SQLite store |
+| `@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/auth.md

@@ -74,8 +74,9 @@ The same normalized request context drives expected same-origin origins,
 WebSocket origin checks, passkey expected origins and RP IDs, the `Secure`
 cookie attribute, cookie paths, setup links, and device/discovery URLs.
 `{PREFIX}_PUBLIC_BASE_URL` is authoritative for origin, hostname, and secure
-state even when forwarded headers are present; trusted prefixes remain
-policy-controlled for path-bearing cookies and links.
+state even when forwarded headers are present. It must be an origin-only
+absolute `http` or `https` URL; trusted prefixes remain policy-controlled for
+path-bearing cookies and links.
 
 Trust mode is a deployment boundary setting, not a way to trust arbitrary
 client input. The reverse proxy must strip client-supplied forwarded headers
@@ -84,3 +85,10 @@ single-value headers. Do not expose the application directly to untrusted
 clients when trust mode is enabled. This release does not implement a
 proxy-address allowlist, so the network boundary and proxy sanitization are
 required.
+
+Applications that generate their own public URLs should use
+`getRequestOriginInfo` or `getRequestBaseUrl` from
+`@pablozaiden/webapp/server` with the server's runtime config instead of
+parsing `{PREFIX}_PUBLIC_BASE_URL` independently. The framework validates the
+configured public base URL during startup and applies the same trusted-proxy
+policy used by its authentication and origin checks.

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
@@ -186,7 +289,7 @@ The app configures an uppercase `envPrefix`; the framework reads only variables
 | `{PREFIX}_TRUST_PROXY` | `false` | Explicitly trust the documented `X-Forwarded-*` headers; keep disabled for direct deployments |
 | `{PREFIX}_TRUST_PROXY_HEADERS` | `proto,host,prefix` when enabled | Comma-separated subset of supported forwarded values: `proto`, `host`, `prefix` |
 | `{PREFIX}_TRUST_PROXY_CHAIN` | `first` | Select the left-most (`first`) or right-most (`last`) non-empty value from comma-separated forwarded headers |
-| `{PREFIX}_PUBLIC_BASE_URL` | request origin | Authoritative external origin for auth/device URLs; it overrides forwarded protocol and host values |
+| `{PREFIX}_PUBLIC_BASE_URL` | request origin | Authoritative absolute `http` or `https` origin (without a path, query, or fragment) for auth/device URLs; it overrides forwarded protocol and host values |
 | `{PREFIX}_AUTH_ISSUER` | `urn:{prefix}:webapp` | JWT issuer override |
 
 The configured data directory contains the framework-owned

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.0",
+  "version": "0.6.2",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,9 @@
     "build": "bun run tsc && 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",
+    "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",
     "tsc": "mkdir -p .cache/tsc && bunx tsc --noEmit --pretty false --incremental --tsBuildInfoFile .cache/tsc/build.tsbuildinfo"
   },
   "dependencies": {

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/index.ts

@@ -3,6 +3,7 @@ export * from "./routes";
 export * from "./route-catalog";
 export * from "./responses";
 export * from "./create-web-app-server";
+export { getRequestBaseUrl, getRequestOriginInfo, type RequestOriginInfo } from "./auth/request-origin";
 export * from "./auth/store";
 export * from "./auth/sqlite-store";
 export * from "./realtime/bus";

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 {
@@ -84,6 +99,30 @@ function parseBoolean(raw: string | undefined, fallback: boolean, name: string):
   throw new Error(`${name} must be true or false; received "${raw}"`);
 }
 
+function parsePublicBaseUrl(raw: string | undefined, name: string): string | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`${name} must be a valid absolute http(s) origin; received "${raw}"`);
+  }
+  if (
+    (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+    parsed.username ||
+    parsed.password ||
+    parsed.origin === "null" ||
+    parsed.pathname !== "/" ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(`${name} must be a valid absolute http(s) origin; received "${raw}"`);
+  }
+  return parsed.origin;
+}
+
 function parseTrustProxyHeaders(raw: string | undefined, enabled: boolean, name: string): TrustProxyHeader[] {
   if (raw === undefined) {
     return enabled ? [...TRUST_PROXY_HEADERS] : [];
@@ -122,6 +161,7 @@ export function readRuntimeConfig(input: {
   const envPrefix = assertEnvPrefix(input.envPrefix);
   const logLevelRaw = readEnv(envPrefix, "LOG_LEVEL");
   const logLevel = parseLogLevel(logLevelRaw, input.defaultLogLevel ?? "info", envName(envPrefix, "LOG_LEVEL"));
+  const publicBaseUrl = parsePublicBaseUrl(readEnv(envPrefix, "PUBLIC_BASE_URL"), envName(envPrefix, "PUBLIC_BASE_URL"));
   const trustProxyEnabled = parseBoolean(readEnv(envPrefix, "TRUST_PROXY"), false, envName(envPrefix, "TRUST_PROXY"));
   const trustProxy = {
     enabled: trustProxyEnabled,
@@ -138,7 +178,7 @@ export function readRuntimeConfig(input: {
     logLevelFromEnv: Boolean(logLevelRaw),
     passkeyDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_PASSKEY")),
     sameOriginDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_SAME_ORIGIN_CHECK")),
-    publicBaseUrl: readEnv(envPrefix, "PUBLIC_BASE_URL"),
+    publicBaseUrl,
     authIssuer: readEnv(envPrefix, "AUTH_ISSUER"),
     trustProxy,
     development: process.env["NODE_ENV"] === "production" ? false : { hmr: true, console: true },

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;
 }