@hosty-sdk/app 0.25.12 → 0.27.22

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.
 
@@ -69,8 +73,8 @@ After first mount, blocked content and app portals become hidden and inert while
 remains mounted. Same-user renewal restores it. A different stable user ID reloads the app document
 and refuses to replay old pending requests. `APP_SESSION_RESTORED` from `/browser-auth` is an optional
 DOM notification with `detail.userId`; it contains no credential. There is no generic draft persistence
-across reloads or cache-clearing framework. Existing identity idle/absolute lifetimes and fixed
-privileged activity windows still apply.
+across reloads or cache-clearing framework. Current user/app permissions and the authorizing principal's idle/absolute lifetime still apply.
+Core 0.130.0 advertises continuous app sessions; older servers retain their actual activity policy.
 
 Compatible SDK updates change standard presentation and recovery after a dependency update and
 rebuild, without editing this wiring. New mandatory Core capabilities can require upgrading Core.
@@ -289,24 +293,48 @@ reads or `mcp:invoke` for assistant mutations, then apply your application's use
 Do not cache validation. Keep `introspectScopedToken` on ordinary APIs: it does not opt into accepting
 MCP-only credentials. Neither token permits skipping the application's own authorization.
 
-## Privileged activity renewal
+## Continuous app access (Core 0.130.0 / SDK 0.26.0)
 
-Identity probes used by `AppIdentityBridge` pass `activeUntil` and `activityRequired` through from
-`resolveAppSession().identity`. Keep app APIs on `appFetch`; a 401 can then request a user-click
-Core popup, exchange a code on the same origin and retry once without replacing mounted content.
-For another UI framework, use `configureAppActivity` with an app-owned `exchangeCode` function,
-listen for `APP_SESSION_ENDED`, and call `renewAppActivity` directly from a click. Do not navigate
-or reload to renew access. `appActivityNeedsRenewal()` supports proactive click renewal near expiry.
-See [the activity contract](../../docs/features/app-activity-window/feature.md), including the
-separate Core-approved assistant session leases.
+Pass `continuity`, `activeUntil` and `activityRequired` from Core revalidation through custom identity
+probes. Standard SDK adapters do this automatically. `HostyOverlay` / `useAppIdentity` maintain a
+live browser parent through a Core-owned frame and refresh the app-local probe. Checks coalesce,
+run on mount/return/network recovery, and repeat at a jittered five-minute interval. App backends
+cannot keep the browser parent alive with app credentials alone.
 
-## Shared panels (Core 0.129.0 / SDK 0.25.0)
+Keep protected client requests on `appFetch`. An outage returns 503 without clearing identity or
+replaying a mutation. Real expiry uses normal recovery, preserving same-user state. Optional
+`<HostyOverlay localContent={<LocalNotes />}>…</HostyOverlay>` places explicitly local/public
+content outside the protected root during an outage; do not place private actor-bound data there.
+
+For another framework, use `configureAppContinuity` / `ensureAppContinuity` from
+`@hosty-sdk/app/continuity/browser`, with validated metadata from `/continuity` and a probe that
+checks the same actor. The probe must bypass maintenance (`appFetch(path, init, false)`) to avoid
+recursion. Clean up the coordinator on unmount. `APP_CONTINUITY_UPDATED` reports silent success;
+`APP_ACTIVITY_RENEWED` continues to mean explicit recovery. Do not replay handoffs/messages on either.
+Missing continuity metadata keeps older Core's `configureAppActivity`/click renewal behavior.
+
+Server-only unattended work requires an explicit Core grant:
+
+```ts
+import { BackgroundGrantClient } from "@hosty-sdk/app/background/server";
+const background = new BackgroundGrantClient(grantId, "health"); // HOSTY_* service configuration
+const response = await background.core("/api/apps/example.target/health");
+```
+
+The client coalesces credential issuance and refreshes before expiry. It sends each operation once;
+Core enforces the immutable selected scope online. `token()` can supply the existing provider/MCP
+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.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.
 
@@ -320,7 +348,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.
 
@@ -371,3 +399,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/background-server.d.ts

@@ -0,0 +1,16 @@
+import type { ProviderServerOptions } from "@hosty-sdk/app/providers/server";
+/** An explicit Core delegation reference. Keep this client and its credentials on the server. */
+export declare class BackgroundGrantClient {
+    private readonly grantId;
+    private readonly scopeId;
+    private credential?;
+    private pending?;
+    private readonly origin;
+    private readonly appId;
+    private readonly service;
+    constructor(grantId: string, scopeId: string, options?: ProviderServerOptions);
+    /** Coalesces issuance; each protected dispatch still validates the delegation online in Core. */
+    token(): Promise<string>;
+    /** Sends one operation. No automatic replay of a possibly completed mutation. */
+    core(path: string, init?: RequestInit): Promise<Response>;
+}

package/dist/background-server.js

