@ggui-ai/protocol 0.1.0-rc.1

package/dist/types/data-contract.d.ts.map

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

package/dist/types/data-contract.js

@@ -0,0 +1,111 @@
+// packages/protocol/src/types/data-contract.ts
+//
+// `DataContract` — the typed declaration an agent author hands to ggui
+// describing one screen of generated UI. Defines the wire surface the
+// component compiles against AND the runtime surface the agent reads
+// back via `ggui_consume`.
+//
+// Mental model — four typed specs + two catalogs:
+//
+//   propsSpec          : agent → client one-shot (initial render data)
+//   streamSpec         : agent → client live    (live-channel emits)
+//   actionSpec         : client → agent gesture (discrete events;
+//                        agent reacts on next turn via `ggui_consume`)
+//   contextSpec        : client → agent state   (observable last-write-wins)
+//   agentCapabilities  : catalog of MCP tools the contract references
+//                        (cross-ref target for `actionSpec[*].nextStep`
+//                        and `streamSpec[*].source.tool`)
+//   clientCapabilities : catalog of browser-capability hooks the component
+//                        imports (`useGeolocation`, `useClipboardWrite`, …)
+//
+// Placement rule for the two inbound specs (actionSpec vs contextSpec):
+// "does this thing need the agent's next-turn reasoning?" Yes →
+// actionSpec (actions drive turns). No → contextSpec (context observes
+// state). There is no third category.
+//
+// Shape: `actionSpec` / `streamSpec` / `contextSpec` are flat
+// `Record<name, Entry>` maps. `propsSpec` is a wrapper
+// `{description?, properties: Record<name, Entry>}` — `properties` is
+// the JSON Schema field name for a property bag, and the wrapper-level
+// `description` documents the props contract as a whole.
+//
+// Every entry under `propsSpec.properties` / `actionSpec` / `streamSpec`
+// / `contextSpec` is a WRAPPER that contains a JSON Schema in its
+// `schema:` field; the JSON Schema does NOT sit flat at the entry level.
+// (The #1 LLM authoring mistake. See {@link PropEntry} / {@link ActionEntry}.)
+/** Locked default applied when {@link StreamChannelEntry.mode} is omitted. */
+export const DEFAULT_STREAM_CHANNEL_MODE = 'append';
+/** Locked default applied when {@link StreamChannelEntry.replay} is omitted. */
+export const DEFAULT_STREAM_REPLAY_POLICY = 'none';
+/** Locked default applied when {@link StreamChannelEntry.complete} is omitted. */
+export const DEFAULT_STREAM_CHANNEL_COMPLETE = false;
+/**
+ * Frozen singleton instance of {@link RefreshInput}. Pass this to
+ * refresh-tool invocations instead of a fresh `{}` literal so that:
+ *
+ *   - Every call site emits exactly the same reference (cheap identity
+ *     checks in mocks / spies / test harnesses).
+ *   - `Object.freeze` catches accidental mutation that would otherwise
+ *     surface as cross-invocation interference in long-running servers.
+ */
+export const EMPTY_REFRESH_INPUT = Object.freeze({});
+/** Locked default applied when {@link ContextEntry.debounceMs}
+ * is omitted. */
+export const DEFAULT_CONTEXT_DEBOUNCE_MS = 300;
+/**
+ * Derive a JSON-safe default value for a {@link ContextEntry}.
+ *
+ * Resolution order:
+ *   1. `entry.default` (if author provided)
+ *   2. Schema-typed fallback:
+ *      - `string` → `''`
+ *      - `number` / `integer` → `0`
+ *      - `boolean` → `false`
+ *      - `array` → `[]`
+ *      - `object` → `{}`
+ *      - `null` → `null`
+ *   3. `undefined` (caller validates / rejects)
+ *
+ * Push-time validators MUST reject contextSpec entries that resolve
+ * to `undefined` here (e.g., schema is `oneOf` with no clear primitive
+ * type — author MUST provide an explicit `default` for such schemas).
+ *
+ * Consumed by the boilerplate generator's useState emission and by
+ * the push-time validator's default-derivability rule.
+ *
+ * @public
+ */
+export function deriveContextDefault(entry) {
+    if (entry.default !== undefined)
+        return entry.default;
+    const t = entry.schema?.type;
+    switch (t) {
+        case 'string': return '';
+        case 'number': return 0;
+        case 'integer': return 0;
+        case 'boolean': return false;
+        case 'array': return [];
+        case 'object': return {};
+        case 'null': return null;
+        default: return undefined;
+    }
+}
+/**
+ * Maximum byte size (UTF-8) of a single contextSpec slot's value
+ * accepted by `ggui_runtime_sync_context`. Values larger than this
+ * reject with `CONTEXT_TOO_LARGE`. contextSpec is observable state for
+ * the agent — content storage belongs on propsSpec / streamSpec / a
+ * tool call.
+ */
+export const CONTEXT_SLOT_VALUE_MAX_BYTES = 16 * 1024;
+/**
+ * Maximum byte size (UTF-8) of the full contextSpec snapshot (sum of
+ * all slot values) accepted by `ggui_runtime_sync_context`. Snapshots
+ * larger than this reject with `CONTEXT_TOO_LARGE`.
+ */
+export const CONTEXT_SNAPSHOT_MAX_BYTES = 64 * 1024;
+/**
+ * Maximum number of slots in a contextSpec snapshot. Snapshots with
+ * more slots reject with `CONTEXT_TOO_LARGE`.
+ */
+export const CONTEXT_SNAPSHOT_MAX_SLOTS = 50;

package/dist/types/events.d.ts

@@ -0,0 +1,182 @@
+import type { JsonValue } from './data-contract';
+/**
+ * Event types that flow from user to agent
+ */
+export type EventType = 'data:submit' | 'data:change' | 'lifecycle:session_start' | 'lifecycle:session_end' | 'lifecycle:stack_push' | 'lifecycle:stack_pop' | 'lifecycle:focus' | 'lifecycle:blur' | 'interaction:click' | 'interaction:hover' | 'interaction:scroll' | 'error:validation' | 'error:connection';
+/**
+ * Payload shape for `data:submit` events emitted by `useAction()`.
+ *
+ * Actions ALWAYS drive turns — every action emits an event the agent
+ * reacts to on its next turn through `ggui_consume`. There is no
+ * synchronous server-side dispatch in agent-mediated deployments. The
+ * optional `tool` hint mirrors the active stack item's
+ * `actionSpec[action].nextStep` so consumers (the WS-direct
+ * `wiredActionRouter` for agent-less `ggui serve` deployments, and
+ * telemetry on agent-mediated deployments) see which tool the agent
+ * intends to call next without re-looking-up the contract.
+ *
+ * @typeParam TData - Type of the action payload (defaults to `unknown`).
+ */
+export interface ActionEventValue<TData = unknown> {
+    /** Action ID from the contract (e.g., "submit", "archive"). */
+    action: string;
+    /** Action payload (e.g., form data). */
+    data: TData;
+    /**
+     * MCP tool name mirrored from the active stack item's
+     * `actionSpec[action].nextStep` (when the author declared one).
+     * Absent when the action has no `nextStep` — the agent decides the
+     * next tool freely from broader context.
+     *
+     * Consumer behavior:
+     *   - Agent-mediated deployments: read by the agent on `ggui_consume`
+     *     as a hint; agent decides whether to honor it.
+     *   - WS-direct agent-less deployments (`ggui serve`): the
+     *     `wiredActionRouter` fires this tool synchronously when present.
+     *
+     * **Disagreement policy:** if both the envelope's `tool` and the
+     * server's `actionSpec[action].nextStep` are present and disagree,
+     * the **client-populated value wins** (client is the source of truth
+     * for what the user actually saw).
+     */
+    tool?: string;
+}
+/**
+ * Inbound live-channel envelope — the body of a `type: 'action'`
+ * WebSocket message.
+ *
+ * Symmetric companion to the outbound {@link StreamEnvelope}. Flat,
+ * narrow, and limited to fields the server actually enforces or
+ * diagnostic fields real consumers populate today.
+ *
+ * Fields that are NOT on this envelope, and why:
+ *   - `appId` — the server resolves it from the session; client-claimed
+ *     values are ignored for enforcement.
+ *   - `user` / `userId` / `deviceInfo` / `interfaceContext` — diagnostic
+ *     session metadata captured at subscribe time, not per-delivery.
+ *   - `componentId` / `contractHash` — diagnostic; no enforcement
+ *     consumer.
+ *   - `timestamp` — the server uses its own clock for ordering + log
+ *     emission; client-supplied timestamps aren't authoritative.
+ *   - `correlationId` — the doctrine names this for agent-push ↔ user
+ *     action pairing; `stackItemId` covers the narrow case today.
+ *
+ * Required fields map to existing enforcement concerns; optional fields
+ * are doctrine-aligned forward-compat additions that cost nothing on the
+ * wire when omitted.
+ */
+export interface ActionEnvelope<TPayload = JsonValue> {
+    /**
+     * Session identity. Server enforces subscriber-session binding —
+     * envelopes whose sessionId doesn't match the ws subscriber's bound
+     * session are rejected (SESSION_MISMATCH).
+     */
+    sessionId: string;
+    /**
+     * Action / event type. Gated by the active stack item's
+     * `subscription.events` allowlist (falling back to
+     * `DEFAULT_SUBSCRIPTION`).
+     */
+    type: EventType;
+    /**
+     * Payload for the action. For `type: 'data:submit'` this carries the
+     * {@link ActionEventValue} shape (`{action, data?, tool?}`) where
+     * `data` is validated against the stack item's
+     * `actionSpec[action].schema`. For non-data:submit types the payload
+     * is free-form — no schema enforcement.
+     */
+    payload?: TPayload;
+    /**
+     * Stack item the action originated from. Authoritative for contract
+     * lookup when present. Server falls back to
+     * `session.currentStackIndex` when absent — that fallback lets
+     * agents that have popped forward between emit and ingress still
+     * process legitimate in-flight actions.
+     */
+    stackIndex?: number;
+    /**
+     * Stable stack-item identifier. Forward-compat with the
+     * three-channel-topology doctrine's `correlationId` semantics — when
+     * `stackItemId` is present and matches a stack item's `id`, server MAY
+     * prefer stackItemId-based contract lookup over positional stackIndex.
+     */
+    stackItemId?: string;
+    /**
+     * Client-monotonic sequence number for at-least-once dedup. Declared
+     * shape; no server enforcement today (no inbound dedup infrastructure
+     * yet). Clients SHOULD populate when their transport can replay
+     * (e.g., reconnect-with-backfill); server SHOULD dedup by
+     * `(sessionId, clientSeq)` when dedup lands.
+     */
+    clientSeq?: number;
+    /**
+     * Protocol schema version stamped by the producer. Pre-launch:
+     * advisory — consumers MUST NOT reject on mismatch. A future
+     * launch-cutover change tightens policy to `UPGRADE_REQUIRED` when
+     * the received major diverges from the client's known major.
+     *
+     * See `PROTOCOL_SCHEMA_VERSION` for the current value.
+     */
+    schemaVersion?: string;
+}
+/**
+ * Event subscription configuration.
+ *
+ * @deprecated Pre-actionSpec event-filtering model. Today's flow:
+ * every action emits a `data:submit` event the agent receives via
+ * `ggui_consume`; non-`data:submit` event types are vestigial. Kept
+ * only for older WS clients that still send `subscribe` with these
+ * filters — new code MUST NOT consult this type.
+ */
+export interface EventSubscription {
+    /** Global event types to subscribe to */
+    events: EventType[];
+    /** Per-component overrides for event filtering and streaming */
+    components?: Record<string, {
+        /** Whether to stream real-time change events for this component */
+        stream?: boolean;
+        /** Component-specific event types (overrides global list) */
+        events?: EventType[];
+    }>;
+}
+/**
+ * Default subscription when agent doesn't specify.
+ *
+ * @deprecated See {@link EventSubscription}.
+ */
+export declare const DEFAULT_SUBSCRIPTION: EventSubscription;
+/**
+ * Emitted when an MCP server requires OAuth credentials that the user
+ * has not yet granted. The frontend should display a consent prompt
+ * linking to {@link consentUrl}.
+ */
+export interface McpAuthRequiredEvent {
+    type: 'system';
+    action: 'auth_required';
+    /** Identifier of the external service (e.g. `'github'`, `'slack'`) */
+    serviceId: string;
+    /** Human-readable service name shown in the consent UI */
+    displayName: string;
+    /** OAuth scopes being requested (optional — omitted when the service uses fixed scopes) */
+    scopes?: string[];
+    /** URL the user should visit to grant consent */
+    consentUrl: string;
+    /** Explanatory message for the user (e.g. "GitHub access is required to list repositories") */
+    message: string;
+}
+/**
+ * Emitted after the user completes (or denies) the OAuth consent flow.
+ * The frontend should dismiss the consent prompt and, if `status` is
+ * `'ready'`, retry the operation that triggered the auth request.
+ */
+export interface McpCredentialReadyEvent {
+    type: 'system';
+    action: 'credential_ready';
+    /** Identifier of the external service that was authorized */
+    serviceId: string;
+    /** Whether the credential is now available or the user denied access */
+    status: 'ready' | 'denied';
+}
+/** Union of all system events emitted by the MCP credential proxy */
+export type McpCredentialSystemEvent = McpAuthRequiredEvent | McpCredentialReadyEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,SAAS,GAEjB,aAAa,GACb,aAAa,GAEb,yBAAyB,GACzB,uBAAuB,GACvB,sBAAsB,GACtB,qBAAqB,GACrB,iBAAiB,GACjB,gBAAgB,GAEhB,mBAAmB,GACnB,mBAAmB,GACnB,oBAAoB,GAEpB,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO;IAC/C,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,IAAI,EAAE,KAAK,CAAC;IACZ;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,SAAS;IAClD;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAC1B,mEAAmE;QACnE,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,6DAA6D;QAC7D,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;KACtB,CAAC,CAAC;CACJ;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,iBAElC,CAAC;AAIF;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,eAAe,CAAC;IACxB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;IAC3B,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,GAAG,uBAAuB,CAAC"}

