@ggui-ai/mcp-server 0.8.0 → 0.10.0

package/dist/build-mcp.d.ts

@@ -60,6 +60,16 @@ export interface BuildMcpServerOptions {
      * host that owns the iframe CSP itself.
      */
     readonly publicBaseUrl?: string;
+    /**
+     * Live-channel origins for the static shell's CSP declaration —
+     * forwarded to `installMcpAppsOutbound`. Deployments that set no
+     * `publicBaseUrl` (the cloud pod) pass their `wsUrl` + its ws→http
+     * origin flip here so the mounted iframe's `connect-src` covers the
+     * SSE / HTTP-polling session API and the WebSocket; otherwise
+     * cross-origin hosts CSP-block every network rung of the failover
+     * ladder (#471 round 11).
+     */
+    readonly extraConnectUrls?: readonly (string | undefined)[];
     /**
      * Identity-kind allowlist for tool registration. When set, handlers
      * whose `allowedFor` field is non-empty AND does NOT intersect this
@@ -116,13 +126,44 @@ export interface BuildMcpServerOptions {
      * `resources/read` later.
      */
     readonly extraResources?: ReadonlyArray<(server: McpServer) => void>;
+    /**
+     * Withhold every handler's per-result bootstrap MATERIAL from tool
+     * results — the read-plane-only posture.
+     *
+     * By default a successful tool result carries the handler's
+     * `resultMeta` — for `ggui_render` / `ggui_update` that is the
+     * `ai.ggui/render` bootstrap a host may mount DIRECTLY without any
+     * further round-trip, plus the spec-canonical pointer `_meta.ui.
+     * resourceUri`. Setting this makes the server publish only the
+     * durable IDENTITY: `structuredContent.resourceUri` (the `ui://`
+     * locator) and — the same value, on the wire slot MCP Apps hosts
+     * read — `_meta.ui.resourceUri` (+ the legacy flat `ui/resourceUri`).
+     * `resultMeta` is never invoked (no bootstrap token is minted for a
+     * slice nobody receives); the pointer is derived from the validated
+     * OUTPUT itself, the single source of truth `resultMeta` reuses.
+     * A host MUST resolve every view by an authenticated `resources/read`
+     * — the persisted-locator path — before it can mount anything.
+     *
+     * Why the pointer stays (ggui#537): the identity IS the pointer.
+     * Spec-canonical hosts (claude.ai, Claude Desktop, `@ggui-ai/
+     * mcp-apps-react`'s chat-helpers, the OSS samples) mount the
+     * per-render self-contained shell that `_meta.ui.resourceUri` names —
+     * a `resources/read` the HOST performs, exactly the read-plane path
+     * this posture wants. The first arm (f8c93405d) stripped `_meta`
+     * wholesale, which took the pointer with it and left every such host
+     * with the declaration-level static shell and a result it could not
+     * mount from ("Waiting for tool result…", prod 2026-08-16→17).
+     *
+     * That is a deployment posture, not a debug switch: a hosted
+     * deployment that wants "views mount only through the read plane"
+     * (thread-scoped ownership checks, fresh per-read credentials, no
+     * inlined bootstrap material crossing a chat transcript) states it
+     * here by construction, and any host that still expects the inlined
+     * bootstrap fails loudly (a locator it cannot resolve) instead of
+     * silently mounting stale material. `structuredContent` and `content`
+     * are untouched; only `_meta` is withheld.
+     */
+    readonly withholdResultMeta?: boolean;
 }
-/**
- * Build a fresh MCP server with every handler registered.
- *
- * `getContext` is a late-binding accessor so the HTTP layer can thread
- * per-request context (via AsyncLocalStorage or a closure) without
- * leaking the shape into this module.
- */
 export declare function buildMcpServer(info: ServerInfo, handlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>, getContext: () => HandlerContext, logger: Logger, opts?: BuildMcpServerOptions): McpServer;
 //# sourceMappingURL=build-mcp.d.ts.map

