@hosty-sdk/app 0.26.0 → 0.27.23

package/README.md

@@ -11,6 +11,9 @@ npm install @hosty-sdk/app
 | --- | --- | --- |
 | `@hosty-sdk/app` | anywhere | status taxonomy, recovery decision, `hosty:auth-required` and `hosty:request-delegated-token` schemas, URL/env helpers |
 | `@hosty-sdk/app/server` | server only | Core revalidation with caching, cookie helpers, the app-code route factory, the app secrets client |
+| `@hosty-sdk/app/next` | Next client | `HostyNextOverlay`, `HostyNextNavigationBridge` for App Router navigation |
+| `@hosty-sdk/app/ui` | client | policy/navigation snapshots, replayable navigation, chooser and presentation operations |
+| `@hosty-sdk/app/ui/react` | React client | navigation boundaries/hooks, app frames and retained panel workspaces |
 | `@hosty-sdk/app/react` | client | `<HostyOverlay />` — shared loading, identity, required setup and recovery UI; legacy bridges remain available |
 | `@hosty-sdk/app/session/server` | server | Framework-neutral session response adapter for authenticated Node servers |
 | `@hosty-sdk/app/embedder` | client | theme sender and legacy embedder message parsers; Shell no longer mints app credentials |
@@ -23,8 +26,8 @@ Minimal Next.js wiring (the configuration object stays server-side):
 
 ```tsx
 // app/layout.tsx — inside the body and the existing theme/launch providers
-import { HostyOverlay } from "@hosty-sdk/app/react";
-// <HostyOverlay>{children}</HostyOverlay>
+import { HostyNextOverlay } from "@hosty-sdk/app/next";
+// <HostyNextOverlay>{children}</HostyNextOverlay>
 
 // lib/hosty.ts
 export const hostyConfig = {
@@ -48,8 +51,9 @@ export const POST = createAppCodeRouteHandler(hostyConfig);
 
 Replace the protected scope's `AppIdentityBridge`, `AppActivityBridge`, custom sign-in rendering
 and `MissingPermissionsNotice` with one `HostyOverlay`. Keep public routes outside that scope.
-Existing launch/theme bridges and bootstrap scripts stay in place. The only optional overlay props
-are `probePath` and `appCodePath` for existing route names; it has no visual customization API.
+Existing launch/theme bridges stay in place for transport compatibility; add the composition
+bootstrap below. `probePath` and `appCodePath` support existing route names. `chrome`, `navigation`
+and `panelLayout` configure UI composition without replacing authentication/recovery rendering.
 API routes and server-rendered data still enforce their own authorization. The overlay delays
 protected client mounting; it is not a server data-access boundary.
 
@@ -323,16 +327,28 @@ client's user-token input. Keep tokens server-side. See
 [Continuous App Access](../../docs/features/continuous-app-access/feature.md) for creation, logout,
 revocation, exact MCP tools and installation boundaries. Background grants do not create a scheduler.
 
-## Shared panels (Core 0.129.0 / SDK 0.25.0)
+## Shared panels (Core 0.131.0 / SDK 0.27.0)
 
 `HostyOverlay` composes one UI owner per top-level browser document. Its default
 `panelLayout="auto"` adds an opened-tool rail, an **Add tool** chooser and a resizable
 workspace. In a directly embedded app it delegates presentation to the verified parent
-and renders no local rail. Use `panelLayout="slot"` with exactly one
-`HostyPanelWorkspace` inside your chrome, or `"none"` for a custom controller renderer.
+and renders no local rail. Use `panelLayout="slot"` with a `HostyPanelWorkspace` per workspace
+ID inside your chrome, or `"none"` with an explicitly registered custom renderer. Without a renderer,
+disable local tools; an opening otherwise fails with `presentation_unavailable`.
 Panel hosting requires reviewed optional `apps.panels.read` (or existing `apps.read`);
 participating as a child does not require catalog access.
 
+Panel headers expose **Minimize panel (keep tool open)** (`−`) without a close button.
+Hosts with a tool rail can set `minimizeControl="drawer"` on `HostyPanelWorkspace` to omit the
+minimize button in docked panels and use the active rail icon to toggle them. Responsive drawers
+keep a visible minimize button because the rail is inert while a drawer is open. The default
+`minimizeControl="always"` retains the button in standalone layouts.
+Custom host layouts can use `UiHost.closePresentation(presentationId)` to release a tool view;
+this does not end its conversation or background work.
+To match host chrome, set `--hosty-panel-background`, `--hosty-panel-foreground`,
+`--hosty-panel-muted` and `--hosty-panel-border` on the workspace or an ancestor.
+These overrides apply in both themes; omitted properties retain the SDK light/dark defaults.
+
 ```ts
 // app/api/hosty/ui/[...action]/route.ts — own app configuration/session only
 import { createHostyUiRouteHandler } from "@hosty-sdk/app/server";
