mountly-mcp 0.0.0 → 3.1.0

package/dist/svelte/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Svelte entry point: turn a Svelte component into an MCP App view.
+ *
+ * ```ts
+ * import { createMcpWidget } from "mountly-mcp/svelte";
+ * import Dashboard from "./Dashboard.svelte";
+ *
+ * const widget = createMcpWidget(Dashboard);
+ * (globalThis as { __mountlyMcpWidget__?: unknown }).__mountlyMcpWidget__ = widget;
+ * ```
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import type { McpWidgetProps } from "mountly-mcp";
+ *   let { mcp, toolResult, hostContext }: McpWidgetProps = $props();
+ * </script>
+ * ```
+ *
+ * Unlike the React and Vue entry points there are no context helpers: Svelte's
+ * `setContext` has to run inside a compiled component, which would mean
+ * shipping a `.svelte` file and a compiler from this package. Props are already
+ * reactive via `$props()`, so pass them down where a nested component needs
+ * them.
+ */
+import { createWidget } from "mountly-svelte";
+import type { AdapterOptions, WidgetModule } from "mountly/adapter";
+import type { McpWidgetProps } from "../types.js";
+/**
+ * Wraps a Svelte component as a mountly `WidgetModule` driven by the
+ * mountly-mcp bridge. The component receives `mcp`, `toolInput`,
+ * `toolInputPartial`, `toolResult` and `hostContext` as props, alongside any
+ * pass-through props.
+ */
+export declare function createMcpWidget<P extends object>(Component: Parameters<typeof createWidget<P & McpWidgetProps>>[0], options?: AdapterOptions): WidgetModule;
+export type { McpWidgetProps };

package/dist/svelte/index.js

@@ -0,0 +1,9 @@
+// src/svelte/index.ts
+import { createWidget } from "mountly-svelte";
+function createMcpWidget(Component, options) {
+  return createWidget(Component, options);
+}
+export {
+  createMcpWidget
+};
+//# sourceMappingURL=index.js.map

package/dist/svelte/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/svelte/index.ts"],"sourcesContent":["/**\n * Svelte entry point: turn a Svelte component into an MCP App view.\n *\n * ```ts\n * import { createMcpWidget } from \"mountly-mcp/svelte\";\n * import Dashboard from \"./Dashboard.svelte\";\n *\n * const widget = createMcpWidget(Dashboard);\n * (globalThis as { __mountlyMcpWidget__?: unknown }).__mountlyMcpWidget__ = widget;\n * ```\n *\n * ```svelte\n * <script lang=\"ts\">\n *   import type { McpWidgetProps } from \"mountly-mcp\";\n *   let { mcp, toolResult, hostContext }: McpWidgetProps = $props();\n * </script>\n * ```\n *\n * Unlike the React and Vue entry points there are no context helpers: Svelte's\n * `setContext` has to run inside a compiled component, which would mean\n * shipping a `.svelte` file and a compiler from this package. Props are already\n * reactive via `$props()`, so pass them down where a nested component needs\n * them.\n */\nimport { createWidget } from \"mountly-svelte\";\nimport type { AdapterOptions, WidgetModule } from \"mountly/adapter\";\nimport type { McpWidgetProps } from \"../types.js\";\n\n/**\n * Wraps a Svelte component as a mountly `WidgetModule` driven by the\n * mountly-mcp bridge. The component receives `mcp`, `toolInput`,\n * `toolInputPartial`, `toolResult` and `hostContext` as props, alongside any\n * pass-through props.\n */\nexport function createMcpWidget<P extends object>(\n  Component: Parameters<typeof createWidget<P & McpWidgetProps>>[0],\n  options?: AdapterOptions,\n): WidgetModule {\n  return createWidget<P & McpWidgetProps>(Component, options);\n}\n\nexport type { McpWidgetProps };\n"],"mappings":";AAwBA,SAAS,oBAAoB;AAUtB,SAAS,gBACd,WACA,SACc;AACd,SAAO,aAAiC,WAAW,OAAO;AAC5D;","names":[]}

package/dist/testing/index.d.ts

@@ -0,0 +1,27 @@
+import { type ConformanceDiagnostic, type McpAppArtifact } from "../artifact/index.js";
+export interface VerifyMcpAppsOptions {
+    /** Canonical manifest. Defaults to `dist/mountly-mcp.manifest.json`. */
+    manifestPath?: string;
+    /** Transitional single-View inputs when no manifest exists. */
+    htmlPaths?: ReadonlyArray<string>;
+    /**
+     * Load each View in a real browser and confirm the widget mounts with content.
+     *
+     * Off by default: it needs Playwright and a Chromium download, which the
+     * static checks do not. Turn it on in CI. Everything else here inspects
+     * files, and a View can satisfy every file-level check while failing to
+     * render — a framework left external, a Node global in the bundle, a bridge
+     * that never completes the handshake all produce conforming HTML.
+     */
+    render?: boolean;
+}
+export interface McpAppConformanceReport {
+    ok: boolean;
+    /** Verification tier selected by the caller. */
+    mode: "static" | "browser";
+    artifacts: ReadonlyArray<McpAppArtifact>;
+    diagnostics: ReadonlyArray<ConformanceDiagnostic>;
+}
+/** Deterministic verification shared by the CLI and downstream CI. */
+export declare function verifyMcpApps(options?: VerifyMcpAppsOptions): Promise<McpAppConformanceReport>;
+export declare function formatConformanceReport(report: McpAppConformanceReport): string;

