@runsnative/mcp-server 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,107 +1,6 @@
 #!/usr/bin/env node
-import { createRequire } from 'node:module';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { GET_COMPONENT_TOOL, handleGetComponent } from './tools/get-component.js';
-import { LIST_COMPONENTS_TOOL, handleListComponents } from './tools/list-components.js';
-import { GET_FOUNDATION_TOOL, handleGetFoundation } from './tools/get-foundation.js';
-import { SEARCH_DOCS_TOOL, handleSearchDocs } from './tools/search-docs.js';
-import { INFER_THEME_TOOL, handleInferTheme } from './tools/infer-theme.js';
-import { INFER_BRAND_THEME_TOOL, handleInferBrandTheme } from './tools/infer-brand-theme.js';
-import { LIST_EXERCISES_TOOL, handleListExercises } from './tools/list-exercises.js';
-import { START_EXERCISE_TOOL, handleStartExercise } from './tools/start-exercise.js';
-import { GET_STEP_TOOL, handleGetStep } from './tools/get-step.js';
-import { SURFACE_PREVIEW_TOOL, handleSurfacePreview } from './tools/surface-preview.js';
-import { LIST_COMPOSITION_PATTERNS_TOOL, handleListCompositionPatterns } from './tools/list-composition-patterns.js';
-import { GET_COMPOSITION_PATTERN_TOOL, handleGetCompositionPattern } from './tools/get-composition-pattern.js';
-import { GET_EMPHASIS_SCALE_TOOL, handleGetEmphasisScale } from './tools/get-emphasis-scale.js';
-import { GET_COMPLETENESS_MAP_TOOL, handleGetCompletenessMap } from './tools/get-completeness-map.js';
-import { LINK_SESSION_TOOL, handleLinkSession } from './tools/link-session.js';
-import { SET_THEME_TOOL, handleSetTheme } from './tools/set-theme.js';
-import { NAVIGATE_TOOL, handleNavigate } from './tools/navigate.js';
-import { SET_INSTANCE_VARIANT_TOOL, handleSetInstanceVariant } from './tools/set-instance-variant.js';
-import { GET_MARKER_CAPTURE_TOOL, handleGetMarkerCapture } from './tools/get-marker-capture.js';
-import { createProvider } from './provider.js';
-import { RemoteContentProvider } from './remote-provider.js';
-// Create the content provider — LocalContentProvider if content tree is present,
-// RemoteContentProvider otherwise. Initialize runs the manifest version check.
-const provider = await createProvider();
-if (provider instanceof RemoteContentProvider) {
-    await provider.initialize();
-}
-// Advertised version reads package.json at runtime — a literal here drifts
-// the moment the next release forgets to update it (0.3.0 survived four
-// releases; 0.1.4 outlived its release within hours).
-const require = createRequire(import.meta.url);
-const { version: pkgVersion } = require('../package.json');
-const server = new Server({ name: 'runsnative-mcp', version: pkgVersion }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-        GET_COMPONENT_TOOL,
-        LIST_COMPONENTS_TOOL,
-        GET_FOUNDATION_TOOL,
-        SEARCH_DOCS_TOOL,
-        INFER_THEME_TOOL,
-        INFER_BRAND_THEME_TOOL,
-        LIST_EXERCISES_TOOL,
-        START_EXERCISE_TOOL,
-        GET_STEP_TOOL,
-        SURFACE_PREVIEW_TOOL,
-        LIST_COMPOSITION_PATTERNS_TOOL,
-        GET_COMPOSITION_PATTERN_TOOL,
-        GET_EMPHASIS_SCALE_TOOL,
-        GET_COMPLETENESS_MAP_TOOL,
-        LINK_SESSION_TOOL,
-        SET_THEME_TOOL,
-        NAVIGATE_TOOL,
-        SET_INSTANCE_VARIANT_TOOL,
-        GET_MARKER_CAPTURE_TOOL,
-    ],
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    switch (request.params.name) {
-        case 'get_component':
-            return handleGetComponent(provider, request.params.arguments ?? {});
-        case 'list_components':
-            return handleListComponents(provider, request.params.arguments ?? {});
-        case 'get_foundation':
-            return handleGetFoundation(provider, request.params.arguments ?? {});
-        case 'search_docs':
-            return handleSearchDocs(provider, request.params.arguments ?? {});
-        case 'infer_theme':
-            return handleInferTheme(request.params.arguments ?? {});
-        case 'infer_brand_theme':
-            return handleInferBrandTheme(request.params.arguments ?? {});
-        case 'list_exercises':
-            return handleListExercises(provider, request.params.arguments ?? {});
-        case 'start_exercise':
-            return handleStartExercise(provider, request.params.arguments ?? {});
-        case 'get_step':
-            return handleGetStep(provider, request.params.arguments ?? {});
-        case 'surface_preview':
-            return handleSurfacePreview();
-        case 'list_composition_patterns':
-            return handleListCompositionPatterns(provider, request.params.arguments ?? {});
-        case 'get_composition_pattern':
-            return handleGetCompositionPattern(provider, request.params.arguments ?? {});
-        case 'get_emphasis_scale':
-            return handleGetEmphasisScale();
-        case 'get_completeness_map':
-            return handleGetCompletenessMap();
-        case 'link_session':
-            return handleLinkSession(request.params.arguments ?? {});
-        case 'set_theme':
-            return handleSetTheme(request.params.arguments ?? {});
-        case 'navigate':
-            return handleNavigate(request.params.arguments ?? {});
-        case 'set_instance_variant':
-            return handleSetInstanceVariant(request.params.arguments ?? {});
-        case 'get_marker_capture':
-            return handleGetMarkerCapture(request.params.arguments ?? {});
-        default:
-            throw new Error(`Unknown tool: ${request.params.name}`);
-    }
-});
+import { createRunsnativeServer } from './server.js';
+const server = await createRunsnativeServer();
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/inferrer/nav-error.js

