@hosty-sdk/app 0.25.12 → 0.27.22

package/dist/overlay-react.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { useAppIdentity } from "./react.js";
@@ -30,7 +30,7 @@ function sessionReady(session) {
     return session?.setup === "ready" && (!session.activityRequired || session.recoveryReady) && !activityExpired(session);
 }
 /** Mount once around protected content. Presentation and recovery belong to Hosty. */
-export function HostyOverlay({ children, probePath = "/api/hosty/session", appCodePath = "/api/auth/app-code", uiPath, panelLayout = "auto" }) {
+export function HostyOverlay({ children, probePath = "/api/hosty/session", appCodePath = "/api/auth/app-code", uiPath, panelLayout = "auto", localContent, chrome, navigation }) {
     const actor = useRef(null);
     const changingActor = useRef(false);
     const [session, setSession] = useState(null);
@@ -80,7 +80,7 @@ export function HostyOverlay({ children, probePath = "/api/hosty/session", appCo
             setReviewing(false);
     }, [session?.setup]);
     useEffect(() => {
-        // No keepalive polling. Focus and a pending Core review are the only readiness refreshes.
+        // Continuous sessions own their maintenance; this also observes pending permission reviews.
         let loading = false;
         const refresh = () => {
             if (loading || !actor.current || activity.pending || (activity.needed && !renewedAwaitingReadiness.current))
@@ -166,7 +166,9 @@ export function HostyOverlay({ children, probePath = "/api/hosty/session", appCo
         action = activity.renew;
         actionLabel = "Renew access";
     }
-    return _jsxs(_Fragment, { children: [_jsx("div", { "data-hosty-content": true, hidden: !ready, inert: !ready, style: ready ? { display: "contents" } : { display: "none" }, children: _jsx(HostyUiRoot, { uiPath: uiPath, panelLayout: panelLayout, active: ready, children: mounted.current ? children : null }) }), !ready && _jsx(OverlaySurface, { pending: pending, title: title, message: message, action: action, actionLabel: actionLabel, reviewUrl: reviewUrl })] });
+    const localOffline = (identity.ui.kind === "unavailable" || (identity.ui.kind === "active" && session?.setup === "unavailable"))
+        && localContent !== undefined;
+    return _jsxs(_Fragment, { children: [localOffline && _jsxs("div", { "data-hosty-local-content": true, children: [_jsx("p", { role: "status", children: "Hosty is unavailable. Local content remains available." }), localContent] }), _jsx("div", { "data-hosty-content": true, hidden: !ready, inert: !ready, style: ready ? { display: "contents" } : { display: "none" }, children: _jsx(HostyUiRoot, { chrome: chrome, navigation: navigation, uiPath: uiPath, panelLayout: panelLayout, active: ready, children: mounted.current ? children : null }) }), !ready && !localOffline && _jsx(OverlaySurface, { pending: pending, title: title, message: message, action: action, actionLabel: actionLabel, reviewUrl: reviewUrl })] });
 }
 function OverlaySurface({ pending, title, message, action, actionLabel, reviewUrl }) {
     const [portal, setPortal] = useState(null);

package/dist/react.d.ts

@@ -1,3 +1,4 @@
+import { type AppContinuity } from "./continuity.js";
 import type { AppAuthProtocol } from "./app-code.js";
 import type { ReactNode } from "react";
 import { type AppLaunchMode, type AppSessionStatus } from "./index.js";
@@ -71,6 +72,7 @@ export declare function useAppIdentity({ probePath, appCodePath, onSession, }?:
         appAuthProtocol: AppAuthProtocol;
         activeUntil?: string | null;
         activityRequired?: boolean;
+        continuity?: AppContinuity;
     } | null;
     hasBeenActive: boolean;
     refresh: () => Promise<unknown>;
@@ -107,3 +109,4 @@ export declare function HostThemeBridge({ followSystem, onTheme }?: HostThemeBri
 export { MissingPermissionsNotice } from "./permissions-react.js";
 export { AppActivityBridge } from "./activity-react.js";
 export { HostyOverlay } from "./overlay-react.js";
+export { HostyNavigation, HostyNavigationBoundary, useHostyChrome, useHostyNavigation } from "./ui-navigation-react.js";

package/dist/react.js

@@ -1,8 +1,11 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { captureChromeHints } from "./ui-composition.js";
 // React slice: the client identity bridge — probe, silent recovery, and the fallback
 // cards. Prop-less by design: the app id and browser-reachable Core origin arrive in the
 // probe response's `recovery` field (request-time values, never build-time props).
+import { readAppContinuity } from "./continuity.js";
+import { configureAppContinuity } from "./continuity-browser.js";
 import { AppActivityBridge } from "./activity-react.js";
 import { AuthNotice, AuthNoticeButton, authNoticeActionStyle } from "./auth-notice.js";
 import { useEffect, useRef, useState } from "react";
@@ -136,6 +139,7 @@ function currentLaunchMode() {
  */
 export function HostLaunchBridge() {
     useEffect(() => {
+        captureChromeHints();
         const url = new URL(window.location.href);
         const param = url.searchParams.get(LAUNCH_MODE_PARAM);
         const { mode, fromParam } = resolveLaunchMode({
@@ -203,6 +207,18 @@ export function useAppIdentity({ probePath = "/api/auth/identity", appCodePath =
     const exchangeRef = useRef(null);
     const onSessionRef = useRef(onSession);
     useEffect(() => { onSessionRef.current = onSession; }, [onSession]);
+    const continuity = activity?.continuity;
+    const continuityActor = session?.userId;
+    useEffect(() => {
+        if (!continuity || !activity?.openUrl || !continuityActor)
+            return;
+        return configureAppContinuity({ coreOrigin: new URL(activity.openUrl).origin, authority: continuity,
+            probe: async () => {
+                const next = await refreshRef.current();
+                return next?.status === "active" && next.userId === continuityActor
+                    && (!next.hosty || (next.hosty.version === 1 && next.hosty.setup === "ready"));
+            } });
+    }, [continuity?.grantId, activity?.openUrl, continuityActor]);
     useEffect(() => {
         let cancelled = false;
         let probeSequence = 0;
@@ -263,7 +279,7 @@ export function useAppIdentity({ probePath = "/api/auth/identity", appCodePath =
             forgetRejectedAppGrant(rejectionCode, revision);
             if (openUrl && protocol)
                 setActivity({ openUrl, appAuthProtocol: protocol,
-                    activeUntil: activityMetadata?.activeUntil, activityRequired: activityMetadata?.activityRequired });
+                    activeUntil: activityMetadata?.activeUntil, activityRequired: activityMetadata?.activityRequired, continuity: readAppContinuity(activityMetadata?.continuity) });
             const initialLoad = firstProbe.current;
             firstProbe.current = false;
             if (silentError.current === "access_denied") {
@@ -551,3 +567,4 @@ export function HostThemeBridge({ followSystem = true, onTheme } = {}) {
 export { MissingPermissionsNotice } from "./permissions-react.js";
 export { AppActivityBridge } from "./activity-react.js";
 export { HostyOverlay } from "./overlay-react.js";
+export { HostyNavigation, HostyNavigationBoundary, useHostyChrome, useHostyNavigation } from "./ui-navigation-react.js";

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import "server-only";
+import { type AppContinuity } from "./continuity.js";
 import { type AppAuthProtocol } from "./app-code.js";
 export { isValidCodeVerifier } from "./app-code.js";
 import { type AppSessionFailureStatus, type AppSessionStatus, type SessionRecoveryParams } from "./index.js";
@@ -25,6 +26,7 @@ export interface HostIdentity {
     expiresAt: string | null;
     activeUntil?: string | null;
     activityRequired?: boolean;
+    continuity?: AppContinuity;
 }
 /** Structured detail for a failed resolution: the Core HTTP status (null when Core was
  * never reached) plus a machine-readable code and human-readable message. Codes pass

package/dist/server.js

@@ -1,6 +1,7 @@
 // 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";
@@ -221,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-composition.d.ts

@@ -0,0 +1,71 @@
+import { type UiChromeOverrides, type UiChromeSnapshot, type UiChromeSource, type UiEnvironment, type UiNavigationCatalog, type UiNavigationEntry, type UiNavigationSnapshot, type UiRouterAdapter } from "./ui-types.js";
+export declare const CHROME_HINT_ATTRIBUTE = "data-hosty-chrome-hints";
+export declare function parseChromeHints(search: string): UiChromeOverrides & {
+    legacy?: "show" | "hide";
+};
+export declare function validChromeOverrides(value: unknown): value is UiChromeOverrides;
+export declare function resolveChrome(defaults: UiChromeOverrides, hints: ReturnType<typeof parseChromeHints>, host?: UiChromeOverrides): {
+    navigation: "hide" | "show";
+    enabled: boolean;
+    launcher: "hide" | "show";
+    sources: {
+        navigation: UiChromeSource;
+        enabled: UiChromeSource;
+        launcher: UiChromeSource;
+    };
+};
+export declare const INITIAL_CHROME: UiChromeSnapshot;
+export declare const INITIAL_NAVIGATION: UiNavigationSnapshot;
+/** Presentation hints are captured only for this document, never from inherited session storage. */
+export declare function captureChromeHints(): string;
+export declare function withChromeHints(href: string, chrome: UiChromeOverrides): string;
+export { chromeBootstrapScript } from "./index.js";
+export declare function activeNavigationKey(entries: readonly UiNavigationEntry[], endpoint: string | undefined, route: string): string | null;
+/** Shared observable state for local and embedded clients; it owns no frame or identity authority. */
+export declare class UiCompositionModel {
+    private readonly path;
+    private defaults;
+    private chrome;
+    private navigation;
+    private readonly chromeListeners;
+    private readonly navigationListeners;
+    private readonly hints;
+    private overrides;
+    private hostRevision;
+    private hostGeneration;
+    private rootDisabled;
+    private capabilities;
+    private environment;
+    private router?;
+    private stopRouter?;
+    private endpoint?;
+    private epoch;
+    private disposed;
+    private refreshing;
+    constructor(path: string, mode: UiEnvironment["mode"], defaults?: UiChromeOverrides);
+    getChrome: () => UiChromeSnapshot;
+    subscribeChrome: (listener: () => void) => () => void;
+    getNavigation: () => Readonly<{
+        status: "loading" | "ready" | "unavailable";
+        catalog: UiNavigationCatalog | null;
+        entries: readonly UiNavigationEntry[];
+        activeKey: string | null;
+        code?: string;
+    }>;
+    subscribeNavigation: (listener: () => void) => () => void;
+    configure(defaults: UiChromeOverrides): void;
+    setEnvironment(environment: UiEnvironment): void;
+    setHostPolicy(generation: string, revision: number, policy: UiChromeOverrides, rootDisabled: boolean, endpoint?: string): void;
+    setLegacyHost(): void;
+    private publishChrome;
+    attachRouter(router?: UiRouterAdapter): void;
+    private updateNavigation;
+    currentRoute: () => string;
+    currentEndpoint: () => string | undefined;
+    isLocalEntry(entry: UiNavigationEntry): boolean;
+    updateRoute: () => void;
+    refreshNavigation: () => Promise<void>;
+    resetNavigation(): void;
+    navigateLocal(entry: UiNavigationEntry): Promise<boolean>;
+    dispose(): void;
+}

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";