@tuongaz/seeflow 0.1.76 → 0.1.80

package/src/cors.ts

@@ -0,0 +1,93 @@
+// Studio CORS + per-process token gate.
+//
+// The MCP App iframe (Claude Desktop) lives in a sandboxed `Origin: null`
+// frame. To prevent drive-by access from other localhost software, every
+// `null`-origin request must carry the per-process token in the
+// `X-Seeflow-Token` header. The token is delivered to the iframe via
+// `_meta['openai/widgetState'].backendToken` from the MCP tool response —
+// no other channel exists, so other localhost processes can't observe it.
+//
+// Other origins:
+//   - Missing Origin (server-side fetches, integration tests, top-level
+//     navigation): pass through with no CORS headers.
+//   - Localhost / 127.0.0.1 / [::1] (any port, dev SPA): allow with CORS
+//     headers so cross-origin XHR (Tailscale + multi-port dev) still works.
+//   - Other origins: pass through with no CORS headers — the browser's
+//     own CORS policy blocks cross-origin XHR. We don't 403 them because
+//     the dev workflow runs over Tailscale hostnames and we don't want to
+//     hard-code that allowlist server-side.
+//
+// Preflight rules: `OPTIONS` from a null origin is allowed unconditionally
+// (the browser can't put `X-Seeflow-Token` on a preflight — it goes in
+// `Access-Control-Request-Headers` instead). The browser will then issue
+// the actual request carrying the token, and THAT one is gated.
+
+import { timingSafeEqual } from 'node:crypto';
+import type { Context, Next } from 'hono';
+
+const LOCALHOST_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+const ALLOWED_HEADERS = 'Content-Type, X-Seeflow-Token';
+const ALLOWED_METHODS = 'GET, POST, PUT, PATCH, DELETE, OPTIONS';
+const TOKEN_HEADER = 'x-seeflow-token';
+
+const isLocalhostOrigin = (origin: string): boolean => {
+  try {
+    const url = new URL(origin);
+    return LOCALHOST_HOSTS.has(url.hostname);
+  } catch {
+    return false;
+  }
+};
+
+// Constant-time comparison to keep timing attacks off the table. 128-bit
+// UUIDs make this overkill in practice, but `timingSafeEqual` is cheap and
+// removes the question entirely.
+const tokensMatch = (a: string, b: string): boolean => {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+};
+
+const setAllowedHeaders = (c: Context, origin: string): void => {
+  c.header('Access-Control-Allow-Origin', origin);
+  c.header('Vary', 'Origin');
+  c.header('Access-Control-Allow-Headers', ALLOWED_HEADERS);
+  c.header('Access-Control-Allow-Methods', ALLOWED_METHODS);
+};
+
+export const createCorsMiddleware = (token: string | undefined) => {
+  return async (c: Context, next: Next) => {
+    const origin = c.req.header('origin');
+    if (!origin) {
+      await next();
+      return;
+    }
+
+    if (origin === 'null') {
+      if (c.req.method === 'OPTIONS') {
+        setAllowedHeaders(c, origin);
+        return c.body(null, 204);
+      }
+      const reqToken = c.req.header(TOKEN_HEADER);
+      if (!token || !reqToken || !tokensMatch(reqToken, token)) {
+        return c.text('Forbidden', 403);
+      }
+      setAllowedHeaders(c, origin);
+      await next();
+      return;
+    }
+
+    if (isLocalhostOrigin(origin)) {
+      setAllowedHeaders(c, origin);
+      if (c.req.method === 'OPTIONS') {
+        return c.body(null, 204);
+      }
+      await next();
+      return;
+    }
+
+    // Non-localhost, non-null origin: no CORS headers. Browser blocks the
+    // cross-origin read; the request still reaches the route handler for
+    // server-side / same-origin-by-port scenarios.
+    await next();
+  };
+};

package/src/jq-filter.ts

