@maravilla-labs/platform 0.11.1 → 0.13.0

package/dist/mcp.d.ts

@@ -149,26 +149,33 @@ interface McpServerSpec {
      */
     public?: boolean;
     /**
-     * Mini-app UI templates referenced by tools via `ui.template`. Each maps a
-     * template `name` to `htmlPath` — a **self-contained single-file HTML widget**
-     * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`). Output the
-     * build into your app's **static assets** and point `htmlPath` at that
-     * deploy-relative path (e.g. `static/mcp-ui/reader.html`), built BEFORE the app
-     * build — so the framework ships it as a normal static asset. The runtime reads
-     * those bytes and serves them as the `ui://<tool>/<template>` resource
-     * (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT) renders inline
-     * — the MCP Apps standard. The widget receives its data over the MCP Apps
-     * channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →
-     * `structuredContent`), not via cookies.
+     * Mini-app UI templates referenced by tools via `ui.template`. Each renders a
+     * tool result as a **self-contained single-file HTML widget** the runtime
+     * serves inline as the `ui://<tool>/<template>` resource
+     * (`text/html;profile=mcp-app`) — the MCP Apps standard — which the host
+     * (Claude, ChatGPT) renders in a sandboxed iframe. The widget receives its
+     * data over the MCP Apps channel (`@modelcontextprotocol/ext-apps`,
+     * `ontoolresult` → `structuredContent`), not via cookies.
      *
-     * `csp` declares the resource's Content-Security-Policy as
-     * {@link McpUiResourceCsp} (emitted at `_meta.ui.csp`): list the external
-     * origins the widget may load — e.g. `resourceDomains` for images/fonts the
-     * widget references. Omit for a fully self-contained widget.
+     * **The build is automatic.** Put the widget *source* in `mcp-ui/<name>/`
+     * (or `src/mcp-ui/<name>/`) — `index.html` + your component + `app.css` with
+     * `@import 'tailwindcss';` — and the platform compiles it to a single inlined
+     * file during `maravilla build` (framework plugin + Tailwind + singlefile, all
+     * resolved for you). No second Vite config, no build script, no `@source`. See
+     * the `mcp-ui-mini-app` recipe.
+     *
+     * - `entry` — override the source location (a dir or an `index.html`); defaults
+     *   to the `mcp-ui/<name>/` convention.
+     * - `htmlPath` — *legacy* escape hatch: point at a pre-built single-file under
+     *   `static/` you build yourself. Prefer the convention.
+     * - `csp` — the resource's Content-Security-Policy ({@link McpUiResourceCsp},
+     *   emitted at `_meta.ui.csp`): external origins the widget may load (e.g.
+     *   `resourceDomains` for remote images). Omit for a self-contained widget.
      */
     uiTemplates?: Array<{
         name: string;
-        htmlPath: string;
+        entry?: string;
+        htmlPath?: string;
         csp?: McpUiResourceCsp;
     }>;
 }