@@ -0,0 +1,31 @@
+// Navigation-failure classification, extracted from page-fetcher.ts (JUNE-607) so the
+// Cloudflare Worker port can import it without dragging in page-fetcher's lazy
+// `import('playwright')` — esbuild cannot bundle a literal dynamic import of a package
+// that is not installed. This module is pure (no imports, no I/O); page-fetcher.ts
+// re-exports everything here, so existing consumers are unaffected.
+/**
+ * Map a Chromium/Playwright navigation error string to a user-meaningful reason. Signatures
+ * verified against live failures: ecolab.com → ERR_HTTP2_PROTOCOL_ERROR (bot-block),
+ * a dead domain → ERR_NAME_NOT_RESOLVED, badssl.com → ERR_CERT_*, port 1 → ERR_UNSAFE_PORT.
+ */
+export function classifyNavError(cause) {
+    const c = cause.toUpperCase();
+    if (/\bTIMEOUT\b|EXCEEDED/.test(c))
+        return 'timeout';
+    if (c.includes('ERR_NAME_NOT_RESOLVED') || c.includes('ERR_NAME_RESOLUTION_FAILED'))
+        return 'not_found';
+    if (c.includes('ERR_CERT'))
+        return 'tls';
+    // Connection reset / HTTP2 protocol errors on the initial navigation are the fingerprint of
+    // a WAF/bot wall fingerprinting headless Chromium (verified: ecolab.com). ERR_ACCESS_DENIED
+    // and ERR_BLOCKED_BY_* are the explicit forms.
+    if (c.includes('ERR_HTTP2_PROTOCOL_ERROR') || c.includes('ERR_CONNECTION_RESET') ||
+        c.includes('ERR_ACCESS_DENIED') || c.includes('ERR_BLOCKED'))
+        return 'blocked';
+    if (c.includes('ERR_CONNECTION_REFUSED') || c.includes('ERR_CONNECTION_TIMED_OUT') ||
+        c.includes('ERR_ADDRESS_UNREACHABLE') || c.includes('ERR_UNSAFE_PORT') ||
+        c.includes('ERR_CONNECTION_CLOSED') || c.includes('ERR_EMPTY_RESPONSE') ||
+        c.includes('ERR_SOCKET_NOT_CONNECTED'))
+        return 'unreachable';
+    return 'unknown';
+}

