@hosty-sdk/app 0.24.0 → 0.26.0

package/dist/ui-react.js

@@ -0,0 +1,225 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useEffect, useId, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { bindUiClient, ui } from "./ui.js";
+import { createUiHost } from "./ui-host.js";
+import { EmbeddedUiClient } from "./ui-embedded.js";
+import { UiHostContext } from "./ui-context.js";
+import { HostyAppFrame } from "./ui-frame.js";
+import { panelKey } from "./ui-types.js";
+import { uiPath as normalizeUiPath } from "./ui-transport.js";
+export { HostyAppFrame } from "./ui-frame.js";
+export function useHostyUi() { return ui; }
+export function useHostyUiHost() { return useContext(UiHostContext); }
+/** Internal composition root, owned by HostyOverlay rather than mounted again by domain apps. */
+export function HostyUiRoot({ children, uiPath, panelLayout = "auto", active = true }) {
+    const [host, setHost] = useState(null);
+    const [environment, setEnvironment] = useState(null);
+    const mounted = useRef(false);
+    const clientRef = useRef(null);
+    const activeRef = useRef(active);
+    useLayoutEffect(() => {
+        activeRef.current = active;
+        clientRef.current?.setActive(active);
+    }, [active]);
+    useEffect(() => {
+        const path = normalizeUiPath(uiPath);
+        const client = window.parent === window ? createUiHost({ uiPath: path, active: activeRef.current }) : new EmbeddedUiClient(path);
+        client.setActive(activeRef.current);
+        clientRef.current = client;
+        const release = bindUiClient(client), stop = client.subscribe(event => { if (event.type === "environment")
+            setEnvironment(event.value); });
+        if (client instanceof EmbeddedUiClient)
+            setHost(null);
+        else
+            setHost(client);
+        return () => { stop(); release(); client.dispose(); clientRef.current = null; };
+    }, [uiPath]);
+    const allowed = environment?.mode === "standalone" || environment?.connection === "connected" || environment?.connection === "unsupported";
+    if (allowed)
+        mounted.current = true;
+    return _jsxs(UiHostContext.Provider, { value: host, children: [_jsx("div", { hidden: !allowed, inert: !allowed, style: { display: allowed ? "contents" : "none" }, children: mounted.current && (panelLayout === "auto" && host ? _jsx(HostyPanelWorkspace, { children: children }) : children) }), !allowed && _jsx("div", { role: "status", className: "hosty-panel-notice", style: { padding: 24, font: "14px system-ui" }, children: environment?.connection === "blocked" ? _jsxs(_Fragment, { children: [_jsx("strong", { children: environment.code === "actor_mismatch" ? "Use the same Hosty account in this app and its host" : "Cannot verify this app’s host" }), _jsx("p", { children: "Check your account and access in Hosty Core, then reconnect. Your existing discussion is unchanged." }), _jsx("button", { type: "button", onClick: () => window.location.reload(), children: "Reconnect" })] }) : "Connecting to the workspace…" })] });
+}
+const empty = { bootstrap: null, catalog: [], tools: [], selected: null, expanded: false, width: 360, error: null };
+const noop = () => () => { };
+/** A single retained frame tree for dock and drawer; only CSS placement changes at the breakpoint. */
+export function HostyPanelWorkspace({ children, railMode = "opened", className = "", initialWidth, initialExpanded, onWidthChange, onExpandedChange, onStartApp, onAskAssistant, onAuthRequired, outbound, renderIcon }) {
+    const host = useHostyUiHost();
+    const state = useSyncExternalStore(host?.subscribeSnapshot ?? noop, host?.getSnapshot ?? (() => empty), () => empty);
+    const unsupported = state.error?.code.startsWith("unsupported") === true;
+    const root = useRef(null), content = useRef(null), body = useRef(null), close = useRef(null);
+    const opener = useRef(null), panelOpener = useRef(null);
+    const [size, setSize] = useState(1200), [chooser, setChooser] = useState(false), [error, setError] = useState(null);
+    const chooserRef = useRef(null);
+    const bodyId = useId();
+    const workspaceOwner = useRef({});
+    useEffect(() => host?.claimWorkspace(workspaceOwner.current), [host]);
+    const drawer = size < 900, expanded = state.expanded && !!state.selected;
+    const selectedKey = state.selected ? panelKey(state.selected) : null;
+    const tabs = railMode === "catalog" ? state.catalog : state.tools.map(tool => state.catalog.find(p => panelKey(p.panel) === tool.key)).filter((p) => !!p);
+    const selected = state.catalog.find(p => panelKey(p.panel) === selectedKey);
+    const tool = state.tools.find(t => t.key === selectedKey);
+    const width = Math.min(state.width, Math.max(280, size - 480 - 60));
+    const optionsRef = useRef({ onWidthChange, onExpandedChange });
+    optionsRef.current = { onWidthChange, onExpandedChange };
+    useEffect(() => {
+        if (!host)
+            return;
+        if (initialWidth !== undefined)
+            host.setWidth(initialWidth);
+        if (initialExpanded !== undefined)
+            host.setExpanded(initialExpanded);
+    }, [host]);
+    useEffect(() => {
+        if (!host || railMode !== "catalog")
+            return;
+        let live = true, pending = false, completed = false;
+        let attemptedCatalog = null;
+        const restore = () => {
+            const current = host.getSnapshot();
+            if (!current.expanded) {
+                attemptedCatalog = null;
+                return;
+            }
+            if (!live || pending || completed || current.selected || current.catalog === attemptedCatalog)
+                return;
+            const first = current.catalog.find(panel => panel.available);
+            if (!first)
+                return;
+            pending = true;
+            attemptedCatalog = current.catalog;
+            void host.selectPanel(first.panel).then(result => { completed = result.status === "opened"; })
+                .finally(() => { pending = false; restore(); });
+        };
+        // A refusal consumes only this catalog generation. A refresh can retry, including one
+        // received while resolution was pending, but a user collapse always prevents restoration.
+        const stop = host.subscribeSnapshot(restore);
+        restore();
+        return () => { live = false; stop(); };
+    }, [host, railMode]);
+    const lastPrefs = useRef({ width: initialWidth ?? 360, expanded: initialExpanded ?? false });
+    useEffect(() => {
+        if (!host || state !== host.getSnapshot())
+            return;
+        if (state.width !== lastPrefs.current.width)
+            optionsRef.current.onWidthChange?.(state.width);
+        if (state.expanded !== lastPrefs.current.expanded)
+            optionsRef.current.onExpandedChange?.(state.expanded);
+        lastPrefs.current = { width: state.width, expanded: state.expanded };
+    }, [host, state.width, state.expanded]);
+    useLayoutEffect(() => {
+        if (!root.current)
+            return;
+        const read = () => setSize(root.current.getBoundingClientRect().width || window.innerWidth);
+        read();
+        const observer = new ResizeObserver(read);
+        observer.observe(root.current);
+        return () => observer.disconnect();
+    }, []);
+    useLayoutEffect(() => {
+        if (!expanded)
+            return;
+        panelOpener.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+        return () => { const previous = panelOpener.current; if (previous?.isConnected)
+            previous.focus(); };
+    }, [expanded]);
+    useLayoutEffect(() => {
+        if (!expanded || !drawer)
+            return;
+        opener.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+        close.current?.focus();
+        const dismiss = () => host?.setExpanded(false);
+        window.addEventListener("hosty:ui:drawer-dismiss", dismiss);
+        return () => { window.removeEventListener("hosty:ui:drawer-dismiss", dismiss); if (opener.current?.isConnected)
+            opener.current.focus(); };
+    }, [expanded, drawer, host]);
+    useEffect(() => {
+        if (expanded && tool?.readiness === "ready")
+            body.current?.querySelector(".hosty-panel-frame:not([hidden]) iframe")?.focus();
+    }, [expanded, selectedKey, tool?.readiness]);
+    useEffect(() => {
+        const dialog = chooserRef.current;
+        if (!chooser || !dialog)
+            return;
+        dialog.showModal();
+        return () => { if (dialog.open)
+            dialog.close(); };
+    }, [chooser]);
+    async function select(panel) {
+        if (!host)
+            return;
+        if (expanded && selectedKey === panelKey(panel.panel)) {
+            host.setExpanded(false);
+            return;
+        }
+        const result = await host.selectPanel(panel.panel);
+        if (result.status !== "opened")
+            setError(panel.available ? "Could not open this tool. Try again." : `${panel.appName} is ${panel.state}.`);
+        else {
+            setError(null);
+            setChooser(false);
+        }
+    }
+    const resize = (event) => {
+        const start = event.clientX, old = width, handle = event.currentTarget;
+        handle.setPointerCapture(event.pointerId);
+        const move = (next) => host?.setWidth(Math.min(size - 540, old + start - next.clientX));
+        const end = () => { handle.removeEventListener("pointermove", move); handle.removeEventListener("pointerup", end); handle.removeEventListener("lostpointercapture", end); };
+        handle.addEventListener("pointermove", move);
+        handle.addEventListener("pointerup", end);
+        handle.addEventListener("lostpointercapture", end);
+    };
+    return _jsxs("div", { ref: root, className: `hosty-panel-workspace ${className}`, "data-hosty-panel-layout": drawer ? "drawer" : "dock", style: { "--hosty-panel-width": `${width}px`, ...(unsupported ? { display: "contents" } : {}) }, children: [_jsx("style", { children: styles }), _jsx("div", { ref: content, className: "hosty-panel-document", style: unsupported ? { display: "contents" } : undefined, inert: expanded && drawer, children: children }), _jsxs("nav", { className: "hosty-panel-rail", "aria-label": "Tools", style: unsupported ? { display: "none" } : undefined, inert: unsupported || expanded && drawer, children: [tabs.map((panel, index) => _jsxs("button", { type: "button", title: `${panel.appName}: ${panel.label}`, "aria-label": panel.label, "aria-controls": bodyId, "aria-expanded": expanded && selectedKey === panelKey(panel.panel), onClick: () => void select(panel), onKeyDown: event => {
+                            const delta = event.key === "ArrowDown" ? 1 : event.key === "ArrowUp" ? -1 : 0;
+                            const next = event.key === "Home" ? 0 : event.key === "End" ? tabs.length - 1 : delta ? (index + delta + tabs.length) % tabs.length : null;
+                            if (next !== null) {
+                                event.preventDefault();
+                                event.currentTarget.parentElement?.children[next]?.focus();
+                            }
+                        }, children: [renderIcon?.(panel) ?? panel.label.slice(0, 2), state.tools.find(t => t.key === panelKey(panel.panel))?.attention ? _jsx("span", { className: "hosty-panel-attention", "aria-label": "Needs attention", children: "\u2022" }) : null] }, panelKey(panel.panel))), _jsx("button", { type: "button", "aria-label": "Add tool", title: "Add tool", onClick: () => { setError(null); setChooser(true); void host?.refresh(); }, children: "+" })] }), expanded && drawer && _jsx("button", { type: "button", className: "hosty-panel-backdrop", "aria-label": "Return to document", onClick: () => host?.setExpanded(false) }), _jsxs("aside", { ref: body, id: bodyId, className: "hosty-panel-body", hidden: !expanded, inert: !expanded, role: drawer ? "dialog" : "complementary", "aria-modal": drawer && expanded ? true : undefined, "aria-label": selected?.label ?? "Tool", onKeyDown: event => {
+                    if (!drawer)
+                        return;
+                    if (event.key === "Escape") {
+                        event.preventDefault();
+                        host?.setExpanded(false);
+                    }
+                    if (event.key === "Tab") {
+                        const focusable = Array.from(body.current?.querySelectorAll('button,a[href],iframe,[tabindex="0"]') ?? []).filter(e => !e.closest("[hidden]") && !e.disabled);
+                        const first = focusable[0], last = focusable.at(-1);
+                        if (event.shiftKey && document.activeElement === first) {
+                            event.preventDefault();
+                            last?.focus();
+                        }
+                        else if (!event.shiftKey && document.activeElement === last) {
+                            event.preventDefault();
+                            first?.focus();
+                        }
+                    }
+                }, children: [drawer && expanded && _jsx("span", { tabIndex: 0, "aria-hidden": "true", className: "hosty-panel-focus-guard", onFocus: () => body.current?.querySelector(".hosty-panel-frame:not([hidden]) iframe")?.focus() }), _jsx("div", { className: "hosty-panel-resize", role: "separator", "aria-label": "Tool panel width", "aria-orientation": "vertical", tabIndex: drawer ? -1 : 0, "aria-valuemin": 280, "aria-valuemax": Math.max(280, Math.min(800, size - 540)), "aria-valuenow": width, onPointerDown: resize, onDoubleClick: () => host?.setWidth(360), onKeyDown: event => {
+                            if (event.key === "Home") {
+                                event.preventDefault();
+                                host?.setWidth(360);
+                            }
+                            if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+                                event.preventDefault();
+                                host?.setWidth(width + (event.key === "ArrowLeft" ? 16 : -16));
+                            }
+                        } }), _jsxs("header", { children: [_jsx("strong", { children: selected?.label ?? "Tool" }), tool?.resolved.standaloneHref && _jsx("a", { href: tool.resolved.standaloneHref, target: "_blank", rel: "noopener noreferrer", title: "Open separately", "aria-label": "Open separately", children: "\u2197" }), _jsx("button", { ref: close, type: "button", onClick: () => host?.setExpanded(false), "aria-label": "Return to document", title: "Return to document", children: "\u00D7" })] }), tool?.resolved.state === "degraded" && _jsx("div", { className: "hosty-panel-state", role: "status", children: "This app\u2019s health check is failing. Its page may still work." }), tool?.readiness === "unreported" && _jsxs("div", { className: "hosty-panel-state", role: "status", children: ["This tool has not confirmed that it loaded. If the page is blank or refuses to connect, use ", _jsx("a", { href: tool.resolved.standaloneHref ?? undefined, target: "_blank", rel: "noopener noreferrer", children: "Open separately" }), "."] }), tool?.readiness === "auth-required" && _jsx("div", { className: "hosty-panel-state", role: "status", children: "Check access in the tool below, then retry opening the discussion." }), state.tools.map(item => _jsx("div", { className: "hosty-panel-frame", hidden: item.key !== selectedKey, inert: item.key !== selectedKey, children: item.resolved.surface ? _jsx(HostyAppFrame, { surface: { ...item.resolved.surface, panelId: item.target.panel.panelId }, title: state.catalog.find(p => panelKey(p.panel) === item.key)?.label ?? "Tool", standaloneHref: item.resolved.standaloneHref, onAskAssistant: onAskAssistant, onAuthRequired: onAuthRequired, onAttention: count => host?.setAttention(item.target.panel, count), outbound: outbound && panelKey(outbound.target.panel) === item.key && outbound.target.route === item.target.route ? outbound : null }, JSON.stringify(item.resolved.surface))
+                            : _jsxs("div", { className: "hosty-panel-notice", children: [_jsxs("p", { children: ["This tool is unavailable (", item.resolved.state, ")."] }), _jsx("button", { type: "button", onClick: () => void host?.selectPanel(item.target.panel), children: "Retry opening" })] }) }, item.key)), drawer && expanded && _jsx("span", { tabIndex: 0, "aria-hidden": "true", className: "hosty-panel-focus-guard", onFocus: () => close.current?.focus() })] }), chooser && _jsxs("dialog", { ref: chooserRef, className: "hosty-tool-chooser", onCancel: () => setChooser(false), "aria-label": "Add tool", children: [_jsxs("header", { children: [_jsx("strong", { children: "Add tool" }), _jsx("button", { type: "button", onClick: () => setChooser(false), "aria-label": "Close tool chooser", children: "\u00D7" })] }), _jsx("p", { children: "Open a tool beside your document." }), error && _jsx("p", { role: "status", children: error }), state.error && _jsx("p", { role: "status", children: state.error.message }), !state.bootstrap?.canHost && _jsx("p", { children: "This app needs optional panel access in Hosty Core to show tools here. You can still use the app." }), state.bootstrap?.canHost && !state.catalog.length && _jsx("p", { children: "No tools are available for your account." }), _jsx("ul", { children: state.catalog.map(panel => _jsxs("li", { children: [_jsxs("button", { type: "button", onClick: () => void select(panel), children: [_jsx("strong", { children: panel.label }), _jsxs("span", { children: [panel.appName, panel.available ? "" : ` · ${panel.state}`] })] }), !panel.available && panel.canStart && onStartApp && _jsx("button", { type: "button", onClick: () => void Promise.resolve(onStartApp(panel.panel.appId)).then(() => host?.refresh()), children: "Start app" })] }, panelKey(panel.panel))) }), _jsx("button", { type: "button", onClick: () => void host?.refresh(), children: "Refresh tools" })] }), error && !chooser && _jsxs("div", { className: "hosty-panel-error", role: "status", children: [error, " ", _jsx("button", { type: "button", onClick: () => { setChooser(true); setError(null); }, children: "Choose tool" })] })] });
+}
+const styles = `
+.hosty-panel-workspace{--hp-bg:#f8f9fb;--hp-fg:#20242c;--hp-muted:#606875;--hp-border:#e0e4eb;display:flex;position:relative;min-width:0;min-height:0;width:100%;height:100dvh;overflow:hidden;background:var(--hp-bg);color:var(--hp-fg)}
+html.dark .hosty-panel-workspace,html[data-hosty-theme=dark] .hosty-panel-workspace{--hp-bg:#14171c;--hp-fg:#f0f2f5;--hp-muted:#a2aab7;--hp-border:#323843}
+.hosty-panel-document{flex:1;min-width:0;min-height:0;overflow:auto}.hosty-panel-rail{order:3;flex:0 0 48px;display:flex;flex-direction:column;align-items:center;gap:8px;padding:10px 0;border-left:1px solid var(--hp-border);overflow:auto}
+.hosty-panel-workspace button,.hosty-panel-workspace a{font:inherit}.hosty-panel-rail button,.hosty-panel-body header button,.hosty-panel-body header a,.hosty-tool-chooser header button{position:relative;display:grid;place-items:center;flex-shrink:0;border:1px solid transparent;border-radius:8px;width:32px;height:32px;padding:0;background:transparent;color:inherit;font:500 13px system-ui;cursor:pointer;text-decoration:none}
+.hosty-panel-rail button:hover,.hosty-panel-rail button[aria-expanded=true]{border-color:var(--hp-border);background:color-mix(in srgb,var(--hp-fg) 8%,transparent)}
+.hosty-panel-workspace :focus-visible{outline:2px solid #5286ee;outline-offset:2px}.hosty-panel-attention{position:absolute;top:0;right:1px;color:#e9a52b;font-size:20px}
+.hosty-panel-body{order:2;display:flex;flex:0 0 var(--hosty-panel-width);flex-direction:column;position:relative;min-width:0;min-height:0;margin-left:12px;border-left:1px solid var(--hp-border);background:var(--hp-bg)}
+.hosty-panel-body[hidden],.hosty-panel-frame[hidden]{display:none}.hosty-panel-body header,.hosty-tool-chooser header{display:flex;align-items:center;gap:6px;min-height:44px;padding:0 10px;border-bottom:1px solid var(--hp-border);font:500 13px system-ui}.hosty-panel-body header strong,.hosty-tool-chooser header strong{flex:1}
+.hosty-panel-focus-guard{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%)}
+.hosty-panel-frame{position:relative;flex:1;min-height:0;overflow:hidden}.hosty-panel-frame iframe{display:block}.hosty-panel-resize{position:absolute;left:-12px;top:0;bottom:0;width:12px;cursor:col-resize;touch-action:none}.hosty-panel-resize:hover{background:color-mix(in srgb,var(--hp-fg) 8%,transparent)}
+.hosty-panel-state{padding:8px 12px;font:12px/1.4 system-ui;border-bottom:1px solid var(--hp-border);color:var(--hp-muted)}.hosty-panel-state a{text-decoration:underline}
+.hosty-panel-workspace[data-hosty-panel-layout=drawer] .hosty-panel-body{position:absolute;inset:0 0 0 auto;width:min(440px,100%);z-index:3;margin:0;box-shadow:-8px 0 30px #0002}.hosty-panel-workspace[data-hosty-panel-layout=drawer] .hosty-panel-resize{display:none}
+.hosty-panel-backdrop{position:absolute;inset:0;border:0;background:#0005;z-index:2;cursor:pointer}.hosty-panel-notice{padding:24px;font:14px/1.5 system-ui}.hosty-panel-review{position:absolute;top:8px;right:8px;z-index:2;padding:10px;background:var(--hp-bg);border:1px solid var(--hp-border);border-radius:8px}
+.hosty-tool-chooser{width:min(440px,calc(100vw - 32px));max-height:80dvh;border:1px solid var(--hp-border);border-radius:12px;padding:16px;background:var(--hp-bg);color:var(--hp-fg);font:14px/1.5 system-ui}.hosty-tool-chooser::backdrop{background:#0005}.hosty-tool-chooser ul{list-style:none;padding:0;display:grid;gap:8px}.hosty-tool-chooser li{display:flex;gap:8px}.hosty-tool-chooser li>button{flex:1;border:1px solid var(--hp-border);background:transparent;color:inherit;border-radius:8px;padding:12px;text-align:left;cursor:pointer}.hosty-tool-chooser li span{display:block;color:var(--hp-muted);font-size:12px}.hosty-panel-error{position:absolute;bottom:16px;right:60px;z-index:4;background:var(--hp-bg);border:1px solid var(--hp-border);border-radius:8px;padding:12px;font:13px system-ui}
+`;

