@yodaos-pkg/ink 0.1.0 → 0.3.0

package/README.md

@@ -36,8 +36,7 @@ Before integrating the SDK, make sure you have one of these two inputs:
    - This is a good fit when assets live on the server and the browser fetches
      them on demand.
 
-If you use the VFS flow, the server side usually works together with
-`@yodaos-pkg/ink-vfs-server`.
+If you use the VFS flow, provide your own HTTP VFS endpoint on the server side.
 
 ## Installation
 
@@ -47,10 +46,11 @@ If you use the VFS flow, the server side usually works together with
 npm install @yodaos-pkg/ink
 ```
 
-If you also want to use the VFS flow, install the server package as well:
+If you also want to use the VFS flow, prepare an HTTP endpoint that exposes:
 
-```bash
-npm install @yodaos-pkg/ink-vfs-server
+```text
+GET /apps/:appId/manifest
+GET /apps/:appId/files/:path
 ```
 
 ## Core API
@@ -94,6 +94,54 @@ Creates an `InkView` instance and initializes the wasm runtime internally.
   - Resolves to an `InkView` instance that can then call
     `bindDomEvents()`, `openBundle()`, and `openFromVfs()`
 
+### `configureNetwork(options)`
+
+Configures host-controlled request interception for Ink network traffic.
+
+**Parameters**
+
+- `options.interceptor`
+  - Optional
+  - A function that receives the outgoing request and returns an action
+- `options.proxyUrl`
+  - Optional
+  - A convenience option for rewriting requests through a proxy endpoint
+- `options.targetSearchParam`
+  - Optional
+  - The query parameter name used when `proxyUrl` is provided
+- `options.clear`
+  - Optional
+  - Clears the previously registered interceptor
+
+**What it does**
+
+- Registers a global Ink request interceptor
+- Lets hosts continue, rewrite, or block outgoing requests
+- Mirrors the shape of a WebView-style request interception hook
+
+**Returns**
+
+- `void`
+
+### `createProxyUrlResolver(options)`
+
+Creates a request interceptor that rewrites outgoing requests to a host-managed
+proxy endpoint such as `'/__proxy?url=...'`.
+
+**Parameters**
+
+- `options.proxyUrl`
+  - Required
+  - The proxy endpoint to call
+- `options.targetSearchParam`
+  - Optional
+  - The query parameter name that receives the original target URL
+
+**Returns**
+
+- `InkRequestInterceptor`
+  - A reusable interceptor for `configureNetwork()` or `initInk()`
+
 ### `view.bindDomEvents(options?)`
 
 Binds common DOM events to the current `InkView`.
@@ -191,6 +239,9 @@ Fetches an Ink bundle from a remote HTTP VFS service and opens it.
 - `options.headers?: HeadersInit`
   - Optional
   - Extra request headers
+- `options.requestInterceptor?: InkRequestInterceptor`
+  - Optional
+  - Overrides the global interceptor for this VFS load only
 - `options.initialPage?: string | null`
   - Optional
   - Sets the first page to open
@@ -203,6 +254,7 @@ Fetches an Ink bundle from a remote HTTP VFS service and opens it.
 - Fetches the VFS manifest first
 - Fetches each file listed in the manifest
 - Reconstructs the bundle in the browser
+- Applies the request interceptor when one is configured
 - Calls `openBundle()` automatically
 
 **Returns**
@@ -213,6 +265,30 @@ Fetches an Ink bundle from a remote HTTP VFS service and opens it.
   - `manifest: VfsManifest`
   - `files: Map<string, Uint8Array>`
 
+### `initInk(options)`
+
+Initializes the wasm runtime and optionally installs a host networking policy.
+
+**Parameters**
+
+- `options.wasmUrl?: string | URL | Request`
+  - Optional
+  - Custom URL for the wasm binary
+- `options.moduleOrPath?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module`
+  - Optional
+  - Custom wasm module input supported by `wasm-bindgen`
+- `options.requestInterceptor?: InkRequestInterceptor`
+  - Optional
+  - Installs a host request interceptor before Ink networking starts
+- `options.proxyUrl?: string`
+  - Optional
+  - Shorthand for a proxy-based interceptor
+
+**Returns**
+
+- `Promise<{ InkWebView, getInkVersion }>`
+  - Resolves to the wasm bindings
+
 ### `view.startRendering()`
 
 Starts the continuous render loop.

package/dist/README.md

@@ -36,8 +36,7 @@ Before integrating the SDK, make sure you have one of these two inputs:
    - This is a good fit when assets live on the server and the browser fetches
      them on demand.
 
-If you use the VFS flow, the server side usually works together with
-`@yodaos-pkg/ink-vfs-server`.
+If you use the VFS flow, provide your own HTTP VFS endpoint on the server side.
 
 ## Installation
 
@@ -47,10 +46,11 @@ If you use the VFS flow, the server side usually works together with
 npm install @yodaos-pkg/ink
 ```
 
-If you also want to use the VFS flow, install the server package as well:
+If you also want to use the VFS flow, prepare an HTTP endpoint that exposes:
 
-```bash
-npm install @yodaos-pkg/ink-vfs-server
+```text
+GET /apps/:appId/manifest
+GET /apps/:appId/files/:path
 ```
 
 ## Core API
@@ -94,6 +94,54 @@ Creates an `InkView` instance and initializes the wasm runtime internally.
   - Resolves to an `InkView` instance that can then call
     `bindDomEvents()`, `openBundle()`, and `openFromVfs()`
 
