@ggui-ai/protocol 0.1.0-rc.1

package/dist/integrations/mcp-apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-apps.d.ts","sourceRoot":"","sources":["../../src/integrations/mcp-apps.ts"],"names":[],"mappings":"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"}

package/dist/integrations/mcp-apps.js

@@ -0,0 +1,427 @@
+/**
+ * MCP Apps integration — outbound delivery types for ggui.
+ *
+ * This module is the **boundary** for MCP Apps outbound delivery. Anything
+ * MCP-Apps-specific that ggui exposes to the rest of the codebase lives
+ * here — never in `types/live-channel.ts`, `types/mcp.ts`, `types/session.ts`,
+ * or any other core module. Consumers opt in via the subpath import:
+ *
+ * ```ts
+ * import {
+ *   MCP_APPS_UI_CAPABILITY,
+ *   GGUI_SESSION_RESOURCE_URI,
+ *   type GguiBootstrapMeta,
+ * } from '@ggui-ai/protocol/integrations/mcp-apps';
+ * ```
+ *
+ * The root `@ggui-ai/protocol` barrel does NOT re-export this module.
+ * That's the isolation rule: core protocol consumers that don't integrate
+ * with MCP Apps pay none of its weight, and the blast radius of any spec
+ * drift is bounded to callers that explicitly import from here.
+ *
+ * Core still carries two fields that make the bootstrap flow work —
+ * `SubscribePayload.bootstrap?: string` and `AckPayload.sessionToken?:
+ * string`. Those are deliberately framed as **general transport bootstrap
+ * credentials** (opaque strings), not MCP-Apps-specific. Any future
+ * bootstrap mechanism (short-code auto-login, signed-URL bootstrap, etc.)
+ * reuses the same slots.
+ */
+/**
+ * MCP capability name ggui servers advertise in their MCP `initialize`
+ * response capabilities when they implement the MCP Apps outbound path.
+ * Spec-canonical; MUST match the string the MCP Apps protocol publishes.
+ */
+export const MCP_APPS_UI_CAPABILITY = 'io.modelcontextprotocol/ui';
+/**
+ * The single MCP Apps resource URI ggui exposes for outbound delivery.
+ * `ggui_push` is the sole tool declaration that carries this in its
+ * `_meta.ui.resourceUri`. No other ggui tool gets a resource URI —
+ * `ggui_push` is the single outbound entry point.
+ */
+export const GGUI_SESSION_RESOURCE_URI = 'ui://ggui/session';
+/**
+ * MIME type for the `ui://ggui/session` resource. Per MCP Apps spec, UI
+ * resources carry the `text/html` base type with a `profile=mcp-app`
+ * parameter so hosts that don't support MCP Apps don't accidentally
+ * render them as plain HTML.
+ */
+export const GGUI_SESSION_RESOURCE_MIME = 'text/html;profile=mcp-app';
+/**
+ * The single `_meta.ui.resourceUri` value ggui uses across every MCP Apps
+ * host surface. Exposed as a named constant so tool-declaration code,
+ * resource-serving code, and tests all agree on one spelling.
+ */
+export const GGUI_PUSH_UI_META = {
+    /** Resource URI hosts fetch via `resources/read` on a `ggui_push` tool call. */
+    resourceUri: GGUI_SESSION_RESOURCE_URI,
+    /** Only `"model"` — outer agent can call, iframe views cannot. */
+    visibility: ['model'],
+};
+/**
+ * Derives the PascalCase Context name from a contextSpec slot key.
+ * E.g., `currentStep` → `CurrentStepContext`. Consumed by the server
+ * (when populating bootstrap.contextSlots) and the iframe-runtime
+ * boilerplate (when generating destructuring lines).
+ *
+ * Edge cases:
+ *   - Empty input → `'Context'` (caller-fault path; documented for
+ *     determinism).
+ *   - Single-character input → `<UPPER>Context` (e.g. `'a'` → `'AContext'`).
+ *
+ * @public
+ */
+export function deriveContextName(slotKey) {
+    if (slotKey.length === 0)
+        return 'Context';
+    return slotKey.charAt(0).toUpperCase() + slotKey.slice(1) + 'Context';
+}
+/**
+ * Type guard: narrows a `SessionStackEntry` (or unknown) to
+ * {@link McpAppsStackItem}. Uses the discriminator.
+ */
+export function isMcpAppsStackItem(entry) {
+    return (entry !== null &&
+        typeof entry === 'object' &&
+        entry.type === 'mcpApps');
+}
+/**
+ * Structural validator for an `McpAppsStackItem` — not a Zod schema
+ * so we don't force a Zod dependency here. Returns null on failure
+ * (caller maps to an appropriate error code). Required when accepting
+ * one over the wire from an agent: the discriminator alone isn't
+ * enough.
+ */
+export function validateMcpAppsStackItem(input) {
+    if (input === null || typeof input !== 'object')
+        return null;
+    const item = input;
+    if (item.type !== 'mcpApps')
+        return null;
+    if (typeof item.id !== 'string' || item.id.length === 0)
+        return null;
+    if (typeof item.createdAt !== 'string')
+        return null;
+    const source = item.source;
+    if (!source || typeof source !== 'object')
+        return null;
+    if (typeof source.connectorId !== 'string' || source.connectorId.length === 0)
+        return null;
+    if (typeof source.toolName !== 'string' || source.toolName.length === 0)
+        return null;
+    if (typeof source.resourceUri !== 'string' || !source.resourceUri.startsWith('ui://'))
+        return null;
+    return input;
+}
+/**
+ * The closed set of valid lifecycle states. Exposed as a `readonly`
+ * tuple so consumers (renderer host filters, conformance tests) can
+ * iterate without re-typing the union literally.
+ *
+ * @public
+ */
+export const MCP_APP_LIFECYCLE_STATES = [
+    'mounting',
+    'code-ready',
+    'error',
+    'disconnected',
+];
+/**
+ * Type guard for {@link McpAppLifecycleMessage}. Trust-boundary helper
+ * — apps consuming raw postMessage data MUST narrow before reading
+ * `event.state` to avoid reaching into untyped property bags.
+ *
+ * Validation rules (all required for `true`):
+ *   - Outer envelope is an object with `type === 'ggui:lifecycle'`.
+ *   - `event` is an object with `state` matching {@link
+ *     MCP_APP_LIFECYCLE_STATES}.
+ *   - If `stackItemId` is present, it is a non-empty string.
+ *   - If `error` is present, it is an object with string `code` +
+ *     `message`.
+ *
+ * @public
+ */
+export function isMcpAppLifecycleMessage(message) {
+    if (message === null || typeof message !== 'object')
+        return false;
+    const m = message;
+    if (m.type !== 'ggui:lifecycle')
+        return false;
+    if (m.event === null || typeof m.event !== 'object')
+        return false;
+    const e = m.event;
+    if (typeof e.state !== 'string')
+        return false;
+    if (!MCP_APP_LIFECYCLE_STATES.includes(e.state)) {
+        return false;
+    }
+    if (e.stackItemId !== undefined) {
+        if (typeof e.stackItemId !== 'string' || e.stackItemId.length === 0) {
+            return false;
+        }
+    }
+    if (e.error !== undefined) {
+        if (e.error === null || typeof e.error !== 'object')
+            return false;
+        const err = e.error;
+        if (typeof err.code !== 'string' || typeof err.message !== 'string') {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Type guard for recognizing a `ggui_push` result `_meta` that carries a
+ * bootstrap block. Handy for views / tests that receive the raw result.
+ *
+ * Validates the three-mode discriminator: a well-formed bootstrap MUST
+ * carry `runtimeUrl` + `sessionId` + `appId` AND at least one of
+ * `{wsUrl, codeUrl, kind}` as a non-empty string. Live mode
+ * additionally requires `token` to pair with `wsUrl` — half-live
+ * (one without the other) is rejected as MALFORMED.
+ */
+export function hasPushBootstrapMeta(meta) {
+    if (meta === null || typeof meta !== 'object')
+        return false;
+    const ggui = meta.ggui;
+    if (ggui === null || typeof ggui !== 'object')
+        return false;
+    const bootstrap = ggui.bootstrap;
+    if (bootstrap === null || typeof bootstrap !== 'object')
+        return false;
+    const b = bootstrap;
+    // Required-everywhere fields.
+    if (!(typeof b.sessionId === 'string' &&
+        b.sessionId.length > 0 &&
+        typeof b.appId === 'string' &&
+        b.appId.length > 0 &&
+        typeof b.runtimeUrl === 'string' &&
+        b.runtimeUrl.length > 0)) {
+        return false;
+    }
+    // Mode discriminator — at least one of {wsUrl, codeUrl, kind} MUST
+    // be a non-empty string. Live mode requires `token` paired with
+    // `wsUrl`; half-live is MALFORMED. `codeUrl` is the static-component
+    // delivery channel (content-addressable URL the runtime fetches the
+    // compiled ES module from). System-card mode (`kind`) is mutually
+    // exclusive with `codeUrl`.
+    const hasWsUrl = typeof b.wsUrl === 'string' && b.wsUrl.length > 0;
+    const hasToken = typeof b.token === 'string' && b.token.length > 0;
+    const hasCodeUrl = typeof b.codeUrl === 'string' && b.codeUrl.length > 0;
+    const hasKind = typeof b.kind === 'string' && b.kind.length > 0;
+    if (hasWsUrl !== hasToken)
+        return false;
+    if (!hasWsUrl && !hasCodeUrl && !hasKind)
+        return false;
+    if (hasKind && hasCodeUrl)
+        return false;
+    // expiresAt is now optional (live-mode-only). When present, must be
+    // a string; type-only check, semantic validation lives in the
+    // iframe-runtime parser which has clock access.
+    if (b.expiresAt !== undefined && typeof b.expiresAt !== 'string') {
+        return false;
+    }
+    // themeMode (when present) must be one of the closed set.
+    if (b.themeMode !== undefined &&
+        b.themeMode !== 'light' &&
+        b.themeMode !== 'dark') {
+        return false;
+    }
+    // themeId / propsJson (when present) must be strings.
+    if (b.themeId !== undefined && typeof b.themeId !== 'string')
+        return false;
+    if (b.propsJson !== undefined && typeof b.propsJson !== 'string')
+        return false;
+    if (b.appCallableTools !== undefined) {
+        if (!Array.isArray(b.appCallableTools))
+            return false;
+        if (!b.appCallableTools.every((s) => typeof s === 'string'))
+            return false;
+    }
+    if (b.actionNextSteps !== undefined) {
+        if (b.actionNextSteps === null ||
+            typeof b.actionNextSteps !== 'object' ||
+            Array.isArray(b.actionNextSteps)) {
+            return false;
+        }
+        for (const value of Object.values(b.actionNextSteps)) {
+            if (typeof value !== 'string')
+                return false;
+        }
+    }
+    // `contextSlots` is OPTIONAL on the wire. Each entry MUST carry
+    // non-empty `name`, non-empty `contextName`, a `schema` object, AND
+    // a `default` value (JsonValue, can be null — the runtime owns
+    // useState per slot and the Provider seed is load-bearing).
+    // Optional `debounceMs` MUST be a number when present.
+    if (b.contextSlots !== undefined) {
+        if (!Array.isArray(b.contextSlots))
+            return false;
+        for (const entry of b.contextSlots) {
+            if (entry === null || typeof entry !== 'object')
+                return false;
+            const e = entry;
+            if (typeof e.name !== 'string' || e.name.length === 0)
+                return false;
+            if (typeof e.contextName !== 'string' || e.contextName.length === 0) {
+                return false;
+            }
+            if (e.schema === null || typeof e.schema !== 'object' || Array.isArray(e.schema)) {
+                return false;
+            }
+            // `default` MUST be present (key exists). The value MAY be null
+            // — that's a legitimate JsonValue. Discriminate via `in` so a
+            // literal `null` passes while truly-missing fails.
+            if (!('default' in e))
+                return false;
+            if (e.debounceMs !== undefined && typeof e.debounceMs !== 'number') {
+                return false;
+            }
+        }
+    }
+    // `permissionsPolicy` is OPTIONAL on the wire. When present, MUST be
+    // an array of non-empty strings (the browser Permissions API names
+    // declared on `DataContract.clientCapabilities.gadgets[*].permission`).
+    if (b.permissionsPolicy !== undefined) {
+        if (!Array.isArray(b.permissionsPolicy))
+            return false;
+        for (const value of b.permissionsPolicy) {
+            if (typeof value !== 'string' || value.length === 0)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * The three canonical gesture kinds — useful for exhaustiveness checks
+ * in `switch (kind) { ... }` blocks. Frozen so consumers can safely use
+ * `as const` against the readonly tuple.
+ */
+export const SUBMIT_ACTION_KINDS = [
+    'dispatch',
+    'openLink',
+    'requestDisplayMode',
+];
+/**
+ * Type guard narrowing an unknown value to {@link GguiSubmitActionInput}.
+ * Validates the `kind` discriminator + the per-kind `payload` shape.
+ * Used by the server-side `ggui_runtime_submit_action` handler to reject
+ * malformed envelopes with `INVALID_ACTION_KIND` instead of silently
+ * coercing.
+ *
+ * Unknown extension kinds are accepted at this guard layer (the
+ * `(string & {})` slot is part of the type) but the per-kind payload
+ * narrowing collapses to `Record<string, unknown>` — extension-handlers
+ * MUST validate shape before consuming.
+ */
+export function isGguiSubmitActionInput(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (typeof v.kind !== 'string' || v.kind.length === 0)
+        return false;
+    if (typeof v.sessionId !== 'string' || v.sessionId.length === 0)
+        return false;
+    if (typeof v.appId !== 'string' || v.appId.length === 0)
+        return false;
+    if (typeof v.actionId !== 'string' || v.actionId.length === 0)
+        return false;
+    if (typeof v.firedAt !== 'string' || v.firedAt.length === 0)
+        return false;
+    if (v.stackItemId !== undefined &&
+        (typeof v.stackItemId !== 'string' || v.stackItemId.length === 0)) {
+        return false;
+    }
+    if (v.payload === null || typeof v.payload !== 'object')
+        return false;
+    // Per-kind payload narrowing for the closed primary set. Unknown
+    // kinds pass through with whatever payload-object the caller supplied
+    // — extension handlers own the validation.
+    const p = v.payload;
+    switch (v.kind) {
+        case 'dispatch':
+            if (typeof p.intent !== 'string' || p.intent.length === 0)
+                return false;
+            // `actionData` MUST be present (key exists). The value MAY be
+            // `null` — bare button clicks legitimately have no payload.
+            // Discriminate via `in` so an explicit `null` passes while
+            // truly-missing fails.
+            if (!('actionData' in p))
+                return false;
+            // `uiContext` MUST be a JSON object — `{}` when there's no
+            // contextSpec. Arrays and null are rejected.
+            if (p.uiContext === null || typeof p.uiContext !== 'object')
+                return false;
+            if (Array.isArray(p.uiContext))
+                return false;
+            return true;
+        case 'openLink':
+            return typeof p.url === 'string' && p.url.length > 0;
+        case 'requestDisplayMode':
+            return typeof p.mode === 'string' && p.mode.length > 0;
+        default:
+            // Extension slot — payload-object presence is the only invariant.
+            return true;
+    }
+}
+/**
+ * Type guard for {@link GguiUserActionMeta}. Validates the
+ * discriminated shape on a `ui/message` envelope's
+ * `params._meta.ggui.userAction` field.
+ *
+ * Designed for `_meta.ggui.userAction`-aware consumers (sample agent
+ * dispatcher, e2e assertions, future SDKs) to route deterministically
+ * without speculative shape coercion.
+ *
+ * @public
+ */
+export function isGguiUserActionMeta(meta) {
+    if (meta === null || typeof meta !== 'object')
+        return false;
+    const m = meta;
+    if (typeof m.description !== 'string' || m.description.length === 0) {
+        return false;
+    }
+    if (typeof m.stackItemId !== 'string' || m.stackItemId.length === 0) {
+        return false;
+    }
+    if (typeof m.actionId !== 'string' || m.actionId.length === 0) {
+        return false;
+    }
+    if (typeof m.submittedAt !== 'string' || m.submittedAt.length === 0) {
+        return false;
+    }
+    if (typeof m.intent !== 'string' || m.intent.length === 0)
+        return false;
+    if (m.kind === 'queued') {
+        if (m.nextStep === null || typeof m.nextStep !== 'object')
+            return false;
+        const ns = m.nextStep;
+        if (ns.tool !== 'ggui_consume')
+            return false;
+        if (ns.args === null || typeof ns.args !== 'object')
+            return false;
+        const args = ns.args;
+        if (typeof args.stackItemId !== 'string' ||
+            args.stackItemId.length === 0) {
+            return false;
+        }
+        return true;
+    }
+    if (m.kind === 'inline') {
+        if (m.payload === null || typeof m.payload !== 'object')
+            return false;
+        const p = m.payload;
+        if (p.actionData === undefined)
+            return false; // explicit null OK
+        if (p.uiContext === null || typeof p.uiContext !== 'object')
+            return false;
+        if (Array.isArray(p.uiContext))
+            return false;
+        if (m.nextStep !== undefined &&
+            (typeof m.nextStep !== 'string' || m.nextStep.length === 0)) {
+            return false;
+        }
+        return true;
+    }
+    return false;
+}

package/dist/navigation/index.d.ts

@@ -0,0 +1,3 @@
+export { stackNavigationReducer, initialNavigationState, } from './stack-navigation';
+export type { StackNavigationAction, StackNavigationState, } from './stack-navigation';
+//# sourceMappingURL=index.d.ts.map

package/dist/navigation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/navigation/index.js

@@ -0,0 +1 @@
+export { stackNavigationReducer, initialNavigationState, } from './stack-navigation.js';

package/dist/navigation/stack-navigation.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Stack Navigation — pure reducer for navigating ggui stack items.
+ *
+ * Framework-agnostic state machine. Used by both @ggui-ai/react and
+ * @ggui-ai/react-native hooks.
+ */
+/**
+ * Actions that can be dispatched to the {@link stackNavigationReducer}.
+ *
+ * - `GO_TO_INDEX` -- Navigate to a specific stack index (clamped to valid range)
+ * - `GO_HOME` -- Navigate to the first item (index 0)
+ * - `GO_BACK` -- Navigate one item backward (no-op if already at index 0)
+ * - `GO_FORWARD` -- Navigate one item forward (no-op if already at the latest)
+ * - `STACK_UPDATED` -- Notify the reducer that the stack length changed (push/pop)
+ * - `TOGGLE_OVERVIEW` -- Toggle the stack overview panel open/closed
+ * - `CLOSE_OVERVIEW` -- Close the stack overview panel
+ */
+export type StackNavigationAction = {
+    type: 'GO_TO_INDEX';
+    index: number;
+} | {
+    type: 'GO_HOME';
+} | {
+    type: 'GO_BACK';
+} | {
+    type: 'GO_FORWARD';
+} | {
+    type: 'STACK_UPDATED';
+    stackLength: number;
+} | {
+    type: 'TOGGLE_OVERVIEW';
+} | {
+    type: 'CLOSE_OVERVIEW';
+};
+export interface StackNavigationState {
+    /** Currently viewed stack index */
+    currentIndex: number;
+    /** Whether the stack overview panel is open */
+    overviewOpen: boolean;
+    /**
+     * When true, the navigator auto-follows new pushes (jumps to latest item).
+     * Disabled when the user manually navigates away from the latest item.
+     */
+    autoFollow: boolean;
+}
+export declare const initialNavigationState: StackNavigationState;
+/**
+ * Pure reducer for stack navigation state.
+ *
+ * @param state   Current navigation state
+ * @param action  Navigation action to dispatch
+ * @param stackLength  Current number of items in the stack
+ */
+export declare function stackNavigationReducer(state: StackNavigationState, action: StackNavigationAction, stackLength: number): StackNavigationState;
+//# sourceMappingURL=stack-navigation.d.ts.map

package/dist/navigation/stack-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-navigation.d.ts","sourceRoot":"","sources":["../../src/navigation/stack-navigation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAM/B,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,YAAY,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,sBAAsB,EAAE,oBAIpC,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,EAC3B,MAAM,EAAE,qBAAqB,EAC7B,WAAW,EAAE,MAAM,GAClB,oBAAoB,CAgEtB"}

package/dist/navigation/stack-navigation.js

@@ -0,0 +1,80 @@
+/**
+ * Stack Navigation — pure reducer for navigating ggui stack items.
+ *
+ * Framework-agnostic state machine. Used by both @ggui-ai/react and
+ * @ggui-ai/react-native hooks.
+ */
+export const initialNavigationState = {
+    currentIndex: 0,
+    overviewOpen: false,
+    autoFollow: true,
+};
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+/**
+ * Pure reducer for stack navigation state.
+ *
+ * @param state   Current navigation state
+ * @param action  Navigation action to dispatch
+ * @param stackLength  Current number of items in the stack
+ */
+export function stackNavigationReducer(state, action, stackLength) {
+    const maxIndex = Math.max(0, stackLength - 1);
+    switch (action.type) {
+        case 'GO_TO_INDEX': {
+            const clamped = Math.max(0, Math.min(action.index, maxIndex));
+            return {
+                ...state,
+                currentIndex: clamped,
+                overviewOpen: false,
+                // Disable auto-follow if user navigated away from latest
+                autoFollow: clamped === maxIndex,
+            };
+        }
+        case 'GO_HOME':
+            return {
+                ...state,
+                currentIndex: 0,
+                overviewOpen: false,
+                autoFollow: maxIndex === 0,
+            };
+        case 'GO_BACK':
+            if (state.currentIndex <= 0)
+                return state;
+            return {
+                ...state,
+                currentIndex: state.currentIndex - 1,
+                autoFollow: false,
+            };
+        case 'GO_FORWARD':
+            if (state.currentIndex >= maxIndex)
+                return state;
+            return {
+                ...state,
+                currentIndex: state.currentIndex + 1,
+                autoFollow: state.currentIndex + 1 === maxIndex,
+            };
+        case 'STACK_UPDATED': {
+            const newMax = Math.max(0, action.stackLength - 1);
+            // If auto-follow is on, jump to the latest item
+            if (state.autoFollow) {
+                return {
+                    ...state,
+                    currentIndex: newMax,
+                };
+            }
+            // Otherwise, clamp to valid range (handles pops)
+            return {
+                ...state,
+                currentIndex: Math.min(state.currentIndex, newMax),
+            };
+        }
+        case 'TOGGLE_OVERVIEW':
+            return { ...state, overviewOpen: !state.overviewOpen };
+        case 'CLOSE_OVERVIEW':
+            return { ...state, overviewOpen: false };
+        default:
+            return state;
+    }
+}

package/dist/recommended-prompts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Recommended agent-side system prompts for hosts running ggui.
+ *
+ * The wire protocol already carries its own self-teaching surfaces:
+ *
+ *   - Per-tool `description` strings on every `ggui_*` MCP tool.
+ *   - The server's `InitializeResult.instructions` field (set via
+ *     `@ggui-ai/mcp-server`'s `MCP_INSTRUCTIONS_PRESETS`).
+ *
+ * Those two carry the wire flow (new_session → handshake → push →
+ * consume → react), the contract-authoring rules, recovery shapes,
+ * and the mutation rule. **Agent builders should NOT replicate any
+ * of that in their system prompt.** The protocol is designed to be
+ * self-teaching from the host's side.
+ *
+ * What an agent-side system prompt SHOULD do: set the agent's role
+ * and posture — "you render UIs, you don't reply in plain text" —
+ * so the model reaches for ggui_* tools instead of conversational
+ * responses. That's a *posture cue*, not a procedural script.
+ *
+ * On hosts like claude.ai, the host's own baseline system prompt
+ * already nudges tool usage, so a one-line user instruction
+ * ("Always respond using ggui_* tools") is enough. On raw SDK hosts
+ * (Claude Agent SDK, OpenAI Assistants, etc.) that baseline is
+ * absent, so the recommended prompt below carries slightly more
+ * role context to compensate.
+ *
+ * If an agent isn't following the wire flow correctly even with
+ * this prompt, the bug lives in the protocol's tool descriptions
+ * or server instructions — fix THOSE, not this string.
+ */
+/**
+ * The recommended one-line system prompt for ggui-aware agents.
+ *
+ * Posture-setting only. Carries no procedural detail — the wire flow
+ * is taught by the server's `InitializeResult.instructions` and
+ * per-tool `description` strings.
+ *
+ * @example
+ * ```ts
+ * import { query } from '@anthropic-ai/claude-agent-sdk';
+ * import { GGUI_AGENT_SYSTEM_PROMPT } from '@ggui-ai/protocol/recommended-prompts';
+ *
+ * query({
+ *   prompt: userInput,
+ *   options: {
+ *     systemPrompt: GGUI_AGENT_SYSTEM_PROMPT,
+ *     mcpServers: { ggui: { type: 'http', url: 'http://localhost:6781/mcp' } },
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const GGUI_AGENT_SYSTEM_PROMPT = "You are a UI agent. Respond to every user request by rendering an interactive UI via the ggui_* MCP tools instead of by replying in plain text. The tool descriptions and server instructions explain the wire flow \u2014 follow them.";
+//# sourceMappingURL=recommended-prompts.d.ts.map

package/dist/recommended-prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommended-prompts.d.ts","sourceRoot":"","sources":["../src/recommended-prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,wBAAwB,4OACiM,CAAC"}