@@ -343,7 +359,7 @@ export const POST = handler;
 
 Non-Next servers use `createHostyUiResponse` from `@hosty-sdk/app/ui/server` with their
 revalidated own app-user session/token. `UiServerClient` provides only `bootstrap`,
-`listPanels` and `resolvePanel`; never expose a generic Core proxy or caller-supplied credentials.
+`listPanels`, `resolvePanel`, `navigation` and `resolveNavigation`; never expose a generic Core proxy or caller-supplied credentials.
 Both server adapters return `no-store` metadata. The React root's `uiPath` defaults to
 `/api/hosty/ui` and must be a same-origin path.
 
@@ -394,3 +410,137 @@ peer metadata. Matching opaque Core/user contexts prevents accidental account mi
 between cooperating apps; it is not attestation of app code or delegated API authority.
 Every target API still authorizes its own session. Older surfaces remain `unreported`.
 See [the panel contract and verification](../../docs/features/sdk-panel-system/feature.md).
+
+## Navigation and UI composition
+
+Supply identical root defaults to the before-paint bootstrap and overlay. Omitted defaults show
+navigation and enable the standalone tool rail/chooser. Hints and verified host policy can override
+each leaf independently; neither framing nor copied launch-mode storage hides the new navigation.
+
+```tsx
+// app/layout.tsx
+import { chromeBootstrapScript } from "@hosty-sdk/app";
+import { HostyNextOverlay } from "@hosty-sdk/app/next";
+
+const chrome = { navigation: "show" as const, tools: { enabled: true, launcher: "show" as const } };
+// In <head>, before hydration and the legacy launch bridge:
+// <script dangerouslySetInnerHTML={{ __html: chromeBootstrapScript(chrome) }} />
+// In <body>, around protected app content:
+// <HostyNextOverlay chrome={chrome}>{children}</HostyNextOverlay>
+```
+
+For React without Next, use `HostyOverlay` and optionally pass
+`navigation={{ renderer: "standard", router }}`. A router implements `getRoute(): string`,
+`subscribe(listener): () => void` and `navigate(relativeRoute): void | Promise<void>`; optional
+`endpoint` disambiguates several endpoint names on the same origin. Without an adapter the SDK
+uses document navigation. The Next entry is optional and does not add Next to plain SDK consumers.
+
+The standard renderer uses only manifest `ui.navigation`. Own navigation needs ordinary app access,
+not `apps.panels.read`. Unavailable metadata has a retry state; an empty declaration adds no menu.
+Same-endpoint links use cached validated metadata and the app router; endpoint changes revalidate
+through Core and replace the same host view. Modified clicks use pinned standalone links.
+
+For custom navigation, suppress the automatic menu and wrap only page navigation/branding:
+
+```tsx
+import { HostyNavigationBoundary, useHostyChrome, useHostyNavigation } from "@hosty-sdk/app/ui/react";
+
+// <HostyNextOverlay navigation={{ renderer: "custom" }}>
+//   <HostyNavigationBoundary><MyPageNavigation /></HostyNavigationBoundary>
+//   <ProjectSelector />  // Contextual controls stay reachable when navigation is hidden.
+//   {children}
+// </HostyNextOverlay>
+```
+
+The boundary retains component state while hidden and moves hidden focus to the content landmark.
+Alternatively place `HostyNavigation` at a custom location. Framework-neutral renderers subscribe
+to `ui.getChrome/subscribeChrome` and `ui.getNavigation/subscribeNavigation`, then apply equivalent
+hidden/inert/focus behavior. Snapshots are immutable. `tools.owner` is derived by the SDK; it is not
+a configurable default or URL field.
+
+```ts
+const result = await ui.navigate(entry.key, { requestId: crypto.randomUUID() });
+const picker = await ui.openToolPicker({ requestId: crypto.randomUUID() });
+// accepted means navigation was accepted / the chooser became visible.
+// Retain request IDs for uncertain retries; an accepted replay does not repeat the action.
+```
+
+Document hints are `hosty_navigation=show|hide`, `hosty_tools=enabled|disabled` and
+`hosty_tool_launcher=show|hide`. The SDK removes them from the visible URL, preserving history
+state. They are not persisted. Verified host overrides take precedence, then hints, app defaults,
+the current document's legacy launch fallback for navigation, and standalone defaults. Hints grant
+no access or hosting authority. Hiding a launcher permits programmatic presentation; disabling
+tools rejects new requests. A root disable applies to every source and collapses retained tools.
+
+### Host views and retained tools
+
+`HostyAppFrame` accepts a view descriptor. A desktop host can choose different policy from Shell:
+
+```tsx
+<HostyAppFrame surface={validatedSurface} title="Plans"
+  view={{ viewId: "plans-window-1", workspaceId: "default",
+    chrome: { navigation: "show", tools: { enabled: true, launcher: "hide" } },
+    navigate: surface => replaceWindowSurface(surface) }} />
+```
+
+Omit `navigate` for the SDK's plain iframe replacement, or use it to update the host's route/window
+model. Key a replaced React frame by its immutable surface; live `chrome` updates keep that key.
+One top-level coordinator handles direct app/tool children. It never delegates credentials.
+
+Panel declarations and presentations have different identities. `PanelRef` identifies a manifest
+tool. `openSurface` returns an SDK `presentationId`; its `requestId` identifies only the operation.
+Default `reuse: "exact"` focuses the matching target in the destination workspace. A distinct route
+retains another frame; `reuse: "new"` creates another even for the same route. Rails have one item
+per declaration and an instance switcher. Replaying a closed presentation's operation does not
+resurrect it; use a new request to reopen. Domain sessions remain owned by the app.
+
+```ts
+const opened = await ui.openSurface(target, {
+  placement: "side", requestId: crypto.randomUUID(), reuse: "exact",
+});
+// A host may satisfy "side" with a dock or tool window.
+```
+
+Hosts use `useHostyUiHost()` or `createUiHost()`:
+
+```ts
+host.setViewChrome("plans-window-1", { navigation: "show", tools: { launcher: "hide" } });
+host.setPlacementResolver(({ source, target, presentations }) => ({ workspaceId: "shared" }));
+host.focusPresentation(presentationId);
+host.collapseWorkspace("shared");
+await host.movePresentation(presentationId, "floating");
+host.closePresentation(presentationId); // Does not delete the conversation.
+```
+
+Register destinations before their views. React's `<HostyPanelWorkspace workspaceId="shared">`
+implements the renderer; `panelLayout="slot"` lets the host place multiple named workspaces.
+`layout="dock"` keeps dock geometry inside an independent tool window. The default `responsive`
+layout switches to a drawer in a narrow region. Keep populated workspaces mounted until their
+presentations are moved or explicitly closed.
+
+Non-React hosts call `registerWorkspace({ workspaceId, renderer })`. A renderer implements async
+`present(instance, signal)` and `showToolPicker(signal)` returning `accepted | unavailable`, plus
+`focus(id)`, `collapse()` and `release(id)`. Acceptance requires an attached visible destination,
+not a promise of later UI. Matching `frameLayer` object identities allow movement; the renderer
+must preserve iframe DOM parent and browsing context, changing geometry instead of reparenting.
+The supplied React renderer does this. A failed move leaves the original presentation in place.
+
+A placement resolver can nominate `presentationId` together with its actual workspace, but only
+an exact resolved target is accepted. Requests are ordered per destination before asynchronous
+resolution; a newer selection or collapse supersedes older work. Closing an app view cancels its
+unaccepted requests and preserves accepted shared presentations. All browser IDs and ledgers are
+local to the document; Core stores no browser workspace/session registry.
+
+### Compatibility and migration
+
+Both peers negotiate `ui.composition.v1` inside the existing verified wire-v1 handshake. New/old
+peers keep legacy openings without new options. Explicit reuse, remote navigation or picker calls
+to old hosts return `unsupported_composition`; the SDK does not silently discard those options.
+Host loss preserves stale policy and exposes reconnect/separate recovery, without taking local
+ownership. Silent session renewal preserves same-actor frames and drafts.
+
+Remove `hosty-shell-chrome`/`data-hosty-launch` visibility CSS when adopting navigation boundaries.
+Keep launch/auth exports for older hosts and native transport. Native clients send explicit hidden
+navigation/launcher and disabled tools until they provide a panel host. `panelLayout="none"` is a
+rendering choice, not a disable policy: explicitly disable local tools or register a renderer.
+See [UI composition and browser acceptance](../../docs/features/sdk-ui-composition/feature.md).

