@fungi.computer/agar 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -4,8 +4,8 @@ export { createCapabilityRegistry, defineCapability } from "./capabilities.js";
 export { pending, pendingSchema } from "./pending.js";
 export type { Pending } from "./pending.js";
 export type { CapabilityContract, CapabilityDirectory, CapabilityRegistry, } from "./capabilities.js";
-export { agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, createAppAgent, renameAppAgent, appAgentCreateInputSchema, appAgentRenameInputSchema, appAgentSchema, appAgentToolPolicyResultSchema, appAgentToolPolicyStatusSchema, listAppAgents, openAppAgent, } from "./agents.js";
-export type { AppAgent, AppAgentCreateHandle, AppAgentCreateInput, AppAgentDirectoryHandle, AppAgentListHandle, AppAgentRenameHandle, AppAgentRenameInput, AppAgentToolPolicyHandle, AppAgentToolPolicyResult, AppAgentToolPolicyStatus, AppAgentTransport, AppAgentTransportHandle, } from "./agents.js";
+export { agentAvatar, agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, createAppAgent, renameAppAgent, setAppAgentAvatar, appAgentAvatarInputSchema, appAgentAvatarSchema, appAgentCreateInputSchema, appAgentRenameInputSchema, appAgentSchema, appAgentToolPolicyResultSchema, appAgentToolPolicyStatusSchema, listAppAgents, openAppAgent, } from "./agents.js";
+export type { AppAgent, AppAgentAvatarHandle, AppAgentAvatarInput, AppAgentCreateHandle, AppAgentCreateInput, AppAgentDirectoryHandle, AppAgentListHandle, AppAgentRenameHandle, AppAgentRenameInput, AppAgentToolPolicyHandle, AppAgentToolPolicyResult, AppAgentToolPolicyStatus, AppAgentTransport, AppAgentTransportHandle, } from "./agents.js";
 export { mediaGeneration, mediaGenerationFailureSchema, mediaGenerationReferenceSchema, mediaGenerationSelectionSchema, mediaModelSchema, openMediaGeneration, } from "./media.js";
 export type { MediaGenerationHandle, MediaGenerationAttempt, MediaGenerationAttemptHandle, MediaGenerationFailure, MediaGenerationInput, MediaGenerationOutcome, MediaGenerationReference, MediaGenerationResult, MediaGenerationSelection, MediaModel, MediaOutputFormat, MediaGenerationSession, } from "./media.js";
 export type { AppCommand, AppCommandHandler, AppCommandInvocation, AppCommands, } from "./commands.js";
@@ -25,7 +25,8 @@ export type { AppRoot } from "./root.js";
 export type { AgentSessionSelection } from "./ui.js";
 export type { Disposer, ReadonlyStore } from "./store.js";
 export type { AppBrowserAction, AppBrowserActionOutcome, AppBrowserActionRefusal, AgentAccessOperation, AppPermissionOutcome, AppPermissionRequest, AppStatusAction, AppStatusActionHandler, AppStatusIcon, AppStatusItem, AppStatusOption, AppStatusTone, ComputerAccessOperation, FileNavigationInput, HostUi, ToastInput, } from "./ui.js";
-export { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_TITLE_MAX, inertHostNavigation, } from "./window.js";
-export type { AppBackHandler, AppNavigationState, AppWindow, BeforeAppClose, HostNavigation, } from "./window.js";
+export { resultRowSchemaV1, type ResultRow } from "@fungi.computer/gills";
+export { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_CRUMBS_MAX, APP_NAVIGATION_LABEL_MAX, APP_NAVIGATION_MENU_MAX, APP_NAVIGATION_PRIMARY_MAX, APP_NAVIGATION_SIBLINGS_MAX, APP_NAVIGATION_STATUS_MAX, APP_NAVIGATION_TITLE_MAX, inertHostNavigation, navigationActivationAllowed, } from "./window.js";
+export type { AppBackHandler, AppCrumb, AppHeaderCommand, AppHeaderStatus, AppNavigationActivation, AppNavigationActivationHandler, AppNavigationState, AppWindow, BeforeAppClose, HostNavigation, } from "./window.js";
 export { appStorage, AppStorageError } from "./storage.js";
 export type { AppStorage, AppStorageWatch, AppStorageWrite, AppStorageReset, ResolvedAppStorage, } from "./storage.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { FungiAuthorSchema, FungiDelegationReplySchema, FungiMessageMetaSchema, messageAuthor, messageDelegationReply, authorMeta, } from "./agent-message-meta.js";
 export { createCapabilityRegistry, defineCapability } from "./capabilities.js";
 export { pending, pendingSchema } from "./pending.js";