package/dist/ui-server.d.ts

@@ -0,0 +1,32 @@
+import type { ProviderServerOptions } from "@hosty-sdk/app/providers/server";
+import { type PanelTarget, type UiBootstrap, type UiPanel, type UiResolvedPanel } from "@hosty-sdk/app/ui/types";
+/** Server transport for generic UI metadata. Credentials never appear in returned metadata. */
+export declare class UiServerClient {
+    private readonly appId;
+    private readonly core;
+    private readonly service;
+    constructor(options?: ProviderServerOptions);
+    private request;
+    bootstrap(options: {
+        parentOrigin?: string;
+    }, token: string, signal?: AbortSignal): Promise<UiBootstrap>;
+    listPanels(token: string, signal?: AbortSignal): Promise<UiPanel[]>;
+    resolvePanel(target: PanelTarget, token: string, signal?: AbortSignal): Promise<UiResolvedPanel>;
+}
+type UiAuthenticatedContext = {
+    session: {
+        status: "active";
+        identity: {
+            hostRole: string | null;
+        };
+    } | {
+        status: "not-present" | "expired" | "forbidden" | "unavailable" | "misconfigured";
+    };
+    token: string | null;
+};
+/** A fixed Web Request/Response adapter; never a caller-chosen Core proxy. */
+export declare function createHostyUiResponse(request: Request, context: UiAuthenticatedContext, options?: ProviderServerOptions & {
+    administratorOnly?: boolean;
+    uiPath?: string;
+}): Promise<Response>;
+export {};

