@spearwolf/shadow-objects 0.32.0 → 0.33.0

package/src/view/LocalShadowObjectEnv.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/view/LocalShadowObjectEnv.ts"],
-  "sourcesContent": ["import {on} from '@spearwolf/eventize';\nimport {MessageToView, ShadowObjectsExport} from '../constants.js';\nimport {importModule} from '../in-the-dark/importModule.js';\nimport {Kernel, type MessageToViewEvent} from '../in-the-dark/Kernel.js';\nimport type {Registry} from '../in-the-dark/Registry.js';\nimport type {ChangeTrailType, ShadowObjectsModule, SyncEvent} from '../types.js';\nimport {toUrlString} from '../utils/toUrlString.js';\nimport {cloneChangeTrail} from './cloneChangeTrail.js';\nimport type {IShadowObjectEnvProxy} from './IShadowObjectEnvProxy.js';\n\nexport class LocalShadowObjectEnv implements IShadowObjectEnvProxy {\n  #importedModules: Set<ShadowObjectsModule> = new Set();\n\n  readonly kernel: Kernel;\n\n  get registry(): Registry {\n    return this.kernel.registry;\n  }\n\n  readonly isLocalEnv = true;\n\n  disableStructuredClone = false;\n\n  constructor(registry?: Registry) {\n    this.kernel = new Kernel(registry);\n\n    on(this.kernel, MessageToView, (message: MessageToViewEvent) => {\n      if ((this as IShadowObjectEnvProxy).onMessageToView != null) {\n        const {type, uuid, traverseChildren} = message;\n        const data = structuredClone(message.data, {transfer: message.transferables});\n        (this as IShadowObjectEnvProxy).onMessageToView({type, uuid, data, traverseChildren});\n      }\n    });\n  }\n\n  start(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  applyChangeTrail(data: ChangeTrailType, _waitForConfirmation: boolean): Promise<void> {\n    const syncData: SyncEvent = {changeTrail: this.disableStructuredClone ? data : cloneChangeTrail(data)};\n    let result: Promise<void>;\n    try {\n      this.kernel.run(syncData);\n      result = Promise.resolve();\n    } catch (error) {\n      result = Promise.reject(error);\n    }\n    return result;\n  }\n\n  async importScript(url: URL | string): Promise<void> {\n    const module = await import(/* @vite-ignore */ toUrlString(url));\n    if (module[ShadowObjectsExport]) {\n      await this.importModule(module[ShadowObjectsExport]);\n    }\n  }\n\n  async importModule(module: ShadowObjectsModule): Promise<void> {\n    return importModule(this.kernel, module, this.#importedModules);\n  }\n\n  destroy(): void {\n    this.kernel.destroy();\n    this.registry.clear();\n    this.#importedModules.clear();\n  }\n}"],
-  "mappings": "AAAA,SAAQ,UAAS;AACjB,SAAQ,eAAe,2BAA0B;AACjD,SAAQ,oBAAmB;AAC3B,SAAQ,cAAsC;AAG9C,SAAQ,mBAAkB;AAC1B,SAAQ,wBAAuB;AAGxB,MAAM,qBAAsD;AAAA,EAajE,YAAY,UAAqB;AAZjC,4BAA6C,oBAAI,IAAI;AAQrD,SAAS,aAAa;AAEtB,kCAAyB;AAGvB,SAAK,SAAS,IAAI,OAAO,QAAQ;AAEjC,OAAG,KAAK,QAAQ,eAAe,CAAC,YAAgC;AAC9D,UAAK,KAA+B,mBAAmB,MAAM;AAC3D,cAAM,EAAC,MAAM,MAAM,iBAAgB,IAAI;AACvC,cAAM,OAAO,gBAAgB,QAAQ,MAAM,EAAC,UAAU,QAAQ,cAAa,CAAC;AAC5E,QAAC,KAA+B,gBAAgB,EAAC,MAAM,MAAM,MAAM,iBAAgB,CAAC;AAAA,MACtF;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAtBA;AAAA,EAIA,IAAI,WAAqB;AACvB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA,EAkBA,QAAuB;AACrB,WAAO,QAAQ,QAAQ;AAAA,EACzB;AAAA,EAEA,iBAAiB,MAAuB,sBAA8C;AACpF,UAAM,WAAsB,EAAC,aAAa,KAAK,yBAAyB,OAAO,iBAAiB,IAAI,EAAC;AACrG,QAAI;AACJ,QAAI;AACF,WAAK,OAAO,IAAI,QAAQ;AACxB,eAAS,QAAQ,QAAQ;AAAA,IAC3B,SAAS,OAAO;AACd,eAAS,QAAQ,OAAO,KAAK;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,aAAa,KAAkC;AACnD,UAAM,SAAS,MAAM;AAAA;AAAA,MAA0B,YAAY,GAAG;AAAA;AAC9D,QAAI,OAAO,mBAAmB,GAAG;AAC/B,YAAM,KAAK,aAAa,OAAO,mBAAmB,CAAC;AAAA,IACrD;AAAA,EACF;AAAA,EAEA,MAAM,aAAa,QAA4C;AAC7D,WAAO,aAAa,KAAK,QAAQ,QAAQ,KAAK,gBAAgB;AAAA,EAChE;AAAA,EAEA,UAAgB;AACd,SAAK,OAAO,QAAQ;AACpB,SAAK,SAAS,MAAM;AACpB,SAAK,iBAAiB,MAAM;AAAA,EAC9B;AACF;",
+  "sourcesContent": ["import {on} from '@spearwolf/eventize';\nimport {MessageToView, ShadowObjectsExport} from '../constants.js';\nimport {importModule} from '../in-the-dark/importModule.js';\nimport {Kernel, type MessageToViewEvent} from '../in-the-dark/Kernel.js';\nimport {Registry} from '../in-the-dark/Registry.js';\nimport type {ChangeTrailType, ShadowObjectsModule, SyncEvent} from '../types.js';\nimport {toUrlString} from '../utils/toUrlString.js';\nimport {cloneChangeTrail} from './cloneChangeTrail.js';\nimport type {IShadowObjectEnvProxy} from './IShadowObjectEnvProxy.js';\n\nexport class LocalShadowObjectEnv implements IShadowObjectEnvProxy {\n  #importedModules: Set<ShadowObjectsModule> = new Set();\n  readonly #usesDefaultRegistry: boolean;\n\n  readonly kernel: Kernel;\n\n  get registry(): Registry {\n    return this.kernel.registry;\n  }\n\n  readonly isLocalEnv = true;\n\n  disableStructuredClone = false;\n\n  constructor(registry?: Registry) {\n    this.kernel = new Kernel(registry);\n    // The default registry is shared with every other environment in this thread and holds\n    // everything `@ShadowObject` and `shadowObjects.define()` register without a registry of\n    // their own, so `destroy()` must not clear it. This check only tells the default registry\n    // apart from any other instance \u2014 a custom registry handed to more than one environment is\n    // cleared by the first one of them to be destroyed, same as the default registry would be\n    // without this guard.\n    this.#usesDefaultRegistry = this.kernel.registry === Registry.get();\n\n    on(this.kernel, MessageToView, (message: MessageToViewEvent) => {\n      const onMessageToView = (this as IShadowObjectEnvProxy).onMessageToView;\n      if (onMessageToView == null) return;\n\n      const {type, uuid, traverseChildren} = message;\n      const data = structuredClone(message.data, {transfer: message.transferables});\n      // call() keeps the binding a plain method call would have given it: an outside\n      // implementation of the proxy interface need not hand over a bound callback\n      onMessageToView.call(this, {type, uuid, data, traverseChildren});\n    });\n  }\n\n  start(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  applyChangeTrail(data: ChangeTrailType, _waitForConfirmation: boolean): Promise<void> {\n    const syncData: SyncEvent = {changeTrail: this.disableStructuredClone ? data : cloneChangeTrail(data)};\n    let result: Promise<void>;\n    try {\n      this.kernel.run(syncData);\n      result = Promise.resolve();\n    } catch (error) {\n      result = Promise.reject(error);\n    }\n    return result;\n  }\n\n  async importScript(url: URL | string): Promise<void> {\n    const module = await import(/* @vite-ignore */ toUrlString(url));\n    if (module[ShadowObjectsExport]) {\n      await this.importModule(module[ShadowObjectsExport]);\n    }\n  }\n\n  async importModule(module: ShadowObjectsModule): Promise<void> {\n    return importModule(this.kernel, module, this.#importedModules);\n  }\n\n  destroy(): void {\n    this.kernel.destroy();\n    if (!this.#usesDefaultRegistry) {\n      this.registry.clear();\n    }\n    this.#importedModules.clear();\n  }\n}"],
+  "mappings": "AAAA,SAAQ,UAAS;AACjB,SAAQ,eAAe,2BAA0B;AACjD,SAAQ,oBAAmB;AAC3B,SAAQ,cAAsC;AAC9C,SAAQ,gBAAe;AAEvB,SAAQ,mBAAkB;AAC1B,SAAQ,wBAAuB;AAGxB,MAAM,qBAAsD;AAAA,EAcjE,YAAY,UAAqB;AAbjC,4BAA6C,oBAAI,IAAI;AASrD,SAAS,aAAa;AAEtB,kCAAyB;AAGvB,SAAK,SAAS,IAAI,OAAO,QAAQ;AAOjC,SAAK,uBAAuB,KAAK,OAAO,aAAa,SAAS,IAAI;AAElE,OAAG,KAAK,QAAQ,eAAe,CAAC,YAAgC;AAC9D,YAAM,kBAAmB,KAA+B;AACxD,UAAI,mBAAmB,KAAM;AAE7B,YAAM,EAAC,MAAM,MAAM,iBAAgB,IAAI;AACvC,YAAM,OAAO,gBAAgB,QAAQ,MAAM,EAAC,UAAU,QAAQ,cAAa,CAAC;AAG5E,sBAAgB,KAAK,MAAM,EAAC,MAAM,MAAM,MAAM,iBAAgB,CAAC;AAAA,IACjE,CAAC;AAAA,EACH;AAAA,EAjCA;AAAA,EACS;AAAA,EAIT,IAAI,WAAqB;AACvB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA,EA4BA,QAAuB;AACrB,WAAO,QAAQ,QAAQ;AAAA,EACzB;AAAA,EAEA,iBAAiB,MAAuB,sBAA8C;AACpF,UAAM,WAAsB,EAAC,aAAa,KAAK,yBAAyB,OAAO,iBAAiB,IAAI,EAAC;AACrG,QAAI;AACJ,QAAI;AACF,WAAK,OAAO,IAAI,QAAQ;AACxB,eAAS,QAAQ,QAAQ;AAAA,IAC3B,SAAS,OAAO;AACd,eAAS,QAAQ,OAAO,KAAK;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,aAAa,KAAkC;AACnD,UAAM,SAAS,MAAM;AAAA;AAAA,MAA0B,YAAY,GAAG;AAAA;AAC9D,QAAI,OAAO,mBAAmB,GAAG;AAC/B,YAAM,KAAK,aAAa,OAAO,mBAAmB,CAAC;AAAA,IACrD;AAAA,EACF;AAAA,EAEA,MAAM,aAAa,QAA4C;AAC7D,WAAO,aAAa,KAAK,QAAQ,QAAQ,KAAK,gBAAgB;AAAA,EAChE;AAAA,EAEA,UAAgB;AACd,SAAK,OAAO,QAAQ;AACpB,QAAI,CAAC,KAAK,sBAAsB;AAC9B,WAAK,SAAS,MAAM;AAAA,IACtB;AACA,SAAK,iBAAiB,MAAM;AAAA,EAC9B;AACF;",
   "names": []
 }