package/dist/inferrer/page-fetcher.js

@@ -1,4 +1,10 @@
 import { extractStylesFromPage } from './style-extractor.js';
+import { classifyNavError } from './nav-error.js';
+// Failure classification lives in nav-error.ts (JUNE-607) so the Cloudflare Worker port can
+// share it without importing this module's lazy `import('playwright')` (esbuild cannot bundle
+// a literal dynamic import of an uninstalled package). Re-exported so existing consumers
+// (pipeline, tests, the MCP tool) keep their import path.
+export { classifyNavError };
 export async function loadChromium() {
     try {
         const playwright = await import('playwright');
@@ -8,32 +14,6 @@ export async function loadChromium() {
         return null;
     }
 }
-/**
- * Map a Chromium/Playwright navigation error string to a user-meaningful reason. Signatures
- * verified against live failures: ecolab.com → ERR_HTTP2_PROTOCOL_ERROR (bot-block),
- * a dead domain → ERR_NAME_NOT_RESOLVED, badssl.com → ERR_CERT_*, port 1 → ERR_UNSAFE_PORT.
- */
-export function classifyNavError(cause) {
-    const c = cause.toUpperCase();
-    if (/\bTIMEOUT\b|EXCEEDED/.test(c))
-        return 'timeout';
-    if (c.includes('ERR_NAME_NOT_RESOLVED') || c.includes('ERR_NAME_RESOLUTION_FAILED'))
-        return 'not_found';
-    if (c.includes('ERR_CERT'))
-        return 'tls';
-    // Connection reset / HTTP2 protocol errors on the initial navigation are the fingerprint of
-    // a WAF/bot wall fingerprinting headless Chromium (verified: ecolab.com). ERR_ACCESS_DENIED
-    // and ERR_BLOCKED_BY_* are the explicit forms.
-    if (c.includes('ERR_HTTP2_PROTOCOL_ERROR') || c.includes('ERR_CONNECTION_RESET') ||
-        c.includes('ERR_ACCESS_DENIED') || c.includes('ERR_BLOCKED'))
-        return 'blocked';
-    if (c.includes('ERR_CONNECTION_REFUSED') || c.includes('ERR_CONNECTION_TIMED_OUT') ||
-        c.includes('ERR_ADDRESS_UNREACHABLE') || c.includes('ERR_UNSAFE_PORT') ||
-        c.includes('ERR_CONNECTION_CLOSED') || c.includes('ERR_EMPTY_RESPONSE') ||
-        c.includes('ERR_SOCKET_NOT_CONNECTED'))
-        return 'unreachable';
-    return 'unknown';
-}
 const VIEWPORT = { width: 1280, height: 800 };
 // Navigation timing. `domcontentloaded` is the hard gate; `networkidle` is a bounded bonus.
 const GOTO_TIMEOUT_MS = 25_000; // hard cap on the initial document navigation

package/dist/server.js

@@ -0,0 +1,131 @@
+import { createRequire } from 'node:module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { GET_COMPONENT_TOOL, handleGetComponent } from './tools/get-component.js';
+import { LIST_COMPONENTS_TOOL, handleListComponents } from './tools/list-components.js';
+import { GET_FOUNDATION_TOOL, handleGetFoundation } from './tools/get-foundation.js';
+import { SEARCH_DOCS_TOOL, handleSearchDocs } from './tools/search-docs.js';
+import { INFER_THEME_TOOL, handleInferTheme } from './tools/infer-theme.js';
+import { INFER_BRAND_THEME_TOOL, handleInferBrandTheme } from './tools/infer-brand-theme.js';
+import { LIST_EXERCISES_TOOL, handleListExercises } from './tools/list-exercises.js';
+import { START_EXERCISE_TOOL, handleStartExercise } from './tools/start-exercise.js';
+import { GET_STEP_TOOL, handleGetStep } from './tools/get-step.js';
+import { RENDER_GATHERING_TOOL, GATHERING_CARD_RESOURCE, handleRenderGathering, readGatheringCardResource, } from './tools/render-gathering.js';
+import { GATHERING_CARD_URI } from './surface/gathering-card.js';
+import { LIST_COMPOSITION_PATTERNS_TOOL, handleListCompositionPatterns } from './tools/list-composition-patterns.js';
+import { GET_COMPOSITION_PATTERN_TOOL, handleGetCompositionPattern } from './tools/get-composition-pattern.js';
+import { GET_EMPHASIS_SCALE_TOOL, handleGetEmphasisScale } from './tools/get-emphasis-scale.js';
+import { GET_COMPLETENESS_MAP_TOOL, handleGetCompletenessMap } from './tools/get-completeness-map.js';
+import { LINK_SESSION_TOOL, handleLinkSession } from './tools/link-session.js';
+import { SET_THEME_TOOL, handleSetTheme } from './tools/set-theme.js';
+import { APPLY_INFERRED_THEME_TOOL, handleApplyInferredTheme } from './tools/apply-inferred-theme.js';
+import { NAVIGATE_TOOL, handleNavigate } from './tools/navigate.js';
+import { SET_INSTANCE_VARIANT_TOOL, handleSetInstanceVariant } from './tools/set-instance-variant.js';
+import { GET_MARKER_CAPTURE_TOOL, handleGetMarkerCapture } from './tools/get-marker-capture.js';
+import { createProvider } from './provider.js';
+import { RemoteContentProvider } from './remote-provider.js';
+/**
+ * Build a fully-registered runsnative MCP Server. Transport-agnostic: the
+ * stdio entry (index.ts) and the dev/verification HTTP entry (dev-host.ts)
+ * both consume this factory, so tool/resource registration cannot drift
+ * between transports.
+ */
+export async function createRunsnativeServer() {
+    // Content provider — LocalContentProvider if a content tree is present,
+    // RemoteContentProvider otherwise. Initialize runs the manifest version check.
+    const provider = await createProvider();
+    if (provider instanceof RemoteContentProvider) {
+        await provider.initialize();
+    }
+    // Advertised version reads package.json at runtime — a literal here drifts
+    // the moment the next release forgets to update it (0.3.0 survived four
+    // releases; 0.1.4 outlived its release within hours).
+    const require = createRequire(import.meta.url);
+    const { version: pkgVersion } = require('../package.json');
+    const server = new Server({ name: 'runsnative-mcp', version: pkgVersion }, { capabilities: { tools: {}, resources: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            GET_COMPONENT_TOOL,
+            LIST_COMPONENTS_TOOL,
+            GET_FOUNDATION_TOOL,
+            SEARCH_DOCS_TOOL,
+            INFER_THEME_TOOL,
+            INFER_BRAND_THEME_TOOL,
+            LIST_EXERCISES_TOOL,
+            START_EXERCISE_TOOL,
+            GET_STEP_TOOL,
+            RENDER_GATHERING_TOOL,
+            LIST_COMPOSITION_PATTERNS_TOOL,
+            GET_COMPOSITION_PATTERN_TOOL,
+            GET_EMPHASIS_SCALE_TOOL,
+            GET_COMPLETENESS_MAP_TOOL,
+            LINK_SESSION_TOOL,
+            SET_THEME_TOOL,
+            APPLY_INFERRED_THEME_TOOL,
+            NAVIGATE_TOOL,
+            SET_INSTANCE_VARIANT_TOOL,
+            GET_MARKER_CAPTURE_TOOL,
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        switch (request.params.name) {
+            case 'get_component':
+                return handleGetComponent(provider, request.params.arguments ?? {});
+            case 'list_components':
+                return handleListComponents(provider, request.params.arguments ?? {});
+            case 'get_foundation':
+                return handleGetFoundation(provider, request.params.arguments ?? {});
+            case 'search_docs':
+                return handleSearchDocs(provider, request.params.arguments ?? {});
+            case 'infer_theme':
+                return handleInferTheme(request.params.arguments ?? {});
+            case 'infer_brand_theme':
+                return handleInferBrandTheme(request.params.arguments ?? {});
+            case 'list_exercises':
+                return handleListExercises(provider, request.params.arguments ?? {});
+            case 'start_exercise':
+                return handleStartExercise(provider, request.params.arguments ?? {});
+            case 'get_step':
+                return handleGetStep(provider, request.params.arguments ?? {});
+            case 'render_gathering':
+                return handleRenderGathering();
+            case 'list_composition_patterns':
+                return handleListCompositionPatterns(provider, request.params.arguments ?? {});
+            case 'get_composition_pattern':
+                return handleGetCompositionPattern(provider, request.params.arguments ?? {});
+            case 'get_emphasis_scale':
+                return handleGetEmphasisScale();
+            case 'get_completeness_map':
+                return handleGetCompletenessMap();
+            case 'link_session':
+                return handleLinkSession(request.params.arguments ?? {});
+            case 'set_theme':
+                return handleSetTheme(request.params.arguments ?? {});
+            case 'apply_inferred_theme':
+                return handleApplyInferredTheme(request.params.arguments ?? {});
+            case 'navigate':
+                return handleNavigate(request.params.arguments ?? {});
+            case 'set_instance_variant':
+                return handleSetInstanceVariant(request.params.arguments ?? {});
+            case 'get_marker_capture':
+                return handleGetMarkerCapture(request.params.arguments ?? {});
+            default:
+                throw new Error(`Unknown tool: ${request.params.name}`);
+        }
+    });
+    // MCP App surfaces (JUNE-618): ui:// resources referenced by tool _meta. The
+    // host reads the resource and renders it in a sandboxed iframe; each document
+    // is fully self-contained (bundle + runtime + CSS inlined by the seam).
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [GATHERING_CARD_RESOURCE],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        switch (request.params.uri) {
+            case GATHERING_CARD_URI:
+                return readGatheringCardResource();
+            default:
+                throw new Error(`Unknown resource: ${request.params.uri}`);
+        }
+    });
+    return server;
+}

