@mcp-native/webview 0.0.1 → 0.0.3

package/README.md

@@ -1,5 +1,90 @@
+<div align="center">
+
 # @mcp-native/webview
 
-Part of MCP Native — a native UI runtime for Model Context Protocol applications.
+### A deny-by-default HTML MCP App compatibility boundary
+
+[![npm](https://img.shields.io/npm/v/@mcp-native/webview)](https://www.npmjs.com/package/@mcp-native/webview)
+[![downloads](https://img.shields.io/npm/dm/@mcp-native/webview)](https://www.npmjs.com/package/@mcp-native/webview)
+[![license](https://img.shields.io/npm/l/@mcp-native/webview)](https://github.com/pablospaniard/mcp-native/blob/main/LICENSE)
+
+[GitHub](https://github.com/pablospaniard/mcp-native) · [Architecture](https://github.com/pablospaniard/mcp-native/blob/main/docs/RFC-0001-architecture.md) · [Security](https://github.com/pablospaniard/mcp-native/blob/main/SECURITY.md)
+
+</div>
+
+> **Experimental:** this package defines document validation and policy decisions. It does not yet mount or sandbox a platform WebView.
+
+`@mcp-native/webview` handles the compatibility path for MCP resources that contain HTML. It recognizes supported MIME types, prefers inline documents, and rejects remote documents unless the host explicitly grants them through policy.
+
+## Install
+
+```bash
+npm install @mcp-native/webview
+```
+
+`@mcp-native/core` is installed as a dependency. The package is ESM-only and includes TypeScript declarations.
+
+## Inline HTML
+
+```ts
+import { createWebViewDocument } from "@mcp-native/webview";
+
+const document = createWebViewDocument({
+  uri: "mcp://example/app",
+  mimeType: "text/html",
+  text: "<main>Hello from an MCP App</main>",
+});
+
+// { kind: "inline", html: "...", baseUrl: "mcp://example/app" }
+```
+
+## Remote documents are denied by default
+
+```ts
+import { createWebViewDocument, WebViewPolicyError } from "@mcp-native/webview";
+
+const resource = {
+  uri: "https://example.com/app",
+  mimeType: "text/html",
+};
+
+try {
+  createWebViewDocument(resource);
+} catch (error) {
+  if (error instanceof WebViewPolicyError) {
+    console.error(error.message);
+  }
+}
+
+const allowed = createWebViewDocument(resource, {
+  allowRemoteDocuments: true,
+});
+```
+
+## Public API
+
+| Export                  | Purpose                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `isHtmlResource`        | Returns whether a resource declares a supported HTML MIME type.                |
+| `createWebViewDocument` | Validates a resource and returns an inline or policy-approved remote document. |
+| `WebViewPolicy`         | Host policy controlling whether remote documents are allowed.                  |
+| `WebViewDocument`       | Discriminated union for inline and remote documents.                           |
+| `WebViewPolicyError`    | Error thrown for unsupported MIME types or denied remote documents.            |
+
+Supported MIME types are `text/html` and `text/html+skybridge`.
+
+## Host responsibilities
+
+Returning a `WebViewDocument` is not permission to render it without further controls. A production host must still define:
+
+- allowed origins and navigation rules;
+- bridge message schemas and directionality;
+- storage, cookie, download, and external-link policy;
+- camera, microphone, location, clipboard, and filesystem permissions;
+- process isolation and platform-specific WebView hardening.
+
+See the repository's [security policy](https://github.com/pablospaniard/mcp-native/blob/main/SECURITY.md) before expanding this boundary. Install [`mcp-native`](https://www.npmjs.com/package/mcp-native) for the complete public API.
+
+## License
 
-Early development.
+[MIT](https://github.com/pablospaniard/mcp-native/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { McpResource } from "@mcp-native/core";
+export interface WebViewPolicy {
+    readonly allowRemoteDocuments?: boolean;
+}
+export type WebViewDocument = {
+    readonly kind: "inline";
+    readonly html: string;
+    readonly baseUrl: string;
+} | {
+    readonly kind: "remote";
+    readonly uri: string;
+};
+export declare class WebViewPolicyError extends Error {
+    constructor(message: string);
+}
+export declare function isHtmlResource(resource: McpResource): boolean;
+export declare function createWebViewDocument(resource: McpResource, policy?: WebViewPolicy): WebViewDocument;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,WAAW,EACrB,MAAM,GAAE,aAAkB,GACzB,eAAe,CAgBjB"}

package/dist/index.js

@@ -0,0 +1,23 @@
+const HTML_MIME_TYPES = new Set(["text/html", "text/html+skybridge"]);
+export class WebViewPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebViewPolicyError";
+    }
+}
+export function isHtmlResource(resource) {
+    return resource.mimeType !== undefined && HTML_MIME_TYPES.has(resource.mimeType);
+}
+export function createWebViewDocument(resource, policy = {}) {
+    if (!isHtmlResource(resource)) {
+        throw new WebViewPolicyError(`Unsupported WebView MIME type: ${resource.mimeType ?? "unknown"}`);
+    }
+    if (resource.text !== undefined) {
+        return { kind: "inline", html: resource.text, baseUrl: resource.uri };
+    }
+    if (policy.allowRemoteDocuments !== true) {
+        throw new WebViewPolicyError("Remote WebView documents are disabled by policy");
+    }
+    return { kind: "remote", uri: resource.uri };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAC;AAiBtE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,UAAU,cAAc,CAAC,QAAqB;IAClD,OAAO,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,QAAqB,EACrB,MAAM,GAAkB,EAAE;IAE1B,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,kBAAkB,CAC1B,kCAAkC,QAAQ,CAAC,QAAQ,IAAI,SAAS,EAAE,CACnE,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC;IACxE,CAAC;IAED,IAAI,MAAM,CAAC,oBAAoB,KAAK,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,kBAAkB,CAAC,iDAAiD,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC;AAC/C,CAAC"}

package/package.json

@@ -1,12 +1,42 @@
 {
   "name": "@mcp-native/webview",
-  "version": "0.0.1",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.0.3",
+  "description": "Policy-gated WebView fallback primitives for MCP Native.",
+  "keywords": [
+    "mcp",
+    "mcp-apps",
+    "model-context-protocol",
+    "security",
+    "webview"
+  ],
+  "homepage": "https://github.com/pablospaniard/mcp-native#readme",
+  "bugs": {
+    "url": "https://github.com/pablospaniard/mcp-native/issues"
   },
-  "keywords": [],
-  "author": "",
   "license": "MIT",
-  "description": "MCP Native - webview package"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pablospaniard/mcp-native.git",
+    "directory": "packages/webview"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mcp-native/core": "^0.0.3"
+  }
 }

package/index.js

@@ -1 +0,0 @@
-module.exports = {};