@hosty-sdk/app 0.23.0 → 0.25.12

package/dist/ui-frame.js

@@ -0,0 +1,104 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useContext, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { UiHostContext } from "./ui-context.js";
+import { appendThemeLaunchParams, parseActiveFrameAskAssistant, parseActiveFrameAttention, parseActiveFrameAuthRequired, parseActiveFramePermissionReview } from "./embedder.js";
+import { createShellThemeMessage } from "./theme.js";
+import { permissionReviewUrl } from "./permissions.js";
+export function parseFrameMcpReview(event, frame, src, appId) {
+    if (!frame || event.source !== frame || !event.data || typeof event.data !== "object")
+        return null;
+    try {
+        if (event.origin !== new URL(src).origin)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const data = event.data;
+    return data.type === "hosty:request-mcp-review" && typeof data.targetAppId === "string" && /^[a-zA-Z0-9._:-]{1,128}$/.test(data.targetAppId)
+        ? { appId, targetAppId: data.targetAppId } : null;
+}
+export function frameSandbox(policy) {
+    return "allow-scripts allow-same-origin allow-forms allow-popups allow-downloads" + (policy.popupEscape ? " allow-popups-to-escape-sandbox" : "");
+}
+/** Shared frame coordinator. No delegated-token responder and no authority inferred from messages. */
+export function HostyAppFrame(props) {
+    const { surface, title, className, standaloneHref, theme, themePreference } = props;
+    const host = useContext(UiHostContext);
+    const ref = useRef(null);
+    const callbacks = useRef(props);
+    callbacks.current = props;
+    const [review, setReview] = useState(null);
+    const [loaded, setLoaded] = useState(false);
+    const [connection, setConnection] = useState({ ready: false, generation: 0 });
+    const [appearance, setAppearance] = useState({ theme: "light", preference: "system" });
+    useEffect(() => {
+        const read = () => {
+            const root = document.documentElement;
+            setAppearance({
+                theme: root.classList.contains("dark") || root.dataset.hostyTheme === "dark" ? "dark" : "light",
+                preference: root.dataset.hostyThemePreference === "dark" ? "dark" : root.dataset.hostyThemePreference === "light" ? "light" : "system"
+            });
+        };
+        read();
+        const observer = new MutationObserver(read);
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-hosty-theme", "data-hosty-theme-preference"] });
+        return () => observer.disconnect();
+    }, []);
+    const resolvedTheme = theme ?? appearance.theme, preference = themePreference ?? appearance.preference;
+    const source = props.src ?? new URL(surface.route, surface.origin).href;
+    // Theme changes are messages; they must not replace a document with an unsent draft.
+    const [launch] = useState(() => {
+        const url = new URL(source);
+        url.searchParams.set("hosty_launch", "embedded");
+        return appendThemeLaunchParams(url.href, resolvedTheme, preference);
+    });
+    const frameId = JSON.stringify([surface, source]);
+    useLayoutEffect(() => {
+        const frame = ref.current;
+        if (!frame || !host)
+            return;
+        return host.registerFrame(frame, surface, ready => setConnection(current => ({ ready, generation: current.generation + (ready ? 1 : 0) })));
+    }, [host, frameId]); // Caller keys the frame by this immutable surface.
+    useEffect(() => {
+        if (loaded)
+            ref.current?.contentWindow?.postMessage(createShellThemeMessage(resolvedTheme, preference), surface.origin);
+    }, [loaded, resolvedTheme, preference, surface.origin]);
+    useEffect(() => {
+        const handle = (event) => {
+            const frame = ref.current?.contentWindow ?? null;
+            if (!frame || event.source !== frame || event.origin !== surface.origin)
+                return;
+            const current = callbacks.current;
+            if (parseActiveFrameAuthRequired(event, frame, source, surface.appId))
+                current.onAuthRequired?.(surface.appId);
+            const ask = parseActiveFrameAskAssistant(event, frame, source);
+            if (ask)
+                current.onAskAssistant?.(ask.text, surface.appId);
+            const attention = parseActiveFrameAttention(event, frame, source);
+            if (attention !== null)
+                current.onAttention?.(attention);
+            const permission = parseActiveFramePermissionReview(event, frame, source, surface.appId);
+            const mcp = parseFrameMcpReview(event, frame, source, surface.appId);
+            const core = host?.getSnapshot().bootstrap?.coreOrigin;
+            if (core && (permission || mcp)) {
+                const url = mcp ? new URL(`/install/agents/${encodeURIComponent(mcp.appId)}/${encodeURIComponent(mcp.targetAppId)}`, core).href : permissionReviewUrl(core, surface.appId);
+                setReview(url);
+                window.open(url, "_blank", "noopener,noreferrer");
+            }
+            current.onMessage?.(event, frame);
+        };
+        window.addEventListener("message", handle);
+        return () => window.removeEventListener("message", handle);
+    }, [host, frameId, source, surface]);
+    const outboundReady = host ? connection.ready : loaded;
+    useEffect(() => {
+        if (outboundReady && props.outbound)
+            ref.current?.contentWindow?.postMessage(props.outbound.message, surface.origin);
+    }, [outboundReady, connection.generation, props.outbound?.nonce, surface.origin]);
+    const insecure = typeof window !== "undefined" && window.location.protocol === "https:" && new URL(surface.origin).protocol === "http:";
+    if (insecure)
+        return _jsxs("div", { role: "status", className: "hosty-panel-notice", children: [_jsxs("strong", { children: [title, " needs HTTPS to appear here"] }), _jsx("p", { children: "This app publishes an HTTP address. Configure its public HTTPS origin in Hosty." }), /^(localhost|127\.|\[::1\])/.test(new URL(surface.origin).hostname) && _jsx("p", { children: "This local address is reachable only from the Hosty computer." }), standaloneHref && _jsx("a", { href: standaloneHref, target: "_blank", rel: "noopener noreferrer", children: "Open separately" })] });
+    return _jsxs(_Fragment, { children: [review && _jsx("a", { className: "hosty-panel-review", href: review, target: "_blank", rel: "noopener noreferrer", children: "Review access in Core" }), _jsx("iframe", { ref: ref, className: className, title: title, src: launch, sandbox: frameSandbox(surface.framePolicy), allow: surface.framePolicy.microphone ? "clipboard-write; microphone 'src'" : "clipboard-write", style: { border: 0, height: "100%", width: "100%", colorScheme: resolvedTheme }, onLoad: () => setLoaded(true) })] });
+}

package/dist/ui-host.d.ts

@@ -0,0 +1,80 @@
+import { type UiClient } from "./ui.js";
+import { type PanelRef, type PanelTarget, type PresentationOptions, type PresentationResult, type UiBootstrap, type UiEnvironment, type UiEvent, type UiFrameSurface, type UiPanel, type UiResolvedPanel, type SurfaceReadiness } from "./ui-types.js";
+export type UiTool = {
+    key: string;
+    target: PanelTarget;
+    resolved: UiResolvedPanel;
+    readiness: SurfaceReadiness;
+    attention: number;
+};
+export type UiHostSnapshot = {
+    bootstrap: UiBootstrap | null;
+    catalog: UiPanel[];
+    tools: UiTool[];
+    selected: PanelRef | null;
+    expanded: boolean;
+    width: number;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+};
+/** One top-level composition owner. All Core traffic goes through this app's authenticated adapter. */
+export declare function createUiHost(options?: {
+    uiPath?: string;
+    active?: boolean;
+}): UiHost;
+export declare class UiHost implements UiClient {
+    private readonly path;
+    private active;
+    private snapshot;
+    private environment;
+    private readonly windowId;
+    private readonly listeners;
+    private readonly events;
+    private readonly frames;
+    private readonly ledger;
+    private readonly toolQueues;
+    private selectionGeneration;
+    private activityGeneration;
+    private activityReady;
+    private disposed;
+    private workspace;
+    private refreshing;
+    private readonly onMessage;
+    private readonly onFocus;
+    constructor(path: string, active?: boolean);
+    getEnvironment: () => UiEnvironment;
+    setActive(active: boolean): void;
+    private checkActivity;
+    claimWorkspace: (owner: object) => () => void;
+    getSnapshot: () => UiHostSnapshot;
+    subscribeSnapshot: (listener: () => void) => () => void;
+    subscribe: (listener: (event: UiEvent) => void) => () => void;
+    private emit;
+    private update;
+    private setEnvironment;
+    private bootstrap;
+    refresh: () => Promise<void>;
+    openSurface: (target: PanelTarget, options: PresentationOptions) => Promise<PresentationResult>;
+    private open;
+    getPresentation: (id: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<PresentationResult>;
+    private status;
+    selectPanel: (ref: PanelRef) => Promise<PresentationResult>;
+    setExpanded: (expanded: boolean) => void;
+    setWidth: (width: number) => void;
+    setAttention: (panel: PanelRef, attention: number) => void;
+    reportSurfaceState: (_state: {
+        route: string;
+        state: "ready" | "blocked";
+        code?: string;
+    }) => void;
+    private forgetFrameRequests;
+    registerFrame: (element: HTMLIFrameElement, surface: UiFrameSurface, onConnection?: (connected: boolean) => void) => (() => void);
+    private post;
+    private reportFrame;
+    private receive;
+    dispose: () => void;
+}

package/dist/ui-host.js

@@ -0,0 +1,439 @@
+import { createPresentationRequestId } from "./ui.js";
+import { UiError, panelKey, routeWithin } from "./ui-types.js";
+import { canonicalSurfaceRoute, DISCOVERY_TIMEOUT, failure, readUiMessage, uiPath, uiRequest, validId, validTarget, waitForPresentation } from "./ui-transport.js";
+let documentHost = null;
+/** One top-level composition owner. All Core traffic goes through this app's authenticated adapter. */
+export function createUiHost(options = {}) {
+    if (typeof window === "undefined" || window.parent !== window)
+        throw new Error("A panel host belongs to a top-level browser document.");
+    if (documentHost)
+        throw new Error("A Hosty panel host already owns this document.");
+    const host = new UiHost(uiPath(options.uiPath), options.active);
+    documentHost = host;
+    return host;
+}
+export class UiHost {
+    path;
+    active;
+    snapshot = { bootstrap: null, catalog: [], tools: [], selected: null, expanded: false, width: 360, error: null };
+    environment = { mode: "standalone", connection: "connecting" };
+    windowId = createPresentationRequestId();
+    listeners = new Set();
+    events = new Set();
+    frames = new Set();
+    ledger = new Map();
+    toolQueues = new Map();
+    selectionGeneration = 0;
+    activityGeneration = 0;
+    activityReady;
+    disposed = false;
+    workspace = null;
+    refreshing = null;
+    onMessage = (event) => { void this.receive(event); };
+    onFocus = () => { void this.refresh(); };
+    constructor(path, active = true) {
+        this.path = path;
+        this.active = active;
+        this.activityReady = active;
+        window.addEventListener("message", this.onMessage);
+        window.addEventListener("focus", this.onFocus);
+        if (active)
+            void this.refresh();
+        else
+            this.setEnvironment("blocked", "activity_required");
+    }
+    getEnvironment = () => this.environment;
+    setActive(active) {
+        if (this.disposed || this.active === active)
+            return;
+        this.active = active;
+        this.activityReady = false;
+        this.activityGeneration++;
+        this.selectionGeneration++;
+        this.refreshing = null;
+        this.toolQueues.clear();
+        for (const [key, entry] of this.ledger)
+            if (entry.pending || entry.frame)
+                this.ledger.delete(key);
+        for (const frame of this.frames) {
+            frame.connected = false;
+            frame.actor = null;
+            frame.nonce = null;
+            frame.onConnection?.(false);
+            frame.generation = createPresentationRequestId();
+        }
+        this.setEnvironment(active ? "connecting" : "blocked", active ? undefined : "activity_required");
+        if (active)
+            void this.refresh();
+    }
+    checkActivity(generation, renewing = false) {
+        if (this.disposed || !this.active || generation !== this.activityGeneration || !renewing && !this.activityReady)
+            throw new UiError("activity_required", "Renew this app's activity before opening panels.");
+    }
+    claimWorkspace = (owner) => {
+        if (this.workspace && this.workspace !== owner)
+            throw new Error("Exactly one panel workspace may occupy this host.");
+        this.workspace = owner;
+        return () => { if (this.workspace === owner)
+            this.workspace = null; };
+    };
+    getSnapshot = () => this.snapshot;
+    subscribeSnapshot = (listener) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+    subscribe = (listener) => {
+        this.events.add(listener);
+        listener({ type: "environment", value: this.environment });
+        return () => { this.events.delete(listener); };
+    };
+    emit(event) { if (!this.disposed)
+        for (const listener of this.events)
+            listener(event); }
+    update(patch) {
+        if (this.disposed)
+            return;
+        this.snapshot = { ...this.snapshot, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+    setEnvironment(connection, code) {
+        this.environment = { mode: "standalone", connection, ...(code ? { code } : {}) };
+        this.emit({ type: "environment", value: this.environment });
+    }
+    async bootstrap(generation = this.activityGeneration, renewing = false) {
+        this.checkActivity(generation, renewing);
+        const value = await uiRequest(this.path, "bootstrap");
+        this.checkActivity(generation, renewing);
+        if (value.version !== 1 || !value.app?.installationId || !value.userId)
+            throw new UiError("unsupported_app", "Unsupported panel metadata.");
+        const previous = this.snapshot.bootstrap;
+        if (previous && (previous.userId !== value.userId || previous.coreOrigin !== value.coreOrigin || previous.app.installationId !== value.app.installationId)) {
+            this.ledger.clear();
+            this.toolQueues.clear();
+            for (const frame of this.frames) {
+                frame.connected = false;
+                frame.actor = null;
+                frame.nonce = null;
+                frame.onConnection?.(false);
+                frame.generation = createPresentationRequestId();
+                this.post(frame, { type: "hosty:ui:probe-request" });
+            }
+            this.update({ tools: [], selected: null, expanded: false });
+        }
+        this.update({ bootstrap: value });
+        return value;
+    }
+    refresh = () => {
+        if (!this.active || this.disposed)
+            return Promise.resolve();
+        if (this.refreshing)
+            return this.refreshing;
+        const generation = this.activityGeneration;
+        const operation = (async () => {
+            try {
+                const own = await this.bootstrap(generation, true);
+                this.checkActivity(generation, true);
+                if (!own.canHost) {
+                    this.setEnvironment("unsupported", "app_permission_required");
+                    this.update({ catalog: [], tools: [], selected: null, expanded: false });
+                    return;
+                }
+                const catalog = await uiRequest(this.path, "panels");
+                this.checkActivity(generation, true);
+                if (!Array.isArray(catalog.panels))
+                    throw new UiError("ui_response_invalid", "Invalid panel catalog.");
+                this.activityReady = true;
+                this.update({ catalog: catalog.panels, error: null });
+                this.setEnvironment("connected");
+                // Catalog disappearance/replacement is access loss, while temporary readiness loss retains drafts.
+                const allowed = new Map(catalog.panels.map(p => [panelKey(p.panel), p]));
+                this.update({ tools: this.snapshot.tools.map(tool => {
+                        const entry = allowed.get(tool.key);
+                        const invalid = !entry || !["running", "degraded", "unavailable", "starting", "stopping"].includes(entry.state);
+                        const surface = tool.resolved.surface;
+                        const changed = entry && surface && JSON.stringify(entry.framePolicy) !== JSON.stringify(surface.framePolicy);
+                        const moved = entry && surface && (entry.origin !== surface.origin || entry.endpoint !== surface.endpoint
+                            || !routeWithin(surface.route, entry.route));
+                        return invalid || changed || moved ? { ...tool, resolved: { ...tool.resolved, available: false, surface: null,
+                                state: !entry ? "access_unavailable" : changed ? "policy_changed" : moved ? "destination_changed" : entry.state } }
+                            : entry && surface ? { ...tool, resolved: { ...tool.resolved, available: entry.available, state: entry.state } } : tool;
+                    }) });
+                for (const frame of this.frames)
+                    this.post(frame, { type: "hosty:ui:probe-request" });
+            }
+            catch (error) {
+                if (!this.active || this.disposed || generation !== this.activityGeneration)
+                    return;
+                const code = error instanceof UiError ? error.code : "ui_unavailable";
+                this.update({ error: { code, message: error instanceof Error ? error.message : "Panel metadata is unavailable." } });
+                this.setEnvironment(code.startsWith("unsupported") ? "unsupported" : "blocked", code);
+            }
+        })().finally(() => { if (this.refreshing === operation)
+            this.refreshing = null; });
+        this.refreshing = operation;
+        return operation;
+    };
+    openSurface = (target, options) => waitForPresentation(this.open(target, options, "local"), options.requestId, options.signal);
+    open(target, options, source, frame) {
+        const id = options.requestId;
+        if (!this.active || !this.activityReady || this.disposed)
+            return Promise.resolve({ status: "blocked", requestId: id, code: "activity_required" });
+        const generation = this.activityGeneration;
+        if (!validId(id) || !validTarget(target) || options.placement !== "side")
+            return Promise.resolve({ status: "rejected", requestId: id, code: "invalid_presentation" });
+        const key = `${source}:${id}`, input = JSON.stringify([target.panel.appId, target.panel.installationId, target.panel.panelId, target.route ?? null]);
+        const existing = this.ledger.get(key);
+        if (existing && existing.input !== input)
+            return Promise.resolve({ status: "rejected", requestId: id, code: "request_conflict" });
+        if (existing?.pending)
+            return existing.pending;
+        if ([...this.ledger.entries()].filter(([k, v]) => k.startsWith(source + ":") && v.pending).length >= 4)
+            return Promise.resolve({ status: "blocked", requestId: id, code: "presentation_busy" });
+        const entry = { input, frame };
+        const selectionGeneration = ++this.selectionGeneration;
+        const currentSource = () => !frame || source === `${frame.surface.appId}:${frame.generation}:${frame.nonce}`;
+        const toolKey = panelKey(target.panel), previous = this.toolQueues.get(toolKey);
+        const operation = (async () => {
+            if (previous)
+                await previous;
+            try {
+                const own = await this.bootstrap(generation);
+                this.checkActivity(generation);
+                if (!own.canHost)
+                    throw new UiError("app_permission_required", "Allow this app to host panels.");
+                if (frame && (!frame.live || !frame.connected || frame.actor !== own.userId || !currentSource()))
+                    throw new UiError("actor_mismatch", "Reconnect using the same account.");
+                const resolved = await uiRequest(this.path, "panels/resolve", target);
+                this.checkActivity(generation);
+                if (this.disposed || this.snapshot.bootstrap?.userId !== own.userId || this.snapshot.bootstrap?.coreOrigin !== own.coreOrigin || this.snapshot.bootstrap?.app.installationId !== own.app.installationId
+                    || frame && (!frame.live || !frame.connected || frame.actor !== own.userId || !currentSource()))
+                    throw new UiError("actor_mismatch", "The signed-in account changed.");
+                if (!resolved.available || !resolved.surface)
+                    throw new UiError(resolved.state || "destination_unavailable", "The selected panel is unavailable.");
+                const insecure = window.location.protocol === "https:" && new URL(resolved.surface.origin).protocol === "http:";
+                if (selectionGeneration !== this.selectionGeneration)
+                    throw new UiError("presentation_superseded", "A newer panel action replaced this opening. Retry to open it again.");
+                const old = this.snapshot.tools.find(t => t.key === toolKey);
+                const same = old?.resolved.surface && JSON.stringify(old.resolved.surface) === JSON.stringify(resolved.surface);
+                const tool = { key: toolKey, target: resolved.target, resolved,
+                    readiness: insecure ? "unreported" : same ? old.readiness : "loading", attention: old?.attention ?? 0 };
+                this.update({ tools: old ? this.snapshot.tools.map(t => t.key === toolKey ? tool : t) : [...this.snapshot.tools, tool], selected: target.panel, expanded: true });
+                return { status: "opened", requestId: id, target: resolved.target, readiness: tool.readiness };
+            }
+            catch (error) {
+                return failure(id, error);
+            }
+        })();
+        entry.pending = operation;
+        this.ledger.set(key, entry);
+        this.toolQueues.set(toolKey, operation);
+        void operation.then(result => {
+            entry.pending = undefined;
+            entry.result = result;
+            if (this.toolQueues.get(toolKey) === operation)
+                this.toolQueues.delete(toolKey);
+            if (!frame && this.active && generation === this.activityGeneration)
+                this.emit({ type: "presentation", value: result });
+            const keys = [...this.ledger.keys()].filter(k => k.startsWith(source + ":"));
+            for (const oldKey of keys.slice(0, Math.max(0, keys.length - 256)))
+                if (!this.ledger.get(oldKey)?.pending)
+                    this.ledger.delete(oldKey);
+        });
+        return operation;
+    }
+    getPresentation = (id, options) => waitForPresentation(this.status(id, "local"), id, options?.signal);
+    async status(id, source, frame) {
+        const generation = this.activityGeneration;
+        try {
+            const own = await this.bootstrap(generation);
+            const check = () => {
+                this.checkActivity(generation);
+                if (!own.canHost)
+                    throw new UiError("app_permission_required", "Allow this app to host panels.");
+                if (this.snapshot.bootstrap?.userId !== own.userId || this.snapshot.bootstrap?.coreOrigin !== own.coreOrigin
+                    || this.snapshot.bootstrap?.app.installationId !== own.app.installationId || frame && (!frame.live || !frame.connected || frame.actor !== own.userId
+                    || source !== `${frame.surface.appId}:${frame.generation}:${frame.nonce}`))
+                    throw new UiError("actor_mismatch", "Reconnect using the same account.");
+            };
+            check();
+            const entry = this.ledger.get(`${source}:${id}`);
+            const result = entry?.pending ? await entry.pending : entry?.result;
+            check();
+            if (result?.status === "opened") {
+                const current = await uiRequest(this.path, "panels/resolve", result.target);
+                check();
+                if (!current.available)
+                    return { status: "blocked", requestId: id, code: current.state };
+                const tool = this.snapshot.tools.find(t => t.key === panelKey(result.target.panel));
+                if (!tool || tool.target.route !== result.target.route || JSON.stringify(tool.resolved.surface) !== JSON.stringify(current.surface))
+                    return { status: "blocked", requestId: id, code: "destination_changed" };
+                return { ...result, readiness: tool.readiness };
+            }
+            return result ?? { status: "unknown", requestId: id, code: "presentation_unknown" };
+        }
+        catch (error) {
+            return failure(id, error);
+        }
+    }
+    selectPanel = async (ref) => {
+        const opened = this.snapshot.tools.find(t => t.key === panelKey(ref));
+        return this.openSurface(opened?.resolved.surface ? opened.target : { panel: ref }, { placement: "side", requestId: createPresentationRequestId() });
+    };
+    setExpanded = (expanded) => {
+        if (expanded && (!this.active || !this.activityReady))
+            return;
+        if (!expanded)
+            this.selectionGeneration++;
+        this.update({ expanded });
+    };
+    setWidth = (width) => { if (Number.isFinite(width))
+        this.update({ width: Math.min(800, Math.max(280, width)) }); };
+    setAttention = (panel, attention) => this.update({ tools: this.snapshot.tools.map(t => t.key === panelKey(panel) ? { ...t, attention: Math.max(0, Math.floor(attention)) } : t) });
+    reportSurfaceState = (_state) => { };
+    forgetFrameRequests(frame) {
+        for (const [key, entry] of this.ledger)
+            if (entry.frame === frame)
+                this.ledger.delete(key);
+    }
+    registerFrame = (element, surface, onConnection) => {
+        const frame = { element, surface, onConnection, generation: createPresentationRequestId(), nonce: null, connected: false, actor: null, live: true, cleanup: () => { }, waitForReadiness: () => { } };
+        let timer;
+        const forget = () => this.forgetFrameRequests(frame);
+        frame.waitForReadiness = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                const tool = this.snapshot.tools.find(t => t.target.panel.panelId === frame.surface.panelId && t.target.panel.appId === frame.surface.appId);
+                if (tool?.readiness === "loading")
+                    this.reportFrame(frame, "unreported");
+            }, DISCOVERY_TIMEOUT);
+        };
+        const loaded = () => {
+            forget();
+            frame.generation = createPresentationRequestId();
+            frame.nonce = null;
+            frame.connected = false;
+            frame.actor = null;
+            frame.onConnection?.(false);
+            this.reportFrame(frame, "loading");
+            this.post(frame, { type: "hosty:ui:probe-request" });
+            frame.waitForReadiness();
+        };
+        frame.cleanup = () => { frame.live = false; forget(); clearTimeout(timer); element.removeEventListener("load", loaded); this.frames.delete(frame); };
+        this.frames.add(frame);
+        element.addEventListener("load", loaded);
+        loaded();
+        return frame.cleanup;
+    };
+    post(frame, value) {
+        if (!frame.live || this.disposed || !this.active || !this.activityReady)
+            return;
+        frame.element.contentWindow?.postMessage({ version: 1, hostWindowId: this.windowId, generation: frame.generation,
+            childNonce: frame.nonce, ...value }, frame.surface.origin);
+    }
+    reportFrame(frame, readiness) {
+        if (!frame.surface.panelId || !this.active || !this.activityReady)
+            return;
+        const tools = this.snapshot.tools.map(t => t.resolved.surface?.appId === frame.surface.appId
+            && t.target.panel.panelId === frame.surface.panelId
+            && t.resolved.surface.installationId === frame.surface.installationId && t.resolved.surface.endpoint === frame.surface.endpoint
+            && t.target.route === frame.surface.route ? { ...t, readiness } : t);
+        this.update({ tools });
+        for (const [key, entry] of this.ledger) {
+            const result = entry.result;
+            if (result?.status !== "opened")
+                continue;
+            const tool = tools.find(t => t.key === panelKey(result.target.panel) && t.target.route === result.target.route);
+            if (!tool || tool.readiness === result.readiness)
+                continue;
+            entry.result = { ...result, readiness: tool.readiness };
+            if (entry.frame?.live)
+                this.post(entry.frame, { type: "hosty:ui:result", requestId: result.requestId, result: entry.result });
+            else if (key.startsWith("local:"))
+                this.emit({ type: "presentation", value: entry.result });
+        }
+    }
+    async receive(event) {
+        if (!this.active || !this.activityReady || this.disposed)
+            return;
+        const msg = readUiMessage(event.data);
+        if (!msg)
+            return;
+        const frame = [...this.frames].find(f => f.live && f.element.contentWindow === event.source && f.surface.origin === event.origin);
+        const own = this.snapshot.bootstrap;
+        if (!frame || !own?.canHost)
+            return;
+        if (msg.type === "hosty:ui:probe" && validId(msg.childNonce) && Array.isArray(msg.versions) && msg.versions.includes(1)) {
+            if (frame.nonce !== msg.childNonce) {
+                this.forgetFrameRequests(frame);
+                frame.connected = false;
+                frame.actor = null;
+                frame.onConnection?.(false);
+            }
+            frame.nonce = msg.childNonce;
+            this.post(frame, { type: "hosty:ui:offer" });
+            return;
+        }
+        if (msg.hostWindowId !== this.windowId || msg.generation !== frame.generation || msg.childNonce !== frame.nonce || !frame.nonce)
+            return;
+        // This is advisory state, accepted only from the mounted origin/document. It grants no authority.
+        if (msg.type === "hosty:ui:auth-required") {
+            frame.connected = false;
+            frame.actor = null;
+            frame.onConnection?.(false);
+            this.reportFrame(frame, "auth-required");
+            return;
+        }
+        if (msg.type === "hosty:ui:accept") {
+            const wasConnected = frame.connected;
+            frame.connected = msg.coreOrigin === own.coreOrigin && msg.userId === own.userId
+                && msg.appId === frame.surface.appId && msg.installationId === frame.surface.installationId;
+            frame.actor = frame.connected ? own.userId : null;
+            if (frame.connected) {
+                this.reportFrame(frame, "loading");
+                frame.waitForReadiness();
+            }
+            this.post(frame, { type: "hosty:ui:connected", coreOrigin: own.coreOrigin, userId: own.userId,
+                appId: own.app.appId, installationId: own.app.installationId, code: frame.connected ? null : "actor_mismatch", route: frame.surface.route });
+            if (frame.connected !== wasConnected)
+                frame.onConnection?.(frame.connected);
+            if (!frame.connected)
+                this.reportFrame(frame, "auth-required");
+            return;
+        }
+        if (!frame.connected)
+            return;
+        const source = `${frame.surface.appId}:${frame.generation}:${frame.nonce}`;
+        if (msg.type === "hosty:ui:open" && validId(msg.requestId)) {
+            const result = await this.open(msg.target, { placement: msg.placement, requestId: msg.requestId }, source, frame);
+            if (source === `${frame.surface.appId}:${frame.generation}:${frame.nonce}`)
+                this.post(frame, { type: "hosty:ui:result", requestId: msg.requestId, result });
+        }
+        else if (msg.type === "hosty:ui:status" && validId(msg.requestId)) {
+            const result = await this.status(msg.requestId, source, frame);
+            if (source === `${frame.surface.appId}:${frame.generation}:${frame.nonce}`)
+                this.post(frame, { type: "hosty:ui:result", requestId: msg.requestId, result });
+        }
+        else if (msg.type === "hosty:ui:surface-state" && canonicalSurfaceRoute(msg.route) !== null
+            && canonicalSurfaceRoute(msg.route) === canonicalSurfaceRoute(frame.surface.route)) {
+            if (msg.state === "ready")
+                this.reportFrame(frame, "ready");
+            else if (msg.state === "auth-required" || msg.state === "blocked")
+                this.reportFrame(frame, "auth-required");
+        }
+        else if (msg.type === "hosty:ui:dismiss") {
+            const selected = this.snapshot.tools.find(t => this.snapshot.selected && t.key === panelKey(this.snapshot.selected));
+            if (selected?.resolved.surface?.appId === frame.surface.appId && selected.target.panel.panelId === frame.surface.panelId && selected.target.route === frame.surface.route)
+                window.dispatchEvent(new CustomEvent("hosty:ui:drawer-dismiss"));
+        }
+    }
+    dispose = () => {
+        this.disposed = true;
+        for (const frame of this.frames)
+            frame.cleanup();
+        window.removeEventListener("message", this.onMessage);
+        window.removeEventListener("focus", this.onFocus);
+        this.listeners.clear();
+        this.events.clear();
+        this.ledger.clear();
+        if (documentHost === this)
+            documentHost = null;
+    };
+}

package/dist/ui-react.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from "react";
+import { type UiClient } from "./ui.js";
+import { type UiHost } from "./ui-host.js";
+import { type HostyAppFrameProps } from "./ui-frame.js";
+import { type PanelTarget, type UiPanel } from "./ui-types.js";
+export { HostyAppFrame, type HostyAppFrameProps } from "./ui-frame.js";
+export declare function useHostyUi(): UiClient;
+export declare function useHostyUiHost(): UiHost | null;
+/** Internal composition root, owned by HostyOverlay rather than mounted again by domain apps. */
+export declare function HostyUiRoot({ children, uiPath, panelLayout, active }: {
+    children: ReactNode;
+    uiPath?: string;
+    panelLayout?: "auto" | "slot" | "none";
+    active?: boolean;
+}): import("react").JSX.Element;
+export type HostyPanelWorkspaceProps = {
+    children: ReactNode;
+    railMode?: "opened" | "catalog";
+    className?: string;
+    initialWidth?: number;
+    initialExpanded?: boolean;
+    onWidthChange?: (width: number) => void;
+    onExpandedChange?: (expanded: boolean) => void;
+    onStartApp?: (appId: string) => void | Promise<void>;
+    onAskAssistant?: HostyAppFrameProps["onAskAssistant"];
+    onAuthRequired?: HostyAppFrameProps["onAuthRequired"];
+    outbound?: {
+        target: PanelTarget;
+        message: unknown;
+        nonce: number;
+    } | null;
+    renderIcon?: (panel: UiPanel) => ReactNode;
+};
+/** A single retained frame tree for dock and drawer; only CSS placement changes at the breakpoint. */
+export declare function HostyPanelWorkspace({ children, railMode, className, initialWidth, initialExpanded, onWidthChange, onExpandedChange, onStartApp, onAskAssistant, onAuthRequired, outbound, renderIcon }: HostyPanelWorkspaceProps): import("react").JSX.Element;