@ggui-ai/mcp-server 0.2.0-alpha.3 → 0.2.0-alpha.4

package/dist/instructions-presets.js

@@ -83,9 +83,9 @@ const DEFAULT_PRESET_BODY = [
     '  • `ggui_consume` and `ggui_update` operate on EXISTING renders identified by `renderId` and require NO handshake. The `renderId` was minted by an earlier `ggui_render` call; it identifies the live iframe the user is interacting with. Calling `ggui_handshake` before `ggui_consume`/`ggui_update` is a category error — it would mint a SEPARATE new render that the user can\'t see, orphaning whichever live iframe the gesture targeted.',
     '  • Each `renderId` is the agent\'s persistent handle to one specific live iframe. Reuse it across consume/update for as long as the user is interacting with that UI; only call `ggui_handshake` again when you need to spawn a genuinely new UI surface.',
     '',
-    '  1. ggui_handshake — FIRST CALL for any UI. Negotiate a contract for the next render. Post {intent, blueprintDraft: {contract, variance?, generator?}}. `variance` is optional and lets you steer cache lookup + gen by axis: `persona` ("minimalist", "playful"), `aesthetic` ("dense", "spacious"), `intentContext` (free-form usage notes), `seedPrompt` (deterministic seed). Server runs BlueprintSearch + contract-validation in parallel and returns a handshakeId + suggestion (origin: cache | agent | synth). cache → blueprint already exists, render delivers it instantly. agent → novel-but-clean draft, gen runs on render. synth → your draft failed validation, server amended it; diff is on suggestion.amendments.',
+    '  1. ggui_handshake — FIRST CALL for any UI. Negotiate a contract for the next render. Post {intent, blueprintDraft: {contract, variance?, generator?}}. `variance` is optional and steers cache lookup + gen by axis: `persona` ("minimalist", "playful"), `aesthetic` ("dense", "spacious"), `seedPrompt` (deterministic seed). HANDSHAKE IS FORGIVING — it ALWAYS returns a handshakeId + a CONFORMING contract, even when your draft is malformed: the server cache-matches an existing blueprint OR repairs your draft until it passes validation. The suggestion carries origin: cache (an existing blueprint matched — delivered instantly) | agent (your draft was already clean) | synth (your draft had problems and the server repaired it; `suggestion.validationFindings` lists exactly what was wrong so you learn for next time). CRITICAL: a synth result is NOT an error and NOT a request to retry — the returned contract is READY. Accept it and call ggui_render. Do NOT re-call ggui_handshake hoping for a different origin — that is a loop that wastes turns and changes nothing.',
     '',
-    '  2. ggui_render — deliver the UI. handshakeId is REQUIRED (from step 1); calling render without it fails with `handshake_not_found`. Send {handshakeId, decision: {kind:"accept"}} to use the suggestion verbatim, OR {handshakeId, decision: {kind:"override", blueprintDraft:{...}}} to mint fresh against a new draft. If the contract declares propsSpec, props is REQUIRED. Response includes the minted `renderId` — your handle for every follow-up call. Handshake records are SINGLE-USE and expire after 10 minutes. On error: `handshake_not_found` → call ggui_handshake again. `contract_violation` (props don\'t match propsSpec) / `contract_schema_invalid` (an inner JSON Schema is malformed) / `cross_reference_unresolved` (`actionSpec[*].nextStep` or `streamSpec[*].source.tool` names a tool not in `agentCapabilities.tools`) / `schema_mismatch_error` (action schema not a subset of the named tool\'s inputSchema) / `missing_props` → fix the input and retry with the SAME handshakeId (still valid until consumed).',
+    '  2. ggui_render — deliver the UI. handshakeId is REQUIRED (from step 1); calling render without it fails with `handshake_not_found`. Send {handshakeId, decision: {kind:"accept"}} to use the handshake suggestion verbatim — THE NORMAL PATH, since the contract is already conforming — OR {handshakeId, decision: {kind:"override", blueprintDraft:{...}}} to commit to a FRESH draft of your own. OVERRIDE IS STRICT: a forced contract MUST already conform — the server does NOT repair it (override means "use mine exactly"). Prefer accept; override only when the suggestion genuinely is not what you want AND your replacement contract is correct. If the contract declares propsSpec, props is REQUIRED. Response includes the minted `renderId` — your handle for every follow-up call. Handshake records are SINGLE-USE and expire after 10 minutes. On error: `handshake_not_found` → call ggui_handshake again; `contract_violation` / `missing_props` (props don\'t match propsSpec) → fix props and retry with the SAME handshakeId; `override_contract_invalid` (your forced override draft failed validation) → drop the override, re-run ggui_handshake with that draft (which WILL repair it), and accept the suggestion — do NOT retry override with the same draft.',
     '',
     '  3. NEXT STEP — read the render response. If it carries a `nextStep` field, call that tool with the given args. Render only emits `nextStep` when the contract declared a non-empty actionSpec (i.e., the UI has interactive buttons/forms); in that case nextStep names ggui_consume and your job is to long-poll for the user\'s gesture. If the render response has NO nextStep, the UI is pure-display (props only, no actionSpec) — you can end your turn; the user reads the UI and types their next prompt when they\'re ready.',
     '',

package/dist/llm-backed-negotiator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-backed-negotiator.d.ts","sourceRoot":"","sources":["../src/llm-backed-negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAEjB,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAGL,KAAK,mBAAmB,EAExB,KAAK,2BAA2B,EAEjC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAqC,MAAM,mBAAmB,CAAC;AAmBtF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,GAAG,SAAS,CAmD9F;AA6ED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;;;OAMG;IACH,UAAU,EAAE,CACV,GAAG,EAAE,cAAc,KAEjB;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GACxD,OAAO,CAAC;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC,GACxE,IAAI,CAAC;IACT;;;OAGG;IACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;KACnC,CAAC;IACF;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;CACnD;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,gCAAgC,GACrC,mBAAmB,CA2MrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,2wDAoBgN,CAAC;AAqC7P;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,CA2CR;AA8CD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,CAyBpF"}
+{"version":3,"file":"llm-backed-negotiator.d.ts","sourceRoot":"","sources":["../src/llm-backed-negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAEjB,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAGL,KAAK,mBAAmB,EAExB,KAAK,2BAA2B,EAEjC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EACV,SAAS,EAIV,MAAM,mBAAmB,CAAC;AAmB3B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,GAAG,SAAS,CAmD9F;AA6ED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;;;OAMG;IACH,UAAU,EAAE,CACV,GAAG,EAAE,cAAc,KAEjB;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GACxD,OAAO,CAAC;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC,GACxE,IAAI,CAAC;IACT;;;OAGG;IACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;KACnC,CAAC;IACF;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;CACnD;AA6CD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,gCAAgC,GACrC,mBAAmB,CAiKrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,2wDAoBgN,CAAC;AAqC7P;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,CA2CR;AA8CD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,CAyBpF"}

package/dist/llm-backed-negotiator.js

@@ -51,7 +51,8 @@
  * infrastructure isn't bound.
  */
 import { DEFAULT_GENERATOR_SLUG, matchBlueprint, } from "@ggui-ai/mcp-server-handlers/renders";
-import { negotiate } from "@ggui-ai/negotiator";
+import { ensureConformingContract } from "@ggui-ai/negotiator";
+import { dataContractSchema, lintContract } from "@ggui-ai/protocol";
 import { blueprintKey } from "@ggui-ai/protocol/blueprint-key";
 import { selectAdapter } from "@ggui-ai/ui-gen/providers";
 import { createHash, randomUUID } from "node:crypto";
@@ -196,9 +197,22 @@ async function anthropicCallStructured(args) {
 }
 const DEFAULT_GEN_LATENCY_MS = 30_000;
 function buildCreateFallback(draftContract, reason, _estimatedLatencyMs) {
-    // Fallback path stamps an `origin: 'agent'` suggestion against the
-    // agent's draft. Gen-pending; no codeHash; provisional blueprintId.
-    const contractHash = blueprintKey(draftContract);
+    // No-LLM fallback (no BYOK creds, or an operational error during synth).
+    // The handshake backstop (validateContract) THROWS on a malformed draft,
+    // and there is no LLM here to repair it — so deterministically
+    // substitute the trivially-conforming empty contract (+ loud findings)
+    // when the draft fails the gate. NEVER return a raw malformed draft into
+    // the throwing backstop (that would revive the handshake-retry loop).
+    // A clean draft is kept verbatim (origin: agent).
+    const lint = lintContract(draftContract);
+    const contract = lint.errors.length === 0 ? dataContractSchema.parse(draftContract) : {};
+    const findings = lint.errors.map((e) => ({
+        code: e.code,
+        severity: "error",
+        path: e.path,
+        message: e.message,
+    }));
+    const contractHash = blueprintKey(contract);
     const suggestion = {
         origin: "agent",
         rationale: reason,
@@ -208,12 +222,13 @@ function buildCreateFallback(draftContract, reason, _estimatedLatencyMs) {
             generator: "ui-gen-default-haiku-4-5",
             variance: {},
         },
+        ...(findings.length > 0 ? { validationFindings: findings } : {}),
     };
     return {
         action: "create",
         reason,
         suggestion,
-        effectiveContract: draftContract,
+        effectiveContract: contract,
     };
 }
 /**
@@ -242,7 +257,12 @@ export function createLlmBackedHandshakeNegotiator(deps) {
             // — the negotiator stays useful when the registry is cold,
             // when matchBlueprint hiccups, or when the deployment skipped
             // the cache deps entirely.
-            if (deps.cache) {
+            // Cache match needs a SHAPE-VALID contract — a malformed draft
+            // (wrapper-nesting, bad type spelling, …) can't canonical-key-match
+            // a registered blueprint, so skip the probe and fall straight to
+            // validate/repair via ensureConformingContract.
+            const parsedDraft = dataContractSchema.safeParse(draftContract);
+            if (deps.cache && parsedDraft.success) {
                 try {
                     const matchDeps = {
                         registry: deps.cache,
@@ -250,7 +270,7 @@ export function createLlmBackedHandshakeNegotiator(deps) {
                     };
                     const matchResult = await matchBlueprint(matchDeps, ctx.appId, {
                         intent,
-                        contract: draftContract,
+                        contract: parsedDraft.data,
                     });
                     if (matchResult.strategy === "exact-key") {
                         const matched = matchResult.blueprint;
@@ -297,85 +317,38 @@ export function createLlmBackedHandshakeNegotiator(deps) {
             }
             try {
                 const llm = buildLlmCaller(creds.selection, creds.providerKey);
-                const declaredAgentTools = Object.keys(draftContract.agentCapabilities?.tools ?? {});
-                const synthPrompt = blueprintDraft.variance?.seedPrompt ?? intent;
-                const result = await negotiate({ llm }, {
-                    agent: {
-                        prompt: synthPrompt,
-                        ...(declaredAgentTools.length > 0 ? { agentTools: declaredAgentTools } : {}),
-                        ...(gadgets !== undefined ? { gadgets } : {}),
-                    },
-                    config: {
-                        appId: ctx.appId,
-                        // Handshake runs ahead of any concrete render — no renderId
-                        // is bound yet. The negotiator only uses `renderId` to key
-                        // its optional `readRenderState` callback, which the OSS
-                        // path doesn't wire here, so a stable placeholder works.
-                        renderId: "handshake",
-                        includeSharedPool: false,
-                    },
+                // Create path (no cache hit): the agent's DRAFT is the basis.
+                // ensureConformingContract validates it against the deterministic
+                // gate (lintContract / validateContract) and, on errors, repairs
+                // it in place via the bounded LLM loop — GUARANTEEING a contract
+                // that passes the handshake backstop, so the handshake never
+                // hard-fails on a malformed draft. origin: 'agent' = draft was
+                // already clean; 'synth' = repaired (or minimal-conforming
+                // fallback when unrepairable).
+                const conforming = await ensureConformingContract({ llm }, {
+                    intent,
+                    draft: draftContract,
+                    ...(gadgets !== undefined ? { appGadgets: gadgets } : {}),
                 });
-                const decision = result.decision;
-                const contract = decision.contract;
-                const contractHash = result.storedContractHash ?? blueprintKey(contract);
-                const draftHash = blueprintKey(draftContract);
-                const blueprintId = decision.blueprintId;
-                // Origin routing:
-                //   - blueprintId present (cache hit) → origin: 'cache'
-                //   - contract == draft               → origin: 'agent'
-                //   - contract != draft               → origin: 'synth'
-                let suggestion;
-                if (blueprintId) {
-                    suggestion = {
-                        origin: "cache",
-                        rationale: decision.reasoning ?? `cache match (${blueprintId})`,
-                        blueprintMeta: {
-                            blueprintId,
-                            contractHash,
-                            generator: "ui-gen-default-haiku-4-5",
-                            variance: {},
-                        },
-                    };
-                }
-                else if (contractHash === draftHash) {
-                    suggestion = {
-                        origin: "agent",
-                        rationale: decision.reasoning ?? "novel-but-clean contract",
-                        blueprintMeta: {
-                            blueprintId: `bp_${randomUUID()}`,
-                            contractHash,
-                            generator: "ui-gen-default-haiku-4-5",
-                            variance: {},
-                        },
-                    };
-                }
-                else {
-                    suggestion = {
-                        origin: "synth",
-                        rationale: decision.reasoning ?? "synth amended contract",
-                        blueprintMeta: {
-                            blueprintId: `bp_${randomUUID()}`,
-                            contractHash,
-                            generator: "ui-gen-default-haiku-4-5",
-                            variance: {},
-                        },
-                        amendments: {
-                            contractDiff: [
-                                {
-                                    op: "replace",
-                                    path: "",
-                                    value: contract,
-                                },
-                            ],
-                            reasoning: decision.reasoning ?? "negotiator-amended contract",
-                        },
-                    };
-                }
+                const contractHash = blueprintKey(conforming.contract);
+                const suggestion = {
+                    origin: conforming.origin,
+                    rationale: conforming.reasoning,
+                    blueprintMeta: {
+                        blueprintId: `bp_${randomUUID()}`,
+                        contractHash,
+                        generator: "ui-gen-default-haiku-4-5",
+                        variance: {},
+                    },
+                    ...(conforming.findings.length > 0
+                        ? { validationFindings: conforming.findings }
+                        : {}),
+                };
                 return {
-                    action: blueprintId ? "reuse" : "create",
-                    reason: decision.reasoning ?? "negotiated",
+                    action: "create",
+                    reason: conforming.reasoning,
                     suggestion,
-                    effectiveContract: contract,
+                    effectiveContract: conforming.contract,
                 };
             }
             catch (err) {

package/dist/mcp-apps-outbound.d.ts

@@ -34,7 +34,7 @@
 import type { RenderStore, VectorStore } from "@ggui-ai/mcp-server-core";
 import { type McpAppAiGguiRenderMeta } from "@ggui-ai/protocol/integrations/mcp-apps";
 import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const GGUI_RENDER_SHELL_HTML = "<!doctype html>\n<html lang=\"en\" style=\"height:100%\"><head><meta charset=\"utf-8\"><title>ggui render</title></head>\n<body style=\"margin:0;height:100%;min-height:480px\"><div id=\"ggui-root\" data-ggui-shell=\"thin\" style=\"height:100%;min-height:480px\"></div>\n<script>\n(function(){'use strict';\n// MCP Apps shell. Speaks the canonical postMessage protocol from\n// @modelcontextprotocol/ext-apps:\n//   1. iframe -> host: ui/initialize\n//   2. iframe -> host: ui/notifications/initialized\n//   3. host -> iframe: ui/notifications/tool-result (per CallToolResult)\n// On tool-result, read the slice envelope from _meta (spec-canonical\n// CallToolResult _meta at the top level, or the first-party\n// params.toolOutput._meta shape), set window.__GGUI_META__ to the\n// envelope, fetch runtime as blob, inject as script.\n// Runtime auto-mounts inline. No nested iframe (claudemcpcontent.com\n// CSP frame-src forbids cross-origin frames). State machine matches\n// buildSelfContainedShell so the same runtime mounts both paths.\n//\n// R5 (2026-05-26): the historic /r/<shortCode> HTTP fallback was\n// removed along with the bearer-by-obscurity model -- hosts that strip\n// _meta no longer have a recovery path here. Spec-canonical hosts\n// deliver _meta inline and are unaffected.\n//\n// Phase B (2026-05-27): the historic two-slice envelope\n// (`ai.ggui/session` + `ai.ggui/stack-item`) collapsed to ONE flat\n// `ai.ggui/render` slice. runtimeUrl now lives directly on the\n// render slice; renderId is the canonical identity.\nvar rpcId=1,pending={};\nvar rootEl=document.getElementById('ggui-root');\nrootEl.style.cssText='display:flex;flex-direction:column;height:100%;min-height:300px;margin:0';\nvar mounted=false;\nfunction setOverlay(text){\n  if(mounted)return;\n  rootEl.innerHTML='<div style=\"font:14px system-ui,sans-serif;padding:24px;color:#666\">'+text+'</div>';\n}\nfunction postNotification(method,params){\n  try{window.parent.postMessage({jsonrpc:'2.0',method:method,params:params||{}},'*');}catch(e){}\n}\nfunction postRpc(method,params){\n  return new Promise(function(res,rej){\n    var id=rpcId++;pending[id]={res:res,rej:rej};\n    try{window.parent.postMessage({jsonrpc:'2.0',id:id,method:method,params:params||{}},'*');}\n    catch(e){delete pending[id];rej(e);}\n  });\n}\nfunction postBootstrapFailed(reason,message){\n  // Surface every shell-layer bootstrap-failure path as a typed\n  // RendererBootFailedMessage envelope so hosts pinning the C9\n  // error pane (McpAppIframe onError, IframeErrorPane) see the\n  // failure instead of staring at the inert overlay until the test\n  // times out. Reason codes match BootstrapFailureReason.\n  try{window.parent.postMessage({type:'ggui:bootstrap-failed',reason:reason,message:message},'*');}catch(e){}\n}\nasync function mountFromMeta(envelope){\n  if(mounted)return;\n  // Slice envelope shape (Phase B): { \"ai.ggui/render\": { renderId,\n  // appId, runtimeUrl, ... } }. runtimeUrl on the render slice is\n  // the only load-bearing field at the shell layer \u2014 it tells us\n  // which iframe-runtime bundle to fetch. Everything else is\n  // optional; the runtime decides at boot time based on the meta\n  // it reads from window.__GGUI_META__.\n  var renderSlice=envelope&&envelope['ai.ggui/render'];\n  var runtimeUrl=renderSlice&&renderSlice.runtimeUrl;\n  if(!envelope||typeof runtimeUrl!=='string'){\n    setOverlay('Bootstrap payload malformed.');\n    postBootstrapFailed('BOOTSTRAP_MALFORMED','Bootstrap payload malformed.');\n    return;\n  }\n  setOverlay('Loading UI\u2026');\n  window.__GGUI_META__=envelope;\n  // Load the runtime bundle via a direct cross-origin script tag\n  // (governed by CSP script-src) instead of fetch + Blob (governed by\n  // CSP connect-src). claude.ai's claudemcpcontent.com iframe CSP\n  // forbids cross-origin connect-src so fetch throws TypeError\n  // 'Failed to fetch', but allows cross-origin script-src when the\n  // bundle responds with the right CORS headers (the iframe-runtime\n  // mount sets them). The self-contained shell already uses this\n  // pattern; legacy postMessage shell now matches it.\n  try{\n    var s=document.createElement('script');\n    s.type='module';\n    // crossorigin=anonymous opts into CORS-mode error reporting.\n    // Without it, cross-origin script tags get a sanitized\n    // \"script error\" with no details, masking the real cause\n    // (CSP block, CORS reject, module-evaluation throw). With it,\n    // the error event surfaces the actual message in the iframe\n    // console -- the bundle ships ACAO=* so credentialed mode is\n    // unnecessary.\n    s.crossOrigin='anonymous';\n    s.src=runtimeUrl;\n    s.onload=function(){mounted=true;};\n    s.onerror=function(e){\n      var msg='Runtime bundle failed to load: '+(e&&e.message||'script error');\n      setOverlay(msg);\n      postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);\n    };\n    rootEl.innerHTML='';\n    document.body.appendChild(s);\n  }catch(e){\n    var msg='Runtime bundle failed to load: '+(e&&e.message||e);\n    setOverlay(msg);\n    postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);\n  }\n}\nfunction readMetaFromInitResult(result){\n  if(!result||typeof result!=='object')return null;\n  var toolOutput=result.toolOutput;\n  if(!toolOutput||typeof toolOutput!=='object')return null;\n  var meta=toolOutput._meta;\n  if(!meta||typeof meta!=='object')return null;\n  // Single slice-envelope key (Phase B: ai.ggui/render). Only the\n  // render slice's runtimeUrl is load-bearing at the shell layer;\n  // the runtime reads everything else off window.__GGUI_META__\n  // after we set it.\n  var renderSlice=meta['ai.ggui/render'];\n  if(!renderSlice||typeof renderSlice!=='object')return null;\n  if(typeof renderSlice.runtimeUrl!=='string')return null;\n  return meta;\n}\nfunction hasAiGguiMetaPlaceholder(result){\n  // Detect the protocol-violation case where the host signaled\n  // \"I tried to deliver meta\" (toolOutput._meta carries an\n  // ai.ggui/render key) but it's malformed. Fail-fast with\n  // BOOTSTRAP_META_MISSING rather than waiting forever.\n  if(!result||typeof result!=='object')return false;\n  var toolOutput=result.toolOutput;\n  if(!toolOutput||typeof toolOutput!=='object')return false;\n  var meta=toolOutput._meta;\n  if(!meta||typeof meta!=='object')return false;\n  return 'ai.ggui/render' in meta;\n}\nfunction readMetaFromCallToolResult(params){\n  // MCP Apps spec (specification/2026-01-26/apps.mdx:1145-1155):\n  //   ui/notifications/tool-result\n  //   params: CallToolResult  // Standard MCP type\n  // So params IS the CallToolResult and _meta lives at the top\n  // level (NOT under params.toolOutput, which is where the\n  // first-party McpAppIframe convention wraps it). Spec-compliant\n  // hosts (Claude Desktop, claude.ai Connector, Claude Code) deliver\n  // slice-envelope material here.\n  if(!params||typeof params!=='object')return null;\n  var meta=params._meta;\n  if(!meta||typeof meta!=='object')return null;\n  var renderSlice=meta['ai.ggui/render'];\n  if(!renderSlice||typeof renderSlice!=='object')return null;\n  if(typeof renderSlice.runtimeUrl!=='string')return null;\n  return meta;\n}\nwindow.addEventListener('message',function(ev){\n  var m=ev&&ev.data;\n  if(!m||m.jsonrpc!=='2.0')return;\n  if(m.id!=null&&pending[m.id]){\n    var p=pending[m.id];delete pending[m.id];\n    if(m.error)p.rej(m.error);else p.res(m.result);\n    return;\n  }\n  if(m.method==='ui/notifications/tool-result'){\n    // Spec-compliant hosts: m.params IS the CallToolResult; _meta is\n    // at the top level. Try this FIRST so Claude Desktop / claude.ai\n    // Connector / Claude Code land here.\n    var specB=readMetaFromCallToolResult(m.params);\n    if(specB){mountFromMeta(specB);return;}\n    // First-party McpAppIframe convention: slice envelope nested under\n    // params.toolOutput._meta. First-party hosts (Studio, Portal,\n    // console) use this shape for both init-response and post-init\n    // notification.\n    var bb=readMetaFromInitResult(m.params);\n    if(bb){mountFromMeta(bb);return;}\n    // R5 (2026-05-26) -- the /r/<shortCode> HTTP fallback was removed\n    // along with the bearer-by-obscurity model. Hosts that strip\n    // _meta on the tool-result wire have no fallback path here;\n    // spec-canonical hosts deliver meta inline and land in the two\n    // branches above.\n  }\n});\nsetOverlay('Initializing\u2026');\nvar initTimer=setTimeout(function(){\n  setOverlay('Host did not respond to ui/initialize within 3s.');\n},3000);\npostRpc('ui/initialize',{\n  appCapabilities:{},\n  appInfo:{name:'ggui-session',version:'1.0.0'},\n  protocolVersion:'2026-01-26'\n}).then(function(result){\n  clearTimeout(initTimer);\n  postNotification('ui/notifications/initialized',{});\n  // Path B: slice envelope inline in ui/initialize result. Hosts\n  // using <McpAppIframe>'s first-party dispatch deliver meta here\n  // and never send a separate ui/notifications/tool-result.\n  var b=readMetaFromInitResult(result);\n  if(b){mountFromMeta(b);return;}\n  // Protocol-violation surface: host signalled an attempt\n  // (toolOutput._meta carries ai.ggui/render) but it's malformed.\n  // Fail fast so hosts pinning a typed error envelope don't sit on\n  // the Path-A waiting overlay forever.\n  if(hasAiGguiMetaPlaceholder(result)){\n    var msg='ui/initialize result missing valid ai.ggui/render.runtimeUrl';\n    setOverlay(msg);\n    postBootstrapFailed('BOOTSTRAP_META_MISSING',msg);\n    return;\n  }\n  // Path A: wait for the host to send ui/notifications/tool-result\n  // with structuredContent.{url, shortCode}. MCP Apps hosts that don't\n  // implement the reading-B inline-meta convention land here.\n  setOverlay('Waiting for tool result\u2026');\n}).catch(function(e){\n  clearTimeout(initTimer);\n  setOverlay('ui/initialize failed: '+(e&&e.message||JSON.stringify(e)));\n});\n})();\n</script></body></html>";
+export declare const GGUI_RENDER_SHELL_HTML = "<!doctype html>\n<html lang=\"en\" style=\"height:100%;background-color:var(--ggui-color-surface, #1e293b)\"><head><meta charset=\"utf-8\"><title>ggui render</title></head>\n<body style=\"margin:0;height:100%;min-height:480px;background-color:var(--ggui-color-surface, #1e293b)\"><div id=\"ggui-root\" data-ggui-shell=\"thin\" style=\"height:100%;min-height:480px\"></div>\n<script>\n(function(){'use strict';\n// MCP Apps shell. Speaks the canonical postMessage protocol from\n// @modelcontextprotocol/ext-apps:\n//   1. iframe -> host: ui/initialize\n//   2. iframe -> host: ui/notifications/initialized\n//   3. host -> iframe: ui/notifications/tool-result (per CallToolResult)\n// On tool-result, read the slice envelope from _meta (spec-canonical\n// CallToolResult _meta at the top level, or the first-party\n// params.toolOutput._meta shape), set window.__GGUI_META__ to the\n// envelope, fetch runtime as blob, inject as script.\n// Runtime auto-mounts inline. No nested iframe (claudemcpcontent.com\n// CSP frame-src forbids cross-origin frames). State machine matches\n// buildSelfContainedShell so the same runtime mounts both paths.\n//\n// R5 (2026-05-26): the historic /r/<shortCode> HTTP fallback was\n// removed along with the bearer-by-obscurity model -- hosts that strip\n// _meta no longer have a recovery path here. Spec-canonical hosts\n// deliver _meta inline and are unaffected.\n//\n// Phase B (2026-05-27): the historic two-slice envelope\n// (`ai.ggui/session` + `ai.ggui/stack-item`) collapsed to ONE flat\n// `ai.ggui/render` slice. runtimeUrl now lives directly on the\n// render slice; renderId is the canonical identity.\nvar rpcId=1,pending={};\nvar rootEl=document.getElementById('ggui-root');\nrootEl.style.cssText='display:flex;flex-direction:column;height:100%;min-height:300px;margin:0';\nvar mounted=false;\nfunction setOverlay(text){\n  if(mounted)return;\n  rootEl.innerHTML='<div style=\"font:14px system-ui,sans-serif;padding:24px;color:#666\">'+text+'</div>';\n}\nfunction postNotification(method,params){\n  try{window.parent.postMessage({jsonrpc:'2.0',method:method,params:params||{}},'*');}catch(e){}\n}\nfunction postRpc(method,params){\n  return new Promise(function(res,rej){\n    var id=rpcId++;pending[id]={res:res,rej:rej};\n    try{window.parent.postMessage({jsonrpc:'2.0',id:id,method:method,params:params||{}},'*');}\n    catch(e){delete pending[id];rej(e);}\n  });\n}\nfunction postBootstrapFailed(reason,message){\n  // Surface every shell-layer bootstrap-failure path as a typed\n  // RendererBootFailedMessage envelope so hosts pinning the C9\n  // error pane (McpAppIframe onError, IframeErrorPane) see the\n  // failure instead of staring at the inert overlay until the test\n  // times out. Reason codes match BootstrapFailureReason.\n  try{window.parent.postMessage({type:'ggui:bootstrap-failed',reason:reason,message:message},'*');}catch(e){}\n}\nasync function mountFromMeta(envelope){\n  if(mounted)return;\n  // Slice envelope shape (Phase B): { \"ai.ggui/render\": { renderId,\n  // appId, runtimeUrl, ... } }. runtimeUrl on the render slice is\n  // the only load-bearing field at the shell layer \u2014 it tells us\n  // which iframe-runtime bundle to fetch. Everything else is\n  // optional; the runtime decides at boot time based on the meta\n  // it reads from window.__GGUI_META__.\n  var renderSlice=envelope&&envelope['ai.ggui/render'];\n  var runtimeUrl=renderSlice&&renderSlice.runtimeUrl;\n  if(!envelope||typeof runtimeUrl!=='string'){\n    setOverlay('Bootstrap payload malformed.');\n    postBootstrapFailed('BOOTSTRAP_MALFORMED','Bootstrap payload malformed.');\n    return;\n  }\n  setOverlay('Loading UI\u2026');\n  window.__GGUI_META__=envelope;\n  // Load the runtime bundle via a direct cross-origin script tag\n  // (governed by CSP script-src) instead of fetch + Blob (governed by\n  // CSP connect-src). claude.ai's claudemcpcontent.com iframe CSP\n  // forbids cross-origin connect-src so fetch throws TypeError\n  // 'Failed to fetch', but allows cross-origin script-src when the\n  // bundle responds with the right CORS headers (the iframe-runtime\n  // mount sets them). The self-contained shell already uses this\n  // pattern; legacy postMessage shell now matches it.\n  try{\n    var s=document.createElement('script');\n    s.type='module';\n    // crossorigin=anonymous opts into CORS-mode error reporting.\n    // Without it, cross-origin script tags get a sanitized\n    // \"script error\" with no details, masking the real cause\n    // (CSP block, CORS reject, module-evaluation throw). With it,\n    // the error event surfaces the actual message in the iframe\n    // console -- the bundle ships ACAO=* so credentialed mode is\n    // unnecessary.\n    s.crossOrigin='anonymous';\n    s.src=runtimeUrl;\n    s.onload=function(){mounted=true;};\n    s.onerror=function(e){\n      var msg='Runtime bundle failed to load: '+(e&&e.message||'script error');\n      setOverlay(msg);\n      postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);\n    };\n    rootEl.innerHTML='';\n    document.body.appendChild(s);\n  }catch(e){\n    var msg='Runtime bundle failed to load: '+(e&&e.message||e);\n    setOverlay(msg);\n    postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);\n  }\n}\nfunction readMetaFromInitResult(result){\n  if(!result||typeof result!=='object')return null;\n  var toolOutput=result.toolOutput;\n  if(!toolOutput||typeof toolOutput!=='object')return null;\n  var meta=toolOutput._meta;\n  if(!meta||typeof meta!=='object')return null;\n  // Single slice-envelope key (Phase B: ai.ggui/render). Only the\n  // render slice's runtimeUrl is load-bearing at the shell layer;\n  // the runtime reads everything else off window.__GGUI_META__\n  // after we set it.\n  var renderSlice=meta['ai.ggui/render'];\n  if(!renderSlice||typeof renderSlice!=='object')return null;\n  if(typeof renderSlice.runtimeUrl!=='string')return null;\n  return meta;\n}\nfunction hasAiGguiMetaPlaceholder(result){\n  // Detect the protocol-violation case where the host signaled\n  // \"I tried to deliver meta\" (toolOutput._meta carries an\n  // ai.ggui/render key) but it's malformed. Fail-fast with\n  // BOOTSTRAP_META_MISSING rather than waiting forever.\n  if(!result||typeof result!=='object')return false;\n  var toolOutput=result.toolOutput;\n  if(!toolOutput||typeof toolOutput!=='object')return false;\n  var meta=toolOutput._meta;\n  if(!meta||typeof meta!=='object')return false;\n  return 'ai.ggui/render' in meta;\n}\nfunction readMetaFromCallToolResult(params){\n  // MCP Apps spec (specification/2026-01-26/apps.mdx:1145-1155):\n  //   ui/notifications/tool-result\n  //   params: CallToolResult  // Standard MCP type\n  // So params IS the CallToolResult and _meta lives at the top\n  // level (NOT under params.toolOutput, which is where the\n  // first-party McpAppIframe convention wraps it). Spec-compliant\n  // hosts (Claude Desktop, claude.ai Connector, Claude Code) deliver\n  // slice-envelope material here.\n  if(!params||typeof params!=='object')return null;\n  var meta=params._meta;\n  if(!meta||typeof meta!=='object')return null;\n  var renderSlice=meta['ai.ggui/render'];\n  if(!renderSlice||typeof renderSlice!=='object')return null;\n  if(typeof renderSlice.runtimeUrl!=='string')return null;\n  return meta;\n}\nwindow.addEventListener('message',function(ev){\n  var m=ev&&ev.data;\n  if(!m||m.jsonrpc!=='2.0')return;\n  if(m.id!=null&&pending[m.id]){\n    var p=pending[m.id];delete pending[m.id];\n    if(m.error)p.rej(m.error);else p.res(m.result);\n    return;\n  }\n  if(m.method==='ui/notifications/tool-result'){\n    // Spec-compliant hosts: m.params IS the CallToolResult; _meta is\n    // at the top level. Try this FIRST so Claude Desktop / claude.ai\n    // Connector / Claude Code land here.\n    var specB=readMetaFromCallToolResult(m.params);\n    if(specB){mountFromMeta(specB);return;}\n    // First-party McpAppIframe convention: slice envelope nested under\n    // params.toolOutput._meta. First-party hosts (Studio, Portal,\n    // console) use this shape for both init-response and post-init\n    // notification.\n    var bb=readMetaFromInitResult(m.params);\n    if(bb){mountFromMeta(bb);return;}\n    // R5 (2026-05-26) -- the /r/<shortCode> HTTP fallback was removed\n    // along with the bearer-by-obscurity model. Hosts that strip\n    // _meta on the tool-result wire have no fallback path here;\n    // spec-canonical hosts deliver meta inline and land in the two\n    // branches above.\n  }\n});\nsetOverlay('Initializing\u2026');\nvar initTimer=setTimeout(function(){\n  setOverlay('Host did not respond to ui/initialize within 3s.');\n},3000);\npostRpc('ui/initialize',{\n  appCapabilities:{},\n  appInfo:{name:'ggui-session',version:'1.0.0'},\n  protocolVersion:'2026-01-26'\n}).then(function(result){\n  clearTimeout(initTimer);\n  postNotification('ui/notifications/initialized',{});\n  // Path B: slice envelope inline in ui/initialize result. Hosts\n  // using <McpAppIframe>'s first-party dispatch deliver meta here\n  // and never send a separate ui/notifications/tool-result.\n  var b=readMetaFromInitResult(result);\n  if(b){mountFromMeta(b);return;}\n  // Protocol-violation surface: host signalled an attempt\n  // (toolOutput._meta carries ai.ggui/render) but it's malformed.\n  // Fail fast so hosts pinning a typed error envelope don't sit on\n  // the Path-A waiting overlay forever.\n  if(hasAiGguiMetaPlaceholder(result)){\n    var msg='ui/initialize result missing valid ai.ggui/render.runtimeUrl';\n    setOverlay(msg);\n    postBootstrapFailed('BOOTSTRAP_META_MISSING',msg);\n    return;\n  }\n  // Path A: wait for the host to send ui/notifications/tool-result\n  // with structuredContent.{url, shortCode}. MCP Apps hosts that don't\n  // implement the reading-B inline-meta convention land here.\n  setOverlay('Waiting for tool result\u2026');\n}).catch(function(e){\n  clearTimeout(initTimer);\n  setOverlay('ui/initialize failed: '+(e&&e.message||JSON.stringify(e)));\n});\n})();\n</script></body></html>";
 /**
  * CSP `script-src` source expression that authorises the inline
  * `<script>` block of {@link GGUI_RENDER_SHELL_HTML} when it executes

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

@@ -1 +1 @@
-{"version":3,"file":"mcp-apps-outbound.d.ts","sourceRoot":"","sources":["../src/mcp-apps-outbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAWzE,OAAO,EAML,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAuS3F,eAAO,MAAM,sBAAsB,mwTAG6B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAEtB,CAAC;AAgFvB,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,EACjB,SAAS,GAAE,MAA+B,EAC1C,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAwEN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAMpE;AAyCD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,sBAAsB,CAAC,kBAAkB,CAAC,CAAC;IACvE;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IACrE;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC,cAAc,CAAC,CAAC;IAC/D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;IACrD;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC,cAAc,CAAC,CAAC;IAC/D;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;IACjE;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACzD;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC,cAAc,CAAC,CAAC;IAC/D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,CAmI9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUvE;AAED;;;;GAIG;AACH,MAAM,WAAW,iCAAiC;IAChD;yBACqB;IACrB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,0BAA0B,EAAE,SAAS,CAAC;IAClE;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,0BAA0B,EAAE,gBAAgB,CAAC;IAChF;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,KACV;QACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAkED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,iCAAiC,GACtC,IAAI,CAuTN;AAsHD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE;IACJ,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAC3D;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAC5B,GACL,IAAI,CAMN"}
+{"version":3,"file":"mcp-apps-outbound.d.ts","sourceRoot":"","sources":["../src/mcp-apps-outbound.ts"],"names":[],"mappings":"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"}

package/dist/mcp-apps-outbound.js

@@ -327,9 +327,40 @@ postRpc('ui/initialize',{
 });
 })();
 `;
+// `--ggui-color-surface` is injected at `:root` on this document's
+// `<head>` by the iframe-runtime at boot (react-renderer.ts ->
+// `<style id="ggui-theme-vars">`), so the `var()` resolves to the
+// active theme's exact per-mode surface color at runtime. The static
+// `#1e293b` fallback (the dark-mode surface) covers the pre-resolve
+// first paint + browsers that drop unresolved custom properties.
+//
+// # Why paint the document background here (Safari white-canvas fix)
+//
+// This shell is ALWAYS the **top-level document of a standalone served
+// iframe** (`ui://ggui/render`, the `/r/<shortCode>` viewer, the
+// sandbox-proxy inner-iframe `srcdoc`). It is NEVER inlined into a host
+// page — the host wrapper (`<McpAppIframe>`) only ever loads it AS an
+// iframe document, never as part of its own DOM. So painting `html` /
+// `body` here is structurally unreachable by inline embedding and
+// cannot impose a background on a host page.
+//
+// The design scope root (`.ggui-rcr-*`) and the sandbox-proxy outer
+// document stay `background-color: transparent` by design (so a host
+// themeing the chat surface shows through AROUND the rendered content).
+// But nothing painted the rendered-content document's OWN backdrop:
+// Chrome composited the transparent iframe document over the dark host
+// app behind it (looked dark), while Safari renders a transparent
+// iframe document's backdrop as the opaque UA `Canvas` color (white) —
+// the per-browser divergence the bug reported. The component itself
+// themed correctly (its scoped vars resolve); only the page behind it
+// diverged. Painting the served document's own surface here removes the
+// dependency on a browser honoring iframe transparency.
+//
+// Value-resolution only — no `--ggui-*` token added or renamed.
+const GGUI_RENDER_SHELL_SURFACE = `var(--ggui-color-surface, #1e293b)`;
 export const GGUI_RENDER_SHELL_HTML = `<!doctype html>
-<html lang="en" style="height:100%"><head><meta charset="utf-8"><title>ggui render</title></head>
-<body style="margin:0;height:100%;min-height:480px"><div id="ggui-root" data-ggui-shell="thin" style="height:100%;min-height:480px"></div>
+<html lang="en" style="height:100%;background-color:${GGUI_RENDER_SHELL_SURFACE}"><head><meta charset="utf-8"><title>ggui render</title></head>
+<body style="margin:0;height:100%;min-height:480px;background-color:${GGUI_RENDER_SHELL_SURFACE}"><div id="ggui-root" data-ggui-shell="thin" style="height:100%;min-height:480px"></div>
 <script>${GGUI_RENDER_SHELL_SCRIPT_BODY}</script></body></html>`;
 /**
  * CSP `script-src` source expression that authorises the inline
@@ -657,9 +688,19 @@ export function buildSelfContainedShell(opts) {
         .replace(/"/g, "&quot;")
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
+    // Standalone served-iframe document — paint its own surface backdrop
+    // so the canvas behind the rendered component never depends on a
+    // browser honoring iframe transparency (the Safari white-canvas bug).
+    // Same gating rationale as `GGUI_RENDER_SHELL_HTML`: this is ALWAYS a
+    // top-level iframe document (the `__GGUI_META__` self-contained shell
+    // for claude.ai / per-render resource shells), never inlined into a
+    // host page, so painting `html`/`body` here cannot regress inline
+    // embedding. `var(--ggui-color-surface, …)` resolves to the active
+    // theme's per-mode surface once the iframe-runtime injects the `:root`
+    // theme vars; the static dark fallback covers pre-resolve paint.
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><title>ggui render</title></head>
-<body>
+<html lang="en" style="background-color:${GGUI_RENDER_SHELL_SURFACE}"><head><meta charset="utf-8"><title>ggui render</title></head>
+<body style="background-color:${GGUI_RENDER_SHELL_SURFACE}">
 <div id="ggui-root" data-ggui-shell="self-contained"></div>
 <script>window.__GGUI_META__ = ${json};</script>
 <script type="module" crossorigin="anonymous" src="${safeRuntimeUrl}"></script>
@@ -679,9 +720,12 @@ export function buildSelfContainedShell(opts) {
  * @public
  */
 export function buildSelfContainedLoadingShell(renderId) {
+    // Standalone served-iframe loading document — same surface-backdrop
+    // paint + gating as the thin/self-contained shells so the canvas is
+    // dark while the render is still in flight (no Safari white flash).
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><title>ggui render</title></head>
-<body>
+<html lang="en" style="background-color:${GGUI_RENDER_SHELL_SURFACE}"><head><meta charset="utf-8"><title>ggui render</title></head>
+<body style="background-color:${GGUI_RENDER_SHELL_SURFACE}">
 <div id="ggui-root" data-ggui-shell="loading" data-ggui-render-id="${renderId
         .replace(/&/g, "&amp;")
         .replace(/"/g, "&quot;")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/mcp-server",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.4",
   "description": "Self-hosted MCP server for the ggui protocol. An HTTP/MCP binding layer over @ggui-ai/mcp-server-handlers and the reference adapters from @ggui-ai/mcp-server-core — run it via `ggui serve`.",
   "keywords": [
     "ggui",
@@ -32,16 +32,16 @@
     "resend": "^6.12.2",
     "ws": "^8.20.1",
     "zod": "^4.3.6",
-    "@ggui-ai/console": "0.2.0-alpha.3",
-    "@ggui-ai/mcp-server-core": "0.2.0-alpha.3",
-    "@ggui-ai/mcp-server-handlers": "0.2.0-alpha.3",
-    "@ggui-ai/iframe-runtime": "0.2.0-alpha.3",
-    "@ggui-ai/negotiator": "0.2.0-alpha.3",
-    "@ggui-ai/preview-a2ui": "0.2.0-alpha.3",
-    "@ggui-ai/project-config": "0.2.0-alpha.3",
-    "@ggui-ai/protocol": "0.2.0-alpha.3",
-    "@ggui-ai/ui-gen": "0.2.0-alpha.3",
-    "@ggui-ai/ui-registry": "0.2.0-alpha.3"
+    "@ggui-ai/console": "0.2.0-alpha.4",
+    "@ggui-ai/mcp-server-core": "0.2.0-alpha.4",
+    "@ggui-ai/iframe-runtime": "0.2.0-alpha.4",
+    "@ggui-ai/mcp-server-handlers": "0.2.0-alpha.4",
+    "@ggui-ai/negotiator": "0.2.0-alpha.4",
+    "@ggui-ai/preview-a2ui": "0.2.0-alpha.4",
+    "@ggui-ai/project-config": "0.2.0-alpha.4",
+    "@ggui-ai/protocol": "0.2.0-alpha.4",
+    "@ggui-ai/ui-gen": "0.2.0-alpha.4",
+    "@ggui-ai/ui-registry": "0.2.0-alpha.4"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",