@nativewindow/ipc 1.0.1 → 1.0.2

package/README.md

@@ -115,16 +115,16 @@ Create a typed channel client inside the webview for use in bundled apps.
 
 ### Channel Options
 
-| Option                 | Type        | Default    | Description                            |
-| ---------------------- | ----------- | ---------- | -------------------------------------- |
+| Option                 | Type                                     | Default    | Description                                                                                   |
+| ---------------------- | ---------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
 | `schemas`              | `{ host: SchemaMap; client: SchemaMap }` | _required_ | Directional schemas — `host` for events the host sends, `client` for events the webview sends |
-| `injectClient`         | `boolean`   | `true`     | Auto-inject client script into webview |
-| `onValidationError`    | `function`  | —          | Called when a payload fails validation |
-| `trustedOrigins`       | `string[]`  | —          | Restrict IPC to specific origins       |
-| `maxMessageSize`       | `number`    | `1048576`  | Max message size in bytes              |
-| `rateLimit`            | `number`    | —          | Max messages per second                |
-| `maxListenersPerEvent` | `number`    | —          | Max listeners per event type           |
-| `channelId`            | `string`    | —          | Unique channel identifier              |
+| `injectClient`         | `boolean`                                | `true`     | Auto-inject client script into webview                                                        |
+| `onValidationError`    | `function`                               | —          | Called when a payload fails validation                                                        |
+| `trustedOrigins`       | `string[]`                               | —          | Restrict IPC to specific origins                                                              |
+| `maxMessageSize`       | `number`                                 | `1048576`  | Max message size in bytes                                                                     |
+| `rateLimit`            | `number`                                 | —          | Max messages per second                                                                       |
+| `maxListenersPerEvent` | `number`                                 | —          | Max listeners per event type                                                                  |
+| `channelId`            | `string`                                 | —          | Unique channel identifier                                                                     |
 
 ### Schema Support
 

package/dist/client.js

@@ -1,129 +1,156 @@
-const MAX_MESSAGE_SIZE = 1048576;
+//#region client.ts
+/**
+* Default maximum IPC message size (1 MB).
+* @internal
+*/
+var MAX_MESSAGE_SIZE = 1048576;
 function encode(type, payload) {
-  return JSON.stringify({ $ch: type, p: payload });
+	return JSON.stringify({
+		$ch: type,
+		p: payload
+	});
 }
-const DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+/** @internal Keys that could pollute prototypes if merged into target objects. */
+var DANGEROUS_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
 function decode(raw) {
-  if (raw.length > MAX_MESSAGE_SIZE) return null;
-  try {
-    const parsed = JSON.parse(
-      raw,
-      (key, value) => DANGEROUS_KEYS.has(key) ? void 0 : value
-    );
-    if (typeof parsed === "object" && parsed !== null && "$ch" in parsed && typeof parsed.$ch === "string") {
-      return parsed;
-    }
-  } catch {
-  }
-  return null;
+	if (raw.length > MAX_MESSAGE_SIZE) return null;
+	try {
+		const parsed = JSON.parse(raw, (key, value) => DANGEROUS_KEYS.has(key) ? void 0 : value);
+		if (typeof parsed === "object" && parsed !== null && "$ch" in parsed && typeof parsed.$ch === "string") return parsed;
+	} catch {}
+	return null;
 }
+/**
+* Validate a payload against a schema using `safeParse()`.
+* Returns the parsed data on success so that schema transforms are honored.
+* @internal
+*/
 function validatePayload(schema, data) {
-  const result = schema.safeParse(data);
-  return result.success ? { success: true, data: result.data } : { success: false };
+	const result = schema.safeParse(data);
+	return result.success ? {
+		success: true,
+		data: result.data
+	} : { success: false };
 }
