@hosty-sdk/app 0.30.0 → 0.32.0

package/README.md

@@ -460,11 +460,20 @@ a configurable default or URL field.
 
 ```ts
 const result = await ui.navigate(entry.key, { requestId: crypto.randomUUID() });
+// Explicitly promote a declared page into the embedder's main application area.
+const main = await ui.navigate(entry.key, {
+  requestId: crypto.randomUUID(), placement: "main", search: "?session=selected-session",
+});
 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.
 ```
 
+Hosts opt in with `host.setMainNavigator(async surface => launchMainPage(surface))`. The SDK resolves
+that caller's entry through Core before invoking it. Main placement preserves the originating panel;
+only the destination query can be overridden. Legacy/standalone hosts report it unavailable instead
+of silently navigating the panel. Normal navigation keeps its existing current-surface behavior.
+
 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,

package/dist/providers-server.d.ts

@@ -1,5 +1,5 @@
 import { AssistantClient } from "@hosty-sdk/app/assistant";
-import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult } from "@hosty-sdk/app/providers";
+import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult, type TranslationRequest, type TranslationResult, type TranslationCapabilities } from "@hosty-sdk/app/providers";
 export type ProviderServerOptions = {
     appId?: string;
     coreOrigin?: string;
@@ -23,6 +23,9 @@ export declare class ProviderClient {
         language?: string;
         signal?: AbortSignal;
     }): Promise<SpeechResult>;