-export { agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, createAppAgent, renameAppAgent, appAgentCreateInputSchema, appAgentRenameInputSchema, appAgentSchema, appAgentToolPolicyResultSchema, appAgentToolPolicyStatusSchema, listAppAgents, openAppAgent, } from "./agents.js";
+export { agentAvatar, agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, createAppAgent, renameAppAgent, setAppAgentAvatar, appAgentAvatarInputSchema, appAgentAvatarSchema, appAgentCreateInputSchema, appAgentRenameInputSchema, appAgentSchema, appAgentToolPolicyResultSchema, appAgentToolPolicyStatusSchema, listAppAgents, openAppAgent, } from "./agents.js";
 export { mediaGeneration, mediaGenerationFailureSchema, mediaGenerationReferenceSchema, mediaGenerationSelectionSchema, mediaModelSchema, openMediaGeneration, } from "./media.js";
 export { registerCatalog } from "./commands.js";
 export { connectApp } from "./connect.js";
@@ -11,5 +11,6 @@ export { AppError } from "./errors.js";
 export { statusActionAllowed, statusText } from "./status.js";
 export { APP_BROWSER_SAVE_MAX_BYTES, APP_BROWSER_COPY_MAX_BYTES, APP_STATUS_ITEMS_MAX, APP_STATUS_OPTIONS_MAX, APP_STATUS_TEXT_MAX, } from "./ui.js";
 export { parseStatusAction as parseAppStatusAction, parseStatusItems as parseAppStatusItems, } from "./internal/schemas.js";
-export { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_TITLE_MAX, inertHostNavigation, } from "./window.js";
+export { resultRowSchemaV1 } from "@fungi.computer/gills";
+export { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_CRUMBS_MAX, APP_NAVIGATION_LABEL_MAX, APP_NAVIGATION_MENU_MAX, APP_NAVIGATION_PRIMARY_MAX, APP_NAVIGATION_SIBLINGS_MAX, APP_NAVIGATION_STATUS_MAX, APP_NAVIGATION_TITLE_MAX, inertHostNavigation, navigationActivationAllowed, } from "./window.js";
 export { appStorage, AppStorageError } from "./storage.js";

package/dist/inference.js

@@ -1,9 +1,10 @@
 import { defineCapability } from "./capabilities.js";
 import { rpcFetchHandleSchema, rpcHandleSchema, rpcMethod, } from "./internal/rpc-contract.js";
+import * as z from "zod";
 import * as Schema from "effect/Schema";
 import { AppError } from "./errors.js";
 import { reportCatchFailure } from "./failure.js";
-export const llmGeneration = defineCapability("llm.generation", 1, rpcHandleSchema({ open: rpcMethod(rpcFetchHandleSchema) }));
+export const llmGeneration = defineCapability("llm.generation", 1, z.lazy(() => rpcHandleSchema({ open: rpcMethod(rpcFetchHandleSchema) })));
 const baseURL = "https://inference.fungi.invalid/v1";
 const decodeResponse = Schema.decodeUnknownSync(Schema.instanceOf(Response));
 /** OpenAI-compatible transport; no Agent, Session, host URL or credentials are exposed. */

package/dist/internal/app-session.js

@@ -5,6 +5,7 @@ import * as Schema from "effect/Schema";
  */
 import { newMessagePortRpcSession, RpcStub, RpcTarget, } from "@fungi.computer/capnweb";
 import { statusActionAllowed } from "../status.js";
+import { navigationActivationAllowed } from "../window.js";
 import { AppError } from "../errors.js";
 import { reportCatchFailure } from "../failure.js";
 import { createLocalBindingState, createReservedChordState, installBrowserBridge, } from "./browser-bridge.js";
@@ -13,7 +14,7 @@ import { createCapabilityDirectory, disposeRpcValue, } from "./capabilities.js";
 import { createAppCommands } from "./commands.js";
 import { APP_PROTOCOL_VERSION, } from "./protocol.js";
 import { callRpc, rpcFailure, rpcSuccess, unwrapRpcResult } from "./result.js";
-import { parseBrowserAction, parseBrowserActionOutcomeResult, parseBootstrapResult, parseHostReconfiguration, parseContext, parseErrorData, parseFact, parseAgentSessionSelection, parseIdentity, parseLifecycle, parseNavigation, parseStatusAction, parseStatusItems, parseNavigationStateInput, parsePermissionOutcomeResult, parsePermissionRequest, parseReservedChords, parseTheme, parseToast, parseVoidResult, } from "./schemas.js";
+import { parseBrowserAction, parseBrowserActionOutcomeResult, parseBootstrapResult, parseHostReconfiguration, parseContext, parseErrorData, parseFact, parseAgentSessionSelection, parseIdentity, parseLifecycle, parseNavigation, parseNavigationActivation, parseNavigationState, parseStatusAction, parseStatusItems, parseNavigationStateInput, parsePermissionOutcomeResult, parsePermissionRequest, parseReservedChords, parseTheme, parseToast, parseVoidResult, } from "./schemas.js";
 const rpcStubSchema = Schema.declare((value) => value instanceof RpcStub);
 import { createReadonlyStore } from "./store.js";
 class AppClientTarget extends RpcTarget {
@@ -57,6 +58,21 @@ class AppClientTarget extends RpcTarget {
             return rpcFailure(cause);
         }
     }
