@yodaos-pkg/ink 0.1.0

package/dist/index.js

@@ -0,0 +1,476 @@
+import initInkWasm, {
+  InkWebView as RawInkWebView,
+  get_version as getInkVersionFromWasm,
+} from './pkg/ink_web.js';
+
+let bindingsPromise;
+
+function getDefaultScaleFactor() {
+  return Number(globalThis.devicePixelRatio || 1);
+}
+
+function ensureFetch(fetchImpl) {
+  const resolved = fetchImpl || globalThis.fetch;
+  if (typeof resolved !== 'function') {
+    throw new Error('A fetch implementation is required for VFS loading.');
+  }
+  return resolved;
+}
+
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, '');
+}
+
+function ensureLeadingSlash(value) {
+  if (!value) {
+    return '/';
+  }
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function normalizeBaseUrl(baseUrl) {
+  if (typeof baseUrl !== 'string' || !baseUrl.trim()) {
+    throw new Error('`baseUrl` must be a non-empty string.');
+  }
+  return trimTrailingSlash(baseUrl.trim());
+}
+
+function cloneUint8Array(value) {
+  if (value instanceof Uint8Array) {
+    return new Uint8Array(value);
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value.slice(0));
+  }
+  return null;
+}
+
+function toBundleBytes(filePath, value) {
+  if (typeof value === 'string') {
+    return new TextEncoder().encode(value);
+  }
+
+  const cloned = cloneUint8Array(value);
+  if (cloned) {
+    return cloned;
+  }
+
+  throw new TypeError(
+    `Unsupported bundle file payload for \`${filePath}\`. Expected string, ArrayBuffer, or Uint8Array.`,
+  );
+}
+
+function getEntries(files) {
+  if (files instanceof Map) {
+    return Array.from(files.entries());
+  }
+  if (Array.isArray(files)) {
+    return files;
+  }
+  if (files && typeof files === 'object') {
+    return Object.entries(files);
+  }
+  throw new TypeError('`files` must be a Map, entry array, or plain object.');
+}
+
+export function normalizeBundleFiles(files) {
+  const normalized = new Map();
+  for (const [filePath, value] of getEntries(files)) {
+    if (typeof filePath !== 'string' || !filePath) {
+      throw new TypeError('Bundle file paths must be non-empty strings.');
+    }
+    normalized.set(filePath, toBundleBytes(filePath, value));
+  }
+  return normalized;
+}
+
+export function serializeQuery(query) {
+  if (query == null) {
+    return null;
+  }
+  if (typeof query === 'string') {
+    return query;
+  }
+  return JSON.stringify(query);
+}
+
+async function buildHttpError(response, bodyReader = (res) => res.text()) {
+  let details = response.statusText;
+  try {
+    details = await bodyReader(response);
+  } catch {
+    // Keep the default status text when the body cannot be read.
+  }
+  const message = `Request failed with ${response.status} ${response.statusText}: ${String(details).slice(0, 200)}`;
+  return new Error(message);
+}
+
+export function createVfsUrls({ baseUrl, appId }) {
+  if (typeof appId !== 'string' || !appId.trim()) {
+    throw new Error('`appId` must be a non-empty string.');
+  }
+
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+  const encodedAppId = encodeURIComponent(appId.trim());
+
+  return {
+    manifestUrl: `${normalizedBaseUrl}/apps/${encodedAppId}/manifest`,
+    fileUrl(filePath) {
+      if (typeof filePath !== 'string' || !filePath) {
+        throw new Error('`filePath` must be a non-empty string.');
+      }
+      const segments = filePath
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(segment));
+      return `${normalizedBaseUrl}/apps/${encodedAppId}/files/${segments.join('/')}`;
+    },
+  };
+}
+
+export async function loadBundleFromVfs({
+  appId,
+  baseUrl,
+  fetch: fetchImpl,
+  signal,
+  headers,
+}) {
+  const resolvedFetch = ensureFetch(fetchImpl);
+  const { manifestUrl, fileUrl } = createVfsUrls({ baseUrl, appId });
+
+  const manifestResponse = await resolvedFetch(manifestUrl, {
+    method: 'GET',
+    headers,
+    signal,
+  });
+  if (!manifestResponse.ok) {
+    throw await buildHttpError(manifestResponse);
+  }
+
+  const manifest = await manifestResponse.json();
+  if (!manifest || !Array.isArray(manifest.files)) {
+    throw new Error('VFS manifest must include a `files` array.');
+  }
+
+  const files = new Map();
+  await Promise.all(
+    manifest.files.map(async (entry) => {
+      if (!entry || typeof entry.path !== 'string' || !entry.path) {
+        throw new Error('Each VFS manifest entry must include a non-empty `path`.');
+      }
+
+      const response = await resolvedFetch(fileUrl(entry.path), {
+        method: 'GET',
+        headers,
+        signal,
+      });
+      if (!response.ok) {
+        throw await buildHttpError(response);
+      }
+
+      files.set(entry.path, new Uint8Array(await response.arrayBuffer()));
+    }),
+  );
+
+  return {
+    appId: manifest.appId || appId,
+    manifest,
+    files,
+  };
+}
+
+function normalizeKeyboardCode(event) {
+  return event.code || event.key || 'Unidentified';
+}
+
+function getPointerPosition(canvas, event) {
+  const rect = canvas.getBoundingClientRect();
+  return {
+    x: event.clientX - rect.left,
+    y: event.clientY - rect.top,
+  };
+}
+
+function ensureAnimationFrameApi() {
+  if (typeof globalThis.requestAnimationFrame !== 'function') {
+    return {
+      request(callback) {
+        return setTimeout(() => callback(Date.now()), 16);
+      },
+      cancel(handle) {
+        clearTimeout(handle);
+      },
+    };
+  }
+
+  return {
+    request(callback) {
+      return globalThis.requestAnimationFrame(callback);
+    },
+    cancel(handle) {
+      globalThis.cancelAnimationFrame(handle);
+    },
+  };
+}
+
+export async function initInk(options = {}) {
+  if (!bindingsPromise) {
+    const initInput = options.wasmUrl || options.moduleOrPath || new URL('./pkg/ink_web_bg.wasm', import.meta.url);
+    bindingsPromise = initInkWasm(initInput).then(() => ({
+      InkWebView: RawInkWebView,
+      getInkVersion: getInkVersionFromWasm,
+    }));
+  }
+
+  return bindingsPromise;
+}
+
+export function getInkVersion() {
+  return getInkVersionFromWasm();
+}
+
+export class InkView {
+  static async create(options) {
+    const config = options || {};
+    const width = Number(config.width);
+    const height = Number(config.height);
+
+    if (!Number.isFinite(width) || !Number.isFinite(height)) {
+      throw new Error('`width` and `height` are required numeric values.');
+    }
+
+    const bindings = await initInk(config.wasm);
+    const rawView = new bindings.InkWebView(width, height, Number(config.scaleFactor || getDefaultScaleFactor()));
+    const view = new InkView(rawView, config);
+
+    if (config.canvas) {
+      view.bindCanvas(config.canvas);
+    }
+
+    return view;
+  }
+
+  #rawView;
+  #canvas;
+  #animationFrameApi;
+  #frameHandle;
+  #autoRender;
+  #domCleanup;
+
+  constructor(rawView, options = {}) {
+    this.#rawView = rawView;
+    this.#canvas = options.canvas || null;
+    this.#animationFrameApi = ensureAnimationFrameApi();
+    this.#frameHandle = null;
+    this.#autoRender = false;
+    this.#domCleanup = null;
+  }
+
+  bindCanvas(canvas) {
+    if (!canvas || typeof canvas.getBoundingClientRect !== 'function') {
+      throw new TypeError('`canvas` must be an HTMLCanvasElement-like object.');
+    }
+
+    this.#rawView.bindCanvas(canvas);
+    this.#canvas = canvas;
+    return this;
+  }
+
+  bindDomEvents(options = {}) {
+    const canvas = options.canvas || this.#canvas;
+    if (!canvas) {
+      throw new Error('bindDomEvents requires a bound canvas.');
+    }
+
+    if (this.#domCleanup) {
+      this.#domCleanup();
+    }
+
+    const keyboardTarget = options.keyboardTarget || globalThis.window || canvas;
+    const focusTarget = options.focusTarget || canvas;
+    const listeners = [];
+    const addListener = (target, type, listener, listenerOptions) => {
+      if (!target || typeof target.addEventListener !== 'function') {
+        return;
+      }
+      target.addEventListener(type, listener, listenerOptions);
+      listeners.push(() => target.removeEventListener(type, listener, listenerOptions));
+    };
+
+    if (focusTarget && typeof focusTarget.setAttribute === 'function' && focusTarget.tabIndex < 0) {
+      focusTarget.setAttribute('tabindex', '0');
+    }
+
+    addListener(canvas, 'pointerdown', (event) => {
+      const { x, y } = getPointerPosition(canvas, event);
+      this.notifyUserInteraction();
+      if (focusTarget && typeof focusTarget.focus === 'function') {
+        focusTarget.focus();
+      }
+      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.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.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.requestRender();
+    });
+    addListener(
+      canvas,
+      'wheel',
+      (event) => {
+        const { x, y } = getPointerPosition(canvas, event);
+        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.requestRender();
+      },
+      { passive: false },
+    );
+
+    addListener(keyboardTarget, 'keydown', (event) => {
+      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.requestRender();
+    });
+    addListener(focusTarget, 'focus', () => {
+      this.focus();
+    });
+    addListener(focusTarget, 'blur', () => {
+      this.blur();
+    });
+
+    this.#domCleanup = () => {
+      for (const dispose of listeners.splice(0)) {
+        dispose();
+      }
+      this.#domCleanup = null;
+    };
+
+    return this.#domCleanup;
+  }
+
+  openBundle({ appId, files, initialPage = null, query = null }) {
+    if (typeof appId !== 'string' || !appId.trim()) {
+      throw new Error('`appId` must be a non-empty string.');
+    }
+
+    this.#rawView.openBundle(appId, normalizeBundleFiles(files), initialPage, serializeQuery(query));
+    this.requestRender();
+    return this;
+  }
+
+  async openFromVfs({ appId, baseUrl, initialPage = null, query = null, fetch, signal, headers }) {
+    const bundle = await loadBundleFromVfs({
+      appId,
+      baseUrl,
+      fetch,
+      signal,
+      headers,
+    });
+    this.openBundle({
+      appId: bundle.appId,
+      files: bundle.files,
+      initialPage,
+      query,
+    });
+    return bundle;
+  }
+
+  resize(width, height, scaleFactor = getDefaultScaleFactor()) {
+    this.#rawView.resize(Number(width), Number(height), Number(scaleFactor));
+    this.requestRender();
+    return this;
+  }
+
+  focus() {
+    this.#rawView.focus();
+    return this;
+  }
+
+  blur() {
+    this.#rawView.blur();
+    return this;
+  }
+
+  notifyUserInteraction() {
+    this.#rawView.notifyUserInteraction();
+    return this;
+  }
+
+  render() {
+    const hasMoreWork = Boolean(this.#rawView.render());
+    if (hasMoreWork || this.#autoRender) {
+      this.requestRender();
+    }
+    return hasMoreWork;
+  }
+
+  requestRender() {
+    if (this.#frameHandle != null) {
+      return this;
+    }
+
+    this.#frameHandle = this.#animationFrameApi.request(() => {
+      this.#frameHandle = null;
+      this.render();
+    });
+    return this;
+  }
+
+  startRendering() {
+    this.#autoRender = true;
+    this.requestRender();
+    return this;
+  }
+
+  stopRendering() {
+    this.#autoRender = false;
+    if (this.#frameHandle != null) {
+      this.#animationFrameApi.cancel(this.#frameHandle);
+      this.#frameHandle = null;
+    }
+    return this;
+  }
+
+  isRunning() {
+    return Boolean(this.#rawView.isRunning());
+  }
+
+  destroy() {
+    this.stopRendering();
+    if (this.#domCleanup) {
+      this.#domCleanup();
+    }
+    this.#rawView.destroy();
+  }
+}
+
+export function createInkView(options) {
+  return InkView.create(options);
+}
+
+export function createFrameworkBindings() {
+  return {
+    ensureLeadingSlash,
+    initInk,
+    createInkView,
+  };
+}

package/dist/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@yodaos-pkg/ink",
+  "version": "0.1.0",
+  "description": "Ink Web SDK for browser rendering and VFS-backed app loading",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsar-project/ink"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.com/"
+  }
+}

package/dist/pkg/README.md

@@ -0,0 +1,34 @@
+# ink-web
+
+`ink-web` provides WebAssembly (Wasm) bindings.
+
+## Features
+
+This package compiles the Ink engine into Wasm, enabling it to run in modern web browsers:
+
+- **Wasm Bindings**: Utilizes `wasm-bindgen` to implement interoperability between Rust code and Web APIs.
+- **Web Rendering**: Bridges Ink's drawing instructions to Web Canvas or WebGL.
+
+## Running Locally
+
+1. Build the demo:
+
+```bash
+./build.sh
+```
+
+2. Start the bundled Node static server and proxy:
+
+```bash
+npm run dev --prefix playground
+```
+
+3. Open:
+
+```text
+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.

package/dist/pkg/ink_web.d.ts

@@ -0,0 +1,77 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class InkWebView {
+    free(): void;
+    [Symbol.dispose](): void;
+    bindCanvas(canvas: HTMLCanvasElement): void;
+    blur(): void;
+    destroy(): void;
+    dispatchInput(event_type: string, code: string, timestamp: number): void;
+    dispatchPointer(event_type: string, x: number, y: number, id: number, button: number, delta_x: number, delta_y: number): void;
+    focus(): void;
+    isRunning(): boolean;
+    constructor(width: number, height: number, scale_factor: number);
+    notifyUserInteraction(): void;
+    openBundle(app_id: string, files: Map<any, any>, initial_page?: string | null, query_json?: string | null): void;
+    render(): boolean;
+    resize(width: number, height: number, scale_factor: number): void;
+}
+
+export function get_version(): string;
+
+export function main(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_inkwebview_free: (a: number, b: number) => void;
+    readonly get_version: (a: number) => void;
+    readonly inkwebview_bindCanvas: (a: number, b: number, c: number) => void;
+    readonly inkwebview_blur: (a: number) => void;
+    readonly inkwebview_destroy: (a: number) => void;
+    readonly inkwebview_dispatchInput: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly inkwebview_dispatchPointer: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+    readonly inkwebview_focus: (a: number) => void;
+    readonly inkwebview_isRunning: (a: number) => number;
+    readonly inkwebview_new: (a: number, b: number, c: number) => number;
+    readonly inkwebview_notifyUserInteraction: (a: number) => void;
+    readonly inkwebview_openBundle: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    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 __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;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;