@@ -0,0 +1,253 @@
+// Minimal jq-style path filter for `seeflow schema --jq <filter>`. Path
+// subset only: identity, field access (`.foo.bar`), bracket access
+// (`.["foo"]`, `.[3]`), iteration (`.[]`), optional (`?`), and pipe (`|`).
+// No comma, no `length`, no functions — keep the surface tight so behaviour
+// matches the real jq tool for the subset we do support. Throws JqError on
+// parse failures and on type errors that the trailing `?` did not suppress.
+
+export class JqError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'JqError';
+  }
+}
+
+type Step =
+  | { kind: 'field'; name: string; optional: boolean }
+  | { kind: 'index'; index: number; optional: boolean }
+  | { kind: 'key'; key: string; optional: boolean }
+  | { kind: 'iter'; optional: boolean };
+
+type Term = Step[];
+type Filter = Term[];
+
+const isIdentStart = (ch: string): boolean => /[A-Za-z_]/.test(ch);
+const isIdent = (ch: string): boolean => /[A-Za-z0-9_]/.test(ch);
+
+function parseFilter(src: string): Filter {
+  const input = src;
+  let i = 0;
+  const len = input.length;
+
+  const skipSpace = (): void => {
+    while (i < len && /\s/.test(input[i] as string)) i++;
+  };
+
+  const expect = (ch: string): void => {
+    if (input[i] !== ch) {
+      throw new JqError(
+        `Expected '${ch}' at position ${i} in filter '${src}' (got '${input[i] ?? '<end>'}')`,
+      );
+    }
+    i++;
+  };
+
+  const parseString = (): string => {
+    const quote = input[i];
+    if (quote !== '"' && quote !== "'") {
+      throw new JqError(`Expected string at position ${i} in filter '${src}'`);
+    }
+    i++;
+    let out = '';
+    while (i < len && input[i] !== quote) {
+      const ch = input[i] as string;
+      if (ch === '\\') {
+        const next = input[i + 1];
+        if (next === undefined) throw new JqError(`Unterminated escape in filter '${src}'`);
+        out += next;
+        i += 2;
+        continue;
+      }
+      out += ch;
+      i++;
+    }
+    if (input[i] !== quote) throw new JqError(`Unterminated string in filter '${src}'`);
+    i++;
+    return out;
+  };
+
+  const parseNumber = (): number => {
+    const start = i;
+    if (input[i] === '-') i++;
+    while (i < len && /[0-9]/.test(input[i] as string)) i++;
+    const raw = input.slice(start, i);
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n)) {
+      throw new JqError(`Invalid number '${raw}' at position ${start} in filter '${src}'`);
+    }
+    return n;
+  };
+
+  const parseOptional = (): boolean => {
+    if (input[i] === '?') {
+      i++;
+      return true;
+    }
+    return false;
+  };
+
+  const parseTerm = (): Term => {
+    skipSpace();
+    if (input[i] !== '.') {
+      throw new JqError(
+        `Filter term must start with '.' at position ${i} in filter '${src}' (got '${input[i] ?? '<end>'}')`,
+      );
+    }
+    i++;
+    const steps: Step[] = [];
+    // `.` followed by ident, `[`, or end/operator → first step.
+    while (i < len) {
+      const ch = input[i] as string;
+      if (ch === '.') {
+        // Chained field: ".foo.bar" — consume the dot and read ident.
+        i++;
+        if (i >= len || !isIdentStart(input[i] as string)) {
+          throw new JqError(`Expected identifier after '.' at position ${i} in filter '${src}'`);
+        }
+        const start = i;
+        while (i < len && isIdent(input[i] as string)) i++;
+        const name = input.slice(start, i);
+        const optional = parseOptional();
+        steps.push({ kind: 'field', name, optional });
+      } else if (isIdentStart(ch)) {
+        // First step right after leading '.', e.g. ".foo".
+        if (steps.length > 0) {
+          throw new JqError(`Unexpected identifier at position ${i} in filter '${src}'`);
+        }
+        const start = i;
+        while (i < len && isIdent(input[i] as string)) i++;
+        const name = input.slice(start, i);
+        const optional = parseOptional();
+        steps.push({ kind: 'field', name, optional });
+      } else if (ch === '[') {
+        i++;
+        skipSpace();
+        if (input[i] === ']') {
+          i++;
+          const optional = parseOptional();
+          steps.push({ kind: 'iter', optional });
+        } else if (input[i] === '"' || input[i] === "'") {
+          const key = parseString();
+          skipSpace();
+          expect(']');
+          const optional = parseOptional();
+          steps.push({ kind: 'key', key, optional });
+        } else if (input[i] === '-' || /[0-9]/.test(input[i] ?? '')) {
+          const index = parseNumber();
+          skipSpace();
+          expect(']');
+          const optional = parseOptional();
+          steps.push({ kind: 'index', index, optional });
+        } else {
+          throw new JqError(`Expected index, string, or ']' at position ${i} in filter '${src}'`);
+        }
+      } else {
+        break;
+      }
+    }
+    return steps;
+  };
+
+  const terms: Term[] = [];
+  skipSpace();
+  terms.push(parseTerm());
+  skipSpace();
+  while (i < len) {
+    if (input[i] !== '|') {
+      throw new JqError(`Unexpected character '${input[i]}' at position ${i} in filter '${src}'`);
+    }
+    i++;
+    skipSpace();
+    terms.push(parseTerm());
+    skipSpace();
+  }
+  if (terms.length === 0) {
+    throw new JqError(`Empty filter '${src}'`);
+  }
+  return terms;
+}
+
+function evaluateStep(step: Step, value: unknown): unknown[] {
+  if (step.kind === 'field') {
+    if (value === null || value === undefined) {
+      if (step.optional) return [];
+      return [null];
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+      if (step.optional) return [];
+      throw new JqError(
+        `Cannot index ${describeType(value)} with field '${step.name}' (use '?' to suppress)`,
+      );
+    }
+    const obj = value as Record<string, unknown>;
+    return [Object.hasOwn(obj, step.name) ? obj[step.name] : null];
+  }
+  if (step.kind === 'key') {
+    if (value === null || value === undefined) {
+      if (step.optional) return [];
+      return [null];
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+      if (step.optional) return [];
+      throw new JqError(
+        `Cannot index ${describeType(value)} with key "${step.key}" (use '?' to suppress)`,
+      );
+    }
+    const obj = value as Record<string, unknown>;
+    return [Object.hasOwn(obj, step.key) ? obj[step.key] : null];
+  }
+  if (step.kind === 'index') {
+    if (value === null || value === undefined) {
+      if (step.optional) return [];
+      return [null];
+    }
+    if (!Array.isArray(value)) {
+      if (step.optional) return [];
+      throw new JqError(
+        `Cannot index ${describeType(value)} with number ${step.index} (use '?' to suppress)`,
+      );
+    }
+    const idx = step.index < 0 ? value.length + step.index : step.index;
+    return [idx >= 0 && idx < value.length ? value[idx] : null];
+  }
+  // iter
+  if (value === null || value === undefined) {
+    if (step.optional) return [];
+    throw new JqError(`Cannot iterate over ${describeType(value)} (use '?' to suppress)`);
+  }
+  if (Array.isArray(value)) return [...value];
+  if (typeof value === 'object') return Object.values(value as Record<string, unknown>);
+  if (step.optional) return [];
+  throw new JqError(`Cannot iterate over ${describeType(value)} (use '?' to suppress)`);
+}
+
+function evaluateTerm(term: Term, input: unknown): unknown[] {
+  let stream: unknown[] = [input];
+  for (const step of term) {
+    const next: unknown[] = [];
+    for (const v of stream) {
+      for (const out of evaluateStep(step, v)) next.push(out);
+    }
+    stream = next;
+  }
+  return stream;
+}
+
+function describeType(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+export function applyJq(input: unknown, filterStr: string): unknown[] {
+  const filter = parseFilter(filterStr);
+  let stream: unknown[] = [input];
+  for (const term of filter) {
+    const next: unknown[] = [];
+    for (const v of stream) {
+      for (const out of evaluateTerm(term, v)) next.push(out);
+    }
+    stream = next;
+  }
+  return stream;
+}

package/src/mcp-shim.ts

@@ -1,13 +1,25 @@
 #!/usr/bin/env bun
 // SeeFlow MCP stdio shim.
 //
-// Bridges an MCP stdio client (e.g. Claude Code via .mcp.json) to the studio's
-// HTTP `/mcp` endpoint. Every JSON-RPC message received on stdin is forwarded
-// to the studio via a Streamable HTTP MCP client transport; every response is
-// piped back to stdout. The shim never interprets tool semantics — it's a
-// transparent JSON-RPC proxy keyed off message ids.
+// Bridges an MCP stdio client (e.g. Claude Code via .mcp.json) to a studio
+// backend. Two modes:
+//   1. Embedded (default): boots an in-process Hono studio on an ephemeral
+//      loopback port and proxies stdio JSON-RPC to its /mcp endpoint. The
+//      iframe canvas rendered by MCP-Apps-capable hosts also connects to
+//      this same port. One process, one install.
+//   2. Proxy (when SEEFLOW_STUDIO_URL is set): forwards stdio JSON-RPC to
+//      an externally-running studio. Backward-compatible with the existing
+//      shim tests and dev workflows where `seeflow studio` already runs.
 //
-// Default target: http://127.0.0.1:4321/mcp. Override with SEEFLOW_STUDIO_URL.
+// In embedded mode the port is bound BEFORE the stdio transport starts so
+// downstream tool handlers (US-008) can attach the backendUrl to _meta. If
+// port binding fails, the shim emits an MCP `notifications/message` over
+// stdout and falls back to the default proxy URL — the canvas won't render
+// but tool calls still flow (degraded, not crashed).
+//
+// Lifecycle: SIGINT, SIGTERM, beforeExit, and the stdio transport's
+// onclose all release the ephemeral port via server.stop(true). Integration
+// coverage lives in apps/studio/integration/mcp-shim-lifecycle.it.ts.
 
 import {
   StreamableHTTPClientTransport,
@@ -15,12 +27,81 @@ import {
 } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { type JSONRPCMessage, isJSONRPCRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { Server as BunHttpServer } from 'bun';
+import { type CreateAppOptions, createApp } from './server.ts';
+
+// Bun's generic Server requires a websocket-data type argument at the type
+// level; we don't attach a websocket handler so `unknown` is the right slot.
+type EphemeralServer = BunHttpServer<unknown>;
 
 const DEFAULT_URL = 'http://127.0.0.1:4321/mcp';
 const STUDIO_NOT_RUNNING_MSG = 'SeeFlow studio is not running. Start it with `bun run dev` first.';
 const STUDIO_WITHOUT_MCP_MSG = 'This studio version does not expose MCP. Upgrade required.';
 
-const url = new URL(process.env.SEEFLOW_STUDIO_URL ?? DEFAULT_URL);
+// Treat empty string the same as unset. Spawning subprocesses with an
+// explicit `SEEFLOW_STUDIO_URL: ''` is the cleanest way to clear an
+// inherited value from the parent env without `delete` semantics, so the
+// shim has to handle that path the same as truly absent.
+const explicitStudioUrl = process.env.SEEFLOW_STUDIO_URL?.trim() || undefined;
+
+// Emit an MCP `notifications/message` over stdout. JSON-RPC notifications
+// have no id; clients route them to a logging sink. Used by the bind-
+// failure path so the host surfaces a real error instead of silently
+// proxying to a dead address.
+const emitMcpNotification = (level: 'error' | 'warning' | 'info', data: string): void => {
+  const notification = {
+    jsonrpc: '2.0',
+    method: 'notifications/message',
+    params: { level, logger: 'seeflow-mcp', data },
+  };
+  process.stdout.write(`${JSON.stringify(notification)}\n`);
+};
+
+// Embedded studio handle. Undefined in proxy mode (SEEFLOW_STUDIO_URL set)
+// and when port binding fails. Lifecycle hooks below null-check before
+// calling .stop().
+let embeddedServer: EphemeralServer | undefined;
+let embeddedUrl: string | undefined;
+
+if (!explicitStudioUrl) {
+  try {
+    // Per-process token: generated once at shim boot, held in memory,
+    // never persisted, never logged. The MCP App iframe receives it via
+    // `_meta['openai/widgetState'].backendToken` (US-008) and replays it
+    // on every cross-origin request as `X-Seeflow-Token`. Anything else
+    // hitting the ephemeral port from `Origin: null` (other localhost
+    // software, drive-by tabs) gets 403'd by the CORS middleware.
+    const token = crypto.randomUUID();
+    // Hold a mutable options reference so we can fill in `httpUrl` AFTER
+    // `Bun.serve` binds — the per-request `/mcp` handler captures
+    // `options` by closure, so the canvas-bearing tools (US-008) read
+    // the live URL when building their `_meta.backendUrl`. Without this
+    // back-fill the closure would observe `httpUrl: undefined` and skip
+    // `_meta` entirely.
+    const appOptions: CreateAppOptions = { token };
+    const app = createApp(appOptions);
+    embeddedServer = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: app.fetch });
+    embeddedUrl = `http://${embeddedServer.hostname}:${embeddedServer.port}`;
+    appOptions.httpUrl = embeddedUrl;
+    // Log the bound URL to stderr so the integration test (and humans
+    // debugging) can discover the port without interleaving with the
+    // JSON-RPC stdout stream. Intentionally omits the token — it MUST
+    // stay in-memory only; printing it to stderr would leak it into any
+    // log scrape that captures the subprocess's stderr.
+    process.stderr.write(`[seeflow-mcp] studio listening on ${embeddedUrl}\n`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    emitMcpNotification(
+      'error',
+      `Failed to bind ephemeral HTTP port for studio: ${msg}. Falling back to ${DEFAULT_URL} (canvas widgets will not render).`,
+    );
+    embeddedServer = undefined;
+    embeddedUrl = undefined;
+  }
+}
+
+const targetUrl = explicitStudioUrl ?? (embeddedUrl ? `${embeddedUrl}/mcp` : DEFAULT_URL);
+const url = new URL(targetUrl);
 
 const stdio = new StdioServerTransport();
 const http = new StreamableHTTPClientTransport(url);
@@ -81,13 +162,39 @@ stdio.onmessage = async (msg) => {
   }
 };
 
+// Tear-down: release the ephemeral port on every exit path so the loopback
+// slot doesn't stay claimed after the parent host kills the subprocess.
+// Bun.Server.stop(true) is synchronous + idempotent — safe to call from
+// multiple lifecycle hooks.
+let serverStopped = false;
+const stopEmbeddedServer = (): void => {
+  if (serverStopped || !embeddedServer) return;
+  serverStopped = true;
+  try {
+    embeddedServer.stop(true);
+  } catch {
+    /* already stopped */
+  }
+};
+
 await http.start();
 await stdio.start();
 
+// The stdio transport sets `onclose` to undefined by default; chain our
+// teardown so a parent killing the pipe still frees the port.
+const stdioOnClose = stdio.onclose;
+stdio.onclose = () => {
+  stopEmbeddedServer();
+  stdioOnClose?.();
+};
+
 const shutdown = async () => {
   await stdio.close().catch(() => undefined);
   await http.close().catch(() => undefined);
+  stopEmbeddedServer();
   process.exit(0);
 };
+
 process.on('SIGINT', () => void shutdown());
 process.on('SIGTERM', () => void shutdown());
+process.on('beforeExit', () => stopEmbeddedServer());

package/src/mcp-ui.ts

@@ -0,0 +1,126 @@
+// MCP Apps UI resource glue for SeeFlow.
+//
+// The MCP-Apps host (Claude Desktop, ChatGPT) renders an iframe whose HTML
+// payload is served via the MCP `resources/read` channel under a stable
+// `ui://` URI. Canvas-bearing tool handlers attach an `_meta` block to their
+// CallToolResult pointing the host at that URI plus an initial widget state.
+//
+// This module centralises three concerns so the wiring in mcp.ts stays thin:
+//   1. The single canonical resource URI for the canvas bundle.
+//   2. A cached reader for the built `apps/mcp-app/dist/index.html` (the
+//      single-file Vite output produced by US-001..US-004).
+//   3. `canvasMeta(state)` — the `_meta` payload the host expects for a
+//      canvas-bearing tool result.
+//
+// The actual `_meta` attachment on each of the 5 canvas-bearing tools lives
+// in US-008. Non-canvas tools never see this module.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Canonical resource URI for the SeeFlow canvas iframe bundle. Hosts that
+ * speak MCP Apps fetch this via `resources/read` to obtain the HTML payload
+ * for the embedded canvas. Tool results reference it via
+ * `_meta['openai/outputTemplate']`.
+ */
+export const CANVAS_RESOURCE_URI = 'ui://seeflow/canvas';
+
+/**
+ * MIME type the MCP-Apps host expects for the canvas bundle. The
+ * `+skybridge` suffix opts the iframe into the host's structured message
+ * channel (`window.openai.sendMessage` / `updateModelContext`).
+ */
+export const CANVAS_RESOURCE_MIME = 'text/html+skybridge';
+
+/**
+ * Widget state delivered to the iframe via `_meta['openai/widgetState']`.
+ *
+ * Mirrors `WidgetState` in `apps/mcp-app/src/bridge.ts` — kept in sync but
+ * duplicated (rather than imported across the workspace boundary) so the
+ * studio doesn't pick up `react`/`react-dom` as a transitive dependency.
+ * When you change one, change the other in the same commit.
+ *
+ *  - `kind: 'navigate'` — the model just inspected a flow/node, render it.
+ *    `projectSlug` + `flowSlug` are both required so the iframe addresses
+ *    the flow via `/api/projects/:project/flows/:flow` without an extra
+ *    lookup round-trip.
+ *  - `kind: 'create'`   — the model just scaffolded a project or registered
+ *    a flow. Either or both slugs may be present (project-only when there's
+ *    no flow yet); `justCreated: true` enables the brief mount-time pill.
+ */
+export type CanvasWidgetState =
+  | {
+      kind: 'navigate';
+      projectSlug: string;
+      flowSlug: string;
+      nodeId?: string;
+      backendUrl: string;
+      backendToken: string;
+    }
+  | {
+      kind: 'create';
+      projectSlug?: string;
+      flowSlug?: string;
+      nodeId?: string;
+      backendUrl: string;
+      backendToken: string;
+      justCreated?: boolean;
+    };
+
+/** Lazy-resolved absolute path to the built iframe HTML. Resolved through
+ *  `import.meta.resolve` so the path is stable whether the studio runs from
+ *  the source tree (dev) or from the published `@tuongaz/seeflow` package
+ *  (where `apps/mcp-app/dist/index.html` is bundled into the tarball). */
+const resolveCanvasHtmlPath = (): string =>
+  fileURLToPath(import.meta.resolve('../../mcp-app/dist/index.html'));
+
+let cachedHtml: string | undefined;
+let cachedPath: string | undefined;
+
+/**
+ * Read the built MCP App iframe bundle. Cached after the first successful
+ * read — the bundle is immutable for the lifetime of the studio process
+ * (the only way to refresh it is to rebuild and restart).
+ *
+ * Throws a clear error pointing at the build step when the dist file is
+ * missing, so a user who forgot `bun run --filter @seeflow/mcp-app build`
+ * gets a one-line fix instead of an ENOENT trace.
+ */
+export function readCanvasHtml(): string {
+  if (cachedHtml !== undefined) return cachedHtml;
+  if (cachedPath === undefined) cachedPath = resolveCanvasHtmlPath();
+  if (!existsSync(cachedPath)) {
+    throw new Error(
+      `MCP App bundle not found at ${cachedPath}. Run 'bun run --filter @seeflow/mcp-app build' to produce it.`,
+    );
+  }
+  cachedHtml = readFileSync(cachedPath, 'utf8');
+  return cachedHtml;
+}
+
+/** Test seam: drop the cached HTML so the next `readCanvasHtml()` call
+ *  re-reads the file from disk. Exported for unit tests that mock the
+ *  filesystem; never called in production code. */
+export function __resetCanvasHtmlCache(): void {
+  cachedHtml = undefined;
+  cachedPath = undefined;
+}
+
+/**
+ * Build the `_meta` payload for a canvas-bearing tool result. The three
+ * keys are the contract the MCP-Apps host introspects:
+ *
+ * - `openai/outputTemplate` → which UI resource to render.
+ * - `openai/widgetState`    → initial state injected as
+ *                             `window.openai.widgetState` in the iframe.
+ * - `openai/widgetAccessible` → declares the widget reads the model
+ *                               context (so the host wires the bridge).
+ */
+export function canvasMeta(state: CanvasWidgetState): Record<string, unknown> {
+  return {
+    'openai/outputTemplate': CANVAS_RESOURCE_URI,
+    'openai/widgetState': state,
+    'openai/widgetAccessible': true,
+  };
+}