@carbonenginejs/runtime-resource 0.9.1 → 0.10.0

package/dist/worker/CjsResManWorker.js

@@ -0,0 +1,217 @@
+import { Operation, Message } from './protocol.js';
+
+/**
+ * Static browser-worker host that owns its operation/message vocabulary,
+ * executes clone-safe source and format operations, installs the message
+ * envelope, transfers owned buffers, and serializes failures for `CjsResMan`.
+ */
+class CjsResManWorker {
+  /** Stable operations understood by the bundled resource module worker. */
+  static Operation = Operation;
+
+  /** Stable message kinds exchanged with the resource module worker. */
+  static Message = Message;
+
+  /**
+   * Execute one bundled resource worker operation.
+   *
+   * This method also permits deterministic non-browser tests and custom
+   * worker hosts without installing global message handlers.
+   *
+   * @param {string} operation Worker operation name.
+   * @param {*} payload Structured-cloneable operation payload.
+   * @param {object} [context={}] Optional fetch and abort context.
+   * @returns {Promise<*>} Operation result.
+   */
+  static async execute(operation, payload, context = {}) {
+    switch (operation) {
+      case Operation.FETCH:
+        return fetchResource(payload, context);
+      case Operation.FORMAT_READ:
+        return readFormat(payload);
+      default:
+        {
+          const error = new Error(`Unknown resource worker operation: ${operation}`);
+          error.code = "CJS_RESOURCE_WORKER_OPERATION_UNKNOWN";
+          error.operation = operation;
+          throw error;
+        }
+    }
+  }
+
+  /**
+   * Install the ResMan message protocol on a Worker-compatible scope.
+   *
+   * @param {WorkerGlobalScope|object} scope Worker global.
+   * @returns {() => void} Uninstall callback.
+   */
+  static install(scope = globalThis) {
+    if (!scope || typeof scope.postMessage !== "function") {
+      throw new TypeError("Resource worker scope must provide postMessage.");
+    }
+    const controllers = new Map();
+    const onMessage = async event => {
+      const message = event?.data;
+      if (!message || typeof message !== "object") return;
+      if (message.type === Message.CANCEL) {
+        controllers.get(message.id)?.abort();
+        return;
+      }
+      if (message.type !== Message.EXECUTE) return;
+      const controller = typeof AbortController === "function" ? new AbortController() : null;
+      if (controller) controllers.set(message.id, controller);
+      try {
+        const result = await CjsResManWorker.execute(message.operation, message.payload, {
+          signal: controller?.signal
+        });
+        scope.postMessage({
+          type: Message.RESULT,
+          id: message.id,
+          ok: true,
+          result
+        }, CjsResManWorker.collectTransferables(result));
+      } catch (error) {
+        scope.postMessage({
+          type: Message.RESULT,
+          id: message.id,
+          ok: false,
+          error: CjsResManWorker.serializeError(error, message.operation)
+        });
+      } finally {
+        controllers.delete(message.id);
+      }
+    };
+    if (typeof scope.addEventListener === "function") {
+      scope.addEventListener("message", onMessage);
+      return () => scope.removeEventListener?.("message", onMessage);
+    }
+    const previous = scope.onmessage;
+    scope.onmessage = onMessage;
+    return () => {
+      if (scope.onmessage === onMessage) scope.onmessage = previous || null;
+    };
+  }
+
+  /**
+   * Collect unique transferable ArrayBuffers from a worker result.
+   *
+   * SharedArrayBuffer is intentionally excluded because it is shared rather
+   * than transferable.
+   *
+   * @param {*} value Result graph.
+   * @returns {ArrayBuffer[]} Transfer list.
+   */
+  static collectTransferables(value) {
+    const buffers = new Set();
+    const seen = new Set();
+    const visit = entry => {
+      if (entry === null || entry === undefined) return;
+      if (entry instanceof ArrayBuffer) {
+        buffers.add(entry);
+        return;
+      }
+      if (ArrayBuffer.isView(entry)) {
+        if (entry.buffer instanceof ArrayBuffer) buffers.add(entry.buffer);
+        return;
+      }
+      if (typeof entry !== "object" || seen.has(entry)) return;
+      seen.add(entry);
+      if (Array.isArray(entry)) {
+        for (const item of entry) visit(item);
+        return;
+      }
+      for (const item of Object.values(entry)) visit(item);
+    };
+    visit(value);
+    return [...buffers];
+  }
+
+  /**
+   * Convert an exception into a cloneable diagnostic.
+   *
+   * @param {*} value Failure value.
+   * @param {string} [operation] Operation name.
+   * @returns {object} Cloneable error data.
+   */
+  static serializeError(value, operation = undefined) {
+    return {
+      name: value?.name || "CjsResManWorkerError",
+      message: value?.message || String(value),
+      code: value?.code,
+      operation: value?.operation || operation,
+      path: value?.path,
+      status: value?.status,
+      statusText: value?.statusText
+    };
+  }
+}
+async function fetchResource(payload, context) {
+  if (!payload || typeof payload.url !== "string") {
+    throw new TypeError("Worker fetch requires a URL.");
+  }
+  const fetchImplementation = context.fetch || globalThis.fetch;
+  if (typeof fetchImplementation !== "function") {
+    throw new ReferenceError("Worker fetch is unavailable.");
+  }
+  const options = {
+    ...(payload.options || {}),
+    ...(context.signal ? {
+      signal: context.signal
+    } : {})
+  };
+  const response = await fetchImplementation(payload.url, options);
+  if (!response.ok) {
+    const error = new Error(`Resource fetch failed: ${response.status} ${response.statusText}`);
+    error.code = "CJS_RESOURCE_FETCH_FAILED";
+    error.path = payload.path;
+    error.status = response.status;
+    error.statusText = response.statusText;
+    throw error;
+  }
+  switch (payload.responseType || "arraybuffer") {
+    case "arraybuffer":
+      return response.arrayBuffer();
+    case "blob":
+      return response.blob();
+    case "json":
+      return response.json();
+    case "text":
+      return response.text();
+    default:
+      {
+        const error = new Error(`Unsupported worker fetch response type: ${payload.responseType}`);
+        error.code = "CJS_RESOURCE_WORKER_RESPONSE_TYPE";
+        throw error;
+      }
+  }
+}
+async function readFormat(payload) {
+  if (!payload || typeof payload.module !== "string" || payload.module === "") {
+    throw new TypeError("Worker format read requires a module URL.");
+  }
+  const module = await import(payload.module);
+  const Format = module[payload.exportName || "default"];
+  if (typeof Format !== "function") {
+    throw new TypeError(`Worker format export was not found: ${payload.exportName || "default"}`);
+  }
+  const options = payload.options || {};
+  if (typeof Format.readAsync === "function") {
+    return Format.readAsync(payload.input, options);
+  }
+  if (typeof Format.read === "function") {
+    return Format.read(payload.input, options);
+  }
+  const reader = new Format(options);
+  if (typeof reader.ReadAsync === "function") {
+    return reader.ReadAsync(payload.input, options);
+  }
+  if (typeof reader.Read === "function") {
+    return reader.Read(payload.input, options);
+  }
+  throw new TypeError(`${Format.name} does not expose a read operation.`);
+}
+const isWorkerScope = typeof WorkerGlobalScope !== "undefined" && globalThis instanceof WorkerGlobalScope;
+if (isWorkerScope) CjsResManWorker.install(globalThis);
+
+export { CjsResManWorker };
+//# sourceMappingURL=CjsResManWorker.js.map