package/dist/index.d.ts

@@ -106,7 +106,7 @@ export interface PageLocation {
  */
 export declare function buildCoreOpenUrl(corePublicOrigin: string | null, appId: string, location: PageLocation): string | null;
 /**
- * How a shell is presenting this app.
+ * Legacy launch/transport context. Navigation visibility uses the independent composition policy.
  *
  * - `embedded` — framed by the browser Shell. The shell renders navigation for this app. The
  *   app restores its per-tab grant, tries a silent Core redirect on first load, then uses its
@@ -117,19 +117,19 @@ export declare function buildCoreOpenUrl(corePublicOrigin: string | null, appId:
  * - `standalone` — a plain browser tab on the app's own origin. Nothing else renders navigation
  *   for this app, so it keeps its own.
  *
- * Two independent decisions read this one value and they do not split it the same way: chrome
- * is hidden whenever the mode is not `standalone` (`hidesAppChrome`), while frame-local silent
- * sign-in and popup recovery belong to `embedded` alone (`AppIdentityBridge`). A native web
- * view keeps standalone recovery even though its app chrome is hidden.
+ * Legacy consumers can still use `hidesAppChrome`. New consumers use `useHostyChrome` and
+ * `HostyNavigationBoundary`; a desktop host can keep navigation visible in embedded apps.
+ * Authentication continues to use the actual transport environment.
  */
 export type AppLaunchMode = "embedded" | "native" | "standalone";
 /** The query parameter a shell appends to the launch URL to declare the mode. */
 export declare const LAUNCH_MODE_PARAM = "hosty_launch";
 /** Where a resolved mode is kept for the life of the tab or web view. */
 export declare const LAUNCH_MODE_STORAGE_KEY = "hosty.launch.mode";
-/** The root attribute the launch bridge writes; CSS hides duplicated chrome off it. */
+/** Legacy launch attribute. Use data-hosty-navigation for composition visibility. */
 export declare const LAUNCH_MODE_ATTRIBUTE = "data-hosty-launch";
 /**
+ * @deprecated Use HostyNavigationBoundary or the effective navigation policy.
  * Marks an element that duplicates chrome a shell already renders — the app's own name and the
  * navigation between its manifest pages. Contextual controls and information a shell does not
  * render (a project picker, a refresh action, an identity badge) are not chrome in this sense
@@ -164,6 +164,7 @@ export declare function resolveLaunchMode(input: {
     heuristic: AppLaunchMode;
 }): LaunchModeResolution;
 /**
+ * @deprecated Use the effective composition navigation policy instead.
  * True when a shell around this app already renders its name and page navigation, so the app's
  * own copies are duplication. False for `standalone`, where nothing else renders them.
  */
@@ -203,3 +204,5 @@ export declare function decideRecoveryAction(input: {
     openUrl: string | null;
     redirectAlreadyAttempted: boolean;
 }): RecoveryAction;
+/** Paint-time navigation policy. Kept in the pure entry point for Node and edge consumers. */
+export declare function chromeBootstrapScript(defaults?: import("./ui-types").UiChromeOverrides): string;

package/dist/index.js

@@ -142,9 +142,10 @@ export function buildCoreOpenUrl(corePublicOrigin, appId, location) {
 export const LAUNCH_MODE_PARAM = "hosty_launch";
 /** Where a resolved mode is kept for the life of the tab or web view. */
 export const LAUNCH_MODE_STORAGE_KEY = "hosty.launch.mode";
-/** The root attribute the launch bridge writes; CSS hides duplicated chrome off it. */
+/** Legacy launch attribute. Use data-hosty-navigation for composition visibility. */
 export const LAUNCH_MODE_ATTRIBUTE = "data-hosty-launch";
 /**
+ * @deprecated Use HostyNavigationBoundary or the effective navigation policy.
  * Marks an element that duplicates chrome a shell already renders — the app's own name and the
  * navigation between its manifest pages. Contextual controls and information a shell does not
  * render (a project picker, a refresh action, an identity badge) are not chrome in this sense
@@ -188,6 +189,7 @@ export function resolveLaunchMode(input) {
     return { mode: stored ?? input.heuristic, fromParam: false };
 }
 /**
+ * @deprecated Use the effective composition navigation policy instead.
  * True when a shell around this app already renders its name and page navigation, so the app's
  * own copies are duplication. False for `standalone`, where nothing else renders them.
  */
@@ -260,3 +262,10 @@ export function decideRecoveryAction(input) {
     }
     return { kind: "card", card: "signin" };
 }
+/** Paint-time navigation policy. Kept in the pure entry point for Node and edge consumers. */
+export function chromeBootstrapScript(defaults = {}) {
+    const navigation = defaults.navigation;
+    if (navigation !== undefined && navigation !== "show" && navigation !== "hide")
+        throw new Error("Invalid navigation default.");
+    return `(()=>{try{const d=${JSON.stringify({ navigation })},p=new URLSearchParams(location.search),h=new URLSearchParams();for(const k of ["hosty_navigation","hosty_tools","hosty_tool_launcher","hosty_launch"])for(const v of p.getAll(k))h.append(k,v);document.documentElement.setAttribute('data-hosty-chrome-hints',h.toString());const one=k=>p.getAll(k).length===1?p.get(k):null,n=one('hosty_navigation'),l=one('hosty_launch');document.documentElement.setAttribute('data-hosty-navigation',n==='show'||n==='hide'?n:d.navigation??(l==='native'||l==='embedded'?'hide':'show'));}catch{}})();`;
+}

package/dist/next.d.ts

@@ -0,0 +1,4 @@
+import { HostyOverlay } from "./overlay-react.js";
+/** Next routing stays an optional adapter; the composition model does not patch browser history. */
+export declare function HostyNextNavigationBridge(): null;
+export declare function HostyNextOverlay({ children, ...props }: Parameters<typeof HostyOverlay>[0]): import("react").JSX.Element;

package/dist/next.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, useContext, useEffect, useMemo, useRef } from "react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { HostyOverlay } from "./overlay-react.js";
+import { UiCompositionContext } from "./ui-context.js";
+/** Next routing stays an optional adapter; the composition model does not patch browser history. */
+export function HostyNextNavigationBridge() {
+    const model = useContext(UiCompositionContext), router = useRouter(), pathname = usePathname(), search = useSearchParams();
+    const current = useRef(router);
+    current.current = router;
+    const listeners = useRef(new Set());
+    const adapter = useMemo(() => ({
+        getRoute: () => `${window.location.pathname}${window.location.search}${window.location.hash}`,
+        subscribe(listener) {
+            listeners.current.add(listener);
+            window.addEventListener("hashchange", listener);
+            return () => { listeners.current.delete(listener); window.removeEventListener("hashchange", listener); };
+        },
+        navigate(route) { current.current.push(route); },
+    }), []);
+    useEffect(() => { model?.attachRouter(adapter); return () => model?.attachRouter(); }, [model, adapter]);
+    useEffect(() => { for (const listener of listeners.current)
+        listener(); }, [pathname, search]);
+    return null;
+}
+export function HostyNextOverlay({ children, ...props }) {
+    return _jsxs(HostyOverlay, { ...props, children: [_jsx(Suspense, { fallback: null, children: _jsx(HostyNextNavigationBridge, {}) }), children] });
+}

package/dist/overlay-react.d.ts

@@ -1,8 +1,14 @@
 import { type ReactNode } from "react";
+import type { UiChromeOverrides, UiRouterAdapter } from "./ui-types.js";
 /** Mount once around protected content. Presentation and recovery belong to Hosty. */
-export declare function HostyOverlay({ children, probePath, appCodePath, uiPath, panelLayout, localContent }: {
+export declare function HostyOverlay({ children, probePath, appCodePath, uiPath, panelLayout, localContent, chrome, navigation }: {
     /** Explicitly public/local content available during an outage; never put protected actor data here. */
     localContent?: ReactNode;
+    chrome?: UiChromeOverrides;
+    navigation?: {
+        renderer: "standard" | "custom";
+        router?: UiRouterAdapter;
+    };
     children: ReactNode;
     probePath?: string;
     appCodePath?: string;

package/dist/overlay-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", localContent }) {
+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);
@@ -168,7 +168,7 @@ export function HostyOverlay({ children, probePath = "/api/hosty/session", appCo
     }
     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, { 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 })] });
+    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

@@ -109,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,5 +1,6 @@
 "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).
@@ -138,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({
@@ -565,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/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;
+}