package/dist/ui-server.js

@@ -0,0 +1,123 @@
+import { UiError } from "@hosty-sdk/app/ui/types";
+/** Server transport for generic UI metadata. Credentials never appear in returned metadata. */
+export class UiServerClient {
+    appId;
+    core;
+    service;
+    constructor(options = {}) {
+        this.appId = options.appId ?? process.env.HOSTY_APP_ID ?? "";
+        this.core = new URL(options.coreOrigin ?? process.env.HOSTY_CORE_ORIGIN ?? "http://127.0.0.1:7070");
+        this.service = options.serviceToken ?? process.env.HOSTY_APP_SERVICE_TOKEN ?? "";
+        if (!this.appId || !this.service)
+            throw new UiError("hosty_misconfigured", "Hosty app credentials are not configured.", 503);
+    }
+    async request(path, token, body, signal) {
+        if (!token)
+            throw new UiError("app_identity_required", "Sign in to use application panels.", 401);
+        const response = await fetch(new URL(`/api/internal/apps/${encodeURIComponent(this.appId)}/ui/${path}`, this.core), {
+            method: body === undefined ? "GET" : "POST", redirect: "error", cache: "no-store",
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+            headers: { authorization: `Bearer ${this.service}`, "X-Hosty-User-Token": token, "content-type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const value = await response.json().catch(() => null);
+        if (response.status === 404)
+            throw new UiError("unsupported_core", "Update Core to use application panels.", 409);
+        if (!response.ok)
+            throw new UiError(value?.code ?? "ui_unavailable", value?.message ?? "Application panels are unavailable.", response.status);
+        if (!value)
+            throw new UiError("ui_response_invalid", "Core returned invalid panel metadata.", 502);
+        return value;
+    }
+    bootstrap(options, token, signal) {
+        return this.request(`bootstrap${options.parentOrigin ? `?parentOrigin=${encodeURIComponent(options.parentOrigin)}` : ""}`, token, undefined, signal);
+    }
+    async listPanels(token, signal) {
+        return (await this.request("panels", token, undefined, signal)).panels;
+    }
+    resolvePanel(target, token, signal) {
+        return this.request("panels/resolve", token, target, signal);
+    }
+}
+const responseHeaders = { "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" };
+/** A fixed Web Request/Response adapter; never a caller-chosen Core proxy. */
+export async function createHostyUiResponse(request, context, options = {}) {
+    try {
+        if (context.session.status !== "active" || !context.token) {
+            const state = context.session.status;
+            return Response.json({ code: state, message: "Sign in to use application panels." }, { status: state === "forbidden" ? 403 : state === "unavailable" ? 503 : 401, headers: responseHeaders });
+        }
+        if (options.administratorOnly && context.session.identity.hostRole !== "host.admin")
+            throw new UiError("admin_required", "This application requires administrator access.", 403);
+        const url = new URL(request.url);
+        const prefix = (options.uiPath ?? "/api/hosty/ui").replace(/\/$/, "");
+        const route = url.pathname.startsWith(prefix + "/") ? url.pathname.slice(prefix.length + 1) : "";
+        const client = new UiServerClient(options);
+        let result;
+        if (request.method === "GET" && route === "bootstrap") {
+            if ([...url.searchParams.keys()].some(k => k !== "parentOrigin") || url.searchParams.getAll("parentOrigin").length > 1)
+                throw new UiError("ui_request_invalid", "Invalid bootstrap request.", 400);
+            result = await client.bootstrap({ parentOrigin: url.searchParams.get("parentOrigin") ?? undefined }, context.token, request.signal);
+        }
+        else if (request.method === "GET" && route === "panels") {
+            result = { panels: await client.listPanels(context.token, request.signal) };
+        }
+        else if (request.method === "POST" && route === "panels/resolve") {
+            if (!sameOrigin(request) || request.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json")
+                throw new UiError("origin_denied", "Open panels from this application page.", 403);
+            const body = await boundedBody(request);
+            result = await client.resolvePanel(JSON.parse(body), context.token, request.signal);
+        }
+        else
+            throw new UiError("ui_route_not_found", "Unknown panel operation.", 404);
+        return Response.json(result, { headers: responseHeaders });
+    }
+    catch (error) {
+        const known = error instanceof UiError;
+        return Response.json({ code: known ? error.code : error instanceof SyntaxError ? "ui_request_invalid" : "ui_unavailable",
+            message: known ? error.message : "Application panels are unavailable. Retry opening the same target." }, { status: known ? error.status : error instanceof SyntaxError ? 400 : 503, headers: responseHeaders });
+    }
+}
+async function boundedBody(request) {
+    const reader = request.body?.getReader();
+    if (!reader)
+        return "";
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > 16_384) {
+                await reader.cancel();
+                throw new UiError("ui_request_invalid", "Panel request is too large.", 413);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
+function sameOrigin(request) {
+    try {
+        const origin = request.headers.get("origin");
+        const source = new URL(origin ?? "");
+        const requestUrl = new URL(request.url);
+        const destination = new URL(`${source.protocol}//${request.headers.get("host") ?? requestUrl.host}`);
+        return origin === source.origin && ["http:", "https:"].includes(source.protocol) && origin === destination.origin
+            && (source.protocol === requestUrl.protocol || request.headers.get("sec-fetch-site") === "same-origin");
+    }
+    catch {
+        return false;
+    }
+}

package/dist/ui-transport.d.ts

@@ -0,0 +1,16 @@
+import { type PanelTarget, type PresentationResult } from "./ui-types.js";
+export declare const UI_VERSION = 1;
+export declare const DISCOVERY_TIMEOUT = 5000;
+export declare const RESPONSE_TIMEOUT = 10000;
+export type UiMessage = Record<string, unknown> & {
+    type: string;
+    version: 1;
+};
+export declare function readUiMessage(value: unknown): UiMessage | null;
+export declare function validId(value: unknown): value is string;
+export declare function canonicalSurfaceRoute(value: unknown): string | null;
+export declare function validTarget(value: unknown): value is PanelTarget;
+export declare function uiPath(path?: string): string;
+export declare function uiRequest<T>(path: string, suffix: string, body?: unknown): Promise<T>;
+export declare function failure(requestId: string, error: unknown): PresentationResult;
+export declare function waitForPresentation(operation: Promise<PresentationResult>, requestId: string, signal?: AbortSignal): Promise<PresentationResult>;

package/dist/ui-transport.js

@@ -0,0 +1,68 @@
+import { appFetch } from "./browser-auth.js";
+import { UiError, isSurfaceRoute } from "./ui-types.js";
+export const UI_VERSION = 1;
+export const DISCOVERY_TIMEOUT = 5_000;
+export const RESPONSE_TIMEOUT = 10_000;
+export function readUiMessage(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    try {
+        if (new TextEncoder().encode(JSON.stringify(value)).length > 16_384)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const msg = value;
+    return msg.version === UI_VERSION && typeof msg.type === "string" && msg.type.startsWith("hosty:ui:") ? msg : null;
+}
+export function validId(value) { return typeof value === "string" && /^[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i.test(value); }
+export function canonicalSurfaceRoute(value) {
+    if (!isSurfaceRoute(value))
+        return null;
+    const route = new URL(value, "https://surface.invalid");
+    for (const key of ["hosty_launch", "hosty_theme", "hosty_theme_preference"])
+        route.searchParams.delete(key);
+    return `${route.pathname}${route.search}${route.hash}`;
+}
+export function validTarget(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const target = value, panel = target.panel;
+    return !!panel && [panel.appId, panel.installationId, panel.panelId].every(s => typeof s === "string" && s.length > 0 && s.length <= 256)
+        && (target.route === undefined || isSurfaceRoute(target.route));
+}
+export function uiPath(path = "/api/hosty/ui") {
+    if (!path.startsWith("/") || path.startsWith("//") || /[?#\\]/.test(path))
+        throw new Error("uiPath must be a same-origin path.");
+    return path.replace(/\/$/, "");
+}
+export async function uiRequest(path, suffix, body) {
+    const response = await appFetch(`${path}/${suffix}`, { method: body === undefined ? "GET" : "POST", cache: "no-store", redirect: "error",
+        signal: AbortSignal.timeout(RESPONSE_TIMEOUT), headers: body === undefined ? undefined : { "content-type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body) });
+    const value = await response.json().catch(() => null);
+    if (response.status === 404)
+        throw new UiError("unsupported_app", "This app does not support shared panels.", 404);
+    if (!response.ok)
+        throw new UiError(value?.code ?? "ui_unavailable", value?.message ?? "Unable to open the panel.", response.status);
+    if (!value)
+        throw new UiError("ui_response_invalid", "The app returned invalid panel metadata.", 502);
+    return value;
+}
+export function failure(requestId, error) {
+    return { status: error instanceof UiError && error.code.startsWith("unsupported") ? "unsupported" : "blocked", requestId,
+        code: error instanceof UiError ? error.code : "ui_unavailable" };
+}
+export function waitForPresentation(operation, requestId, signal) {
+    return new Promise(resolve => {
+        const finish = (value) => { clearTimeout(timer); signal?.removeEventListener("abort", uncertain); resolve(value); };
+        const uncertain = () => finish({ status: "uncertain", requestId, code: "presentation_unknown" });
+        const timer = setTimeout(uncertain, RESPONSE_TIMEOUT);
+        if (signal?.aborted)
+            uncertain();
+        else
+            signal?.addEventListener("abort", uncertain, { once: true });
+        void operation.then(finish, error => finish(failure(requestId, error)));
+    });
+}

package/dist/ui-types.d.ts

@@ -0,0 +1,99 @@
+/** A tool within one Core installation; no user credential or conversation identity. */
+export type PanelRef = {
+    appId: string;
+    installationId: string;
+    panelId: string;
+};
+export type PanelTarget = {
+    panel: PanelRef;
+    route?: string;
+};
+export type AppSurfaceRef = {
+    appId: string;
+    installationId: string;
+    endpoint: string;
+    route: string;
+};
+export type UiFramePolicy = {
+    microphone: boolean;
+    popupEscape: boolean;
+};
+export type UiPeer = {
+    appId: string;
+    installationId: string;
+    origins: string[];
+};
+export type UiBootstrap = {
+    version: 1;
+    coreOrigin: string;
+    userId: string;
+    app: UiPeer;
+    canHost: boolean;
+    pinnedOpen: boolean;
+    peer?: UiPeer | null;
+};
+export type UiPanel = {
+    panel: PanelRef;
+    label: string;
+    appName: string;
+    icon: string | null;
+    endpoint: string;
+    route: string;
+    origin: string | null;
+    available: boolean;
+    state: string;
+    canStart: boolean;
+    framePolicy: UiFramePolicy;
+};
+export type UiFrameSurface = AppSurfaceRef & {
+    origin: string;
+    framePolicy: UiFramePolicy;
+    panelId?: string;
+};
+export type UiResolvedPanel = {
+    target: PanelTarget;
+    surface: UiFrameSurface | null;
+    available: boolean;
+    state: string;
+    standaloneHref: string | null;
+};
+export type UiEnvironment = {
+    mode: "standalone" | "embedded";
+    connection: "connecting" | "connected" | "unsupported" | "blocked";
+    code?: string;
+};
+export type SurfaceReadiness = "loading" | "auth-required" | "ready" | "unreported";
+export type PresentationResult = {
+    status: "opened";
+    requestId: string;
+    target: PanelTarget;
+    readiness: SurfaceReadiness;
+} | {
+    status: "blocked" | "unsupported" | "rejected" | "uncertain" | "unknown";
+    requestId: string;
+    code: string;
+};
+export type PresentationOptions = {
+    placement: "side";
+    requestId: string;
+    signal?: AbortSignal;
+};
+export type UiEvent = {
+    type: "environment";
+    value: UiEnvironment;
+} | {
+    type: "presentation";
+    value: PresentationResult;
+};
+/** UI endpoints preserve typed operational failures without hiding identity refusals. */
+export declare class UiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+export declare function panelKey(panel: PanelRef): string;
+/** Reject traversal before URL normalization can erase it. Query/fragment are opaque navigation. */
+export declare function isSurfaceRoute(route: unknown): route is string;
+export declare function routeWithin(route: string, declared: string): boolean;
+/** Constructs navigation only. Core must advertise pinnedOpen and revalidate at redemption. */
+export declare function buildSurfaceOpenUrl(coreOrigin: string, destination: AppSurfaceRef): string;

package/dist/ui-types.js

@@ -0,0 +1,43 @@
+/** UI endpoints preserve typed operational failures without hiding identity refusals. */
+export class UiError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 409) { super(message); this.code = code; this.status = status; }
+}
+export function panelKey(panel) {
+    return JSON.stringify([panel.appId, panel.installationId, panel.panelId]);
+}
+/** Reject traversal before URL normalization can erase it. Query/fragment are opaque navigation. */
+export function isSurfaceRoute(route) {
+    if (typeof route !== "string" || route.length > 8192 || !route.startsWith("/") || route.startsWith("//") || /[\\\u0000-\u001f\u007f]/.test(route))
+        return false;
+    const path = route.split(/[?#]/, 1)[0];
+    if (/%(?:2f|5c|25)/i.test(path) || /%(?![\da-f]{2})/i.test(path))
+        return false;
+    try {
+        return !decodeURIComponent(path).split("/").some(part => part === "." || part === "..");
+    }
+    catch {
+        return false;
+    }
+}
+export function routeWithin(route, declared) {
+    if (!isSurfaceRoute(route) || !isSurfaceRoute(declared))
+        return false;
+    const path = new URL(route, "https://surface.invalid").pathname;
+    const root = new URL(declared, "https://surface.invalid").pathname.replace(/\/$/, "") || "/";
+    return root === "/" || path === root || path.startsWith(root + "/");
+}
+/** Constructs navigation only. Core must advertise pinnedOpen and revalidate at redemption. */
+export function buildSurfaceOpenUrl(coreOrigin, destination) {
+    if (!isSurfaceRoute(destination.route) || !destination.installationId || !destination.endpoint || !destination.appId)
+        throw new UiError("destination_invalid", "Invalid app surface destination.");
+    const core = new URL(coreOrigin);
+    if (!["http:", "https:"].includes(core.protocol) || core.username || core.password)
+        throw new UiError("core_origin_invalid", "Invalid Core browser origin.");
+    const url = new URL(`/api/apps/${encodeURIComponent(destination.appId)}/open`, core.origin);
+    url.searchParams.set("installationId", destination.installationId);
+    url.searchParams.set("endpoint", destination.endpoint);
+    url.searchParams.set("route", destination.route);
+    return url.href;
+}

package/dist/ui.d.ts

@@ -0,0 +1,20 @@
+import type { PanelTarget, PresentationOptions, PresentationResult, UiEnvironment, UiEvent } from "@hosty-sdk/app/ui/types";
+export * from "@hosty-sdk/app/ui/types";
+export interface UiClient {
+    getEnvironment(): UiEnvironment;
+    openSurface(target: PanelTarget, options: PresentationOptions): Promise<PresentationResult>;
+    getPresentation(requestId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<PresentationResult>;
+    subscribe(listener: (event: UiEvent) => void): () => void;
+    reportSurfaceState(state: {
+        route: string;
+        state: "ready" | "blocked";
+        code?: string;
+    }): void;
+}
+/** One document-local facade shared by domain apps; it never selects a provider or opens popups. */
+export declare const ui: UiClient;
+/** Internal root integration; exported from this source only, not as an ambient browser global. */
+export declare function bindUiClient(client: UiClient): () => void;
+export declare function createPresentationRequestId(): string;