akanjs 3.0.2 → 3.1.0-rc.0

package/types/vendor/@akanjs/native/plugins/external-view/src/index.d.ts

@@ -0,0 +1,132 @@
+import { type FileRef } from "../../../packages/core/src/index.ts";
+/**
+ * A third-party page shown first-party inside an app window, for signage: a scoreboard, a menu board. The view is a
+ * webview of its own laid over the window's page, which cannot draw over it — hide the view to show the page.
+ *
+ * Nothing of the app reaches the view: no bridge, no init script of the app, no app scheme. It keeps its own browser
+ * profile (cookies, storage, cache), so `clearData` never touches the app's, and it navigates only to `allowOrigins`;
+ * popups, downloads and device permissions are refused. Listing the plugin in `native.plugins` is what lets an app
+ * open one.
+ *
+ * Windows has every method. macOS (14 or later, for its separate profile) has all but `sendKey`, `setMuted` and
+ * `capture`, and sends no `loadFailed` or `consoleMessage`. Linux, iOS and Android: UNSUPPORTED.
+ */
+export type ExternalViewBounds = "fill" | {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type ExternalViewConsoleLevel = "debug" | "info" | "warn" | "error";
+export interface ExternalViewOpenOptions {
+    /** Names the view in every later call: letters, digits, `-` and `_`. */
+    id: string;
+    url: string;
+    /** The origins it may navigate to (`https://host[:port]`); `url` must be on one. */
+    allowOrigins: string[];
+    /** Logical pixels in the window's content area; "fill" (default) follows the window's size. */
+    bounds?: ExternalViewBounds;
+    /** Runs at the start of every top document, before the page's own scripts; read what it keeps with `evaluate`. */
+    initScript?: string;
+    muted?: boolean;
+    /** Media plays with sound without a gesture first (default true): nobody taps a signage screen. */
+    autoplay?: boolean;
+    /** Sends the page's console as `consoleMessage` from this level up (`true` is "warn"); off by default. */
+    console?: boolean | ExternalViewConsoleLevel;
+    /** The window it is laid over; the calling page's window by default. */
+    window?: number;
+}
+export interface ExternalViewState {
+    id: string;
+    window: number;
+    url: string;
+    visible: boolean;
+    /** Times its web process ended and the view loaded its page again. */
+    restarts: number;
+}
+export interface ExternalViewApi {
+    /** Opens the view, or brings an open one with this id to these options (a page that mounts again finds it). */
+    open(args: ExternalViewOpenOptions): Promise<ExternalViewState>;
+    /** Rejects NOT_ALLOWED for a URL on none of its `allowOrigins`. */
+    navigate(args: {
+        id: string;
+        url: string;
+    }): Promise<void>;
+    reload(args: {
+        id: string;
+    }): Promise<void>;
+    close(args: {
+        id: string;
+    }): Promise<void>;
+    list(): Promise<ExternalViewState[]>;
+    setVisible(args: {
+        id: string;
+        visible: boolean;
+    }): Promise<void>;
+    setBounds(args: {
+        id: string;
+        bounds: ExternalViewBounds;
+    }): Promise<void>;
+    /** The script's completion value; a promise is not awaited. An exception answers `null`: catch it in the script. */
+    evaluate(args: {
+        id: string;
+        script: string;
+    }): Promise<{
+        value: unknown;
+    }>;
+    /** A trusted key press (`{ key: "z", code: "KeyZ" }`), whether or not the view has the focus. Windows only. */
+    sendKey(args: {
+        id: string;
+        key: string;
+        code: string;
+    }): Promise<void>;
+    /** The view's own sound only; the system volume is the volume plugin's. Windows only. */
+    setMuted(args: {
+        id: string;
+        muted: boolean;
+    }): Promise<void>;
+    /** Clears the view's cookies, storage and cache; the app's own stay. */
+    clearData(args: {
+        id: string;
+    }): Promise<void>;
+    /** A PNG of the view's content, not of the screen. Windows only. */
+    capture(args: {
+        id: string;
+    }): Promise<FileRef & {
+        width?: number;
+        height?: number;
+    }>;
+}
+export interface ExternalViewEvents {
+    load: {
+        id: string;
+        state: "started" | "finished";
+        url: string;
+    };
+    /**
+     * A navigation that failed. `errorCode`: `http<status>` for a server's 4xx or 5xx page, else WebView2's own
+     * (`hostNameNotResolved`, `cannotConnect`, `timeout`, `certificate`, `disconnected`, …; a refused connection is
+     * `unknown`). Windows only.
+     */
+    loadFailed: {
+        id: string;
+        url: string;
+        errorCode: string;
+    };
+    /** Its web process ended; the view loads its page again by itself, sooner the first times. */
+    gone: {
+        id: string;
+        reason: string;
+        restarts: number;
+    };
+    /** `dropped`: messages left out before this one, past the rate cap. Windows only. */
+    consoleMessage: {
+        id: string;
+        level: ExternalViewConsoleLevel;
+        text: string;
+        url?: string;
+        line?: number;
+        dropped?: number;
+    };
+}
+export declare const externalView: import("../../../packages/core/src/plugin.ts").Plugin<ExternalViewApi, ExternalViewEvents>;

package/types/vendor/@akanjs/native/plugins/external-view/src.d.ts

@@ -0,0 +1 @@
+export * from "./src/index.d.ts";

package/types/vendor/@akanjs/native/plugins/updates/src/index.d.ts

@@ -63,6 +63,14 @@ export interface UpdatesApi {
      * releases; the running app stays, and a trial keeps its record.
      */
     reset(): Promise<void>;
+    /**
+     * Desktop: the manifest this app reads from now on, over the built `updates.channel` until set back with `null` —
+     * a server that moves this device between a pilot and a stable channel. A release older than the running one is
+     * never taken, so a device leaving a pilot channel stays on its pilot build until the other channel passes it.
+     */
+    setChannel(args: {
+        channel: string | null;
+    }): Promise<void>;
 }
 export interface UpdatesEvents {
     progress: UpdateProgress;

package/types/vendor/@akanjs/native/plugins/window/src/desktop.d.ts

@@ -1,6 +1,9 @@
 import { type DesktopContext } from "../../../packages/desktop/src/plugin.ts";
-import type { DragDropEvent, WindowApi, WindowEvents } from "./index.ts";
+import type { Display } from "../../screen/src/index.ts";
+import type { DragDropEvent, PlaceOnDisplayOptions, WindowApi, WindowEvents } from "./index.ts";
 /** Regular files among the dropped paths, served at /__akan_native/file/<id>; folders and unreadable paths are left out. */
 export declare function droppedFiles(ctx: Pick<DesktopContext, "registerFile">, paths: string[]): NonNullable<DragDropEvent["files"]>;
+export declare function displayOf(displays: Display[], args: PlaceOnDisplayOptions | undefined): Display;
+export declare function placement(display: Display, args: PlaceOnDisplayOptions | undefined): Record<string, unknown>;
 declare const _default: import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<WindowApi, WindowEvents>;
 export default _default;

package/types/vendor/@akanjs/native/plugins/window/src/index.d.ts

@@ -27,6 +27,26 @@ export interface CreateWindowOptions {
     /** Default: offset from the focused window, like new documents on macOS. */
     x?: number;
     y?: number;
+    /** No title bar or border, from the first frame: a kiosk drawn at an exact size. */
+    frameless?: boolean;
+}
+/** A display of `screen.getDisplays()` and where on it the window goes. */
+export interface PlaceOnDisplayOptions {
+    /** The display's `id`. */
+    display?: number;
+    /** Or its place in that list; 0 is the primary display. */
+    index?: number;
+    /** From the display's top-left corner, the window's frame; left out, the whole display. */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** "logical" (default): CSS px at that display's own scale. "physical": its device pixels, as a panel is specified. */
+    unit?: "logical" | "physical";
+    /** Borderless fullscreen on that display, in place of `bounds`. */
+    fullscreen?: boolean;
 }
 /** `window`: which window an op acts on. Default: the window of the page that calls. */
 type On = {
@@ -57,6 +77,30 @@ export interface WindowApi {
     setAlwaysOnTop(args: {
         value: boolean;
     } & On): Promise<WindowState>;
+    /** Shows or hides the title bar and border. */
+    setDecorations(args: {
+        value: boolean;
+    } & On): Promise<WindowState>;
+    /**
+     * Hides the pointer while it is over this window, as a kiosk screen does — over its external views too, on
+     * Windows; elsewhere on the desktop it still shows.
+     */
+    setCursorVisible(args: {
+        value: boolean;
+    } & On): Promise<WindowState>;
+    /**
+     * The smallest inner size, logical pixels; left out, none. The default is 320×240, which an LED board drawn at
+     * its device size (640×128 ÷ the display's `scale`) is below.
+     */
+    setMinSize(args: {
+        width?: number;
+        height?: number;
+    } & On): Promise<WindowState>;
+    /**
+     * Puts the window on one display, however the displays' scales differ. Bounds below the minimum size lower it to
+     * fit. NOT_FOUND for a display that is not connected.
+     */
+    placeOnDisplay(args: PlaceOnDisplayOptions & On): Promise<WindowState>;
     show(args?: On): Promise<WindowState>;
     hide(args?: On): Promise<WindowState>;
     focus(args?: On): Promise<WindowState>;
@@ -147,6 +191,11 @@ export interface WindowHandle {
     toggleMaximize(): Promise<WindowState>;
     setFullscreen(value: boolean): Promise<WindowState>;
     setAlwaysOnTop(value: boolean): Promise<WindowState>;
+    setDecorations(value: boolean): Promise<WindowState>;
+    setCursorVisible(value: boolean): Promise<WindowState>;
+    /** Left out: no minimum. */
+    setMinSize(width?: number, height?: number): Promise<WindowState>;
+    placeOnDisplay(options: PlaceOnDisplayOptions): Promise<WindowState>;
     show(): Promise<WindowState>;
     hide(): Promise<WindowState>;
     focus(): Promise<WindowState>;

package/types/vendor/use-agentic/types.d.ts

@@ -30,6 +30,8 @@ interface ToolEntryBase {
     settle?: boolean;
     confirm?: ToolConfirm;
     guard?: ToolGuard;
+    /** What a person reads for the action in the host's own UI, a command palette; never sent to the model. */
+    label?: () => string | undefined;
 }
 export interface ToolActionEntry extends ToolEntryBase {
     run: (args: Record<string, unknown>) => unknown;

package/types/webkit/CsrStack.d.ts

@@ -1,4 +1,4 @@
-import type { CsrNavigationPhase, CsrStackEntry, History, Location } from "akanjs/client";
+import { type CsrNavigationPhase, type CsrStackEntry, type History, type Location } from "akanjs/client";
 interface CsrStackState {
     history: History;
     location: Location;

package/types/webkit/McpAppAgent.d.ts

@@ -0,0 +1,14 @@
+import { type AgenticSurface } from "../vendor/use-agentic.d.ts";
+import { McpAppApprovals } from "./McpAppApprovals.d.ts";
+import type { McpAppBridge, McpAppTool, McpToolResultLike } from "./McpAppBridge.d.ts";
+export declare class McpAppAgent {
+    #private;
+    static readonly settleMs = 500;
+    static readonly contextLimit = 20000;
+    static readonly approvalMs = 25000;
+    constructor(bridge: McpAppBridge, surface?: AgenticSurface, approvals?: McpAppApprovals);
+    start(): void;
+    tools(): McpAppTool[];
+    call(name: string, args: Record<string, unknown>, signal: AbortSignal): Promise<McpToolResultLike>;
+    context(): string;
+}

package/types/webkit/McpAppApprovals.d.ts

@@ -0,0 +1,8 @@
+import type { PendingApproval, ToolApprovalRequest } from "../vendor/use-agentic.d.ts";
+export declare class McpAppApprovals {
+    #private;
+    static get shared(): McpAppApprovals;
+    subscribe: (listener: () => void) => () => void;
+    current: () => PendingApproval | null;
+    ask({ callId, name, args, message }: ToolApprovalRequest, signal: AbortSignal): Promise<true | string>;
+}

package/types/webkit/McpAppBridge.d.ts

@@ -0,0 +1,101 @@
+import { type FetchBridge } from "akanjs/fetch";
+export interface McpToolResultLike {
+    content?: {
+        type: string;
+        text?: string;
+    }[];
+    structuredContent?: unknown;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+}
+export interface McpAppTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+export interface McpAppToolServer {
+    list: () => McpAppTool[];
+    call: (name: string, args: Record<string, unknown>, signal: AbortSignal) => Promise<McpToolResultLike>;
+}
+export interface McpHostCapabilities {
+    openLinks?: object;
+    downloadFile?: object;
+    updateModelContext?: {
+        text?: object;
+    };
+    serverTools?: {
+        listChanged?: boolean;
+    };
+}
+export type McpDownloadContent = {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+} | {
+    type: "resource_link";
+    uri: string;
+    name: string;
+    mimeType?: string;
+};
+export interface McpHostContext {
+    theme?: "light" | "dark";
+    displayMode?: "inline" | "fullscreen" | "pip";
+    locale?: string;
+    timeZone?: string;
+    containerDimensions?: {
+        width?: number;
+        height?: number;
+        maxWidth?: number;
+        maxHeight?: number;
+    };
+    styles?: {
+        variables?: Record<string, string | undefined>;
+    };
+}
+interface McpAppSnapshotRecord {
+    key: string;
+    args: Record<string, unknown>;
+    value: unknown;
+}
+export type McpAppStart = {
+    ok: true;
+    href: string;
+    snapshot: McpAppSnapshotRecord[];
+    account: Record<string, unknown> | null;
+} | {
+    ok: false;
+    message: string;
+};
+export declare class McpAppBridge {
+    #private;
+    static readonly protocolVersion = "2026-01-26";
+    static readonly initializeTimeoutMs = 15000;
+    constructor();
+    get hostContext(): McpHostContext;
+    get hostCapabilities(): McpHostCapabilities;
+    /** Whether the host asked for the view's own tools, which is the only sign it offers them to its model. */
+    get toolsListed(): boolean;
+    connect(): Promise<McpAppStart>;
+    onHostContext(listener: (context: McpHostContext) => void): () => boolean;
+    request(method: string, params: Record<string, unknown>, { timeoutMs }?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    notify(method: string, params: Record<string, unknown>): void;
+    callTool(name: string, args: Record<string, unknown>): Promise<McpToolResultLike>;
+    openLink(url: string): Promise<void>;
+    downloadFile(contents: McpDownloadContent[]): Promise<void>;
+    updateModelContext(text: string): Promise<void>;
+    serveTools(server: McpAppToolServer): void;
+    toolsChanged(): void;
+    fetchBridge(snapshot: McpAppSnapshotRecord[]): FetchBridge;
+}
+export {};

package/types/webkit/McpAppView.d.ts

@@ -0,0 +1,21 @@
+import type { McpAppBridge } from "./McpAppBridge.d.ts";
+export declare class McpAppView {
+    #private;
+    static readonly contentGap = 24;
+    static readonly hostTokens: {
+        readonly "--color-background-primary": readonly ["--background", "--card", "--popover"];
+        readonly "--color-background-secondary": readonly ["--muted"];
+        readonly "--color-text-primary": readonly ["--foreground", "--card-foreground", "--popover-foreground"];
+        readonly "--color-text-secondary": readonly ["--muted-foreground"];
+        readonly "--color-border-primary": readonly ["--border", "--input"];
+        readonly "--color-ring-primary": readonly ["--ring"];
+        readonly "--font-sans": readonly ["--font-sans"];
+        readonly "--font-mono": readonly ["--font-mono"];
+    };
+    constructor(bridge: McpAppBridge);
+    /** `href` in the host's language when the app speaks it: the page run used the server's MCP language. */
+    static localize(href: string, locale: string | undefined, locales: readonly string[]): string;
+    mount(): void;
+    /** In place of the app, for a result that names no screen: the host still sizes the view to what it shows. */
+    showUnavailable(message: string): void;
+}

package/types/webkit/index.d.ts

@@ -19,3 +19,4 @@ export { usePageTool } from "./usePageTool.d.ts";
 export type { ScreenScopeItem } from "./useScreenScope.d.ts";
 export { useScreenScope } from "./useScreenScope.d.ts";
 export { useThrottle } from "./useThrottle.d.ts";
+export { useVisualViewportFrame, type VisualViewportFrame } from "./useVisualViewportFrame.d.ts";

package/types/webkit/useLocation.d.ts

@@ -1,4 +1,4 @@
-import type { Location, RouteGuide } from "akanjs/client";
+import { type Location, type RouteGuide } from "akanjs/client";
 interface UseLocationOptions {
     rootRouteGuide: RouteGuide;
 }

package/types/webkit/useVisualViewportFrame.d.ts

@@ -0,0 +1,13 @@
+export interface VisualViewportFrame {
+    /** The on-screen keyboard's height over the layout viewport's bottom; 0 while it is closed. */
+    keyboardHeight: number;
+    /** The visible rectangle's height and its scroll offset from the layout viewport's top, in CSS px. */
+    height: number;
+    offsetTop: number;
+}
+/**
+ * The visible part of the page while the on-screen keyboard is up, on the web. Only `visualViewport` reports the
+ * keyboard: `dvh` tracks the browser's own chrome, and iOS pans the visual viewport to the field instead of shrinking
+ * the page, so a fixed bottom bar stays behind the keyboard until it is placed at `offsetTop + height`.
+ */
+export declare const useVisualViewportFrame: () => VisualViewportFrame;

package/ui/Agent/Chat.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { cn, usePage } from "akanjs/client";
+import { cn, isMobileDevice, usePage } from "akanjs/client";
 import { AgentPrompts, type AgentVisualOption } from "akanjs/store";
 import {
   type KeyboardEvent as ReactKeyboardEvent,
@@ -41,7 +41,7 @@ import { type QueuedMessage, useChatQueue } from "./useChatQueue";
 import { useChatReferences } from "./useChatReferences";
 import { useChatVoice } from "./useChatVoice";
 import { useDraftRecall } from "./useDraftRecall";
-import { useKeyboardInset } from "./useKeyboardInset";
+import { useKeyboardFrame } from "./useKeyboardFrame";
 import { type ReferenceSource, useReferenceMenu } from "./useReferenceMenu";
 import { useSlashMenu } from "./useSlashMenu";
 import type { VoiceEngine } from "./voice";
@@ -79,6 +79,10 @@ export interface ChatProps {
   /** `false` leaves Cmd/Ctrl+L to the browser. */
   shortcut?: boolean;
   launcherClassName?: string;
+  /** The corner the launcher sits in; it clears the page's bottom chrome and safe area either way. */
+  launcherPlacement?: "right" | "left";
+  /** Draws no launcher below this breakpoint; the panel still opens from the shortcut or a controlled `open`. */
+  hideLauncherBelow?: "sm" | "md" | "lg";
   panelClassName?: string;
   /** Shown in place of the intro line while the transcript is empty. */
   intro?: ReactNode;
@@ -106,7 +110,13 @@ const isApplePlatform = () => {
   return /Mac|iPhone|iPad|iPod/i.test(data?.platform || navigator.platform || navigator.userAgent);
 };
 
-const launcherLayer = "fixed right-4 bottom-4 z-[150]";
+const launcherLayer =
+  "fixed bottom-[calc(var(--akan-bottom-inset,0px)+max(var(--akan-bottom-safe-area,0px),env(safe-area-inset-bottom,0px))+1rem)] z-[80]";
+const launcherSides = {
+  right: "right-[calc(env(safe-area-inset-right,0px)+1rem)]",
+  left: "left-[calc(env(safe-area-inset-left,0px)+1rem)]",
+} as const;
+const launcherHiddenBelow = { sm: "max-sm:hidden", md: "max-md:hidden", lg: "max-lg:hidden" } as const;
 
 const panelLayer = "fixed inset-0 z-[150] sm:inset-auto sm:right-4 sm:bottom-4";
 const panelSize =
@@ -132,6 +142,8 @@ export const DefaultChat = ({
   inline = false,
   shortcut = true,
   launcherClassName,
+  launcherPlacement = "right",
+  hideLauncherBelow,
   panelClassName,
   intro,
   header,
@@ -200,7 +212,7 @@ export const DefaultChat = ({
   const sticky = useRef(true);
   const returning = useRef(false);
   const read = useRef(session.messages.length);
-  const keyboardInset = useKeyboardInset();
+  const keyboardFrame = useKeyboardFrame();
   const [overlay, setOverlay] = useState<HTMLElement | null>(null);
   useEffect(() => {
     setOverlay(document.body);
@@ -210,7 +222,7 @@ export const DefaultChat = ({
     if (sticky.current) listRef.current?.scrollTo({ top: listRef.current.scrollHeight });
   }, [version, open]);
   useEffect(() => {
-    if (!shortcut) return;
+    if (!shortcut || globalThis.__AKAN_EMBED__) return;
     const apple = isApplePlatform();
     setHotkey(apple ? { label: "⌘ L", keys: "Meta+L" } : { label: "Ctrl+L", keys: "Control+L" });
     const onKeyDown = (event: KeyboardEvent) => {
@@ -232,7 +244,8 @@ export const DefaultChat = ({
       returning.current = false;
       return;
     }
-    focusComposer();
+    
+    if (!isMobileDevice()) focusComposer();
   }, [open, session.pendingQuestion?.callId]);
   useEffect(
     () => () => {
@@ -401,12 +414,19 @@ export const DefaultChat = ({
   
   const context = useMemo(() => session.context, [version]);
   const unread = open ? 0 : Math.max(0, session.messages.length - read.current);
-  const layer = (surface: ReactNode) => (inline ? surface : overlay ? createPortal(surface, overlay) : null);
+  
+  const layer = (surface: ReactNode) =>
+    globalThis.__AKAN_EMBED__ ? null : inline ? surface : overlay ? createPortal(surface, overlay) : null;
   if (!open)
     return launcher
       ? layer(
           <Launcher
-            className={cn(!inline && launcherLayer, className, launcherClassName)}
+            className={cn(
+              !inline && [launcherLayer, launcherSides[launcherPlacement]],
+              hideLauncherBelow && launcherHiddenBelow[hideLauncherBelow],
+              className,
+              launcherClassName,
+            )}
             hotkey={hotkey}
             label={l("base.agent")}
             buttonRef={launcherRef}
@@ -428,8 +448,7 @@ export const DefaultChat = ({
         panelClassName,
       )}
       role="dialog"
-      
-      style={inline ? undefined : { paddingBottom: keyboardInset || undefined }}
+      style={inline ? undefined : keyboardFrame}
       {...files.dropProps}
     >
       {chrome ? (

package/ui/Agent/Composer.tsx

@@ -72,7 +72,8 @@ export const DefaultComposer = ({
 }: ComposerProps) => {
   const { l } = usePage();
   const surface = useUiRecipe("input") ?? inputRecipe;
-  const field = surface({ kind: "area", size: "sm" }, "max-h-32 flex-1 resize-none py-1.5");
+  
+  const field = surface({ kind: "area", size: "sm" }, "max-h-32 flex-1 resize-none py-1.5 pointer-coarse:text-base");
   const placeholder = session.pendingQuestion
     ? l("base.agentAnswer")
     : session.isRunning

package/ui/Agent/EmbedApproval.tsx

@@ -0,0 +1,17 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { McpAppApprovals } from "../../webkit/McpAppApprovals";
+import Approval from "./Approval";
+
+export const EmbedApproval = () => {
+  const approvals = McpAppApprovals.shared;
+  const pending = useSyncExternalStore(approvals.subscribe, approvals.current, () => null);
+  if (!pending) return null;
+  return createPortal(
+    <div data-akan-embed-overlay="" className="fixed inset-x-0 bottom-0 z-[100] bg-background shadow-lg">
+      <Approval approval={pending} />
+    </div>,
+    document.body,
+  );
+};

package/ui/Agent/RichInput.tsx

@@ -135,7 +135,7 @@ export const RichInput = ({
         suppressContentEditableWarning
       />
       {draft ? null : (
-        <span className="pointer-events-none absolute inset-0 select-none px-3 py-1.5 text-foreground/40 text-sm">
+        <span className="pointer-events-none absolute inset-0 select-none px-3 py-1.5 pointer-coarse:text-base text-foreground/40 text-sm">
           {placeholder}
         </span>
       )}

package/ui/Agent/index.ts

@@ -4,6 +4,7 @@ import { Guide } from "./Guide";
 import { History } from "./History";
 import { Chat } from "./index_";
 import { Skip } from "./Skip";
+import { useScreenActions } from "./useScreenActions";
 import { Zone } from "./Zone";
 
 export const Agent = {
@@ -19,4 +20,5 @@ export const Agent = {
   Tool,
   Transcript,
   Zone,
+  useScreenActions,
 };

package/ui/Agent/useKeyboardFrame.ts

@@ -0,0 +1,10 @@
+"use client";
+import { useVisualViewportFrame } from "akanjs/webkit";
+import type { CSSProperties } from "react";
+
+export const useKeyboardFrame = (): CSSProperties | undefined => {
+  const { keyboardHeight, height, offsetTop } = useVisualViewportFrame();
+  if (!keyboardHeight) return undefined;
+  if (window.matchMedia("(width < 40rem)").matches) return { top: offsetTop, bottom: "auto", height };
+  return { paddingBottom: keyboardHeight };
+};

package/ui/Agent/useScreenActions.ts

@@ -0,0 +1,45 @@
+"use client";
+import { useEffect, useReducer } from "react";
+import { AgenticSurface } from "../../vendor/use-agentic";
+
+export interface ScreenAction {
+  name: string;
+  description?: string;
+  /** The tool's `label` (`st.tool(name, { label })`): what to show a person, in their language. */
+  label?: string;
+  /** A `remove*` tool, or one that declares `confirm`: ask the person before `run`. */
+  needsConfirm: boolean;
+  /** Runs the control's own handler, as its click does; refuses as the tool's guard does. */
+  run: () => Promise<void>;
+}
+
+/**
+ * The actions the current screen publishes that need no argument — what a command palette can offer, and exactly
+ * what the agent can do here. A person's pick is not recorded as an agent call.
+ */
+export const useScreenActions = ({ surface = AgenticSurface.shared }: { surface?: AgenticSurface } = {}) => {
+  const [, refresh] = useReducer((version: number) => version + 1, 0);
+  useEffect(() => surface.subscribe(refresh), [surface]);
+  return surface
+    .snapshot()
+    .tools.filter((tool) => {
+      const required = tool.parameters?.required;
+      return !Array.isArray(required) || required.length === 0;
+    })
+    .map((tool): ScreenAction => {
+      const label = surface.tool(tool.name)?.label?.();
+      return {
+        name: tool.name,
+        ...(tool.description ? { description: tool.description } : {}),
+        ...(label ? { label } : {}),
+        needsConfirm: tool.needsConfirm,
+        run: async () => {
+          const entry = surface.tool(tool.name);
+          if (!entry || !("run" in entry) || !entry.run) return;
+          const verdict = entry.guard?.({}) ?? true;
+          if (verdict !== true) throw new Error(verdict);
+          await entry.run({});
+        },
+      };
+    });
+};