package/src/view/RemoteWorkerEnv.d.ts

@@ -1,17 +1,59 @@
 import type { ChangeTrailType } from '../types.js';
 import { ConsoleLogger } from '../utils/ConsoleLogger.js';
 import type { IShadowObjectEnvProxy } from './IShadowObjectEnvProxy.js';
+/**
+ * The reason every pending and every later worker request is rejected with
+ * once the worker has failed.
+ */
+export declare class WorkerFailedError extends Error {
+    /** `'error'` when the worker itself threw, `'messageerror'` when it sent something that could not be deserialized. */
+    readonly type: 'error' | 'messageerror';
+    constructor(type: 'error' | 'messageerror', message: string, options?: ErrorOptions);
+}
+/**
+ * The reason a request is rejected with once the environment has been torn down
+ * with {@link RemoteWorkerEnv.destroy}. The worker is gone; no reply can arrive.
+ */
+export declare class WorkerDestroyedError extends Error {
+    constructor(message?: string);
+}
+/** What {@link RemoteWorkerEnv.WorkerFailed} carries. */
+export interface WorkerFailedEvent {
+    /** the environment whose worker failed */
+    env: RemoteWorkerEnv;
+    /** what the worker reported */
+    type: 'error' | 'messageerror';
+    /** a readable description of the failure */
+    message: string;
+    /** the error every pending and every later request is rejected with */
+    reason: WorkerFailedError;
+    /** the worker event the failure was read from */
+    event: ErrorEvent | MessageEvent;
+}
 export declare class RemoteWorkerEnv implements IShadowObjectEnvProxy {
     #private;
     static WorkerLoaded: string;
+    static WorkerFailed: string;
     readonly logger: ConsoleLogger;
     get isDestroyed(): boolean;
+    /**
+     * Resolves once the worker is up.
+     *
+     * Every read hands out a promise that can reject, so a caller that only wants to
+     * kick the environment off and never awaits the result should still attach a
+     * `catch()` — otherwise a worker failure surfaces as an unhandled rejection.
+     *
+     * @throws {WorkerFailedError} if the worker fails before or after that happens
+     */
     get workerLoaded(): Promise<RemoteWorkerEnv>;
     constructor();
     start(): Promise<void>;
     applyChangeTrail(changeTrail: ChangeTrailType, waitForConfirmation: boolean): Promise<void>;
     importScript(url: URL | string): Promise<void>;
     destroy(): void;
+    private onWorkerError;
+    private onWorkerMessageError;
+    private handleWorkerFailure;
     private onMessageFromWorker;
     private configureConsoleLogger;
 }