package/dist/types/events.js

@@ -0,0 +1,8 @@
+/**
+ * Default subscription when agent doesn't specify.
+ *
+ * @deprecated See {@link EventSubscription}.
+ */
+export const DEFAULT_SUBSCRIPTION = {
+    events: ['data:submit', 'lifecycle:session_end'],
+};

package/dist/types/feedback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * UI Feedback types -- end-user ratings for generated UIs.
+ *
+ * Users can rate each rendered page with love/dislike/other.
+ * Feedback is sent via WebSocket and stored server-side.
+ */
+/**
+ * Feedback rating options for a generated UI page.
+ */
+export type FeedbackRating = 'love' | 'dislike' | 'other';
+/**
+ * Input payload for submitting UI feedback via WebSocket.
+ */
+export interface UIFeedbackPayload {
+    /** Page (stack item) being rated */
+    stackItemId: string;
+    /** Session the page belongs to */
+    sessionId: string;
+    /** Rating type */
+    rating: FeedbackRating;
+    /** Free-text comment (required when rating is 'other', optional otherwise) */
+    comment?: string;
+}
+//# sourceMappingURL=feedback.d.ts.map

package/dist/types/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/types/feedback.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types/feedback.js

@@ -0,0 +1,7 @@
+/**
+ * UI Feedback types -- end-user ratings for generated UIs.
+ *
+ * Users can rate each rendered page with love/dislike/other.
+ * Feedback is sent via WebSocket and stored server-side.
+ */
+export {};

