@hosty-sdk/app 0.21.2 → 0.23.0

package/README.md

@@ -11,37 +11,75 @@ 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, Core popup/navigation recovery, content gate |
+| `@hosty-sdk/app/react` | client | `<HostyOverlay />` — shared loading, identity, required setup and recovery UI; legacy bridges remain available |
+| `@hosty-sdk/app/session/server` | server | Framework-neutral session response adapter for authenticated Node servers |
 | `@hosty-sdk/app/embedder` | client | theme sender and legacy embedder message parsers; Shell no longer mints app credentials |
 | `@hosty-sdk/app/browser-auth` | client | `appFetch` for app-local API requests and bound Core popup sign-in |
 | `@hosty-sdk/app/providers` | anywhere | permission state, provider descriptors, speech contract types |
 | `@hosty-sdk/app/providers/server` | server only | `ProviderClient`: discovery, speech recognition, assistant handoffs and live credential validation |
 | `@hosty-sdk/app/theme` | anywhere | the shell→app theme protocol: constants, `resolveTheme`, `applyTheme`, `parseShellThemeMessage`, `themeBootstrapScript` / `createThemeBootstrapScript` |
 
-Minimal Next.js wiring:
+Minimal Next.js wiring (the configuration object stays server-side):
 
 ```tsx
-// app/layout.tsx
-import { AppIdentityBridge } from "@hosty-sdk/app/react";
-// wrap protected client content: <AppIdentityBridge>{children}</AppIdentityBridge>
+// app/layout.tsx — inside the body and the existing theme/launch providers
+import { HostyOverlay } from "@hosty-sdk/app/react";
+// <HostyOverlay>{children}</HostyOverlay>
 
-// Reuse an active probe that already returns the app's session fields:
-// <AppIdentityBridge probePath="/api/auth/session" onSession={seedSessionCache}>
-//   {children}
-// </AppIdentityBridge>
-// seedSessionCache receives unknown JSON; validate app-specific fields before caching.
-// The callback runs before children mount, only for a successful active probe.
+// lib/hosty.ts
+export const hostyConfig = {
+  appIdFallback: "com.example.my-app",
+  identityCookieName: "my_app_hosty_identity",
+};
 
-// app/api/auth/app-code/route.ts
-import { createAppCodeRouteHandler } from "@hosty-sdk/app/server";
+// app/api/hosty/session/route.ts
+import { createHostySessionRouteHandler } from "@hosty-sdk/app/server";
+import { hostyConfig } from "@/lib/hosty";
 export const dynamic = "force-dynamic";
 export const runtime = "nodejs";
-export const POST = createAppCodeRouteHandler({
-  appIdFallback: "com.example.my-app",
-  identityCookieName: "my_app_hosty_identity",
-});
+export const GET = createHostySessionRouteHandler(hostyConfig);
+// Administrator-only app: pass { administratorOnly: true } as the second argument.
+
+// app/api/auth/app-code/route.ts
+import { createAppCodeRouteHandler } from "@hosty-sdk/app/server";
+import { hostyConfig } from "@/lib/hosty";
+export const POST = createAppCodeRouteHandler(hostyConfig);
 ```
 
+Replace the protected scope's `AppIdentityBridge`, `AppActivityBridge`, custom sign-in rendering
+and `MissingPermissionsNotice` with one `HostyOverlay`. Keep public routes outside that scope.
+Existing launch/theme bridges and bootstrap scripts stay in place. The only optional overlay props
+are `probePath` and `appCodePath` for existing route names; it has no visual customization API.
+API routes and server-rendered data still enforce their own authorization. The overlay delays
+protected client mounting; it is not a server data-access boundary.
+
+The session adapter resolves identity and checks the app's declared required permissions together.
+Only an administrator receives permission details and a Core review action; a regular user sees an
+administrator-setup explanation without buttons. Optional permissions do not block the app.
+A missing setup capability on Core displays a compatibility state instead of exposing content.
+Keep service credentials on the server and use `appFetch` for app-local browser requests.
+
+For a plain Node server, call `createHostySessionResponse(validatedSession, recovery, options)` from
+`@hosty-sdk/app/session/server` and forward its response. Pass a server-validated session, never an
+identity supplied by the request body. Harness is the in-repository example. Shell retains its
+HttpOnly-only code exchange; the shared coordinator also accepts a successful exchange without a
+browser-readable token.
+
+After first mount, blocked content and app portals become hidden and inert while the component tree
+remains mounted. Same-user renewal restores it. A different stable user ID reloads the app document
+and refuses to replay old pending requests. `APP_SESSION_RESTORED` from `/browser-auth` is an optional
+DOM notification with `detail.userId`; it contains no credential. There is no generic draft persistence
+across reloads or cache-clearing framework. Existing identity idle/absolute lifetimes and fixed
+privileged activity windows still apply.
+
+Compatible SDK updates change standard presentation and recovery after a dependency update and
+rebuild, without editing this wiring. New mandatory Core capabilities can require upgrading Core.
+`node packages/app-sdk/scripts/check-overlay-upgrade.mjs` checks the published export layout using
+identical consumer source before and after a dependency-only presentation revision (run SDK build first).
+
+Legacy `AppIdentityBridge` exports, `renderState` and `onSession` remain compatible for consumers
+that have not migrated. See [Hosty Overlay](../../docs/features/hosty-overlay/feature.md) for behavior.
+
 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:
