@ggui-ai/mcp-server 0.9.0 → 0.10.0

package/dist/api-renders-routes.d.ts

@@ -64,6 +64,27 @@ interface MountOptions {
     readonly codeStore?: CodeStore;
     /** Operator-configured public origin for absolute URL composition. */
     readonly publicBaseUrl?: string;
+    /**
+     * Origin the content-addressable routes (`/code/*`, `/contract/*`)
+     * are reached at — an edge-cached asset host when the deployment
+     * fronts static paths separately (ggui#522). Defaults to
+     * {@link publicBaseUrl}, then the request host. Session-API URLs
+     * (`/events`, `/stream`) never use it: those are dynamic and stay on
+     * the public origin.
+     */
+    readonly codeBaseUrl?: string;
+    /**
+     * Strict-CSP module-variant minter (ggui#522 slice 2) — the /state
+     * read re-mints the `codeModuleUrl` twin alongside `codeUrl`. Only
+     * consulted when an explicit {@link codeBaseUrl}/{@link publicBaseUrl}
+     * base resolved: the variant embeds absolute shim URLs on the SAME
+     * origin, and a request-derived base has no shim family behind it.
+     */
+    readonly mintCodeModuleUrl?: (args: {
+        readonly code: string;
+        readonly hash: string;
+        readonly base: string;
+    }) => string | undefined;
     /** Live-mode credential minter — fresh trio on every /state read. */
     readonly mintBootstrap?: (sessionId: string, appId: string) => {
         wsUrl: string;

package/dist/api-renders-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-renders-routes.d.ts","sourceRoot":"","sources":["../src/api-renders-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQ9F,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,KACV;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,MAAM,CAAC;IACzC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA0V9D"}
+{"version":3,"file":"api-renders-routes.d.ts","sourceRoot":"","sources":["../src/api-renders-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQ9F,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE;QAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,KACV;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,MAAM,CAAC;IACzC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA8W9D"}

package/dist/api-renders-routes.js

@@ -52,7 +52,11 @@ import { composeSessionApiUrls, MCP_APP_AI_GGUI_RENDER_META_KEY, } from "@ggui-a
  * Returns nothing — the routes self-register.
  */
 export function mountApiRendersRoutes(opts) {
-    const { app, renderStore, secret, appMetadataStore, themeId, themeMode, codeStore, publicBaseUrl, mintBootstrap, resolveRuntimeUrl, logger, } = opts;
+    const { app, renderStore, secret, appMetadataStore, themeId, themeMode, codeStore, publicBaseUrl, codeBaseUrl, mintBootstrap, resolveRuntimeUrl, logger, } = opts;
+    // The origin the content-addressable routes are reached at (asset
+    // host if fronted separately, else the public origin); the request
+    // host is the last resort for local/tunnel deployments.
+    const staticBase = codeBaseUrl ?? publicBaseUrl;
     app.get("/api/sessions/:sessionId/state", async (req, res) => {
         // CORS on EVERY response, gates included: cross-origin frames can
         // only read a status when the response carries ACAO. Without it a
@@ -173,6 +177,7 @@ export function mountApiRendersRoutes(opts) {
         // and need the URL to mount/refresh the static-component variant.
         let renderCodeUrl;
         let renderCodeHash;
+        let renderCodeModuleUrl;
         let renderContractHash;
         let renderValidatorsUrl;
         if (!isSystem && !isMcpApps && codeStore) {
@@ -183,10 +188,19 @@ export function mountApiRendersRoutes(opts) {
                     await codeStore.put(hash, code);
                     renderCodeHash = hash;
                     const requestHost = req.get("host") ?? "";
-                    const base = publicBaseUrl
-                        ? publicBaseUrl.replace(/\/$/, "")
+                    const base = staticBase !== undefined
+                        ? staticBase.replace(/\/$/, "")
                         : `${req.protocol}://${requestHost}`;
                     renderCodeUrl = `${base}/code/${hash}.js`;
+                    // Strict-CSP module-variant twin — only on an explicit base
+                    // (see MountOptions.mintCodeModuleUrl for why).
+                    if (staticBase !== undefined) {
+                        renderCodeModuleUrl = opts.mintCodeModuleUrl?.({
+                            code,
+                            hash,
+                            base,
+                        });
+                    }
                 }
                 catch {
                     // Silent — the caller falls back to live-mode delivery, and
@@ -205,8 +219,8 @@ export function mountApiRendersRoutes(opts) {
                         await codeStore.put(bundle.contractHash, bundle.bundleSource);
                         renderContractHash = bundle.contractHash;
                         const requestHost = req.get("host") ?? "";
-                        const base = publicBaseUrl
-                            ? publicBaseUrl.replace(/\/$/, "")
+                        const base = staticBase !== undefined
+                            ? staticBase.replace(/\/$/, "")
                             : `${req.protocol}://${requestHost}`;
                         renderValidatorsUrl = `${base}/contract/${bundle.contractHash}.js`;
                     }
@@ -251,6 +265,9 @@ export function mountApiRendersRoutes(opts) {
                 ? {
                     codeUrl: renderCodeUrl,
                     ...(renderCodeHash !== undefined ? { codeHash: renderCodeHash } : {}),
+                    ...(renderCodeModuleUrl !== undefined
+                        ? { codeModuleUrl: renderCodeModuleUrl }
+                        : {}),
                 }
                 : {}),
             ...(renderContractHash !== undefined && renderValidatorsUrl !== undefined

package/dist/build-mcp.d.ts

@@ -126,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;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;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,CAmPX"}
+{"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

@@ -22,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,
@@ -128,8 +145,12 @@ 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,

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"}