@@ -0,0 +1,52 @@
+import { ProviderError } from "@hosty-sdk/app/providers";
+/** An explicit Core delegation reference. Keep this client and its credentials on the server. */
+export class BackgroundGrantClient {
+    grantId;
+    scopeId;
+    credential;
+    pending;
+    origin;
+    appId;
+    service;
+    constructor(grantId, scopeId, options = {}) {
+        this.grantId = grantId;
+        this.scopeId = scopeId;
+        this.origin = new URL(options.coreOrigin ?? process.env.HOSTY_CORE_ORIGIN ?? "http://127.0.0.1:7070");
+        this.appId = options.appId ?? process.env.HOSTY_APP_ID ?? "";
+        this.service = options.serviceToken ?? process.env.HOSTY_APP_SERVICE_TOKEN ?? "";
+        if (!this.appId || !this.service || !grantId || !scopeId)
+            throw new Error("An app service identity and explicit background grant/scope references are required.");
+    }
+    /** Coalesces issuance; each protected dispatch still validates the delegation online in Core. */
+    token() {
+        if (this.credential && Date.parse(this.credential.expiresAt) > Date.now() + 30_000)
+            return Promise.resolve(this.credential.accessToken);
+        if (this.pending)
+            return this.pending;
+        this.pending = (async () => {
+            const response = await fetch(new URL(`/api/internal/apps/${encodeURIComponent(this.appId)}/background/token`, this.origin), {
+                method: "POST", redirect: "error", cache: "no-store", signal: AbortSignal.timeout(10_000),
+                headers: { authorization: `Bearer ${this.service}`, "content-type": "application/json" },
+                body: JSON.stringify({ grantId: this.grantId, scopeId: this.scopeId }),
+            });
+            const body = await response.json();
+            if (!response.ok)
+                throw new ProviderError(body.code ?? "background_denied", body.message ?? "Background access is unavailable.", response.status);
+            if (typeof body.accessToken !== "string" || !Number.isFinite(Date.parse(body.expiresAt)))
+                throw new Error("Invalid background credential response.");
+            this.credential = body;
+            return body.accessToken;
+        })().finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    /** Sends one operation. No automatic replay of a possibly completed mutation. */
+    async core(path, init = {}) {
+        const url = new URL(path, this.origin);
+        if (url.origin !== this.origin.origin || !url.pathname.startsWith("/api/apps/") || url.username || url.password)
+            throw new Error("Use a Core app operation path.");
+        const headers = new Headers(init.headers);
+        headers.set("authorization", `Bearer ${this.service}`);
+        headers.set("X-Hosty-App-Identity", await this.token());
+        return fetch(url, { ...init, headers, redirect: "error", cache: "no-store" });
+    }
+}

package/dist/browser-auth.d.ts

@@ -1,3 +1,5 @@
+export { APP_CONTINUITY_UPDATED } from "@hosty-sdk/app/continuity/browser";
+export { readAppContinuity, type AppContinuity } from "@hosty-sdk/app/continuity";
 import type { AppAuthProtocol } from "./app-code.js";
 export type AppSignInResult = {
     code: string;

package/dist/browser-auth.js

@@ -1,3 +1,6 @@
+import { ensureAppContinuity } from "@hosty-sdk/app/continuity/browser";
+export { APP_CONTINUITY_UPDATED } from "@hosty-sdk/app/continuity/browser";
+export { readAppContinuity } from "@hosty-sdk/app/continuity";
 import { sha256 } from "@noble/hashes/sha2.js";
 function isValidCodeVerifier(value) {
     return typeof value === "string" && /^[A-Za-z0-9._~-]{43,128}$/.test(value);
@@ -270,6 +273,8 @@ export async function appFetch(input, init = {}, recover = true) {
     // SDK identity/protocol probes use recover=false so that validation itself can proceed.
     if (recover && renewal && activityConfig?.validateSession && !await waitForActivity(init.signal))
         return Response.json({ code: "reauth_required", message: "Hosty access has not been restored." }, { status: 401 });
+    if (recover && !await ensureAppContinuity())
+        return Response.json({ code: "session_unavailable", message: "Hosty access could not be verified." }, { status: 503 });
     const current = grant?.origin === url.origin ? grant : null;
     const headers = new Headers(init.headers);
     if (current)

package/dist/continuity-browser.d.ts

@@ -0,0 +1,11 @@
+import type { AppContinuity } from "./continuity.js";
+export declare const APP_CONTINUITY_UPDATED = "hosty:app-continuity-updated";
+type Owner = {
+    coreOrigin: string;
+    authority: AppContinuity;
+    probe: () => Promise<boolean>;
+};
+/** One coordinator per app document; probes bypass appFetch's maintenance to avoid recursion. */
+export declare function ensureAppContinuity(force?: boolean): Promise<boolean>;
+export declare function configureAppContinuity(config: Owner): () => void;
+export {};

package/dist/continuity-browser.js

@@ -0,0 +1,92 @@
+export const APP_CONTINUITY_UPDATED = "hosty:app-continuity-updated";
+let owner = null;
+let pending = null;
+let checkedAt = 0;
+let valid = true;
+/** One coordinator per app document; probes bypass appFetch's maintenance to avoid recursion. */
+export async function ensureAppContinuity(force = false) {
+    if (!owner)
+        return true;
+    if (pending)
+        return pending;
+    if (!force && Date.now() - checkedAt < Math.min(30_000, owner.authority.checkAfterSeconds * 1000))
+        return valid;
+    const current = owner;
+    pending = (async () => {
+        // Browser policy may refuse the frame. Only the app's authoritative probe decides access.
+        if (current.authority.mode === "browser")
+            await maintainParent(current);
+        const result = await current.probe().catch(() => false);
+        if (owner !== current)
+            return false;
+        valid = result;
+        checkedAt = Date.now();
+        if (result)
+            window.dispatchEvent(new Event(APP_CONTINUITY_UPDATED));
+        return result;
+    })().finally(() => { pending = null; });
+    return pending;
+}
+export function configureAppContinuity(config) {
+    owner = config;
+    checkedAt = 0;
+    valid = true;
+    let disposed = false;
+    let failures = 0;
+    let scheduleVersion = 0;
+    let timer;
+    const schedule = async (force = false) => {
+        const version = ++scheduleVersion;
+        clearTimeout(timer);
+        const ok = await ensureAppContinuity(force);
+        // Events can share one pending probe; only the latest waiter installs its next timer.
+        if (disposed || version !== scheduleVersion)
+            return;
+        failures = ok ? 0 : Math.min(4, failures + 1);
+        const seconds = ok ? config.authority.checkAfterSeconds : Math.min(300, 15 * 2 ** failures);
+        timer = setTimeout(() => { void schedule(true); }, seconds * 1000 * (0.9 + Math.random() * 0.2));
+    };
+    const wake = () => { void schedule(); };
+    const online = () => { void schedule(true); };
+    window.addEventListener("focus", wake);
+    window.addEventListener("online", online);
+    document.addEventListener("visibilitychange", wake);
+    void schedule(true);
+    return () => {
+        disposed = true;
+        clearTimeout(timer);
+        window.removeEventListener("focus", wake);
+        window.removeEventListener("online", online);
+        document.removeEventListener("visibilitychange", wake);
+        if (owner === config) {
+            owner = null;
+            checkedAt = 0;
+        }
+    };
+}
+function maintainParent(config) {
+    return new Promise(resolve => {
+        const state = Array.from(crypto.getRandomValues(new Uint8Array(32)), b => b.toString(16).padStart(2, "0")).join("");
+        const url = new URL("/api/auth/apps/continuity/frame", config.coreOrigin);
+        url.searchParams.set("grantId", config.authority.grantId);
+        url.searchParams.set("origin", window.location.origin);
+        url.searchParams.set("state", state);
+        const frame = document.createElement("iframe");
+        frame.hidden = true;
+        frame.title = "Hosty session maintenance";
+        frame.referrerPolicy = "no-referrer";
+        const done = () => { clearTimeout(timer); window.removeEventListener("message", received); frame.remove(); resolve(); };
+        const received = (event) => {
+            if (event.source === frame.contentWindow && event.origin === url.origin &&
+                event.data?.type === "hosty:continuity-result" && event.data.state === state &&
+                ["maintained", "unavailable"].includes(event.data.status))
+                done();
+        };
+        const timer = setTimeout(done, 4_000);
+        window.addEventListener("message", received);
+        frame.onload = () => frame.contentWindow?.postMessage({ type: "hosty:continuity-check", state }, url.origin);
+        frame.onerror = done;
+        frame.src = url.href;
+        document.body.append(frame);
+    });
+}

package/dist/continuity.d.ts

@@ -0,0 +1,9 @@
+/** Server-advertised authority, never inferred from embedding or a missing activity deadline. */
+export type AppContinuity = {
+    version: 1;
+    mode: "browser" | "native";
+    grantId: string;
+    expiresAt: string;
+    checkAfterSeconds: number;
+};
+export declare function readAppContinuity(value: unknown): AppContinuity | undefined;

package/dist/continuity.js

@@ -0,0 +1,9 @@
+export function readAppContinuity(value) {
+    const v = value;
+    if (v?.version !== 1 || !["browser", "native"].includes(v.mode ?? "") ||
+        typeof v.grantId !== "string" || !v.grantId || v.grantId.length > 128 ||
+        typeof v.expiresAt !== "string" || !Number.isFinite(Date.parse(v.expiresAt)) ||
+        typeof v.checkAfterSeconds !== "number" || !Number.isFinite(v.checkAfterSeconds) || v.checkAfterSeconds <= 0)
+        return;
+    return { ...v, checkAfterSeconds: Math.min(300, v.checkAfterSeconds) };
+}

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,6 +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 }: {
+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;