package/dist/worker/CjsResManWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CjsResManWorker.js","sources":["../../../src/worker/CjsResManWorker.js"],"sourcesContent":["import { Message, Operation } from \"./protocol.js\";\n\n/**\n * Static browser-worker host that owns its operation/message vocabulary,\n * executes clone-safe source and format operations, installs the message\n * envelope, transfers owned buffers, and serializes failures for `CjsResMan`.\n */\nexport class CjsResManWorker\n{\n  /** Stable operations understood by the bundled resource module worker. */\n  static Operation = Operation;\n\n  /** Stable message kinds exchanged with the resource module worker. */\n  static Message = Message;\n\n  /**\n   * Execute one bundled resource worker operation.\n   *\n   * This method also permits deterministic non-browser tests and custom\n   * worker hosts without installing global message handlers.\n   *\n   * @param {string} operation Worker operation name.\n   * @param {*} payload Structured-cloneable operation payload.\n   * @param {object} [context={}] Optional fetch and abort context.\n   * @returns {Promise<*>} Operation result.\n   */\n  static async execute(operation, payload, context = {})\n  {\n    switch (operation)\n    {\n      case Operation.FETCH:\n        return fetchResource(payload, context);\n\n      case Operation.FORMAT_READ:\n        return readFormat(payload);\n\n      default:\n      {\n        const error = new Error(`Unknown resource worker operation: ${operation}`);\n        error.code = \"CJS_RESOURCE_WORKER_OPERATION_UNKNOWN\";\n        error.operation = operation;\n        throw error;\n      }\n    }\n  }\n\n  /**\n   * Install the ResMan message protocol on a Worker-compatible scope.\n   *\n   * @param {WorkerGlobalScope|object} scope Worker global.\n   * @returns {() => void} Uninstall callback.\n   */\n  static install(scope = globalThis)\n  {\n    if (!scope || typeof scope.postMessage !== \"function\")\n    {\n      throw new TypeError(\"Resource worker scope must provide postMessage.\");\n    }\n    const controllers = new Map();\n    const onMessage = async event =>\n    {\n      const message = event?.data;\n      if (!message || typeof message !== \"object\") return;\n\n      if (message.type === Message.CANCEL)\n      {\n        controllers.get(message.id)?.abort();\n        return;\n      }\n      if (message.type !== Message.EXECUTE) return;\n\n      const controller = typeof AbortController === \"function\"\n        ? new AbortController()\n        : null;\n      if (controller) controllers.set(message.id, controller);\n      try\n      {\n        const result = await CjsResManWorker.execute(\n          message.operation,\n          message.payload,\n          { signal: controller?.signal }\n        );\n        scope.postMessage({\n          type: Message.RESULT,\n          id: message.id,\n          ok: true,\n          result\n        }, CjsResManWorker.collectTransferables(result));\n      }\n      catch (error)\n      {\n        scope.postMessage({\n          type: Message.RESULT,\n          id: message.id,\n          ok: false,\n          error: CjsResManWorker.serializeError(error, message.operation)\n        });\n      }\n      finally\n      {\n        controllers.delete(message.id);\n      }\n    };\n\n    if (typeof scope.addEventListener === \"function\")\n    {\n      scope.addEventListener(\"message\", onMessage);\n      return () => scope.removeEventListener?.(\"message\", onMessage);\n    }\n    const previous = scope.onmessage;\n    scope.onmessage = onMessage;\n    return () =>\n    {\n      if (scope.onmessage === onMessage) scope.onmessage = previous || null;\n    };\n  }\n\n  /**\n   * Collect unique transferable ArrayBuffers from a worker result.\n   *\n   * SharedArrayBuffer is intentionally excluded because it is shared rather\n   * than transferable.\n   *\n   * @param {*} value Result graph.\n   * @returns {ArrayBuffer[]} Transfer list.\n   */\n  static collectTransferables(value)\n  {\n    const buffers = new Set();\n    const seen = new Set();\n\n    const visit = entry =>\n    {\n      if (entry === null || entry === undefined) return;\n      if (entry instanceof ArrayBuffer)\n      {\n        buffers.add(entry);\n        return;\n      }\n      if (ArrayBuffer.isView(entry))\n      {\n        if (entry.buffer instanceof ArrayBuffer) buffers.add(entry.buffer);\n        return;\n      }\n      if (typeof entry !== \"object\" || seen.has(entry)) return;\n      seen.add(entry);\n      if (Array.isArray(entry))\n      {\n        for (const item of entry) visit(item);\n        return;\n      }\n      for (const item of Object.values(entry)) visit(item);\n    };\n\n    visit(value);\n    return [ ...buffers ];\n  }\n\n  /**\n   * Convert an exception into a cloneable diagnostic.\n   *\n   * @param {*} value Failure value.\n   * @param {string} [operation] Operation name.\n   * @returns {object} Cloneable error data.\n   */\n  static serializeError(value, operation = undefined)\n  {\n    return {\n      name: value?.name || \"CjsResManWorkerError\",\n      message: value?.message || String(value),\n      code: value?.code,\n      operation: value?.operation || operation,\n      path: value?.path,\n      status: value?.status,\n      statusText: value?.statusText\n    };\n  }\n}\n\nasync function fetchResource(payload, context) {\n  if (!payload || typeof payload.url !== \"string\") {\n    throw new TypeError(\"Worker fetch requires a URL.\");\n  }\n  const fetchImplementation = context.fetch || globalThis.fetch;\n  if (typeof fetchImplementation !== \"function\") {\n    throw new ReferenceError(\"Worker fetch is unavailable.\");\n  }\n  const options = {\n    ...(payload.options || {}),\n    ...(context.signal ? { signal: context.signal } : {})\n  };\n  const response = await fetchImplementation(payload.url, options);\n  if (!response.ok) {\n    const error = new Error(\n      `Resource fetch failed: ${response.status} ${response.statusText}`\n    );\n    error.code = \"CJS_RESOURCE_FETCH_FAILED\";\n    error.path = payload.path;\n    error.status = response.status;\n    error.statusText = response.statusText;\n    throw error;\n  }\n\n  switch (payload.responseType || \"arraybuffer\") {\n    case \"arraybuffer\":\n      return response.arrayBuffer();\n    case \"blob\":\n      return response.blob();\n    case \"json\":\n      return response.json();\n    case \"text\":\n      return response.text();\n    default: {\n      const error = new Error(`Unsupported worker fetch response type: ${payload.responseType}`);\n      error.code = \"CJS_RESOURCE_WORKER_RESPONSE_TYPE\";\n      throw error;\n    }\n  }\n}\n\nasync function readFormat(payload) {\n  if (!payload || typeof payload.module !== \"string\" || payload.module === \"\") {\n    throw new TypeError(\"Worker format read requires a module URL.\");\n  }\n  const module = await import(payload.module);\n  const Format = module[payload.exportName || \"default\"];\n  if (typeof Format !== \"function\") {\n    throw new TypeError(\n      `Worker format export was not found: ${payload.exportName || \"default\"}`\n    );\n  }\n  const options = payload.options || {};\n  if (typeof Format.readAsync === \"function\") {\n    return Format.readAsync(payload.input, options);\n  }\n  if (typeof Format.read === \"function\") {\n    return Format.read(payload.input, options);\n  }\n\n  const reader = new Format(options);\n  if (typeof reader.ReadAsync === \"function\") {\n    return reader.ReadAsync(payload.input, options);\n  }\n  if (typeof reader.Read === \"function\") {\n    return reader.Read(payload.input, options);\n  }\n  throw new TypeError(`${Format.name} does not expose a read operation.`);\n}\n\nconst isWorkerScope = typeof WorkerGlobalScope !== \"undefined\"\n  && globalThis instanceof WorkerGlobalScope;\nif (isWorkerScope) CjsResManWorker.install(globalThis);\n"],"names":["CjsResManWorker","Operation","Message","execute","operation","payload","context","FETCH","fetchResource","FORMAT_READ","readFormat","error","Error","code","install","scope","globalThis","postMessage","TypeError","controllers","Map","onMessage","event","message","data","type","CANCEL","get","id","abort","EXECUTE","controller","AbortController","set","result","signal","RESULT","ok","collectTransferables","serializeError","delete","addEventListener","removeEventListener","previous","onmessage","value","buffers","Set","seen","visit","entry","undefined","ArrayBuffer","add","isView","buffer","has","Array","isArray","item","Object","values","name","String","path","status","statusText","url","fetchImplementation","fetch","ReferenceError","options","response","responseType","arrayBuffer","blob","json","text","module","Format","exportName","readAsync","input","read","reader","ReadAsync","Read","isWorkerScope","WorkerGlobalScope"],"mappings":"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"}

package/dist/worker/CjsResManWorkerLoader.js

@@ -0,0 +1,434 @@
+import { Operation, Message } from './protocol.js';
+import { CjsResManMainThreadLoader } from './CjsResManMainThreadLoader.js';
+
+const DEFAULT_WORKER_OPTIONS = Object.freeze({
+  type: "module",
+  name: "CjsResManWorker"
+});
+
+/**
+ * Browser module-worker strategy that correlates source/format requests, transfers owned buffers, propagates cancellation and fatal failure, and delegates unsupported operations to a main-thread loader.
+ *
+ * One module worker can overlap fetch requests and serializes synchronous
+ * reader work on its own event loop. Sources opt in through
+ * `CreateWorkerRequest(path, options)`. Formats opt in through a static
+ * `worker` declaration containing their module URL and export name.
+ */
+class CjsResManWorkerLoader {
+  #boundError;
+  #boundMessage;
+  #nextId = 1;
+  #pending = new Map();
+
+  /**
+   * @param {object} [options={}] Worker construction and fallback options.
+   * @param {CjsResManMainThreadLoader|object} [options.fallback] Unsupported-operation fallback.
+   * @param {Worker|object} [options.worker] Existing Worker-compatible instance.
+   * @param {(url: string|URL, options: object) => Worker|object} [options.workerFactory] Worker factory.
+   * @param {string|URL} [options.workerUrl] Module worker entry URL.
+   * @param {object} [options.workerOptions] Options passed to the Worker constructor.
+   * @param {boolean} [options.enabled=true] Whether worker execution may be used.
+   */
+  constructor(options = {}) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+      throw new TypeError("CjsResManWorkerLoader options must be an object.");
+    }
+    this.fallback = options.fallback || new CjsResManMainThreadLoader();
+    assertResourceLoader(this.fallback, "fallback");
+    this.workerFactory = options.workerFactory || defaultWorkerFactory;
+    if (typeof this.workerFactory !== "function") {
+      throw new TypeError("CjsResManWorkerLoader workerFactory must be a function.");
+    }
+    this.workerUrl = options.workerUrl || new URL("./CjsResManWorker.js", import.meta.url);
+    this.workerOptions = Object.freeze({
+      ...DEFAULT_WORKER_OPTIONS,
+      ...(options.workerOptions || {})
+    });
+    this.enabled = options.enabled !== false;
+    this.failed = false;
+    this.worker = options.worker || null;
+    this.#boundMessage = event => this.#OnMessage(event);
+    this.#boundError = event => this.#OnError(event);
+    if (this.worker) this.#Attach(this.worker);
+  }
+
+  /**
+   * Enable and lazily create the configured worker.
+   *
+   * @param {string|URL} [workerUrl] Optional replacement worker URL.
+   * @returns {boolean} Whether a worker is ready.
+   */
+  Enable(workerUrl = this.workerUrl) {
+    this.enabled = true;
+    if (workerUrl !== undefined && workerUrl !== null) this.workerUrl = workerUrl;
+    if (this.worker) return true;
+    if (this.failed) return false;
+    try {
+      const worker = this.workerFactory(this.workerUrl, this.workerOptions);
+      if (!worker || typeof worker.postMessage !== "function") {
+        throw new TypeError("Worker factory did not return a Worker-compatible object.");
+      }
+      this.worker = worker;
+      this.#Attach(worker);
+      return true;
+    } catch {
+      this.worker = null;
+      this.failed = true;
+      return false;
+    }
+  }
+
+  /**
+   * Stop worker use and reject every pending request.
+   *
+   * @param {*} [reason] Optional failure reason.
+   * @returns {CjsResManWorkerLoader} This loader.
+   */
+  Disable(reason = null) {
+    const worker = this.worker;
+    if (worker) {
+      this.#Detach(worker);
+      worker.terminate?.();
+    }
+    this.worker = null;
+    this.enabled = false;
+    this.failed = reason !== null && reason !== undefined;
+    if (this.#pending.size) {
+      const error = normalizeWorkerError(reason || createWorkerUnavailableError("Resource worker was disabled."));
+      for (const request of this.#pending.values()) {
+        cleanupPendingRequest(request);
+        request.reject(error);
+      }
+      this.#pending.clear();
+    }
+    return this;
+  }
+
+  /**
+   * Clear a previous creation/fatal failure so a later enable can retry.
+   *
+   * @returns {CjsResManWorkerLoader} This loader.
+   */
+  Reset() {
+    this.failed = false;
+    this.enabled = true;
+    return this;
+  }
+
+  /**
+   * Replace the unsupported-operation fallback.
+   *
+   * @param {CjsResManMainThreadLoader|object} fallback Loader exposing Read and ReadFormat.
+   * @returns {CjsResManWorkerLoader} This loader.
+   */
+  SetFallback(fallback) {
+    assertResourceLoader(fallback, "fallback");
+    this.fallback = fallback;
+    return this;
+  }
+
+  /**
+   * Report whether worker execution is configured and constructible.
+   *
+   * @returns {boolean}
+   */
+  IsAvailable() {
+    return this.enabled && (Boolean(this.worker) || this.Enable());
+  }
+
+  /**
+   * Read a source through its declared worker request, falling back when the
+   * source is not worker-aware or a worker cannot be created.
+   *
+   * @param {object|Function} source Source implementation.
+   * @param {string} path Normalized resource path.
+   * @param {object} [options={}] Source options.
+   * @returns {Promise<*>|*} Source result.
+   */
+  Read(source, path, options = {}) {
+    assertResourceSource(source);
+    if (typeof source.CreateWorkerRequest !== "function") {
+      return this.fallback.Read(source, path, options);
+    }
+    const request = normalizeWorkerRequest(source.CreateWorkerRequest(path, options));
+    if (!request || !this.IsAvailable()) {
+      return this.fallback.Read(source, path, options);
+    }
+    return this.Execute(request.operation, request.payload, {
+      signal: request.signal || options.signal,
+      transfer: request.transfer
+    });
+  }
+
+  /**
+   * Test whether a registered format can be safely dispatched to this worker.
+   *
+   * @param {object} descriptor Registered format descriptor.
+   * @param {object} [formatOptions={}] Normalized format options.
+   * @returns {boolean}
+   */
+  CanReadFormat(descriptor, formatOptions = {}) {
+    const declaration = normalizeFormatWorkerDeclaration(descriptor);
+    return Boolean(declaration && isWorkerFormatOutputSupported(declaration, formatOptions) && canCloneWorkerValue(formatOptions) && this.IsAvailable());
+  }
+
+  /**
+   * Execute a worker-safe format reader or use the main-thread fallback.
+   *
+   * Inputs are cloned by default so shared source-cache ownership is not
+   * detached. A format may explicitly declare `transferInput: true` when its
+   * caller guarantees exclusive ownership.
+   *
+   * @param {object} descriptor Registered format descriptor.
+   * @param {*} input Reader input.
+   * @param {object} [formatOptions={}] Normalized format options.
+   * @returns {Promise<*>} Format result.
+   */
+  ReadFormat(descriptor, input, formatOptions = {}) {
+    const declaration = normalizeFormatWorkerDeclaration(descriptor);
+    if (!declaration || !isWorkerFormatOutputSupported(declaration, formatOptions) || !canCloneWorkerValue(formatOptions) || !this.IsAvailable()) {
+      return this.fallback.ReadFormat(descriptor, input, formatOptions);
+    }
+    const transfer = declaration.transferInput ? getExclusiveInputTransferables(input) : [];
+    return this.Execute(Operation.FORMAT_READ, {
+      module: declaration.module,
+      exportName: declaration.exportName,
+      input,
+      options: formatOptions
+    }, {
+      transfer
+    });
+  }
+
+  /**
+   * Dispatch one operation using the stable worker message protocol.
+   *
+   * @param {string} operation Operation name.
+   * @param {*} payload Structured-cloneable operation payload.
+   * @param {object} [options={}] Transfer and cancellation options.
+   * @returns {Promise<*>} Worker result.
+   */
+  Execute(operation, payload, options = {}) {
+    if (typeof operation !== "string" || operation.trim() === "") {
+      return Promise.reject(new TypeError("Worker operation must be a non-empty string."));
+    }
+    if (!this.IsAvailable()) {
+      return Promise.reject(createWorkerUnavailableError());
+    }
+    const signal = options.signal || null;
+    if (signal?.aborted) return Promise.reject(createAbortError(signal.reason));
+    const id = this.#nextId++;
+    let resolve;
+    let reject;
+    const promise = new Promise((onResolve, onReject) => {
+      resolve = onResolve;
+      reject = onReject;
+    });
+    const request = {
+      id,
+      resolve,
+      reject,
+      signal,
+      onAbort: null
+    };
+    if (signal && typeof signal.addEventListener === "function") {
+      request.onAbort = () => {
+        if (!this.#pending.delete(id)) return;
+        cleanupPendingRequest(request);
+        try {
+          this.worker?.postMessage({
+            type: Message.CANCEL,
+            id
+          });
+        } catch {
+          // The local abort remains authoritative if the worker is already gone.
+        }
+        reject(createAbortError(signal.reason));
+      };
+      signal.addEventListener("abort", request.onAbort, {
+        once: true
+      });
+    }
+    this.#pending.set(id, request);
+    try {
+      this.worker.postMessage({
+        type: Message.EXECUTE,
+        id,
+        operation,
+        payload
+      }, normalizeTransferList(options.transfer));
+    } catch (error) {
+      this.#pending.delete(id);
+      cleanupPendingRequest(request);
+      reject(error);
+    }
+    return promise;
+  }
+
+  /**
+   * Return the number of unresolved worker requests.
+   *
+   * @returns {number}
+   */
+  GetPendingCount() {
+    return this.#pending.size;
+  }
+
+  /** Attach this loader's result and failure listeners to a worker. */
+  #Attach(worker) {
+    if (typeof worker.addEventListener === "function") {
+      worker.addEventListener("message", this.#boundMessage);
+      worker.addEventListener("error", this.#boundError);
+      worker.addEventListener("messageerror", this.#boundError);
+    } else {
+      worker.onmessage = this.#boundMessage;
+      worker.onerror = this.#boundError;
+      worker.onmessageerror = this.#boundError;
+    }
+  }
+
+  /** Detach this loader's result and failure listeners from a worker. */
+  #Detach(worker) {
+    if (typeof worker.removeEventListener === "function") {
+      worker.removeEventListener("message", this.#boundMessage);
+      worker.removeEventListener("error", this.#boundError);
+      worker.removeEventListener("messageerror", this.#boundError);
+    } else {
+      if (worker.onmessage === this.#boundMessage) worker.onmessage = null;
+      if (worker.onerror === this.#boundError) worker.onerror = null;
+      if (worker.onmessageerror === this.#boundError) worker.onmessageerror = null;
+    }
+  }
+
+  /** Settle the pending request identified by one worker result message. */
+  #OnMessage(event) {
+    const data = event?.data;
+    if (!data || data.type !== Message.RESULT) return;
+    const request = this.#pending.get(data.id);
+    if (!request) return;
+    this.#pending.delete(data.id);
+    cleanupPendingRequest(request);
+    if (data.ok) request.resolve(data.result);else request.reject(normalizeWorkerError(data.error));
+  }
+
+  /** Disable worker execution after a fatal worker or message failure. */
+  #OnError(event) {
+    const reason = event?.error || event || new Error("Resource worker failed.");
+    this.Disable(reason);
+  }
+}
+function assertResourceSource(source) {
+  if (!source || typeof source !== "object" && typeof source !== "function" || typeof source.Read !== "function") {
+    throw new TypeError("Resource source must provide Read(path, options).");
+  }
+}
+function assertResourceLoader(loader, name = "loader") {
+  if (!loader || typeof loader.Read !== "function" || typeof loader.ReadFormat !== "function") {
+    throw new TypeError(`CjsResManWorkerLoader ${name} must provide Read and ReadFormat.`);
+  }
+}
+function defaultWorkerFactory(url, options) {
+  if (typeof Worker === "undefined") {
+    throw new ReferenceError("Browser Worker is not available.");
+  }
+  return new Worker(url, options);
+}
+function normalizeWorkerRequest(request) {
+  if (request === null || request === undefined || request === false) return null;
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    throw new TypeError("CreateWorkerRequest must return an object or null.");
+  }
+  if (typeof request.operation !== "string" || request.operation.trim() === "") {
+    throw new TypeError("Worker source request requires a non-empty operation.");
+  }
+  return {
+    operation: request.operation,
+    payload: request.payload,
+    signal: request.signal || null,
+    transfer: normalizeTransferList(request.transfer)
+  };
+}
+function normalizeFormatWorkerDeclaration(descriptor) {
+  const Format = descriptor?.Format;
+  const declaration = descriptor?.worker || Format?.worker;
+  if (!declaration) return null;
+  const value = typeof declaration === "string" ? {
+    module: declaration
+  } : declaration;
+  if (!value || typeof value !== "object" || !value.module) return null;
+  return Object.freeze({
+    module: String(value.module),
+    exportName: String(value.exportName || Format?.name || "default"),
+    outputTypes: Array.isArray(value.outputTypes) ? Object.freeze(value.outputTypes.map(String)) : null,
+    defaultOutput: value.defaultOutput === undefined ? undefined : String(value.defaultOutput),
+    transferInput: value.transferInput === true
+  });
+}
+function isWorkerFormatOutputSupported(declaration, formatOptions) {
+  if (!declaration.outputTypes) return true;
+  const output = formatOptions.emit ?? declaration.defaultOutput;
+  return output !== undefined && declaration.outputTypes.includes(String(output));
+}
+function normalizeTransferList(value) {
+  if (value === null || value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new TypeError("Worker transfer list must be an array.");
+  }
+  return value;
+}
+function getExclusiveInputTransferables(input) {
+  if (input instanceof ArrayBuffer) return [input];
+  if (ArrayBuffer.isView(input) && input.byteOffset === 0 && input.byteLength === input.buffer.byteLength) {
+    return [input.buffer];
+  }
+  return [];
+}
+function canCloneWorkerValue(value, seen = new Set()) {
+  if (value === null || value === undefined) return true;
+  const type = typeof value;
+  if (type === "string" || type === "number" || type === "boolean" || type === "bigint") {
+    return true;
+  }
+  if (type !== "object") return false;
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value) || value instanceof Date) {
+    return true;
+  }
+  if (seen.has(value)) return false;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.every(entry => canCloneWorkerValue(entry, seen));
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  return Object.values(value).every(entry => canCloneWorkerValue(entry, seen));
+}
+function cleanupPendingRequest(request) {
+  if (request.signal && request.onAbort && typeof request.signal.removeEventListener === "function") {
+    request.signal.removeEventListener("abort", request.onAbort);
+  }
+}
+function createWorkerUnavailableError(message = "Resource worker is unavailable.") {
+  const error = new Error(message);
+  error.name = "CjsResManWorkerUnavailableError";
+  error.code = "CJS_RESOURCE_WORKER_UNAVAILABLE";
+  return error;
+}
+function createAbortError(reason) {
+  if (reason instanceof Error) return reason;
+  const error = new Error(reason === undefined ? "Resource worker request was aborted." : String(reason));
+  error.name = "AbortError";
+  error.code = "ABORT_ERR";
+  return error;
+}
+function normalizeWorkerError(value) {
+  if (value instanceof Error) return value;
+  const error = new Error(value?.message || "Resource worker operation failed.");
+  error.name = value?.name || "CjsResManWorkerError";
+  for (const key of ["code", "operation", "path", "status", "statusText"]) {
+    if (value?.[key] !== undefined) error[key] = value[key];
+  }
+  return error;
+}
+
+export { CjsResManWorkerLoader };
+//# sourceMappingURL=CjsResManWorkerLoader.js.map