@@ -138,23 +176,34 @@ Set `publicOrigin` to the Core-injected public origin for your UI endpoint when
 exposes an internal request URL. The adapter checks browser `Origin` against this configured
 value, or against the request URL when it is omitted; forwarded-host headers are never trusted.
 
-The default dialog includes runtime selection, settings and a link to Core confirmation:
+The default dialog prepares installation and links to Core confirmation:
 
 ```tsx
 "use client";
 import { createInstallationClient } from "@hosty-sdk/app/install";
 import { InstallDialog } from "@hosty-sdk/app/install/react";
+import { openInstallationConfirmation } from "@hosty-sdk/app/install";
 const client = createInstallationClient();
 
+// In the Install click handler, before awaiting source preparation:
+const confirmationWindow = openInstallationConfirmation();
 // Render conditionally while open; unmount it when closed.
 <InstallDialog
   client={client}
+  confirmationWindow={confirmationWindow}
   source={{ feedsUrl: "https://example.com/feeds.json", feedId: "stable" }}
   onClose={() => setOpen(false)}
   onInstalled={() => { setOpen(false); refreshInstalledApps(); }}
 />;
 ```
 
+The default dialog immediately prepares the selected source and submits defaults. Core alone
+asks for runtime, automatic startup and permissions. Choose the channel before opening the
+dialog; changing the source creates a new request. Missing required configuration does not
+prevent installation: configure the stopped app afterwards. The dialog shows preparation,
+errors, status and an explicit confirmation link when the popup is blocked. An uncertain
+submission retains its ID and offers status-only recovery.
+
 For a custom UI, use `useInstallation(client)` or the framework-independent `InstallationFlow`.
 For direct API use, the same client provides the full request sequence:
 

package/dist/activity-react.d.ts

@@ -1,6 +1,6 @@
 import type { AppAuthProtocol } from "./app-code.js";
 /** Keep mounted beside app content so expiry never discards drafts or component state. */
