@hosty-sdk/app 0.23.0 → 0.25.12

package/README.md

@@ -299,3 +299,75 @@ listen for `APP_SESSION_ENDED`, and call `renewAppActivity` directly from a clic
 or reload to renew access. `appActivityNeedsRenewal()` supports proactive click renewal near expiry.
 See [the activity contract](../../docs/features/app-activity-window/feature.md), including the
 separate Core-approved assistant session leases.
+
+## Shared panels (Core 0.129.0 / SDK 0.25.0)
+
+`HostyOverlay` composes one UI owner per top-level browser document. Its default
+`panelLayout="auto"` adds an opened-tool rail, an **Add tool** chooser and a resizable
+workspace. In a directly embedded app it delegates presentation to the verified parent
+and renders no local rail. Use `panelLayout="slot"` with exactly one
+`HostyPanelWorkspace` inside your chrome, or `"none"` for a custom controller renderer.
+Panel hosting requires reviewed optional `apps.panels.read` (or existing `apps.read`);
+participating as a child does not require catalog access.
+
+```ts
+// app/api/hosty/ui/[...action]/route.ts — own app configuration/session only
+import { createHostyUiRouteHandler } from "@hosty-sdk/app/server";
+const handler = createHostyUiRouteHandler(config);
+export const GET = handler;
+export const POST = handler;
+```
+
+Non-Next servers use `createHostyUiResponse` from `@hosty-sdk/app/ui/server` with their
+revalidated own app-user session/token. `UiServerClient` provides only `bootstrap`,
+`listPanels` and `resolvePanel`; never expose a generic Core proxy or caller-supplied credentials.
+Both server adapters return `no-store` metadata. The React root's `uiPath` defaults to
+`/api/hosty/ui` and must be a same-origin path.
+
+Finalize a business handoff before requesting placement. Freeze the provider's app ID,
+installation ID and interface key before `ProviderClient.assistant(...)`, then read its
+current descriptor and map the completed result:
+
+```ts
+import { resolveAssistantPresentation } from "@hosty-sdk/app/assistant";
+import { buildSurfaceOpenUrl } from "@hosty-sdk/app/ui";
+const presentation = resolveAssistantPresentation(currentProvider, finalized, { expectedProvider });
+const href = buildSurfaceOpenUrl(bootstrap.coreOrigin, presentation.destination);
+// bootstrap.pinnedOpen must be true before relying on this link.
+```
+
+The pure mapper never selects an assistant or invokes it. Explicit `result.open.panelId`
+selects a matching declared panel; otherwise the unique longest endpoint/path boundary
+wins. Ties return `ambiguous_surface`, navigation-only providers return `no_panel`, and
+both retain the exact same-session destination for explicit separate opening. A changed
+provider installation is refused. Core validates pinned links again after login.
+
+```tsx
+import { useHostyUi } from "@hosty-sdk/app/ui/react";
+import { createPresentationRequestId } from "@hosty-sdk/app/ui";
+const ui = useHostyUi();
+const requestId = createPresentationRequestId(); // retain with the completed result
+const result = await ui.openSurface(presentation.target!, { placement: "side", requestId });
+// Reuse requestId and target for retries; do not repeat the business action.
+const current = await ui.getPresentation(requestId);
+const unsubscribe = ui.subscribe(event => { /* environment or presentation update */ });
+```
+
+`opened` confirms placement, with separate `loading`, `auth-required`, `ready` or
+`unreported` readiness. Providers call `ui.reportSurfaceState({ route, state: "ready" })`
+after their exact route has loaded; iframe load alone is not readiness. Deadline/abort
+returns `uncertain`, not cancellation. Query or retry the same ID. An unsupported host
+never automatically opens a tab or creates a nested workspace. **Open separately** is an
+explicit `target="_blank" rel="noopener noreferrer"` link to the pinned destination.
+
+Framework-neutral clients use `createUiHost` from `@hosty-sdk/app/ui/host`, its snapshots,
+`registerFrame`, `openSurface`, `getPresentation`, `setExpanded`, `setWidth` and `dispose`.
+React clients normally use the overlay-owned controller via `useHostyUiHost` and the shared
+`HostyAppFrame`. Core projects the target's minimal microphone/popup policy; an app message
+cannot widen it. No delegated-token responder is required.
+
+Trust is limited to exact mounted window/origin, document generation and stateless Core
+peer metadata. Matching opaque Core/user contexts prevents accidental account mixing
+between cooperating apps; it is not attestation of app code or delegated API authority.
+Every target API still authorizes its own session. Older surfaces remain `unreported`.
+See [the panel contract and verification](../../docs/features/sdk-panel-system/feature.md).