package/dist/build-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-mcp.d.ts","sourceRoot":"","sources":["../src/build-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAC3D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC;CACtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAChE,UAAU,EAAE,MAAM,cAAc,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,SAAS,CAqLX"}
+{"version":3,"file":"build-mcp.d.ts","sourceRoot":"","sources":["../src/build-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAC3D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAC5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC;IAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAyBD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAChE,UAAU,EAAE,MAAM,cAAc,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,SAAS,CAwPX"}

package/dist/build-mcp.js

@@ -13,6 +13,7 @@ import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
 import { isRecord } from '@ggui-ai/protocol';
 import { z } from 'zod';
 import { isHandlerFailure, } from '@ggui-ai/mcp-server-handlers';
+import { GGUI_RENDER_RESOURCE_URI } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { installMcpAppsOutbound, } from './mcp-apps-outbound.js';
 /**
  * Build a fresh MCP server with every handler registered.
@@ -21,6 +22,23 @@ import { installMcpAppsOutbound, } from './mcp-apps-outbound.js';
  * per-request context (via AsyncLocalStorage or a closure) without
  * leaking the shape into this module.
  */
+/**
+ * The identity-only `_meta` a withholding server publishes (ggui#537):
+ * when the validated output carries a `ui://` `resourceUri` (the durable
+ * locator `ggui_render` / `ggui_update` surface on structuredContent),
+ * mirror it onto the spec-canonical `_meta.ui.resourceUri` slot MCP
+ * Apps hosts read (+ the legacy flat key), and nothing else. Same value
+ * `resultMeta` would have stamped, without invoking it — no bootstrap
+ * material, no minted token. `undefined` for outputs without a locator.
+ */
+function identityPointerMeta(validated) {
+    if (!isRecord(validated))
+        return undefined;
+    const uri = validated['resourceUri'];
+    if (typeof uri !== 'string' || !uri.startsWith('ui://'))
+        return undefined;
+    return { ui: { resourceUri: uri }, 'ui/resourceUri': uri };
+}
 export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
     const server = new McpServer({
         name: info.name,
@@ -28,8 +46,13 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
         ...(info.description ? { description: info.description } : {}),
         ...(opts.instructions ? { instructions: opts.instructions } : {}),
     });
+    // Content-addressed shell URI (stale-shell bust) — when MCP Apps
+    // outbound wiring registers the shell, declarations advertising the
+    // BARE `ui://ggui/render` are rewritten to the versioned twin below
+    // so host prefetch caches key on content, not on a constant string.
+    let shellResourceUri;
     if (opts.mcpAppsOutbound) {
-        installMcpAppsOutbound(server, {
+        ({ shellResourceUri } = installMcpAppsOutbound(server, {
             ...(opts.shellHtml !== undefined ? { shellHtml: opts.shellHtml } : {}),
             // Thread the same per-request context accessor + logger the tool
             // path uses (`getContext`, param 3 of `buildMcpServer`) so the
@@ -41,7 +64,10 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
             ...(opts.publicBaseUrl !== undefined
                 ? { publicBaseUrl: opts.publicBaseUrl }
                 : {}),
-        });
+            ...(opts.extraConnectUrls !== undefined
+                ? { extraConnectUrls: opts.extraConnectUrls }
+                : {}),
+        }));
     }
     // Per-request resource registrars supplied by the host. Run BEFORE
     // tool registration so `tools/list` ordering is unaffected and any
@@ -119,17 +145,64 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
                 const validated = z.object(handler.outputSchema).parse(data);
                 // Per-result `_meta` — NOT merged into structuredContent, so
                 // agents that typecheck against the tool signature never see
-                // it. This is where view-only bootstrap material lives.
-                const meta = await handler.resultMeta?.(data, input, ctx);
+                // it. This is where view-only bootstrap material lives. Under
+                // the withhold posture only the identity pointer is published,
+                // derived from the output (see `withholdResultMeta`).
+                const meta = opts.withholdResultMeta === true
+                    ? identityPointerMeta(validated)
+                    : await handler.resultMeta?.(data, input, ctx);
                 logger.info('tool_invoked', {
                     tool: handler.name,
                     appId: ctx.appId,
                     outcome: 'success',
                     elapsedMs: Date.now() - start,
                 });
+                // When the handler's output carries a `nextStep`, lead the
+                // model-visible content with the imperative in PLAIN TEXT.
+                // Burying the chain cue inside the JSON block proved fragile
+                // on live hosts (the first claude.ai #471 test: the agent
+                // rendered, never noticed `nextStep`, ended its turn, and the
+                // user's click had no listener). The JSON stays second —
+                // structured consumers read `structuredContent` anyway.
+                const nextStepHint = validated !== null &&
+                    typeof validated === 'object' &&
+                    'nextStep' in validated &&
+                    validated.nextStep &&
+                    typeof validated.nextStep
+                        .example === 'string'
+                    ? validated.nextStep.example
+                    : undefined;
+                // The gesture-poll wrapper below describes ggui_consume's
+                // semantics ("catch an immediate gesture", "waits up to 25s")
+                // — it is ONLY true when the nextStep IS the consume hint.
+                // Ungated, it decorated ggui_handshake results too (whose
+                // nextStep is a ggui_render example), telling agents a
+                // not-yet-rendered UI "has interactive actions" — a live agent
+                // flagged the contradiction against an actions=∅ contract
+                // (2026-08-12).
+                const gestureHint = nextStepHint !== undefined && nextStepHint.includes('ggui_consume')
+                    ? nextStepHint
+                    : undefined;
                 return {
                     structuredContent: validated,
                     content: [
+                        ...(gestureHint !== undefined
+                            ? [
+                                {
+                                    type: 'text',
+                                    // Gentle + bounded, deliberately: a forcing
+                                    // imperative hijacked live agents into polling
+                                    // instead of acting (matrix scenario 6), and an
+                                    // unbounded "re-call on empty" looped them past
+                                    // their turn budget. The poll is a latency
+                                    // optimization, not the delivery guarantee — when
+                                    // nobody is polling, a gesture rings the chat via
+                                    // ui/message and arrives as a new user message
+                                    // carrying its own consume directive.
+                                    text: `The UI has interactive actions. After this turn's work, you may call ${gestureHint} once to catch an immediate gesture (waits up to 25s); if events is empty, end your turn — later gestures arrive as new user messages.`,
+                                },
+                            ]
+                            : []),
                         { type: 'text', text: JSON.stringify(validated) },
                     ],
                     ...(meta !== undefined ? { _meta: meta } : {}),
@@ -164,11 +237,19 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
         // error on the handler author's side — fail loud rather than
         // silently registering the tool without its UI surface.
         if (handler._meta && 'ui' in handler._meta) {
-            const ui = handler._meta['ui'];
-            if (!isMcpUiToolMeta(ui)) {
+            const uiRaw = handler._meta['ui'];
+            if (!isMcpUiToolMeta(uiRaw)) {
                 throw new Error(`Tool ${handler.name} declares _meta.ui with an invalid shape — ` +
                     `expected { resourceUri?: string; visibility?: ('model' | 'app')[] }.`);
             }
+            // Declarations author the STABLE `ui://ggui/render` constant;
+            // registration swaps in the content-addressed twin so hosts
+            // prefetch (and cache) the shell by its content hash. Handlers
+            // stay host-cache-agnostic; the swap lives in ONE place.
+            const ui = shellResourceUri !== undefined &&
+                uiRaw.resourceUri === GGUI_RENDER_RESOURCE_URI
+                ? { ...uiRaw, resourceUri: shellResourceUri }
+                : uiRaw;
             registerAppTool(server, handler.name, {
                 ...baseConfig,
                 _meta: { ...handler._meta, ui },

package/dist/code-module-variant.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Strict-CSP module-variant delivery (ggui#522 slice 2).
+ *
+ * The `/code/<hash>.js` route serves STORED component bytes — compiled
+ * ESM whose imports are still BARE specifiers (`react`,
+ * `@ggui-ai/design/primitives`, …). A browser cannot import that
+ * standalone; the renderer historically bridged the gap in-frame by
+ * rewriting bare specifiers to `data:` shims and instantiating the
+ * module from a `blob:` URL — both of which a strict host CSP refuses.
+ *
+ * This module adds the server-side twin of that bridge: a SECOND,
+ * immutable route `/code/<hash>.m<rt>.js` serving the SAME stored bytes
+ * with the rewrite already applied — every bare specifier resolved to a
+ * static shim asset under `/_ggui/shims/<rt>/<name>.js` on the same
+ * origin. A frame whose `script-src` allows only the asset origin can
+ * `import()` the variant URL directly: no `blob:`, no `data:`, no
+ * `'unsafe-eval'`.
+ *
+ * `<rt>` — the 12-hex content hash of the runtime bundle — is the
+ * variant KEY, and it lives in the PATH deliberately: the asset CDN
+ * (CloudFront `CACHING_OPTIMIZED`) ignores query strings, so a
+ * query-keyed variant would collapse to one cached body across
+ * runtime versions. The hash versions the whole family: the shim
+ * files ship in the runtime bundle's dist, so any shim-affecting
+ * change also changes the bundle bytes, which changes `<rt>`, which
+ * changes every variant URL — immutable caching stays sound.
+ *
+ * The route serves only the CURRENT `<rt>`: after a redeploy, a
+ * CDN-evicted old-variant URL 404s (`no-store`) and the renderer falls
+ * back to its raw-bytes ladder — honest degradation, never stale shims.
+ *
+ * 3rd-party gadget packages (GG.8.2) have no static shim (their
+ * exports are derived per-render from the generated code); a module
+ * importing one is NOT asset-deliverable. Both ends respect that: the
+ * minter declines to stamp `codeModuleUrl`, and the route declines
+ * (404) any body whose rewrite leaves a bare specifier standing.
+ */
+import type { Express } from "express";
+import type { Logger } from "./logger.js";
+/**
+ * Mint the `codeModuleUrl` for one render's component code, or decline.
+ *
+ * `undefined` ⇒ the code is not asset-deliverable (it imports a
+ * package with no static shim) — the slice then carries only the raw
+ * `codeUrl`/`codeB64` carriers and the renderer uses its blob ladder.
+ */
+export type MintCodeModuleUrl = (args: {
+    /** RAW stored component code (markers included — stripped here). */
+    readonly code: string;
+    /** `sha256(code)` — the same hash `codeUrl` is composed from. */
+    readonly hash: string;
+    /** Code base URL, no trailing slash (the emitter already trims). */
+    readonly base: string;
+}) => string | undefined;
+/** The variant URL for (hash, rt) under `base` — ONE composition site. */
+export declare function composeCodeModuleUrl(args: {
+    readonly base: string;
+    readonly hash: string;
+    readonly runtimeHash: string;
+}): string;
+/**
+ * Build the minter every `codeUrl` emitter injects. Coverability is
+ * decided from the code's own import list: every bare specifier must
+ * have a static shim ({@link ASSET_SHIM_FOR_SPECIFIER}) or the mint
+ * declines. Markers are stripped first — their embedded JSON can
+ * contain strings the import scanner would misread.
+ */
+export declare function createCodeModuleUrlMinter(args: {
+    readonly runtimeHash: string;
+}): MintCodeModuleUrl;
+/**
+ * Rewrite stored component bytes into the servable asset-module
+ * variant — the same preprocessing the renderer's blob ladder applies
+ * (strip markers, hoist imports) plus the `asset-url` specifier
+ * rewrite. Declines when any bare specifier survives (no static shim
+ * exists for it) instead of serving a module that fails at eval.
+ */
+export declare function rewriteToAssetModule(args: {
+    readonly code: string;
+    readonly shimBaseUrl: string;
+}): {
+    readonly ok: true;
+    readonly code: string;
+} | {
+    readonly ok: false;
+    readonly leftover: readonly string[];
+};
+/**
+ * Read the static shim files emitted by the iframe-runtime build
+ * (`dist/shims/<name>.js`) into memory, keyed by file name. Captured
+ * ONCE at composition — the immutable shim route must keep serving the
+ * exact bytes its URL family was stamped for, even across an in-place
+ * rebuild of the dist (same guarantee the hashed bundle route makes by
+ * serving captured bytes).
+ *
+ * `undefined` when the directory is missing/empty (bundle built by an
+ * older toolchain) — callers then skip the whole variant family.
+ */
+export declare function captureShimSources(shimsDir: string): ReadonlyMap<string, Buffer> | undefined;
+/**
+ * Mount `GET <urlPrefix>/:rt/:file` serving the captured shim sources
+ * with the immutable posture of the hashed-bundle route. Only the
+ * CURRENT `runtimeHash` is served; any other `rt` 404s `no-store` so a
+ * stale URL can never lock wrong bytes into a cache.
+ */
+export declare function mountShimRoutes(opts: {
+    readonly app: Express;
+    readonly urlPrefix: string;
+    readonly runtimeHash: string;
+    readonly shims: ReadonlyMap<string, Buffer>;
+}): void;
+/**
+ * Options for the `/code/<hash>.m<rt>.js` variant route
+ * (mounted by `mountCodeRoutes` BEFORE the plain routes).
+ */
+export interface CodeModuleVariantOptions {
+    /** 12-hex content hash of the runtime bundle currently served. */
+    readonly runtimeHash: string;
+    /**
+     * Absolute base of THIS build's shim directory
+     * (`<codeBaseUrl><urlPrefix>/<runtimeHash>`), no trailing slash —
+     * the rewrite embeds it into every import.
+     */
+    readonly shimBaseUrl: string;
+}
+/**
+ * RegExp route for the variant path. A RegExp (not a string pattern)
+ * on purpose: two params separated by literal dots inside one path
+ * segment sit exactly on path-to-regexp's least-stable parsing ground,
+ * and a silent non-match here would read as "variant never works".
+ */
+export declare const CODE_MODULE_VARIANT_ROUTE: RegExp;
+/**
+ * Mount the module-variant route. Serving posture mirrors the plain
+ * code route (immutable on success, `no-store` on every failure); the
+ * two decline arms are:
+ *
+ *   - `rt` ≠ the current runtime hash → 404. The shims for another
+ *     build are unknowable here; the renderer falls back to raw bytes.
+ *   - leftover bare specifier after rewrite → 404. The module imports
+ *     a package with no static shim (3rd-party gadget); serving it
+ *     would fail at eval inside the frame instead of falling back.
+ */
+export declare function mountCodeModuleVariantRoute(opts: {
+    readonly app: Express;
+    readonly codeStore: import("@ggui-ai/mcp-server-core").CodeStore;
+    readonly variant: CodeModuleVariantOptions;
+    readonly logger: Logger;
+}): void;
+//# sourceMappingURL=code-module-variant.d.ts.map

package/dist/code-module-variant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-module-variant.d.ts","sourceRoot":"","sources":["../src/code-module-variant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAU1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IACrC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,KAAK,MAAM,GAAG,SAAS,CAAC;AAEzB,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GAAG,MAAM,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GAAG,iBAAiB,CASpB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAQ9G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GACf,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAkBzC;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C,GAAG,IAAI,CAyCP;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAkD,CAAC;AAEzF;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,0BAA0B,EAAE,SAAS,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,IAAI,CA8DP"}

package/dist/code-module-variant.js

@@ -0,0 +1,243 @@
+/**
+ * Strict-CSP module-variant delivery (ggui#522 slice 2).
+ *
+ * The `/code/<hash>.js` route serves STORED component bytes — compiled
+ * ESM whose imports are still BARE specifiers (`react`,
+ * `@ggui-ai/design/primitives`, …). A browser cannot import that
+ * standalone; the renderer historically bridged the gap in-frame by
+ * rewriting bare specifiers to `data:` shims and instantiating the
+ * module from a `blob:` URL — both of which a strict host CSP refuses.
+ *
+ * This module adds the server-side twin of that bridge: a SECOND,
+ * immutable route `/code/<hash>.m<rt>.js` serving the SAME stored bytes
+ * with the rewrite already applied — every bare specifier resolved to a
+ * static shim asset under `/_ggui/shims/<rt>/<name>.js` on the same
+ * origin. A frame whose `script-src` allows only the asset origin can
+ * `import()` the variant URL directly: no `blob:`, no `data:`, no
+ * `'unsafe-eval'`.
+ *
+ * `<rt>` — the 12-hex content hash of the runtime bundle — is the
+ * variant KEY, and it lives in the PATH deliberately: the asset CDN
+ * (CloudFront `CACHING_OPTIMIZED`) ignores query strings, so a
+ * query-keyed variant would collapse to one cached body across
+ * runtime versions. The hash versions the whole family: the shim
+ * files ship in the runtime bundle's dist, so any shim-affecting
+ * change also changes the bundle bytes, which changes `<rt>`, which
+ * changes every variant URL — immutable caching stays sound.
+ *
+ * The route serves only the CURRENT `<rt>`: after a redeploy, a
+ * CDN-evicted old-variant URL 404s (`no-store`) and the renderer falls
+ * back to its raw-bytes ladder — honest degradation, never stale shims.
+ *
+ * 3rd-party gadget packages (GG.8.2) have no static shim (their
+ * exports are derived per-render from the generated code); a module
+ * importing one is NOT asset-deliverable. Both ends respect that: the
+ * minter declines to stamp `codeModuleUrl`, and the route declines
+ * (404) any body whose rewrite leaves a bare specifier standing.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { rewriteImports, findBareImportSpecifiers, stripMarkers, ASSET_SHIM_FOR_SPECIFIER, } from "@ggui-ai/design/rendering";
+import { hoistImports } from "@ggui-ai/design/module-loader";
+/** The variant URL for (hash, rt) under `base` — ONE composition site. */
+export function composeCodeModuleUrl(args) {
+    return `${args.base}/code/${args.hash}.m${args.runtimeHash}.js`;
+}
+/**
+ * Build the minter every `codeUrl` emitter injects. Coverability is
+ * decided from the code's own import list: every bare specifier must
+ * have a static shim ({@link ASSET_SHIM_FOR_SPECIFIER}) or the mint
+ * declines. Markers are stripped first — their embedded JSON can
+ * contain strings the import scanner would misread.
+ */
+export function createCodeModuleUrlMinter(args) {
+    const { runtimeHash } = args;
+    return ({ code, hash, base }) => {
+        const bare = findBareImportSpecifiers(stripMarkers(code));
+        if (!bare.every((spec) => spec in ASSET_SHIM_FOR_SPECIFIER)) {
+            return undefined;
+        }
+        return composeCodeModuleUrl({ base, hash, runtimeHash });
+    };
+}
+/**
+ * Rewrite stored component bytes into the servable asset-module
+ * variant — the same preprocessing the renderer's blob ladder applies
+ * (strip markers, hoist imports) plus the `asset-url` specifier
+ * rewrite. Declines when any bare specifier survives (no static shim
+ * exists for it) instead of serving a module that fails at eval.
+ */
+export function rewriteToAssetModule(args) {
+    const rewritten = rewriteImports(hoistImports(stripMarkers(args.code)), {
+        mode: "asset-url",
+        shimBaseUrl: args.shimBaseUrl,
+    });
+    const leftover = findBareImportSpecifiers(rewritten);
+    if (leftover.length > 0)
+        return { ok: false, leftover };
+    return { ok: true, code: rewritten };
+}
+/**
+ * Read the static shim files emitted by the iframe-runtime build
+ * (`dist/shims/<name>.js`) into memory, keyed by file name. Captured
+ * ONCE at composition — the immutable shim route must keep serving the
+ * exact bytes its URL family was stamped for, even across an in-place
+ * rebuild of the dist (same guarantee the hashed bundle route makes by
+ * serving captured bytes).
+ *
+ * `undefined` when the directory is missing/empty (bundle built by an
+ * older toolchain) — callers then skip the whole variant family.
+ */
+export function captureShimSources(shimsDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(shimsDir);
+    }
+    catch {
+        return undefined;
+    }
+    const out = new Map();
+    for (const entry of entries) {
+        if (!entry.endsWith(".js"))
+            continue;
+        try {
+            out.set(entry, fs.readFileSync(path.join(shimsDir, entry)));
+        }
+        catch {
+            // A vanishing file mid-capture degrades to "that shim 404s";
+            // the renderer's fallback ladder covers it.
+        }
+    }
+    return out.size > 0 ? out : undefined;
+}
+/** File-segment shape of a shim asset (`react.js`, `jsx-runtime.js`). */
+const SHIM_FILE_REGEX = /^[a-z][a-z-]*\.js$/;
+/** 12-hex runtime-hash path segment. */
+const RUNTIME_HASH_REGEX = /^[a-f0-9]{12}$/;
+/**
+ * Mount `GET <urlPrefix>/:rt/:file` serving the captured shim sources
+ * with the immutable posture of the hashed-bundle route. Only the
+ * CURRENT `runtimeHash` is served; any other `rt` 404s `no-store` so a
+ * stale URL can never lock wrong bytes into a cache.
+ */
+export function mountShimRoutes(opts) {
+    const { app, urlPrefix, runtimeHash, shims } = opts;
+    app.get(`${urlPrefix}/:rt/:file`, (req, res) => {
+        // Same CORS rationale as the runtime bundle: module fetches from a
+        // sandboxed `srcdoc` iframe (`null` origin) always run CORS mode.
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        const rt = req.params["rt"];
+        const file = req.params["file"];
+        if (typeof rt !== "string" ||
+            !RUNTIME_HASH_REGEX.test(rt) ||
+            typeof file !== "string" ||
+            !SHIM_FILE_REGEX.test(file)) {
+            res.setHeader("Cache-Control", "no-store");
+            res.status(400).json({
+                error: {
+                    code: "invalid_request",
+                    message: "shim path must be /<12-hex runtime hash>/<name>.js",
+                },
+            });
+            return;
+        }
+        const source = rt === runtimeHash ? shims.get(file) : undefined;
+        if (source === undefined) {
+            res.setHeader("Cache-Control", "no-store");
+            res.status(404).json({
+                error: {
+                    code: "not_found",
+                    message: rt === runtimeHash
+                        ? "unknown shim module"
+                        : "shim family not served by this runtime build",
+                },
+            });
+            return;
+        }
+        res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+        res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+        res.status(200).send(source);
+    });
+}
+/**
+ * RegExp route for the variant path. A RegExp (not a string pattern)
+ * on purpose: two params separated by literal dots inside one path
+ * segment sit exactly on path-to-regexp's least-stable parsing ground,
+ * and a silent non-match here would read as "variant never works".
+ */
+export const CODE_MODULE_VARIANT_ROUTE = /^\/code\/([a-f0-9]{64})\.m([a-f0-9]{12})\.js$/;
+/**
+ * Mount the module-variant route. Serving posture mirrors the plain
+ * code route (immutable on success, `no-store` on every failure); the
+ * two decline arms are:
+ *
+ *   - `rt` ≠ the current runtime hash → 404. The shims for another
+ *     build are unknowable here; the renderer falls back to raw bytes.
+ *   - leftover bare specifier after rewrite → 404. The module imports
+ *     a package with no static shim (3rd-party gadget); serving it
+ *     would fail at eval inside the frame instead of falling back.
+ */
+export function mountCodeModuleVariantRoute(opts) {
+    const { app, codeStore, variant, logger } = opts;
+    app.get(CODE_MODULE_VARIANT_ROUTE, async (req, res) => {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        // RegExp routes surface capture groups as positional params.
+        const hash = req.params["0"];
+        const rt = req.params["1"];
+        if (typeof hash !== "string" || typeof rt !== "string") {
+            res.setHeader("Cache-Control", "no-store");
+            res.status(400).json({
+                error: { code: "invalid_request", message: "malformed variant path" },
+            });
+            return;
+        }
+        if (rt !== variant.runtimeHash) {
+            res.setHeader("Cache-Control", "no-store");
+            res.status(404).json({
+                error: {
+                    code: "not_found",
+                    message: "variant family not served by this runtime build",
+                },
+            });
+            return;
+        }
+        try {
+            const code = await codeStore.get(hash);
+            if (code === null) {
+                res.setHeader("Cache-Control", "no-store");
+                res.status(404).json({
+                    error: { code: "not_found", message: "unknown code hash" },
+                });
+                return;
+            }
+            const rewritten = rewriteToAssetModule({
+                code,
+                shimBaseUrl: variant.shimBaseUrl,
+            });
+            if (!rewritten.ok) {
+                logger.warn("code_module_variant_declined", {
+                    hash,
+                    leftover: [...rewritten.leftover],
+                });
+                res.setHeader("Cache-Control", "no-store");
+                res.status(404).json({
+                    error: {
+                        code: "not_found",
+                        message: "module not asset-deliverable (bare imports without static shims)",
+                    },
+                });
+                return;
+            }
+            res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+            res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+            res.status(200).send(rewritten.code);
+        }
+        catch (err) {
+            logger.warn("code_module_variant_failed", { hash, error: String(err) });
+            res.setHeader("Cache-Control", "no-store");
+            res.status(500).json({
+                error: { code: "internal", message: "variant fetch failed" },
+            });
+        }
+    });
+}

package/dist/code-routes.d.ts

@@ -30,6 +30,7 @@
 import type { CodeStore } from "@ggui-ai/mcp-server-core";
 import type { Express } from "express";
 import type { Logger } from "./logger.js";
+import { type CodeModuleVariantOptions } from "./code-module-variant.js";
 interface MountOptions {
     /** Express app to mount onto. */
     readonly app: Express;
@@ -37,10 +38,19 @@ interface MountOptions {
     readonly codeStore: CodeStore;
     /** Structured logger for fetch-failure warnings. */
     readonly logger: Logger;
+    /**
+     * Strict-CSP module-variant family (`/code/<hash>.m<rt>.js`,
+     * ggui#522 slice 2). Present ⇒ the variant route mounts BEFORE the
+     * plain routes — ordering is load-bearing: `/code/:hash.js`'s param
+     * would otherwise swallow the variant path (`:hash` = `<hash>.m<rt>`)
+     * and 400 it at the hash gate.
+     */
+    readonly moduleVariant?: CodeModuleVariantOptions;
 }
 /**
- * Mount `GET /code/:hash.js` + `GET /contract/:hash.js` onto the
- * express app. Returns nothing — the routes self-register.
+ * Mount `GET /code/:hash.js` + `GET /contract/:hash.js` (+ the
+ * module-variant route when configured) onto the express app. Returns
+ * nothing — the routes self-register.
  */
 export declare function mountCodeRoutes(opts: MountOptions): void;
 export {};

package/dist/code-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-routes.d.ts","sourceRoot":"","sources":["../src/code-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA6CxD"}
+{"version":3,"file":"code-routes.d.ts","sourceRoot":"","sources":["../src/code-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,0BAA0B,CAAC;AAElC,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;CACnD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAqDxD"}