package/dist/surface/assets.js

@@ -0,0 +1,89 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// trim(): trailing whitespace from setx/cmd wrappers silently corrupts URLs
+// and headers (KUKAMANGA-wide env-read rule).
+const THEME_CSS_BASE = (process.env['RUNSNATIVE_THEME_CSS_BASE'] ?? 'https://runsnative.org').trim();
+const FETCH_HEADERS = { 'User-Agent': 'runsnative-mcp-server (surface-assets)' };
+let _bundleCache = null;
+let _runtimeCache = null;
+const _themeCssCache = new Map();
+// In dist/, this module compiles to dist/surface/assets.js — both build-time
+// artifacts sit one level up, in the shipped dist/ root.
+function distPath(file) {
+    return resolve(__dirname, '..', file);
+}
+/**
+ * The run-* web-component bundle to inline into an MCP App surface.
+ *
+ * Read from dist/components-inline.js — a build-time flattening of the pinned
+ * @runsnative/components release into ONE self-contained ES module (the
+ * published runsnative.min.js statically imports ./chunks/*, so it cannot be
+ * inlined as-is). No network at tool-call time; the sandbox CSP never sees an
+ * external URL because the fetch problem is solved at build time.
+ */
+export function componentsBundle() {
+    if (_bundleCache === null) {
+        _bundleCache = readFileSync(distPath('components-inline.js'), 'utf8');
+    }
+    return _bundleCache;
+}
+/**
+ * The iframe-side MCP Apps runtime (App class + PostMessageTransport), built
+ * to dist/iframe-runtime.js as a self-contained IIFE exposing
+ * globalThis.__MCP_APP_SDK__.
+ */
+export function iframeRuntime() {
+    if (_runtimeCache === null) {
+        _runtimeCache = readFileSync(distPath('iframe-runtime.js'), 'utf8');
+    }
+    return _runtimeCache;
+}
+const BRAND_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+// Strip @import lines — webfont imports cannot load inside the sandboxed
+// iframe and would only produce console noise (same transform compare.js
+// applies for section-scoped theme loading, JUNE-95).
+function stripImports(css) {
+    return css.replace(/^\s*@import[^;]*;\s*$/gm, '');
+}
+/**
+ * Token-engine theme CSS for a brand (tokens-<brand>.css, already scoped to
+ * :where([data-run-theme="X"])). Sourced from the pinned components package
+ * first (dist/tokens/, offline, version-consistent with the inlined bundle);
+ * falls back to the runsnative.org public root for brands the pinned release
+ * doesn't carry (e.g. themes landed after the pin).
+ * Returns null when the brand has no landed theme file — the card then renders
+ * with the accent-hex fallback.
+ */
+export async function themeCss(brandId) {
+    if (!BRAND_ID_PATTERN.test(brandId))
+        return null;
+    if (_themeCssCache.has(brandId))
+        return _themeCssCache.get(brandId) ?? null;
+    let css = null;
+    // dist/tokens/ is populated at build time from the same pinned release as
+    // the inlined bundle — offline and version-consistent.
+    const packaged = distPath(`tokens/tokens-${brandId}.css`);
+    if (existsSync(packaged))
+        css = stripImports(readFileSync(packaged, 'utf8'));
+    if (css === null) {
+        try {
+            const res = await fetch(`${THEME_CSS_BASE}/tokens-${brandId}.css`, { headers: FETCH_HEADERS });
+            if (res.ok)
+                css = stripImports(await res.text());
+        }
+        catch {
+            css = null;
+        }
+    }
+    _themeCssCache.set(brandId, css);
+    return css;
+}
+/** Test seam — reset module-level caches between tests. */
+export function _resetAssetCaches() {
+    _bundleCache = null;
+    _runtimeCache = null;
+    _themeCssCache.clear();
+}