package/dist/mcp.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mcp.ts"],"sourcesContent":["/**\n * @fileoverview MCP tool authoring helpers for Maravilla.\n *\n * User apps declare MCP tools in `mcp.ts` or `mcp/*.ts`:\n *\n * ```ts\n * import { defineMcpTool, defineMcpServer } from '@maravilla-labs/platform/mcp';\n *\n * export const server = defineMcpServer({\n *   name: 'Acme Tools',\n *   version: '1.0.0',\n *   instructions: 'Tools for managing Acme orders.',\n *   uiTemplates: [{ name: 'order-card', route: '/_mcp/ui/order-card' }],\n * });\n *\n * export const getOrder = defineMcpTool(\n *   {\n *     name: 'get_order',\n *     description: 'Look up an order by id.',\n *     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },\n *     scopes: ['acme:read'],\n *     ui: { template: 'order-card' },\n *   },\n *   async (args, ctx) => {\n *     const order = await ctx.database.findOne('orders', { _id: args.id });\n *     return { content: [{ type: 'text', text: JSON.stringify(order) }] };\n *   },\n * );\n * ```\n *\n * These helpers are pure factories. `defineMcpTool` produces a\n * `RegisteredMcpTool` marker object that the build pipeline\n * (`@maravilla-labs/functions` `buildMcp`) detects by its `__maravilla_mcp`\n * property; `defineMcpServer` produces a `RegisteredMcpServer` detected by\n * `__maravilla_mcp_server`. The generated bundle exposes\n * `globalThis.handleMcpTool(toolId, args, ctx)`; the Rust MCP dispatcher\n * (`crates/platform/src/mcp/dispatch.rs`) drives it via a synthetic request\n * whose body is `{ tool_id, args, identity }`.\n */\n\n// ============ Tool handler context ============\n\n/**\n * Context handed to every MCP tool handler. The first seven services mirror\n * the events `EventCtx` (and `globalThis.platform`) exactly. `user`/`client`\n * carry the authenticated identity behind the OAuth token or API key so the\n * handler — and the platform ops it calls — run as the real end-user.\n */\nexport interface McpToolContext {\n  /** Per-tenant env vars. */\n  env: Record<string, string>;\n  /** KV store — same shape as `getPlatform().env.KV` / `platform.kv`. */\n  kv?: unknown;\n  /** MongoDB-style database — same shape as `getPlatform().env.DB`. */\n  database?: unknown;\n  /** Object storage. */\n  storage?: unknown;\n  /** Durable queue producer (`.send(name, payload, opts?)`). */\n  queue?: { send: (name: string, payload: unknown, opts?: unknown) => Promise<string> };\n  /** Auth service — register/login/logout/user CRUD/etc. */\n  auth?: unknown;\n  /** Web Push service. */\n  push?: unknown;\n  /** Full platform object — escape hatch for services not surfaced above. */\n  platform?: unknown;\n  /** Tenant identifier. */\n  tenant: string;\n  /** Trace correlation id — propagate through logs. */\n  traceId: string;\n  /** The end-user behind the token/key, or `null` for a client-only call. */\n  user: { id: string; email: string; groups: string[]; scopes: string[] } | null;\n  /** The OAuth client (agent) that authenticated, when known. */\n  client: { id: string } | null;\n}\n\n// ============ Tool result shapes ============\n\n/** A single content item returned by a tool. */\nexport type McpContentItem =\n  | { type: 'text'; text: string }\n  | { type: 'json'; json: unknown }\n  | { type: 'resource'; resource: Record<string, unknown> };\n\n/**\n * What a tool handler may return:\n * - `{ content }` — explicit MCP content items.\n * - `{ ui }` — render an iframe mini-app template (§7); optional `content`\n *   is shown alongside for clients that don't support the UI.\n * - any other value — wrapped as a single `text` content item.\n */\nexport type McpToolResult =\n  | { content: McpContentItem[] }\n  | { ui: { template: string; data?: unknown }; content?: McpContentItem[] }\n  | unknown;\n\n// ============ Registered markers ============\n\nexport const MCP_TOOL_SYMBOL = '__maravilla_mcp' as const;\nexport const MCP_SERVER_SYMBOL = '__maravilla_mcp_server' as const;\n\n/** Spec passed to {@link defineMcpTool}. */\nexport interface McpToolSpec {\n  /** Tool name surfaced to the client (defaults to the export name). */\n  name: string;\n  /** Human-readable description sent in `tools/list`. */\n  description: string;\n  /** JSON Schema for the tool input, sent verbatim in `tools/list`. */\n  inputSchema: Record<string, unknown>;\n  /** Required scopes; dispatch enforces `scopes ⊆ identity.scopes`. */\n  scopes?: string[];\n  /**\n   * Per-tool public opt-in. When `true`, this tool is callable with an\n   * anonymous identity (no bearer) even on an otherwise-private server — its\n   * `scopes` must still be a subset of the caller's, so an anonymous caller can\n   * only reach it when it declares no scopes. Defaults to `false`.\n   */\n  public?: boolean;\n  /** Links this tool to a UI template declared on the server (§7). */\n  ui?: { template: string };\n}\n\nexport interface RegisteredMcpTool {\n  readonly [MCP_TOOL_SYMBOL]: McpToolSpec;\n  readonly handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>;\n}\n\n/** Spec passed to {@link defineMcpServer}. */\nexport interface McpServerSpec {\n  /** Human-readable server name (e.g. \"Acme Tools\"). */\n  name: string;\n  /** Optional semantic version. */\n  version?: string;\n  /** Optional natural-language usage instructions for the client/model. */\n  instructions?: string;\n  /**\n   * Server-level public flag. When `true`, unauthenticated MCP requests build\n   * an anonymous identity (instead of a 401) so `initialize` / `tools/list` and\n   * any no-scope tool work without a bearer. Per-tool `public` opt-in still\n   * works on an otherwise-private server. Defaults to `false`.\n   */\n  public?: boolean;\n  /**\n   * Mini-app UI templates referenced by tools via `ui.template`. Each maps a\n   * template `name` to `htmlPath` — a **self-contained single-file HTML widget**\n   * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`). Output the\n   * build into your app's **static assets** and point `htmlPath` at that\n   * deploy-relative path (e.g. `static/mcp-ui/reader.html`), built BEFORE the app\n   * build — so the framework ships it as a normal static asset. The runtime reads\n   * those bytes and serves them as the `ui://<tool>/<template>` resource\n   * (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT) renders inline\n   * — the MCP Apps standard. The widget receives its data over the MCP Apps\n   * channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →\n   * `structuredContent`), not via cookies.\n   *\n   * `csp` declares the resource's Content-Security-Policy as\n   * {@link McpUiResourceCsp} (emitted at `_meta.ui.csp`): list the external\n   * origins the widget may load — e.g. `resourceDomains` for images/fonts the\n   * widget references. Omit for a fully self-contained widget.\n   */\n  uiTemplates?: Array<{ name: string; htmlPath: string; csp?: McpUiResourceCsp }>;\n}\n\n/**\n * Content-Security-Policy for a UI template resource, emitted at the resource's\n * `_meta.ui.csp` (the MCP Apps contract). The host derives CSP directives from\n * these origin lists; omitting a list blocks that class of request.\n */\nexport interface McpUiResourceCsp {\n  /** `connect-src` — fetch / XHR / WebSocket origins. */\n  connectDomains?: string[];\n  /** `img-src` / `script-src` / `style-src` / `font-src` / `media-src` — static\n   *  resource origins. Supports wildcard subdomains, e.g. `https://*.example.com`. */\n  resourceDomains?: string[];\n  /** `frame-src` — origins allowed in nested iframes. */\n  frameDomains?: string[];\n  /** `base-uri` — allowed document base URIs. */\n  baseUriDomains?: string[];\n}\n\nexport interface RegisteredMcpServer {\n  readonly [MCP_SERVER_SYMBOL]: McpServerSpec;\n}\n\n// ============ Public factory helpers ============\n\n/**\n * Declare an MCP tool. The runtime advertises it in `tools/list` (using\n * `name`, `description`, `inputSchema`) and dispatches `tools/call` to\n * `handler`, enforcing `scopes` against the caller's granted scopes.\n */\nexport function defineMcpTool(\n  spec: McpToolSpec,\n  handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>,\n): RegisteredMcpTool {\n  return { [MCP_TOOL_SYMBOL]: spec, handler };\n}\n\n/**\n * Declare the MCP server identity and its iframe mini-app templates.\n * Optional — at most one per app; the last one discovered wins.\n */\nexport function defineMcpServer(spec: McpServerSpec): RegisteredMcpServer {\n  return { [MCP_SERVER_SYMBOL]: spec };\n}\n\n/** Type guard used by the build-time discoverer and the runtime registry. */\nexport function isRegisteredMcpTool(value: unknown): value is RegisteredMcpTool {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_TOOL_SYMBOL in value &&\n    typeof (value as Record<string, unknown>).handler === 'function'\n  );\n}\n\n/** Type guard for a registered MCP server descriptor. */\nexport function isRegisteredMcpServer(value: unknown): value is RegisteredMcpServer {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_SERVER_SYMBOL in value\n  );\n}\n"],"mappings":";AAiGO,IAAM,kBAAkB;AACxB,IAAM,oBAAoB;AA4F1B,SAAS,cACd,MACA,SACmB;AACnB,SAAO,EAAE,CAAC,eAAe,GAAG,MAAM,QAAQ;AAC5C;AAMO,SAAS,gBAAgB,MAA0C;AACxE,SAAO,EAAE,CAAC,iBAAiB,GAAG,KAAK;AACrC;AAGO,SAAS,oBAAoB,OAA4C;AAC9E,SACE,OAAO,UAAU,YACjB,UAAU,QACV,mBAAmB,SACnB,OAAQ,MAAkC,YAAY;AAE1D;AAGO,SAAS,sBAAsB,OAA8C;AAClF,SACE,OAAO,UAAU,YACjB,UAAU,QACV,qBAAqB;AAEzB;","names":[]}
+{"version":3,"sources":["../src/mcp.ts"],"sourcesContent":["/**\n * @fileoverview MCP tool authoring helpers for Maravilla.\n *\n * User apps declare MCP tools in `mcp.ts` or `mcp/*.ts`:\n *\n * ```ts\n * import { defineMcpTool, defineMcpServer } from '@maravilla-labs/platform/mcp';\n *\n * export const server = defineMcpServer({\n *   name: 'Acme Tools',\n *   version: '1.0.0',\n *   instructions: 'Tools for managing Acme orders.',\n *   uiTemplates: [{ name: 'order-card', route: '/_mcp/ui/order-card' }],\n * });\n *\n * export const getOrder = defineMcpTool(\n *   {\n *     name: 'get_order',\n *     description: 'Look up an order by id.',\n *     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },\n *     scopes: ['acme:read'],\n *     ui: { template: 'order-card' },\n *   },\n *   async (args, ctx) => {\n *     const order = await ctx.database.findOne('orders', { _id: args.id });\n *     return { content: [{ type: 'text', text: JSON.stringify(order) }] };\n *   },\n * );\n * ```\n *\n * These helpers are pure factories. `defineMcpTool` produces a\n * `RegisteredMcpTool` marker object that the build pipeline\n * (`@maravilla-labs/functions` `buildMcp`) detects by its `__maravilla_mcp`\n * property; `defineMcpServer` produces a `RegisteredMcpServer` detected by\n * `__maravilla_mcp_server`. The generated bundle exposes\n * `globalThis.handleMcpTool(toolId, args, ctx)`; the Rust MCP dispatcher\n * (`crates/platform/src/mcp/dispatch.rs`) drives it via a synthetic request\n * whose body is `{ tool_id, args, identity }`.\n */\n\n// ============ Tool handler context ============\n\n/**\n * Context handed to every MCP tool handler. The first seven services mirror\n * the events `EventCtx` (and `globalThis.platform`) exactly. `user`/`client`\n * carry the authenticated identity behind the OAuth token or API key so the\n * handler — and the platform ops it calls — run as the real end-user.\n */\nexport interface McpToolContext {\n  /** Per-tenant env vars. */\n  env: Record<string, string>;\n  /** KV store — same shape as `getPlatform().env.KV` / `platform.kv`. */\n  kv?: unknown;\n  /** MongoDB-style database — same shape as `getPlatform().env.DB`. */\n  database?: unknown;\n  /** Object storage. */\n  storage?: unknown;\n  /** Durable queue producer (`.send(name, payload, opts?)`). */\n  queue?: { send: (name: string, payload: unknown, opts?: unknown) => Promise<string> };\n  /** Auth service — register/login/logout/user CRUD/etc. */\n  auth?: unknown;\n  /** Web Push service. */\n  push?: unknown;\n  /** Full platform object — escape hatch for services not surfaced above. */\n  platform?: unknown;\n  /** Tenant identifier. */\n  tenant: string;\n  /** Trace correlation id — propagate through logs. */\n  traceId: string;\n  /** The end-user behind the token/key, or `null` for a client-only call. */\n  user: { id: string; email: string; groups: string[]; scopes: string[] } | null;\n  /** The OAuth client (agent) that authenticated, when known. */\n  client: { id: string } | null;\n}\n\n// ============ Tool result shapes ============\n\n/** A single content item returned by a tool. */\nexport type McpContentItem =\n  | { type: 'text'; text: string }\n  | { type: 'json'; json: unknown }\n  | { type: 'resource'; resource: Record<string, unknown> };\n\n/**\n * What a tool handler may return:\n * - `{ content }` — explicit MCP content items.\n * - `{ ui }` — render an iframe mini-app template (§7); optional `content`\n *   is shown alongside for clients that don't support the UI.\n * - any other value — wrapped as a single `text` content item.\n */\nexport type McpToolResult =\n  | { content: McpContentItem[] }\n  | { ui: { template: string; data?: unknown }; content?: McpContentItem[] }\n  | unknown;\n\n// ============ Registered markers ============\n\nexport const MCP_TOOL_SYMBOL = '__maravilla_mcp' as const;\nexport const MCP_SERVER_SYMBOL = '__maravilla_mcp_server' as const;\n\n/** Spec passed to {@link defineMcpTool}. */\nexport interface McpToolSpec {\n  /** Tool name surfaced to the client (defaults to the export name). */\n  name: string;\n  /** Human-readable description sent in `tools/list`. */\n  description: string;\n  /** JSON Schema for the tool input, sent verbatim in `tools/list`. */\n  inputSchema: Record<string, unknown>;\n  /** Required scopes; dispatch enforces `scopes ⊆ identity.scopes`. */\n  scopes?: string[];\n  /**\n   * Per-tool public opt-in. When `true`, this tool is callable with an\n   * anonymous identity (no bearer) even on an otherwise-private server — its\n   * `scopes` must still be a subset of the caller's, so an anonymous caller can\n   * only reach it when it declares no scopes. Defaults to `false`.\n   */\n  public?: boolean;\n  /** Links this tool to a UI template declared on the server (§7). */\n  ui?: { template: string };\n}\n\nexport interface RegisteredMcpTool {\n  readonly [MCP_TOOL_SYMBOL]: McpToolSpec;\n  readonly handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>;\n}\n\n/** Spec passed to {@link defineMcpServer}. */\nexport interface McpServerSpec {\n  /** Human-readable server name (e.g. \"Acme Tools\"). */\n  name: string;\n  /** Optional semantic version. */\n  version?: string;\n  /** Optional natural-language usage instructions for the client/model. */\n  instructions?: string;\n  /**\n   * Server-level public flag. When `true`, unauthenticated MCP requests build\n   * an anonymous identity (instead of a 401) so `initialize` / `tools/list` and\n   * any no-scope tool work without a bearer. Per-tool `public` opt-in still\n   * works on an otherwise-private server. Defaults to `false`.\n   */\n  public?: boolean;\n  /**\n   * Mini-app UI templates referenced by tools via `ui.template`. Each renders a\n   * tool result as a **self-contained single-file HTML widget** the runtime\n   * serves inline as the `ui://<tool>/<template>` resource\n   * (`text/html;profile=mcp-app`) — the MCP Apps standard — which the host\n   * (Claude, ChatGPT) renders in a sandboxed iframe. The widget receives its\n   * data over the MCP Apps channel (`@modelcontextprotocol/ext-apps`,\n   * `ontoolresult` → `structuredContent`), not via cookies.\n   *\n   * **The build is automatic.** Put the widget *source* in `mcp-ui/<name>/`\n   * (or `src/mcp-ui/<name>/`) — `index.html` + your component + `app.css` with\n   * `@import 'tailwindcss';` — and the platform compiles it to a single inlined\n   * file during `maravilla build` (framework plugin + Tailwind + singlefile, all\n   * resolved for you). No second Vite config, no build script, no `@source`. See\n   * the `mcp-ui-mini-app` recipe.\n   *\n   * - `entry` — override the source location (a dir or an `index.html`); defaults\n   *   to the `mcp-ui/<name>/` convention.\n   * - `htmlPath` — *legacy* escape hatch: point at a pre-built single-file under\n   *   `static/` you build yourself. Prefer the convention.\n   * - `csp` — the resource's Content-Security-Policy ({@link McpUiResourceCsp},\n   *   emitted at `_meta.ui.csp`): external origins the widget may load (e.g.\n   *   `resourceDomains` for remote images). Omit for a self-contained widget.\n   */\n  uiTemplates?: Array<{ name: string; entry?: string; htmlPath?: string; csp?: McpUiResourceCsp }>;\n}\n\n/**\n * Content-Security-Policy for a UI template resource, emitted at the resource's\n * `_meta.ui.csp` (the MCP Apps contract). The host derives CSP directives from\n * these origin lists; omitting a list blocks that class of request.\n */\nexport interface McpUiResourceCsp {\n  /** `connect-src` — fetch / XHR / WebSocket origins. */\n  connectDomains?: string[];\n  /** `img-src` / `script-src` / `style-src` / `font-src` / `media-src` — static\n   *  resource origins. Supports wildcard subdomains, e.g. `https://*.example.com`. */\n  resourceDomains?: string[];\n  /** `frame-src` — origins allowed in nested iframes. */\n  frameDomains?: string[];\n  /** `base-uri` — allowed document base URIs. */\n  baseUriDomains?: string[];\n}\n\nexport interface RegisteredMcpServer {\n  readonly [MCP_SERVER_SYMBOL]: McpServerSpec;\n}\n\n// ============ Public factory helpers ============\n\n/**\n * Declare an MCP tool. The runtime advertises it in `tools/list` (using\n * `name`, `description`, `inputSchema`) and dispatches `tools/call` to\n * `handler`, enforcing `scopes` against the caller's granted scopes.\n */\nexport function defineMcpTool(\n  spec: McpToolSpec,\n  handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>,\n): RegisteredMcpTool {\n  return { [MCP_TOOL_SYMBOL]: spec, handler };\n}\n\n/**\n * Declare the MCP server identity and its iframe mini-app templates.\n * Optional — at most one per app; the last one discovered wins.\n */\nexport function defineMcpServer(spec: McpServerSpec): RegisteredMcpServer {\n  return { [MCP_SERVER_SYMBOL]: spec };\n}\n\n/** Type guard used by the build-time discoverer and the runtime registry. */\nexport function isRegisteredMcpTool(value: unknown): value is RegisteredMcpTool {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_TOOL_SYMBOL in value &&\n    typeof (value as Record<string, unknown>).handler === 'function'\n  );\n}\n\n/** Type guard for a registered MCP server descriptor. */\nexport function isRegisteredMcpServer(value: unknown): value is RegisteredMcpServer {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_SERVER_SYMBOL in value\n  );\n}\n"],"mappings":";AAiGO,IAAM,kBAAkB;AACxB,IAAM,oBAAoB;AAkG1B,SAAS,cACd,MACA,SACmB;AACnB,SAAO,EAAE,CAAC,eAAe,GAAG,MAAM,QAAQ;AAC5C;AAMO,SAAS,gBAAgB,MAA0C;AACxE,SAAO,EAAE,CAAC,iBAAiB,GAAG,KAAK;AACrC;AAGO,SAAS,oBAAoB,OAA4C;AAC9E,SACE,OAAO,UAAU,YACjB,UAAU,QACV,mBAAmB,SACnB,OAAQ,MAAkC,YAAY;AAE1D;AAGO,SAAS,sBAAsB,OAA8C;AAClF,SACE,OAAO,UAAU,YACjB,UAAU,QACV,qBAAqB;AAEzB;","names":[]}