-export declare function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired, appAuthProtocol, probePath, native }: {
+export type AppActivityOptions = {
     openUrl: string;
     appCodePath: string;
     activeUntil?: string | null;
@@ -8,4 +8,13 @@ export declare function AppActivityBridge({ openUrl, appCodePath, activeUntil, a
     appAuthProtocol?: AppAuthProtocol | null;
     probePath?: string;
     native?: boolean;
-}): import("react").JSX.Element | null;
+    validateSession?: () => Promise<boolean>;
+};
+export declare function useAppActivity(options: AppActivityOptions | null): {
+    needed: boolean;
+    pending: boolean;
+    error: string;
+    renew: () => void;
+    cancel: () => void;
+};
+export declare function AppActivityBridge(options: AppActivityOptions): import("react").JSX.Element | null;

package/dist/activity-react.js

@@ -5,8 +5,8 @@ import { AuthNotice, AuthNoticeButton } from "./auth-notice.js";
 import { APP_SESSION_ENDED, APP_ACTIVITY_RENEWED, appActivityNeedsRenewal, configureAppActivity, updateAppActivity, renewAppActivity, cancelActivityRenewal } from "./browser-auth.js";
 import { resolveLaunchMode, detectLaunchMode, normalizeLaunchMode, LAUNCH_MODE_ATTRIBUTE, LAUNCH_MODE_PARAM, LAUNCH_MODE_STORAGE_KEY } from "./index.js";
 import { acceptAppAuthProtocol, refreshAppAuthProtocol } from "./browser-auth.js";
-/** Keep mounted beside app content so expiry never discards drafts or component state. */
-export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired = false, appAuthProtocol, probePath = "/api/auth/identity", native }) {
+export function useAppActivity(options) {
+    const { openUrl, appCodePath = "/api/auth/app-code", activeUntil, activityRequired = false, appAuthProtocol, probePath = "/api/auth/identity", native, validateSession } = options ?? {};
     const [needed, setNeeded] = useState(false);
     const [pending, setPending] = useState(false);
     const [error, setError] = useState("");
@@ -17,6 +17,8 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
         void operation.catch(e => { setNeeded(true); setError(String(e.message ?? e)); }).finally(() => setPending(false));
     };
     useEffect(() => {
+        if (!openUrl)
+            return;
         let cancelled = false;
         let cleanup;
         const controller = new AbortController();
@@ -31,7 +33,7 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
             const mode = normalizeLaunchMode(document.documentElement.getAttribute(LAUNCH_MODE_ATTRIBUTE)) ?? resolveLaunchMode({
                 param: new URL(window.location.href).searchParams.get(LAUNCH_MODE_PARAM), stored, heuristic: detectLaunchMode(window),
             }).mode;
-            cleanup = configureAppActivity({ openUrl, appAuthProtocol: protocol, probePath, native: native ?? mode === "native", activeUntil, activityRequired, exchangeCode: async (proof) => {
+            cleanup = configureAppActivity({ openUrl, appAuthProtocol: protocol, probePath, native: native ?? mode === "native", activeUntil, activityRequired, validateSession, exchangeCode: async (proof) => {
                     const response = await fetch(appCodePath, { method: "POST", credentials: "same-origin", redirect: "error",
                         headers: { "Content-Type": "application/json" }, body: JSON.stringify(proof) });
                     const body = await response.json();
@@ -59,9 +61,13 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
         window.addEventListener(APP_ACTIVITY_RENEWED, renewed);
         document.addEventListener("click", click, true);
         return () => { cancelled = true; controller.abort(); cleanup?.(); window.removeEventListener(APP_SESSION_ENDED, expired); window.removeEventListener(APP_ACTIVITY_RENEWED, renewed); document.removeEventListener("click", click, true); };
-    }, [openUrl, appCodePath, appAuthProtocol, probePath, native]);
+    }, [openUrl, appCodePath, appAuthProtocol, probePath, native, validateSession]);
     useEffect(() => { updateAppActivity(activeUntil, activityRequired); }, [activeUntil, activityRequired, openUrl, appCodePath]);
+    return { needed, pending, error, renew, cancel: () => { cancelActivityRenewal(); setNeeded(false); } };
+}
+export function AppActivityBridge(options) {
+    const { needed, pending, error, renew, cancel } = useAppActivity(options);
     if (!needed)
         return null;
-    return _jsxs(AuthNotice, { children: [_jsx("span", { children: error || "Renew access through Core to continue. Your work stays on this page." }), _jsx(AuthNoticeButton, { disabled: pending, onClick: renew, children: pending ? "Waiting for Core…" : "Renew access" }), _jsx(AuthNoticeButton, { secondary: true, onClick: () => { cancelActivityRenewal(); setNeeded(false); }, children: "Later" })] });
+    return _jsxs(AuthNotice, { children: [_jsx("span", { children: error || "Renew access through Core to continue. Your work stays on this page." }), _jsx(AuthNoticeButton, { disabled: pending, onClick: renew, children: pending ? "Waiting for Core…" : "Renew access" }), _jsx(AuthNoticeButton, { secondary: true, onClick: cancel, children: "Later" })] });
 }

package/dist/browser-auth.d.ts

@@ -45,6 +45,8 @@ export declare function refreshAppAuthProtocol(openUrl: string, probePath?: stri
 /** Must be called directly from a user gesture. Native hosts intercept before any request. */
 export declare function openAppSignIn(openUrl: string, signal?: AbortSignal, appAuthProtocol?: AppAuthProtocol, native?: boolean, probePath?: string): Promise<AppSignInResult>;
 export declare const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
+/** Validated restoration of the same actor, before the app resumes protected work. */
+export declare const APP_SESSION_RESTORED = "hosty:app-session-restored";
 export type AppActivityConfig = {
     openUrl: string;
     appAuthProtocol: AppAuthProtocol;
@@ -56,6 +58,8 @@ export type AppActivityConfig = {
         accessToken?: string;
         activeUntil?: string | null;
     }>;
+    /** The root coordinator verifies actor and setup before any waiting request can retry. */
+    validateSession?: () => Promise<boolean>;
 };
 export declare function configureAppActivity(config: AppActivityConfig): () => void;
 export declare function updateAppActivity(activeUntil?: string | null, activityRequired?: boolean): void;

package/dist/browser-auth.js

@@ -265,6 +265,11 @@ export async function appFetch(input, init = {}, recover = true) {
     const url = new URL(input, window.location.href);
     if (url.origin !== window.location.origin || url.username || url.password)
         throw new Error("App API requests must stay on this app's origin.");
+    // Mounted app effects can still run behind the overlay. Do not send their requests with
+    // the newly exchanged credential until the coordinator has checked the actor and setup.
+    // SDK identity/protocol probes use recover=false so that validation itself can proceed.
+    if (recover && renewal && activityConfig?.validateSession && !await waitForActivity(init.signal))
+        return Response.json({ code: "reauth_required", message: "Hosty access has not been restored." }, { status: 401 });
     const current = grant?.origin === url.origin ? grant : null;
     const headers = new Headers(init.headers);
     if (current)
@@ -521,6 +526,8 @@ function openNativeAppSignIn(attempt, signal) {
     });
 }
 export const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
+/** Validated restoration of the same actor, before the app resumes protected work. */
+export const APP_SESSION_RESTORED = "hosty:app-session-restored";
 let activityConfig = null;
 let renewal = null;
 let renewalController = null;
@@ -571,6 +578,10 @@ export function renewAppActivity() {
         if (result.accessToken)
             rememberAppGrant(result.accessToken);
         config.activeUntil = result.activeUntil;
+        if (config.validateSession && !await config.validateSession())
+            throw new Error("Access has not been restored. Complete the Hosty setup before continuing.");
+        if (controller.signal.aborted || activityConfig !== config)
+            throw new Error("Sign-in was cancelled.");
         recoveryPending = false;
         for (const done of [...waiting])
             done(true);

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { AppSessionStatus, AppSessionFailureStatus, SessionRecoveryParams } from "./session-types.js";
+export type { AppSessionStatus, AppSessionFailureStatus, SessionRecoveryParams } from "./session-types.js";
 /**
  * The postMessage type for an embedded app's authentication-required intent.
  * A frozen protocol constant: it deliberately does not track product branding (precedent:
@@ -71,22 +73,6 @@ export interface DelegatedTokenGrant {
 export declare function createDelegatedTokenRequest(options?: {
     refresh?: boolean;
 }): DelegatedTokenRequest;
-/**
- * Recovery classification of an app session, per the platform identity error contract:
- * - `not-present`: no token at all (recoverable — same handling as `expired`).
- * - `active`: token revalidated OK.
- * - `expired`: Core 401 — recoverable; re-authorize via the Shell (embedded) or Core `/open`
- *   (standalone).
- * - `forbidden`: Core 403 or a token minted for a different app — terminal; never
- *   auto-redirect (it would loop).
- * - `unavailable`: Core unreachable, slow, or answering garbage — transient; keep the
- *   cookie and offer a retry.
- * - `misconfigured`: the app itself is broken (no service token / no Core origin) — an
- *   operator problem; signing in cannot fix it, so never offer a login.
- */
-export type AppSessionStatus = "not-present" | "active" | "expired" | "forbidden" | "unavailable" | "misconfigured";
-/** Failure statuses (everything but `active`). */
-export type AppSessionFailureStatus = Exclude<AppSessionStatus, "active">;
 /**
  * Maps a Core revalidation HTTP status onto the session classification. Classification is
  * by status code only — never by error-code strings — so new Core codes cannot break an
@@ -99,11 +85,6 @@ export declare function classifyRevalidationHttpStatus(status: number): AppSessi
  * prerendered at image build time, where the HOSTY_* environment does not exist yet
  * (docker-host PR #233 / media-server PR #63). Neither value is secret.
  */
-export interface SessionRecoveryParams {
-    appId: string | null;
-    corePublicOrigin: string | null;
-    appAuthProtocol: 1 | 2 | null;
-}
 export declare function readRecoveryParams(body: unknown): SessionRecoveryParams;
 /** True for hosts that only resolve on the machine itself. */
 export declare function isLoopbackHost(hostname: string): boolean;

package/dist/index.js

@@ -86,6 +86,12 @@ export function classifyRevalidationHttpStatus(status) {
     }
     return "unavailable";
 }
+/**
+ * Recovery parameters an app's force-dynamic identity/session endpoint hands the browser.
+ * They ride in a response — never in a server-component prop — because app pages are
+ * prerendered at image build time, where the HOSTY_* environment does not exist yet
+ * (docker-host PR #233 / media-server PR #63). Neither value is secret.
+ */
 export function readRecoveryParams(body) {
     const recovery = body && typeof body === "object" ? body.recovery : null;
     if (!recovery || typeof recovery !== "object") {

package/dist/install-react.d.ts

@@ -5,12 +5,18 @@ export declare function useInstallation(client: InstallationClient): {
     request: InstallationRequest | null;
     busy: boolean;
     error: string | null;
+    uncertainSubmit: boolean;
 };
 export interface InstallDialogProps {
     client: InstallationClient;
+    /** Choose the source/channel before opening. Core freezes that selection during preparation. */
     source?: InstallationSource;
+    /** Open synchronously in the Install click handler, before mounting or fetching a source. */
+    confirmationWindow?: Window | null;
     onClose: () => void;
+    /** Return to the caller's source/connection picker after a known pre-confirmation error. */
+    onChooseSource?: () => void;
     onInstalled?: (request: InstallationRequest) => void;
 }
-/** Mount when opened; unmount on close. Styling is self-contained and has no Next/Tailwind dependency. */
-export declare function InstallDialog({ client, source, onClose, onInstalled }: InstallDialogProps): import("react").JSX.Element;
+/** One Core confirmation, with app-local preparation/progress only. No installation questionnaire. */
+export declare function InstallDialog(props: InstallDialogProps): import("react").JSX.Element;

package/dist/install-react.js

@@ -15,29 +15,83 @@ export function useInstallation(client) {
     }, [flow, state.request?.id, state.request?.status]);
     return { ...state, flow };
 }
-/** Mount when opened; unmount on close. Styling is self-contained and has no Next/Tailwind dependency. */
-export function InstallDialog({ client, source, onClose, onInstalled }) {
-    const { request, busy, error, flow } = useInstallation(client);
+const popupOwners = new WeakMap();
+/** One Core confirmation, with app-local preparation/progress only. No installation questionnaire. */
+export function InstallDialog(props) {
+    // A changed source is a new review. Never apply an earlier channel's confirmation to it.
+    return _jsx(InstallationSession, { ...props }, JSON.stringify(props.source ?? null));
+}
+function InstallationSession({ client, source, confirmationWindow, onClose, onChooseSource, onInstalled }) {
+    const { request, busy, error, uncertainSubmit, flow } = useInstallation(client);
     const dialog = useRef(null);
     const titleId = useId();
-    const [manifestPath, setManifestPath] = useState(source?.manifestPath ?? "");
-    const [settings, setSettings] = useState({});
-    const [autostart, setAutostart] = useState(true);
-    const [draftPlanId, setDraftPlanId] = useState(null);
+    const [manifestPath, setManifestPath] = useState("");
+    const [presentationError, setPresentationError] = useState(null);
     const notified = useRef(null);
-    const plan = request?.plan ?? null;
-    if (plan && request?.id !== draftPlanId) {
-        setDraftPlanId(request.id);
-        setSettings(Object.fromEntries(plan.settings.map(setting => [setting.key, setting.secret ? "" : setting.defaultValue ?? ""])));
-        setAutostart(plan.defaultAutostart ?? true);
-    }
-    const initialManifest = source?.manifestPath;
-    const initialFeed = source?.feedsUrl;
-    const initialFeedId = source?.feedId;
+    const [initialSource] = useState(source);
+    const activePopup = useRef(confirmationWindow ?? null);
+    const popupOwner = useRef({});
+    const popupShown = useRef(false);
+    const mountLease = useRef(0);
+    const hasSource = Boolean(initialSource?.manifestPath || initialSource?.feedsUrl);
+    const frozen = uncertainSubmit || (request !== null && request.status !== "draft");
+    const claimPopup = (popup) => {
+        activePopup.current = popup;
+        popupShown.current = false;
+        if (popup)
+            popupOwners.set(popup, popupOwner.current);
+    };
+    const closeUnusedPopup = (popup = activePopup.current) => {
+        if (!popup || popupShown.current || popupOwners.get(popup) !== popupOwner.current)
+            return;
+        popupOwners.delete(popup);
+        popup.close();
+    };
+    const showConfirmation = (popup, submitted) => {
+        // A newer source session may now own the caller's preopened window.
+        if (popup && popupOwners.get(popup) !== popupOwner.current)
+            return;
+        if (!submitted || submitted.status !== "pending") {
+            closeUnusedPopup(popup);
+            return;
+        }
+        try {
+            showInstallationConfirmation(popup, submitted);
+            popupShown.current = Boolean(popup && !popup.closed);
+        }
+        catch (cause) {
+            closeUnusedPopup(popup);
+            setPresentationError(cause instanceof Error ? cause.message : "Core confirmation could not be opened.");
+        }
+    };
+    useEffect(() => {
+        const lease = ++mountLease.current;
+        claimPopup(activePopup.current);
+        return () => {
+            // StrictMode immediately replays setup. Defer cleanup so that replay, or a new source
+            // session adopting the same window, can retain the reservation.
+            queueMicrotask(() => { if (mountLease.current === lease)
+                closeUnusedPopup(); });
+        };
+    }, [flow]);
     useEffect(() => {
-        if (initialManifest || initialFeed)
-            void flow.review({ manifestPath: initialManifest, feedsUrl: initialFeed, feedId: initialFeedId });
-    }, [flow, initialManifest, initialFeed, initialFeedId]);
+        if (!initialSource?.manifestPath && !initialSource?.feedsUrl)
+            return;
+        let cancelled = false;
+        void (async () => {
+            await flow.review(initialSource);
+            if (cancelled)
+                return;
+            if (flow.snapshot().request?.status !== "draft") {
+                closeUnusedPopup();
+                return;
+            }
+            const submitted = await flow.submit();
+            if (!cancelled)
+                showConfirmation(activePopup.current, submitted);
+        })();
+        return () => { cancelled = true; };
+    }, [flow, initialSource]);
     useEffect(() => {
         const element = dialog.current;
         element?.showModal();
@@ -49,28 +103,55 @@ export function InstallDialog({ client, source, onClose, onInstalled }) {
             onInstalled?.(request);
         }
     }, [request, onInstalled]);
-    const frozen = request !== null && request.status !== "draft";
-    const review = (runtime) => flow.review({
-        ...(source?.feedsUrl ? { feedsUrl: source.feedsUrl, feedId: source.feedId } : { manifestPath: manifestPath.trim() }),
-        selectedRuntime: runtime,
-    });
-    const submit = async () => {
+    const install = async () => {
+        if (busy || frozen)
+            return;
+        // The browser gesture is still active here, before any async preparation.
         const popup = openInstallationConfirmation();
-        const values = Object.fromEntries((plan?.settings ?? []).filter(setting => !setting.secret || settings[setting.key])
-            .map(setting => [setting.key, settings[setting.key] ?? ""]));
-        const submitted = await flow.submit(values, autostart);
-        if (submitted)
-            showInstallationConfirmation(popup, submitted);
-        else
-            popup?.close();
+        claimPopup(popup);
+        setPresentationError(null);
+        await flow.review({ manifestPath: manifestPath.trim() });
+        if (flow.snapshot().request?.status !== "draft") {
+            closeUnusedPopup(popup);
+            return;
+        }
+        showConfirmation(popup, await flow.submit());
     };
-    return _jsxs("dialog", { ref: dialog, className: "hosty-install", "aria-labelledby": titleId, onCancel: event => { event.preventDefault(); onClose(); }, children: [_jsx("style", { children: styles }), _jsxs("header", { children: [_jsx("h2", { id: titleId, children: "Install app" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close installation", children: "\u00D7" })] }), _jsx("p", { children: "Prepare the installation here, then confirm it securely in Hosty Core." }), !source?.feedsUrl && !source?.manifestPath && _jsxs("form", { onSubmit: event => { event.preventDefault(); void review(); }, children: [_jsxs("label", { children: ["Manifest, app directory, or URL", _jsx("input", { value: manifestPath, onChange: event => { setManifestPath(event.target.value); flow.clearReview(); }, required: true, disabled: busy || frozen })] }), _jsx("button", { disabled: busy || frozen || !manifestPath.trim(), children: "Review" })] }), busy && _jsx("p", { role: "status", children: "Preparing installation\u2026" }), error && _jsxs("div", { role: "alert", children: [_jsx("p", { children: error }), !frozen && _jsx("button", { type: "button", disabled: busy, onClick: () => void review(), children: "Retry review" })] }), plan && _jsxs("form", { onSubmit: event => { event.preventDefault(); void submit(); }, children: [_jsxs("h3", { children: [plan.displayName, " ", _jsx("small", { children: plan.targetVersion })] }), plan.description && _jsx("p", { children: plan.description }), _jsxs("label", { children: ["Runtime", _jsx("select", { value: plan.targetRuntime, disabled: busy || frozen, onChange: event => void review(event.target.value), children: (plan.runtimeProfiles ?? [{ key: plan.targetRuntime, type: plan.targetRuntimeType }]).map(runtime => _jsxs("option", { value: runtime.key, children: [runtime.key, " (", runtime.type, ")"] }, runtime.key)) })] }), plan.targetRuntimeType === "localCommand" && _jsx("p", { className: "warning", children: "This runtime runs commands directly on your host, outside a container. Only install code you trust." }), plan.system && _jsx("p", { className: "warning", children: "This is a system app. User access is controlled by Hosty assignments." }), !!plan.requestedRoles?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested provider roles" }), _jsx("ul", { children: plan.requestedRoles.map(role => _jsx("li", { children: plan.roleDescriptions?.[role] ?? role }, role)) })] }), !!plan.corePermissions?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested Core permissions" }), _jsx("ul", { children: plan.corePermissions.map(permission => _jsx("li", { children: plan.permissionDescriptions?.[permission] ?? permission }, permission)) })] }), plan.settings.map(setting => _jsxs("label", { children: [setting.label || setting.key, setting.required ? " (required)" : "", setting.type === "boolean" && !setting.secret
-                                ? _jsx("input", { type: "checkbox", checked: ["true", "1", "yes", "on", "enabled"].includes((settings[setting.key] ?? "").toLowerCase()), disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: String(event.target.checked) })) })
-                                : setting.type === "select" && setting.options?.length && !setting.secret
-                                    ? _jsxs("select", { value: settings[setting.key] ?? "", disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: event.target.value })), children: [_jsx("option", { value: "", children: "Select a value" }), setting.options.map(option => _jsx("option", { value: option.value, children: option.label }, option.value))] })
-                                    : _jsx("input", { type: setting.secret ? "password" : setting.type === "number" ? "number" : setting.type === "url" ? "url" : "text", step: setting.type === "number" ? "any" : undefined, autoComplete: setting.secret ? "new-password" : "off", required: setting.required && !setting.secret, disabled: busy || frozen, value: settings[setting.key] ?? "", onChange: event => setSettings(current => ({ ...current, [setting.key]: event.target.value })) }), setting.description && _jsx("small", { children: setting.description })] }, setting.key)), _jsxs("label", { className: "check", children: [_jsx("input", { type: "checkbox", checked: autostart, disabled: busy || frozen, onChange: event => setAutostart(event.target.checked) }), " Start automatically (now and on Core startup)"] }), !frozen && _jsx("footer", { children: _jsx("button", { className: "primary", disabled: busy, children: "Continue to Core confirmation" }) })] }), frozen && _jsxs("section", { role: "status", children: [_jsx("p", { children: request.status === "pending" ? "Waiting for your confirmation in Hosty Core." : request.status === "executing" ? "Core is applying your confirmed request…" : request.status === "succeeded" ? "App installed." : request.status === "denied" ? "Installation cancelled." : "Installation failed. Close this dialog and review a new plan to retry." }), request.status === "pending" && _jsx("a", { href: request.approvalUrl, target: "_blank", rel: "noopener noreferrer", children: "Open Core confirmation" }), _jsx("p", { children: _jsx("small", { children: "Closing this dialog does not cancel an operation already confirmed in Core." }) })] })] });
+    const retry = async () => {
+        setPresentationError(null);
+        if (uncertainSubmit) {
+            await flow.refresh();
+            return;
+        }
+        const popup = openInstallationConfirmation();
+        claimPopup(popup);
+        // A known draft submit failure retries its existing identity, without resolving the feed again.
+        if (!request)
+            await flow.review(initialSource ?? { manifestPath: manifestPath.trim() });
+        if (flow.snapshot().request?.status !== "draft") {
+            closeUnusedPopup(popup);
+            return;
+        }
+        showConfirmation(popup, await flow.submit());
+    };
+    const close = () => {
+        closeUnusedPopup();
+        onClose();
+    };
+    const confirmationUrl = (() => {
+        if (request?.status !== "pending")
+            return null;
+        try {
+            const url = new URL(request.approvalUrl);
+            return ["http:", "https:"].includes(url.protocol) ? url.href : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    return _jsxs("dialog", { ref: dialog, className: "hosty-install", "aria-labelledby": titleId, onCancel: event => { event.preventDefault(); close(); }, children: [_jsx("style", { children: styles }), _jsxs("header", { children: [_jsx("h2", { id: titleId, children: "Install app" }), _jsx("button", { type: "button", onClick: close, "aria-label": "Close installation", children: "\u00D7" })] }), !hasSource && !request && _jsxs("form", { onSubmit: event => { event.preventDefault(); void install(); }, children: [_jsxs("label", { children: ["Manifest, app directory, or URL", _jsx("input", { value: manifestPath, onChange: event => setManifestPath(event.target.value), required: true, disabled: busy })] }), _jsx("button", { className: "primary", disabled: busy || !manifestPath.trim(), children: "Install" })] }), busy && _jsx("p", { role: "status", children: "Preparing Core confirmation\u2026" }), (error || presentationError) && _jsxs("div", { role: "alert", children: [_jsx("p", { children: error || presentationError }), (!frozen || uncertainSubmit) && _jsx("button", { type: "button", disabled: busy, onClick: () => void retry(), children: uncertainSubmit ? "Check request status" : "Retry" }), !frozen && onChooseSource && _jsx("button", { type: "button", disabled: busy, onClick: () => { closeUnusedPopup(); onChooseSource(); }, children: "Change source" })] }), uncertainSubmit && _jsx("p", { role: "status", children: "Core may have received this request. Check its status before continuing." }), request && request.status !== "draft" && _jsxs("section", { role: "status", children: [_jsx("p", { children: request.status === "pending" ? "Confirm runtime, automatic startup and permissions in Hosty Core." : request.status === "executing" ? "Core is installing your app…" : request.status === "succeeded" ? "App installed." : request.status === "denied" ? "Installation cancelled." : "Installation failed. Close this dialog to begin a new request." }), confirmationUrl && _jsx("a", { href: confirmationUrl, target: "_blank", rel: "noopener noreferrer", children: "Open Core confirmation" }), _jsx("p", { children: _jsx("small", { children: "Closing this dialog does not cancel an operation already confirmed in Core." }) })] })] });
 }
 const styles = `
-.hosty-install{box-sizing:border-box;width:min(640px,calc(100vw - 32px));max-height:calc(100dvh - 32px);padding:24px;border:1px solid var(--border,#aaa);border-radius:12px;background:var(--background,Canvas);color:var(--foreground,CanvasText);font:inherit;overflow:auto;margin:auto}
-.hosty-install::backdrop{background:#0008}.hosty-install header{display:flex;align-items:center;justify-content:space-between;gap:16px}.hosty-install h2{font-size:1.25rem;margin:0}.hosty-install h3{font-size:1rem;margin:20px 0 8px}.hosty-install p{margin:12px 0;font-size:.9rem}.hosty-install small{font-size:.8rem;opacity:.75}.hosty-install label{display:flex;flex-direction:column;gap:6px;margin:16px 0;font-size:.9rem}.hosty-install input:not([type=checkbox]),.hosty-install select{box-sizing:border-box;width:100%;border:1px solid var(--border,#aaa);border-radius:6px;padding:8px 10px;background:transparent;color:inherit;font:inherit}.hosty-install .check{flex-direction:row;align-items:center;gap:10px}.hosty-install input[type=checkbox]{width:16px;height:16px;accent-color:#2563eb}.hosty-install button{border:1px solid var(--border,#aaa);border-radius:6px;padding:8px 12px;font:inherit;background:transparent;color:inherit;cursor:pointer}.hosty-install button:disabled{opacity:.5;cursor:default}.hosty-install .primary{background:#2563eb;color:white;border-color:#2563eb}.hosty-install footer{display:flex;justify-content:flex-end;margin-top:24px}.hosty-install .warning{padding:12px;border:1px solid #b7791f;border-radius:6px}.hosty-install [role=alert]{color:#d33}.hosty-install a{color:#2563eb;text-decoration:underline}.hosty-install :focus-visible{outline:2px solid #60a5fa;outline-offset:3px}
+.hosty-install{box-sizing:border-box;width:min(480px,calc(100vw - 32px));max-height:calc(100dvh - 32px);padding:24px;border:1px solid var(--border,#aaa);border-radius:12px;background:var(--background,Canvas);color:var(--foreground,CanvasText);font:inherit;overflow:auto;margin:auto}
+.hosty-install::backdrop{background:#0008}.hosty-install header{display:flex;align-items:center;justify-content:space-between;gap:16px}.hosty-install h2{font-size:1.25rem;margin:0}.hosty-install p{margin:12px 0;font-size:.9rem}.hosty-install small{font-size:.8rem;opacity:.75}.hosty-install label{display:flex;flex-direction:column;gap:6px;margin:16px 0;font-size:.9rem}.hosty-install input{box-sizing:border-box;width:100%;border:1px solid var(--border,#aaa);border-radius:6px;padding:8px 10px;background:transparent;color:inherit;font:inherit}.hosty-install button{border:1px solid var(--border,#aaa);border-radius:6px;padding:8px 12px;font:inherit;background:transparent;color:inherit;cursor:pointer}.hosty-install button:disabled{opacity:.5;cursor:default}.hosty-install .primary{background:#2563eb;color:white;border-color:#2563eb}.hosty-install [role=alert]{color:#d33}.hosty-install a{color:#2563eb;text-decoration:underline}.hosty-install :focus-visible{outline:2px solid #60a5fa;outline-offset:3px}
 `;

package/dist/install.d.ts

@@ -12,6 +12,16 @@ export interface InstallSetting {
         label: string;
     }[] | null;
 }
+export interface InstallationConfigurationReadiness {
+    required: boolean;
+    missingSettings: string[];
+    mounts: {
+        key: string;
+        label?: string | null;
+        reason: string;
+    }[];
+    error?: string | null;
+}
 export interface InstallPlan {
     appId: string;
     displayName: string;
@@ -37,6 +47,14 @@ export interface InstallPlan {
         development?: boolean;
     }[];
     settings: InstallSetting[];
+    runtimeChoices?: {
+        key: string;
+        type: string;
+        default: boolean;
+        available: boolean;
+        error?: string | null;
+    }[];
+    configurationReadiness?: InstallationConfigurationReadiness | null;
 }
 export interface InstallationSource {
     manifestPath?: string;
@@ -97,10 +115,22 @@ export interface InstallationRequest {
     plan: InstallPlan | null;
     updatePlan?: {
         appId: string;
-        displayName: string;
+        displayName?: string | null;
         targetVersion: string;
         targetRuntime: string;
         changes: string[];
+        previousRequiredCorePermissions?: string[] | null;
+        previousOptionalCorePermissions?: string[] | null;
+        feedsUrl?: string | null;
+        feedId?: string | null;
+        targetRuntimeType?: string | null;
+        settingChanges?: {
+            key: string;
+            label?: string | null;
+            change: string;
+            detail?: string | null;
+        }[];
+        configurationReadiness?: InstallationConfigurationReadiness | null;
     } | null;
     permissionPlan?: {
         appId: string;
@@ -128,7 +158,7 @@ export interface InstallationRequest {
 }
 export interface InstallationClient {
     prepare(source: InstallationSource): Promise<InstallationRequest>;
-    submit(id: string, settings: Record<string, string | null>, autostart: boolean): Promise<InstallationRequest>;
+    submit(id: string, settings?: Record<string, string | null>, autostart?: boolean): Promise<InstallationRequest>;
     status(id: string): Promise<InstallationRequest>;
 }
 export declare class InstallationError extends Error {
@@ -145,6 +175,8 @@ export interface InstallationState {
     request: InstallationRequest | null;
     busy: boolean;
     error: string | null;
+    /** A submit may have succeeded; resolve the existing identity before another mutation. */
+    uncertainSubmit: boolean;
 }
 /** Reusable state flow for custom UIs, independent of React. Never automatically retries a mutation. */
 export declare class InstallationFlow {
@@ -153,6 +185,8 @@ export declare class InstallationFlow {
     private listeners;
     private generation;
     private disposed;
+    private submitting;
+    private refreshing;
     constructor(client: InstallationClient);
     snapshot: () => InstallationState;
     subscribe: (listener: () => void) => (() => void);
@@ -161,7 +195,7 @@ export declare class InstallationFlow {
     cancelPending(): void;
     dispose(): void;
     review(source: InstallationSource): Promise<void>;
-    submit(settings: Record<string, string | null>, autostart: boolean): Promise<InstallationRequest | null>;
+    submit(settings?: Record<string, string | null>, autostart?: boolean): Promise<InstallationRequest | null>;
     refresh(): Promise<void>;
 }
 /** Open synchronously in a click handler, before awaiting plan/submit requests. */