+    async activateNavigation(value) {
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            const activation = parseNavigationActivation(value);
+            // A shell's stale copy can still send a crumb or command the App has
+            // since dropped; only what it published now reaches the App.
+            if (!navigationActivationAllowed(this.#state.navigation, activation))
+                return rpcSuccess(false);
+            return rpcSuccess(await (this.#state.activate?.(activation) ?? false));
+        }
+        catch (cause) {
+            return rpcFailure(cause);
+        }
+    }
     async activateStatus(value) {
         try {
             if (this.#disposed)
@@ -231,6 +247,7 @@ function createBrokenPromise(remote) {
 function createClientState() {
     return {
         statusItems: [],
+        navigation: { canGoBack: false },
         bindings: createLocalBindingState(),
         chords: createReservedChordState([]),
         context: createReadonlyStore({
@@ -293,6 +310,7 @@ function createRootRuntime(options, identity, capabilities) {
             () => {
                 options.state.beforeClose = undefined;
                 options.state.back = undefined;
+                options.state.activate = undefined;
                 options.state.statusAction = undefined;
             },
             () => {
@@ -370,8 +388,26 @@ function createAppWindow(state, remote, assertConnected) {
             assertConnected();
             const wire = parseNavigationStateInput(input);
             state.canGoBack = wire.canGoBack;
+            state.navigation = parseNavigationState(wire);
             await callRpc(remote.reportNavigation(wire), parseVoidResult);
         },
+        onActivate(handler) {
+            assertConnected();
+            if (state.activate !== undefined)
+                throw new AppError("The App already owns navigation activations", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            state.activate = handler;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                if (state.activate === handler)
+                    state.activate = undefined;
+            };
+        },
         onBack(handler) {
             assertConnected();
             if (state.back !== undefined)

package/dist/internal/protocol.d.ts

@@ -2,7 +2,7 @@ import type { AppCommand } from "../commands.js";
 import type { WhistleExecutionOrigin, WhistleJsonValue } from "@fungi.computer/whistle";
 import type { AppContext, AppIdentity, AppLifecycle, FocusState } from "../lifecycle.js";
 import type { AppBrowserAction, AppBrowserActionOutcome, AgentSessionSelection, AppPermissionOutcome, AppPermissionRequest, AppStatusAction, AppStatusItem, FileNavigationInput, ToastInput } from "../ui.js";
-import type { APP_NAVIGATION_CONTRACT_VERSION } from "../window.js";
+import type { APP_NAVIGATION_CONTRACT_VERSION, AppNavigationActivation, AppNavigationState } from "../window.js";
 import type { AppErrorData } from "./app-error.js";
 import type { RpcResult } from "./result.js";
 import type { WhistleFailure } from "@fungi.computer/whistle";
@@ -17,6 +17,8 @@ export type AppClientRpc = {
     requestClose(): Promise<RpcResult<boolean>>;
     /** Ask the App to go back one step in its own history; `true` when it did. */
     requestBack(): Promise<RpcResult<boolean>>;
+    /** The person used a crumb or header command; `true` when the App acted. */
+    activateNavigation(activation: AppNavigationActivation): Promise<RpcResult<boolean>>;
     /** The person used one of the App's status items; `true` when it acted. */
     activateStatus(action: AppStatusAction): Promise<RpcResult<boolean>>;
     updateContext(context: VersionedFact<AppContext>): Promise<RpcResult<void>>;
@@ -51,9 +53,7 @@ export type AppHostRpc = {
 /** The versioned navigation contract an App reports to its host. */
 export type NavigationStateWire = Readonly<{
     contractVersion: typeof APP_NAVIGATION_CONTRACT_VERSION;
-    canGoBack: boolean;
-    title?: string;
-}>;
+}> & AppNavigationState;
 /** The App iframe's handshake message announcing it is ready to connect. */
 export type AppReadyMessage = {
     readonly protocolVersion: typeof APP_PROTOCOL_VERSION;

package/dist/internal/schemas.d.ts

@@ -8,9 +8,9 @@ import type { WhistleJsonValue } from "@fungi.computer/whistle";
 import type { AppContext, AppIdentity, AppLifecycle, FocusState } from "../lifecycle.js";
 import type { AppBrowserAction, AppBrowserActionRefusal, AppBrowserActionOutcome, AppPermissionOutcome, AppStatusItem, FileNavigationInput, ToastInput } from "../ui.js";
 import type { AppErrorData } from "./app-error.js";
-import type { CapabilityGrantWire, AppHostReconfigurationWire, CommandInvocationResultWire, HostBootstrapWire, RegisteredCommandWire } from "./protocol.js";
+import type { CapabilityGrantWire, AppHostReconfigurationWire, CommandInvocationResultWire, HostBootstrapWire, NavigationStateWire, RegisteredCommandWire } from "./protocol.js";
 import type { RpcResult } from "./result.js";
-import { APP_NAVIGATION_CONTRACT_VERSION } from "../window.js";
+import { type AppNavigationActivation } from "../window.js";
 import { type AppConnectMessage, type AppReadyMessage, type CommandInvocationWire, type ConnectRequestWire, type ReservedChord, type VersionedFact } from "./protocol.js";
 export declare function appInvocation(value: CommandInvocationWire, signal: AbortSignal): Readonly<AppCommandInvocation>;
 export declare const parseCommand: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
@@ -38,6 +38,7 @@ export declare const parseCommand: (input: unknown, options?: import("effect/Sch
         } | undefined;
         readonly slash?: {
             readonly aliases: readonly string[];
+            readonly consumesDraft?: boolean | undefined;
             readonly order?: number | undefined;
             readonly arguments?: {
                 readonly hint: string;
@@ -263,13 +264,38 @@ export declare const parseNavigation: (input: unknown, options?: import("effect/
 export declare const parseNavigationState: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
     canGoBack: boolean;
     title?: string;
+    crumbs?: readonly Readonly<{
+        id: string;
+        label: string;
+        siblings?: readonly Readonly<{
+            id: string;
+            label: string;
+        }>[];
+    }>[];
+    primary?: readonly Readonly<{
+        id: string;
+        label: string;
+        variant?: "primary" | "outline" | "ghost";
+        tone?: "destructive";
+        disabled?: boolean;
+    }>[];
+    menu?: readonly Readonly<{
+        id: string;
+        label: string;
+        variant?: "primary" | "outline" | "ghost";
+        tone?: "destructive";
+        disabled?: boolean;
+    }>[];
+    status?: readonly Readonly<{
+        id: string;
+        label: string;
+        tone?: "neutral" | "info" | "warning" | "success" | "error";
+    }>[];
 }>;
 /** App edge: trim the title, drop an empty one, then check the wire bounds. */
-export declare const parseNavigationStateInput: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
-    contractVersion: typeof APP_NAVIGATION_CONTRACT_VERSION;
-    canGoBack: boolean;
-    title?: string;
-}>;
+export declare const parseNavigationStateInput: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => NavigationStateWire;
+/** Host to App: one crumb or command the person used. */
+export declare const parseNavigationActivation: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => AppNavigationActivation;
 export declare const parseAgentSessionSelection: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
     agentId: string;
     sessionId: string;

package/dist/internal/schemas.js

@@ -9,7 +9,7 @@ import { flow } from "effect/Function";
 import { parseCommandDefinition, parseJsonValue, } from "@fungi.computer/whistle/wire";
 import { isUnsafeStatusCodeUnit } from "../status.js";
 import { APP_BROWSER_SAVE_MAX_BYTES, APP_BROWSER_COPY_MAX_BYTES, APP_STATUS_ITEMS_MAX, APP_STATUS_OPTIONS_MAX, APP_STATUS_TEXT_MAX, } from "../ui.js";
-import { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_TITLE_MAX, } from "../window.js";
+import { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_CRUMBS_MAX, APP_NAVIGATION_LABEL_MAX, APP_NAVIGATION_MENU_MAX, APP_NAVIGATION_PRIMARY_MAX, APP_NAVIGATION_SIBLINGS_MAX, APP_NAVIGATION_STATUS_MAX, APP_NAVIGATION_TITLE_MAX, } from "../window.js";
 import { AppError } from "../errors.js";
 import { parseFailure } from "@fungi.computer/whistle/wire";
 import { APP_CONNECT_TYPE, APP_PROTOCOL_VERSION, APP_READY_TYPE, } from "./protocol.js";
@@ -175,15 +175,62 @@ const navigationSchema = Schema.Struct({
 const navigationTitleSchema = boundedText(APP_NAVIGATION_TITLE_MAX).pipe(Schema.check(Schema.makeFilter((title) => title.trim() === title, {
     message: "Expected a trimmed title",
 })));
+const navigationIdSchema = boundedText(64);
+const navigationLabelSchema = boundedText(APP_NAVIGATION_LABEL_MAX);
+/** Ids name what a person used; repeats would make an activation ambiguous. */
+const uniqueIds = (items) => new Set(items.map((item) => item.id)).size === items.length;
+const crumbSchema = Schema.Struct({
+    id: navigationIdSchema,
+    label: navigationLabelSchema,
+    siblings: Schema.optional(Schema.Array(Schema.Struct({ id: navigationIdSchema, label: navigationLabelSchema })).pipe(Schema.check(Schema.isMaxLength(APP_NAVIGATION_SIBLINGS_MAX)), Schema.check(Schema.makeFilter(uniqueIds, {
+        message: "Expected unique crumb sibling ids",
+    })))),
+});
+const headerCommandSchema = Schema.Struct({
+    id: navigationIdSchema,
+    label: navigationLabelSchema,
+    variant: Schema.optional(Schema.Literals(["primary", "outline", "ghost"])),
+    tone: Schema.optional(Schema.Literal("destructive")),
+    disabled: Schema.optional(Schema.Boolean),
+});
+const commandsSchema = (maximum) => Schema.Array(headerCommandSchema).pipe(Schema.check(Schema.isMaxLength(maximum)), Schema.check(Schema.makeFilter(uniqueIds, {
+    message: "Expected unique header command ids",
+})));
+const headerStatusSchema = Schema.Struct({
+    id: navigationIdSchema,
+    label: navigationLabelSchema,
+    tone: Schema.optional(Schema.Literals(["neutral", "info", "warning", "success", "error"])),
+});
+const navigationFields = {
+    status: Schema.optional(Schema.Array(headerStatusSchema).pipe(Schema.check(Schema.isMaxLength(APP_NAVIGATION_STATUS_MAX)), Schema.check(Schema.makeFilter(uniqueIds, {
+        message: "Expected unique header status ids",
+    })))),
+    crumbs: Schema.optional(Schema.Array(crumbSchema).pipe(Schema.check(Schema.isMaxLength(APP_NAVIGATION_CRUMBS_MAX)), Schema.check(Schema.makeFilter(uniqueIds, { message: "Expected unique crumb ids" })))),
+    primary: Schema.optional(commandsSchema(APP_NAVIGATION_PRIMARY_MAX)),
+    menu: Schema.optional(commandsSchema(APP_NAVIGATION_MENU_MAX)),
+};
 const navigationStateWireSchema = Schema.Struct({
     contractVersion: Schema.Literal(APP_NAVIGATION_CONTRACT_VERSION),
     canGoBack: Schema.Boolean,
     title: Schema.optional(navigationTitleSchema),
+    ...navigationFields,
 });
 const navigationStateInputSchema = Schema.Struct({
     canGoBack: Schema.Boolean,
     title: Schema.optional(Schema.String),
+    ...navigationFields,
 });
+const navigationActivationSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("crumb"),
+        crumbId: navigationIdSchema,
+        siblingId: Schema.optional(navigationIdSchema),
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("action"),
+        actionId: navigationIdSchema,
+    }),
+]);
 const agentSessionSelectionSchema = Schema.NullOr(Schema.Struct({
     agentId: boundedText(256),
     sessionId: boundedText(256),
@@ -339,25 +386,69 @@ export const parseStatusAction = decoder(Schema.Struct({
     ? { ...action }
     : { ...action, anchor: frozen({ ...action.anchor }) }), "INVALID_ARGUMENT");
 export const parseNavigation = decoder(navigationSchema, (value) => frozen({ ...value }), "INVALID_ARGUMENT");
+function statusOf(item) {
+    const copy = { id: item.id, label: item.label };
+    return frozen(item.tone === undefined ? copy : { ...copy, tone: item.tone });
+}
+function crumbOf(crumb) {
+    const copy = { id: crumb.id, label: crumb.label };
+    if (crumb.siblings === undefined)
+        return frozen(copy);
+    return frozen({
+        ...copy,
+        siblings: frozen(crumb.siblings.map((item) => frozen({ ...item }))),
+    });
+}
+function commandOf(command) {
+    let copy = { id: command.id, label: command.label };
+    if (command.variant !== undefined)
+        copy = { ...copy, variant: command.variant };
+    if (command.tone !== undefined)
+        copy = { ...copy, tone: command.tone };
+    if (command.disabled !== undefined)
+        copy = { ...copy, disabled: command.disabled };
+    return frozen(copy);
+}
+/** One report's fields, each present only when the App sent it. */
+function navigationOf(value) {
+    let state = { canGoBack: value.canGoBack };
+    if (value.title !== undefined)
+        state = { ...state, title: value.title };
+    if (value.crumbs !== undefined)
+        state = { ...state, crumbs: frozen(value.crumbs.map(crumbOf)) };
+    if (value.primary !== undefined)
+        state = { ...state, primary: frozen(value.primary.map(commandOf)) };
+    if (value.menu !== undefined)
+        state = { ...state, menu: frozen(value.menu.map(commandOf)) };
+    if (value.status !== undefined)
+        state = { ...state, status: frozen(value.status.map(statusOf)) };
+    return frozen(state);
+}
 /** Host edge: one App report, projected without its contract version. */
-export const parseNavigationState = decoder(navigationStateWireSchema, (value) => frozen(value.title === undefined
-    ? { canGoBack: value.canGoBack }
-    : { canGoBack: value.canGoBack, title: value.title }), "INVALID_ARGUMENT");
+export const parseNavigationState = decoder(navigationStateWireSchema, navigationOf, "INVALID_ARGUMENT");
 /** App edge: trim the title, drop an empty one, then check the wire bounds. */
 export const parseNavigationStateInput = decoder(navigationStateInputSchema, (value) => {
-    const title = value.title?.trim();
-    return parseNavigationStateWire(title === undefined || title.length === 0
-        ? {
-            contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
-            canGoBack: value.canGoBack,
-        }
-        : {
-            contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
-            canGoBack: value.canGoBack,
-            title,
-        });
+    const trimmed = value.title?.trim();
+    return parseNavigationStateWire({
+        ...navigationOf({
+            ...value,
+            title: trimmed === undefined || trimmed.length === 0 ? undefined : trimmed,
+        }),
+        contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
+    });
+}, "INVALID_ARGUMENT");
+const parseNavigationStateWire = decoder(navigationStateWireSchema, (value) => frozen({
+    ...navigationOf(value),
+    contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
+}), "INVALID_ARGUMENT");
+/** Host to App: one crumb or command the person used. */
+export const parseNavigationActivation = decoder(navigationActivationSchema, (value) => {
+    if (value.kind === "action")
+        return frozen({ ...value });
+    return frozen(value.siblingId === undefined
+        ? { kind: value.kind, crumbId: value.crumbId }
+        : value);
 }, "INVALID_ARGUMENT");
-const parseNavigationStateWire = decoder(navigationStateWireSchema, (value) => frozen({ ...value }), "INVALID_ARGUMENT");
 export const parseAgentSessionSelection = decoder(agentSessionSelectionSchema, (value) => value === null ? null : frozen({ ...value }), "INVALID_ARGUMENT");
 export const parsePermissionRequest = decoder(permissionRequestSchema, (value) => frozen({
     agents: frozen([...new Set(value.agents ?? [])]),

package/dist/marketplace.js

@@ -72,19 +72,21 @@ export const marketplaceAcquisitionSchema = Schema.Union([
     }),
 ]);
 /** Read the Marketplace gallery as the Team that mounted this App. */
-export const marketplaceBrowse = defineCapability("marketplace.browse", 1, rpcHandleSchema({
-    list: rpcMethod(rpcDataSchema(z.unknown().transform((value) => decodeMarketplaceBrowseResult(value)))),
-}));
+export const marketplaceBrowse = defineCapability("marketplace.browse", 1, z.lazy(() => rpcHandleSchema({
+    list: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => decodeMarketplaceBrowseResult(value)))),
+})));
 /**
  * Acquire a listing for the mounting Team. Free listings install at once;
  * paid listings return a hosted Checkout URL and install after payment.
  * The host re-checks Team authority and entitlement on every call.
  */
-export const marketplacePurchase = defineCapability("marketplace.purchase", 1, rpcHandleSchema({
+export const marketplacePurchase = defineCapability("marketplace.purchase", 1, z.lazy(() => rpcHandleSchema({
     acquire: rpcMethod(rpcDataSchema(z
         .unknown()
         .transform((value) => Schema.decodeUnknownSync(marketplaceAcquisitionSchema)(value)))),
-}));
+})));
 /** Anonymous discovery only; acquisition and launch still require Team admission. */
 export async function browsePublicMarketplace(hubOrigin, category, request = fetch) {
     const url = new URL("/api/public/marketplace/listings", hubOrigin);

package/dist/media-request-id.d.ts

@@ -4,4 +4,4 @@ export declare const mediaRequestIds: Readonly<{
     readonly request: import("@fungi.computer/cairn/id").IdCodec<"hub-media-request", "request", 1>;
 }>;
 /** Public wire grammar for the canonical retry identity, visible in App JSON schemas. */
-export declare const mediaRequestIdSchema: z.ZodString;
+export declare const mediaRequestIdSchema: z.ZodLazy<z.ZodString>;

package/dist/media-request-id.js

@@ -10,7 +10,7 @@ export const mediaRequestIds = defineIdFamily({
     },
 });
 /** Public wire grammar for the canonical retry identity, visible in App JSON schemas. */
-export const mediaRequestIdSchema = z
+export const mediaRequestIdSchema = z.lazy(() => z
     .string()
     .length(35)
-    .regex(/^media_request_[a-z0-9]{21}$/);
+    .regex(/^media_request_[a-z0-9]{21}$/));

package/dist/media.js

@@ -327,7 +327,7 @@ const mediaAttemptHandleSchema = rpcHandleSchema({
 /** Capability contract for generating Media (images or video). Apps
  * declare it to request access; openMediaGeneration uses it to obtain
  * the host's handle. */
-export const mediaGeneration = defineCapability("media.generation", 5, rpcHandleSchema({
+export const mediaGeneration = defineCapability("media.generation", 5, z.lazy(() => rpcHandleSchema({
     describe: rpcMethod(rpcDataSchema(z.unknown().transform((value) => {
         const { computerId, canGenerate, models } = Schema.decodeUnknownSync(descriptionSchema, {
             onExcessProperty: "error",
@@ -337,7 +337,7 @@ export const mediaGeneration = defineCapability("media.generation", 5, rpcHandle
     createAttempt: rpcMethod(mediaAttemptHandleSchema),
     restoreAttempt: rpcMethod(mediaAttemptHandleSchema),
     cancelAttempt: rpcVoid,
-}));
+})));
 /** Parse a value received from the host and turn schema failures into the
  * transport-safe Agar error used by the other capability helpers. */
 function decode(schema, value) {

package/dist/method-presentation.d.ts

@@ -0,0 +1,7 @@
+import type { ResultRowCodec } from "./backend-definition.js";
+/**
+ * The shared result row's decoder and JSON boundary, for
+ * `defineAppMethod({ present: { verb, row, rows: resultRows } })`. Only
+ * backends that present import this module, so the rest carry no decoder.
+ */
+export declare const resultRows: ResultRowCodec;

package/dist/method-presentation.js

@@ -0,0 +1,14 @@
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { resultRowSchemaV1 } from "@fungi.computer/gills";
+/**
+ * The shared result row's decoder and JSON boundary, for
+ * `defineAppMethod({ present: { verb, row, rows: resultRows } })`. Only
+ * backends that present import this module, so the rest carry no decoder.
+ */
+export const resultRows = Object.freeze({
+    decode: Schema.decodeUnknownSync(resultRowSchemaV1, {
+        onExcessProperty: "error",
+    }),
+    schema: z.fromJSONSchema(Schema.toJsonSchemaDocument(resultRowSchemaV1).schema),
+});

package/dist/method-refusal.d.ts

@@ -29,7 +29,7 @@ export declare class AppMethodRefusal extends Error {
     constructor(code: AppMethodRefusalCode, message: string);
 }
 /** A refused call as it crosses the generated method boundary. */
-export declare const appMethodRefusedReplySchema: z.ZodObject<{
+export declare const appMethodRefusedReplySchema: z.ZodLazy<z.ZodObject<{
     kind: z.ZodLiteral<"refused">;
     code: z.ZodEnum<{
         unavailable: "unavailable";
@@ -39,14 +39,14 @@ export declare const appMethodRefusedReplySchema: z.ZodObject<{
         not_found: "not_found";
     }>;
     message: z.ZodString;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** A decoded {@link appMethodRefusedReplySchema} value. */
 export type AppMethodRefusedReply = z.output<typeof appMethodRefusedReplySchema>;
 /** Every generated App method RPC answers with exactly one of these. */
-export declare const appMethodReplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const appMethodReplySchema: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"ok">;
     value: z.ZodJSONSchema;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>, z.ZodLazy<z.ZodObject<{
     kind: z.ZodLiteral<"refused">;
     code: z.ZodEnum<{
         unavailable: "unavailable";
@@ -56,7 +56,7 @@ export declare const appMethodReplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         not_found: "not_found";
     }>;
     message: z.ZodString;
-}, z.core.$strict>], "kind">;
+}, z.core.$strict>>], "kind">>;
 /** A decoded {@link appMethodReplySchema} value; the result is read-only JSON. */
 export type AppMethodReply = Readonly<{
     kind: "ok";

package/dist/method-refusal.js

@@ -36,13 +36,13 @@ export class AppMethodRefusal extends Error {
     }
 }
 /** A refused call as it crosses the generated method boundary. */
-export const appMethodRefusedReplySchema = z.strictObject({
+export const appMethodRefusedReplySchema = z.lazy(() => z.strictObject({
     kind: z.literal("refused"),
     code: z.enum(appMethodRefusalCodes),
     message: z.string().min(1).max(maxAppMethodRefusalMessage),
-});
+}));
 /** Every generated App method RPC answers with exactly one of these. */
-export const appMethodReplySchema = z.discriminatedUnion("kind", [
+export const appMethodReplySchema = z.lazy(() => z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("ok"), value: z.json() }),
     appMethodRefusedReplySchema,
-]);
+]));

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { type WhistleContribution, type WhistleRuntime } from "@fungi.computer/whistle";
-import type { AppBackHandler, HostNavigation } from "./window.js";
+import type { AppBackHandler, AppCrumb, AppHeaderCommand, AppHeaderStatus, HostNavigation } from "./window.js";
 import type { AppContext } from "./lifecycle.js";
 import type { AppStatusActionHandler, AppStatusItem } from "./ui.js";
 import type { AppRoot } from "./root.js";
@@ -31,11 +31,23 @@ export type HostNavigationOptions = Readonly<{
     canGoBack: boolean;
     /** The current page's title, shown after the App name in window chrome. */
     title?: string | undefined;
+    /** The App's path, shown in the window header in place of the title. */
+    crumbs?: readonly AppCrumb[] | undefined;
+    /** The view's main commands, as header buttons. */
+    primary?: readonly AppHeaderCommand[] | undefined;
+    /** Less common commands, behind the header's overflow menu. */
+    menu?: readonly AppHeaderCommand[] | undefined;
+    /** Facts about the view, shown as muted text with a status bead. */
+    status?: readonly AppHeaderStatus[] | undefined;
     onBack: AppBackHandler;
+    /** The person chose a crumb, or a sibling from a switcher crumb. */
+    onCrumb?: ((crumbId: string, siblingId?: string) => void) | undefined;
+    /** The person used a primary or menu command. */
+    onAction?: ((actionId: string) => void) | undefined;
 }>;
 /**
  * Publish an App's navigation state to its host and own the host's Back
  * requests while mounted. Pass `app?.window.navigation`; with no connected
  * App it does nothing. Unmounting withdraws Back from the host chrome.
  */
-export declare function useHostNavigation(navigation: HostNavigation | null | undefined, { canGoBack, title, onBack }: HostNavigationOptions): void;
+export declare function useHostNavigation(navigation: HostNavigation | null | undefined, { canGoBack, title, crumbs, primary, menu, status, onBack, onCrumb, onAction, }: HostNavigationOptions): void;

package/dist/react.js

@@ -80,26 +80,62 @@ export function useAppCommandCatalog(app, { sourceId, namespace }, build) {
  * requests while mounted. Pass `app?.window.navigation`; with no connected
  * App it does nothing. Unmounting withdraws Back from the host chrome.
  */
-export function useHostNavigation(navigation, { canGoBack, title, onBack }) {
+export function useHostNavigation(navigation, { canGoBack, title, crumbs, primary, menu, status, onBack, onCrumb, onAction, }) {
     const latestBack = useRef(onBack);
+    const latestCrumb = useRef(onCrumb);
+    const latestAction = useRef(onAction);
     useEffect(() => {
         latestBack.current = onBack;
-    }, [onBack]);
+        latestCrumb.current = onCrumb;
+        latestAction.current = onAction;
+    }, [onBack, onCrumb, onAction]);
     useEffect(() => {
         if (!navigation)
             return undefined;
         const release = navigation.onBack(() => latestBack.current());
+        const releaseActivation = navigation.onActivate((activation) => {
+            if (activation.kind === "action") {
+                const handler = latestAction.current;
+                handler?.(activation.actionId);
+                return handler !== undefined;
+            }
+            const handler = latestCrumb.current;
+            if (activation.siblingId === undefined)
+                handler?.(activation.crumbId);
+            else
+                handler?.(activation.crumbId, activation.siblingId);
+            return handler !== undefined;
+        });
         return () => {
             release();
+            releaseActivation();
             report(navigation, { canGoBack: false });
         };
     }, [navigation]);
+    // Callers pass fresh arrays each render; the report follows their content.
+    const lists = JSON.stringify([crumbs, primary, menu, status]);
+    const latestLists = useRef({ crumbs, primary, menu, status });
+    useEffect(() => {
+        latestLists.current = { crumbs, primary, menu, status };
+    }, [crumbs, primary, menu, status]);
     // Each change replaces the last report; only unmount withdraws Back.
     useEffect(() => {
         if (!navigation)
             return;
-        report(navigation, title === undefined ? { canGoBack } : { canGoBack, title });
-    }, [navigation, canGoBack, title]);
+        let state = { canGoBack };
+        if (title !== undefined)
+            state = { ...state, title };
+        const current = latestLists.current;
+        if (current.crumbs !== undefined)
+            state = { ...state, crumbs: current.crumbs };
+        if (current.primary !== undefined)
+            state = { ...state, primary: current.primary };
+        if (current.menu !== undefined)
+            state = { ...state, menu: current.menu };
+        if (current.status !== undefined)
+            state = { ...state, status: current.status };
+        report(navigation, state);
+    }, [navigation, canGoBack, title, lists]);
 }
 function report(navigation, state) {
     navigation.publish(state).catch((cause) => {