@hosty-sdk/app 0.26.0 → 0.27.22

package/dist/ui-composition.js

@@ -0,0 +1,232 @@
+import { UI_COMPOSITION_CAPABILITY, UiError, isSurfaceRoute } from "./ui-types.js";
+import { canonicalSurfaceRoute, uiRequest } from "./ui-transport.js";
+export const CHROME_HINT_ATTRIBUTE = "data-hosty-chrome-hints";
+const navigationAttribute = "data-hosty-navigation";
+const fields = ["hosty_navigation", "hosty_tools", "hosty_tool_launcher", "hosty_launch"];
+export function parseChromeHints(search) {
+    const params = new URLSearchParams(search);
+    const one = (key) => params.getAll(key).length === 1 ? params.get(key) : null;
+    const navigation = one(fields[0]), enabled = one(fields[1]), launcher = one(fields[2]), launch = one(fields[3]);
+    return { ...(navigation === "show" || navigation === "hide" ? { navigation } : {}),
+        tools: { ...(enabled === "enabled" || enabled === "disabled" ? { enabled: enabled === "enabled" } : {}),
+            ...(launcher === "show" || launcher === "hide" ? { launcher } : {}) },
+        ...(launch === "embedded" || launch === "native" ? { legacy: "hide" } : launch === "standalone" ? { legacy: "show" } : {}) };
+}
+export function validChromeOverrides(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const v = value;
+    if (Object.keys(v).some(k => !["navigation", "tools"].includes(k)))
+        return false;
+    if (v.navigation !== undefined && v.navigation !== "show" && v.navigation !== "hide")
+        return false;
+    if (v.tools === undefined)
+        return true;
+    return !!v.tools && typeof v.tools === "object" && !Array.isArray(v.tools)
+        && Object.keys(v.tools).every(k => k === "enabled" || k === "launcher")
+        && (v.tools.enabled === undefined || typeof v.tools.enabled === "boolean")
+        && (v.tools.launcher === undefined || ["show", "hide"].includes(v.tools.launcher));
+}
+export function resolveChrome(defaults, hints, host = {}) {
+    function leaf(values, fallback) {
+        return values.find(([value]) => value !== undefined) ?? [fallback, "default"];
+    }
+    const [navigation, n] = leaf([[host.navigation, "host"], [hints.navigation, "url"], [defaults.navigation, "app"], [hints.legacy, "legacy"]], "show");
+    const [enabled, e] = leaf([[host.tools?.enabled, "host"], [hints.tools?.enabled, "url"], [defaults.tools?.enabled, "app"]], true);
+    const [launcher, l] = leaf([[host.tools?.launcher, "host"], [hints.tools?.launcher, "url"], [defaults.tools?.launcher, "app"]], "show");
+    return { navigation, enabled, launcher, sources: { navigation: n, enabled: e, launcher: l } };
+}
+export const INITIAL_CHROME = Object.freeze({ navigation: "show", tools: Object.freeze({ enabled: true, launcher: "show", owner: "unavailable" }),
+    revision: 0, hostRevision: -1, rootDisabled: false, stale: false, connection: "connecting", capabilities: Object.freeze([]),
+    sources: Object.freeze({ navigation: "default", enabled: "default", launcher: "default" }) });
+export const INITIAL_NAVIGATION = Object.freeze({ status: "loading", catalog: null, entries: Object.freeze([]), activeKey: null });
+/** Presentation hints are captured only for this document, never from inherited session storage. */
+export function captureChromeHints() {
+    if (typeof document === "undefined")
+        return "";
+    const root = document.documentElement;
+    const captured = root.getAttribute(CHROME_HINT_ATTRIBUTE);
+    if (captured !== null)
+        return captured;
+    const params = new URLSearchParams(window.location.search), hints = new URLSearchParams();
+    for (const key of fields)
+        for (const value of params.getAll(key))
+            hints.append(key, value);
+    root.setAttribute(CHROME_HINT_ATTRIBUTE, hints.toString());
+    return hints.toString();
+}
+export function withChromeHints(href, chrome) {
+    const url = new URL(href, typeof location === "undefined" ? "https://surface.invalid" : location.href);
+    for (const key of fields.slice(0, 3))
+        url.searchParams.delete(key);
+    if (chrome.navigation !== undefined)
+        url.searchParams.set(fields[0], chrome.navigation);
+    if (chrome.tools?.enabled !== undefined)
+        url.searchParams.set(fields[1], chrome.tools.enabled ? "enabled" : "disabled");
+    if (chrome.tools?.launcher !== undefined)
+        url.searchParams.set(fields[2], chrome.tools.launcher);
+    return url.href;
+}
+export { chromeBootstrapScript } from "./index.js";
+export function activeNavigationKey(entries, endpoint, route) {
+    const canonical = canonicalSurfaceRoute(route);
+    if (!canonical || !endpoint)
+        return null;
+    const current = new URL(canonical, "https://surface.invalid");
+    const candidates = entries.flatMap((entry, index) => {
+        if (entry.endpoint !== endpoint || !entry.route)
+            return [];
+        const normalized = canonicalSurfaceRoute(entry.route);
+        if (!normalized)
+            return [];
+        const declared = new URL(normalized, current.origin), path = declared.pathname.replace(/\/$/, "") || "/";
+        if (declared.search && declared.search !== current.search || declared.hash && declared.hash !== current.hash)
+            return [];
+        if (current.pathname !== declared.pathname && (path === "/" || !current.pathname.startsWith(path + "/")))
+            return [];
+        return [{ key: entry.key, rank: normalized === canonical ? Infinity : path.length, index }];
+    });
+    return candidates.sort((a, b) => b.rank - a.rank || a.index - b.index)[0]?.key ?? null;
+}
+/** Shared observable state for local and embedded clients; it owns no frame or identity authority. */
+export class UiCompositionModel {
+    path;
+    defaults;
+    chrome = INITIAL_CHROME;
+    navigation = INITIAL_NAVIGATION;
+    chromeListeners = new Set();
+    navigationListeners = new Set();
+    hints = parseChromeHints(captureChromeHints());
+    overrides = {};
+    hostRevision = -1;
+    hostGeneration = "";
+    rootDisabled = false;
+    capabilities = [];
+    environment;
+    router;
+    stopRouter;
+    endpoint;
+    epoch = 0;
+    disposed = false;
+    refreshing = null;
+    constructor(path, mode, defaults = {}) {
+        this.path = path;
+        this.defaults = defaults;
+        this.environment = { mode, connection: "connecting" };
+        if (mode === "standalone")
+            this.capabilities = [UI_COMPOSITION_CAPABILITY];
+        this.publishChrome();
+    }
+    getChrome = () => this.chrome;
+    subscribeChrome = (listener) => { this.chromeListeners.add(listener); return () => { this.chromeListeners.delete(listener); }; };
+    getNavigation = () => this.navigation;
+    subscribeNavigation = (listener) => { this.navigationListeners.add(listener); return () => { this.navigationListeners.delete(listener); }; };
+    configure(defaults) {
+        if (!validChromeOverrides(defaults))
+            throw new Error("Invalid chrome defaults.");
+        this.defaults = structuredClone(defaults);
+        this.publishChrome();
+    }
+    setEnvironment(environment) { this.environment = environment; this.publishChrome(); }
+    setHostPolicy(generation, revision, policy, rootDisabled, endpoint) {
+        if (!validChromeOverrides(policy) || !Number.isSafeInteger(revision) || revision < 0)
+            return;
+        if (generation === this.hostGeneration && revision <= this.hostRevision)
+            return;
+        this.hostGeneration = generation;
+        this.hostRevision = revision;
+        this.overrides = structuredClone(policy);
+        this.rootDisabled = rootDisabled;
+        this.endpoint = endpoint;
+        this.capabilities = [UI_COMPOSITION_CAPABILITY];
+        this.publishChrome();
+        this.updateRoute();
+    }
+    setLegacyHost() {
+        this.capabilities = [];
+        this.overrides = {};
+        this.hostRevision = -1;
+        this.hostGeneration = "";
+        this.rootDisabled = false;
+        this.publishChrome();
+    }
+    publishChrome() {
+        const { navigation, enabled, launcher, sources } = resolveChrome(this.defaults, this.hints, this.overrides);
+        const connected = this.environment.connection === "connected";
+        this.chrome = Object.freeze({ navigation, tools: Object.freeze({ enabled: enabled && !this.rootDisabled, launcher,
+                owner: this.environment.mode === "standalone" ? "local" : connected ? "host" : "unavailable" }),
+            revision: this.chrome.revision + 1, hostRevision: this.hostRevision, rootDisabled: this.rootDisabled,
+            stale: this.hostRevision >= 0 && !connected, connection: this.environment.connection,
+            capabilities: Object.freeze([...this.capabilities]), sources: Object.freeze({ ...sources, ...(this.rootDisabled ? { enabled: "host" } : {}) }) });
+        if (typeof document !== "undefined")
+            document.documentElement.setAttribute(navigationAttribute, navigation);
+        for (const listener of this.chromeListeners)
+            listener();
+    }
+    attachRouter(router) {
+        this.stopRouter?.();
+        this.router = router;
+        if (router)
+            this.stopRouter = router.subscribe(() => this.updateRoute());
+        else if (typeof window !== "undefined") {
+            const changed = () => this.updateRoute();
+            window.addEventListener("popstate", changed);
+            window.addEventListener("hashchange", changed);
+            this.stopRouter = () => { window.removeEventListener("popstate", changed); window.removeEventListener("hashchange", changed); };
+        }
+        this.updateRoute();
+    }
+    updateNavigation(patch) {
+        this.navigation = Object.freeze({ ...this.navigation, ...patch });
+        for (const listener of this.navigationListeners)
+            listener();
+    }
+    currentRoute = () => this.router?.getRoute() ?? `${window.location.pathname}${window.location.search}${window.location.hash}`;
+    currentEndpoint = () => {
+        const endpoints = new Set(this.navigation.entries.filter(e => e.origin === window.location.origin && e.endpoint).map(e => e.endpoint));
+        return this.router?.endpoint ?? this.endpoint ?? (endpoints.size === 1 ? [...endpoints][0] : undefined);
+    };
+    isLocalEntry(entry) { return entry.origin === window.location.origin && entry.endpoint === this.currentEndpoint(); }
+    updateRoute = () => {
+        const origins = new Set(this.navigation.entries.filter(e => e.origin === window.location.origin && e.endpoint).map(e => e.endpoint));
+        const endpoint = this.router?.endpoint ?? this.endpoint ?? (origins.size === 1 ? [...origins][0] : undefined);
+        const route = this.router?.getRoute() ?? `${window.location.pathname}${window.location.search}${window.location.hash}`;
+        this.updateNavigation({ activeKey: activeNavigationKey(this.navigation.entries, endpoint, route) });
+    };
+    refreshNavigation = () => {
+        if (this.refreshing)
+            return this.refreshing;
+        const epoch = this.epoch;
+        const operation = (async () => {
+            try {
+                const catalog = await uiRequest(this.path, "navigation");
+                if (this.disposed || epoch !== this.epoch)
+                    return;
+                if (!catalog.installationId || !Array.isArray(catalog.entries) || catalog.entries.some(e => e.route !== null && !isSurfaceRoute(e.route)))
+                    throw new UiError("ui_response_invalid", "Invalid navigation metadata.");
+                const entries = Object.freeze(catalog.entries.map(e => Object.freeze({ ...e })));
+                this.updateNavigation({ status: "ready", catalog: Object.freeze({ ...catalog, entries }), entries, code: undefined });
+                this.updateRoute();
+            }
+            catch (error) {
+                if (!this.disposed && epoch === this.epoch)
+                    this.updateNavigation({ status: "unavailable", code: error instanceof UiError ? error.code : "ui_unavailable" });
+            }
+        })().finally(() => { if (this.refreshing === operation)
+            this.refreshing = null; });
+        this.refreshing = operation;
+        return operation;
+    };
+    resetNavigation() { this.epoch++; this.refreshing = null; this.updateNavigation({ ...INITIAL_NAVIGATION }); }
+    async navigateLocal(entry) {
+        if (!entry.route || !isSurfaceRoute(entry.route) || !this.isLocalEntry(entry))
+            return false;
+        if (this.router)
+            await this.router.navigate(entry.route);
+        else
+            window.location.assign(withChromeHints(new URL(entry.route, window.location.origin).href, this.chrome));
+        this.updateRoute();
+        return true;
+    }
+    dispose() { this.disposed = true; this.epoch++; this.stopRouter?.(); this.chromeListeners.clear(); this.navigationListeners.clear(); }
+}

