@ggui-ai/protocol 0.1.0-rc.1

package/dist/types/handshake-suggestion.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Handshake-suggestion shapes (2026-05-12).
+ *
+ * The three-step handshake protocol replaces the older `match` + `plan`
+ * framing on the handshake output.
+ *
+ * Step 1 — the agent posts a `BlueprintDraft` (its idea: contract +
+ * optional variance + optional generator hint).
+ *
+ * Step 2 — the server runs `BlueprintSearch` + contract validation in
+ * parallel and returns a {@link HandshakeSuggestion}. The suggestion's
+ * `origin` enum routes the agent's next decision:
+ *
+ *   - `cache`  — search-score crossed the per-app threshold; cached
+ *                code wins. `blueprintMeta.codeHash` is present.
+ *   - `agent`  — search missed but validation passed; gen pending
+ *                against the agent's draft. Provisional blueprintId.
+ *   - `synth`  — search missed AND validation failed; synth amended
+ *                the contract. Provisional blueprintId; `amendments`
+ *                carries the diff vs the agent's draft.
+ *
+ * Step 3 — the agent posts a `PushDecision` (accept the suggestion or
+ * override with a fresh draft). Accept reuses the provisional
+ * `blueprintId`; override mints a fresh one.
+ *
+ * Locked decisions:
+ *
+ *   - `blueprintMeta` is ALWAYS present on a successful handshake
+ *     (Option B from §D5). `codeHash` is the only field that's absent
+ *     on non-cache origins.
+ *   - `amendments` is populated only on `origin: 'synth'`. On `cache`
+ *     and `agent` origins it MUST be omitted.
+ *   - `validationFindings` is populated only when validators ran AND
+ *     produced findings — on cache hits these surface as a soft
+ *     warning ("your draft would've had X issue — using cached
+ *     blueprint instead"); on agent/synth they're carried for
+ *     telemetry only (synth's amendment already addressed them).
+ */
+import type { Blueprint, BlueprintVariance } from './blueprint.js';
+import type { DataContract, JsonValue } from './data-contract.js';
+/**
+ * Where the handshake's `blueprintMeta` came from. Routes the agent's
+ * cognitive model:
+ *
+ *   - `cache`  — an existing blueprint matched at or above the per-app
+ *                threshold. `blueprintMeta.codeHash` is present; the
+ *                paired `ggui_push({decision: {kind: 'accept'}})`
+ *                short-circuits to cache delivery.
+ *   - `agent`  — no cache hit, but the agent's draft validated cleanly.
+ *                `codeHash` absent; gen runs on push against the
+ *                agent's draft contract verbatim.
+ *   - `synth`  — no cache hit AND validation failed. The synth
+ *                amender produced a new contract; the diff vs the
+ *                agent's draft is in `amendments.contractDiff`.
+ */
+export type SuggestionOrigin = 'cache' | 'agent' | 'synth';
+/**
+ * Agent's draft on the handshake input — what the agent wants to
+ * build. The contract is required; variance + generator are optional
+ * hints. The server combines this with its own session/app context
+ * (cached blueprints, validator outcomes, operator pins) to produce
+ * a {@link HandshakeSuggestion}.
+ */
+export interface BlueprintDraft {
+    /**
+     * Agent-authored DataContract. Drives both the blueprint-search
+     * embed/structural axes and the contract validators. The agent is
+     * the contract authority; synth amends only when validation fails.
+     */
+    readonly contract: DataContract;
+    /**
+     * Optional variance tags. Carried through to the suggestion's
+     * `blueprintMeta.variance` field; if `decision: 'accept'` lands on a
+     * fresh-gen path (origin === 'agent' or 'synth'), the persisted
+     * Blueprint row inherits these tags.
+     */
+    readonly variance?: {
+        /** Free-form persona tag (e.g. 'minimalist', 'data-dense'). */
+        readonly persona?: string;
+        /** Aesthetic tag — promoted to first-class in a future slice. */
+        readonly aesthetic?: string;
+        /** Small structured signal — JSON-safe. */
+        readonly context?: {
+            readonly [key: string]: JsonValue | undefined;
+        };
+        /** Raw style hint / seed prompt. */
+        readonly seedPrompt?: string;
+    };
+    /**
+     * Generator slug hint (e.g. `'ui-gen-advanced-opus-4-7'`). The
+     * server resolves the effective generator as:
+     *
+     *   1. Operator app-pin (`App.pinnedGenerator`) — wins if set.
+     *   2. This hint — if registered in the GeneratorRegistry.
+     *   3. Registry default (`ui-gen-default-haiku-4-5`).
+     *
+     * Hint-only; unknown slugs fall through to the registry default.
+     */
+    readonly generator?: string;
+}
+/**
+ * Blueprint metadata projected onto the handshake response. The agent
+ * uses this to decide whether to accept (reuse the provisional id) or
+ * override (mint a fresh id with its own new draft).
+ *
+ * `blueprintId` is PROVISIONAL — it becomes durable iff the paired
+ * push sends `decision: 'accept'`. An override discards it.
+ */
+export interface BlueprintMeta {
+    /**
+     * Provisional blueprint id. Server-minted at handshake-time.
+     * Becomes durable when push accepts; discarded on push override.
+     */
+    readonly blueprintId: string;
+    /** Canonical RFC 8785 (JCS) hash of the suggestion's contract. */
+    readonly contractHash: string;
+    /**
+     * Content hash of the cached code body. Present iff `origin ===
+     * 'cache'`. Absent for `agent` / `synth` (gen pending).
+     */
+    readonly codeHash?: string;
+    /** Slug of the generator that produced (or will produce) the code. */
+    readonly generator: string;
+    /** Variance tags carried through from the suggestion. */
+    readonly variance: BlueprintVariance;
+    /**
+     * Optional matcher telemetry — why this blueprint was selected.
+     * Operator-readable; LLM-readable. E.g. `'contract-hash, persona →
+     * score 0.92'`.
+     */
+    readonly selectedReason?: string;
+}
+/**
+ * Validator finding surfaced on the suggestion. Mirrors
+ * `@ggui-ai/protocol/validation/lint-contract`'s `ContractIssue` shape
+ * loosely — kept structural here so the suggestion contract doesn't
+ * import from the linter module and create a tight cycle.
+ *
+ * Each finding has a stable `code`, a severity, the dotted-path
+ * location, and a human-readable `message`.
+ */
+export interface SuggestionFinding {
+    /** Stable error code (e.g. `'CTR_REF_NEXT_STEP'`, `'CTR_DUP_NAME'`). */
+    readonly code: string;
+    readonly severity: 'error' | 'warn';
+    /** Dotted JS-style path into the contract. */
+    readonly path: string;
+    /** Human-readable violation prose. */
+    readonly message: string;
+}
+/**
+ * Synth's amendment — the diff vs the agent's draft. Populated only on
+ * `origin: 'synth'`.
+ *
+ * `contractDiff` is an RFC 6902 JSON-Patch-style array; the diff
+ * applied to the agent's draft yields the suggestion's contract.
+ * Helpers in `@ggui-ai/protocol/validation/contract-diff` produce and
+ * apply the diff.
+ *
+ * `reasoning` is the synth model's natural-language explanation —
+ * "added required `submit` action so the form completion is
+ * observable", etc.
+ */
+export interface SuggestionAmendments {
+    readonly contractDiff: JsonPatch;
+    readonly reasoning: string;
+}
+/**
+ * Minimal RFC 6902 JSON-Patch shape carried in handshake-suggestion
+ * amendments. The protocol re-exports this so consumers can apply /
+ * inspect patches without an external dependency.
+ *
+ * Subset support — every emitter MUST honor `add` / `remove` /
+ * `replace`; `move` / `copy` / `test` are reserved for future use
+ * (consumers MAY reject unrecognized ops).
+ */
+export type JsonPatch = readonly JsonPatchOp[];
+export type JsonPatchOp = {
+    readonly op: 'add';
+    readonly path: string;
+    readonly value: JsonValue;
+} | {
+    readonly op: 'remove';
+    readonly path: string;
+} | {
+    readonly op: 'replace';
+    readonly path: string;
+    readonly value: JsonValue;
+};
+/**
+ * The full handshake suggestion. Produced by the server in step-2 of
+ * the three-step handshake; the agent reads this in the response and
+ * branches its push decision on `origin` (accept vs override).
+ */
+export interface HandshakeSuggestion {
+    /** Routing discriminator — see {@link SuggestionOrigin}. */
+    readonly origin: SuggestionOrigin;
+    /** Operator-readable + LLM-readable rationale ("contract-hash → score 0.92"). */
+    readonly rationale: string;
+    /** Provisional blueprint metadata — see {@link BlueprintMeta}. */
+    readonly blueprintMeta: BlueprintMeta;
+    /**
+     * Populated iff `origin === 'synth'`. Carries the JSON-Patch diff
+     * vs the agent's draft and the synth model's reasoning.
+     */
+    readonly amendments?: SuggestionAmendments;
+    /**
+     * Populated iff validators ran AND produced findings. On `origin:
+     * 'cache'` these surface as a soft warning (the agent's draft
+     * WOULD have had issues, but the cached blueprint is being served);
+     * on `agent` / `synth` they're absent (agent path's validators
+     * passed; synth path's amendments already addressed them).
+     */
+    readonly validationFindings?: readonly SuggestionFinding[];
+}
+/**
+ * Decision discriminator on the push input. Replaces the old
+ * `{contract? | contractHash?}` triad with a clearer accept-vs-
+ * override branch.
+ *
+ *   - `accept`   — use the handshake's `blueprintMeta` verbatim.
+ *                  If `codeHash` is present (origin === 'cache'),
+ *                  delivery is a fast cache fetch. Otherwise gen
+ *                  runs against the suggestion's stored contract.
+ *   - `override` — mint a fresh blueprintId and run gen against the
+ *                  agent's NEW draft. The provisional id from the
+ *                  handshake is discarded.
+ */
+export type PushDecision = {
+    readonly kind: 'accept';
+} | {
+    readonly kind: 'override';
+    readonly blueprintDraft: BlueprintDraft;
+};
+/**
+ * Build a minimal JSON-Patch RFC 6902 diff between two contracts.
+ *
+ * Algorithm: shallow walk over the union of top-level keys; for each
+ * key, recurse into nested objects, otherwise emit `add` / `remove` /
+ * `replace` at the appropriate path. Arrays are diffed as whole values
+ * (no LCS) — sufficient for the synth-amendment use case where the
+ * synth model rewrites slot/action maps wholesale rather than
+ * splicing single array elements.
+ *
+ * Output is a {@link JsonPatch}; applying it to `before` produces
+ * `after` (modulo array-element identity).
+ *
+ * Pure / deterministic. Exposed so synth implementations don't need
+ * to ship their own diff helper.
+ */
+export declare function jsonPatch(before: unknown, after: unknown): JsonPatch;
+/**
+ * Top-N alternative blueprints surfaced on the handshake response.
+ * Agents can override into one of these (push with `decision:
+ * 'override'`) — the alternatives are full {@link Blueprint} rows so
+ * the agent inspects everything it needs to decide.
+ *
+ * Sorted by descending match score; the suggestion's primary
+ * `blueprintMeta` is NOT duplicated here (the alternatives are
+ * what the search returned EXCLUDING the top result that became the
+ * primary).
+ */
+export type SuggestionAlternatives = readonly Blueprint[];
+//# sourceMappingURL=handshake-suggestion.d.ts.map

package/dist/types/handshake-suggestion.d.ts.map

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

package/dist/types/handshake-suggestion.js

@@ -0,0 +1,70 @@
+/**
+ * Build a minimal JSON-Patch RFC 6902 diff between two contracts.
+ *
+ * Algorithm: shallow walk over the union of top-level keys; for each
+ * key, recurse into nested objects, otherwise emit `add` / `remove` /
+ * `replace` at the appropriate path. Arrays are diffed as whole values
+ * (no LCS) — sufficient for the synth-amendment use case where the
+ * synth model rewrites slot/action maps wholesale rather than
+ * splicing single array elements.
+ *
+ * Output is a {@link JsonPatch}; applying it to `before` produces
+ * `after` (modulo array-element identity).
+ *
+ * Pure / deterministic. Exposed so synth implementations don't need
+ * to ship their own diff helper.
+ */
+export function jsonPatch(before, after) {
+    const ops = [];
+    buildPatchOps(before, after, '', ops);
+    return Object.freeze(ops);
+}
+function buildPatchOps(before, after, path, ops) {
+    if (before === after)
+        return;
+    // null / primitive replacements
+    if (before === null ||
+        after === null ||
+        typeof before !== 'object' ||
+        typeof after !== 'object') {
+        ops.push({ op: 'replace', path, value: after });
+        return;
+    }
+    const beforeArr = Array.isArray(before);
+    const afterArr = Array.isArray(after);
+    if (beforeArr !== afterArr) {
+        // Whole-value replace when the kind flips (object ↔ array).
+        ops.push({ op: 'replace', path, value: after });
+        return;
+    }
+    if (beforeArr && afterArr) {
+        // Whole-array replace — sufficient for amendment diffs.
+        ops.push({ op: 'replace', path, value: after });
+        return;
+    }
+    // Both are plain objects.
+    const beforeObj = before;
+    const afterObj = after;
+    const keys = new Set([...Object.keys(beforeObj), ...Object.keys(afterObj)]);
+    for (const key of keys) {
+        const childPath = `${path}/${encodeJsonPointerSegment(key)}`;
+        const inBefore = Object.prototype.hasOwnProperty.call(beforeObj, key);
+        const inAfter = Object.prototype.hasOwnProperty.call(afterObj, key);
+        if (!inAfter) {
+            ops.push({ op: 'remove', path: childPath });
+            continue;
+        }
+        if (!inBefore) {
+            ops.push({ op: 'add', path: childPath, value: afterObj[key] });
+            continue;
+        }
+        buildPatchOps(beforeObj[key], afterObj[key], childPath, ops);
+    }
+}
+/**
+ * Encode a single JSON-Pointer segment per RFC 6901 §4: `~` → `~0`,
+ * `/` → `~1`. Other characters pass through unchanged.
+ */
+function encodeJsonPointerSegment(seg) {
+    return seg.replace(/~/g, '~0').replace(/\//g, '~1');
+}

package/dist/types/host-context.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Host Context — projected subset of `McpUiHostContext` ggui captures from
+ * the MCP Apps `ui/initialize` response and echoes back to session state so
+ * the agent can reason about device/host capabilities on subsequent turns.
+ *
+ * The MCP Apps spec (`@modelcontextprotocol/ext-apps`) defines a rich
+ * `McpUiHostContext` (theme, styles, displayMode, availableDisplayModes,
+ * containerDimensions, locale, timeZone, userAgent, platform,
+ * deviceCapabilities). ggui captures it iframe-side at `ui/initialize` and
+ * echoes a TRIMMED projection back over the live channel (via the
+ * `host_context_observed` outbound message) so the server can persist it on
+ * `SessionRecord.hostContext` and surface it on `ggui_handshake` /
+ * `ggui_consume` output for the agent.
+ *
+ * Why a projection rather than passthrough:
+ *
+ *   - `theme` / `styles` already flow through ggui's separate theming
+ *     pipeline (`InterfaceContext` + the theme registry). Duplicating
+ *     creates two sources of truth.
+ *   - `toolInfo` is host-loop-internal — the agent has its own toolInfo via
+ *     MCP framing.
+ *   - `userAgent` is rarely actionable; skip until a concrete use case
+ *     appears. Easy to add later (additive optional field).
+ *
+ * What the projection KEEPS:
+ *
+ *   - `availableDisplayModes` / `currentDisplayMode` — drives canvas-mode
+ *     display-mode escalation policy (see canvas-mode-detail-displaymode.md).
+ *   - `containerDimensions` — lets the agent reason about layout density
+ *     and lets the canvas reflow on resize.
+ *   - `platform` / `deviceCapabilities` — feeds the generator's
+ *     responsive-UI prompts.
+ *   - `locale` / `timeZone` — useful for the agent's date/number rendering.
+ *
+ * Compatibility posture: every field is optional. Hosts that emit a
+ * minimal `McpUiHostContext` (spec-permissible) project to an empty
+ * object; consumers MUST handle every field as possibly absent.
+ *
+ * Versioning: the wire wrapper carries `schemaVersion` so future
+ * projection widenings can be detected; this module is the canonical
+ * shape for the current schema major.
+ */
+import type { JsonValue } from './data-contract';
+/**
+ * The three display modes the MCP Apps spec defines. Mirror of
+ * `McpUiDisplayMode` from `@modelcontextprotocol/ext-apps` — re-declared
+ * here so the protocol package doesn't take a runtime dependency on the
+ * SDK (the SDK is consumed in iframe-runtime + system-card; the protocol
+ * package stays SDK-free per the layering boundary).
+ *
+ * Stay in sync with the SDK literal: `'inline' | 'fullscreen' | 'pip'`.
+ * If the spec adds a fourth mode, widen here and in
+ * `iframe-runtime`'s capability-resolution helpers in lockstep.
+ */
+export type McpUiDisplayMode = 'inline' | 'fullscreen' | 'pip';
+/**
+ * Width specification — either fixed `width` or `maxWidth`, never both.
+ * Matches the spec's discriminated container-dimension shape.
+ */
+export interface HostContextWidth {
+    readonly width?: number;
+    readonly maxWidth?: number;
+}
+/**
+ * Height specification — either fixed `height` or `maxHeight`, never both.
+ */
+export interface HostContextHeight {
+    readonly height?: number;
+    readonly maxHeight?: number;
+}
+/**
+ * Iframe / container dimensions reported by the host. Width and height
+ * are independently spec'd (one may be fixed, the other max-bounded).
+ */
+export type HostContextContainerDimensions = HostContextWidth & HostContextHeight;
+/**
+ * Input capabilities reported by the host. Both `touch` and `hover` may
+ * be true (hybrid devices); both may be false (rare, e.g., voice-only
+ * hosts).
+ */
+export interface HostContextDeviceCapabilities {
+    readonly touch?: boolean;
+    readonly hover?: boolean;
+}
+/**
+ * Trimmed projection of `McpUiHostContext` that ggui captures iframe-side
+ * and echoes to session state for agent visibility.
+ *
+ * Every field is optional. Hosts that emit minimal context project to
+ * mostly-empty objects; consumers MUST treat every field as possibly
+ * absent and degrade gracefully.
+ *
+ * Theme + styles intentionally EXCLUDED — they flow through ggui's own
+ * theming pipeline (`InterfaceContext`, theme registry). Duplicating
+ * here would create two sources of truth.
+ *
+ * `userAgent` + `toolInfo` intentionally EXCLUDED for v1 — easy to add
+ * later if a concrete use case appears.
+ */
+export interface HostContextProjection {
+    /** Display modes the host can render this view in. Absent ⇒ assume `['inline']`. */
+    readonly availableDisplayModes?: readonly McpUiDisplayMode[];
+    /** Current display mode the host is rendering. Absent ⇒ assume `'inline'`. */
+    readonly currentDisplayMode?: McpUiDisplayMode;
+    /** Iframe container dimensions. Absent ⇒ unknown; use a reasonable default. */
+    readonly containerDimensions?: HostContextContainerDimensions;
+    /** Host platform classification. */
+    readonly platform?: 'web' | 'desktop' | 'mobile';
+    /** Touch / hover input capability. */
+    readonly deviceCapabilities?: HostContextDeviceCapabilities;
+    /** User's BCP-47 locale (e.g., `'en-US'`). */
+    readonly locale?: string;
+    /** User's IANA timezone (e.g., `'America/Los_Angeles'`). */
+    readonly timeZone?: string;
+}
+/**
+ * Live-channel inbound (client → server) payload that delivers the
+ * iframe-captured `HostContextProjection` to the server. Server-side
+ * handler writes to `SessionRecord.hostContext`; subsequent
+ * `ggui_handshake` / `ggui_consume` responses surface the value to the
+ * agent via the optional `client.hostContext` field.
+ *
+ * Emission cadence:
+ *   - Once after the iframe-runtime's `ui/initialize` resolves (initial
+ *     capture).
+ *   - Once per `ui/notifications/host-context-changed` notification
+ *     received from the host.
+ *
+ * Idempotent — re-delivery (e.g., after a reconnect) overwrites the
+ * stored value; no merge logic.
+ */
+export interface HostContextObservedPayload {
+    readonly sessionId: string;
+    readonly hostContext: HostContextProjection;
+}
+/**
+ * Project a raw `McpUiHostContext` (from the spec SDK or any equivalent
+ * shape — accepts `unknown` so callers don't need to drag in the SDK
+ * just to call this) into `HostContextProjection`.
+ *
+ * Defensive: every field crosses a trust boundary. Malformed inputs
+ * (wrong types, weird shapes) drop silently to undefined for that
+ * field rather than failing the whole projection. The whole capture
+ * path is best-effort — never blocks the bootstrap.
+ *
+ * Returns `undefined` when the input is not an object at all (caller
+ * received null / array / primitive from the host). Returns an empty
+ * object when the input is an object but no recognized fields are
+ * present — the distinction lets callers tell "host emitted context
+ * with no recognized fields" from "host emitted no context."
+ */
+export declare function projectHostContext(raw: unknown): HostContextProjection | undefined;
+/**
+ * Deep equality check for two projections. Used by the iframe-runtime
+ * to suppress no-op re-emissions when a `host-context-changed`
+ * notification arrives but no projection-visible field actually changed.
+ *
+ * JSON-stringify is sufficient because the projection contains only
+ * primitives, arrays of primitives, and plain objects of primitives.
+ */
+export declare function hostContextProjectionsEqual(a: HostContextProjection | undefined, b: HostContextProjection | undefined): boolean;
+export type { JsonValue };
+//# sourceMappingURL=host-context.d.ts.map

package/dist/types/host-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-context.d.ts","sourceRoot":"","sources":["../../src/types/host-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMjD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,YAAY,GAAG,KAAK,CAAC;AAM/D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAMlF;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAMD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7D,8EAA8E;IAC9E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IAC/C,+EAA+E;IAC/E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IAC9D,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;IACjD,sCAAsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,6BAA6B,CAAC;IAC5D,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;CAC7C;AAoBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAsDlF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,CAAC,EAAE,qBAAqB,GAAG,SAAS,EACpC,CAAC,EAAE,qBAAqB,GAAG,SAAS,GACnC,OAAO,CAIT;AAGD,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/dist/types/host-context.js

@@ -0,0 +1,142 @@
+/**
+ * Host Context — projected subset of `McpUiHostContext` ggui captures from
+ * the MCP Apps `ui/initialize` response and echoes back to session state so
+ * the agent can reason about device/host capabilities on subsequent turns.
+ *
+ * The MCP Apps spec (`@modelcontextprotocol/ext-apps`) defines a rich
+ * `McpUiHostContext` (theme, styles, displayMode, availableDisplayModes,
+ * containerDimensions, locale, timeZone, userAgent, platform,
+ * deviceCapabilities). ggui captures it iframe-side at `ui/initialize` and
+ * echoes a TRIMMED projection back over the live channel (via the
+ * `host_context_observed` outbound message) so the server can persist it on
+ * `SessionRecord.hostContext` and surface it on `ggui_handshake` /
+ * `ggui_consume` output for the agent.
+ *
+ * Why a projection rather than passthrough:
+ *
+ *   - `theme` / `styles` already flow through ggui's separate theming
+ *     pipeline (`InterfaceContext` + the theme registry). Duplicating
+ *     creates two sources of truth.
+ *   - `toolInfo` is host-loop-internal — the agent has its own toolInfo via
+ *     MCP framing.
+ *   - `userAgent` is rarely actionable; skip until a concrete use case
+ *     appears. Easy to add later (additive optional field).
+ *
+ * What the projection KEEPS:
+ *
+ *   - `availableDisplayModes` / `currentDisplayMode` — drives canvas-mode
+ *     display-mode escalation policy (see canvas-mode-detail-displaymode.md).
+ *   - `containerDimensions` — lets the agent reason about layout density
+ *     and lets the canvas reflow on resize.
+ *   - `platform` / `deviceCapabilities` — feeds the generator's
+ *     responsive-UI prompts.
+ *   - `locale` / `timeZone` — useful for the agent's date/number rendering.
+ *
+ * Compatibility posture: every field is optional. Hosts that emit a
+ * minimal `McpUiHostContext` (spec-permissible) project to an empty
+ * object; consumers MUST handle every field as possibly absent.
+ *
+ * Versioning: the wire wrapper carries `schemaVersion` so future
+ * projection widenings can be detected; this module is the canonical
+ * shape for the current schema major.
+ */
+// =============================================================================
+// Projection helper
+// =============================================================================
+/**
+ * Type guard — `value` is a non-null, non-array plain object.
+ */
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * True iff `value` is a valid `McpUiDisplayMode` literal.
+ */
+function isDisplayMode(value) {
+    return value === 'inline' || value === 'fullscreen' || value === 'pip';
+}
+/**
+ * Project a raw `McpUiHostContext` (from the spec SDK or any equivalent
+ * shape — accepts `unknown` so callers don't need to drag in the SDK
+ * just to call this) into `HostContextProjection`.
+ *
+ * Defensive: every field crosses a trust boundary. Malformed inputs
+ * (wrong types, weird shapes) drop silently to undefined for that
+ * field rather than failing the whole projection. The whole capture
+ * path is best-effort — never blocks the bootstrap.
+ *
+ * Returns `undefined` when the input is not an object at all (caller
+ * received null / array / primitive from the host). Returns an empty
+ * object when the input is an object but no recognized fields are
+ * present — the distinction lets callers tell "host emitted context
+ * with no recognized fields" from "host emitted no context."
+ */
+export function projectHostContext(raw) {
+    if (!isPlainObject(raw))
+        return undefined;
+    const out = {};
+    // displayMode
+    if (isDisplayMode(raw.displayMode)) {
+        out.currentDisplayMode = raw.displayMode;
+    }
+    // availableDisplayModes
+    if (Array.isArray(raw.availableDisplayModes)) {
+        const filtered = raw.availableDisplayModes.filter(isDisplayMode);
+        if (filtered.length > 0)
+            out.availableDisplayModes = filtered;
+    }
+    // containerDimensions
+    if (isPlainObject(raw.containerDimensions)) {
+        const dims = {};
+        const cd = raw.containerDimensions;
+        if (typeof cd.width === 'number')
+            dims.width = cd.width;
+        if (typeof cd.maxWidth === 'number')
+            dims.maxWidth = cd.maxWidth;
+        if (typeof cd.height === 'number')
+            dims.height = cd.height;
+        if (typeof cd.maxHeight === 'number')
+            dims.maxHeight = cd.maxHeight;
+        if (Object.keys(dims).length > 0)
+            out.containerDimensions = dims;
+    }
+    // platform
+    if (raw.platform === 'web' || raw.platform === 'desktop' || raw.platform === 'mobile') {
+        out.platform = raw.platform;
+    }
+    // deviceCapabilities
+    if (isPlainObject(raw.deviceCapabilities)) {
+        const dc = {};
+        const src = raw.deviceCapabilities;
+        if (typeof src.touch === 'boolean')
+            dc.touch = src.touch;
+        if (typeof src.hover === 'boolean')
+            dc.hover = src.hover;
+        if (Object.keys(dc).length > 0)
+            out.deviceCapabilities = dc;
+    }
+    // locale
+    if (typeof raw.locale === 'string' && raw.locale.length > 0) {
+        out.locale = raw.locale;
+    }
+    // timeZone
+    if (typeof raw.timeZone === 'string' && raw.timeZone.length > 0) {
+        out.timeZone = raw.timeZone;
+    }
+    return out;
+}
+/**
+ * Deep equality check for two projections. Used by the iframe-runtime
+ * to suppress no-op re-emissions when a `host-context-changed`
+ * notification arrives but no projection-visible field actually changed.
+ *
+ * JSON-stringify is sufficient because the projection contains only
+ * primitives, arrays of primitives, and plain objects of primitives.
+ */
+export function hostContextProjectionsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    return JSON.stringify(a) === JSON.stringify(b);
+}