package/dist/types/gadget.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Lifecycle states a {@link GadgetHook} reports through its
+ * `status` field. Implementations MUST transition through these in a
+ * predictable order; the UI generator's boilerplate may render
+ * status-conditioned UI (e.g., a "Tap to start" CTA on `'idle'`, a
+ * spinner on `'prompting'`, an error banner on `'denied' | 'error'`).
+ *
+ *  - `'idle'`       — hook mounted; no `start()` invoked yet.
+ *  - `'prompting'`  — browser permission UI surfaced; awaiting user.
+ *  - `'active'`     — gadget in flight (mic recording, location
+ *                     stream open, camera frame loop running, …). For
+ *                     one-shot gadgets (`navigator.share`), this
+ *                     status may not be observed.
+ *  - `'completed'`  — terminal success state. `value` populated.
+ *  - `'denied'`     — terminal failure: user (or platform policy)
+ *                     refused permission. `error.code === 'permission_denied'`.
+ *  - `'error'`      — terminal failure: any other error.
+ */
+export type GadgetStatus = 'idle' | 'prompting' | 'active' | 'completed' | 'denied' | 'error';
+/**
+ * Shape of {@link GadgetHook}'s `error` field when the hook is
+ * in a terminal-failure status (`'denied'` / `'error'`).
+ *
+ * `code` is a closed set today and MAY be extended with `(string &
+ * {})` in a future minor — consumers MUST handle unknown codes by
+ * falling through to a default branch instead of throwing.
+ *
+ * `message` is author-readable; safe to surface in UI. Hooks SHOULD
+ * NOT include raw stack traces here (those belong on hook-internal
+ * logging, not on the public error surface).
+ */
+export interface GadgetError {
+    /**
+     * Canonical failure code. Implementations MUST set one of:
+     *
+     *  - `'permission_denied'` — user refused the browser-permission
+     *    prompt OR a platform policy (iframe sandbox, HTTP origin,
+     *    enterprise lockdown) blocks the gadget.
+     *  - `'not_supported'`     — the host environment does not implement
+     *    the underlying API (`!('mediaDevices' in navigator)`).
+     *  - `'aborted'`           — the call was cancelled (e.g., the user
+     *    closed a `navigator.share` sheet, the hook was unmounted
+     *    mid-flight).
+     *  - `'timeout'`           — the hook exceeded its configured
+     *    deadline (e.g., geolocation watch never produced a fix).
+     *  - `'unknown'`           — fallback for failures the hook can't
+     *    classify; `message` carries the platform string.
+     */
+    readonly code: 'permission_denied' | 'not_supported' | 'aborted' | 'timeout' | 'unknown';
+    /** Short, author-readable failure summary. Safe to surface in UI. */
+    readonly message: string;
+}
+/**
+ * The interface every browser-capability gadget hook in
+ * `@ggui-ai/gadgets` (and any third-party gadget hook
+ * registered on a `clientCapabilities` entry) MUST satisfy.
+ *
+ * Shape generic over:
+ *
+ *   - `TOutput`  — the value the gadget produces when active /
+ *     completed (e.g., a `MediaRecorder`-backed `Blob` for
+ *     `useMicrophone`, a `GeolocationPosition` for `useGeolocation`).
+ *   - `TOptions` — the optional configuration passed to the hook (e.g.,
+ *     `{ enableHighAccuracy: true }` for `useGeolocation`). Defaults to
+ *     `void` for hooks that take no options.
+ *
+ * Return-shape contract:
+ *
+ *   - `value`   — `TOutput | undefined`. Undefined until the
+ *     gadget transitions to `'active'` / `'completed'`.
+ *   - `status`  — current lifecycle state; see {@link GadgetStatus}.
+ *   - `error`   — present iff `status` is `'denied'` or `'error'`.
+ *   - `start()` — invokes the gadget. MUST be idempotent if called
+ *     while `status === 'active'`. Resolves with the produced value on
+ *     success, `undefined` on failure (consumers read `error` for
+ *     diagnostics).
+ *   - `stop?`   — optional cancel/teardown for continuous gadgets
+ *     (mic stream, geolocation watch). Absent on one-shot gadgets.
+ *
+ * Why declarative-only on the contract surface:
+ *
+ *   `DataContract.clientCapabilities.gadgets` is package-keyed —
+ *   `Record<packageName, Record<exportName, { description?, usage? }>>`.
+ *   Each export entry declares only WHICH export the UI uses (the
+ *   export name is the inner map key; its grammar — `use`-prefixed
+ *   hook vs PascalCase component — discriminates kind) and HOW the
+ *   agent should describe it. It does NOT carry argument schemas,
+ *   response schemas, or example payloads. Gadget values only become
+ *   observable to the agent if the UI threads them into a
+ *   `contextSpec` slot or an `actionSpec` payload —
+ *   `clientCapabilities.gadgets` itself is an export-declaration
+ *   catalog, not an RPC channel.
+ */
+export interface GadgetHook<TOutput, TOptions = void> {
+    (options?: TOptions): {
+        /**
+         * Current gadget value. Undefined until the hook transitions to
+         * `'active'` / `'completed'`. For continuous gadgets (mic stream)
+         * this may update on every frame; for one-shot gadgets
+         * (`navigator.share`) it settles once on success.
+         */
+        readonly value: TOutput | undefined;
+        /** Lifecycle state; see {@link GadgetStatus}. */
+        readonly status: GadgetStatus;
+        /** Present iff `status` is `'denied'` or `'error'`. */
+        readonly error?: GadgetError;
+        /**
+         * Invoke the gadget. Idempotent while `status === 'active'`.
+         * Resolves to the produced value on success, `undefined` on
+         * failure. Consumers read `error` for diagnostics.
+         */
+        readonly start: () => Promise<TOutput | undefined>;
+        /**
+         * Optional teardown. Present only on continuous gadgets (mic
+         * stream, geolocation watch). Absent on one-shot gadgets
+         * (`navigator.share`).
+         */
+        readonly stop?: () => void;
+    };
+}
+//# sourceMappingURL=gadget.d.ts.map