+/**
+* Create a typed channel client for use inside the webview.
+* Call this once; it hooks into the native IPC bridge.
+*
+* The client sends events defined by the `client` schemas and receives
+* events defined by the `host` schemas — the inverse of the host side.
+*
+* @example
+* ```ts
+* import { z } from "zod";
+* import { createChannelClient } from "native-window-ipc/client";
+*
+* const ch = createChannelClient({
+*   schemas: {
+*     host: { "update-title": z.string() },
+*     client: { "user-click": z.object({ x: z.number(), y: z.number() }) },
+*   },
+* });
+*
+* ch.send("user-click", { x: 10, y: 20 }); // only client events
+* ch.on("update-title", (title) => {        // only host events
+*   document.title = title;
+* });
+* ```
+*/
 function createChannelClient(options) {
-  const { schemas, onValidationError } = options;
-  const hostSchemas = schemas.host;
-  schemas.client;
-  const _push = Array.prototype.push;
-  const _indexOf = Array.prototype.indexOf;
-  const _splice = Array.prototype.splice;
-  const listeners = /* @__PURE__ */ new Map();
-  const channel = {
-    send(...args) {
-      const [type, payload] = args;
-      window.ipc.postMessage(encode(type, payload));
-    },
-    on(type, handler) {
-      let set = listeners.get(type);
-      if (!set) {
-        set = /* @__PURE__ */ new Set();
-        listeners.set(type, set);
-      }
-      set.add(handler);
-    },
-    off(type, handler) {
-      const set = listeners.get(type);
-      if (set) set.delete(handler);
-    }
-  };
-  const externalListeners = [];
-  const orig = window.__native_message__;
-  try {
-    Object.defineProperty(window, "__native_message__", {
-      value(msg) {
-        const env = decode(msg);
-        if (env) {
-          if (!(env.$ch in hostSchemas)) {
-            for (const fn of externalListeners) {
-              try {
-                fn(msg);
-              } catch {
-              }
-            }
-            orig?.(msg);
-            return;
-          }
-          const set = listeners.get(env.$ch);
-          if (set) {
-            const schema = hostSchemas[env.$ch];
-            let validatedPayload = env.p;
-            if (schema) {
-              const result = validatePayload(schema, env.p);
-              if (!result.success) {
-                onValidationError?.(env.$ch, env.p);
-                return;
-              }
-              validatedPayload = result.data;
-            }
-            for (const fn of set) {
-              try {
-                fn(validatedPayload);
-              } catch {
-              }
-            }
-            return;
-          }
-        }
-        for (const fn of externalListeners) {
-          try {
-            fn(msg);
-          } catch {
-          }
-        }
-        orig?.(msg);
-      },
-      writable: false,
-      configurable: false
-    });
-  } catch {
-  }
-  try {
-    Object.defineProperty(window, "__native_message_listeners__", {
-      value: Object.freeze({
-        add(fn) {
-          if (typeof fn === "function") _push.call(externalListeners, fn);
-        },
-        remove(fn) {
-          const idx = _indexOf.call(externalListeners, fn);
-          if (idx !== -1) _splice.call(externalListeners, idx, 1);
-        }
-      }),
-      writable: false,
-      configurable: false
-    });
-  } catch {
-  }
-  try {
-    Object.defineProperty(window, "__channel__", {
-      value: channel,
-      writable: false,
-      configurable: false
-    });
-  } catch {
-  }
-  return channel;
+	const { schemas, onValidationError } = options;
+	const hostSchemas = schemas.host;
+	schemas.client;
+	const _push = Array.prototype.push;
+	const _indexOf = Array.prototype.indexOf;
+	const _splice = Array.prototype.splice;
+	const listeners = /* @__PURE__ */ new Map();
+	const channel = {
+		send(...args) {
+			const [type, payload] = args;
+			window.ipc.postMessage(encode(type, payload));
+		},
+		on(type, handler) {
+			let set = listeners.get(type);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				listeners.set(type, set);
+			}
+			set.add(handler);
+		},
+		off(type, handler) {
+			const set = listeners.get(type);
+			if (set) set.delete(handler);
+		}
+	};
+	const externalListeners = [];
+	const orig = window.__native_message__;
+	try {
+		Object.defineProperty(window, "__native_message__", {
+			value(msg) {
+				const env = decode(msg);
+				if (env) {
+					if (!(env.$ch in hostSchemas)) {
+						for (const fn of externalListeners) try {
+							fn(msg);
+						} catch {}
+						orig?.(msg);
+						return;
+					}
+					const set = listeners.get(env.$ch);
+					if (set) {
+						const schema = hostSchemas[env.$ch];
+						let validatedPayload = env.p;
+						if (schema) {
+							const result = validatePayload(schema, env.p);
+							if (!result.success) {
+								onValidationError?.(env.$ch, env.p);
+								return;
+							}
+							validatedPayload = result.data;
+						}
+						for (const fn of set) try {
+							fn(validatedPayload);
+						} catch {}
+						return;
+					}
+				}
+				for (const fn of externalListeners) try {
+					fn(msg);
+				} catch {}
+				orig?.(msg);
+			},
+			writable: false,
+			configurable: false
+		});
+	} catch {}
+	try {
+		Object.defineProperty(window, "__native_message_listeners__", {
+			value: Object.freeze({
+				add(fn) {
+					if (typeof fn === "function") _push.call(externalListeners, fn);
+				},
+				remove(fn) {
+					const idx = _indexOf.call(externalListeners, fn);
+					if (idx !== -1) _splice.call(externalListeners, idx, 1);
+				}
+			}),
+			writable: false,
+			configurable: false
+		});
+	} catch {}
+	try {
+		Object.defineProperty(window, "__channel__", {
+			value: channel,
+			writable: false,
+			configurable: false
+		});
+	} catch {}
+	return channel;
 }