package/dist/surface/gathering-card.js

@@ -0,0 +1,162 @@
+/**
+ * The gathering-card MCP App shell (JUNE-618) — the Create-a-Gathering finale.
+ *
+ * Static shell: no per-call data is baked in. The host delivers the tool
+ * result (gathering + theme CSS) via the MCP Apps tool-result notification;
+ * the app script below renders the card client-side with DOM APIs
+ * (textContent only — user-authored fields can never parse as markup).
+ */
+import { packageSurface } from './package-surface.js';
+export const GATHERING_CARD_URI = 'ui://runsnative/gathering-card.html';
+const CARD_CSS = `
+/* Shell defaults live in the lowest layer so injected token-engine CSS
+   (@layer primitives/semantics/themes, or unlayered scoped bundles) always
+   wins the cascade. Order is fixed by this first declaration. */
+@layer rn-shell, primitives, semantics, themes;
+@layer rn-shell {
+  :root {
+    --run-color-text-primary: #1e293b;
+    --run-color-text-secondary: #64748b;
+    --run-color-surface-default: #ffffff;
+    --run-color-surface-subtle: #f8fafc;
+    --run-color-surface-canvas: transparent;
+    --run-color-border-default: #e2e8f0;
+    --run-color-focus-ring: #2563eb;
+    --run-font-size-s: 14px;
+    --run-font-size-m: 16px;
+  }
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  color: var(--run-color-text-primary);
+  background: var(--run-color-surface-canvas);
+  padding: 12px;
+}
+.gathering-card {
+  max-width: 440px;
+  border: 1px solid var(--run-color-border-default);
+  border-radius: 12px;
+  background: var(--run-color-surface-default);
+  padding: 20px;
+  display: none;
+  flex-direction: column;
+  gap: 10px;
+}
+.gathering-card.is-ready { display: flex; }
+.card-host-bar { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+.card-meta { display: flex; align-items: center; gap: 8px; margin-top: 2px; }
+.card-avatar {
+  width: 28px; height: 28px; border-radius: 50%;
+  background: var(--run-color-brand-600, var(--card-accent, #2563eb)); color: #fff;
+  display: inline-flex; align-items: center; justify-content: center;
+  font-size: 11px; font-weight: 600; letter-spacing: 0.02em;
+}
+.card-actions { display: flex; align-items: center; gap: 10px; margin-top: 8px; }
+.card-status { font-size: 12px; color: var(--run-color-text-secondary); min-height: 1.2em; }
+#placeholder { font-size: 13px; color: var(--run-color-text-secondary); padding: 8px 2px; }
+`;
+const CARD_BODY = `
+<div id="placeholder">Waiting for your gathering…</div>
+<article class="gathering-card" id="card">
+  <div class="card-host-bar">
+    <run-text id="card-brand" variant="label" as="span" size="sm" color="theme"></run-text>
+    <run-badge variant="info" size="sm" pill>Yours</run-badge>
+  </div>
+  <run-text id="card-title" variant="title" as="h3" size="md"></run-text>
+  <run-text id="card-desc" variant="body" as="p" size="sm" color="secondary"></run-text>
+  <div class="card-meta">
+    <span class="card-avatar" id="card-avatar" aria-hidden="true"></span>
+    <run-text id="card-presenter" variant="caption" as="span"></run-text>
+    <run-text id="card-date" variant="caption" as="span" color="secondary"></run-text>
+  </div>
+  <div class="card-actions">
+    <run-button id="view-btn" variant="primary" size="sm">View on Convene</run-button>
+  </div>
+  <div class="card-status" id="card-status"></div>
+</article>
+`;
+// Static, data-free by design: everything user-authored arrives at runtime via
+// the tool-result notification and is assigned with textContent. Keep it that
+// way — interpolating server-side values here would reopen the injection door
+// the seam exists to close.
+const CARD_APP_SCRIPT = `
+const { App } = globalThis.__MCP_APP_SDK__;
+
+const BRAND_ID = /^[a-z0-9][a-z0-9-]*$/;
+const ACCENT_HEX = /^#[0-9a-fA-F]{3,8}$/;
+
+function setText(id, value) {
+  document.getElementById(id).textContent = value == null ? '' : String(value);
+}
+
+function render(payload) {
+  const g = payload && payload.gathering;
+  if (!g) return;
+  const card = document.getElementById('card');
+
+  // Theme: landed brands get their token-engine CSS (scoped to
+  // :where([data-run-theme="X"])); everything else falls back to the accent.
+  if (typeof payload.theme_css === 'string' && payload.theme_css && BRAND_ID.test(g.brand_id || '')) {
+    const style = document.createElement('style');
+    style.textContent = payload.theme_css;
+    document.head.appendChild(style);
+    card.setAttribute('data-run-theme', g.brand_id);
+    document.documentElement.setAttribute('data-run-theme', g.brand_id);
+  } else if (typeof g.accent_hex === 'string' && ACCENT_HEX.test(g.accent_hex)) {
+    // No landed theme — carry the user's accent onto the tokens the card's
+    // components actually consume.
+    card.style.setProperty('--card-accent', g.accent_hex);
+    card.style.setProperty('--run-color-focus-ring', g.accent_hex);
+    card.style.setProperty('--run-button-background', g.accent_hex);
+    card.style.setProperty('--run-button-background-hover', g.accent_hex);
+    card.style.setProperty('--run-button-background-active', g.accent_hex);
+    card.style.setProperty('--run-button-color', '#ffffff');
+    card.style.setProperty('--run-button-focus-ring-color', g.accent_hex);
+  }
+
+  setText('card-brand', payload.brand_label || g.brand_id || 'RunsNative');
+  setText('card-title', g.title);
+  setText('card-desc', g.description);
+  setText('card-avatar', (g.presenter_initials || '').slice(0, 3).toUpperCase());
+  setText('card-presenter', g.presenter_name);
+  setText('card-date', g.date_string);
+
+  document.getElementById('placeholder').style.display = 'none';
+  card.classList.add('is-ready');
+}
+
+const app = new App({ name: 'runsnative-gathering-card', version: '1.0.0' }, {});
+
+// Register before connect() so no notification is missed.
+app.ontoolresult = (params) => {
+  if (params && params.isError) {
+    setText('placeholder', 'Could not load your gathering — see the conversation for details.');
+    return;
+  }
+  render(params && params.structuredContent);
+};
+
+document.getElementById('view-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  status.textContent = 'Sending your tab to Convene…';
+  try {
+    const result = await app.callServerTool({ name: 'navigate', arguments: { path: '/compare/' } });
+    status.textContent = result && result.isError
+      ? 'No linked tab — open runsnative.org/compare/ to see it live.'
+      : 'Your linked tab is heading to Convene.';
+  } catch (e) {
+    status.textContent = 'No linked tab — open runsnative.org/compare/ to see it live.';
+  }
+});
+
+await app.connect();
+`;
+export function buildGatheringCardHtml(assets) {
+    return packageSurface({
+        title: 'Your Gathering — Convene',
+        bodyHtml: CARD_BODY,
+        css: CARD_CSS,
+        appScript: CARD_APP_SCRIPT,
+    }, assets);
+}