package/dist/assistant.d.ts

@@ -1,3 +1,5 @@
+import type { ProviderDescriptor } from "./providers.js";
+import { type AppSurfaceRef, type PanelTarget } from "@hosty-sdk/app/ui/types";
 /** Preserve provider refusal details through app-owned server transports. */
 export declare class AssistantError extends Error {
     readonly code: string;
@@ -12,6 +14,7 @@ export type AssistantContract = {
 export type AssistantDestination = {
     endpoint: string;
     path: string;
+    panelId?: string;
 };
 export type AssistantHandoffResult = {
     conversationId: string;
@@ -51,6 +54,18 @@ export declare function resolveAssistantDestination(destination: AssistantDestin
     path?: string | null;
     url?: string | null;
 }[]): string;
+/** Pure mapping after finalization; the presentation host separately checks current access. */
+export declare function resolveAssistantPresentation(provider: ProviderDescriptor, result: AssistantHandoffResult, options: {
+    expectedProvider: {
+        appId: string;
+        installationId: string;
+        key: string;
+    };
+}): {
+    target: PanelTarget | null;
+    destination: AppSurfaceRef;
+    reason?: "no_panel" | "ambiguous_surface";
+};
 export declare class AssistantClient {
     private readonly baseUrl;
     private readonly contract;

package/dist/assistant.js

@@ -1,3 +1,4 @@
+import { isSurfaceRoute, routeWithin } from "@hosty-sdk/app/ui/types";
 /** Preserve provider refusal details through app-owned server transports. */
 export class AssistantError extends Error {
     code;
@@ -27,7 +28,7 @@ export function createAssistantRequestId(now = Date.now()) {
 }
 /** Resolve only inside a declared UI surface on the selected app's resolved endpoint. */
 export function resolveAssistantDestination(destination, surfaces) {
-    if (!destination || typeof destination.path !== "string" || !destination.path.startsWith("/") || destination.path.startsWith("//") || /[\\\u0000-\u001f]/.test(destination.path))
+    if (!destination || !isSurfaceRoute(destination.path))
         throw new Error("Invalid assistant UI destination.");
     if (/%(?:2f|5c|25)/i.test(destination.path.split(/[?#]/, 1)[0]))
         throw new Error("Invalid assistant UI destination.");
@@ -42,6 +43,42 @@ export function resolveAssistantDestination(destination, surfaces) {
     }
     throw new Error("The assistant returned a destination outside its declared UI.");
 }
+/** Pure mapping after finalization; the presentation host separately checks current access. */
+export function resolveAssistantPresentation(provider, result, options) {
+    const expected = options.expectedProvider;
+    if (!provider.installationId)
+        throw new AssistantError("unsupported_core", "Update Core to identify assistant installations.", 409);
+    if (provider.appId !== expected.appId || provider.key !== expected.key || provider.installationId !== expected.installationId)
+        throw new AssistantError("provider_changed", "The original assistant installation is no longer available.", 409);
+    try {
+        resolveAssistantDestination(result.open, provider.uiSurfaces ?? []);
+    }
+    catch {
+        throw new AssistantError("destination_invalid", "The assistant returned an undeclared destination.", 409);
+    }
+    const destination = { appId: provider.appId, installationId: provider.installationId,
+        endpoint: result.open.endpoint, route: result.open.path };
+    const panels = (provider.uiSurfaces ?? []).filter(s => s.kind === "panel" && s.panelId && s.url
+        && s.endpoint === destination.endpoint && routeWithin(destination.route, s.path));
+    let selected;
+    if (result.open.panelId !== undefined) {
+        selected = panels.find(s => s.panelId === result.open.panelId);
+        if (!selected)
+            throw new AssistantError("destination_invalid", "The assistant panel does not match its destination.", 409);
+    }
+    else {
+        if (!panels.length)
+            return { target: null, destination, reason: "no_panel" };
+        const length = (path) => new URL(path, "https://surface.invalid").pathname.replace(/\/$/, "").length;
+        const longest = Math.max(...panels.map(s => length(s.path)));
+        const matches = panels.filter(s => length(s.path) === longest);
+        if (new Set(matches.map(s => s.panelId)).size !== 1)
+            return { target: null, destination, reason: "ambiguous_surface" };
+        selected = matches[0];
+    }
+    return { target: { panel: { appId: provider.appId, installationId: provider.installationId, panelId: selected.panelId },
+            route: destination.route }, destination };
+}
 export class AssistantClient {
     baseUrl;
     contract;

package/dist/overlay-react.d.ts

@@ -1,7 +1,9 @@
 import { type ReactNode } from "react";
 /** Mount once around protected content. Presentation and recovery belong to Hosty. */
-export declare function HostyOverlay({ children, probePath, appCodePath }: {
+export declare function HostyOverlay({ children, probePath, appCodePath, uiPath, panelLayout }: {
     children: ReactNode;
     probePath?: string;
     appCodePath?: string;
+    uiPath?: string;
+    panelLayout?: "auto" | "slot" | "none";
 }): import("react").JSX.Element;

package/dist/overlay-react.js

@@ -7,6 +7,7 @@ import { useAppActivity } from "./activity-react.js";
 import { APP_SESSION_ENDED, APP_SESSION_RESTORED, APP_ACTIVITY_RENEWED, acceptAppAuthProtocol } from "./browser-auth.js";
 import { buildCoreOpenUrl, readRecoveryParams } from "./index.js";
 import { permissionReviewUrl, requestPermissionReview } from "./permissions.js";
+import { HostyUiRoot } from "./ui-react.js";
 function snapshot(body) {
     const value = body;
     if (value?.status !== "active" || typeof value.userId !== "string" || !value.userId)
@@ -29,7 +30,7 @@ function sessionReady(session) {
     return session?.setup === "ready" && (!session.activityRequired || session.recoveryReady) && !activityExpired(session);
 }
 /** Mount once around protected content. Presentation and recovery belong to Hosty. */
-export function HostyOverlay({ children, probePath = "/api/hosty/session", appCodePath = "/api/auth/app-code" }) {
+export function HostyOverlay({ children, probePath = "/api/hosty/session", appCodePath = "/api/auth/app-code", uiPath, panelLayout = "auto" }) {
     const actor = useRef(null);
     const changingActor = useRef(false);
     const [session, setSession] = useState(null);
@@ -165,7 +166,7 @@ export function HostyOverlay({ children, probePath = "/api/hosty/session", appCo
         action = activity.renew;
         actionLabel = "Renew access";
     }
-    return _jsxs(_Fragment, { children: [_jsx("div", { "data-hosty-content": true, hidden: !ready, inert: !ready, style: ready ? { display: "contents" } : { display: "none" }, children: mounted.current ? children : null }), !ready && _jsx(OverlaySurface, { pending: pending, title: title, message: message, action: action, actionLabel: actionLabel, reviewUrl: reviewUrl })] });
+    return _jsxs(_Fragment, { children: [_jsx("div", { "data-hosty-content": true, hidden: !ready, inert: !ready, style: ready ? { display: "contents" } : { display: "none" }, children: _jsx(HostyUiRoot, { uiPath: uiPath, panelLayout: panelLayout, active: ready, children: mounted.current ? children : null }) }), !ready && _jsx(OverlaySurface, { pending: pending, title: title, message: message, action: action, actionLabel: actionLabel, reviewUrl: reviewUrl })] });
 }
 function OverlaySurface({ pending, title, message, action, actionLabel, reviewUrl }) {
     const [portal, setPortal] = useState(null);

package/dist/providers-server.d.ts

@@ -24,7 +24,9 @@ export declare class ProviderClient {
         signal?: AbortSignal;
     }): Promise<SpeechResult>;
     /** User-attributed requests preserve the assistant's existing handoff and dispatch policy. */
-    assistant(provider: Pick<ProviderDescriptor, "appId" | "key">, userToken: () => Promise<string>): Promise<AssistantClient>;
+    assistant(provider: Pick<ProviderDescriptor, "appId" | "key"> & {
+        installationId?: string | null;
+    }, userToken: () => Promise<string>): Promise<AssistantClient>;
     /** Provider-side validation checks live grants on every request; never cache this result. */
     validate(token: string, kind: ProviderKind, key?: string, signal?: AbortSignal): Promise<ProviderInvocation>;
 }

package/dist/providers-server.js

@@ -31,6 +31,8 @@ export class ProviderClient {
         const issued = await this.coreRequest(`/providers/${provider.kind}/token`, { providerAppId: provider.appId, key: provider.key }, signal, userToken);
         if (issued.provider.version !== 1 || !issued.provider.url)
             throw new ProviderError("provider_incompatible", "This provider does not support interface version 1.", 409);
+        if (provider.installationId && issued.provider.installationId !== provider.installationId)
+            throw new ProviderError("provider_changed", "The selected assistant installation changed. Start a new discussion explicitly.", 409);
         const url = new URL(issued.provider.url);
         if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
             throw new ProviderError("provider_url_invalid", "Invalid provider endpoint.", 409);
@@ -58,8 +60,8 @@ export class ProviderClient {
         const binding = await this.connect(target, undefined, await userToken());
         return new AssistantClient(binding.url, { version: binding.provider.version, capabilities: binding.provider.capabilities }, async () => {
             const fresh = await this.connect(target, undefined, await userToken());
-            if (fresh.url !== binding.url)
-                throw new ProviderError("provider_changed", "The assistant endpoint changed. Reconnect explicitly.", 409);
+            if (fresh.url !== binding.url || fresh.provider.installationId !== binding.provider.installationId)
+                throw new ProviderError("provider_changed", "The assistant endpoint or installation changed. Reconnect explicitly.", 409);
             return { token: fresh.token };
         });
     }

package/dist/providers.d.ts

@@ -9,6 +9,16 @@ 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;
+        kind?: "panel" | "navigation" | "entrypoint";
+        panelId?: string | null;
+    }> | null;
+    /** Opaque Core installation identity; compare for equality, never parse. */
+    installationId?: string | null;
 };
 export type AppPermissionState = {
     required: string[];

package/dist/server.d.ts

@@ -47,6 +47,11 @@ export declare function getAppId(config: HostyAppConfig): string;
 export declare function createHostySessionRouteHandler(config: HostyAppConfig, options?: {
     administratorOnly?: boolean;
 }): (request: Request) => Promise<Response>;
+/** Mount GET/POST at /api/hosty/ui/[...action] for the shared panel protocol. */
+export declare function createHostyUiRouteHandler(config: HostyAppConfig, options?: {
+    administratorOnly?: boolean;
+    uiPath?: string;
+}): (request: Request) => Promise<Response>;
 export declare function getCoreOrigin(): string | null;
 /** Browser-reachable Core origin. Core always injects it (falls back to its loopback
  * listen URL on localhost-only installs), so a missing value is a broken environment. */

package/dist/server.js

@@ -2,6 +2,7 @@
 // bundle — the service token lives here.
 import "server-only";
 import { createHostySessionResponse } from "./session-server.js";
+import { createHostyUiResponse } from "./ui-server.js";
 import { resolveAppAuthProtocol, appAuthProtocolMinimum, isValidCodeVerifier } from "./app-code.js";
 export { isValidCodeVerifier } from "./app-code.js";
 import { classifyRevalidationHttpStatus, } from "./index.js";
@@ -28,6 +29,14 @@ export function createHostySessionRouteHandler(config, options = {}) {
         return createHostySessionResponse(session, recovery, { ...options, signal: request.signal });
     };
 }
+/** Mount GET/POST at /api/hosty/ui/[...action] for the shared panel protocol. */
+export function createHostyUiRouteHandler(config, options = {}) {
+    return async (request) => {
+        const token = readAppIdentityToken(request.headers, config);
+        const session = await resolveAppSession(token, config);
+        return createHostyUiResponse(request, { session, token }, { ...options, appId: getAppId(config) });
+    };
+}
 export function getCoreOrigin() {
     return process.env.HOSTY_CORE_ORIGIN?.trim() || null;
 }

package/dist/ui-context.d.ts

@@ -0,0 +1,2 @@
+import type { UiHost } from "./ui-host.js";
+export declare const UiHostContext: import("react").Context<UiHost | null>;

package/dist/ui-context.js

@@ -0,0 +1,3 @@
+"use client";
+import { createContext } from "react";
+export const UiHostContext = createContext(null);

package/dist/ui-embedded.d.ts

@@ -0,0 +1,45 @@
+import { type UiClient } from "./ui.js";
+import { type PanelTarget, type PresentationOptions, type PresentationResult, type UiEnvironment, type UiEvent } from "./ui-types.js";
+/** Direct-child transport. Discovery carries no identity and never creates a fallback host. */
+export declare class EmbeddedUiClient implements UiClient {
+    private readonly path;
+    private environment;
+    private nonce;
+    private readonly listeners;
+    private readonly pending;
+    private channel;
+    private verifying;
+    private disposed;
+    private deadline;
+    private retries;
+    private state;
+    private active;
+    private offered;
+    private readonly onMessage;
+    private readonly onFocus;
+    private readonly onKey;
+    constructor(path: string);
+    getEnvironment: () => UiEnvironment;
+    setActive(active: boolean): void;
+    subscribe: (listener: (event: UiEvent) => void) => () => void;
+    private emit;
+    private retirePending;
+    private setEnvironment;
+    private probe;
+    private discover;
+    private post;
+    private recheck;
+    private receive;
+    private request;
+    private wait;
+    openSurface: (target: PanelTarget, options: PresentationOptions) => Promise<PresentationResult>;
+    getPresentation: (requestId: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<PresentationResult>;
+    reportSurfaceState: (state: {
+        route: string;
+        state: "ready" | "blocked";
+        code?: string;
+    }) => void;
+    dispose: () => void;
+}

package/dist/ui-embedded.js

@@ -0,0 +1,278 @@
+import { createPresentationRequestId } from "./ui.js";
+import { UiError } from "./ui-types.js";
+import { DISCOVERY_TIMEOUT, failure, readUiMessage, uiRequest, validId, validTarget, waitForPresentation } from "./ui-transport.js";
+/** Direct-child transport. Discovery carries no identity and never creates a fallback host. */
+export class EmbeddedUiClient {
+    path;
+    environment = { mode: "embedded", connection: "connecting" };
+    nonce = createPresentationRequestId();
+    listeners = new Set();
+    pending = new Map();
+    channel = null;
+    verifying = null;
+    disposed = false;
+    deadline;
+    retries = [];
+    state = null;
+    active = true;
+    offered = false;
+    onMessage = (event) => { void this.receive(event); };
+    onFocus = () => { void this.recheck(); };
+    onKey = (event) => { if (this.active && !event.defaultPrevented && event.key === "Escape")
+        this.post({ type: "hosty:ui:dismiss" }); };
+    constructor(path) {
+        this.path = path;
+        window.addEventListener("message", this.onMessage);
+        window.addEventListener("focus", this.onFocus);
+        window.addEventListener("keydown", this.onKey);
+        this.discover();
+        if (window.parent !== window.top)
+            this.setEnvironment("unsupported", "unsupported_nesting");
+    }
+    getEnvironment = () => this.environment;
+    setActive(active) {
+        if (this.active === active)
+            return;
+        if (!active)
+            this.post({ type: "hosty:ui:auth-required" });
+        this.active = active;
+        this.channel = null;
+        this.verifying = null;
+        this.nonce = createPresentationRequestId();
+        clearTimeout(this.deadline);
+        this.retries.forEach(clearTimeout);
+        if (!active) {
+            for (const [requestId, entry] of this.pending)
+                entry.resolve(entry.sent
+                    ? { status: "uncertain", requestId, code: "presentation_unknown" }
+                    : { status: "blocked", requestId, code: "activity_required" });
+            this.pending.clear();
+            this.setEnvironment("blocked", "activity_required");
+        }
+        else {
+            this.setEnvironment("connecting");
+            this.discover();
+        }
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        listener({ type: "environment", value: this.environment });
+        return () => { this.listeners.delete(listener); };
+    };
+    emit(event) { if (!this.disposed)
+        for (const listener of this.listeners)
+            listener(event); }
+    retirePending() {
+        for (const [requestId, entry] of this.pending)
+            entry.resolve(entry.sent
+                ? { status: "uncertain", requestId, code: "presentation_unknown" }
+                : { status: "unsupported", requestId, code: "host_unavailable" });
+    }
+    setEnvironment(connection, code) {
+        if (this.disposed)
+            return;
+        this.environment = { mode: "embedded", connection, ...(code ? { code } : {}) };
+        this.emit({ type: "environment", value: this.environment });
+    }
+    probe() {
+        if (this.active && !this.disposed && window.parent === window.top && !this.channel)
+            window.parent.postMessage({ type: "hosty:ui:probe", version: 1, versions: [1], childNonce: this.nonce }, "*");
+    }
+    discover() {
+        clearTimeout(this.deadline);
+        this.retries.forEach(clearTimeout);
+        this.deadline = setTimeout(() => {
+            if (this.environment.connection === "connecting")
+                this.setEnvironment(this.offered ? "blocked" : "unsupported", "host_unavailable");
+        }, DISCOVERY_TIMEOUT);
+        this.probe();
+        this.retries = [150, 500, 1500].map(delay => setTimeout(() => this.probe(), delay));
+    }
+    post(value) {
+        const channel = this.channel;
+        if (!channel || !this.active || this.disposed)
+            return;
+        window.parent.postMessage({ version: 1, childNonce: this.nonce, hostWindowId: channel.hostWindowId, generation: channel.generation, ...value }, channel.origin);
+    }
+    async recheck() {
+        const channel = this.channel;
+        if (!this.active || !channel || this.environment.connection !== "connected")
+            return false;
+        try {
+            const own = await uiRequest(this.path, `bootstrap?parentOrigin=${encodeURIComponent(channel.origin)}`);
+            if (this.disposed || this.channel !== channel)
+                return false;
+            if (own.userId !== channel.own.userId || own.coreOrigin !== channel.own.coreOrigin || own.app.installationId !== channel.own.app.installationId
+                || own.peer?.installationId !== channel.own.peer?.installationId || own.peer?.appId !== channel.own.peer?.appId)
+                throw new UiError("actor_mismatch", "Reconnect using the same Hosty account.");
+            return true;
+        }
+        catch (error) {
+            if (this.channel !== channel || this.disposed)
+                return false;
+            this.post({ type: "hosty:ui:surface-state", route: this.state?.route, state: "auth-required" });
+            this.setEnvironment("blocked", error instanceof UiError ? error.code : "ui_unavailable");
+            return false;
+        }
+    }
+    async receive(event) {
+        const msg = readUiMessage(event.data);
+        if (!msg || !this.active || event.source !== window.parent || window.parent !== window.top || event.origin === "null" || this.disposed)
+            return;
+        if (msg.type === "hosty:ui:probe-request") {
+            if (this.channel && event.origin === this.channel.origin && (msg.generation !== this.channel.generation || msg.hostWindowId !== this.channel.hostWindowId)) {
+                this.retirePending();
+                this.channel = null;
+                this.setEnvironment("connecting");
+                this.discover();
+            }
+            if (this.channel) {
+                void this.recheck();
+                return;
+            }
+            this.probe();
+            return;
+        }
+        if (msg.childNonce !== this.nonce || !validId(msg.hostWindowId) || !validId(msg.generation))
+            return;
+        if (msg.type === "hosty:ui:offer") {
+            this.offered = true;
+            if (this.channel?.origin === event.origin && this.channel.hostWindowId === msg.hostWindowId
+                && this.channel.generation === msg.generation && this.environment.connection === "connected")
+                return;
+            const key = `${this.nonce}:${event.origin}:${msg.hostWindowId}:${msg.generation}`;
+            if (this.verifying === key)
+                return;
+            this.verifying = key;
+            try {
+                const own = await uiRequest(this.path, `bootstrap?parentOrigin=${encodeURIComponent(event.origin)}`);
+                if (this.disposed || !this.active || this.verifying !== key)
+                    return;
+                if (own.version !== 1 || !own.userId || !own.peer?.origins.includes(event.origin))
+                    throw new UiError("host_untrusted", "Hosty cannot verify this host.");
+                const previous = this.channel;
+                if (previous && (previous.origin !== event.origin || previous.hostWindowId !== msg.hostWindowId || previous.generation !== msg.generation))
+                    this.retirePending();
+                this.channel = { origin: event.origin, hostWindowId: msg.hostWindowId, generation: msg.generation, own };
+                this.post({ type: "hosty:ui:accept", coreOrigin: own.coreOrigin, userId: own.userId, appId: own.app.appId, installationId: own.app.installationId });
+            }
+            catch (error) {
+                if (this.disposed || !this.active || this.verifying !== key)
+                    return;
+                const code = error instanceof UiError ? error.code : "ui_unavailable";
+                this.setEnvironment(code.startsWith("unsupported") ? "unsupported" : "blocked", code);
+            }
+            finally {
+                if (this.verifying === key)
+                    this.verifying = null;
+            }
+            return;
+        }
+        const channel = this.channel;
+        if (!channel || event.origin !== channel.origin || msg.hostWindowId !== channel.hostWindowId || msg.generation !== channel.generation)
+            return;
+        if (msg.type === "hosty:ui:connected") {
+            const own = channel.own;
+            if (msg.code || msg.coreOrigin !== own.coreOrigin || msg.userId !== own.userId || msg.appId !== own.peer?.appId || msg.installationId !== own.peer?.installationId) {
+                this.setEnvironment("blocked", "actor_mismatch");
+                return;
+            }
+            clearTimeout(this.deadline);
+            this.setEnvironment("connected");
+            if (this.state)
+                this.reportSurfaceState(this.state);
+            return;
+        }
+        if (this.environment.connection !== "connected")
+            return;
+        if (msg.type === "hosty:ui:result" && validId(msg.requestId) && validResult(msg.result, msg.requestId)) {
+            const result = msg.result;
+            this.pending.get(msg.requestId)?.resolve(result);
+            this.emit({ type: "presentation", value: result });
+        }
+    }
+    async request(requestId, message, signal) {
+        if (!validId(requestId))
+            return { status: "rejected", requestId, code: "invalid_presentation" };
+        if (!this.active)
+            return { status: "blocked", requestId, code: "activity_required" };
+        if (signal?.aborted)
+            return { status: "uncertain", requestId, code: "presentation_unknown" };
+        const target = message.target;
+        const input = target ? JSON.stringify([target.panel.appId, target.panel.installationId, target.panel.panelId, target.route ?? null]) : null;
+        const existing = this.pending.get(requestId);
+        if (existing) {
+            if (input !== null && existing.input !== null && input !== existing.input)
+                return { status: "rejected", requestId, code: "request_conflict" };
+            // A status response cannot satisfy an opening dispatched later. Finish that query first;
+            // status queried during an opening can simply share the in-flight operation's result.
+            if (input !== null && existing.input === null) {
+                const result = await this.wait(requestId, existing, signal);
+                if (this.pending.get(requestId) === existing)
+                    return result;
+                return this.request(requestId, message, signal);
+            }
+            return this.wait(requestId, existing, signal);
+        }
+        if (this.pending.size >= 4)
+            return { status: "blocked", requestId, code: "presentation_busy" };
+        let settle;
+        const operation = new Promise(resolve => { settle = resolve; });
+        const entry = { input, operation, waiters: 0, sent: false, resolve: result => {
+                if (this.pending.get(requestId) === entry)
+                    this.pending.delete(requestId);
+                settle(result);
+            } };
+        // Reserve identity before asynchronous revalidation so racing callers cannot share
+        // different payloads or overwrite each other's completion/cleanup handlers.
+        this.pending.set(requestId, entry);
+        void this.recheck().then(verified => {
+            if (this.pending.get(requestId) !== entry)
+                return;
+            if (!verified)
+                entry.resolve({ status: this.environment.connection === "blocked" ? "blocked" : "unsupported", requestId, code: this.environment.code ?? "host_unavailable" });
+            else {
+                entry.sent = true;
+                this.post({ ...message, requestId });
+            }
+        });
+        return this.wait(requestId, entry, signal);
+    }
+    wait(requestId, entry, signal) {
+        entry.waiters++;
+        return waitForPresentation(entry.operation, requestId, signal).finally(() => {
+            // Ending a caller's wait does not cancel a sent message. Keep its reservation until
+            // its response arrives or the channel is retired, so it cannot settle newer work.
+            if (--entry.waiters === 0 && !entry.sent && this.pending.get(requestId) === entry)
+                this.pending.delete(requestId);
+        });
+    }
+    openSurface = (target, options) => validTarget(target) && options.placement === "side"
+        ? this.request(options.requestId, { type: "hosty:ui:open", target, placement: "side" }, options.signal)
+        : Promise.resolve({ status: "rejected", requestId: options.requestId, code: "invalid_presentation" });
+    getPresentation = (requestId, options) => this.request(requestId, { type: "hosty:ui:status" }, options?.signal);
+    reportSurfaceState = (state) => {
+        this.state = state;
+        if (this.environment.connection === "connected")
+            this.post({ type: "hosty:ui:surface-state", ...state });
+    };
+    dispose = () => {
+        this.disposed = true;
+        clearTimeout(this.deadline);
+        this.retries.forEach(clearTimeout);
+        window.removeEventListener("message", this.onMessage);
+        window.removeEventListener("focus", this.onFocus);
+        window.removeEventListener("keydown", this.onKey);
+        for (const [id, entry] of this.pending)
+            entry.resolve(failure(id, new UiError("host_unavailable", "Host disconnected.")));
+        this.pending.clear();
+        this.listeners.clear();
+    };
+}
+function validResult(value, id) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return v.requestId === id && (v.status === "opened" ? validTarget(v.target) && ["loading", "ready", "unreported", "auth-required"].includes(v.readiness)
+        : ["blocked", "unsupported", "rejected", "uncertain", "unknown"].includes(v.status) && "code" in v && typeof v.code === "string");
+}

package/dist/ui-frame.d.ts

@@ -0,0 +1,30 @@
+import { type HostyResolvedTheme, type HostyThemePreference } from "./theme.js";
+import type { UiFrameSurface } from "./ui-types.js";
+export declare function parseFrameMcpReview(event: {
+    source: unknown;
+    origin: string;
+    data: unknown;
+}, frame: unknown, src: string, appId: string): {
+    appId: string;
+    targetAppId: string;
+} | null;
+export declare function frameSandbox(policy: UiFrameSurface["framePolicy"]): string;
+export type HostyAppFrameProps = {
+    surface: UiFrameSurface;
+    title: string;
+    src?: string;
+    className?: string;
+    theme?: HostyResolvedTheme;
+    themePreference?: HostyThemePreference;
+    standaloneHref?: string | null;
+    onAskAssistant?: (text: string, appId: string) => void;
+    onAttention?: (count: number) => void;
+    onAuthRequired?: (appId: string) => void;
+    onMessage?: (event: MessageEvent, frame: Window | null) => void;
+    outbound?: {
+        message: unknown;
+        nonce: number;
+    } | null;
+};
+/** Shared frame coordinator. No delegated-token responder and no authority inferred from messages. */
+export declare function HostyAppFrame(props: HostyAppFrameProps): import("react").JSX.Element;