-export {
-  createChannelClient
-};
+//#endregion
+export { createChannelClient };

package/dist/index.js

@@ -1,54 +1,107 @@
 import { NativeWindow } from "@nativewindow/webview";
-const MAX_MESSAGE_SIZE = 1048576;
+//#region index.ts
+/**
+* Default maximum IPC message size (1 MB).
+* Messages exceeding this limit are silently dropped to prevent
+* memory exhaustion from oversized payloads.
+* @internal
+*/
+var MAX_MESSAGE_SIZE = 1048576;
+/**
+* Validate a payload against a schema using `safeParse()`.
+* Returns the parsed data on success so that schema transforms are honored.
+* @internal
+*/
 function validatePayload(schema, data) {
-  const result = schema.safeParse(data);
-  return result.success ? { success: true, data: result.data } : { success: false };
+	const result = schema.safeParse(data);
+	return result.success ? {
+		success: true,
+		data: result.data
+	} : { success: false };
 }
 function isEnvelope(data) {
-  return typeof data === "object" && data !== null && "$ch" in data && typeof data.$ch === "string";
+	return typeof data === "object" && data !== null && "$ch" in data && typeof data.$ch === "string";
 }
 function encode(type, payload) {
-  return JSON.stringify({ $ch: type, p: payload });
+	return JSON.stringify({
+		$ch: type,
+		p: payload
+	});
 }