package/dist/types/gadget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gadget.d.ts","sourceRoot":"","sources":["../../src/types/gadget.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,WAAW,GACX,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,OAAO,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACzF,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI;IAClD,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG;QACpB;;;;;WAKG;QACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;QACpC,iDAAiD;QACjD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;QAC9B,uDAAuD;QACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;QAC7B;;;;WAIG;QACH,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;QACnD;;;;WAIG;QACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC;KAC5B,CAAC;CACH"}

package/dist/types/gadget.js

@@ -0,0 +1,24 @@
+// packages/protocol/src/types/gadget.ts
+//
+// `GadgetHook` generic + the runtime status / error types that
+// every browser-capability gadget hook in `@ggui-ai/gadgets`
+// (and any third-party gadget hook) MUST satisfy.
+//
+// Capabilities differ from agent tools by direction and ownership:
+//
+//   - **agentCapabilities** (in `@ggui-ai/protocol`'s
+//     `DataContract.agentCapabilities`) — RPC the contract REFERENCES.
+//     The agent's MCP toolbox is the source of truth at dispatch time.
+//     Catalog declaration is documentation.
+//
+//   - **clientCapabilities** (in `DataContract.clientCapabilities`) —
+//     browser-capability gadget HOOKS the UI uses. The catalog says
+//     "this UI calls `useMicrophone()`"; the value flows from browser →
+//     UI → (optionally) into context/action payloads. The agent does
+//     NOT invoke these from its side — there is no RPC. The UI hook
+//     owns the lifecycle (prompting, status, value, error).
+//
+// The generic below pins what every gadget hook MUST return so the
+// generated boilerplate, the LLM authoring contract, and the
+// `@ggui-ai/gadgets` v1 package all agree on shape.
+export {};