+### `configureNetwork(options)`
+
+Configures host-controlled request interception for Ink network traffic.
+
+**Parameters**
+
+- `options.interceptor`
+  - Optional
+  - A function that receives the outgoing request and returns an action
+- `options.proxyUrl`
+  - Optional
+  - A convenience option for rewriting requests through a proxy endpoint
+- `options.targetSearchParam`
+  - Optional
+  - The query parameter name used when `proxyUrl` is provided
+- `options.clear`
+  - Optional
+  - Clears the previously registered interceptor
+
+**What it does**
+
+- Registers a global Ink request interceptor
+- Lets hosts continue, rewrite, or block outgoing requests
+- Mirrors the shape of a WebView-style request interception hook
+
+**Returns**
+
+- `void`
+
+### `createProxyUrlResolver(options)`
+
+Creates a request interceptor that rewrites outgoing requests to a host-managed
+proxy endpoint such as `'/__proxy?url=...'`.
+
+**Parameters**
+
+- `options.proxyUrl`
+  - Required
+  - The proxy endpoint to call
+- `options.targetSearchParam`
+  - Optional
+  - The query parameter name that receives the original target URL
+
+**Returns**
+
+- `InkRequestInterceptor`
+  - A reusable interceptor for `configureNetwork()` or `initInk()`
+
 ### `view.bindDomEvents(options?)`
 
 Binds common DOM events to the current `InkView`.
@@ -191,6 +239,9 @@ Fetches an Ink bundle from a remote HTTP VFS service and opens it.
 - `options.headers?: HeadersInit`
   - Optional
   - Extra request headers
+- `options.requestInterceptor?: InkRequestInterceptor`
+  - Optional
+  - Overrides the global interceptor for this VFS load only
 - `options.initialPage?: string | null`
   - Optional
   - Sets the first page to open
@@ -203,6 +254,7 @@ Fetches an Ink bundle from a remote HTTP VFS service and opens it.
 - Fetches the VFS manifest first
 - Fetches each file listed in the manifest
 - Reconstructs the bundle in the browser
+- Applies the request interceptor when one is configured
 - Calls `openBundle()` automatically
 
 **Returns**
@@ -213,6 +265,30 @@ Fetches an Ink bundle from a remote HTTP VFS service and opens it.
   - `manifest: VfsManifest`
   - `files: Map<string, Uint8Array>`
 
+### `initInk(options)`
+
+Initializes the wasm runtime and optionally installs a host networking policy.
+
+**Parameters**
+
+- `options.wasmUrl?: string | URL | Request`
+  - Optional
+  - Custom URL for the wasm binary
+- `options.moduleOrPath?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module`
+  - Optional
+  - Custom wasm module input supported by `wasm-bindgen`
+- `options.requestInterceptor?: InkRequestInterceptor`
+  - Optional
+  - Installs a host request interceptor before Ink networking starts
+- `options.proxyUrl?: string`
+  - Optional
+  - Shorthand for a proxy-based interceptor
+
+**Returns**
+
+- `Promise<{ InkWebView, getInkVersion }>`
+  - Resolves to the wasm bindings
+
 ### `view.startRendering()`
 
 Starts the continuous render loop.

package/dist/env.js

@@ -2,11 +2,190 @@ let wasmExports = null;
 const allocationSizes = new Map();
 const textDecoder = new TextDecoder('utf-8', { fatal: false });
 const textEncoder = new TextEncoder();
+let inkRequestInterceptor = null;
+const hrtimeOriginNs =
+  typeof performance !== 'undefined' && typeof performance.now === 'function'
+    ? BigInt(Math.floor(performance.now() * 1_000_000))
+    : 0n;
+
+export function rquickjs_browser_date_now_us() {
+  return BigInt(Date.now()) * 1000n;
+}
+
+export function rquickjs_browser_hrtime_ns() {
+  if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+    return BigInt(Math.floor(performance.now() * 1_000_000)) - hrtimeOriginNs;
+  }
+  return BigInt(Date.now()) * 1_000_000n;
+}
 
 export function __setWasmInstance(exports) {
   wasmExports = exports;
 }
 
