@ai-ecoverse/sliccy-browser 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@ai-ecoverse/sliccy-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "sliccy:browser for jsh, over CDP",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-ecoverse/slicc-cdp.git",
+    "directory": "packages/sliccy-browser"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "slicc": "./src/browser.js",
+      "import": "./src/browser.js",
+      "require": "./src/browser.js",
+      "default": "./src/browser.js"
+    }
+  },
+  "main": "./src/browser.js",
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@ai-ecoverse/slicc-cdp": "1.19.1"
+  }
+}

package/src/browser.js

@@ -0,0 +1,576 @@
+import { appendFile } from 'node:fs/promises';
+import path from 'node:path';
+import { connect } from '@ai-ecoverse/slicc-cdp';
+import { buildBrowserFetchScript } from './fetch-script.js';
+import { routerSource } from './ws-router.js';
+
+const BINDING = '__sliccWsRouterReport';
+const LOAD_TIMEOUT_MS = 15000;
+
+let opening;
+const sessions = new Map();
+const routers = new Set();
+const subscribers = new Map();
+let seq = 1;
+let listening = false;
+let active = 0;
+let idle;
+
+function openClient() {
+  if (!opening) {
+    opening = connect().catch((error) => {
+      opening = undefined;
+      throw error;
+    });
+  }
+  return opening;
+}
+
+async function using(work) {
+  active += 1;
+  clearTimeout(idle);
+  idle = undefined;
+  try {
+    return await work();
+  } finally {
+    active -= 1;
+    release();
+  }
+}
+
+function release() {
+  if (active > 0 || subscribers.size > 0 || !opening || idle) return;
+  idle = setTimeout(closeIdle, 0);
+}
+
+function closeIdle() {
+  idle = undefined;
+  if (active > 0 || subscribers.size > 0 || !opening) return;
+  const closing = opening;
+  opening = undefined;
+  sessions.clear();
+  routers.clear();
+  listening = false;
+  closing.then(
+    (client) => client.close(),
+    () => undefined
+  );
+}
+
+function ignoreMethod(prefix) {
+  return (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith(prefix)) return undefined;
+    throw error;
+  };
+}
+
+async function sessionFor(targetId) {
+  const client = await openClient();
+  const cached = sessions.get(targetId);
+  if (cached) return { client, sessionId: cached };
+  const sessionId = await client.attach(targetId);
+  await client.send('Page.enable', {}, sessionId).catch(ignoreMethod('Page.enable:'));
+  await client.send('Runtime.enable', {}, sessionId).catch(ignoreMethod('Runtime.enable:'));
+  await client.send('Network.enable', {}, sessionId).catch(ignoreMethod('Network.enable:'));
+  sessions.set(targetId, sessionId);
+  listen(client);
+  return { client, sessionId };
+}
+
+function listen(client) {
+  if (listening) return;
+  listening = true;
+  client.on('Runtime.bindingCalled', (message) => {
+    const params = message?.params;
+    if (!params || params.name !== BINDING || typeof params.payload !== 'string') return;
+    let body;
+    try {
+      body = JSON.parse(params.payload);
+    } catch {
+      return;
+    }
+    if (!body || typeof body.subId !== 'string') return;
+    void deliver(body.subId, body.payload);
+  });
+}
+
+function targetIdOf(tab) {
+  if (typeof tab === 'string') return tab;
+  if (tab && typeof tab === 'object' && typeof tab.targetId === 'string') return tab.targetId;
+  throw new TypeError('browser: expected a tab handle or targetId string');
+}
+
+function patternOf(value) {
+  if (value === undefined) return undefined;
+  if (value instanceof RegExp) return value.source;
+  if (typeof value === 'string') return value;
+  throw new TypeError('browser: url match must be a string or RegExp');
+}
+
+function compilePattern(source, label) {
+  try {
+    return new RegExp(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${label}: invalid url match regex: ${message}`);
+  }
+}
+
+function hostnameOf(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
+
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+async function listTabs() {
+  const client = await openClient();
+  const result = await client.send('Target.getTargets');
+  const infos = Array.isArray(result?.targetInfos) ? result.targetInfos : [];
+  return infos
+    .filter((info) => info && info.type === 'page' && typeof info.targetId === 'string')
+    .map((info) => ({
+      targetId: info.targetId,
+      url: typeof info.url === 'string' ? info.url : '',
+      title: typeof info.title === 'string' ? info.title : '',
+    }));
+}
+
+export async function findTab(query) {
+  return using(() => findTabNow(query));
+}
+
+async function findTabNow(query = {}) {
+  const domain = typeof query.domain === 'string' ? query.domain : undefined;
+  const urlMatch = patternOf(query.urlMatch);
+  if (domain === undefined && urlMatch === undefined) {
+    throw new Error('browser.findTab: query requires `domain` or `urlMatch`');
+  }
+  const tabs = await listTabs();
+  if (domain !== undefined) {
+    const wanted = domain.toLowerCase();
+    return tabs.find((tab) => hostnameOf(tab.url)?.toLowerCase() === wanted) ?? null;
+  }
+  const re = compilePattern(urlMatch, 'browser.findTab');
+  return tabs.find((tab) => re.test(tab.url)) ?? null;
+}
+
+export async function ensureTab(url, options) {
+  return using(() => ensureTabNow(url, options));
+}
+
+async function ensureTabNow(url, options = {}) {
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new TypeError('browser.ensureTab: url must be a string');
+  }
+  const tabs = await listTabs();
+  const matchUrl = patternOf(options.matchUrl);
+  if (matchUrl !== undefined) {
+    const re = compilePattern(matchUrl, 'browser.ensureTab');
+    const hit = tabs.find((tab) => re.test(tab.url));
+    if (hit) return hit;
+  } else {
+    const wanted = originOf(url);
+    if (wanted) {
+      const hit = tabs.find((tab) => originOf(tab.url) === wanted);
+      if (hit) return hit;
+    }
+  }
+  const client = await openClient();
+  const created = await client.send('Target.createTarget', { url: 'about:blank' });
+  const targetId = created?.targetId;
+  if (typeof targetId !== 'string' || targetId.length === 0) {
+    throw new Error('Target.createTarget returned no targetId');
+  }
+  const { sessionId } = await sessionFor(targetId);
+  if (url === 'about:blank') await waitForLoad(client, sessionId);
+  else await navigateAndWait(client, sessionId, url);
+  const live = (await listTabs()).find((tab) => tab.targetId === targetId);
+  return live ?? { targetId, url, title: '' };
+}
+
+function evalSource(tab, source) {
+  return evaluate(tab, source, false);
+}
+
+function evalSourceAsync(tab, source) {
+  return evaluate(tab, source, true);
+}
+
+export { evalSource as eval, evalSourceAsync as evalAsync };
+
+function evaluate(tab, source, awaitPromise) {
+  return using(() => evaluateNow(tab, source, awaitPromise));
+}
+
+async function evaluateNow(tab, source, awaitPromise) {
+  const { client, sessionId } = await sessionFor(targetIdOf(tab));
+  const result = await client.send(
+    'Runtime.evaluate',
+    {
+      expression: serializeEvalSource(source),
+      returnByValue: true,
+      awaitPromise,
+    },
+    sessionId
+  );
+  if (result?.exceptionDetails) {
+    throw new Error(exceptionMessage(result.exceptionDetails));
+  }
+  return unwrapEvalResult(result?.result?.value);
+}
+
+export async function cookie(tab, name) {
+  if (typeof name !== 'string') throw new TypeError('browser.cookie: name must be a string');
+  return using(() => cookieNow(tab, name));
+}
+
+async function cookieNow(tab, name) {
+  const { client, sessionId } = await sessionFor(targetIdOf(tab));
+  const result = await client.send('Network.getCookies', {}, sessionId);
+  const cookies = Array.isArray(result?.cookies) ? result.cookies : [];
+  const hit = cookies.find((item) => item && item.name === name);
+  return hit && typeof hit.value === 'string' ? hit.value : null;
+}
+
+export async function localStorage(tab, key) {
+  if (typeof key !== 'string') throw new TypeError('browser.localStorage: key must be a string');
+  const raw = await evaluate(
+    tab,
+    `(function(){try{var v=window.localStorage.getItem(${JSON.stringify(key)});return v===null?null:String(v);}catch(e){return null;}})()`,
+    false
+  );
+  if (raw === null || raw === undefined) return null;
+  return typeof raw === 'string' ? raw : String(raw);
+}
+
+export async function fetch(tab, url, opts = {}) {
+  if (typeof url !== 'string') throw new TypeError('browser.fetch: url must be a string');
+  const script = await buildBrowserFetchScript(url, opts);
+  return evalSourceAsync(tab, script);
+}
+
+function serializeEvalSource(source) {
+  if (typeof source === 'function') return `(${source.toString()})()`;
+  if (typeof source === 'string') return source;
+  throw new TypeError('browser.eval/evalAsync: source must be a function or string');
+}
+
+function exceptionMessage(details) {
+  const description = details.exception?.description;
+  if (typeof description === 'string') return description;
+  if (typeof details.text === 'string') return details.text;
+  return 'evaluation failed';
+}
+
+function unwrapEvalResult(value) {
+  if (typeof value !== 'string') return value;
+  const first = tryParseJson(value);
+  if (first === undefined) return value;
+  if (first !== null && typeof first === 'object') return first;
+  if (typeof first === 'string') {
+    const trimmed = first.trim();
+    if (trimmed.length > 0 && (trimmed[0] === '{' || trimmed[0] === '[')) {
+      const second = tryParseJson(first);
+      if (second !== null && typeof second === 'object') return second;
+    }
+    return first;
+  }
+  return value;
+}
+
+function tryParseJson(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return undefined;
+  const first = trimmed[0];
+  const looksJson =
+    first === '{' ||
+    first === '[' ||
+    first === '"' ||
+    first === '-' ||
+    (first >= '0' && first <= '9') ||
+    trimmed === 'true' ||
+    trimmed === 'false' ||
+    trimmed === 'null';
+  if (!looksJson) return undefined;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
+function pageIsSettled(client, sessionId) {
+  return client
+    .send(
+      'Runtime.evaluate',
+      { expression: 'document.readyState', returnByValue: true },
+      sessionId,
+      1000
+    )
+    .then((result) => {
+      const state = result?.result?.value;
+      return state !== 'loading' && state !== 'interactive';
+    })
+    .catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      if (
+        message.startsWith('Runtime.evaluate timed out') ||
+        message.startsWith('Runtime.evaluate:')
+      ) {
+        return true;
+      }
+      throw error;
+    });
+}
+
+function navigateAndWait(client, sessionId, url) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      client.off('Page.loadEventFired', listener);
+      if (error) reject(error);
+      else resolve();
+    };
+    const listener = (message) => {
+      if (typeof message?.sessionId === 'string' && message.sessionId !== sessionId) return;
+      finish();
+    };
+    client.on('Page.loadEventFired', listener);
+    timer = setTimeout(() => finish(), LOAD_TIMEOUT_MS);
+    client.send('Page.navigate', { url }, sessionId).then(
+      (result) => {
+        if (result?.errorText) finish(new Error(`navigate: ${result.errorText}`));
+        else if (!result?.loaderId) finish();
+      },
+      (error) => finish(error)
+    );
+  });
+}
+
+function waitForLoad(client, sessionId) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      client.off('Page.loadEventFired', listener);
+      if (error) reject(error);
+      else resolve();
+    };
+    const listener = (message) => {
+      if (typeof message?.sessionId === 'string' && message.sessionId !== sessionId) return;
+      finish();
+    };
+    client.on('Page.loadEventFired', listener);
+    timer = setTimeout(() => finish(), LOAD_TIMEOUT_MS);
+    pageIsSettled(client, sessionId).then(
+      (ready) => {
+        if (ready) finish();
+      },
+      (error) => finish(error)
+    );
+  });
+}
+
+function unsupported(sink) {
+  const error = new Error(`browser.websocket: ${sink} is only available inside SLICC`);
+  error.code = 'ENOTSUP';
+  return error;
+}
+
+function validateSink(forward) {
+  if (!forward || typeof forward !== 'object' || typeof forward.sink !== 'string') {
+    throw new Error('browser.websocket: forward.sink is required');
+  }
+  switch (forward.sink) {
+    case 'webhook':
+    case 'scoop':
+      throw unsupported(forward.sink);
+    case 'vfs':
+      if (typeof forward.path !== 'string' || !path.isAbsolute(forward.path)) {
+        throw new Error('browser.websocket: vfs sink path must be an absolute path');
+      }
+      return;
+    case 'log':
+      return;
+    default:
+      throw new Error(`browser.websocket: unknown sink "${forward.sink ?? ''}"`);
+  }
+}
+
+async function installRouter(targetId) {
+  if (routers.has(targetId)) return;
+  const { client, sessionId } = await sessionFor(targetId);
+  try {
+    await client.send('Runtime.addBinding', { name: BINDING }, sessionId);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes('already exists')) throw error;
+  }
+  await client.send('Page.addScriptToEvaluateOnNewDocument', { source: routerSource }, sessionId);
+  const installed = await client.send(
+    'Runtime.evaluate',
+    { expression: routerSource, returnByValue: true },
+    sessionId
+  );
+  if (installed?.exceptionDetails) {
+    throw new Error(exceptionMessage(installed.exceptionDetails));
+  }
+  routers.add(targetId);
+}
+
+async function callRouter(targetId, expression) {
+  const { client, sessionId } = await sessionFor(targetId);
+  const result = await client.send(
+    'Runtime.evaluate',
+    { expression, returnByValue: true },
+    sessionId
+  );
+  if (result?.exceptionDetails) {
+    throw new Error(exceptionMessage(result.exceptionDetails));
+  }
+}
+
+function toInfo(sub) {
+  const info = {
+    id: sub.id,
+    targetId: sub.targetId,
+    forward: sub.forward,
+    createdAt: sub.createdAt,
+  };
+  if (sub.urlMatch !== undefined) info.urlMatch = sub.urlMatch;
+  if (sub.filter !== undefined) info.filter = sub.filter;
+  return info;
+}
+
+function makeHandle(sub) {
+  return {
+    ...toInfo(sub),
+    async update(patch = {}) {
+      const wire = {};
+      if (patch.urlMatch !== undefined) {
+        wire.urlMatch =
+          patch.urlMatch === null
+            ? null
+            : patch.urlMatch instanceof RegExp
+              ? patch.urlMatch.source
+              : patch.urlMatch;
+      }
+      if (patch.filter !== undefined) wire.filter = patch.filter;
+      await using(() =>
+        callRouter(
+          sub.targetId,
+          `globalThis.__sliccWsRouter.update(${JSON.stringify(sub.id)}, ${JSON.stringify(wire)})`
+        )
+      );
+      if (wire.urlMatch === null) delete sub.urlMatch;
+      else if (wire.urlMatch !== undefined) sub.urlMatch = wire.urlMatch;
+      if (patch.filter === null) delete sub.filter;
+      else if (patch.filter !== undefined) sub.filter = patch.filter;
+      return toInfo(sub);
+    },
+    async close() {
+      if (!subscribers.has(sub.id)) return false;
+      subscribers.delete(sub.id);
+      await using(() =>
+        callRouter(sub.targetId, `globalThis.__sliccWsRouter.unregister(${JSON.stringify(sub.id)})`)
+      );
+      return true;
+    },
+  };
+}
+
+async function deliver(subId, payload) {
+  const sub = subscribers.get(subId);
+  if (!sub) return;
+  try {
+    if (sub.forward.sink === 'log') {
+      console.log(typeof payload === 'string' ? payload : JSON.stringify(payload));
+      return;
+    }
+    if (sub.forward.sink === 'vfs') {
+      const line = `${typeof payload === 'string' ? payload : JSON.stringify(payload)}\n`;
+      await appendFile(sub.forward.path, line);
+    }
+  } catch {
+    return;
+  }
+}
+
+export const websocket = {
+  on(tab, opts = {}) {
+    const targetId = targetIdOf(tab);
+    const urlMatch = patternOf(opts.urlMatch);
+    let selector;
+    const builder = {
+      filter(next) {
+        if (typeof next === 'function' || typeof next === 'string') {
+          throw new TypeError(
+            'browser.websocket: filter must be a declarative JSON object, not a function or string'
+          );
+        }
+        selector = next;
+        return builder;
+      },
+      async forward(sink) {
+        validateSink(sink);
+        return using(() => subscribe(sink));
+      },
+    };
+    async function subscribe(sink) {
+      await installRouter(targetId);
+      const id = `wssub-${seq++}-${Date.now().toString(36)}`;
+      const sub = {
+        id,
+        targetId,
+        forward: sink,
+        createdAt: new Date().toISOString(),
+      };
+      if (urlMatch !== undefined) sub.urlMatch = urlMatch;
+      if (selector !== undefined) sub.filter = selector;
+      const registered = { id };
+      if (urlMatch !== undefined) registered.urlMatch = urlMatch;
+      if (selector !== undefined) registered.filter = selector;
+      await callRouter(
+        targetId,
+        `globalThis.__sliccWsRouter.register(${JSON.stringify(registered)})`
+      );
+      subscribers.set(id, sub);
+      return makeHandle(sub);
+    }
+    return builder;
+  },
+  async list() {
+    return [...subscribers.values()].map((sub) => toInfo(sub));
+  },
+};
+
+const browser = {
+  findTab,
+  ensureTab,
+  eval: evalSource,
+  evalAsync: evalSourceAsync,
+  cookie,
+  localStorage,
+  fetch,
+  websocket,
+};
+
+export default browser;

package/src/fetch-script.js

@@ -0,0 +1,139 @@
+function bytesToBase64(bytes) {
+  let binary = '';
+  const chunkSize = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binary += String.fromCharCode(...Array.from(bytes.subarray(i, i + chunkSize)));
+  }
+  return btoa(binary);
+}
+
+async function serializeFormData(form) {
+  const entries = [];
+  for (const [name, value] of form.entries()) {
+    if (typeof value === 'string') {
+      entries.push({ name, value });
+      continue;
+    }
+    const bytes = new Uint8Array(await value.arrayBuffer());
+    entries.push({
+      name,
+      file: {
+        data: bytesToBase64(bytes),
+        filename: typeof value.name === 'string' ? value.name : 'blob',
+        type: value.type || '',
+      },
+    });
+  }
+  return { kind: 'formdata', entries };
+}
+
+async function serializeBody(raw, headers) {
+  const hasContentType = () =>
+    Object.keys(headers).some((key) => key.toLowerCase() === 'content-type');
+  if (typeof raw === 'string') return { body: raw };
+  if (raw instanceof URLSearchParams) {
+    if (!hasContentType()) {
+      headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+    }
+    return { body: raw.toString() };
+  }
+  if (raw instanceof Blob) {
+    const bytes = new Uint8Array(await raw.arrayBuffer());
+    return { descriptor: { kind: 'blob', data: bytesToBase64(bytes), type: raw.type || '' } };
+  }
+  if (raw instanceof ArrayBuffer) {
+    return { descriptor: { kind: 'bytes', data: bytesToBase64(new Uint8Array(raw)) } };
+  }
+  if (ArrayBuffer.isView(raw)) {
+    const bytes = new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+    return { descriptor: { kind: 'bytes', data: bytesToBase64(bytes) } };
+  }
+  if (typeof FormData !== 'undefined' && raw instanceof FormData) {
+    return { descriptor: await serializeFormData(raw) };
+  }
+  if (!hasContentType()) headers['Content-Type'] = 'application/json';
+  return { body: JSON.stringify(raw) };
+}
+
+function bodyReconstruction(descriptor) {
+  if (!descriptor) return '';
+  return (
+    'const __b64 = (s) => { const bin = atob(s); const n = bin.length; ' +
+    'const u = new Uint8Array(n); for (let i = 0; i < n; i++) u[i] = bin.charCodeAt(i); return u; };' +
+    `const __body = ${JSON.stringify(descriptor)};` +
+    "if (__body.kind === 'bytes') { __init.body = __b64(__body.data); }" +
+    "else if (__body.kind === 'blob') { __init.body = new Blob([__b64(__body.data)], { type: __body.type }); }" +
+    "else if (__body.kind === 'formdata') { const __fd = new FormData(); " +
+    'for (const e of __body.entries) { ' +
+    'if (e.file) { __fd.append(e.name, new Blob([__b64(e.file.data)], { type: e.file.type }), e.file.filename); } ' +
+    'else { __fd.append(e.name, e.value); } } __init.body = __fd; }'
+  );
+}
+
+function responseHandling(responseType) {
+  return (
+    'const h = {};' +
+    'r.headers.forEach((v, k) => { h[k] = v; });' +
+    "const ct = r.headers.get('content-type') || '';" +
+    `const __rt = ${JSON.stringify(responseType ?? null)};` +
+    'const __ctl = ct.toLowerCase();' +
+    "const __binPrefixes = ['image/','audio/','video/','application/octet-stream'," +
+    "'application/pdf','application/protobuf','application/x-protobuf','application/wasm','application/zip'];" +
+    "const __isXml = __ctl.indexOf('+xml') !== -1 || __ctl.indexOf('application/xml') === 0 || __ctl.indexOf('text/xml') === 0;" +
+    "const __isBinary = __rt === 'binary' || (__rt !== 'text' && __rt !== 'json' && !__isXml && " +
+    '__binPrefixes.some((p) => __ctl.indexOf(p) === 0));' +
+    'const __meta = { ok: r.ok, status: r.status, statusText: r.statusText, ' +
+    'url: r.url, redirected: !!r.redirected, headers: h };' +
+    'if (__isBinary) {' +
+    'const __u = new Uint8Array(await r.arrayBuffer());' +
+    "let __s = ''; const __cs = 0x8000;" +
+    'for (let __i = 0; __i < __u.length; __i += __cs) { ' +
+    '__s += String.fromCharCode.apply(null, __u.subarray(__i, __i + __cs)); }' +
+    "return Object.assign(__meta, { body: btoa(__s), bodyEncoding: 'base64' });" +
+    '}' +
+    'const t = await r.text();' +
+    'let b;' +
+    "const __jsonWanted = __rt === 'json' || (__rt !== 'text' && ct.indexOf('application/json') !== -1);" +
+    'if (__jsonWanted) { if (!t) { b = null; } else { try { b = JSON.parse(t); } catch (e) { b = t; } } }' +
+    'else { b = t; }' +
+    'return Object.assign(__meta, { body: b });'
+  );
+}
+
+export async function buildBrowserFetchScript(url, opts = {}) {
+  const headers = {};
+  for (const [key, value] of Object.entries(opts.headers ?? {})) {
+    if (typeof value === 'string') headers[key] = value;
+  }
+  const method = typeof opts.method === 'string' ? opts.method : 'GET';
+  const credentials =
+    opts.credentials === 'same-origin' || opts.credentials === 'omit'
+      ? opts.credentials
+      : 'include';
+  const raw = opts.body;
+  const { body, descriptor } =
+    raw === undefined || raw === null ? {} : await serializeBody(raw, headers);
+  const init = { method, credentials, headers };
+  if (body !== undefined) init.body = body;
+  if (opts.mode !== undefined) init.mode = opts.mode;
+  if (opts.cache !== undefined) init.cache = opts.cache;
+  if (opts.redirect !== undefined) init.redirect = opts.redirect;
+  if (opts.referrer !== undefined) init.referrer = opts.referrer;
+  if (opts.referrerPolicy !== undefined) init.referrerPolicy = opts.referrerPolicy;
+  if (opts.integrity !== undefined) init.integrity = opts.integrity;
+  if (opts.keepalive !== undefined) init.keepalive = opts.keepalive;
+  const timeoutMs =
+    typeof opts.timeoutMs === 'number' && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+      ? Math.round(opts.timeoutMs)
+      : 0;
+  const timeoutScript = timeoutMs > 0 ? `__init.signal = AbortSignal.timeout(${timeoutMs});` : '';
+  return (
+    '(async () => {' +
+    `const __init = ${JSON.stringify(init)};` +
+    timeoutScript +
+    bodyReconstruction(descriptor) +
+    `const r = await fetch(${JSON.stringify(url)}, __init);` +
+    responseHandling(opts.responseType) +
+    '})()'
+  );
+}

package/src/ws-router.js

@@ -0,0 +1,149 @@
+export function installWsRouter(win) {
+  const w = win;
+  if (w.__sliccWsRouter) return;
+
+  const subs = new Map();
+
+  function compileUrlMatch(pattern) {
+    if (pattern === undefined) return undefined;
+    try {
+      return new RegExp(pattern);
+    } catch {
+      return null;
+    }
+  }
+
+  function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+
+  function subsetMatch(value, template) {
+    for (const key of Object.keys(template)) {
+      const expected = template[key];
+      const actual = value[key];
+      if (isPlainObject(expected)) {
+        if (!isPlainObject(actual)) return false;
+        if (!subsetMatch(actual, expected)) return false;
+        continue;
+      }
+      if (!Object.is(actual, expected)) return false;
+    }
+    return true;
+  }
+
+  function parseFrame(raw, parseAs) {
+    if (parseAs === 'text') return raw;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+  }
+
+  function project(body, fields) {
+    if (!fields || fields.length === 0) return body;
+    if (!isPlainObject(body)) return body;
+    const out = {};
+    for (const field of fields) if (field in body) out[field] = body[field];
+    return out;
+  }
+
+  function report(subId, payload) {
+    const reporter = w.__sliccWsRouterReport;
+    if (typeof reporter !== 'function') return;
+    try {
+      reporter(JSON.stringify({ subId, payload }));
+    } catch {
+      return;
+    }
+  }
+
+  function urlMatches(sub, url) {
+    if (sub.urlMatch === undefined) return true;
+    const re = sub._urlMatchRe;
+    if (re === null) return false;
+    return !re || re.test(url);
+  }
+
+  function whereMatches(sub, body) {
+    const where = sub.filter?.where;
+    if (!where || Object.keys(where).length === 0) return true;
+    if (!isPlainObject(body)) return false;
+    return subsetMatch(body, where);
+  }
+
+  function dispatchFrame(url, raw) {
+    if (subs.size === 0) return;
+    for (const sub of subs.values()) {
+      if (!urlMatches(sub, url)) continue;
+      const body = parseFrame(raw, sub.filter?.parseAs);
+      if (body === undefined) continue;
+      if (!whereMatches(sub, body)) continue;
+      report(sub.id, project(body, sub.filter?.project));
+    }
+  }
+
+  const seen = new WeakSet();
+  function wrapInstance(ws) {
+    if (seen.has(ws)) return;
+    seen.add(ws);
+    ws.addEventListener('message', (ev) => {
+      if (typeof ev.data !== 'string') return;
+      try {
+        dispatchFrame(ws.url, ev.data);
+      } catch {
+        return;
+      }
+    });
+  }
+
+  const WS = w.WebSocket;
+  if (!WS) return;
+  const origSend = WS.prototype.send;
+  WS.prototype.send = function patchedSend(data) {
+    wrapInstance(this);
+    return origSend.call(this, data);
+  };
+
+  function applyUrlMatchPatch(next, patch) {
+    if (!Object.prototype.hasOwnProperty.call(patch, 'urlMatch')) return;
+    if (patch.urlMatch === null) {
+      delete next.urlMatch;
+      next._urlMatchRe = undefined;
+      return;
+    }
+    if (typeof patch.urlMatch === 'string') {
+      next.urlMatch = patch.urlMatch;
+      next._urlMatchRe = compileUrlMatch(patch.urlMatch);
+    }
+  }
+
+  function applyFilterPatch(next, patch) {
+    if (!Object.prototype.hasOwnProperty.call(patch, 'filter')) return;
+    if (patch.filter === null) {
+      delete next.filter;
+      return;
+    }
+    if (patch.filter !== undefined) next.filter = patch.filter;
+  }
+
+  const router = {
+    register(sub) {
+      subs.set(sub.id, { ...sub, _urlMatchRe: compileUrlMatch(sub.urlMatch) });
+    },
+    update(id, patch) {
+      const cur = subs.get(id);
+      if (!cur) return;
+      const next = { ...cur, id };
+      applyUrlMatchPatch(next, patch);
+      applyFilterPatch(next, patch);
+      subs.set(id, next);
+    },
+    unregister(id) {
+      subs.delete(id);
+    },
+  };
+  Object.defineProperty(w, '__sliccWsRouter', { value: router, configurable: false });
+}
+
+export const routerSource = `(${installWsRouter.toString()})(globalThis);`;

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.