@hosty-sdk/app 0.24.0 → 0.26.0

package/dist/server.js

@@ -1,7 +1,9 @@
 // Server slice: Next route-handler factories and Core revalidation. Never reaches a client
 // bundle — the service token lives here.
 import "server-only";
+import { readAppContinuity } from "./continuity.js";
 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 +30,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;
 }
@@ -212,6 +222,7 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
         expiresAt,
         activeUntil: readString(payload.activeUntil),
         activityRequired: payload.activityRequired === true,
+        continuity: readAppContinuity(payload.continuity),
     };
     const expiresAtMs = expiresAt ? Date.parse(expiresAt) : Number.NaN;
     if (Number.isFinite(expiresAtMs) && expiresAtMs > Date.now()) {

package/dist/session-server.d.ts

@@ -1,5 +1,6 @@
 import { type ProviderServerOptions } from "@hosty-sdk/app/providers/server";
 import type { AppSessionStatus, SessionRecoveryParams } from "./session-types.js";
+import type { AppContinuity } from "./continuity.js";
 /** Framework-neutral server adapter. Call with an already authenticated app session, never request data. */
 export type HostySessionInput = {
     status: AppSessionStatus;
@@ -8,6 +9,7 @@ export type HostySessionInput = {
         hostRole: string | null;
         activeUntil?: string | null;
         activityRequired?: boolean;
+        continuity?: AppContinuity;
     };
     error?: {
         code: string;

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;

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;
+}