package/src/view/RemoteWorkerEnv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RemoteWorkerEnv.d.ts","sourceRoot":"","sources":["../../../src/view/RemoteWorkerEnv.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAA0B,eAAe,EAAyC,MAAM,aAAa,CAAC;AAClH,OAAO,EAAiB,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAGxE,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAqBtE,qBAAa,eAAgB,YAAW,qBAAqB;;IAC3D,MAAM,CAAC,YAAY,SAAkB;IAMrC,QAAQ,CAAC,MAAM,gBAAwC;IAEvD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC,CAE3C;;IAMK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqC5B,gBAAgB,CAAC,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB3F,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,sBAAsB;CAkB/B"}
+{"version":3,"file":"RemoteWorkerEnv.d.ts","sourceRoot":"","sources":["../../../src/view/RemoteWorkerEnv.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAA0B,eAAe,EAAyC,MAAM,aAAa,CAAC;AAClH,OAAO,EAAiB,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAGxE,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAqBtE;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,sHAAsH;IACtH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;gBAE5B,IAAI,EAAE,OAAO,GAAG,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpF;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,SAA8C;CAIlE;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,GAAG,EAAE,eAAe,CAAC;IACrB,+BAA+B;IAC/B,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IAC/B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,iBAAiB,CAAC;IAC1B,iDAAiD;IACjD,KAAK,EAAE,UAAU,GAAG,YAAY,CAAC;CAClC;AAED,qBAAa,eAAgB,YAAW,qBAAqB;;IAC3D,MAAM,CAAC,YAAY,SAAkB;IACrC,MAAM,CAAC,YAAY,SAAkB;IAYrC,QAAQ,CAAC,MAAM,gBAAwC;IAEvD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;;;;OAQG;IACH,IAAI,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC,CA4B3C;;IAQK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiE5B,gBAAgB,CAAC,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC3F,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB9C,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,mBAAmB;IAsC3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,sBAAsB;CAkB/B"}

package/src/view/RemoteWorkerEnv.js

@@ -1,4 +1,4 @@
-import { emit, onceAsync, retain } from "@spearwolf/eventize";
+import { emit, once, retain } from "@spearwolf/eventize";
 import {
   AppliedChangeTrail,
   ChangeTrail,
@@ -33,78 +33,158 @@ const removeTransferables = (changeTrail) => {
   }
   return transferables;
 };
+class WorkerFailedError extends Error {
+  constructor(type, message, options) {
+    super(message, options);
+    this.name = "WorkerFailedError";
+    this.type = type;
+  }
+}
+class WorkerDestroyedError extends Error {
+  constructor(message = "the worker environment has been destroyed") {
+    super(message);
+    this.name = "WorkerDestroyedError";
+  }
+}
 class RemoteWorkerEnv {
   constructor() {
     this.#isDestroyed = false;
     this.#changeTrailSerial = 0;
+    /**
+     * Aborted exactly once, with the {@link WorkerFailedError} that describes the failure.
+     * It settles every request already waiting for a reply and turns away every later one.
+     */
+    this.#workerFailure = new AbortController();
     this.logger = new ConsoleLogger("RemoteWorkerEnv");
     retain(this, RemoteWorkerEnv.WorkerLoaded);
+    retain(this, RemoteWorkerEnv.WorkerFailed);
   }
   static {
     this.WorkerLoaded = "workerLoaded";
   }
+  static {
+    this.WorkerFailed = "workerFailed";
+  }
   #worker;
   #isDestroyed;
   #changeTrailSerial;
+  #workerFailure;
   get isDestroyed() {
     return this.#isDestroyed;
   }
+  /**
+   * Resolves once the worker is up.
+   *
+   * Every read hands out a promise that can reject, so a caller that only wants to
+   * kick the environment off and never awaits the result should still attach a
+   * `catch()` — otherwise a worker failure surfaces as an unhandled rejection.
+   *
+   * @throws {WorkerFailedError} if the worker fails before or after that happens
+   */
   get workerLoaded() {
-    return onceAsync(this, RemoteWorkerEnv.WorkerLoaded);
+    const { signal } = this.#workerFailure;
+    if (signal.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      let unsubscribeLoaded;
+      let settled = false;
+      const onFailure = () => {
+        if (settled) return;
+        settled = true;
+        unsubscribeLoaded?.();
+        reject(signal.reason);
+      };
+      unsubscribeLoaded = once(this, RemoteWorkerEnv.WorkerLoaded, (env) => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", onFailure);
+        resolve(env);
+      });
+      if (settled) return;
+      signal.addEventListener("abort", onFailure, { once: true });
+    });
   }
   async start() {
+    const { signal } = this.#workerFailure;
+    if (signal.aborted) throw signal.reason;
+    if (this.#isDestroyed) throw new WorkerDestroyedError();
     if (this.#worker) {
       if (this.logger.isWarn) {
         this.logger.warn("already started");
       }
       return this.workerLoaded.then(() => {
         if (this.isDestroyed) {
-          throw "worker was destroyed";
+          throw new WorkerDestroyedError();
         }
-        return void 0;
       });
     }
     const worker = this.#worker = createWorker();
+    worker.addEventListener("error", this.onWorkerError.bind(this));
+    worker.addEventListener("messageerror", this.onWorkerMessageError.bind(this));
     this.configureConsoleLogger(worker);
     try {
-      await waitForMessageOfType(worker, Loaded, WorkerLoadTimeout);
+      await waitForMessageOfType(worker, Loaded, WorkerLoadTimeout, void 0, signal);
       if (this.isDestroyed) {
-        throw "worker was destroyed";
+        throw new WorkerDestroyedError();
       }
       worker.addEventListener("message", this.onMessageFromWorker.bind(this));
       queueMicrotask(() => {
         emit(this, RemoteWorkerEnv.WorkerLoaded, this);
       });
     } catch (error) {
-      this.logger.error("failed to start", error);
+      if (error !== signal.reason) {
+        this.logger.error("failed to start", error);
+      }
       this.#worker = void 0;
+      if (!this.#isDestroyed) {
+        worker.terminate();
+      }
       throw error;
     }
   }
   applyChangeTrail(changeTrail, waitForConfirmation) {
+    const { signal } = this.#workerFailure;
+    if (signal.aborted) return Promise.reject(signal.reason);
+    const worker = this.#worker;
+    if (worker == null) return Promise.reject(new WorkerDestroyedError());
     const transferables = removeTransferables(changeTrail);
     const message = { type: ChangeTrail, changeTrail };
     const serial = ++this.#changeTrailSerial;
     if (waitForConfirmation) {
       message.serial = serial;
     }
-    this.#worker.postMessage(message, transferables);
+    worker.postMessage(message, transferables ?? []);
     if (waitForConfirmation) {
-      return waitForMessageOfType(this.#worker, AppliedChangeTrail, WorkerChangeTrailTimeout, (data) => {
-        if (data.error) throw data.error;
-        return data.serial === serial;
-      });
+      return waitForMessageOfType(
+        worker,
+        AppliedChangeTrail,
+        WorkerChangeTrailTimeout,
+        (data) => {
+          if (data.error) throw data.error;
+          return data.serial === serial;
+        },
+        signal
+      );
     } else {
       return Promise.resolve();
     }
   }
   importScript(url) {
+    const { signal } = this.#workerFailure;
+    if (signal.aborted) return Promise.reject(signal.reason);
+    const worker = this.#worker;
+    if (worker == null) return Promise.reject(new WorkerDestroyedError());
     url = toUrlString(url);
-    this.#worker.postMessage({ type: Configure, importModule: url });
-    return waitForMessageOfType(this.#worker, ImportedModule, WorkerConfigureTimeout, (data) => {
-      if (data.error) throw data.error;
-      return data.url === url;
-    });
+    worker.postMessage({ type: Configure, importModule: url });
+    return waitForMessageOfType(
+      worker,
+      ImportedModule,
+      WorkerConfigureTimeout,
+      (data) => {
+        if (data.error) throw data.error;
+        return data.url === url;
+      },
+      signal
+    );
   }
   destroy() {
     if (!this.#worker) return;
@@ -116,6 +196,36 @@ class RemoteWorkerEnv {
       worker.terminate();
     });
   }