package/dist/{transforms-DwCPOVTn.d.ts → transforms-CbM38kf7.d.ts}

@@ -43,6 +43,43 @@ interface ThumbnailOpts {
     format?: ImageFormat;
     quality?: number;
 }
+/**
+ * Options for `transforms.extractFrames` — decode a video into a sequence of
+ * still images at a fixed fps. General capability (any MP4 → frames); the
+ * frames renderer consumes the result to swap `<video>`→`<img>` per frame, and
+ * it's reusable for thumbnails/scrubbing.
+ */
+interface ExtractFramesOpts {
+    /** Frames per second to sample the source at. */
+    fps: number;
+    /** Optional max width (height auto, aspect preserved, no upscaling). */
+    width?: number;
+    /** Output image format. Defaults to `"jpg"` server-side when omitted. */
+    format?: ImageFormat;
+    /** JPEG/WebP quality 1..=100 (higher = better). Ignored for PNG. */
+    quality?: number;
+    /** Start offset into the clip, ms (default 0). */
+    seek_ms?: number;
+    /** How much of the clip to extract from `seek_ms`, ms (default: to end). */
+    duration_ms?: number;
+}
+/**
+ * Result of an `extractFrames` job: a JSON manifest stored at the job's
+ * `output_key` describing the frame set. Frame `i` (0-based) lives at
+ * `${prefix}/frame_${i padded to 6}.${ext}`.
+ */
+interface FramesetManifest {
+    /** Storage key prefix the frame images live under (no trailing slash). */
+    prefix: string;
+    /** Number of frames written. */
+    count: number;
+    /** Sampling fps the frames were extracted at. */
+    fps: number;
+    /** Frame image format. */
+    format: ImageFormat;
+    width?: number;
+    height?: number;
+}
 /** Options for `transforms.resize`. */
 interface ResizeOpts {
     width?: number;
@@ -174,6 +211,8 @@ type TransformSpec = ({
 } & TranscodeOpts) | ({
     kind: 'thumbnail';
 } & ThumbnailOpts) | ({
+    kind: 'extract_frames';
+} & ExtractFramesOpts) | ({
     kind: 'resize';
 } & ResizeOpts) | ({
     kind: 'ocr';
@@ -219,6 +258,12 @@ interface JobStatusResponse {
 interface TransformsService {
     transcode(srcKey: string, opts: TranscodeOpts): Promise<JobHandle>;
     thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle>;
+    /**
+     * Decode a video into a sequence of frame images at a fixed fps. Resolves to
+     * a `JobHandle` whose `output_key` holds a `FramesetManifest` (JSON) once
+     * complete; frames live under `${manifest.prefix}/frame_NNNNNN.<ext>`.
+     */
+    extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle>;
     resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
     probe(srcKey: string): Promise<MediaInfo>;
     ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
@@ -298,4 +343,4 @@ interface TransformsPatternSpec {
  */
 type TransformsConfig = Record<string, TransformsPatternSpec>;
 
-export { type DocFormat as D, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type DocToPdfOpts as d, type DocThumbnailOpts as e, type DocConvertOpts as f, type DocToMarkdownOpts as g, type DocToHtmlOpts as h, type ImageRef as i, type DocReplaceImagesOpts as j, type DocInsertQrCodeOpts as k, type QrPayload as l, type DocTemplateMergeOpts as m, type TransformSpec as n, type JobHandle as o, type JobStatusResponse as p, type TransformsService as q, keyFor as r, transforms as t };
+export { type DocFormat as D, type ExtractFramesOpts as E, type FramesetManifest as F, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type DocToPdfOpts as d, type DocThumbnailOpts as e, type DocConvertOpts as f, type DocToMarkdownOpts as g, type DocToHtmlOpts as h, type ImageRef as i, type DocReplaceImagesOpts as j, type DocInsertQrCodeOpts as k, type QrPayload as l, type DocTemplateMergeOpts as m, type TransformSpec as n, type JobHandle as o, type JobStatusResponse as p, type TransformsService as q, keyFor as r, transforms as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/mcp.ts

@@ -140,24 +140,30 @@ export interface McpServerSpec {
    */
   public?: boolean;
   /**
-   * Mini-app UI templates referenced by tools via `ui.template`. Each maps a
-   * template `name` to `htmlPath` — a **self-contained single-file HTML widget**
-   * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`). Output the
-   * build into your app's **static assets** and point `htmlPath` at that
-   * deploy-relative path (e.g. `static/mcp-ui/reader.html`), built BEFORE the app
-   * build — so the framework ships it as a normal static asset. The runtime reads
-   * those bytes and serves them as the `ui://<tool>/<template>` resource
-   * (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT) renders inline
-   * — the MCP Apps standard. The widget receives its data over the MCP Apps
-   * channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →
-   * `structuredContent`), not via cookies.
+   * Mini-app UI templates referenced by tools via `ui.template`. Each renders a
+   * tool result as a **self-contained single-file HTML widget** the runtime
+   * serves inline as the `ui://<tool>/<template>` resource
+   * (`text/html;profile=mcp-app`) — the MCP Apps standard — which the host
+   * (Claude, ChatGPT) renders in a sandboxed iframe. The widget receives its
+   * data over the MCP Apps channel (`@modelcontextprotocol/ext-apps`,
+   * `ontoolresult` → `structuredContent`), not via cookies.
    *
-   * `csp` declares the resource's Content-Security-Policy as
-   * {@link McpUiResourceCsp} (emitted at `_meta.ui.csp`): list the external
-   * origins the widget may load — e.g. `resourceDomains` for images/fonts the
-   * widget references. Omit for a fully self-contained widget.
+   * **The build is automatic.** Put the widget *source* in `mcp-ui/<name>/`
+   * (or `src/mcp-ui/<name>/`) — `index.html` + your component + `app.css` with
+   * `@import 'tailwindcss';` — and the platform compiles it to a single inlined
+   * file during `maravilla build` (framework plugin + Tailwind + singlefile, all
+   * resolved for you). No second Vite config, no build script, no `@source`. See
+   * the `mcp-ui-mini-app` recipe.
+   *
+   * - `entry` — override the source location (a dir or an `index.html`); defaults
+   *   to the `mcp-ui/<name>/` convention.
+   * - `htmlPath` — *legacy* escape hatch: point at a pre-built single-file under
+   *   `static/` you build yourself. Prefer the convention.
+   * - `csp` — the resource's Content-Security-Policy ({@link McpUiResourceCsp},
+   *   emitted at `_meta.ui.csp`): external origins the widget may load (e.g.
+   *   `resourceDomains` for remote images). Omit for a self-contained widget.
    */
-  uiTemplates?: Array<{ name: string; htmlPath: string; csp?: McpUiResourceCsp }>;
+  uiTemplates?: Array<{ name: string; entry?: string; htmlPath?: string; csp?: McpUiResourceCsp }>;
 }
 
 /**

package/src/transforms.ts

@@ -93,6 +93,45 @@ export interface ThumbnailOpts {
   quality?: number;
 }
 
+/**
+ * Options for `transforms.extractFrames` — decode a video into a sequence of
+ * still images at a fixed fps. General capability (any MP4 → frames); the
+ * frames renderer consumes the result to swap `<video>`→`<img>` per frame, and
+ * it's reusable for thumbnails/scrubbing.
+ */
+export interface ExtractFramesOpts {
+  /** Frames per second to sample the source at. */
+  fps: number;
+  /** Optional max width (height auto, aspect preserved, no upscaling). */
+  width?: number;
+  /** Output image format. Defaults to `"jpg"` server-side when omitted. */
+  format?: ImageFormat;
+  /** JPEG/WebP quality 1..=100 (higher = better). Ignored for PNG. */
+  quality?: number;
+  /** Start offset into the clip, ms (default 0). */
+  seek_ms?: number;
+  /** How much of the clip to extract from `seek_ms`, ms (default: to end). */
+  duration_ms?: number;
+}
+
+/**
+ * Result of an `extractFrames` job: a JSON manifest stored at the job's
+ * `output_key` describing the frame set. Frame `i` (0-based) lives at
+ * `${prefix}/frame_${i padded to 6}.${ext}`.
+ */
+export interface FramesetManifest {
+  /** Storage key prefix the frame images live under (no trailing slash). */
+  prefix: string;
+  /** Number of frames written. */
+  count: number;
+  /** Sampling fps the frames were extracted at. */
+  fps: number;
+  /** Frame image format. */
+  format: ImageFormat;
+  width?: number;
+  height?: number;
+}
+
 /** Options for `transforms.resize`. */
 export interface ResizeOpts {
   width?: number;
@@ -236,6 +275,7 @@ export interface DocTemplateMergeOpts {
 export type TransformSpec =
   | ({ kind: 'transcode' } & TranscodeOpts)
   | ({ kind: 'thumbnail' } & ThumbnailOpts)
+  | ({ kind: 'extract_frames' } & ExtractFramesOpts)
   | ({ kind: 'resize' } & ResizeOpts)
   | ({ kind: 'ocr' } & OcrOpts)
   | ({ kind: 'doc_to_pdf' } & DocToPdfOpts)
@@ -277,6 +317,12 @@ export interface JobStatusResponse {
 export interface TransformsService {
   transcode(srcKey: string, opts: TranscodeOpts): Promise<JobHandle>;
   thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle>;
+  /**
+   * Decode a video into a sequence of frame images at a fixed fps. Resolves to
+   * a `JobHandle` whose `output_key` holds a `FramesetManifest` (JSON) once
+   * complete; frames live under `${manifest.prefix}/frame_NNNNNN.<ext>`.
+   */
+  extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle>;
   resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
   probe(srcKey: string): Promise<MediaInfo>;
   ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
@@ -340,6 +386,9 @@ function outputExtension(spec: TransformSpec): string {
   switch (spec.kind) {
     case 'transcode':
       return spec.format; // 'mp4' | 'webm'
+    case 'extract_frames':
+      // Output key is the JSON frameset manifest; frames live under its base.
+      return 'json';
     case 'thumbnail':
     case 'resize': {
       // thumbnail's `format` is optional in TS (defaults to jpg server-side);