+    translationCapabilities(provider: Pick<ProviderDescriptor, "appId" | "key">, signal?: AbortSignal): Promise<TranslationCapabilities>;
+    /** Translate text or Markdown through the explicitly selected provider; never retries or falls back. */
+    translate(provider: Pick<ProviderDescriptor, "appId" | "key">, input: TranslationRequest, signal?: AbortSignal): Promise<TranslationResult>;
     /** User-attributed requests preserve the assistant's existing handoff and dispatch policy. */
     assistant(provider: Pick<ProviderDescriptor, "appId" | "key"> & {
         installationId?: string | null;

package/dist/providers-server.js

@@ -54,6 +54,20 @@ export class ProviderClient {
         return read(await fetch(url, { method: "POST", redirect: "error", signal,
             headers: { authorization: `Bearer ${binding.token}`, "content-type": audio.type || "audio/wav" }, body: audio }));
     }
+    async translationCapabilities(provider, signal) {
+        const binding = await this.connect({ ...provider, kind: "translation" }, signal);
+        return read(await fetch(`${binding.url}/capabilities`, { redirect: "error", signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000), headers: { authorization: `Bearer ${binding.token}` } }));
+    }
+    /** Translate text or Markdown through the explicitly selected provider; never retries or falls back. */
+    async translate(provider, input, signal) {
+        const deadline = signal ? AbortSignal.any([signal, AbortSignal.timeout(610_000)]) : AbortSignal.timeout(610_000);
+        const binding = await this.connect({ ...provider, kind: "translation" }, deadline);
+        const result = await read(await fetch(`${binding.url}/translations`, { method: "POST", redirect: "error", signal: deadline,
+            headers: { authorization: `Bearer ${binding.token}`, "content-type": "application/json" }, body: JSON.stringify(input) }));
+        if (typeof result.text !== "string" || result.targetLanguage !== input.targetLanguage || result.sourceLanguage !== (input.sourceLanguage ?? "auto"))
+            throw new ProviderError("provider_response_invalid", "Invalid translation response.", 502);
+        return result;
+    }
     /** User-attributed requests preserve the assistant's existing handoff and dispatch policy. */
     async assistant(provider, userToken) {
         const target = { ...provider, kind: "assistant" };

package/dist/providers.d.ts

@@ -1,5 +1,5 @@
 /** Provider categories supported by Core. Agent execution is intentionally not part of this contract. */
-export type ProviderKind = "speech-to-text" | "assistant";
+export type ProviderKind = "speech-to-text" | "assistant" | "translation";
 export type ProviderDescriptor = {
     appId: string;
     displayName: string;
@@ -48,6 +48,29 @@ export type SpeechCapabilities = {
     backend: string;
     ready: boolean;
 };
+export type TranslationRequest = {
+    text: string;
+    targetLanguage: string;
+    sourceLanguage?: string;
+    format?: "text" | "markdown";
+};
+export type TranslationResult = {
+    text: string;
+    targetLanguage: string;
+    sourceLanguage: string;
+};
+export type TranslationCapabilities = {
+    version: 1;
+    formats: string[];
+    maxCharacters: number;
+    maxSegmentCharacters: number;
+    maxBytes: number;
+    maxOutputBytes: number;
+    timeoutSeconds: number;
+    backend: string;
+    ready: boolean;
+    reason?: string;
+};
 /** Errors retain Core/provider codes so consumers can distinguish denial from unavailable service. */
 export declare class ProviderError extends Error {
     readonly code: string;

package/dist/ui-embedded.d.ts

@@ -1,5 +1,5 @@
 import { UiCompositionModel } from "./ui-composition.js";
-import { type UiChromeOverrides, type UiActionOptions, type UiActionResult } from "./ui-types.js";
+import { type UiNavigationOptions, 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. */
@@ -19,6 +19,7 @@ export declare class EmbeddedUiClient implements UiClient {
     private state;
     private active;
     private offered;
+    private mainNavigation;
     private readonly onMessage;
     private readonly onFocus;
     private readonly onKey;
@@ -51,7 +52,7 @@ export declare class EmbeddedUiClient implements UiClient {
         signal?: AbortSignal;
     }) => Promise<PresentationResult>;
     openToolPicker: (options: UiActionOptions) => Promise<UiActionResult>;
-    navigate: (entryKey: string, options: UiActionOptions) => Promise<UiActionResult>;
+    navigate: (entryKey: string, options: UiNavigationOptions) => Promise<UiActionResult>;
     private reportRoute;
     reportSurfaceState: (state: {
         route: string;

package/dist/ui-embedded.js

@@ -1,5 +1,5 @@
 import { activeNavigationKey, UiCompositionModel } from "./ui-composition.js";
-import { UI_COMPOSITION_CAPABILITY } from "./ui-types.js";
+import { UI_COMPOSITION_CAPABILITY, UI_MAIN_NAVIGATION_CAPABILITY, navigationSearch } from "./ui-types.js";
 import { createPresentationRequestId } from "./ui.js";
 import { UiError } from "./ui-types.js";
 import { canonicalSurfaceRoute, DISCOVERY_TIMEOUT, failure, readUiMessage, uiRequest, validId, validTarget, waitForPresentation } from "./ui-transport.js";
@@ -20,6 +20,7 @@ export class EmbeddedUiClient {
     state = null;
     active = true;
     offered = false;
+    mainNavigation = false;
     onMessage = (event) => { void this.receive(event); };
     onFocus = () => { void this.recheck(); };
     onKey = (event) => { if (this.active && !event.defaultPrevented && event.key === "Escape")
@@ -200,6 +201,7 @@ export class EmbeddedUiClient {
                 return;
             }
             clearTimeout(this.deadline);
+            this.mainNavigation = Array.isArray(msg.capabilities) && msg.capabilities.includes(UI_MAIN_NAVIGATION_CAPABILITY);
             this.setEnvironment("connected");
             if (Array.isArray(msg.capabilities) && msg.capabilities.includes(UI_COMPOSITION_CAPABILITY)) {
                 this.composition.setHostPolicy(channel.generation, msg.revision, msg.chrome, msg.rootDisabled === true, msg.endpoint);
@@ -234,7 +236,7 @@ export class EmbeddedUiClient {
         if (signal?.aborted)
             return { status: "uncertain", requestId, code: "presentation_unknown" };
         const target = message.target;
-        const input = message.type === "hosty:ui:status" ? null : JSON.stringify([message.type, target?.panel ?? null, target?.route ?? null, message.reuse ?? "exact", message.entryKey ?? null]);
+        const input = message.type === "hosty:ui:status" ? null : JSON.stringify([message.type, target?.panel ?? null, target?.route ?? null, message.reuse ?? "exact", message.entryKey ?? null, message.search ?? null]);
         if (this.localActions.has(requestId))
             return { status: "rejected", requestId, code: "request_conflict" };
         const existing = this.pending.get(requestId);
@@ -255,7 +257,7 @@ export class EmbeddedUiClient {
             return { status: "blocked", requestId, code: "presentation_busy" };
         let settle;
         const operation = new Promise(resolve => { settle = resolve; });
-        const entry = { kind: message.type === "hosty:ui:picker" || message.type === "hosty:ui:navigate" ? "action" : "presentation", input, operation, waiters: 0, sent: false, resolve: result => {
+        const entry = { kind: message.type === "hosty:ui:picker" || message.type === "hosty:ui:navigate" || message.type === "hosty:ui:navigate-main" ? "action" : "presentation", input, operation, waiters: 0, sent: false, resolve: result => {
                 if (this.pending.get(requestId) === entry)
                     this.pending.delete(requestId);
                 settle(result);
@@ -302,6 +304,13 @@ export class EmbeddedUiClient {
         return this.request(options.requestId, { type: "hosty:ui:picker" }, options.signal);
     };
     navigate = (entryKey, options) => {
+        if (options.placement === "main") {
+            if (!navigationSearch(options.search))
+                return Promise.resolve({ status: "rejected", requestId: options.requestId, code: "destination_invalid" });
+            if (!this.mainNavigation)
+                return Promise.resolve({ status: "unsupported", requestId: options.requestId, code: "main_navigation_unavailable" });
+            return this.request(options.requestId, { type: "hosty:ui:navigate-main", entryKey, search: options.search }, options.signal);
+        }
         const id = options.requestId, existing = this.localActions.get(id);
         if (!validId(id))
             return Promise.resolve({ status: "rejected", requestId: id, code: "invalid_presentation" });

package/dist/ui-host.d.ts

@@ -1,7 +1,7 @@
 import { UiCompositionModel } from "./ui-composition.js";
 import { type UiPresentation, type UiWorkspaceSnapshot, type UiWorkspaceRenderer, type UiViewDescriptor, type UiPlacementResolver } from "./ui-workspaces.js";
 export type { UiWorkspaceRenderer, UiViewDescriptor, UiPlacementResolver, UiPresentation } from "./ui-workspaces.js";
-import { type UiChromeOverrides, type UiActionOptions, type UiActionResult } from "./ui-types.js";
+import { type UiNavigationOptions, type UiChromeOverrides, type UiActionOptions, type UiActionResult } from "./ui-types.js";
 import { type UiClient } from "./ui.js";
 import { type PanelRef, type PanelTarget, type PresentationOptions, type PresentationResult, type UiBootstrap, type UiEnvironment, type UiEvent, type UiFrameSurface, type UiPanel } from "./ui-types.js";
 export type UiTool = UiPresentation & {
@@ -45,6 +45,9 @@ export declare class UiHost implements UiClient {
     readonly composition: UiCompositionModel;
     private readonly workspaces;
     private placement?;
+    private mainNavigator?;
+    /** The host chooses where its primary application area lives. */
+    setMainNavigator(navigate?: (surface: UiFrameSurface) => Promise<boolean>): void;
     private readonly actions;
     private focusSequence;
     private activityGeneration;
@@ -100,9 +103,10 @@ export declare class UiHost implements UiClient {
     private trimLedger;
     private peerResult;
     private action;
-    navigate: (entryKey: string, options: UiActionOptions) => Promise<UiActionResult>;
+    navigate: (entryKey: string, options: UiNavigationOptions) => Promise<UiActionResult>;
     openToolPicker: (options: UiActionOptions) => Promise<UiActionResult>;
     private pickTools;
+    private navigateMain;
     private navigateFrame;
     getPresentation: (id: string, options?: {
         signal?: AbortSignal;

package/dist/ui-host.js

@@ -1,6 +1,6 @@
 import { UiCompositionModel, validChromeOverrides, withChromeHints } from "./ui-composition.js";
 import { DEFAULT_WORKSPACE, ROOT_VIEW, workspace } from "./ui-workspaces.js";
-import { UI_COMPOSITION_CAPABILITY } from "./ui-types.js";
+import { UI_COMPOSITION_CAPABILITY, UI_MAIN_NAVIGATION_CAPABILITY, navigationSearch } from "./ui-types.js";
 import { createPresentationRequestId } from "./ui.js";
 import { UiError, panelKey, routeWithin } from "./ui-types.js";
 import { canonicalSurfaceRoute, DISCOVERY_TIMEOUT, failure, readUiMessage, uiPath, uiRequest, validId, validTarget, waitForPresentation } from "./ui-transport.js";
@@ -40,6 +40,9 @@ export class UiHost {
     composition;
     workspaces = new Map([[DEFAULT_WORKSPACE, workspace(DEFAULT_WORKSPACE)]]);
     placement;
+    mainNavigator;
+    /** The host chooses where its primary application area lives. */
+    setMainNavigator(navigate) { this.mainNavigator = navigate; }
     actions = new Map();
     focusSequence = 0;
     activityGeneration = 0;
@@ -628,7 +631,9 @@ export class UiHost {
         void operation.then(result => { entry.pending = undefined; entry.result = result; this.trimLedger(source); });
         return waitForPresentation(operation, id, options.signal);
     }
-    navigate = (entryKey, options) => this.action("navigate", entryKey, options, async (check) => {
+    navigate = (entryKey, options) => this.action("navigate", [entryKey, options.placement, options.search], options, async (check) => {
+        if (options.placement === "main")
+            throw new UiError("main_navigation_unavailable", "This document has no parent main surface.");
         const catalog = this.getNavigation().catalog, entry = catalog?.entries.find(e => e.key === entryKey);
         if (!entry || !entry.route)
             throw new UiError("destination_changed", "Refresh this app's navigation.");
@@ -666,6 +671,31 @@ export class UiHost {
             checkRenderer();
         }, frame);
     }
+    navigateMain(entryKey, search, options, frame) {
+        return this.action("navigate-main", [entryKey, search], options, async (check) => {
+            if (!navigationSearch(search))
+                throw new UiError("destination_invalid", "Invalid navigation query.");
+            const navigate = this.mainNavigator;
+            if (!navigate)
+                throw new UiError("main_navigation_unavailable", "This host has no main application surface.");
+            await this.bootstrap();
+            check();
+            const target = { appId: frame.surface.appId, installationId: frame.surface.installationId, entryKey };
+            const resolved = await uiRequest(this.path, "navigation/resolve", target);
+            check();
+            if (!resolved.available || !resolved.surface)
+                throw new UiError(resolved.state, "This page is unavailable.");
+            const destination = { ...resolved.surface };
+            if (search !== undefined) {
+                const url = new URL(destination.route, destination.origin);
+                url.search = search;
+                destination.route = url.pathname + url.search + url.hash;
+            }
+            if (!await this.mainNavigator?.(destination))
+                throw new UiError("destination_changed", "Refresh this app's navigation.");
+            check();
+        }, frame);
+    }
     navigateFrame(entryKey, options, frame) {
         return this.action("navigate", entryKey, options, async (check) => {
             await this.bootstrap();
@@ -951,7 +981,7 @@ export class UiHost {
             }
             this.post(frame, { type: "hosty:ui:connected", coreOrigin: own.coreOrigin, userId: own.userId,
                 appId: own.app.appId, installationId: own.app.installationId, code: frame.connected ? null : "actor_mismatch", route: frame.surface.route,
-                ...(frame.composition ? { capabilities: [UI_COMPOSITION_CAPABILITY], chrome: frame.chrome, revision: ++frame.policyRevision,
+                ...(frame.composition ? { capabilities: [UI_COMPOSITION_CAPABILITY, UI_MAIN_NAVIGATION_CAPABILITY], chrome: frame.chrome, revision: ++frame.policyRevision,
                     rootDisabled: !this.getChrome().tools.enabled, endpoint: frame.surface.endpoint } : {}) });
             if (frame.connected !== wasConnected)
                 frame.onConnection?.(frame.connected);
@@ -962,9 +992,11 @@ export class UiHost {
         if (!frame.connected)
             return;
         const source = `${frame.surface.appId}:${frame.generation}:${frame.nonce}`;
-        if (frame.composition && (msg.type === "hosty:ui:picker" || msg.type === "hosty:ui:navigate") && validId(msg.requestId)) {
+        if (frame.composition && (msg.type === "hosty:ui:picker" || msg.type === "hosty:ui:navigate" || msg.type === "hosty:ui:navigate-main") && validId(msg.requestId)) {
             const result = msg.type === "hosty:ui:picker" ? await this.pickTools({ requestId: msg.requestId }, frame)
-                : typeof msg.entryKey === "string" ? await this.navigateFrame(msg.entryKey, { requestId: msg.requestId }, frame)
+                : typeof msg.entryKey === "string" ? msg.type === "hosty:ui:navigate-main"
+                    ? await this.navigateMain(msg.entryKey, msg.search, { requestId: msg.requestId }, frame)
+                    : await this.navigateFrame(msg.entryKey, { requestId: msg.requestId }, frame)
                     : { status: "rejected", requestId: msg.requestId, code: "destination_invalid" };
             if (source === `${frame.surface.appId}:${frame.generation}:${frame.nonce}`)
                 this.post(frame, { type: "hosty:ui:action-result", requestId: msg.requestId, result });

package/dist/ui-types.d.ts

@@ -165,10 +165,17 @@ export type UiResolvedNavigation = {
     state: string;
     standaloneHref: string | null;
 };
+export declare const UI_MAIN_NAVIGATION_CAPABILITY = "ui.main-navigation.v1";
 export type UiActionOptions = {
     requestId: string;
     signal?: AbortSignal;
 };
+/** Main placement is explicit; only the resolved navigation entry's query can be overridden. */
+export type UiNavigationOptions = UiActionOptions & {
+    placement?: "main";
+    search?: string;
+};
+export declare function navigationSearch(value: unknown): value is string | undefined;
 export type UiActionResult = {
     status: "accepted";
     requestId: string;

package/dist/ui-types.js

@@ -42,3 +42,8 @@ export function buildSurfaceOpenUrl(coreOrigin, destination) {
     return url.href;
 }
 export const UI_COMPOSITION_CAPABILITY = "ui.composition.v1";
+export const UI_MAIN_NAVIGATION_CAPABILITY = "ui.main-navigation.v1";
+export function navigationSearch(value) {
+    return value === undefined || typeof value === "string" && value.length <= 4096
+        && (value === "" || value.startsWith("?")) && !/[#\u0000-\u001f\u007f]/.test(value);
+}

package/dist/ui.d.ts

@@ -1,4 +1,4 @@
-import type { UiChromeSnapshot, UiNavigationSnapshot, UiActionOptions, UiActionResult, PanelTarget, PresentationOptions, PresentationResult, UiEnvironment, UiEvent } from "@hosty-sdk/app/ui/types";
+import type { UiChromeSnapshot, UiNavigationSnapshot, UiActionOptions, UiNavigationOptions, UiActionResult, PanelTarget, PresentationOptions, PresentationResult, UiEnvironment, UiEvent } from "@hosty-sdk/app/ui/types";
 export * from "@hosty-sdk/app/ui/types";
 export interface UiClient {
     getEnvironment(): UiEnvironment;
@@ -6,7 +6,7 @@ export interface UiClient {
     subscribeChrome(listener: () => void): () => void;
     getNavigation(): UiNavigationSnapshot;
     subscribeNavigation(listener: () => void): () => void;
-    navigate(entryKey: string, options: UiActionOptions): Promise<UiActionResult>;
+    navigate(entryKey: string, options: UiNavigationOptions): Promise<UiActionResult>;
     openToolPicker(options: UiActionOptions): Promise<UiActionResult>;
     openSurface(target: PanelTarget, options: PresentationOptions): Promise<PresentationResult>;
     getPresentation(requestId: string, options?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -139,7 +139,7 @@
     "server-only": "^0.0.1"
   },
   "peerDependencies": {
-    "next": "^16.3.8",
+    "next": "^16.4.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8"
   },
@@ -155,10 +155,10 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24.19.1",
+    "@types/node": "^24.19.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "jsdom": "^30.1.1",
+    "jsdom": "^30.1.2",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "typescript": "^6",