+  onWorkerError(event) {
+    this.handleWorkerFailure("error", event, event.message || "the worker reported an error");
+  }
+  onWorkerMessageError(event) {
+    this.handleWorkerFailure("messageerror", event, "the worker sent a message that could not be deserialized");
+  }
+  handleWorkerFailure(type, event, message) {
+    if (this.#isDestroyed) return;
+    this.#isDestroyed = true;
+    const reason = new WorkerFailedError(type, message, {
+      cause: type === "error" ? event.error ?? event : event
+    });
+    this.logger.error(message, event);
+    const worker = this.#worker;
+    this.#worker = void 0;
+    this.#workerFailure.abort(reason);
+    worker?.terminate();
+    try {
+      this.onProxyFailed?.(reason);
+    } catch (error) {
+      this.logger.error("the proxy-failed callback threw", error);
+    }
+    emit(this, RemoteWorkerEnv.WorkerFailed, {
+      env: this,
+      type,
+      message,
+      reason,
+      event
+    });
+  }
   onMessageFromWorker(event) {
     if (event.data?.type === MessageToView) {
       this.onMessageToView?.(event.data.data);
@@ -141,6 +251,8 @@ class RemoteWorkerEnv {
   }
 }
 export {
-  RemoteWorkerEnv
+  RemoteWorkerEnv,
+  WorkerDestroyedError,
+  WorkerFailedError
 };
 //# sourceMappingURL=RemoteWorkerEnv.js.map

package/src/view/RemoteWorkerEnv.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/view/RemoteWorkerEnv.ts"],
-  "sourcesContent": ["import {emit, onceAsync, retain} from '@spearwolf/eventize';\nimport {\n  AppliedChangeTrail,\n  ChangeTrail,\n  Configure,\n  Destroy,\n  Destroyed,\n  ImportedModule,\n  Loaded,\n  MessageToView,\n  WorkerChangeTrailTimeout,\n  WorkerConfigureTimeout,\n  WorkerDestroyTimeout,\n  WorkerLoadTimeout,\n} from '../constants.js';\nimport createWorker from '../create-worker.js';\nimport type {AppliedChangeTrailEvent, ChangeTrailType, ImportedModuleEvent, TransferablesType} from '../types.js';\nimport {CONSOLE_LOGGER, ConsoleLogger} from '../utils/ConsoleLogger.js';\nimport {toUrlString} from '../utils/toUrlString.js';\nimport {waitForMessageOfType} from '../utils/waitForMessageOfType.js';\nimport type {IShadowObjectEnvProxy} from './IShadowObjectEnvProxy.js';\n\nconst removeTransferables = (changeTrail: ChangeTrailType): TransferablesType | undefined => {\n  let transferables: TransferablesType | undefined;\n\n  if (changeTrail != null && Array.isArray(changeTrail)) {\n    for (const changeItem of changeTrail) {\n      if (changeItem.transferables) {\n        if (!transferables) {\n          transferables = changeItem.transferables;\n        } else {\n          transferables = [...transferables, ...changeItem.transferables];\n        }\n        delete changeItem.transferables;\n      }\n    }\n  }\n\n  return transferables;\n};\n\nexport class RemoteWorkerEnv implements IShadowObjectEnvProxy {\n  static WorkerLoaded = 'workerLoaded';\n\n  #worker?: Worker;\n  #isDestroyed = false;\n  #changeTrailSerial = 0;\n\n  readonly logger = new ConsoleLogger('RemoteWorkerEnv');\n\n  get isDestroyed(): boolean {\n    return this.#isDestroyed;\n  }\n\n  get workerLoaded(): Promise<RemoteWorkerEnv> {\n    return onceAsync<RemoteWorkerEnv>(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded);\n  }\n\n  constructor() {\n    retain(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded);\n  }\n\n  async start(): Promise<void> {\n    if (this.#worker) {\n      if (this.logger.isWarn) {\n        this.logger.warn('already started');\n      }\n\n      return this.workerLoaded.then((): void => {\n        if (this.isDestroyed) {\n          throw 'worker was destroyed';\n        }\n        return undefined;\n      });\n    }\n\n    const worker = (this.#worker = createWorker());\n\n    this.configureConsoleLogger(worker);\n\n    try {\n      await waitForMessageOfType(worker, Loaded, WorkerLoadTimeout);\n\n      if (this.isDestroyed) {\n        throw 'worker was destroyed';\n      }\n\n      worker.addEventListener('message', this.onMessageFromWorker.bind(this));\n\n      queueMicrotask(() => {\n        emit(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, this);\n      });\n    } catch (error) {\n      this.logger.error('failed to start', error);\n      this.#worker = undefined;\n      throw error;\n    }\n  }\n\n  applyChangeTrail(changeTrail: ChangeTrailType, waitForConfirmation: boolean): Promise<void> {\n    const transferables = removeTransferables(changeTrail);\n    const message = {type: ChangeTrail, changeTrail} as any;\n\n    const serial = ++this.#changeTrailSerial;\n    if (waitForConfirmation) {\n      message.serial = serial;\n    }\n\n    this.#worker.postMessage(message, transferables);\n\n    if (waitForConfirmation) {\n      return waitForMessageOfType(this.#worker, AppliedChangeTrail, WorkerChangeTrailTimeout, (data: AppliedChangeTrailEvent) => {\n        if (data.error) throw data.error;\n        return data.serial === serial;\n      });\n    } else {\n      return Promise.resolve();\n    }\n  }\n\n  importScript(url: URL | string): Promise<void> {\n    url = toUrlString(url);\n    this.#worker.postMessage({type: Configure, importModule: url});\n    return waitForMessageOfType(this.#worker, ImportedModule, WorkerConfigureTimeout, (data: ImportedModuleEvent) => {\n      if (data.error) throw data.error;\n      return data.url === url;\n    });\n  }\n\n  destroy(): void {\n    if (!this.#worker) return;\n\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    this.#isDestroyed = true;\n\n    worker.postMessage({type: Destroy});\n\n    waitForMessageOfType(worker, Destroyed, WorkerDestroyTimeout).finally(() => {\n      worker.terminate();\n    });\n  }\n\n  private onMessageFromWorker(event: MessageEvent) {\n    if (event.data?.type === MessageToView) {\n      (this as IShadowObjectEnvProxy).onMessageToView?.(event.data.data);\n    } else if (this.logger.isDebug) {\n      this.logger.debug('message from worker', event);\n    }\n  }\n\n  private configureConsoleLogger(worker: Worker) {\n    const workerConfigKey = `${CONSOLE_LOGGER}.RemoteWorkerEnv.workerConfig`;\n    const workerConfig = JSON.parse(localStorage.getItem(workerConfigKey) ?? '{}');\n\n    if (this.logger.isInfo) {\n      this.logger.info('load console-logger worker config', {localStorageKey: workerConfigKey, workerConfig});\n    }\n\n    worker.postMessage({\n      type: CONSOLE_LOGGER,\n      config: {\n        ...ConsoleLogger.sharedConfig,\n        enable: this.logger.isEnabled,\n        ...workerConfig,\n        ...(ConsoleLogger.isEnabled ? {} : {enable: false}),\n      },\n    });\n  }\n}"],
-  "mappings": "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",
+  "sourcesContent": ["import {emit, once, retain} from '@spearwolf/eventize';\nimport {\n  AppliedChangeTrail,\n  ChangeTrail,\n  Configure,\n  Destroy,\n  Destroyed,\n  ImportedModule,\n  Loaded,\n  MessageToView,\n  WorkerChangeTrailTimeout,\n  WorkerConfigureTimeout,\n  WorkerDestroyTimeout,\n  WorkerLoadTimeout,\n} from '../constants.js';\nimport createWorker from '../create-worker.js';\nimport type {AppliedChangeTrailEvent, ChangeTrailType, ImportedModuleEvent, TransferablesType} from '../types.js';\nimport {CONSOLE_LOGGER, ConsoleLogger} from '../utils/ConsoleLogger.js';\nimport {toUrlString} from '../utils/toUrlString.js';\nimport {waitForMessageOfType} from '../utils/waitForMessageOfType.js';\nimport type {IShadowObjectEnvProxy} from './IShadowObjectEnvProxy.js';\n\nconst removeTransferables = (changeTrail: ChangeTrailType): TransferablesType | undefined => {\n  let transferables: TransferablesType | undefined;\n\n  if (changeTrail != null && Array.isArray(changeTrail)) {\n    for (const changeItem of changeTrail) {\n      if (changeItem.transferables) {\n        if (!transferables) {\n          transferables = changeItem.transferables;\n        } else {\n          transferables = [...transferables, ...changeItem.transferables];\n        }\n        delete changeItem.transferables;\n      }\n    }\n  }\n\n  return transferables;\n};\n\n/**\n * The reason every pending and every later worker request is rejected with\n * once the worker has failed.\n */\nexport class WorkerFailedError extends Error {\n  /** `'error'` when the worker itself threw, `'messageerror'` when it sent something that could not be deserialized. */\n  readonly type: 'error' | 'messageerror';\n\n  constructor(type: 'error' | 'messageerror', message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'WorkerFailedError';\n    this.type = type;\n  }\n}\n\n/**\n * The reason a request is rejected with once the environment has been torn down\n * with {@link RemoteWorkerEnv.destroy}. The worker is gone; no reply can arrive.\n */\nexport class WorkerDestroyedError extends Error {\n  constructor(message = 'the worker environment has been destroyed') {\n    super(message);\n    this.name = 'WorkerDestroyedError';\n  }\n}\n\n/** What {@link RemoteWorkerEnv.WorkerFailed} carries. */\nexport interface WorkerFailedEvent {\n  /** the environment whose worker failed */\n  env: RemoteWorkerEnv;\n  /** what the worker reported */\n  type: 'error' | 'messageerror';\n  /** a readable description of the failure */\n  message: string;\n  /** the error every pending and every later request is rejected with */\n  reason: WorkerFailedError;\n  /** the worker event the failure was read from */\n  event: ErrorEvent | MessageEvent;\n}\n\nexport class RemoteWorkerEnv implements IShadowObjectEnvProxy {\n  static WorkerLoaded = 'workerLoaded';\n  static WorkerFailed = 'workerFailed';\n\n  #worker?: Worker;\n  #isDestroyed = false;\n  #changeTrailSerial = 0;\n\n  /**\n   * Aborted exactly once, with the {@link WorkerFailedError} that describes the failure.\n   * It settles every request already waiting for a reply and turns away every later one.\n   */\n  readonly #workerFailure = new AbortController();\n\n  readonly logger = new ConsoleLogger('RemoteWorkerEnv');\n\n  get isDestroyed(): boolean {\n    return this.#isDestroyed;\n  }\n\n  /**\n   * Resolves once the worker is up.\n   *\n   * Every read hands out a promise that can reject, so a caller that only wants to\n   * kick the environment off and never awaits the result should still attach a\n   * `catch()` \u2014 otherwise a worker failure surfaces as an unhandled rejection.\n   *\n   * @throws {WorkerFailedError} if the worker fails before or after that happens\n   */\n  get workerLoaded(): Promise<RemoteWorkerEnv> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    return new Promise<RemoteWorkerEnv>((resolve, reject) => {\n      let unsubscribeLoaded: (() => void) | undefined;\n      let settled = false;\n\n      const onFailure = () => {\n        if (settled) return;\n        settled = true;\n        unsubscribeLoaded?.();\n        reject(signal.reason);\n      };\n\n      unsubscribeLoaded = once(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, (env: RemoteWorkerEnv) => {\n        if (settled) return;\n        settled = true;\n        signal.removeEventListener('abort', onFailure);\n        resolve(env);\n      });\n\n      // a retained WorkerLoaded is replayed inside once(), before it returns \u2014\n      // then there is nothing left to wait for and no abort listener to attach\n      if (settled) return;\n\n      signal.addEventListener('abort', onFailure, {once: true});\n    });\n  }\n\n  constructor() {\n    retain(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded);\n    // a consumer that subscribes only after the failure still gets to hear about it\n    retain(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerFailed);\n  }\n\n  async start(): Promise<void> {\n    // both guards are needed, and in this order: a failure aborts the signal *and* marks the\n    // environment destroyed, so asking about the teardown first would bury the more precise\n    // reason \u2014 while a teardown leaves the signal untouched and would slip past it\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) throw signal.reason;\n\n    // a torn-down environment must not spawn a worker: nothing would ever reach it, and\n    // nothing would ever shut it down again\n    if (this.#isDestroyed) throw new WorkerDestroyedError();\n\n    if (this.#worker) {\n      if (this.logger.isWarn) {\n        this.logger.warn('already started');\n      }\n\n      return this.workerLoaded.then((): void => {\n        if (this.isDestroyed) {\n          throw new WorkerDestroyedError();\n        }\n      });\n    }\n\n    const worker = (this.#worker = createWorker());\n\n    // registered before the load handshake begins: a worker that dies while it is\n    // still coming up must not leave the caller waiting for the load timeout\n    worker.addEventListener('error', this.onWorkerError.bind(this));\n    worker.addEventListener('messageerror', this.onWorkerMessageError.bind(this));\n\n    this.configureConsoleLogger(worker);\n\n    try {\n      await waitForMessageOfType(worker, Loaded, WorkerLoadTimeout, undefined, signal);\n\n      if (this.isDestroyed) {\n        throw new WorkerDestroyedError();\n      }\n\n      worker.addEventListener('message', this.onMessageFromWorker.bind(this));\n\n      queueMicrotask(() => {\n        emit(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, this);\n      });\n    } catch (error) {\n      // the failure path reports with the worker event in hand; anything else is on us\n      if (error !== signal.reason) {\n        this.logger.error('failed to start', error);\n      }\n\n      this.#worker = undefined;\n\n      // only a start that nobody else is unwinding owns this worker: the reference is gone,\n      // nobody can reach it any more, and leaving it running would keep a thread open for an\n      // environment that never started. A failure has already terminated it, and a teardown\n      // in flight is waiting for its Destroyed reply \u2014 cutting that short here would leave\n      // destroy() to sit out its timeout and skip the worker-side teardown entirely.\n      if (!this.#isDestroyed) {\n        worker.terminate();\n      }\n\n      throw error;\n    }\n  }\n\n  applyChangeTrail(changeTrail: ChangeTrailType, waitForConfirmation: boolean): Promise<void> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    const worker = this.#worker;\n    if (worker == null) return Promise.reject(new WorkerDestroyedError());\n\n    const transferables = removeTransferables(changeTrail);\n    const message = {type: ChangeTrail, changeTrail} as any;\n\n    const serial = ++this.#changeTrailSerial;\n    if (waitForConfirmation) {\n      message.serial = serial;\n    }\n\n    worker.postMessage(message, transferables ?? []);\n\n    if (waitForConfirmation) {\n      return waitForMessageOfType(\n        worker,\n        AppliedChangeTrail,\n        WorkerChangeTrailTimeout,\n        (data: AppliedChangeTrailEvent) => {\n          if (data.error) throw data.error;\n          return data.serial === serial;\n        },\n        signal,\n      );\n    } else {\n      return Promise.resolve();\n    }\n  }\n\n  importScript(url: URL | string): Promise<void> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    const worker = this.#worker;\n    if (worker == null) return Promise.reject(new WorkerDestroyedError());\n\n    url = toUrlString(url);\n    worker.postMessage({type: Configure, importModule: url});\n    return waitForMessageOfType(\n      worker,\n      ImportedModule,\n      WorkerConfigureTimeout,\n      (data: ImportedModuleEvent) => {\n        if (data.error) throw data.error;\n        return data.url === url;\n      },\n      signal,\n    );\n  }\n\n  destroy(): void {\n    if (!this.#worker) return;\n\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    this.#isDestroyed = true;\n\n    worker.postMessage({type: Destroy});\n\n    waitForMessageOfType(worker, Destroyed, WorkerDestroyTimeout).finally(() => {\n      worker.terminate();\n    });\n  }\n\n  private onWorkerError(event: ErrorEvent) {\n    this.handleWorkerFailure('error', event, event.message || 'the worker reported an error');\n  }\n\n  private onWorkerMessageError(event: MessageEvent) {\n    this.handleWorkerFailure('messageerror', event, 'the worker sent a message that could not be deserialized');\n  }\n\n  private handleWorkerFailure(type: 'error' | 'messageerror', event: ErrorEvent | MessageEvent, message: string): void {\n    // a deliberate teardown, or a failure that was already reported: the first one wins\n    if (this.#isDestroyed) return;\n\n    this.#isDestroyed = true;\n\n    const reason = new WorkerFailedError(type, message, {\n      cause: type === 'error' ? ((event as ErrorEvent).error ?? event) : event,\n    });\n\n    this.logger.error(message, event);\n\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    // settle everyone waiting for a reply before the worker goes away \u2014 it can no longer arrive\n    this.#workerFailure.abort(reason);\n\n    worker?.terminate();\n\n    // the ShadowEnv is told first, so that the state it derives from this is already\n    // settled when consumers hear about it. Whatever happens down that path stays\n    // there \u2014 the public event is announced either way\n    try {\n      (this as IShadowObjectEnvProxy).onProxyFailed?.(reason);\n    } catch (error) {\n      this.logger.error('the proxy-failed callback threw', error);\n    }\n\n    emit(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerFailed, {\n      env: this,\n      type,\n      message,\n      reason,\n      event,\n    } as WorkerFailedEvent);\n  }\n\n  private onMessageFromWorker(event: MessageEvent) {\n    if (event.data?.type === MessageToView) {\n      (this as IShadowObjectEnvProxy).onMessageToView?.(event.data.data);\n    } else if (this.logger.isDebug) {\n      this.logger.debug('message from worker', event);\n    }\n  }\n\n  private configureConsoleLogger(worker: Worker) {\n    const workerConfigKey = `${CONSOLE_LOGGER}.RemoteWorkerEnv.workerConfig`;\n    const workerConfig = JSON.parse(localStorage.getItem(workerConfigKey) ?? '{}');\n\n    if (this.logger.isInfo) {\n      this.logger.info('load console-logger worker config', {localStorageKey: workerConfigKey, workerConfig});\n    }\n\n    worker.postMessage({\n      type: CONSOLE_LOGGER,\n      config: {\n        ...ConsoleLogger.sharedConfig,\n        enable: this.logger.isEnabled,\n        ...workerConfig,\n        ...(ConsoleLogger.isEnabled ? {} : {enable: false}),\n      },\n    });\n  }\n}"],
+  "mappings": "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",
   "names": []
 }

package/src/view/ShadowEnv.d.ts

@@ -5,14 +5,22 @@ import type { IShadowObjectEnvProxy } from './IShadowObjectEnvProxy.js';
 declare global {
     var __shadowEnvs: Map<NamespaceType, ShadowEnv> | undefined;
 }
+/**
+ * The reason every pending {@link ShadowEnv.ready} and {@link ShadowEnv.syncWait} promise
+ * is rejected with when the environment is destroyed.
+ */
+export declare class ShadowEnvDestroyedError extends Error {
+    constructor(message?: string);
+}
 export declare class ShadowEnv {
     #private;
     static AfterSync: string;
     static ContextLost: string;
     static ContextCreated: string;
+    static ProxyFailed: string;
     static get(ns: NamespaceType): ShadowEnv | undefined;
     readonly logger: ConsoleLogger;
-    readonly ns$: import("@spearwolf/signalize").Signal<NamespaceType>;
+    readonly ns$: import("@spearwolf/signalize").Signal<NamespaceType | undefined>;
     accessor viewReady: boolean;
     accessor proxyReady: boolean;
     get isDestroyed(): boolean;
@@ -22,9 +30,25 @@ export declare class ShadowEnv {
     get envProxy(): IShadowObjectEnvProxy | undefined;
     set envProxy(proxy: IShadowObjectEnvProxy | null | undefined);
     get isReady(): boolean;
+    /**
+     * Resolves once the environment is ready.
+     *
+     * @throws {ShadowEnvDestroyedError} if the environment is destroyed before that happens
+     */
     readonly ready: () => Promise<ShadowEnv>;
     sync(): void;
+    /**
+     * Like {@link ShadowEnv.sync}, but resolves with the change trail once the cycle completed.
+     *
+     * @throws {ShadowEnvDestroyedError} if the environment is destroyed before that happens
+     */
     syncWait(): Promise<ChangeTrailType>;
+    /**
+     * Tear the environment down: the proxy is destroyed, the namespace is released, all signals
+     * and listeners are removed, and every caller still waiting on {@link ShadowEnv.ready} or
+     * {@link ShadowEnv.syncWait} is rejected with a {@link ShadowEnvDestroyedError} instead of
+     * being left pending forever. Calling it more than once is a no-op.
+     */
     destroy(): void;
 }
 //# sourceMappingURL=ShadowEnv.d.ts.map

package/src/view/ShadowEnv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadowEnv.d.ts","sourceRoot":"","sources":["../../../src/view/ShadowEnv.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,eAAe,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC;AAChE,OAAO,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAEtE,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED,qBAAa,SAAS;;IACpB,MAAM,CAAC,SAAS,SAAe;IAC/B,MAAM,CAAC,WAAW,SAAiB;IACnC,MAAM,CAAC,cAAc,SAAoB;IAEzC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS;IAYpD,QAAQ,CAAC,MAAM,gBAAkC;IAEjD,QAAQ,CAAC,GAAG,uDAA6C;IAE/C,QAAQ,CAAC,SAAS,UAAS;IAC3B,QAAQ,CAAC,UAAU,UAAS;IAItC,IAAI,WAAW,YAEd;;IAyBD,IAAI,IAAI,IAAI,gBAAgB,GAAG,SAAS,CAEvC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAwBhD;IAED,IAAI,QAAQ,IAAI,qBAAqB,GAAG,SAAS,CAEhD;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EAyB3D;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,QAAQ,CAAC,KAAK,QAAa,OAAO,CAAC,SAAS,CAAC,CAE3C;IAEF,IAAI,IAAI,IAAI;IAUZ,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;IAWpC,OAAO;CAoDR"}
+{"version":3,"file":"ShadowEnv.d.ts","sourceRoot":"","sources":["../../../src/view/ShadowEnv.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,eAAe,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC;AAChE,OAAO,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAEtE,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,SAA8C;CAIlE;AAED,qBAAa,SAAS;;IACpB,MAAM,CAAC,SAAS,SAAe;IAC/B,MAAM,CAAC,WAAW,SAAiB;IACnC,MAAM,CAAC,cAAc,SAAoB;IACzC,MAAM,CAAC,WAAW,SAAiB;IAEnC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS;IAYpD,QAAQ,CAAC,MAAM,gBAAkC;IAEjD,QAAQ,CAAC,GAAG,mEAA6C;IAE/C,QAAQ,CAAC,SAAS,UAAS;IAC3B,QAAQ,CAAC,UAAU,UAAS;IAItC,IAAI,WAAW,YAEd;;IA2BD,IAAI,IAAI,IAAI,gBAAgB,GAAG,SAAS,CAEvC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAwBhD;IAED,IAAI,QAAQ,IAAI,qBAAqB,GAAG,SAAS,CAEhD;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EA0B3D;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAuBD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,QAAa,OAAO,CAAC,SAAS,CAAC,CAI3C;IAEF,IAAI,IAAI,IAAI;IAWZ;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;IAyBpC;;;;;OAKG;IACH,OAAO;CAwFR"}