package/dist/testing/index.js

@@ -0,0 +1,312 @@
+import {
+  MCP_APP_MANIFEST_FILE,
+  McpAppConformanceError,
+  readMcpAppArtifact,
+  readMcpAppManifest
+} from "../chunk-DKK26TRS.js";
+
+// src/testing/index.ts
+import { access, readFile } from "fs/promises";
+import { isDeepStrictEqual } from "util";
+
+// src/testing/render-artifact.ts
+function error(code, message, source) {
+  return { severity: "error", code, message, source };
+}
+function warning(code, message, source) {
+  return { severity: "warning", code, message, source };
+}
+async function loadAxeSource() {
+  const specifier = "axe-core";
+  try {
+    const mod = await import(specifier);
+    return mod.source ?? mod.default?.source;
+  } catch {
+    return void 0;
+  }
+}
+async function auditAccessibility(view, artifact) {
+  const axeSource = await loadAxeSource();
+  if (!axeSource) return [];
+  let violations;
+  try {
+    await view.evaluate(axeSource);
+    violations = await view.evaluate(`
+      axe.run(document, { resultTypes: ["violations"] }).then((result) =>
+        result.violations.map((violation) => ({
+          id: violation.id,
+          impact: violation.impact ?? null,
+          help: violation.help,
+          nodes: violation.nodes.length,
+          target: String(violation.nodes[0]?.target?.[0] ?? "")
+        }))
+      )
+    `);
+  } catch (caught) {
+    return [
+      warning(
+        "render/a11y-unavailable",
+        `accessibility pass did not run: ${caught instanceof Error ? caught.message : String(caught)}`,
+        artifact.htmlPath
+      )
+    ];
+  }
+  return violations.map(
+    (violation) => warning(
+      "render/a11y",
+      `${violation.id} (${violation.impact ?? "unknown"} impact): ${violation.help} \u2014 ${violation.nodes} element${violation.nodes === 1 ? "" : "s"}, first at \`${violation.target}\``,
+      artifact.htmlPath
+    )
+  );
+}
+async function launchBrowser() {
+  const specifiers = ["playwright", "@playwright/test"];
+  for (const specifier of specifiers) {
+    let mod;
+    try {
+      mod = await import(specifier);
+    } catch {
+      continue;
+    }
+    if (mod.chromium) return mod.chromium.launch();
+  }
+  return void 0;
+}
+async function startHost(artifact) {
+  const { startDevHost } = await import("../dev/index.js");
+  return startDevHost({
+    htmlPath: artifact.htmlPath,
+    fixtures: { conformance: {} },
+    hostPort: 5480
+  });
+}
+async function renderMcpAppArtifactWith(artifact, dependencies) {
+  let browser;
+  try {
+    browser = await dependencies.launchBrowser();
+  } catch (caught) {
+    return [
+      error(
+        "render/unavailable",
+        `could not launch Chromium: ${caught instanceof Error ? caught.message : String(caught)}`,
+        artifact.htmlPath
+      )
+    ];
+  }
+  if (!browser) {
+    return [
+      error(
+        "render/unavailable",
+        "render requested but Playwright is not installed (npm i -D playwright)",
+        artifact.htmlPath
+      )
+    ];
+  }
+  let host;
+  const failures = [];
+  try {
+    host = await dependencies.startHost(artifact);
+    const page = await browser.newPage();
+    const pageErrors = [];
+    page.on("pageerror", (caught) => pageErrors.push(caught.message));
+    await page.goto(host.hostUrl);
+    const deadline = Date.now() + 2e4;
+    let mounted = false;
+    let renderedContent = false;
+    let mountedAt;
+    let boundary;
+    while (!boundary && Date.now() < deadline && pageErrors.length === 0) {
+      const view = page.frames().find((frame) => frame.url().includes("srcdoc"));
+      const state = view ? await view.evaluate(() => {
+        const failed = document.querySelector("[data-mountly-mcp-error]");
+        const root = document.querySelector("#mountly-mcp-root");
+        const bounds = root?.getBoundingClientRect();
+        return {
+          state: root?.getAttribute("data-mountly-mcp-state") ?? void 0,
+          html: root?.innerHTML ?? "",
+          shadowHtml: root?.shadowRoot?.innerHTML ?? "",
+          visibleHeight: bounds?.height ?? 0,
+          error: failed ? `${failed.getAttribute("data-mountly-mcp-error") ?? ""}: ${failed.textContent ?? ""}` : void 0
+        };
+      }).catch(() => void 0) : void 0;
+      boundary = state?.error;
+      mounted || (mounted = state?.state === "mounted");
+      if (mounted && mountedAt === void 0) mountedAt = Date.now();
+      renderedContent = (state?.html ?? "").trim().length > 0 || (state?.shadowHtml ?? "").trim().length > 0 || (state?.visibleHeight ?? 0) > 0;
+      if (mounted && renderedContent) break;
+      if (mountedAt !== void 0 && Date.now() - mountedAt >= 2e3) break;
+      await new Promise((done) => setTimeout(done, 100));
+    }
+    if (boundary) {
+      failures.push(
+        error("render/error-boundary", `View rendered an error: ${boundary}`, artifact.htmlPath)
+      );
+    } else if (pageErrors.length > 0) {
+      failures.push(
+        error("render/threw", `View threw while loading: ${pageErrors[0]}`, artifact.htmlPath)
+      );
+    } else if (!mounted) {
+      failures.push(
+        error(
+          "render/timeout",
+          "View never mounted: the handshake or widget mount did not complete",
+          artifact.htmlPath
+        )
+      );
+    } else if (!renderedContent) {
+      failures.push(
+        error("render/blank", "View mounted but rendered no content", artifact.htmlPath)
+      );
+    } else {
+      const view = page.frames().find((frame) => frame.url().includes("srcdoc"));
+      if (view) failures.push(...await auditAccessibility(view, artifact));
+    }
+  } catch (caught) {
+    failures.push(
+      error(
+        "render/failed",
+        caught instanceof Error ? caught.message : String(caught),
+        artifact.htmlPath
+      )
+    );
+  } finally {
+    await Promise.allSettled([browser.close(), host?.close() ?? Promise.resolve()]);
+  }
+  return failures;
+}
+function renderMcpAppArtifact(artifact) {
+  return renderMcpAppArtifactWith(artifact, { launchBrowser, startHost });
+}
+
+// src/testing/index.ts
+function error2(code, message, source) {
+  return { severity: "error", code, message, source };
+}
+function warning2(code, message, source) {
+  return { severity: "warning", code, message, source };
+}
+async function verifyMcpApps(options = {}) {
+  const diagnostics = [];
+  const artifacts = [];
+  if (options.htmlPaths && options.htmlPaths.length > 0) {
+    for (const path of options.htmlPaths) {
+      try {
+        artifacts.push(await readMcpAppArtifact(path));
+      } catch (caught) {
+        if (caught instanceof McpAppConformanceError) diagnostics.push(...caught.diagnostics);
+        else
+          diagnostics.push(
+            error2("verify/load", caught instanceof Error ? caught.message : String(caught))
+          );
+      }
+    }
+  } else {
+    try {
+      const loaded = await readMcpAppManifest(
+        options.manifestPath ?? `dist/${MCP_APP_MANIFEST_FILE}`
+      );
+      for (const declared of loaded.artifacts) {
+        try {
+          const actual = await readMcpAppArtifact(declared.htmlPath, declared.uri);
+          if (actual.name !== declared.name) {
+            diagnostics.push(
+              error2(
+                "manifest/name-mismatch",
+                `manifest app '${declared.name}' points to artifact '${actual.name}'`,
+                loaded.path
+              )
+            );
+          }
+          if (!isDeepStrictEqual(actual.declaration, declared.declaration)) {
+            diagnostics.push(
+              error2(
+                "manifest/declaration-mismatch",
+                `manifest declaration for '${declared.name}' does not match its metadata file`,
+                loaded.path
+              )
+            );
+          }
+          artifacts.push(actual);
+        } catch (caught) {
+          if (caught instanceof McpAppConformanceError) diagnostics.push(...caught.diagnostics);
+          else
+            diagnostics.push(
+              error2("verify/load", caught instanceof Error ? caught.message : String(caught))
+            );
+        }
+      }
+    } catch (caught) {
+      if (caught instanceof McpAppConformanceError) diagnostics.push(...caught.diagnostics);
+      else
+        diagnostics.push(
+          error2("verify/load", caught instanceof Error ? caught.message : String(caught))
+        );
+    }
+  }
+  const names = /* @__PURE__ */ new Set();
+  const uris = /* @__PURE__ */ new Set();
+  for (const artifact of artifacts) {
+    if (names.has(artifact.name)) {
+      diagnostics.push(error2("manifest/duplicate-name", `duplicate app name '${artifact.name}'`));
+    }
+    if (uris.has(artifact.uri)) {
+      diagnostics.push(error2("manifest/duplicate-uri", `duplicate app uri '${artifact.uri}'`));
+    }
+    names.add(artifact.name);
+    uris.add(artifact.uri);
+    try {
+      await Promise.all([access(artifact.htmlPath), access(artifact.metaPath)]);
+      const html = await readFile(artifact.htmlPath, "utf8");
+      if (!html.includes("ui/initialize") || !html.includes("ui/notifications/initialized")) {
+        diagnostics.push(
+          error2(
+            "artifact/bridge",
+            "View HTML does not contain the MCP Apps initialization handshake",
+            artifact.htmlPath
+          )
+        );
+      }
+      if (options.render) diagnostics.push(...await renderMcpAppArtifact(artifact));
+      if (!artifact.declaration.description) {
+        diagnostics.push(
+          warning2(
+            "artifact/description",
+            `View '${artifact.name}' has no description`,
+            artifact.metaPath
+          )
+        );
+      }
+    } catch (caught) {
+      diagnostics.push(
+        error2(
+          "artifact/files",
+          caught instanceof Error ? caught.message : String(caught),
+          artifact.htmlPath
+        )
+      );
+    }
+  }
+  return {
+    ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
+    mode: options.render === true ? "browser" : "static",
+    artifacts,
+    diagnostics
+  };
+}
+function formatConformanceReport(report) {
+  const lines = report.diagnostics.map((diagnostic) => {
+    const marker = diagnostic.severity === "error" ? "ERROR" : "WARN";
+    const source = diagnostic.source ? ` (${diagnostic.source})` : "";
+    return `${marker} ${diagnostic.code}: ${diagnostic.message}${source}`;
+  });
+  lines.push(
+    `${report.ok ? "PASS" : "FAIL"} ${report.artifacts.length} app artifact${report.artifacts.length === 1 ? "" : "s"} (${report.mode === "browser" ? "browser checks" : "static checks only; pass --render for runtime coverage"})`
+  );
+  return `${lines.join("\n")}
+`;
+}
+export {
+  formatConformanceReport,
+  verifyMcpApps
+};
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/index.ts","../../src/testing/render-artifact.ts"],"sourcesContent":["import { access, readFile } from \"node:fs/promises\";\nimport { isDeepStrictEqual } from \"node:util\";\nimport {\n  MCP_APP_MANIFEST_FILE,\n  McpAppConformanceError,\n  readMcpAppArtifact,\n  readMcpAppManifest,\n  type ConformanceDiagnostic,\n  type McpAppArtifact,\n} from \"../artifact/index.js\";\nimport { renderMcpAppArtifact } from \"./render-artifact.js\";\n\nexport interface VerifyMcpAppsOptions {\n  /** Canonical manifest. Defaults to `dist/mountly-mcp.manifest.json`. */\n  manifestPath?: string;\n  /** Transitional single-View inputs when no manifest exists. */\n  htmlPaths?: ReadonlyArray<string>;\n  /**\n   * Load each View in a real browser and confirm the widget mounts with content.\n   *\n   * Off by default: it needs Playwright and a Chromium download, which the\n   * static checks do not. Turn it on in CI. Everything else here inspects\n   * files, and a View can satisfy every file-level check while failing to\n   * render — a framework left external, a Node global in the bundle, a bridge\n   * that never completes the handshake all produce conforming HTML.\n   */\n  render?: boolean;\n}\n\nexport interface McpAppConformanceReport {\n  ok: boolean;\n  /** Verification tier selected by the caller. */\n  mode: \"static\" | \"browser\";\n  artifacts: ReadonlyArray<McpAppArtifact>;\n  diagnostics: ReadonlyArray<ConformanceDiagnostic>;\n}\n\nfunction error(code: string, message: string, source?: string): ConformanceDiagnostic {\n  return { severity: \"error\", code, message, source };\n}\n\nfunction warning(code: string, message: string, source?: string): ConformanceDiagnostic {\n  return { severity: \"warning\", code, message, source };\n}\n\n/** Deterministic verification shared by the CLI and downstream CI. */\nexport async function verifyMcpApps(\n  options: VerifyMcpAppsOptions = {},\n): Promise<McpAppConformanceReport> {\n  const diagnostics: ConformanceDiagnostic[] = [];\n  const artifacts: McpAppArtifact[] = [];\n  if (options.htmlPaths && options.htmlPaths.length > 0) {\n    for (const path of options.htmlPaths) {\n      try {\n        artifacts.push(await readMcpAppArtifact(path));\n      } catch (caught) {\n        if (caught instanceof McpAppConformanceError) diagnostics.push(...caught.diagnostics);\n        else\n          diagnostics.push(\n            error(\"verify/load\", caught instanceof Error ? caught.message : String(caught)),\n          );\n      }\n    }\n  } else {\n    try {\n      const loaded = await readMcpAppManifest(\n        options.manifestPath ?? `dist/${MCP_APP_MANIFEST_FILE}`,\n      );\n      for (const declared of loaded.artifacts) {\n        try {\n          const actual = await readMcpAppArtifact(declared.htmlPath, declared.uri);\n          if (actual.name !== declared.name) {\n            diagnostics.push(\n              error(\n                \"manifest/name-mismatch\",\n                `manifest app '${declared.name}' points to artifact '${actual.name}'`,\n                loaded.path,\n              ),\n            );\n          }\n          if (!isDeepStrictEqual(actual.declaration, declared.declaration)) {\n            diagnostics.push(\n              error(\n                \"manifest/declaration-mismatch\",\n                `manifest declaration for '${declared.name}' does not match its metadata file`,\n                loaded.path,\n              ),\n            );\n          }\n          artifacts.push(actual);\n        } catch (caught) {\n          if (caught instanceof McpAppConformanceError) diagnostics.push(...caught.diagnostics);\n          else\n            diagnostics.push(\n              error(\"verify/load\", caught instanceof Error ? caught.message : String(caught)),\n            );\n        }\n      }\n    } catch (caught) {\n      if (caught instanceof McpAppConformanceError) diagnostics.push(...caught.diagnostics);\n      else\n        diagnostics.push(\n          error(\"verify/load\", caught instanceof Error ? caught.message : String(caught)),\n        );\n    }\n  }\n\n  const names = new Set<string>();\n  const uris = new Set<string>();\n  for (const artifact of artifacts) {\n    if (names.has(artifact.name)) {\n      diagnostics.push(error(\"manifest/duplicate-name\", `duplicate app name '${artifact.name}'`));\n    }\n    if (uris.has(artifact.uri)) {\n      diagnostics.push(error(\"manifest/duplicate-uri\", `duplicate app uri '${artifact.uri}'`));\n    }\n    names.add(artifact.name);\n    uris.add(artifact.uri);\n    try {\n      await Promise.all([access(artifact.htmlPath), access(artifact.metaPath)]);\n      const html = await readFile(artifact.htmlPath, \"utf8\");\n      if (!html.includes(\"ui/initialize\") || !html.includes(\"ui/notifications/initialized\")) {\n        diagnostics.push(\n          error(\n            \"artifact/bridge\",\n            \"View HTML does not contain the MCP Apps initialization handshake\",\n            artifact.htmlPath,\n          ),\n        );\n      }\n      if (options.render) diagnostics.push(...(await renderMcpAppArtifact(artifact)));\n      if (!artifact.declaration.description) {\n        diagnostics.push(\n          warning(\n            \"artifact/description\",\n            `View '${artifact.name}' has no description`,\n            artifact.metaPath,\n          ),\n        );\n      }\n    } catch (caught) {\n      diagnostics.push(\n        error(\n          \"artifact/files\",\n          caught instanceof Error ? caught.message : String(caught),\n          artifact.htmlPath,\n        ),\n      );\n    }\n  }\n\n  return {\n    ok: !diagnostics.some((diagnostic) => diagnostic.severity === \"error\"),\n    mode: options.render === true ? \"browser\" : \"static\",\n    artifacts,\n    diagnostics,\n  };\n}\n\nexport function formatConformanceReport(report: McpAppConformanceReport): string {\n  const lines = report.diagnostics.map((diagnostic) => {\n    const marker = diagnostic.severity === \"error\" ? \"ERROR\" : \"WARN\";\n    const source = diagnostic.source ? ` (${diagnostic.source})` : \"\";\n    return `${marker} ${diagnostic.code}: ${diagnostic.message}${source}`;\n  });\n  lines.push(\n    `${report.ok ? \"PASS\" : \"FAIL\"} ${report.artifacts.length} app artifact${report.artifacts.length === 1 ? \"\" : \"s\"} (${report.mode === \"browser\" ? \"browser checks\" : \"static checks only; pass --render for runtime coverage\"})`,\n  );\n  return `${lines.join(\"\\n\")}\\n`;\n}\n","import type { ConformanceDiagnostic, McpAppArtifact } from \"../artifact/index.js\";\n\ninterface FrameLike {\n  url(): string;\n  /**\n   * A string expression is evaluated through the debugger protocol rather than\n   * as page script, which is how axe reaches a View whose CSP withholds\n   * `unsafe-eval` — the same CSP a host enforces in production.\n   */\n  evaluate<T>(fn: (() => T) | string): Promise<T>;\n}\n\ninterface PageLike {\n  on(event: \"pageerror\", handler: (error: Error) => void): void;\n  goto(url: string): Promise<unknown>;\n  frames(): FrameLike[];\n}\n\nexport interface ConformanceBrowser {\n  newPage(): Promise<PageLike>;\n  close(): Promise<void>;\n}\n\nexport interface ConformanceHost {\n  hostUrl: string;\n  close(): Promise<void>;\n}\n\n/** @internal Test seam for browser and host lifecycle failures. */\nexport interface RenderMcpAppArtifactDependencies {\n  launchBrowser(): Promise<ConformanceBrowser | undefined>;\n  startHost(artifact: McpAppArtifact): Promise<ConformanceHost>;\n}\n\nfunction error(code: string, message: string, source: string): ConformanceDiagnostic {\n  return { severity: \"error\", code, message, source };\n}\n\nfunction warning(code: string, message: string, source: string): ConformanceDiagnostic {\n  return { severity: \"warning\", code, message, source };\n}\n\ninterface AxeViolation {\n  id: string;\n  impact: string | null;\n  help: string;\n  nodes: number;\n  target: string;\n}\n\n/** axe-core is an optional peer, like Playwright: absent means the pass is skipped. */\nasync function loadAxeSource(): Promise<string | undefined> {\n  const specifier: string = \"axe-core\";\n  try {\n    const mod = (await import(specifier)) as { source?: string; default?: { source?: string } };\n    return mod.source ?? mod.default?.source;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Accessibility of the View as assembled, which component-level checks cannot\n * see: every part can be accessible and the composition still fail, because a\n * missing label or a contrast pairing only exists once the parts are together.\n *\n * Reported as warnings, so a run stays green unless `--strict` is on. They are\n * findings about the View you built, not proof the artifact is malformed.\n */\nasync function auditAccessibility(\n  view: FrameLike,\n  artifact: McpAppArtifact,\n): Promise<ConformanceDiagnostic[]> {\n  const axeSource = await loadAxeSource();\n  if (!axeSource) return [];\n\n  let violations: AxeViolation[];\n  try {\n    await view.evaluate(axeSource);\n    violations = await view.evaluate<AxeViolation[]>(`\n      axe.run(document, { resultTypes: [\"violations\"] }).then((result) =>\n        result.violations.map((violation) => ({\n          id: violation.id,\n          impact: violation.impact ?? null,\n          help: violation.help,\n          nodes: violation.nodes.length,\n          target: String(violation.nodes[0]?.target?.[0] ?? \"\")\n        }))\n      )\n    `);\n  } catch (caught) {\n    return [\n      warning(\n        \"render/a11y-unavailable\",\n        `accessibility pass did not run: ${caught instanceof Error ? caught.message : String(caught)}`,\n        artifact.htmlPath,\n      ),\n    ];\n  }\n\n  return violations.map((violation) =>\n    warning(\n      \"render/a11y\",\n      `${violation.id} (${violation.impact ?? \"unknown\"} impact): ${violation.help} — ${violation.nodes} element${violation.nodes === 1 ? \"\" : \"s\"}, first at \\`${violation.target}\\``,\n      artifact.htmlPath,\n    ),\n  );\n}\n\n/** Playwright is an optional peer — absent is a diagnostic, not a crash. */\nasync function launchBrowser(): Promise<ConformanceBrowser | undefined> {\n  // Both specifiers are tried: under an isolated `node_modules` a project that\n  // installed `@playwright/test` cannot resolve bare `playwright`, even though\n  // one depends on the other. Specifiers stay `string`-typed so the optional\n  // peer is optional at type-check time as well as at runtime.\n  const specifiers: string[] = [\"playwright\", \"@playwright/test\"];\n  for (const specifier of specifiers) {\n    let mod: { chromium?: { launch(): Promise<ConformanceBrowser> } };\n    try {\n      mod = (await import(specifier)) as typeof mod;\n    } catch {\n      continue;\n    }\n    if (mod.chromium) return mod.chromium.launch();\n  }\n  return undefined;\n}\n\nasync function startHost(artifact: McpAppArtifact): Promise<ConformanceHost> {\n  const { startDevHost } = await import(\"../dev/index.js\");\n  return startDevHost({\n    htmlPath: artifact.htmlPath,\n    fixtures: { conformance: {} },\n    hostPort: 5480,\n  });\n}\n\n/**\n * Exercise an App artifact through the real two-origin host and browser.\n * Browser and host ownership stays local so every startup path is cleaned up.\n */\nexport async function renderMcpAppArtifactWith(\n  artifact: McpAppArtifact,\n  dependencies: RenderMcpAppArtifactDependencies,\n): Promise<ConformanceDiagnostic[]> {\n  let browser: ConformanceBrowser | undefined;\n  try {\n    browser = await dependencies.launchBrowser();\n  } catch (caught) {\n    return [\n      error(\n        \"render/unavailable\",\n        `could not launch Chromium: ${caught instanceof Error ? caught.message : String(caught)}`,\n        artifact.htmlPath,\n      ),\n    ];\n  }\n  if (!browser) {\n    return [\n      error(\n        \"render/unavailable\",\n        \"render requested but Playwright is not installed (npm i -D playwright)\",\n        artifact.htmlPath,\n      ),\n    ];\n  }\n\n  let host: ConformanceHost | undefined;\n  const failures: ConformanceDiagnostic[] = [];\n  try {\n    host = await dependencies.startHost(artifact);\n    const page = await browser.newPage();\n    const pageErrors: string[] = [];\n    page.on(\"pageerror\", (caught) => pageErrors.push(caught.message));\n    await page.goto(host.hostUrl);\n\n    const deadline = Date.now() + 20_000;\n    let mounted = false;\n    let renderedContent = false;\n    let mountedAt: number | undefined;\n    let boundary: string | undefined;\n    while (!boundary && Date.now() < deadline && pageErrors.length === 0) {\n      const view = page.frames().find((frame) => frame.url().includes(\"srcdoc\"));\n      const state = view\n        ? await view\n            .evaluate(() => {\n              const failed = document.querySelector(\"[data-mountly-mcp-error]\");\n              const root = document.querySelector(\"#mountly-mcp-root\");\n              const bounds = root?.getBoundingClientRect();\n              return {\n                state: root?.getAttribute(\"data-mountly-mcp-state\") ?? undefined,\n                html: root?.innerHTML ?? \"\",\n                shadowHtml: root?.shadowRoot?.innerHTML ?? \"\",\n                visibleHeight: bounds?.height ?? 0,\n                error: failed\n                  ? `${failed.getAttribute(\"data-mountly-mcp-error\") ?? \"\"}: ${failed.textContent ?? \"\"}`\n                  : undefined,\n              };\n            })\n            .catch(() => undefined)\n        : undefined;\n      boundary = state?.error;\n      // Sticky: the bridge's state only moves forward, and a View that mounted\n      // stays mounted even if a later poll reads the frame mid-navigation.\n      mounted ||= state?.state === \"mounted\";\n      if (mounted && mountedAt === undefined) mountedAt = Date.now();\n      renderedContent =\n        (state?.html ?? \"\").trim().length > 0 ||\n        (state?.shadowHtml ?? \"\").trim().length > 0 ||\n        (state?.visibleHeight ?? 0) > 0;\n      if (mounted && renderedContent) break;\n      // Framework renderers may commit after mount() returns. Give them a\n      // bounded window while still failing a genuinely empty View quickly.\n      if (mountedAt !== undefined && Date.now() - mountedAt >= 2_000) break;\n      await new Promise((done) => setTimeout(done, 100));\n    }\n\n    if (boundary) {\n      failures.push(\n        error(\"render/error-boundary\", `View rendered an error: ${boundary}`, artifact.htmlPath),\n      );\n    } else if (pageErrors.length > 0) {\n      failures.push(\n        error(\"render/threw\", `View threw while loading: ${pageErrors[0]}`, artifact.htmlPath),\n      );\n    } else if (!mounted) {\n      failures.push(\n        error(\n          \"render/timeout\",\n          \"View never mounted: the handshake or widget mount did not complete\",\n          artifact.htmlPath,\n        ),\n      );\n    } else if (!renderedContent) {\n      failures.push(\n        error(\"render/blank\", \"View mounted but rendered no content\", artifact.htmlPath),\n      );\n    } else {\n      // Only a View that actually rendered can be audited — anything else has\n      // already failed, and axe would just report on an empty document.\n      const view = page.frames().find((frame) => frame.url().includes(\"srcdoc\"));\n      if (view) failures.push(...(await auditAccessibility(view, artifact)));\n    }\n  } catch (caught) {\n    failures.push(\n      error(\n        \"render/failed\",\n        caught instanceof Error ? caught.message : String(caught),\n        artifact.htmlPath,\n      ),\n    );\n  } finally {\n    await Promise.allSettled([browser.close(), host?.close() ?? Promise.resolve()]);\n  }\n  return failures;\n}\n\nexport function renderMcpAppArtifact(artifact: McpAppArtifact): Promise<ConformanceDiagnostic[]> {\n  return renderMcpAppArtifactWith(artifact, { launchBrowser, startHost });\n}\n"],"mappings":"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","names":["error","warning"]}