package/dist/ui-context.d.ts

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

package/dist/ui-context.js

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

package/dist/ui-embedded.d.ts

@@ -1,8 +1,12 @@
+import { UiCompositionModel } from "./ui-composition.js";
+import { type UiChromeOverrides, type UiActionOptions, type UiActionResult } from "./ui-types.js";
 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;
+    readonly composition: UiCompositionModel;
+    private readonly localActions;
     private environment;
     private nonce;
     private readonly listeners;
@@ -18,8 +22,18 @@ export declare class EmbeddedUiClient implements UiClient {
     private readonly onMessage;
     private readonly onFocus;
     private readonly onKey;
-    constructor(path: string);
+    constructor(path: string, chrome?: UiChromeOverrides);
     getEnvironment: () => UiEnvironment;
+    getChrome: () => import("./ui-types").UiChromeSnapshot;
+    subscribeChrome: (listener: () => void) => () => void;
+    getNavigation: () => Readonly<{
+        status: "loading" | "ready" | "unavailable";
+        catalog: import("./ui-types").UiNavigationCatalog | null;
+        entries: readonly import("./ui-types").UiNavigationEntry[];
+        activeKey: string | null;
+        code?: string;
+    }>;
+    subscribeNavigation: (listener: () => void) => () => void;
     setActive(active: boolean): void;
     subscribe: (listener: (event: UiEvent) => void) => () => void;
     private emit;
@@ -36,6 +50,9 @@ export declare class EmbeddedUiClient implements UiClient {
     getPresentation: (requestId: string, options?: {
         signal?: AbortSignal;
     }) => Promise<PresentationResult>;
+    openToolPicker: (options: UiActionOptions) => Promise<UiActionResult>;
+    navigate: (entryKey: string, options: UiActionOptions) => Promise<UiActionResult>;
+    private reportRoute;
     reportSurfaceState: (state: {
         route: string;
         state: "ready" | "blocked";

package/dist/ui-embedded.js

@@ -1,9 +1,13 @@
+import { activeNavigationKey, UiCompositionModel } from "./ui-composition.js";
+import { UI_COMPOSITION_CAPABILITY } from "./ui-types.js";
 import { createPresentationRequestId } from "./ui.js";
 import { UiError } from "./ui-types.js";
-import { DISCOVERY_TIMEOUT, failure, readUiMessage, uiRequest, validId, validTarget, waitForPresentation } from "./ui-transport.js";
+import { canonicalSurfaceRoute, 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;
+    composition;
+    localActions = new Map();
     environment = { mode: "embedded", connection: "connecting" };
     nonce = createPresentationRequestId();
     listeners = new Set();
@@ -20,8 +24,19 @@ export class EmbeddedUiClient {
     onFocus = () => { void this.recheck(); };
     onKey = (event) => { if (this.active && !event.defaultPrevented && event.key === "Escape")
         this.post({ type: "hosty:ui:dismiss" }); };
-    constructor(path) {
+    constructor(path, chrome = {}) {
         this.path = path;
+        this.composition = new UiCompositionModel(path, "embedded", chrome);
+        this.composition.attachRouter();
+        this.composition.subscribeNavigation(() => {
+            if (this.getChrome().capabilities.includes(UI_COMPOSITION_CAPABILITY) && this.environment.connection === "connected") {
+                const route = this.composition.currentRoute();
+                if (this.state && canonicalSurfaceRoute(this.state.route) === canonicalSurfaceRoute(route))
+                    this.reportSurfaceState(this.state);
+                else
+                    this.reportRoute(route);
+            }
+        });
         window.addEventListener("message", this.onMessage);
         window.addEventListener("focus", this.onFocus);
         window.addEventListener("keydown", this.onKey);
@@ -30,12 +45,18 @@ export class EmbeddedUiClient {
             this.setEnvironment("unsupported", "unsupported_nesting");
     }
     getEnvironment = () => this.environment;
+    getChrome = () => this.composition.getChrome();
+    subscribeChrome = (listener) => this.composition.subscribeChrome(listener);
+    getNavigation = () => this.composition.getNavigation();
+    subscribeNavigation = (listener) => this.composition.subscribeNavigation(listener);
     setActive(active) {
         if (this.active === active)
             return;
         if (!active)
             this.post({ type: "hosty:ui:auth-required" });
         this.active = active;
+        this.composition.resetNavigation();
+        this.localActions.clear();
         this.channel = null;
         this.verifying = null;
         this.nonce = createPresentationRequestId();
@@ -72,11 +93,12 @@ export class EmbeddedUiClient {
         if (this.disposed)
             return;
         this.environment = { mode: "embedded", connection, ...(code ? { code } : {}) };
+        this.composition.setEnvironment(this.environment);
         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 }, "*");
+            window.parent.postMessage({ type: "hosty:ui:probe", version: 1, versions: [1], capabilities: [UI_COMPOSITION_CAPABILITY], childNonce: this.nonce }, "*");
     }
     discover() {
         clearTimeout(this.deadline);
@@ -154,7 +176,7 @@ export class EmbeddedUiClient {
                 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 });
+                this.post({ type: "hosty:ui:accept", capabilities: [UI_COMPOSITION_CAPABILITY], coreOrigin: own.coreOrigin, userId: own.userId, appId: own.app.appId, installationId: own.app.installationId });
             }
             catch (error) {
                 if (this.disposed || !this.active || this.verifying !== key)
@@ -179,16 +201,29 @@ export class EmbeddedUiClient {
             }
             clearTimeout(this.deadline);
             this.setEnvironment("connected");
+            if (Array.isArray(msg.capabilities) && msg.capabilities.includes(UI_COMPOSITION_CAPABILITY)) {
+                this.composition.setHostPolicy(channel.generation, msg.revision, msg.chrome, msg.rootDisabled === true, msg.endpoint);
+            }
+            else
+                this.composition.setLegacyHost();
+            void this.composition.refreshNavigation();
             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 });
+        if (msg.type === "hosty:ui:chrome" && this.getChrome().capabilities.includes(UI_COMPOSITION_CAPABILITY)) {
+            this.composition.setHostPolicy(channel.generation, msg.revision, msg.chrome, msg.rootDisabled === true, msg.endpoint);
+            return;
+        }
+        if ((msg.type === "hosty:ui:result" || msg.type === "hosty:ui:action-result") && validId(msg.requestId) && validResult(msg.result, msg.requestId)) {
+            const result = msg.result, pending = this.pending.get(msg.requestId);
+            if (result.status === "accepted" && pending?.kind !== "action" || result.status === "opened" && pending?.kind === "action")
+                return;
+            pending?.resolve(result);
+            if (result.status !== "accepted")
+                this.emit({ type: "presentation", value: result });
         }
     }
     async request(requestId, message, signal) {
@@ -199,7 +234,9 @@ export class EmbeddedUiClient {
         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 input = message.type === "hosty:ui:status" ? null : JSON.stringify([message.type, target?.panel ?? null, target?.route ?? null, message.reuse ?? "exact", message.entryKey ?? null]);
+        if (this.localActions.has(requestId))
+            return { status: "rejected", requestId, code: "request_conflict" };
         const existing = this.pending.get(requestId);
         if (existing) {
             if (input !== null && existing.input !== null && input !== existing.input)
@@ -214,11 +251,11 @@ export class EmbeddedUiClient {
             }
             return this.wait(requestId, existing, signal);
         }
-        if (this.pending.size >= 4)
+        if (this.pending.size + [...this.localActions.values()].filter(value => value.pending).length >= 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 => {
+        const entry = { kind: message.type === "hosty:ui:picker" || message.type === "hosty:ui:navigate" ? "action" : "presentation", input, operation, waiters: 0, sent: false, resolve: result => {
                 if (this.pending.get(requestId) === entry)
                     this.pending.delete(requestId);
                 settle(result);
@@ -247,17 +284,86 @@ export class EmbeddedUiClient {
                 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" });
+    openSurface = (target, options) => {
+        if (!this.getChrome().tools.enabled)
+            return Promise.resolve({ status: "blocked", requestId: options.requestId, code: "tools_disabled" });
+        if (options.reuse !== undefined && !this.getChrome().capabilities.includes(UI_COMPOSITION_CAPABILITY))
+            return Promise.resolve({ status: "unsupported", requestId: options.requestId, code: "unsupported_composition" });
+        return validTarget(target) && options.placement === "side"
+            ? this.request(options.requestId, { type: "hosty:ui:open", target, placement: "side", ...(options.reuse ? { reuse: options.reuse } : {}) }, options.signal)
+            : Promise.resolve({ status: "rejected", requestId: options.requestId, code: "invalid_presentation" });
+    };
     getPresentation = (requestId, options) => this.request(requestId, { type: "hosty:ui:status" }, options?.signal);
+    openToolPicker = (options) => {
+        if (!this.getChrome().tools.enabled)
+            return Promise.resolve({ status: "blocked", requestId: options.requestId, code: "tools_disabled" });
+        if (!this.getChrome().capabilities.includes(UI_COMPOSITION_CAPABILITY))
+            return Promise.resolve({ status: "unsupported", requestId: options.requestId, code: "unsupported_composition" });
+        return this.request(options.requestId, { type: "hosty:ui:picker" }, options.signal);
+    };
+    navigate = (entryKey, options) => {
+        const id = options.requestId, existing = this.localActions.get(id);
+        if (!validId(id))
+            return Promise.resolve({ status: "rejected", requestId: id, code: "invalid_presentation" });
+        if (existing)
+            return existing.key === entryKey ? waitForPresentation(existing.result, id, options.signal) : Promise.resolve({ status: "rejected", requestId: id, code: "request_conflict" });
+        const entry = this.getNavigation().entries.find(e => e.key === entryKey);
+        if (!entry?.route)
+            return Promise.resolve({ status: "blocked", requestId: id, code: "destination_changed" });
+        if (!this.composition.isLocalEntry(entry)) {
+            if (!this.getChrome().capabilities.includes(UI_COMPOSITION_CAPABILITY))
+                return Promise.resolve({ status: "unsupported", requestId: id, code: "unsupported_composition" });
+            return this.request(id, { type: "hosty:ui:navigate", entryKey }, options.signal);
+        }
+        if (this.pending.has(id))
+            return Promise.resolve({ status: "rejected", requestId: id, code: "request_conflict" });
+        if (this.pending.size + [...this.localActions.values()].filter(value => value.pending).length >= 4)
+            return Promise.resolve({ status: "blocked", requestId: id, code: "presentation_busy" });
+        const nonce = this.nonce;
+        const operation = Promise.resolve().then(async () => {
+            try {
+                if (!this.active || this.disposed || nonce !== this.nonce)
+                    throw new UiError("activity_required", "Sign in to navigate.");
+                if (options.signal?.aborted)
+                    return { status: "uncertain", requestId: id, code: "presentation_unknown" };
+                await this.composition.navigateLocal(entry);
+                if (!this.active || this.disposed || nonce !== this.nonce)
+                    throw new UiError("activity_required", "Sign in to navigate.");
+                return { status: "accepted", requestId: id };
+            }
+            catch (error) {
+                return failure(id, error);
+            }
+        });
+        const action = { key: entryKey, result: operation, pending: true };
+        this.localActions.set(id, action);
+        void operation.finally(() => {
+            action.pending = false;
+            for (const [key, value] of this.localActions) {
+                if (this.localActions.size <= 256)
+                    break;
+                if (!value.pending)
+                    this.localActions.delete(key);
+            }
+        });
+        return waitForPresentation(operation, id, options.signal);
+    };
+    reportRoute(route) {
+        const entryKey = activeNavigationKey(this.getNavigation().entries, this.composition.currentEndpoint(), route);
+        this.post({ type: "hosty:ui:route", route, ...(entryKey ? { entryKey } : {}) });
+    }
     reportSurfaceState = (state) => {
         this.state = state;
-        if (this.environment.connection === "connected")
+        if (this.environment.connection === "connected") {
+            if (this.getChrome().capabilities.includes(UI_COMPOSITION_CAPABILITY))
+                this.reportRoute(state.route);
             this.post({ type: "hosty:ui:surface-state", ...state });
+        }
     };
     dispose = () => {
         this.disposed = true;
+        this.composition.dispose();
+        this.localActions.clear();
         clearTimeout(this.deadline);
         this.retries.forEach(clearTimeout);
         window.removeEventListener("message", this.onMessage);
@@ -273,6 +379,6 @@ 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");
+    return v.requestId === id && (v.status === "accepted" || (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-layer.d.ts

@@ -0,0 +1,36 @@
+import { type HostyAppFrameProps } from "./ui-frame.js";
+import type { UiHost } from "./ui-host.js";
+import type { PanelTarget } from "./ui-types.js";
+export type UiViewport = {
+    element: HTMLElement;
+    drawer: boolean;
+    onAskAssistant?: HostyAppFrameProps["onAskAssistant"];
+    onAuthRequired?: HostyAppFrameProps["onAuthRequired"];
+    outbound?: {
+        target: PanelTarget;
+        presentationId?: string;
+        message: unknown;
+        nonce: number;
+    } | null;
+};
+/** One stable React frame tree for every dock/window rectangle in this document. */
+export declare class UiFrameLayer {
+    root: HTMLDivElement | null;
+    readonly containers: Map<string, HTMLDivElement>;
+    ensure(id: string): boolean;
+    release(id: string): void;
+    readonly viewports: Map<string, UiViewport>;
+    private revision;
+    private readonly listeners;
+    getSnapshot: () => number;
+    subscribe: (listener: () => void) => () => void;
+    update: () => void;
+    register(id: string, viewport: UiViewport): () => void;
+}
+export declare const UiFrameLayerContext: import("react").Context<UiFrameLayer | null>;
+export declare function presentationElement(id: string): HTMLElement | null;
+export declare function HostyPresentationLayer({ layer, host, active }: {
+    layer: UiFrameLayer;
+    host: UiHost;
+    active: boolean;
+}): import("react").JSX.Element;

package/dist/ui-frame-layer.js

@@ -0,0 +1,88 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, useEffect, useLayoutEffect, useSyncExternalStore } from "react";
+import { HostyAppFrame } from "./ui-frame.js";
+import { createPortal } from "react-dom";
+import { panelKey } from "./ui-types.js";
+/** One stable React frame tree for every dock/window rectangle in this document. */
+export class UiFrameLayer {
+    root = null;
+    containers = new Map();
+    ensure(id) {
+        if (!this.root?.isConnected)
+            return false;
+        if (!this.containers.has(id)) {
+            const element = document.createElement("div");
+            element.dataset.hostyPresentation = id;
+            element.id = `hosty-presentation-${id}`;
+            element.className = "hosty-panel-frame";
+            element.hidden = true;
+            element.inert = true;
+            element.style.display = "none";
+            this.root.append(element);
+            this.containers.set(id, element);
+            this.update();
+        }
+        return true;
+    }
+    release(id) { this.containers.get(id)?.remove(); this.containers.delete(id); this.update(); }
+    viewports = new Map();
+    revision = 0;
+    listeners = new Set();
+    getSnapshot = () => this.revision;
+    subscribe = (listener) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+    update = () => { this.revision++; for (const listener of this.listeners)
+        listener(); };
+    register(id, viewport) {
+        this.viewports.set(id, viewport);
+        this.update();
+        const observer = new ResizeObserver(this.update);
+        observer.observe(viewport.element);
+        return () => { observer.disconnect(); if (this.viewports.get(id) === viewport)
+            this.viewports.delete(id); this.update(); };
+    }
+}
+export const UiFrameLayerContext = createContext(null);
+export function presentationElement(id) {
+    return document.querySelector(`[data-hosty-presentation="${id}"]`);
+}
+export function HostyPresentationLayer({ layer, host, active }) {
+    const state = useSyncExternalStore(host.subscribeSnapshot, host.getSnapshot, host.getSnapshot);
+    useSyncExternalStore(layer.subscribe, layer.getSnapshot, layer.getSnapshot);
+    useEffect(() => {
+        window.addEventListener("resize", layer.update);
+        window.addEventListener("scroll", layer.update, true);
+        return () => { window.removeEventListener("resize", layer.update); window.removeEventListener("scroll", layer.update, true); };
+    }, [layer]);
+    useLayoutEffect(() => {
+        for (const [id, element] of layer.containers) {
+            const tool = state.tools.find(t => t.presentationId === id);
+            if (!tool) {
+                layer.release(id);
+                continue;
+            }
+            const viewport = layer.viewports.get(tool.workspaceId), workspace = state.workspaces?.find(w => w.workspaceId === tool.workspaceId);
+            const visible = !!(active && viewport && workspace?.expanded && workspace.selectedId === id);
+            const rect = viewport?.element.getBoundingClientRect();
+            element.hidden = !visible;
+            element.inert = !visible;
+            Object.assign(element.style, { position: "fixed", left: `${rect?.left ?? 0}px`, top: `${rect?.top ?? 0}px`,
+                width: `${rect?.width ?? 0}px`, height: `${rect?.height ?? 0}px`, zIndex: viewport?.drawer ? "103" : "10", display: visible ? "block" : "none" });
+        }
+    });
+    return _jsxs(_Fragment, { children: [_jsx("div", { ref: element => { layer.root = element; }, className: "hosty-presentation-layer" }), state.tools.map(tool => {
+                const viewport = layer.viewports.get(tool.workspaceId), workspace = state.workspaces?.find(w => w.workspaceId === tool.workspaceId);
+                const surface = tool.resolved.surface, container = layer.containers.get(tool.presentationId);
+                if (!container)
+                    return null;
+                const focusControls = (last) => {
+                    const controls = Array.from(viewport?.element.closest("aside")?.querySelectorAll('button,a[href],select') ?? [])
+                        .filter(element => !element.disabled);
+                    (last ? controls.at(-1) : controls[0])?.focus();
+                };
+                return createPortal(_jsxs(_Fragment, { children: [viewport?.drawer && _jsx("span", { tabIndex: 0, "aria-hidden": "true", className: "hosty-panel-focus-guard", onFocus: () => focusControls(true) }), surface ? _jsx(HostyAppFrame, { surface: { ...surface, panelId: tool.target.panel.panelId }, view: { viewId: `tool-${tool.presentationId}`, workspaceId: tool.workspaceId, presentationId: tool.presentationId, chrome: { navigation: "hide", tools: { launcher: "hide" } } }, title: state.catalog.find(p => panelKey(p.panel) === tool.key)?.label ?? "Tool", standaloneHref: tool.resolved.standaloneHref, onAskAssistant: viewport?.onAskAssistant, onAuthRequired: viewport?.onAuthRequired, onAttention: count => host.setAttention(tool.presentationId, count), outbound: viewport?.outbound && panelKey(viewport.outbound.target.panel) === tool.key
+                                && (viewport.outbound.presentationId ? viewport.outbound.presentationId === tool.presentationId
+                                    : workspace?.selectedId === tool.presentationId && viewport.outbound.target.route === tool.currentRoute) ? viewport.outbound : null })
+                            : _jsxs("div", { className: "hosty-panel-notice", role: "status", children: ["This tool is unavailable (", tool.resolved.state, ")."] }), viewport?.drawer && _jsx("span", { tabIndex: 0, "aria-hidden": "true", className: "hosty-panel-focus-guard", onFocus: () => focusControls(false) })] }), container, tool.presentationId);
+            })] });
+}