@hosty-sdk/app 0.11.0 → 0.13.0

package/README.md

@@ -13,7 +13,8 @@ npm install @hosty-sdk/app
 | `@hosty-sdk/app` | anywhere | status taxonomy, recovery decision, `hosty:auth-required` and `hosty:request-delegated-token` schemas, URL/env helpers |
 | `@hosty-sdk/app/server` | server only | Core revalidation with caching, cookie helpers, the app-code route factory, the app secrets client |
 | `@hosty-sdk/app/react` | client | `<AppIdentityBridge />` — probe, silent recovery, fallback cards |
-| `@hosty-sdk/app/embedder` | client | verified responders — launch-code recovery and delegated tokens — for anything that embeds Hosty apps |
+| `@hosty-sdk/app/embedder` | client | verified responders — launch-code recovery and delegated tokens — plus the theme sender half, for anything that embeds Hosty apps |
+| `@hosty-sdk/app/theme` | anywhere | the shell→app theme protocol: constants, `resolveTheme`, `applyTheme`, `parseShellThemeMessage`, `themeBootstrapScript` / `createThemeBootstrapScript` |
 
 Minimal Next.js wiring:
 
@@ -32,6 +33,38 @@ export const POST = createAppCodeRouteHandler({
 });
 ```
 
+Following the shell's theme — the launch parameters decide the theme a document loads with, the
+`hosty:shell-theme` post covers changes while the frame is up, and the bootstrap keeps the first
+paint right:
+
+```tsx
+// app/layout.tsx
+import { launchModeBootstrapScript } from "@hosty-sdk/app";
+import { HostLaunchBridge, HostThemeBridge } from "@hosty-sdk/app/react";
+import { themeBootstrapScript } from "@hosty-sdk/app/theme";
+
+<html suppressHydrationWarning>
+  <head>
+    <script dangerouslySetInnerHTML={{ __html: launchModeBootstrapScript }} />
+    <script dangerouslySetInnerHTML={{ __html: themeBootstrapScript }} />
+  </head>
+  <body>
+    <HostThemeBridge /> {/* followSystem={false} onTheme={setTheme} when the app runs its own provider (next-themes) */}
+    <HostLaunchBridge />
+  </body>
+</html>
+```
+
+An embedder declares the theme on every frame URL and posts changes to the frame's own origin:
+
+```ts
+import { appendThemeLaunchParams } from "@hosty-sdk/app/embedder";
+import { createShellThemeMessage } from "@hosty-sdk/app/theme";
+
+frame.src = appendThemeLaunchParams(launchUrl, theme, preference);
+frame.contentWindow.postMessage(createShellThemeMessage(theme, preference), frameOrigin);
+```
+
 App secrets — the Core-managed keychain for runtime-acquired credentials (OAuth tokens and the
 like), kept by Core outside the app's backed-up data directory:
 

package/dist/embedder.d.ts

@@ -1,3 +1,4 @@
+import { type HostyResolvedTheme, type HostyThemePreference } from "./theme.js";
 /** The three fields of a `message` event these parsers read. */
 export interface EmbedderMessage {
     data: unknown;
@@ -73,3 +74,11 @@ export declare function createReissueRateLimiter(minIntervalMs: number, now?: ()
     /** True when a reissue for this app is allowed now; records the attempt when allowed. */
     tryAcquire(appId: string): boolean;
 };
+/**
+ * Declares the theme an embedder is rendering in on the URL it is about to load into a frame — the
+ * workspace page, a settings tab, a panel. This is the channel that decides the theme the frame
+ * paints with; the `hosty:shell-theme` post (`createShellThemeMessage`) is for changes made while
+ * the frame is already up, because a post at the frame's `load` routinely lands before the app has
+ * a listener. Re-derived on every launch and every page switch, so it is never stale.
+ */
+export declare function appendThemeLaunchParams(redirectUri: string, theme: HostyResolvedTheme, preference: HostyThemePreference): string;

package/dist/embedder.js

@@ -13,6 +13,7 @@
 // to that frame's origin. Both requests are unauthenticated by design; what makes them safe is
 // that the embedder answers from facts about its own DOM rather than from what the frame claims.
 import { ASK_ASSISTANT_MAX_CHARS, ASK_ASSISTANT_TYPE, ATTENTION_TYPE, AUTH_REQUIRED_INTENT_TYPE, DELEGATED_TOKEN_REQUEST_TYPE, } from "./index.js";
+import { THEME_PARAM, THEME_PREFERENCE_PARAM } from "./theme.js";
 /**
  * Verifies that a `message` event is a genuine auth-required intent from the active app
  * frame. Every check is about facts only the embedder can know:
@@ -137,3 +138,16 @@ export function createReissueRateLimiter(minIntervalMs, now = Date.now) {
         },
     };
 }
+/**
+ * Declares the theme an embedder is rendering in on the URL it is about to load into a frame — the
+ * workspace page, a settings tab, a panel. This is the channel that decides the theme the frame
+ * paints with; the `hosty:shell-theme` post (`createShellThemeMessage`) is for changes made while
+ * the frame is already up, because a post at the frame's `load` routinely lands before the app has
+ * a listener. Re-derived on every launch and every page switch, so it is never stale.
+ */
+export function appendThemeLaunchParams(redirectUri, theme, preference) {
+    const url = new URL(redirectUri);
+    url.searchParams.set(THEME_PARAM, theme);
+    url.searchParams.set(THEME_PREFERENCE_PARAM, preference);
+    return url.toString();
+}

package/dist/react.d.ts

@@ -1,4 +1,6 @@
+import type { ReactNode } from "react";
 import { type AppLaunchMode, type AppSessionStatus } from "./index.js";
+import { type HostyResolvedTheme, type HostyThemePreference } from "./theme.js";
 /**
  * Tolerant probe reader: accepts both identity-route shapes in the fleet — a top-level
  * `status` (marketplace/telemetry) and a nested `appSession.status` (demo-app,
@@ -24,11 +26,28 @@ export declare function HostLaunchBridge(): null;
  * express the decision.
  */
 export declare function useLaunchMode(): AppLaunchMode | null;
+export type AppIdentityBridgeState = {
+    kind: "recovering";
+} | {
+    kind: "active";
+} | {
+    kind: "signin";
+    openUrl: string | null;
+    embedded: boolean;
+} | {
+    kind: "denied";
+} | {
+    kind: "unavailable";
+} | {
+    kind: "misconfigured";
+};
 export interface AppIdentityBridgeProps {
     /** Probe endpoint returning a session status + recovery params. */
     probePath?: string;
     /** Code-exchange endpoint. */
     appCodePath?: string;
+    /** Optional app-owned rendering, including loading and active content. Recovery remains SDK-owned. */
+    renderState?: (state: AppIdentityBridgeState) => ReactNode;
 }
 /**
  * Mount once at the top of the root layout body. On first load it consumes a `?code` from
@@ -37,4 +56,32 @@ export interface AppIdentityBridgeProps {
  * redirect through Core `/open` when standalone, and cards only in fallback/terminal states
  * — never a login UI while recovery is still running.
  */
-export declare function AppIdentityBridge({ probePath, appCodePath, }?: AppIdentityBridgeProps): import("react").JSX.Element | null;
+export declare function AppIdentityBridge({ probePath, appCodePath, renderState, }?: AppIdentityBridgeProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+export interface HostThemeBridgeProps {
+    /**
+     * Whether the operating system decides the theme while no shell has spoken — `true` unless the
+     * app runs its own theme provider for standalone use (next-themes), which owns that case and
+     * whose stored choice the host must not overwrite. Pass the same value to
+     * `createThemeBootstrapScript`.
+     */
+    followSystem?: boolean;
+    /**
+     * Runs after every application, with the theme just applied. An app that also runs its own
+     * theme provider hands that provider the shell's decision here; an app that only follows the
+     * host needs nothing.
+     */
+    onTheme?: (theme: HostyResolvedTheme, preference: HostyThemePreference) => void;
+}
+/**
+ * Mount once in the root layout. Applies the theme from the launch parameters, the value stored
+ * for this tab, or the operating system — in that order — persists a declared one, cleans the
+ * parameters out of the URL so a copied link cannot carry a shell's presentation into a plain
+ * browser tab, and then follows `hosty:shell-theme` posts from the parent for the life of the
+ * document.
+ *
+ * Pair it with `themeBootstrapScript` in the head: this effect runs after first paint, so without
+ * the script a document paints in the default theme for a frame before it is corrected. The system
+ * preference is followed live only while no shell has spoken — a declared theme is a choice, and a
+ * choice is not overruled by the OS.
+ */
+export declare function HostThemeBridge({ followSystem, onTheme }?: HostThemeBridgeProps): null;

package/dist/react.js

@@ -3,8 +3,9 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 // React slice: the client identity bridge — probe, silent recovery, and the fallback
 // cards. Prop-less by design: the app id and browser-reachable Core origin arrive in the
 // probe response's `recovery` field (request-time values, never build-time props).
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { buildCoreOpenUrl, decideRecoveryAction, detectLaunchMode, normalizeLaunchMode, readRecoveryParams, resolveLaunchMode, LAUNCH_MODE_ATTRIBUTE, LAUNCH_MODE_PARAM, LAUNCH_MODE_STORAGE_KEY, } from "./index.js";
+import { applyTheme, parseShellThemeMessage, resolveTheme, THEME_PARAM, THEME_PREFERENCE_PARAM, THEME_PREFERENCE_STORAGE_KEY, THEME_STORAGE_KEY, } from "./theme.js";
 // Once-per-tab guard so a standalone app that returns from Core still unauthorized does
 // not bounce through /open forever. Cleared on a successful code exchange.
 const RECOVERY_GUARD_KEY = "hosty.auth.recovery-attempted";
@@ -147,8 +148,11 @@ export function useLaunchMode() {
  * redirect through Core `/open` when standalone, and cards only in fallback/terminal states
  * — never a login UI while recovery is still running.
  */
-export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", } = {}) {
-    const [ui, setUi] = useState({ kind: "hidden" });
+export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", renderState, } = {}) {
+    const [ui, setUi] = useState({ kind: "recovering" });
+    // A launch code is single-use. Strict Mode replays the effect after the URL is cleaned;
+    // keep its exchange alive and let the replacement effect await the same response.
+    const exchangeRef = useRef(null);
     useEffect(() => {
         let cancelled = false;
         const controller = new AbortController();
@@ -197,7 +201,7 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 });
             switch (action.kind) {
                 case "none":
-                    setUi({ kind: "hidden" });
+                    setUi({ kind: "active" });
                     return;
                 case "post-auth-required": {
                     // The payload carries no secret, so targetOrigin "*" is safe — the Shell verifies
@@ -234,12 +238,18 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         if (code) {
             url.searchParams.delete("code");
             window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
-            void fetch(appCodePath, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ code }),
-                signal: controller.signal,
-            })
+            exchangeRef.current = {
+                path: appCodePath,
+                response: fetch(appCodePath, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ code }),
+                }),
+            };
+        }
+        const exchange = exchangeRef.current;
+        if (exchange && exchange.path === appCodePath) {
+            void exchange.response
                 .then((response) => {
                 if (cancelled) {
                     return;
@@ -249,11 +259,13 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                     window.location.reload();
                 }
                 else {
+                    exchangeRef.current = null;
                     void probeAndRecover();
                 }
             })
                 .catch(() => {
                 if (!cancelled) {
+                    exchangeRef.current = null;
                     void probeAndRecover();
                 }
             });
@@ -266,7 +278,9 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
             controller.abort();
         };
     }, [probePath, appCodePath]);
-    if (ui.kind === "hidden") {
+    if (renderState)
+        return renderState(ui);
+    if (ui.kind === "recovering" || ui.kind === "active") {
         return null;
     }
     return (_jsx("div", { role: "status", style: barStyle, children: ui.kind === "signin" ? (_jsxs(_Fragment, { children: [_jsx("span", { children: "Your Hosty session ended." }), ui.openUrl ? (_jsx("a", { href: ui.openUrl, ...(ui.embedded ? { target: "_blank", rel: "noopener noreferrer" } : {}), style: actionStyle, children: "Sign in via Hosty" })) : (_jsx("span", { children: "Open this app from the machine running Hosty, or configure a public origin." }))] })) : ui.kind === "denied" ? (_jsx("span", { children: "You are signed in to Hosty but are not allowed to use this app." })) : ui.kind === "misconfigured" ? (_jsx("span", { children: "This app is not configured correctly on the host. Contact the administrator." })) : (_jsxs(_Fragment, { children: [_jsx("span", { children: "Can\u2019t reach Hosty right now." }), _jsx("button", { type: "button", onClick: () => window.location.reload(), style: actionStyle, children: "Retry" })] })) }));
@@ -299,3 +313,101 @@ const actionStyle = {
     fontWeight: 650,
     textDecoration: "none",
 };
+function readStoredTheme(key) {
+    try {
+        return window.sessionStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function writeStoredTheme(theme, preference) {
+    try {
+        window.sessionStorage.setItem(THEME_STORAGE_KEY, theme);
+        window.sessionStorage.setItem(THEME_PREFERENCE_STORAGE_KEY, preference);
+    }
+    catch {
+        // sessionStorage may be blocked. The shell re-declares the theme on every launch and on every
+        // page switch it drives, so only app-internal navigation loses it.
+    }
+}
+function clearStoredTheme() {
+    try {
+        window.sessionStorage.removeItem(THEME_STORAGE_KEY);
+        window.sessionStorage.removeItem(THEME_PREFERENCE_STORAGE_KEY);
+    }
+    catch {
+        // Same as above — nothing to keep.
+    }
+}
+/**
+ * Mount once in the root layout. Applies the theme from the launch parameters, the value stored
+ * for this tab, or the operating system — in that order — persists a declared one, cleans the
+ * parameters out of the URL so a copied link cannot carry a shell's presentation into a plain
+ * browser tab, and then follows `hosty:shell-theme` posts from the parent for the life of the
+ * document.
+ *
+ * Pair it with `themeBootstrapScript` in the head: this effect runs after first paint, so without
+ * the script a document paints in the default theme for a frame before it is corrected. The system
+ * preference is followed live only while no shell has spoken — a declared theme is a choice, and a
+ * choice is not overruled by the OS.
+ */
+export function HostThemeBridge({ followSystem = true, onTheme } = {}) {
+    const onThemeRef = useRef(onTheme);
+    useEffect(() => {
+        onThemeRef.current = onTheme;
+    }, [onTheme]);
+    useEffect(() => {
+        const root = document.documentElement;
+        const system = window.matchMedia("(prefers-color-scheme: dark)");
+        const apply = (theme, preference, declared) => {
+            applyTheme(root, theme, preference);
+            if (declared) {
+                writeStoredTheme(theme, preference);
+            }
+            else {
+                clearStoredTheme();
+            }
+            onThemeRef.current?.(theme, preference);
+        };
+        const url = new URL(window.location.href);
+        const resolution = resolveTheme({
+            param: url.searchParams.get(THEME_PARAM),
+            preferenceParam: url.searchParams.get(THEME_PREFERENCE_PARAM),
+            stored: readStoredTheme(THEME_STORAGE_KEY),
+            storedPreference: readStoredTheme(THEME_PREFERENCE_STORAGE_KEY),
+            systemPrefersDark: system.matches,
+        });
+        let declared = resolution.source !== "system";
+        if (declared || followSystem) {
+            apply(resolution.theme, resolution.preference, declared);
+        }
+        // Cleaned whenever present, including an unrecognized value: a parameter this app ignored
+        // must not survive into a link someone copies.
+        if (url.searchParams.has(THEME_PARAM) || url.searchParams.has(THEME_PREFERENCE_PARAM)) {
+            url.searchParams.delete(THEME_PARAM);
+            url.searchParams.delete(THEME_PREFERENCE_PARAM);
+            window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
+        }
+        const handleMessage = (event) => {
+            const message = parseShellThemeMessage(event, window);
+            if (!message) {
+                return;
+            }
+            declared = true;
+            apply(message.theme, message.preference, true);
+        };
+        const handleSystemChange = () => {
+            if (!declared && followSystem) {
+                apply(system.matches ? "dark" : "light", "system", false);
+            }
+        };
+        window.addEventListener("message", handleMessage);
+        system.addEventListener("change", handleSystemChange);
+        return () => {
+            window.removeEventListener("message", handleMessage);
+            system.removeEventListener("change", handleSystemChange);
+        };
+    }, []);
+    return null;
+}

package/dist/theme.d.ts

@@ -0,0 +1,104 @@
+export type HostyResolvedTheme = "light" | "dark";
+/** What the operator chose in the shell. `system` means the shell follows the OS, and so does the app. */
+export type HostyThemePreference = "light" | "dark" | "system";
+/** The message a shell posts its frame on every theme change, and again when the frame loads. */
+export declare const SHELL_THEME_TYPE = "hosty:shell-theme";
+/** The launch parameters a shell appends to every URL it loads into a frame. */
+export declare const THEME_PARAM = "hosty_theme";
+export declare const THEME_PREFERENCE_PARAM = "hosty_theme_preference";
+/**
+ * Where a declared theme is kept for the life of the tab. App-internal navigation carries no
+ * parameter and must not lose the theme; a tab the app opens itself inherits the storage, which
+ * is the one accepted leak — no first-party app opens one.
+ */
+export declare const THEME_STORAGE_KEY = "hosty.theme.resolved";
+export declare const THEME_PREFERENCE_STORAGE_KEY = "hosty.theme.preference";
+/** The root attributes written beside the class, for CSS or scripts that key on them. */
+export declare const THEME_ATTRIBUTE = "data-hosty-theme";
+export declare const THEME_PREFERENCE_ATTRIBUTE = "data-hosty-theme-preference";
+/** The root class every Hosty app's `dark:` variant keys on. */
+export declare const DARK_THEME_CLASS = "dark";
+export interface ShellThemeMessage {
+    type: typeof SHELL_THEME_TYPE;
+    theme: HostyResolvedTheme;
+    preference: HostyThemePreference;
+}
+export declare function createShellThemeMessage(theme: HostyResolvedTheme, preference: HostyThemePreference): ShellThemeMessage;
+export declare function normalizeResolvedTheme(value: unknown): HostyResolvedTheme | null;
+export declare function normalizeThemePreference(value: unknown): HostyThemePreference | null;
+export type ThemeSource = "param" | "stored" | "system";
+export interface ThemeResolution {
+    theme: HostyResolvedTheme;
+    preference: HostyThemePreference;
+    /** Which channel decided. `system` is the only one no shell spoke through. */
+    source: ThemeSource;
+}
+/**
+ * Resolves the theme a document paints with, in explicit precedence: the launch parameter a
+ * shell just sent, then the value persisted for this tab, then the operating system.
+ *
+ * The parameter outranks storage because a shell rewrites it on every launch and every page
+ * switch it drives, so it is the one channel that cannot go stale. An unrecognized value on
+ * either channel is ignored rather than honoured — a newer shell must degrade an older app to
+ * what it did before, never to a theme it cannot render. A preference that arrives without a
+ * recognizable value defaults to the theme itself: a shell that resolved `dark` and said nothing
+ * more chose dark.
+ */
+export declare function resolveTheme(input: {
+    param?: string | null;
+    preferenceParam?: string | null;
+    stored?: string | null;
+    storedPreference?: string | null;
+    systemPrefersDark: boolean;
+}): ThemeResolution;
+/** The slice of the document root the bridge writes to. */
+export interface ThemeRoot {
+    classList: {
+        toggle(token: string, force?: boolean): unknown;
+    };
+    style: {
+        colorScheme: string;
+    };
+    setAttribute(name: string, value: string): void;
+}
+/**
+ * Writes one theme to the root: the `dark` class Tailwind keys on, `color-scheme` so native
+ * controls and scrollbars follow, and the two attributes for anything that wants the words.
+ */
+export declare function applyTheme(root: ThemeRoot, theme: HostyResolvedTheme, preference: HostyThemePreference): void;
+/**
+ * Reads a `hosty:shell-theme` message, accepting it from the parent frame alone.
+ *
+ * `event.source === window.parent` is set by the browser and is the trustworthy gate. The parent's
+ * origin is deliberately not checked: an app learns which origin embeds it from messages like this
+ * one, so it cannot be used to pre-filter them, and `document.referrer` — what some copies used —
+ * goes stale the moment the app reloads itself. Theme is not sensitive; the source check is
+ * sufficient. Not embedded at all means no parent to hear from, so nothing is accepted.
+ */
+export declare function parseShellThemeMessage(event: {
+    data: unknown;
+    source: unknown;
+}, win: Pick<Window, "parent" | "self">): {
+    theme: HostyResolvedTheme;
+    preference: HostyThemePreference;
+} | null;
+/**
+ * The pre-hydration bootstrap: applies the theme from the same precedence `resolveTheme`
+ * implements, so a document never paints in the wrong theme before React can correct it. Mount
+ * it as an inline `<script>` in the document head.
+ *
+ * `followSystem` is the same switch `HostThemeBridge` takes. An app that runs its own theme
+ * provider for standalone use (next-themes) passes `false` here and there: the host's bootstrap
+ * then applies only a theme a shell declared and otherwise leaves the root to the provider, whose
+ * own stored choice must not be overwritten by the operating system's.
+ *
+ * A parameter is persisted here as well as in the bridge, on the launch mode's precedent, so a
+ * reload between this script and hydration cannot lose it. It does not clean the parameter out of
+ * the URL — that is `HostThemeBridge`'s job: a `history.replaceState` before hydration is a
+ * router's business, not a paint-blocking script's.
+ */
+export declare function createThemeBootstrapScript(options?: {
+    followSystem?: boolean;
+}): string;
+/** The bootstrap for an app that follows the host and otherwise the operating system — the common case. */
+export declare const themeBootstrapScript: string;

package/dist/theme.js

@@ -0,0 +1,159 @@
+// Theme slice: the protocol by which a shell hands an embedded app the theme it is rendering in,
+// and the app half that applies it. Pure — no React, and no DOM beyond the narrow shapes the
+// functions take — so one precedence runs in the pre-hydration bootstrap, in the React bridge,
+// and in the tests.
+//
+// The design answers one failure. A shell posts `hosty:shell-theme` when its iframe fires `load`,
+// and that post routinely lands before the app's effect has attached a listener, so it is lost.
+// The copies this replaced then read whatever an earlier post had stored for the tab: one session
+// in dark pinned an app dark for the life of the tab, whatever the shell was set to (telemetry-ui,
+// 2026-09-07). So the launch parameters — which travel with the document and cannot be missed —
+// decide the theme a document loads with; the post is for changes made while the frame is up.
+/** The message a shell posts its frame on every theme change, and again when the frame loads. */
+export const SHELL_THEME_TYPE = "hosty:shell-theme";
+/** The launch parameters a shell appends to every URL it loads into a frame. */
+export const THEME_PARAM = "hosty_theme";
+export const THEME_PREFERENCE_PARAM = "hosty_theme_preference";
+/**
+ * Where a declared theme is kept for the life of the tab. App-internal navigation carries no
+ * parameter and must not lose the theme; a tab the app opens itself inherits the storage, which
+ * is the one accepted leak — no first-party app opens one.
+ */
+export const THEME_STORAGE_KEY = "hosty.theme.resolved";
+export const THEME_PREFERENCE_STORAGE_KEY = "hosty.theme.preference";
+/** The root attributes written beside the class, for CSS or scripts that key on them. */
+export const THEME_ATTRIBUTE = "data-hosty-theme";
+export const THEME_PREFERENCE_ATTRIBUTE = "data-hosty-theme-preference";
+/** The root class every Hosty app's `dark:` variant keys on. */
+export const DARK_THEME_CLASS = "dark";
+export function createShellThemeMessage(theme, preference) {
+    return { type: SHELL_THEME_TYPE, theme, preference };
+}
+export function normalizeResolvedTheme(value) {
+    return value === "light" || value === "dark" ? value : null;
+}
+export function normalizeThemePreference(value) {
+    return value === "light" || value === "dark" || value === "system" ? value : null;
+}
+/**
+ * Resolves the theme a document paints with, in explicit precedence: the launch parameter a
+ * shell just sent, then the value persisted for this tab, then the operating system.
+ *
+ * The parameter outranks storage because a shell rewrites it on every launch and every page
+ * switch it drives, so it is the one channel that cannot go stale. An unrecognized value on
+ * either channel is ignored rather than honoured — a newer shell must degrade an older app to
+ * what it did before, never to a theme it cannot render. A preference that arrives without a
+ * recognizable value defaults to the theme itself: a shell that resolved `dark` and said nothing
+ * more chose dark.
+ */
+export function resolveTheme(input) {
+    const declared = normalizeResolvedTheme(input.param);
+    if (declared) {
+        return { theme: declared, preference: normalizeThemePreference(input.preferenceParam) ?? declared, source: "param" };
+    }
+    const stored = normalizeResolvedTheme(input.stored);
+    if (stored) {
+        return { theme: stored, preference: normalizeThemePreference(input.storedPreference) ?? stored, source: "stored" };
+    }
+    return { theme: input.systemPrefersDark ? "dark" : "light", preference: "system", source: "system" };
+}
+/**
+ * Writes one theme to the root: the `dark` class Tailwind keys on, `color-scheme` so native
+ * controls and scrollbars follow, and the two attributes for anything that wants the words.
+ */
+export function applyTheme(root, theme, preference) {
+    root.classList.toggle(DARK_THEME_CLASS, theme === "dark");
+    root.style.colorScheme = theme;
+    root.setAttribute(THEME_ATTRIBUTE, theme);
+    root.setAttribute(THEME_PREFERENCE_ATTRIBUTE, preference);
+}
+/**
+ * Reads a `hosty:shell-theme` message, accepting it from the parent frame alone.
+ *
+ * `event.source === window.parent` is set by the browser and is the trustworthy gate. The parent's
+ * origin is deliberately not checked: an app learns which origin embeds it from messages like this
+ * one, so it cannot be used to pre-filter them, and `document.referrer` — what some copies used —
+ * goes stale the moment the app reloads itself. Theme is not sensitive; the source check is
+ * sufficient. Not embedded at all means no parent to hear from, so nothing is accepted.
+ */
+export function parseShellThemeMessage(event, win) {
+    if (win.parent === win.self || event.source !== win.parent) {
+        return null;
+    }
+    const data = event.data;
+    if (!data || typeof data !== "object" || data.type !== SHELL_THEME_TYPE) {
+        return null;
+    }
+    const theme = normalizeResolvedTheme(data.theme);
+    if (!theme) {
+        return null;
+    }
+    return { theme, preference: normalizeThemePreference(data.preference) ?? theme };
+}
+/**
+ * The pre-hydration bootstrap: applies the theme from the same precedence `resolveTheme`
+ * implements, so a document never paints in the wrong theme before React can correct it. Mount
+ * it as an inline `<script>` in the document head.
+ *
+ * `followSystem` is the same switch `HostThemeBridge` takes. An app that runs its own theme
+ * provider for standalone use (next-themes) passes `false` here and there: the host's bootstrap
+ * then applies only a theme a shell declared and otherwise leaves the root to the provider, whose
+ * own stored choice must not be overwritten by the operating system's.
+ *
+ * A parameter is persisted here as well as in the bridge, on the launch mode's precedent, so a
+ * reload between this script and hydration cannot lose it. It does not clean the parameter out of
+ * the URL — that is `HostThemeBridge`'s job: a `history.replaceState` before hydration is a
+ * router's business, not a paint-blocking script's.
+ */
+export function createThemeBootstrapScript(options = {}) {
+    const followSystem = options.followSystem !== false;
+    return `
+(() => {
+  const themes = ["light", "dark"];
+  const preferences = ["light", "dark", "system"];
+  const pick = (known, value) => (known.indexOf(value) >= 0 ? value : null);
+  const read = (key) => {
+    try {
+      return window.sessionStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  };
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const declared = pick(themes, params.get(${JSON.stringify(THEME_PARAM)}));
+    let theme = declared;
+    let preference = null;
+    if (declared) {
+      preference = pick(preferences, params.get(${JSON.stringify(THEME_PREFERENCE_PARAM)})) || declared;
+    } else {
+      const stored = pick(themes, read(${JSON.stringify(THEME_STORAGE_KEY)}));
+      if (stored) {
+        theme = stored;
+        preference = pick(preferences, read(${JSON.stringify(THEME_PREFERENCE_STORAGE_KEY)})) || stored;
+      }
+    }
+    if (!theme) {
+      if (!${JSON.stringify(followSystem)}) {
+        return;
+      }
+      theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+      preference = "system";
+    }
+    const root = document.documentElement;
+    root.classList.toggle(${JSON.stringify(DARK_THEME_CLASS)}, theme === "dark");
+    root.style.colorScheme = theme;
+    root.setAttribute(${JSON.stringify(THEME_ATTRIBUTE)}, theme);
+    root.setAttribute(${JSON.stringify(THEME_PREFERENCE_ATTRIBUTE)}, preference);
+    if (declared) {
+      try {
+        window.sessionStorage.setItem(${JSON.stringify(THEME_STORAGE_KEY)}, theme);
+        window.sessionStorage.setItem(${JSON.stringify(THEME_PREFERENCE_STORAGE_KEY)}, preference);
+      } catch {}
+    }
+  } catch {}
+})();
+`;
+}
+/** The bootstrap for an app that follows the host and otherwise the operating system — the common case. */
+export const themeBootstrapScript = createThemeBootstrapScript();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -32,6 +32,10 @@
     "./embedder": {
       "types": "./dist/embedder.d.ts",
       "default": "./dist/embedder.js"
+    },
+    "./theme": {
+      "types": "./dist/theme.d.ts",
+      "default": "./dist/theme.js"
     }
   },
   "scripts": {
@@ -42,7 +46,7 @@
     "server-only": "^0.0.1"
   },
   "peerDependencies": {
-    "next": "^16.2.10",
+    "next": "^16.3.4",
     "react": "^19.2.8"
   },
   "peerDependenciesMeta": {
@@ -57,7 +61,7 @@
     "@types/node": "^24",
     "@types/react": "^19.2.18",
     "typescript": "^6",
-    "vitest": "^4"
+    "vitest": "^5.0.0"
   },
   "repository": {
     "type": "git",