package/dist/testing/render-artifact.d.ts

@@ -0,0 +1,35 @@
+import type { ConformanceDiagnostic, McpAppArtifact } from "../artifact/index.js";
+interface FrameLike {
+    url(): string;
+    /**
+     * A string expression is evaluated through the debugger protocol rather than
+     * as page script, which is how axe reaches a View whose CSP withholds
+     * `unsafe-eval` — the same CSP a host enforces in production.
+     */
+    evaluate<T>(fn: (() => T) | string): Promise<T>;
+}
+interface PageLike {
+    on(event: "pageerror", handler: (error: Error) => void): void;
+    goto(url: string): Promise<unknown>;
+    frames(): FrameLike[];
+}
+export interface ConformanceBrowser {
+    newPage(): Promise<PageLike>;
+    close(): Promise<void>;
+}
+export interface ConformanceHost {
+    hostUrl: string;
+    close(): Promise<void>;
+}
+/** @internal Test seam for browser and host lifecycle failures. */
+export interface RenderMcpAppArtifactDependencies {
+    launchBrowser(): Promise<ConformanceBrowser | undefined>;
+    startHost(artifact: McpAppArtifact): Promise<ConformanceHost>;
+}
+/**
+ * Exercise an App artifact through the real two-origin host and browser.
+ * Browser and host ownership stays local so every startup path is cleaned up.
+ */
+export declare function renderMcpAppArtifactWith(artifact: McpAppArtifact, dependencies: RenderMcpAppArtifactDependencies): Promise<ConformanceDiagnostic[]>;
+export declare function renderMcpAppArtifact(artifact: McpAppArtifact): Promise<ConformanceDiagnostic[]>;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Spec types come straight from `@modelcontextprotocol/ext-apps` under their
+ * own names — `McpUiDisplayMode`, `McpUiHostContext`, and the rest. mountly
+ * deliberately does not rename them: the names in the MCP Apps spec (SEP-1865)
+ * are the vocabulary users already learned, and every alias is one more thing
+ * to translate and one more place to drift.
+ *
+ * Only genuinely mountly-specific types live here: the props a widget's
+ * `mount()` receives, and the sidecar declaration written next to the built HTML.
+ */
+export type { App, McpUiAppCapabilities, McpUiDisplayMode, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiResourceCsp, McpUiResourceMeta, McpUiResourcePermissions, McpUiToolCancelledNotification, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolMeta, McpUiToolResultNotification, McpUiToolVisibility, } from "@modelcontextprotocol/ext-apps";
+import type { App, McpUiDisplayMode, McpUiHostContext, McpUiResourceMeta, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification } from "@modelcontextprotocol/ext-apps";
+import type { MCP_APPS_MIME, MCP_APPS_PROTOCOL_VERSION } from "./schema.js";
+/**
+ * Props passed to a `WidgetModule.mount(container, props)` call.
+ *
+ * The bridge surfaces the App handle plus the latest tool input/result and a
+ * snapshot of host context. Widgets receive new props through `update()` as
+ * notifications arrive — see `runBridge` in `bridge/index.ts`.
+ */
+export interface McpWidgetProps {
+    /** The view-side ext-apps App; exposes the full spec-compliant API surface. */
+    mcp: App;
+    /** Tool arguments (after `ui/notifications/tool-input`). */
+    toolInput?: McpUiToolInputNotification["params"];
+    /**
+     * Streaming tool arguments (`ui/notifications/tool-input-partial`), only when
+     * the bridge runs with `streamToolInput`. Best-effort recovered JSON: fields
+     * may be missing or change between notifications, so never drive a critical
+     * operation from it. Cleared once the complete `toolInput` arrives.
+     */
+    toolInputPartial?: McpUiToolInputPartialNotification["params"];
+    /** Tool result (after `ui/notifications/tool-result`). */
+    toolResult?: McpUiToolResultNotification["params"];
+    /** Host context (theme, styles, displayMode, container dimensions, etc.). */
+    hostContext?: McpUiHostContext;
+}
+/**
+ * Resource metadata written to the `.meta.json` sidecar next to the emitted
+ * HTML, consumed by `mountly-mcp/server` when registering the `ui://`
+ * resource with `_meta.ui = {...}`.
+ */
+export interface McpResourceDeclaration {
+    protocolVersion: typeof MCP_APPS_PROTOCOL_VERSION;
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType: typeof MCP_APPS_MIME;
+    /** Whether `runBridge` defers mount until the first tool-result arrives. */
+    awaitToolResult: boolean;
+    displayModes: ReadonlyArray<McpUiDisplayMode>;
+    _meta: {
+        ui: McpUiResourceMeta;
+    };
+}

package/dist/vite/index.d.ts

@@ -0,0 +1,23 @@
+import type { Plugin } from "vite";
+import type { BuildSelfContainedOptions } from "../build/index.js";
+export interface MountlyMcpWidgetOptions extends Omit<BuildSelfContainedOptions, "entry" | "output" | "cssEntry"> {
+    entry: string;
+    output?: string;
+    cleanIntermediate?: boolean;
+}
+export interface MountlyMcpWidgetsOptions {
+    apps: ReadonlyArray<MountlyMcpWidgetOptions>;
+    /** Defaults to `<outDir>/mountly-mcp.manifest.json`; false disables it. */
+    manifest?: string | false;
+}
+export type MountlyMcpViteOptions = MountlyMcpWidgetOptions | MountlyMcpWidgetsOptions;
+export interface MountlyMcpViteApi {
+    apps: ReadonlyArray<MountlyMcpWidgetOptions>;
+    manifest?: string | false;
+}
+/**
+ * Build one or many independent MCP Apps Views. Each View is a Vite build
+ * environment, so frameworks and CSS remain isolated while callers configure
+ * the collection once.
+ */
+export declare function mountlyMcpWidget(options: MountlyMcpViteOptions): Plugin;