package/dist/surface/iframe-runtime-entry.js

@@ -0,0 +1,8 @@
+// Entry for the iframe-side MCP Apps runtime bundle. Built by
+// scripts/build-iframe-runtime.mjs into dist/iframe-runtime.js as a
+// self-contained IIFE, then inlined into every packaged surface by the seam
+// (package-surface.ts). Exposes a stable global so the (also inlined) app
+// script can use the SDK without module imports — inline module scripts
+// cannot import each other, and external URLs are blocked by the host CSP.
+import { App } from '@modelcontextprotocol/ext-apps';
+globalThis.__MCP_APP_SDK__ = { App };

package/dist/surface/package-surface.js

@@ -0,0 +1,59 @@
+/**
+ * The MCP App packaging seam (JUNE-618) — component tree + theme + app script
+ * into ONE self-contained `ui://` resource document.
+ *
+ * This is the mold-shaped boundary: every host-specific quirk of rendering
+ * RunsNative surfaces inside an agent host lives in this module (and the
+ * assets it inlines), NEVER in components. Contract:
+ * mukadra docs/contracts/agent-surface-packaging-contract-v1.md.
+ *
+ * Invariants:
+ * - The emitted document references ZERO external URLs. The component bundle,
+ *   the MCP Apps iframe runtime, and all CSS ride inside the document —
+ *   the host sandbox CSP blocks external loads (RUN-477 / in-host verify).
+ * - Data does NOT ride in the document. The shell is static; per-call data
+ *   arrives through the MCP Apps tool-result notification and is rendered
+ *   client-side with DOM APIs (textContent), never markup interpolation.
+ */
+// MIME type for MCP App resources, per ext-apps (RESOURCE_MIME_TYPE). Kept as
+// a literal so this module stays dependency-free and pure.
+export const SURFACE_MIME_TYPE = 'text/html;profile=mcp-app';
+export function escapeHtml(s) {
+    return String(s ?? '')
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+// A closing </script> inside inlined JS text would terminate the surrounding
+// script element early and let the remainder parse as markup. Break the
+// sequence — safe inside JS strings and regexes alike.
+function escapeInlineScript(js) {
+    return js.replace(/<\/script/gi, '<\\/script');
+}
+function escapeInlineStyle(css) {
+    return css.replace(/<\/style/gi, '<\\/style');
+}
+/**
+ * Package a surface into a single self-contained HTML document.
+ * Pure function: assets are injected so tests need no network or filesystem.
+ */
+export function packageSurface(input, assets) {
+    const { title, bodyHtml, css, appScript } = input;
+    return `<!DOCTYPE html>
+<html lang="en" data-run-mode="light">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(title)}</title>
+<style>${escapeInlineStyle(css ?? '')}</style>
+</head>
+<body>
+${bodyHtml}
+<script type="module">${escapeInlineScript(assets.componentsBundle)}</script>
+<script>${escapeInlineScript(assets.iframeRuntime)}</script>
+<script type="module">${escapeInlineScript(appScript ?? '')}</script>
+</body>
+</html>`;
+}