-const DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+/** @internal Keys that could pollute prototypes if merged into target objects. */
+var DANGEROUS_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
 function decode(raw, maxSize = MAX_MESSAGE_SIZE) {
-  if (raw.length > maxSize) return null;
-  try {
-    const parsed = JSON.parse(
-      raw,
-      (key, value) => DANGEROUS_KEYS.has(key) ? void 0 : value
-    );
-    return isEnvelope(parsed) ? parsed : null;
-  } catch {
-    return null;
-  }
+	if (raw.length > maxSize) return null;
+	try {
+		const parsed = JSON.parse(raw, (key, value) => DANGEROUS_KEYS.has(key) ? void 0 : value);
+		return isEnvelope(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
 }
+/**
+* Normalize an origin string using the WHATWG URL Standard.
+* Lowercases scheme/host, strips default ports (80/443), and
+* strips userinfo — matching the Rust `url` crate behavior.
+* Returns `null` for malformed URLs or opaque origins.
+* @internal
+*/
 function normalizeOrigin(origin) {
-  try {
-    const o = new URL(origin).origin;
-    return o === "null" ? null : o;
-  } catch {
-    return null;
-  }
+	try {
+		const o = new URL(origin).origin;
+		return o === "null" ? null : o;
+	} catch {
+		return null;
+	}
 }
+/**
+* Check if a URL's origin matches any of the trusted origins.
+* The `trustedOrigins` array must already be normalized via
+* {@link normalizeOrigin} for correct comparison.
+* @internal
+*/
 function isOriginTrusted(url, trustedOrigins) {
-  try {
-    const parsed = new URL(url);
-    return trustedOrigins.includes(parsed.origin);
-  } catch {
-    return false;
-  }
+	try {
+		const parsed = new URL(url);
+		return trustedOrigins.includes(parsed.origin);
+	} catch {
+		return false;
+	}
 }
+/**
+* Returns the webview-side channel client as a self-contained JS string.
+* This is the same logic as `client.ts`, minified for injection.
+* Can also be embedded in a `<script>` tag manually.
+*
+* When `options.channelId` is provided, the injected script prefixes all
+* `$ch` values with the channel ID, matching the host-side behavior.
+*
+* **Note:** The injected client does not support payload validation.
+* For client-side validation, use the bundled {@link createChannelClient}
+* import from `native-window-ipc/client` with the `schemas` option.
+*
+* @example
+* ```ts
+* // Without namespace (default)
+* const script = getClientScript();
+*
+* // With namespace
+* const script = getClientScript({ channelId: "abc123" });
+* ```
+*/
 function getClientScript(options) {
-  const prefix = options?.channelId ?? "";
-  const prefixLiteral = JSON.stringify(prefix);
-  return `(function(){
+	const prefix = options?.channelId ?? "";
+	return `(function(){
 var _slice=Array.prototype.slice;
 var _filter=Array.prototype.filter;
 var _push=Array.prototype.push;
 var _indexOf=Array.prototype.indexOf;
 var _splice=Array.prototype.splice;
-var _pfx=${prefixLiteral};
+var _pfx=${JSON.stringify(prefix)};
 var _l=Object.create(null);
 var _el=[];
 function _e(t,p){return JSON.stringify({$ch:_pfx?_pfx+":"+t:t,p:p})}
@@ -70,108 +123,146 @@ try{Object.defineProperty(window,'__native_message_listeners__',{value:Object.fr
 try{Object.defineProperty(window,'__channel__',{value:Object.freeze(ch),writable:false,configurable:false})}catch(e){console.error('[native-window] Failed to define __channel__:',e)}
 })();`;
 }
+/**
+* Wrap an existing NativeWindow with a typed message channel.
+*
+* Schemas are required — they provide both TypeScript types and runtime
+* validation for each event. Compatible with Zod v4, Valibot v1, and
+* any schema library implementing the `safeParse()` interface.
+*
+* The `schemas` option uses directional groups:
+* - `host`: events the host sends to the client.
+* - `client`: events the client sends to the host.
+*
+* On the returned channel, `send()` only accepts `host` event types and
+* `on()`/`off()` only accept `client` event types.
+*
+* @security **Origin restriction:** When `trustedOrigins` is configured,
+* both client script injection and incoming IPC messages are restricted to
+* pages whose URL origin matches the whitelist. The native `onMessage`
+* callback now includes the source page URL, enabling the channel to reject
+* messages from untrusted origins. Empty source URLs (e.g. `about:blank`,
+* `data:` URIs) are treated as untrusted when `trustedOrigins` is set.
+*
+* @example
+* ```ts
+* import { z } from "zod";
+* import { createChannel } from "native-window-ipc";
+*
+* const ch = createChannel(win, {
+*   schemas: {
+*     host: { "update-title": z.string() },
+*     client: { "user-click": z.object({ x: z.number(), y: z.number() }) },
+*   },
+* });
+* ch.send("update-title", "Hello"); // only host events
+* ch.on("user-click", (p) => {});   // only client events, p: { x: number; y: number }
+* ```
+*/
 function createChannel(win, options) {
-  const {
-    schemas,
-    injectClient = true,
-    onValidationError,
-    trustedOrigins,
-    maxMessageSize,
-    rateLimit,
-    maxListenersPerEvent,
-    channelId: channelIdOpt
-  } = options;
-  schemas.host;
-  const clientSchemas = schemas.client;
-  const channelId = channelIdOpt === true ? crypto.randomUUID().replace(/-/g, "").slice(0, 16) : channelIdOpt ?? "";
-  const normalizedOrigins = trustedOrigins?.map(normalizeOrigin).filter((o) => o !== null);
-  const prefixCh = (type) => channelId ? `${channelId}:${type}` : type;
-  const unprefixCh = (ch) => {
-    if (!channelId) return ch;
-    const pfx = `${channelId}:`;
-    return ch.startsWith(pfx) ? ch.slice(pfx.length) : null;
-  };
-  const listeners = /* @__PURE__ */ new Map();
-  let _bucketTokens = rateLimit ?? 0;
-  let _bucketLastRefill = Date.now();
-  win.onMessage((raw, sourceUrl) => {
-    if (rateLimit !== void 0 && rateLimit > 0) {
-      const now = Date.now();
-      const elapsed = now - _bucketLastRefill;
-      if (elapsed >= 1e3) {
-        _bucketTokens = rateLimit;
-        _bucketLastRefill = now;
-      }
-      if (_bucketTokens <= 0) return;
-      _bucketTokens--;
-    }
-    const env = decode(raw, maxMessageSize);
-    if (!env) return;
-    const eventType = unprefixCh(env.$ch);
-    if (eventType === null) return;
-    if (normalizedOrigins && normalizedOrigins.length > 0) {
-      if (!isOriginTrusted(sourceUrl, normalizedOrigins)) return;
-    }
-    const set = listeners.get(eventType);
-    if (!set) return;
-    if (!(eventType in clientSchemas)) return;
-    const schema = clientSchemas[eventType];
-    let validatedPayload = env.p;
-    if (schema) {
-      const result = validatePayload(schema, env.p);
-      if (!result.success) {
-        onValidationError?.(eventType, env.p);
-        return;
-      }
-      validatedPayload = result.data;
-    }
-    for (const fn of set) {
-      try {
-        fn(validatedPayload);
-      } catch {
-      }
-    }
-  });
-  if (injectClient) {
-    if (!normalizedOrigins || normalizedOrigins.length === 0) {
-      win.unsafe.evaluateJs(getClientScript({ channelId: channelId || void 0 }));
-    }
-    win.onPageLoad((event, url) => {
-      if (event !== "finished") return;
-      if (normalizedOrigins && normalizedOrigins.length > 0) {
-        if (!isOriginTrusted(url, normalizedOrigins)) return;
-      }
-      win.unsafe.evaluateJs(getClientScript({ channelId: channelId || void 0 }));
-    });
-  }
-  return {
-    window: win,
-    send(...args) {
-      const [type, payload] = args;
-      win.postMessage(encode(prefixCh(type), payload));
-    },
-    on(type, handler) {
-      if (!(type in clientSchemas)) return;
-      let set = listeners.get(type);
-      if (!set) {
-        set = /* @__PURE__ */ new Set();
-        listeners.set(type, set);
-      }
-      if (maxListenersPerEvent !== void 0 && set.size >= maxListenersPerEvent) return;
-      set.add(handler);
-    },
-    off(type, handler) {
-      const set = listeners.get(type);
-      if (set) set.delete(handler);
-    }
-  };
+	const { schemas, injectClient = true, onValidationError, trustedOrigins, maxMessageSize, rateLimit, maxListenersPerEvent, channelId: channelIdOpt } = options;
+	schemas.host;
+	const clientSchemas = schemas.client;
+	const channelId = channelIdOpt === true ? crypto.randomUUID().replace(/-/g, "").slice(0, 16) : channelIdOpt ?? "";
+	const normalizedOrigins = trustedOrigins?.map(normalizeOrigin).filter((o) => o !== null);
+	const prefixCh = (type) => channelId ? `${channelId}:${type}` : type;
+	const unprefixCh = (ch) => {
+		if (!channelId) return ch;
+		const pfx = `${channelId}:`;
+		return ch.startsWith(pfx) ? ch.slice(pfx.length) : null;
+	};
+	const listeners = /* @__PURE__ */ new Map();
+	let _bucketTokens = rateLimit ?? 0;
+	let _bucketLastRefill = Date.now();
+	win.onMessage((raw, sourceUrl) => {
+		if (rateLimit !== void 0 && rateLimit > 0) {
+			const now = Date.now();
+			if (now - _bucketLastRefill >= 1e3) {
+				_bucketTokens = rateLimit;
+				_bucketLastRefill = now;
+			}
+			if (_bucketTokens <= 0) return;
+			_bucketTokens--;
+		}
+		const env = decode(raw, maxMessageSize);
+		if (!env) return;
+		const eventType = unprefixCh(env.$ch);
+		if (eventType === null) return;
+		if (normalizedOrigins && normalizedOrigins.length > 0) {
+			if (!isOriginTrusted(sourceUrl, normalizedOrigins)) return;
+		}
+		const set = listeners.get(eventType);
+		if (!set) return;
+		if (!(eventType in clientSchemas)) return;
+		const schema = clientSchemas[eventType];
+		let validatedPayload = env.p;
+		if (schema) {
+			const result = validatePayload(schema, env.p);
+			if (!result.success) {
+				onValidationError?.(eventType, env.p);
+				return;
+			}
+			validatedPayload = result.data;
+		}
+		for (const fn of set) try {
+			fn(validatedPayload);
+		} catch {}
+	});
+	if (injectClient) {
+		if (!normalizedOrigins || normalizedOrigins.length === 0) win.unsafe.evaluateJs(getClientScript({ channelId: channelId || void 0 }));
+		win.onPageLoad((event, url) => {
+			if (event !== "finished") return;
+			if (normalizedOrigins && normalizedOrigins.length > 0) {
+				if (!isOriginTrusted(url, normalizedOrigins)) return;
+			}
+			win.unsafe.evaluateJs(getClientScript({ channelId: channelId || void 0 }));
+		});
+	}
+	return {
+		window: win,
+		send(...args) {
+			const [type, payload] = args;
+			win.postMessage(encode(prefixCh(type), payload));
+		},
+		on(type, handler) {
+			if (!(type in clientSchemas)) return;
+			let set = listeners.get(type);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				listeners.set(type, set);
+			}
+			if (maxListenersPerEvent !== void 0 && set.size >= maxListenersPerEvent) return;
+			set.add(handler);
+		},
+		off(type, handler) {
+			const set = listeners.get(type);
+			if (set) set.delete(handler);
+		}
+	};
 }
+/**
+* Create a new NativeWindow and immediately wrap it with a typed channel.
+*
+* @example
+* ```ts
+* import { z } from "zod";
+* import { createWindow } from "native-window-ipc";
+*
+* const ch = createWindow(
+*   { title: "My App" },
+*   {
+*     schemas: {
+*       host: { "update-title": z.string() },
+*       client: { "user-click": z.object({ x: z.number(), y: z.number() }) },
+*     },
+*   },
+* );
+* ch.send("update-title", "Hello"); // only host events
+* ch.on("user-click", (p) => {});   // only client events
+* ```
+*/
 function createWindow(windowOptions, channelOptions) {
-  const win = new NativeWindow(windowOptions);
-  return createChannel(win, channelOptions);
+	return createChannel(new NativeWindow(windowOptions), channelOptions);
 }
-export {
-  createChannel,
-  createWindow,
-  getClientScript
-};
+//#endregion
+export { createChannel, createWindow, getClientScript };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativewindow/ipc",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Typesafe IPC channels for native-window (beta)",
   "homepage": "https://nativewindow.fcannizzaro.com",
   "bugs": {
@@ -46,16 +46,16 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",
-    "arktype": "^2.1.20",
-    "valibot": "^1.2.0",
-    "vite": "^7.3.1",
+    "arktype": "^2.2.0",
+    "valibot": "^1.3.1",
+    "vite": "^8.0.3",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.18",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@nativewindow/webview": "workspace:*",
-    "typescript": "^5",
+    "typescript": "^6.0.2",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {