@effindomv2/fui-as 0.1.0

package/browser/src/worker-manager.ts

@@ -0,0 +1,230 @@
+import type {
+  WorkerBootstrapInboundMessage,
+  WorkerBootstrapOutboundMessage,
+  WorkerHostServicesBundleConfig,
+  WorkerManifest,
+} from './worker-types';
+
+interface WorkerHarnessExports {
+  __fui_on_worker_progress(workerId: number, textPtr: number, textLen: number): void;
+  __fui_on_worker_complete(workerId: number, textPtr: number, textLen: number): void;
+  __fui_on_worker_error(workerId: number, textPtr: number, textLen: number): void;
+}
+
+export interface WorkerHarnessSession {
+  readonly exports: WorkerHarnessExports;
+  readonly memory: WebAssembly.Memory;
+  readonly textBufferPtr: number;
+  readonly textBufferSize: number;
+}
+
+interface WorkerTextSession {
+  readonly memory: WebAssembly.Memory;
+  readonly textBufferPtr: number;
+  readonly textBufferSize: number;
+}
+
+interface WorkerRecord {
+  worker: Worker | null;
+  cancelled: boolean;
+}
+
+export interface WorkerManager {
+  startString(workerId: number, entryName: string, input: string): void;
+  cancel(workerId: number): void;
+  terminateAll(): void;
+}
+
+interface WorkerManagerOptions {
+  readonly scriptBaseUrl: string;
+  readonly getCurrentSession: () => WorkerHarnessSession | null;
+  readonly getCurrentWorkerHostServices: () => WorkerHostServicesBundleConfig | undefined;
+  readonly writeTextCallbackPayload: (session: WorkerTextSession, text: string, context: string) => number;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function validateManifest(value: unknown): WorkerManifest {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error('Malformed worker manifest: expected an object.');
+  }
+  const candidate = value as { version?: unknown; entries?: unknown; };
+  if (candidate.version !== 1) {
+    throw new Error('Malformed worker manifest: expected version 1.');
+  }
+  if (typeof candidate.entries !== 'object' || candidate.entries === null) {
+    throw new Error('Malformed worker manifest: expected an entries object.');
+  }
+  for (const [entryName, entryUrl] of Object.entries(candidate.entries as Record<string, unknown>)) {
+    if (typeof entryName !== 'string' || entryName.length === 0 || typeof entryUrl !== 'string' || entryUrl.length === 0) {
+      throw new Error('Malformed worker manifest: each entry must map a non-empty name to a non-empty URL.');
+    }
+  }
+  return candidate as WorkerManifest;
+}
+
+export function createWorkerManager(options: WorkerManagerOptions): WorkerManager {
+  const workerBootstrapUrl = new URL('./worker-bootstrap.js', options.scriptBaseUrl).toString();
+  const workerManifestUrl = new URL('./worker-manifest.json', options.scriptBaseUrl).toString();
+  const records = new Map<number, WorkerRecord>();
+  let manifestPromise: Promise<WorkerManifest> | null = null;
+
+  function emitToSession(workerId: number, kind: 'progress' | 'complete' | 'error', text: string): void {
+    const session = options.getCurrentSession();
+    if (session === null) {
+      return;
+    }
+    try {
+      const textLength = options.writeTextCallbackPayload(session, text, `Worker ${kind} payload`);
+      const textPtr = textLength > 0 ? session.textBufferPtr : 0;
+      if (kind === 'progress') {
+        session.exports.__fui_on_worker_progress(workerId, textPtr, textLength);
+        return;
+      }
+      if (kind === 'complete') {
+        session.exports.__fui_on_worker_complete(workerId, textPtr, textLength);
+        return;
+      }
+      session.exports.__fui_on_worker_error(workerId, textPtr, textLength);
+    } catch (error: unknown) {
+      console.error(`[fui-worker] failed to deliver ${kind} payload for worker ${String(workerId)}: ${describeError(error)}`);
+      if (kind !== 'error') {
+        emitToSession(workerId, 'error', `Worker ${kind} delivery failed: ${describeError(error)}`);
+      }
+    }
+  }
+
+  function finishWorker(workerId: number): void {
+    const record = records.get(workerId);
+    if (record === undefined) {
+      return;
+    }
+    record.worker?.terminate();
+    records.delete(workerId);
+  }
+
+  function handleWorkerMessage(workerId: number, message: WorkerBootstrapOutboundMessage): void {
+    const record = records.get(workerId);
+    if (record === undefined) {
+      return;
+    }
+    if (message.type === 'progress') {
+      if (!record.cancelled) {
+        emitToSession(workerId, 'progress', message.text);
+      }
+      return;
+    }
+    if (message.type === 'complete') {
+      emitToSession(workerId, 'complete', message.text);
+      finishWorker(workerId);
+      return;
+    }
+    emitToSession(workerId, 'error', message.text);
+    finishWorker(workerId);
+  }
+
+  function loadManifest(): Promise<WorkerManifest> {
+    if (manifestPromise !== null) {
+      return manifestPromise;
+    }
+    manifestPromise = fetch(workerManifestUrl, {
+      cache: 'no-store',
+      credentials: 'same-origin',
+    }).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(`Failed to load worker manifest from ${workerManifestUrl}.`);
+      }
+      return validateManifest(await response.json());
+    });
+    return manifestPromise;
+  }
+
+  async function startWorkerAsync(workerId: number, entryName: string, input: string): Promise<void> {
+    const record = records.get(workerId);
+    if (record === undefined) {
+      return;
+    }
+    try {
+      const manifest = await loadManifest();
+      if (records.get(workerId) !== record) {
+        return;
+      }
+      const workerModuleUrl = manifest.entries[entryName];
+      if (typeof workerModuleUrl !== 'string' || workerModuleUrl.length === 0) {
+        emitToSession(workerId, 'error', `Unknown worker entry "${entryName}".`);
+        finishWorker(workerId);
+        return;
+      }
+      const worker = new Worker(workerBootstrapUrl);
+      if (records.get(workerId) !== record) {
+        worker.terminate();
+        return;
+      }
+      record.worker = worker;
+      worker.addEventListener('message', (event: MessageEvent<WorkerBootstrapOutboundMessage>) => {
+        handleWorkerMessage(workerId, event.data);
+      });
+      worker.addEventListener('error', (event: ErrorEvent) => {
+        const active = records.get(workerId);
+        if (active === undefined) {
+          return;
+        }
+        emitToSession(workerId, 'error', event.message.length > 0 ? event.message : 'Worker bootstrap crashed.');
+        finishWorker(workerId);
+      });
+      const message: WorkerBootstrapInboundMessage = {
+        type: 'start',
+        workerId,
+        wasmUrl: new URL(workerModuleUrl, workerManifestUrl).toString(),
+        entryName,
+        input,
+        workerHostServices: options.getCurrentWorkerHostServices(),
+      };
+      worker.postMessage(message);
+      if (record.cancelled) {
+        worker.postMessage({
+          type: 'cancel',
+          workerId,
+        });
+      }
+    } catch (error: unknown) {
+      emitToSession(workerId, 'error', describeError(error));
+      finishWorker(workerId);
+    }
+  }
+
+  return {
+    startString(workerId: number, entryName: string, input: string): void {
+      if (records.has(workerId)) {
+        emitToSession(workerId, 'error', 'Worker already started.');
+        return;
+      }
+      records.set(workerId, {
+        worker: null,
+        cancelled: false,
+      });
+      void startWorkerAsync(workerId, entryName, input);
+    },
+    cancel(workerId: number): void {
+      const record = records.get(workerId);
+      if (record === undefined) {
+        return;
+      }
+      record.cancelled = true;
+      if (record.worker !== null) {
+        record.worker.postMessage({
+          type: 'cancel',
+          workerId,
+        });
+      }
+    },
+    terminateAll(): void {
+      for (const record of records.values()) {
+        record.worker?.terminate();
+      }
+      records.clear();
+    },
+  };
+}

package/browser/src/worker-types.ts

@@ -0,0 +1,50 @@
+export interface WorkerManifest {
+  readonly version: 1;
+  readonly entries: Readonly<Record<string, string>>;
+}
+
+export interface WorkerHostServicesBundleConfig {
+  readonly scriptUrl: string;
+  readonly exportName: string;
+}
+
+export interface WorkerBootstrapStartMessage {
+  readonly type: "start";
+  readonly workerId: number;
+  readonly wasmUrl: string;
+  readonly entryName: string;
+  readonly input: string;
+  readonly workerHostServices?: WorkerHostServicesBundleConfig;
+}
+
+export interface WorkerBootstrapCancelMessage {
+  readonly type: "cancel";
+  readonly workerId: number;
+}
+
+export type WorkerBootstrapInboundMessage =
+  | WorkerBootstrapStartMessage
+  | WorkerBootstrapCancelMessage;
+
+export interface WorkerBootstrapProgressMessage {
+  readonly type: "progress";
+  readonly workerId: number;
+  readonly text: string;
+}
+
+export interface WorkerBootstrapCompleteMessage {
+  readonly type: "complete";
+  readonly workerId: number;
+  readonly text: string;
+}
+
+export interface WorkerBootstrapErrorMessage {
+  readonly type: "error";
+  readonly workerId: number;
+  readonly text: string;
+}
+
+export type WorkerBootstrapOutboundMessage =
+  | WorkerBootstrapProgressMessage
+  | WorkerBootstrapCompleteMessage
+  | WorkerBootstrapErrorMessage;

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@effindomv2/fui-as",
+  "version": "0.1.0",
+  "private": false,
+  "license": "BSL-1.1",
+  "description": "EffinDom v2 AssemblyScript SDK and browser harness",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./src/Fui.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/Fui.ts",
+      "default": "./src/Fui.ts"
+    },
+    "./primitives": {
+      "types": "./src/FuiPrimitives.ts",
+      "default": "./src/FuiPrimitives.ts"
+    },
+    "./worker": {
+      "types": "./src/FuiWorker.ts",
+      "default": "./src/FuiWorker.ts"
+    },
+    "./worker-exports": {
+      "types": "./src/FuiWorkerExports.ts",
+      "default": "./src/FuiWorkerExports.ts"
+    },
+    "./exports": {
+      "types": "./src/FuiExports.ts",
+      "default": "./src/FuiExports.ts"
+    },
+    "./browser": {
+      "types": "./browser/src/index.ts",
+      "default": "./browser/src/index.ts"
+    },
+    "./browser/common-harness": {
+      "types": "./browser/src/common-harness.ts",
+      "default": "./browser/src/common-harness.ts"
+    },
+    "./browser/routed-harness": {
+      "types": "./browser/src/routed-harness.ts",
+      "default": "./browser/src/routed-harness.ts"
+    },
+    "./browser/host-events": {
+      "types": "./browser/src/host-events.ts",
+      "default": "./browser/src/host-events.ts"
+    },
+    "./browser/host-services": {
+      "types": "./browser/src/host-services.ts",
+      "default": "./browser/src/host-services.ts"
+    },
+    "./browser/worker-types": {
+      "types": "./browser/src/worker-types.ts",
+      "default": "./browser/src/worker-types.ts"
+    }
+  },
+  "files": [
+    "src",
+    "browser/src",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "build:only": "bash scripts/build.sh",
+    "build:full": "bash scripts/build.sh",
+    "build:demo:as": "bash scripts/build-demo-as.sh",
+    "test:unit": "asp --verbose -c as-pect.config.mjs -a as-pect.asconfig.json",
+    "test:integration": "npm run build:full && playwright test -c playwright.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@effindomv2/runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "@assemblyscript/loader": "^0.28.17",
+    "@as-pect/assembly": "8.1.0",
+    "@as-pect/cli": "8.1.0",
+    "@as-pect/core": "8.1.0",
+    "@playwright/test": "1.59.1",
+    "@types/node": "^24.10.1",
+    "assemblyscript": "0.28.17",
+    "esbuild": "^0.27.7",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/build-demo-as.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+PACKAGE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPO_ROOT="$(cd "${PACKAGE_DIR}/../.." && pwd)"
+DEMO_OUT_DIR="${REPO_ROOT}/public/v2/fui-as/demo"
+HELLO_OUT_DIR="${REPO_ROOT}/public/v2/fui-as/demo-hello-world"
+HOST_SERVICE_GENERATOR_BUILD="${PACKAGE_DIR}/build/generate-host-services.mjs"
+HOST_EVENT_GENERATOR_BUILD="${PACKAGE_DIR}/build/generate-host-events.mjs"
+BUILD_TARGET="${1:-all}"
+
+mkdir -p "${PACKAGE_DIR}/build" "${DEMO_OUT_DIR}" "${HELLO_OUT_DIR}"
+cd "${PACKAGE_DIR}"
+
+build_demo_app() {
+  local entry_file="$1"
+  local wasm_out="$2"
+
+  npx asc "${entry_file}" --config asconfig.json --target release
+  cp "${PACKAGE_DIR}/build/app.wasm" "${wasm_out}"
+  if [ -f "${PACKAGE_DIR}/build/app.wasm.map" ]; then
+    cp "${PACKAGE_DIR}/build/app.wasm.map" "${wasm_out}.map"
+  fi
+}
+
+generate_host_services() {
+  local definition_file="$1"
+  local export_name="$2"
+  local output_file="$3"
+
+  npx esbuild "${PACKAGE_DIR}/scripts/generate-host-services.ts" \
+    --bundle \
+    --format=esm \
+    --platform=node \
+    --target=node20 \
+    --packages=external \
+    --outfile="${HOST_SERVICE_GENERATOR_BUILD}"
+
+  node "${HOST_SERVICE_GENERATOR_BUILD}" "${definition_file}" "${export_name}" "${output_file}"
+}
+
+generate_host_events() {
+  local definition_file="$1"
+  local export_name="$2"
+  local output_file="$3"
+
+  npx esbuild "${PACKAGE_DIR}/scripts/generate-host-events.ts" \
+    --bundle \
+    --format=esm \
+    --platform=node \
+    --target=node20 \
+    --packages=external \
+    --outfile="${HOST_EVENT_GENERATOR_BUILD}"
+
+  node "${HOST_EVENT_GENERATOR_BUILD}" "${definition_file}" "${export_name}" "${output_file}"
+}
+
+generate_host_services "demo/src/host-services.ts" "demoHostServices" "demo/src/generated/HostServices.ts"
+generate_host_events "demo/src/host-events.ts" "demoHostEvents" "demo/src/generated/HostEvents.ts"
+generate_host_services "demo/src/worker-host-services.ts" "demoWorkerHostServices" "demo/src/generated/WorkerHostServices.ts"
+
+case "${BUILD_TARGET}" in
+  all)
+    build_demo_app "demo/src/dashboard.ts" "${DEMO_OUT_DIR}/demo.wasm"
+    build_demo_app "demo/src/routes/demo_home.ts" "${DEMO_OUT_DIR}/home.wasm"
+    build_demo_app "demo/src/routes/demo_advanced_controls.ts" "${DEMO_OUT_DIR}/advanced-controls.wasm"
+    build_demo_app "demo/src/routes/templated-controls.ts" "${DEMO_OUT_DIR}/templated-controls.wasm"
+    build_demo_app "demo-hello-world/src/App.ts" "${HELLO_OUT_DIR}/app.wasm"
+    ;;
+  dashboard)
+    build_demo_app "demo/src/dashboard.ts" "${DEMO_OUT_DIR}/demo.wasm"
+    ;;
+  home)
+    build_demo_app "demo/src/routes/demo_home.ts" "${DEMO_OUT_DIR}/home.wasm"
+    ;;
+  advanced-controls|advanced)
+    build_demo_app "demo/src/routes/demo_advanced_controls.ts" "${DEMO_OUT_DIR}/advanced-controls.wasm"
+    ;;
+  templated-controls|templated)
+    build_demo_app "demo/src/routes/templated-controls.ts" "${DEMO_OUT_DIR}/templated-controls.wasm"
+    ;;
+  hello-world|hello)
+    build_demo_app "demo-hello-world/src/App.ts" "${HELLO_OUT_DIR}/app.wasm"
+    ;;
+  *)
+    echo "Unknown build target: ${BUILD_TARGET}" >&2
+    echo "Usage: bash scripts/build-demo-as.sh [all|dashboard|home|advanced-controls|templated-controls|hello-world]" >&2
+    exit 1
+    ;;
+esac