+function ensureFetchImplementation(fetchImpl) {
+  const resolved = fetchImpl || globalThis.fetch;
+  if (typeof resolved !== 'function') {
+    throw new Error('A fetch implementation is required for Ink networking.');
+  }
+  return resolved;
+}
+
+function headersToObject(headersLike) {
+  if (!headersLike) {
+    return {};
+  }
+  if (typeof Headers !== 'undefined' && headersLike instanceof Headers) {
+    const result = {};
+    for (const [name, value] of headersLike.entries()) {
+      result[name] = value;
+    }
+    return result;
+  }
+  if (Array.isArray(headersLike)) {
+    const result = {};
+    for (const entry of headersLike) {
+      if (!Array.isArray(entry) || entry.length < 2) {
+        continue;
+      }
+      result[String(entry[0])] = String(entry[1]);
+    }
+    return result;
+  }
+  if (headersLike && typeof headersLike === 'object') {
+    return Object.fromEntries(
+      Object.entries(headersLike).map(([name, value]) => [
+        name,
+        Array.isArray(value) ? value.join(', ') : String(value),
+      ]),
+    );
+  }
+  return {};
+}
+
+function cloneBody(body) {
+  if (body == null) {
+    return null;
+  }
+  if (typeof body === 'string') {
+    return body;
+  }
+  if (body instanceof Uint8Array) {
+    return new Uint8Array(body);
+  }
+  if (ArrayBuffer.isView(body)) {
+    return new Uint8Array(body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength));
+  }
+  if (body instanceof ArrayBuffer) {
+    return body.slice(0);
+  }
+  return body;
+}
+
+function normalizeRequest(input, init = {}, metadata = {}) {
+  const url = typeof input === 'string' ? input : String(input);
+  return {
+    url,
+    method: String(init.method || 'GET').toUpperCase(),
+    headers: headersToObject(init.headers),
+    body: cloneBody(init.body),
+    metadata: metadata && typeof metadata === 'object' ? { ...metadata } : {},
+  };
+}
+
+function normalizeInterceptorResult(request, result) {
+  if (result == null || result === false) {
+    return {
+      url: request.url,
+      init: {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+      },
+    };
+  }
+
+  if (typeof result !== 'object') {
+    throw new TypeError('Ink request interceptor must return an object, null, or undefined.');
+  }
+
+  const action = result.action || 'rewrite';
+  if (action === 'continue') {
+    return {
+      url: request.url,
+      init: {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+      },
+    };
+  }
+
+  if (action === 'block') {
+    throw new Error(result.reason || `Ink request blocked: ${request.url}`);
+  }
+
+  if (action !== 'rewrite') {
+    throw new Error(`Unsupported Ink request interceptor action: ${action}`);
+  }
+
+  return {
+    url: typeof result.url === 'string' && result.url ? result.url : request.url,
+    init: {
+      method: typeof result.method === 'string' && result.method ? result.method : request.method,
+      headers: result.headers ? headersToObject(result.headers) : request.headers,
+      body: Object.prototype.hasOwnProperty.call(result, 'body') ? result.body : request.body,
+    },
+  };
+}
+
+async function resolveInkFetchRequest(input, init = {}, metadata = {}, interceptorOverride = null) {
+  const request = normalizeRequest(input, init, metadata);
+  const interceptor = interceptorOverride || inkRequestInterceptor;
+  if (!interceptor) {
+    return {
+      url: request.url,
+      init: {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+      },
+    };
+  }
+  const result = await interceptor(request);
+  return normalizeInterceptorResult(request, result);
+}
+
+export function setInkRequestInterceptor(interceptor) {
+  if (interceptor != null && typeof interceptor !== 'function') {
+    throw new TypeError('Ink request interceptor must be a function, null, or undefined.');
+  }
+  inkRequestInterceptor = interceptor || null;
+}
+
+export function clearInkRequestInterceptor() {
+  inkRequestInterceptor = null;
+}
+
+export async function __inkFetch(input, init, metadata) {
+  const resolved = await resolveInkFetchRequest(input, init, metadata);
+  const fetchImpl = ensureFetchImplementation();
+  return fetchImpl(resolved.url, resolved.init);
+}
+
+export async function fetchWithInkRequestInterceptor(input, init = {}, options = {}) {
+  const resolved = await resolveInkFetchRequest(
+    input,
+    init,
+    options.metadata,
+    options.interceptor || null,
+  );
+  const fetchImpl = ensureFetchImplementation(options.fetch);
+  return fetchImpl(resolved.url, resolved.init);
+}
+
+globalThis.__inkFetch = __inkFetch;
+
 function requireWasm() {
   if (!wasmExports) {
     throw new Error('Wasm exports are not initialized');
@@ -73,8 +252,243 @@ function consoleWrite(prefix, text) {
   console.log(value);
 }
 
-function formatPrintf(fmtPtr) {
-  return readCString(fmtPtr);
+function readCStringWithLength(ptr, maxBytes) {
+  ptr >>>= 0;
+  const bytes = memoryBytes();
+  let end = ptr;
+  const maxEnd = Math.min(bytes.length, ptr + Math.max(0, maxBytes | 0));
+  while (end < maxEnd && bytes[end] !== 0) {
+    end += 1;
+  }
+  return textDecoder.decode(bytes.subarray(ptr, end));
+}
+
+function normalizePrintfValue(value) {
+  if (typeof value === 'bigint') {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : 0;
+  }
+  if (value == null) {
+    return 0;
+  }
+  return Number(value) || 0;
+}
+
+function createDirectArgumentReader(values, offset) {
+  let index = offset;
+  return {
+    next() {
+      const value = index < values.length ? values[index] : 0;
+      index += 1;
+      return value;
+    },
+    nextInt32() {
+      return Number(normalizePrintfValue(this.next())) | 0;
+    },
+    nextUint32() {
+      return Number(normalizePrintfValue(this.next())) >>> 0;
+    },
+    nextPointer() {
+      return Number(normalizePrintfValue(this.next())) >>> 0;
+    },
+    nextFloat64() {
+      return Number(normalizePrintfValue(this.next()));
+    },
+  };
+}
+
+function createVaListReader(argsPtr) {
+  let cursor = argsPtr >>> 0;
+  const view = memoryView();
+  const nextSlot = () => {
+    const slot = cursor;
+    cursor = (cursor + 8) >>> 0;
+    return slot;
+  };
+  return {
+    nextInt32() {
+      return view.getInt32(nextSlot(), true);
+    },
+    nextUint32() {
+      return view.getUint32(nextSlot(), true);
+    },
+    nextPointer() {
+      return view.getUint32(nextSlot(), true);
+    },
+    nextFloat64() {
+      return view.getFloat64(nextSlot(), true);
+    },
+  };
+}
+
+function formatInteger(value, {
+  signed = true,
+  base = 10,
+  width = 0,
+  padZero = false,
+  uppercase = false,
+} = {}) {
+  let normalized = normalizePrintfValue(value);
+  let negative = false;
+  let digits = '';
+
+  if (typeof normalized === 'bigint') {
+    if (signed && normalized < 0n) {
+      negative = true;
+      normalized = -normalized;
+    } else if (!signed) {
+      normalized = BigInt.asUintN(64, normalized);
+    }
+    digits = normalized.toString(base);
+  } else {
+    let numberValue = Math.trunc(Number(normalized) || 0);
+    if (signed) {
+      negative = numberValue < 0;
+      numberValue = Math.abs(numberValue);
+      digits = numberValue.toString(base);
+    } else {
+      digits = (numberValue >>> 0).toString(base);
+    }
+  }
+
+  if (uppercase) {
+    digits = digits.toUpperCase();
+  }
+
+  const prefix = negative ? '-' : '';
+  const paddedDigits = padZero && width > prefix.length + digits.length
+    ? digits.padStart(width - prefix.length, '0')
+    : digits;
+  const result = `${prefix}${paddedDigits}`;
+  return !padZero && width > result.length
+    ? result.padStart(width, ' ')
+    : result;
+}
+
+function formatStringValue(value, precision) {
+  if (typeof value === 'string') {
+    return precision == null ? value : value.slice(0, precision);
+  }
+  const ptr = Number(normalizePrintfValue(value)) >>> 0;
+  if (ptr === 0) {
+    return '(null)';
+  }
+  if (precision == null) {
+    return readCString(ptr);
+  }
+  return readCStringWithLength(ptr, precision);
+}
+
+function formatPrintf(fmtPtr, reader = null) {
+  const fmt = readCString(fmtPtr);
+  if (!reader) {
+    return fmt;
+  }
+
+  let result = '';
+  for (let i = 0; i < fmt.length; i += 1) {
+    const ch = fmt[i];
+    if (ch !== '%') {
+      result += ch;
+      continue;
+    }
+
+    const next = fmt[i + 1];
+    if (next === '%') {
+      result += '%';
+      i += 1;
+      continue;
+    }
+
+    let cursor = i + 1;
+    let padZero = false;
+    if (fmt[cursor] === '0') {
+      padZero = true;
+      cursor += 1;
+    }
+
+    let widthText = '';
+    while (cursor < fmt.length && /[0-9]/.test(fmt[cursor])) {
+      widthText += fmt[cursor];
+      cursor += 1;
+    }
+    const width = widthText ? Number.parseInt(widthText, 10) : 0;
+
+    let precision = null;
+    if (fmt[cursor] === '.') {
+      cursor += 1;
+      if (fmt[cursor] === '*') {
+        precision = Math.max(0, reader.nextInt32());
+        cursor += 1;
+      } else {
+        let precisionText = '';
+        while (cursor < fmt.length && /[0-9]/.test(fmt[cursor])) {
+          precisionText += fmt[cursor];
+          cursor += 1;
+        }
+        precision = precisionText ? Number.parseInt(precisionText, 10) : 0;
+      }
+    }
+
+    while (cursor < fmt.length && /[hljztL]/.test(fmt[cursor])) {
+      cursor += 1;
+    }
+
+    const specifier = fmt[cursor];
+    if (!specifier) {
+      result += '%';
+      break;
+    }
+
+    switch (specifier) {
+      case 's':
+        result += formatStringValue(reader.nextPointer(), precision);
+        break;
+      case 'c':
+        result += String.fromCodePoint(reader.nextInt32() >>> 0);
+        break;
+      case 'd':
+      case 'i':
+        result += formatInteger(reader.nextInt32(), {
+          signed: true,
+          base: 10,
+          width,
+          padZero,
+        });
+        break;
+      case 'u':
+        result += formatInteger(reader.nextUint32(), {
+          signed: false,
+          base: 10,
+          width,
+          padZero,
+        });
+        break;
+      case 'x':
+      case 'X':
+        result += formatInteger(reader.nextUint32(), {
+          signed: false,
+          base: 16,
+          width,
+          padZero,
+          uppercase: specifier === 'X',
+        });
+        break;
+      case 'f':
+      case 'g':
+        result += String(reader.nextFloat64());
+        break;
+      default:
+        result += `%${fmt.slice(i + 1, cursor + 1)}`;
+        break;
+    }
+
+    i = cursor;
+  }
+
+  return result;
 }
 
 function parseNumberPrefix(text) {
@@ -106,8 +520,8 @@ export function __assert_fail(assertionPtr, filePtr, line, functionPtr) {
   throw new Error(`assertion failed: ${assertion} at ${file}:${line} in ${func}`);
 }
 
-export function printf(fmtPtr, _argsPtr) {
-  const message = formatPrintf(fmtPtr);
+export function printf(fmtPtr) {
+  const message = formatPrintf(fmtPtr, createDirectArgumentReader(arguments, 1));
   consoleWrite('', message);
   return message.length | 0;
 }
@@ -128,8 +542,8 @@ export function putchar(ch) {
   return ch | 0;
 }
 
-export function fprintf(_stream, fmtPtr, _argsPtr) {
-  const message = formatPrintf(fmtPtr);
+export function fprintf(_stream, fmtPtr) {
+  const message = formatPrintf(fmtPtr, createDirectArgumentReader(arguments, 2));
   consoleWrite('', message);
   return message.length | 0;
 }
@@ -145,12 +559,12 @@ export function fputc(ch, _stream) {
   return putchar(ch);
 }
 
-export function vsnprintf(dst, size, fmtPtr, _argsPtr) {
-  return writeCString(dst, size, formatPrintf(fmtPtr)) | 0;
+export function vsnprintf(dst, size, fmtPtr, argsPtr) {
+  return writeCString(dst, size, formatPrintf(fmtPtr, createVaListReader(argsPtr))) | 0;
 }
 
-export function snprintf(dst, size, fmtPtr, _arg3) {
-  return writeCString(dst, size, formatPrintf(fmtPtr)) | 0;
+export function snprintf(dst, size, fmtPtr) {
+  return writeCString(dst, size, formatPrintf(fmtPtr, createDirectArgumentReader(arguments, 3))) | 0;
 }
 
 export function scalbn(x, n) {

package/dist/index.d.ts

@@ -1,8 +1,4 @@
-export type BundleFileInput =
-  | string
-  | Uint8Array
-  | ArrayBuffer
-  | ArrayBufferView;
+export type BundleFileInput = string | Uint8Array | ArrayBuffer | ArrayBufferView;
 
 export type BundleFiles =
   | Map<string, BundleFileInput>
@@ -12,6 +8,9 @@ export type BundleFiles =
 export interface InitInkOptions {
   wasmUrl?: string | URL | Request;
   moduleOrPath?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+  proxyUrl?: string;
+  targetSearchParam?: string;
+  requestInterceptor?: InkRequestInterceptor;
 }
 
 export interface CreateInkViewOptions {
@@ -35,6 +34,7 @@ export interface LoadBundleFromVfsOptions {
   fetch?: typeof globalThis.fetch;
   signal?: AbortSignal;
   headers?: HeadersInit;
+  requestInterceptor?: InkRequestInterceptor;
 }
 
 export interface OpenFromVfsOptions extends LoadBundleFromVfsOptions {
@@ -42,6 +42,39 @@ export interface OpenFromVfsOptions extends LoadBundleFromVfsOptions {
   query?: string | Record<string, unknown> | null;
 }
 
+export interface InkInterceptedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: BodyInit | ArrayBuffer | ArrayBufferView | Uint8Array | null;
+  metadata: Record<string, unknown>;
+}
+
+export type InkInterceptedRequestAction =
+  | { action?: 'continue' }
+  | {
+      action: 'rewrite';
+      url?: string;
+      method?: string;
+      headers?: HeadersInit | Record<string, string>;
+      body?: BodyInit | ArrayBuffer | ArrayBufferView | Uint8Array | null;
+    }
+  | {
+      action: 'block';
+      reason?: string;
+    };
+
+export type InkRequestInterceptor = (
+  request: InkInterceptedRequest,
+) => InkInterceptedRequestAction | Promise<InkInterceptedRequestAction>;
+
+export interface ConfigureNetworkOptions {
+  proxyUrl?: string;
+  targetSearchParam?: string;
+  interceptor?: InkRequestInterceptor;
+  clear?: boolean;
+}
+
 export interface VfsManifestEntry {
   path: string;
   size?: number;
@@ -76,17 +109,31 @@ export declare function getInkVersion(): string;
 
 export declare function normalizeBundleFiles(files: BundleFiles): Map<string, Uint8Array>;
 
-export declare function serializeQuery(query: string | Record<string, unknown> | null | undefined): string | null;
+export declare function serializeQuery(
+  query: string | Record<string, unknown> | null | undefined,
+): string | null;
 
-export declare function createVfsUrls(input: {
-  baseUrl: string;
-  appId: string;
-}): {
+export declare function createProxyUrlResolver(options: {
+  proxyUrl: string;
+  targetSearchParam?: string;
+}): InkRequestInterceptor;
+
+export declare function setInkRequestInterceptor(
+  interceptor: InkRequestInterceptor | null | undefined,
+): void;
+
+export declare function clearInkRequestInterceptor(): void;
+
+export declare function configureNetwork(options?: ConfigureNetworkOptions): void;
+
+export declare function createVfsUrls(input: { baseUrl: string; appId: string }): {
   manifestUrl: string;
   fileUrl(filePath: string): string;
 };
 
-export declare function loadBundleFromVfs(options: LoadBundleFromVfsOptions): Promise<LoadedVfsBundle>;
+export declare function loadBundleFromVfs(
+  options: LoadBundleFromVfsOptions,
+): Promise<LoadedVfsBundle>;
 
 export declare class InkView {
   static create(options: CreateInkViewOptions): Promise<InkView>;
@@ -112,4 +159,8 @@ export declare function createFrameworkBindings(): {
   ensureLeadingSlash(path: string): string;
   initInk: typeof initInk;
   createInkView: typeof createInkView;
+  configureNetwork: typeof configureNetwork;
+  setInkRequestInterceptor: typeof setInkRequestInterceptor;
+  clearInkRequestInterceptor: typeof clearInkRequestInterceptor;
+  createProxyUrlResolver: typeof createProxyUrlResolver;
 };

package/dist/index.js

@@ -2,6 +2,11 @@ import initInkWasm, {
   InkWebView as RawInkWebView,
   get_version as getInkVersionFromWasm,
 } from './pkg/ink_web.js';
+import {
+  clearInkRequestInterceptor as clearInkRequestInterceptorBridge,
+  fetchWithInkRequestInterceptor,
+  setInkRequestInterceptor as setInkRequestInterceptorBridge,
+} from './env.js';
 
 let bindingsPromise;
 
@@ -40,7 +45,9 @@ function cloneUint8Array(value) {
     return new Uint8Array(value);
   }
   if (ArrayBuffer.isView(value)) {
-    return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+    return new Uint8Array(
+      value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength),
+    );
   }
   if (value instanceof ArrayBuffer) {
     return new Uint8Array(value.slice(0));
@@ -97,6 +104,51 @@ export function serializeQuery(query) {
   return JSON.stringify(query);
 }
 
+export function createProxyUrlResolver({ proxyUrl, targetSearchParam = 'url' }) {
+  if (typeof proxyUrl !== 'string' || !proxyUrl.trim()) {
+    throw new Error('`proxyUrl` must be a non-empty string.');
+  }
+  if (typeof targetSearchParam !== 'string' || !targetSearchParam.trim()) {
+    throw new Error('`targetSearchParam` must be a non-empty string.');
+  }
+
+  const normalizedProxyUrl = proxyUrl.trim();
+  const normalizedTargetSearchParam = targetSearchParam.trim();
+  return (request) => {
+    const target = new URL(normalizedProxyUrl, globalThis.location?.href || 'http://localhost');
+    target.searchParams.set(normalizedTargetSearchParam, request.url);
+    return {
+      action: 'rewrite',
+      url: target.toString(),
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+    };
+  };
+}
+
+export function setInkRequestInterceptor(interceptor) {
+  setInkRequestInterceptorBridge(interceptor);
+}
+
+export function clearInkRequestInterceptor() {
+  clearInkRequestInterceptorBridge();
+}
+
+export function configureNetwork(options = {}) {
+  if (options.interceptor) {
+    setInkRequestInterceptor(options.interceptor);
+    return;
+  }
+  if (options.proxyUrl) {
+    setInkRequestInterceptor(createProxyUrlResolver(options));
+    return;
+  }
+  if (options.clear) {
+    clearInkRequestInterceptor();
+  }
+}
+
 async function buildHttpError(response, bodyReader = (res) => res.text()) {
   let details = response.statusText;
   try {
@@ -137,11 +189,21 @@ export async function loadBundleFromVfs({
   fetch: fetchImpl,
   signal,
   headers,
+  requestInterceptor,
 }) {
   const resolvedFetch = ensureFetch(fetchImpl);
+  const wrappedFetch = async (url, init) =>
+    fetchWithInkRequestInterceptor(url, init, {
+      fetch: resolvedFetch,
+      interceptor: requestInterceptor || null,
+      metadata: {
+        kind: 'vfs',
+        appId,
+      },
+    });
   const { manifestUrl, fileUrl } = createVfsUrls({ baseUrl, appId });
 
-  const manifestResponse = await resolvedFetch(manifestUrl, {
+  const manifestResponse = await wrappedFetch(manifestUrl, {
     method: 'GET',
     headers,
     signal,
@@ -162,7 +224,7 @@ export async function loadBundleFromVfs({
         throw new Error('Each VFS manifest entry must include a non-empty `path`.');
       }
 
-      const response = await resolvedFetch(fileUrl(entry.path), {
+      const response = await wrappedFetch(fileUrl(entry.path), {
         method: 'GET',
         headers,
         signal,
@@ -217,8 +279,15 @@ function ensureAnimationFrameApi() {
 }
 
 export async function initInk(options = {}) {
+  if (options.requestInterceptor) {
+    setInkRequestInterceptor(options.requestInterceptor);
+  } else if (options.proxyUrl) {
+    setInkRequestInterceptor(createProxyUrlResolver(options));
+  }
+
   if (!bindingsPromise) {
-    const initInput = options.wasmUrl || options.moduleOrPath || new URL('./pkg/ink_web_bg.wasm', import.meta.url);
+    const initInput =
+      options.wasmUrl || options.moduleOrPath || new URL('./pkg/ink_web_bg.wasm', import.meta.url);
     bindingsPromise = initInkWasm(initInput).then(() => ({
       InkWebView: RawInkWebView,
       getInkVersion: getInkVersionFromWasm,
@@ -243,7 +312,11 @@ export class InkView {
     }
 
     const bindings = await initInk(config.wasm);
-    const rawView = new bindings.InkWebView(width, height, Number(config.scaleFactor || getDefaultScaleFactor()));
+    const rawView = new bindings.InkWebView(
+      width,
+      height,
+      Number(config.scaleFactor || getDefaultScaleFactor()),
+    );
     const view = new InkView(rawView, config);
 
     if (config.canvas) {
@@ -310,22 +383,54 @@ export class InkView {
       if (focusTarget && typeof focusTarget.focus === 'function') {
         focusTarget.focus();
       }
-      this.#rawView.dispatchPointer('pointerdown', x, y, event.pointerId || 0, event.button || 0, 0, 0);
+      this.#rawView.dispatchPointer(
+        'pointerdown',
+        x,
+        y,
+        event.pointerId || 0,
+        event.button || 0,
+        0,
+        0,
+      );
       this.requestRender();
     });
     addListener(canvas, 'pointermove', (event) => {
       const { x, y } = getPointerPosition(canvas, event);
-      this.#rawView.dispatchPointer('pointermove', x, y, event.pointerId || 0, event.button || 0, 0, 0);
+      this.#rawView.dispatchPointer(
+        'pointermove',
+        x,
+        y,
+        event.pointerId || 0,
+        event.button || 0,
+        0,
+        0,
+      );
       this.requestRender();
     });
     addListener(canvas, 'pointerup', (event) => {
       const { x, y } = getPointerPosition(canvas, event);
-      this.#rawView.dispatchPointer('pointerup', x, y, event.pointerId || 0, event.button || 0, 0, 0);
+      this.#rawView.dispatchPointer(
+        'pointerup',
+        x,
+        y,
+        event.pointerId || 0,
+        event.button || 0,
+        0,
+        0,
+      );
       this.requestRender();
     });
     addListener(canvas, 'pointercancel', (event) => {
       const { x, y } = getPointerPosition(canvas, event);
-      this.#rawView.dispatchPointer('touchcancel', x, y, event.pointerId || 0, event.button || 0, 0, 0);
+      this.#rawView.dispatchPointer(
+        'touchcancel',
+        x,
+        y,
+        event.pointerId || 0,
+        event.button || 0,
+        0,
+        0,
+      );
       this.requestRender();
     });
     addListener(
@@ -336,18 +441,34 @@ export class InkView {
         if (options.preventWheelDefault !== false && typeof event.preventDefault === 'function') {
           event.preventDefault();
         }
-        this.#rawView.dispatchPointer('mousewheel', x, y, 0, 0, event.deltaX || 0, event.deltaY || 0);
+        this.#rawView.dispatchPointer(
+          'mousewheel',
+          x,
+          y,
+          0,
+          0,
+          event.deltaX || 0,
+          event.deltaY || 0,
+        );
         this.requestRender();
       },
       { passive: false },
     );
 
     addListener(keyboardTarget, 'keydown', (event) => {
-      this.#rawView.dispatchInput('keydown', normalizeKeyboardCode(event), Number(event.timeStamp || Date.now()));
+      this.#rawView.dispatchInput(
+        'keydown',
+        normalizeKeyboardCode(event),
+        Number(event.timeStamp || Date.now()),
+      );
       this.requestRender();
     });
     addListener(keyboardTarget, 'keyup', (event) => {
-      this.#rawView.dispatchInput('keyup', normalizeKeyboardCode(event), Number(event.timeStamp || Date.now()));
+      this.#rawView.dispatchInput(
+        'keyup',
+        normalizeKeyboardCode(event),
+        Number(event.timeStamp || Date.now()),
+      );
       this.requestRender();
     });
     addListener(focusTarget, 'focus', () => {
@@ -372,18 +493,33 @@ export class InkView {
       throw new Error('`appId` must be a non-empty string.');
     }
 
-    this.#rawView.openBundle(appId, normalizeBundleFiles(files), initialPage, serializeQuery(query));
+    this.#rawView.openBundle(
+      appId,
+      normalizeBundleFiles(files),
+      initialPage,
+      serializeQuery(query),
+    );
     this.requestRender();
     return this;
   }
 
-  async openFromVfs({ appId, baseUrl, initialPage = null, query = null, fetch, signal, headers }) {
+  async openFromVfs({
+    appId,
+    baseUrl,
+    initialPage = null,
+    query = null,
+    fetch,
+    signal,
+    headers,
+    requestInterceptor,
+  }) {
     const bundle = await loadBundleFromVfs({
       appId,
       baseUrl,
       fetch,
       signal,
       headers,
+      requestInterceptor,
     });
     this.openBundle({
       appId: bundle.appId,
@@ -472,5 +608,9 @@ export function createFrameworkBindings() {
     ensureLeadingSlash,
     initInk,
     createInkView,
+    configureNetwork,
+    setInkRequestInterceptor,
+    clearInkRequestInterceptor,
+    createProxyUrlResolver,
   };
 }

package/dist/pkg/README.md

@@ -17,7 +17,7 @@ This package compiles the Ink engine into Wasm, enabling it to run in modern web
 ./build.sh
 ```
 
-2. Start the bundled Node static server and proxy:
+2. Start the bundled Node static server:
 
 ```bash
 npm run dev --prefix playground
@@ -29,6 +29,6 @@ npm run dev --prefix playground
 http://localhost:8080
 ```
 
-The local server also exposes a same-origin `/__proxy` endpoint for external HTTP resources so
-the demo can load remote images and other browser-fetched assets without direct cross-origin
-requests from the page.
+The playground host configures a same-origin `/__proxy` interceptor example for
+external HTTP resources. This proxy behavior is no longer hard-coded inside
+`ink-web`; hosts now opt into request interception explicitly from the SDK side.

package/dist/pkg/ink_web.d.ts

@@ -41,11 +41,11 @@ export interface InitOutput {
     readonly inkwebview_render: (a: number, b: number) => void;
     readonly inkwebview_resize: (a: number, b: number, c: number, d: number) => void;
     readonly main: () => void;
-    readonly __wasm_bindgen_func_elem_8675: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_12871: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_8855: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_12872: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_8856: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_8658: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_12847: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_8747: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_12848: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_8748: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/dist/pkg/ink_web.js

@@ -208,6 +208,8 @@ import * as import25 from "../env.js"
 import * as import26 from "../env.js"
 import * as import27 from "../env.js"
 import * as import28 from "../env.js"
+import * as import29 from "../env.js"
+import * as import30 from "../env.js"
 
 function __wbg_get_imports() {
     const import0 = {
@@ -314,6 +316,10 @@ function __wbg_get_imports() {
             const ret = getObject(arg0).call(getObject(arg1));
             return addHeapObject(ret);
         }, arguments); },
+        __wbg_call_e8c868596c950cf6: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+            const ret = getObject(arg0).call(getObject(arg1), getObject(arg2), getObject(arg3), getObject(arg4));
+            return addHeapObject(ret);
+        }, arguments); },
         __wbg_clearRect_1eed255045515c55: function(arg0, arg1, arg2, arg3, arg4) {
             getObject(arg0).clearRect(arg1, arg2, arg3, arg4);
         },
@@ -433,10 +439,6 @@ function __wbg_get_imports() {
         __wbg_error_9a7fe3f932034cde: function(arg0) {
             console.error(getObject(arg0));
         },
-        __wbg_fetch_7f864e6b0cbd00ea: function(arg0, arg1, arg2, arg3) {
-            const ret = getObject(arg0).fetch(getStringFromWasm0(arg1, arg2), getObject(arg3));
-            return addHeapObject(ret);
-        },
         __wbg_fillRect_d44afec47e3a3fab: function(arg0, arg1, arg2, arg3, arg4) {
             getObject(arg0).fillRect(arg1, arg2, arg3, arg4);
         },
@@ -498,6 +500,16 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
+        __wbg_instanceof_Error_8573fe0b0b480f46: function(arg0) {
+            let result;
+            try {
+                result = getObject(arg0) instanceof Error;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
         __wbg_instanceof_HtmlCanvasElement_3f2f6e1edb1c9792: function(arg0) {
             let result;
             try {
@@ -598,9 +610,17 @@ function __wbg_get_imports() {
             const ret = getObject(arg0).measureText(getStringFromWasm0(arg1, arg2));
             return addHeapObject(ret);
         }, arguments); },
+        __wbg_message_9ddc4b9a62a7c379: function(arg0) {
+            const ret = getObject(arg0).message;
+            return addHeapObject(ret);
+        },
         __wbg_moveTo_e9190fc700d55b40: function(arg0, arg1, arg2) {
             getObject(arg0).moveTo(arg1, arg2);
         },
+        __wbg_name_446e25ef2cfdab5a: function(arg0) {
+            const ret = getObject(arg0).name;
+            return addHeapObject(ret);
+        },
         __wbg_navigator_43be698ba96fc088: function(arg0) {
             const ret = getObject(arg0).navigator;
             return addHeapObject(ret);
@@ -621,6 +641,10 @@ function __wbg_get_imports() {
             const ret = new Headers();
             return addHeapObject(ret);
         }, arguments); },
+        __wbg_new_72b49615380db768: function(arg0, arg1) {
+            const ret = new Error(getStringFromWasm0(arg0, arg1));
+            return addHeapObject(ret);
+        },
         __wbg_new_7455c5eb8798868d: function() { return handleError(function () {
             const ret = new Audio();
             return addHeapObject(ret);
@@ -943,28 +967,28 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 2341, function: Function { arguments: [NamedExternref("CloseEvent")], shim_idx: 2298, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8675, __wasm_bindgen_func_elem_8855);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 2300, function: Function { arguments: [NamedExternref("CloseEvent")], shim_idx: 2304, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8658, __wasm_bindgen_func_elem_8747);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 2341, function: Function { arguments: [NamedExternref("Event")], shim_idx: 2298, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8675, __wasm_bindgen_func_elem_8855);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 2300, function: Function { arguments: [NamedExternref("Event")], shim_idx: 2304, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8658, __wasm_bindgen_func_elem_8747);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 2341, function: Function { arguments: [NamedExternref("MessageEvent")], shim_idx: 2298, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8675, __wasm_bindgen_func_elem_8855);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 2300, function: Function { arguments: [NamedExternref("MessageEvent")], shim_idx: 2304, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8658, __wasm_bindgen_func_elem_8747);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000004: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 2341, function: Function { arguments: [], shim_idx: 2344, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8675, __wasm_bindgen_func_elem_8856);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 2300, function: Function { arguments: [], shim_idx: 2301, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_8658, __wasm_bindgen_func_elem_8748);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000005: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 3267, function: Function { arguments: [Externref], shim_idx: 3268, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_12871, __wasm_bindgen_func_elem_12872);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 3264, function: Function { arguments: [Externref], shim_idx: 3265, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_12847, __wasm_bindgen_func_elem_12848);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000006: function(arg0) {
@@ -1016,19 +1040,21 @@ function __wbg_get_imports() {
         "env": import26,
         "env": import27,
         "env": import28,
+        "env": import29,
+        "env": import30,
     };
 }
 
-function __wasm_bindgen_func_elem_8856(arg0, arg1) {
-    wasm.__wasm_bindgen_func_elem_8856(arg0, arg1);
+function __wasm_bindgen_func_elem_8748(arg0, arg1) {
+    wasm.__wasm_bindgen_func_elem_8748(arg0, arg1);
 }
 
-function __wasm_bindgen_func_elem_8855(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_8855(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_8747(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_8747(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_12872(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_12872(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_12848(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_12848(arg0, arg1, addHeapObject(arg2));
 }
 
 

package/dist/pkg/ink_web_bg.wasm.d.ts

@@ -16,11 +16,11 @@ export const inkwebview_openBundle: (a: number, b: number, c: number, d: number,
 export const inkwebview_render: (a: number, b: number) => void;
 export const inkwebview_resize: (a: number, b: number, c: number, d: number) => void;
 export const main: () => void;
-export const __wasm_bindgen_func_elem_8675: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_12871: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_8855: (a: number, b: number, c: number) => void;
-export const __wasm_bindgen_func_elem_12872: (a: number, b: number, c: number) => void;
-export const __wasm_bindgen_func_elem_8856: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_8658: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_12847: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_8747: (a: number, b: number, c: number) => void;
+export const __wasm_bindgen_func_elem_12848: (a: number, b: number, c: number) => void;
+export const __wasm_bindgen_func_elem_8748: (a: number, b: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yodaos-pkg/ink",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Ink Web SDK for browser rendering and VFS-backed app loading",
   "type": "module",
   "main": "dist/index.js",