@hosty-sdk/app 0.22.1 → 0.24.0

package/README.md

@@ -176,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/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. */

package/dist/install.js

@@ -33,10 +33,12 @@ export function createInstallationClient(options = {}) {
 /** Reusable state flow for custom UIs, independent of React. Never automatically retries a mutation. */
 export class InstallationFlow {
     client;
-    state = { request: null, busy: false, error: null };
+    state = { request: null, busy: false, error: null, uncertainSubmit: false };
     listeners = new Set();
     generation = 0;
     disposed = false;
+    submitting = false;
+    refreshing = false;
     constructor(client) {
         this.client = client;
     }
@@ -50,72 +52,88 @@ export class InstallationFlow {
             listener();
     }
     clearReview() {
-        if (this.state.request && this.state.request.status !== "draft")
+        const status = this.state.request?.status;
+        if (this.submitting || this.state.uncertainSubmit || (status && !["draft", "succeeded", "denied", "failed"].includes(status)))
             return;
         this.generation++;
-        this.set({ request: null, busy: false, error: null });
+        this.set({ request: null, busy: false, error: null, uncertainSubmit: false });
     }
     cancelPending() { this.generation++; }
     dispose() { this.disposed = true; this.generation++; this.listeners.clear(); }
     async review(source) {
-        if (this.state.request && this.state.request.status !== "draft")
+        if (this.submitting || this.state.uncertainSubmit || (this.state.request && this.state.request.status !== "draft"))
             return;
         const generation = ++this.generation;
-        this.set({ request: null, busy: true, error: null });
+        this.set({ request: null, busy: true, error: null, uncertainSubmit: false });
         try {
             const request = await this.client.prepare(source);
             if (generation === this.generation)
-                this.set({ request, busy: false, error: null });
+                this.set({ request, busy: false, error: null, uncertainSubmit: false });
         }
         catch (error) {
             if (generation === this.generation)
-                this.set({ request: null, busy: false, error: message(error) });
+                this.set({ request: null, busy: false, error: message(error), uncertainSubmit: false });
         }
     }
     async submit(settings, autostart) {
-        if (this.state.busy || this.state.request?.status !== "draft")
+        if (this.state.busy || this.state.uncertainSubmit || this.state.request?.status !== "draft")
             return null;
         const id = this.state.request.id;
         const generation = this.generation;
+        this.submitting = true;
         this.set({ ...this.state, busy: true, error: null });
         try {
             const request = await this.client.submit(id, settings, autostart);
             if (generation !== this.generation)
                 return null;
-            this.set({ request, busy: false, error: null });
+            this.set({ request, busy: false, error: null, uncertainSubmit: false });
             return request;
         }
         catch (error) {
+            if (error instanceof InstallationError && error.status >= 400 && error.status < 500) {
+                if (generation === this.generation)
+                    this.set({ ...this.state, busy: false, error: message(error), uncertainSubmit: false });
+                return null;
+            }
             // A lost response may mean the request was already frozen. Recover by reading its status,
             // not by sending another submit or creating a second installation.
             try {
                 const request = await this.client.status(id);
                 if (generation !== this.generation)
                     return null;
-                this.set({ request, busy: false, error: request.status === "draft" ? message(error) : null });
+                this.set({ request, busy: false, error: request.status === "draft" ? message(error) : null, uncertainSubmit: false });
                 return request.status === "draft" ? null : request;
             }
             catch {
                 if (generation === this.generation)
-                    this.set({ ...this.state, busy: false, error: message(error) });
+                    this.set({ ...this.state, busy: false, error: message(error), uncertainSubmit: true });
                 return null;
             }
         }
+        finally {
+            this.submitting = false;
+        }
     }
     async refresh() {
-        if (!this.state.request || this.state.busy)
+        if (!this.state.request || this.state.busy || this.refreshing)
             return;
+        this.refreshing = true;
         const id = this.state.request.id;
         const generation = this.generation;
         try {
             const request = await this.client.status(id);
             if (generation === this.generation)
-                this.set({ request, busy: false, error: request.error ?? null });
+                this.set({ request, busy: false,
+                    error: request.error ?? (this.state.uncertainSubmit && request.status === "draft" ? "Core has not received the submission. Retry this request." : null),
+                    uncertainSubmit: false });
         }
         catch (error) {
             if (generation === this.generation)
                 this.set({ ...this.state, error: message(error) });
         }
+        finally {
+            this.refreshing = false;
+        }
     }
 }
 function message(error) { return error instanceof Error ? error.message : "Installation request failed."; }

package/dist/providers.d.ts

@@ -9,6 +9,12 @@ export type ProviderDescriptor = {
     capabilities: string[];
     url: string | null;
     available: boolean;
+    /** Declared browser surfaces for resolving assistant handoffs; absent on older Core versions. */
+    uiSurfaces?: Array<{
+        endpoint: string | null;
+        path: string;
+        url: string | null;
+    }> | null;
 };
 export type AppPermissionState = {
     required: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",