@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/view/RemoteWorkerEnv.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/view/RemoteWorkerEnv.ts"],
-  "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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",
+  "sourcesContent": ["import {emitStrict, once, retain} from '@spearwolf/eventize';\nimport {ChangeTrailRefusedError} from '../ChangeTrailRefusedError.js';\nimport {\n  AppliedChangeTrail,\n  ChangeTrail,\n  Configure,\n  Destroy,\n  Destroyed,\n  ImportedModule,\n  Inspect,\n  Inspected,\n  Loaded,\n  MessageToView,\n  WorkerChangeTrailTimeout,\n  WorkerConfigureTimeout,\n  WorkerDestroyTimeout,\n  WorkerInspectTimeout,\n  WorkerLoadTimeout,\n} from '../constants.js';\nimport createWorker from '../create-worker.js';\nimport type {InspectRequest, KernelSnapshot} from '../inspect/types.js';\nimport type {\n  AppliedChangeTrailEvent,\n  ChangeTrailType,\n  ImportedModuleEvent,\n  InspectEvent,\n  InspectedEvent,\n  SyncEvent,\n  TransferablesType,\n} from '../types.js';\nimport {CONSOLE_LOGGER, ConsoleLogger, consoleLoggerConfigKey, loadConsoleLoggerConfig} from '../utils/ConsoleLogger.js';\nimport {toUrlString} from '../utils/toUrlString.js';\nimport {isTimeout, MaxWorkerTimeout, waitForMessageOfType} from '../utils/waitForMessageOfType.js';\nimport type {IShadowObjectEnvProxy} from './IShadowObjectEnvProxy.js';\n\n/**\n * Splits the transferables out of a change trail without writing to it. The trail handed in is a\n * snapshot that travels on after this call -- to the `ShadowEnv.AfterSync` consumers when the\n * environment applies it, to the `ShadowEnv.SyncFailed` consumers when it refuses it -- so an\n * entry carrying transferables is replaced by a shallow copy without them and every other\n * entry is passed through as it is. A trail that carries none is handed back object for\n * object.\n */\nconst splitTransferables = (\n  changeTrail: ChangeTrailType,\n): {changeTrail: ChangeTrailType; transferables?: TransferablesType | undefined} => {\n  if (!Array.isArray(changeTrail)) return {changeTrail};\n\n  let outbound: ChangeTrailType | undefined;\n  let transferables: TransferablesType | undefined;\n\n  for (let i = 0; i < changeTrail.length; i++) {\n    const changeItem = changeTrail[i];\n    if (changeItem?.transferables) {\n      transferables = transferables ? [...transferables, ...changeItem.transferables] : [...changeItem.transferables];\n\n      outbound ??= [...changeTrail];\n      const withoutTransferables = {...changeItem};\n      delete withoutTransferables.transferables;\n      outbound[i] = withoutTransferables;\n    }\n  }\n\n  return {changeTrail: outbound ?? changeTrail, transferables};\n};\n\n/**\n * What actually goes on the wire for a `ChangeTrail` message. `SyncEvent` describes the shape a\n * change trail carries once it is inside the worker, without the `type` discriminant that gets\n * it there \u2014 its two neighbors on the wire (`ImportedModuleEvent`, `AppliedChangeTrailEvent`)\n * both require that field, so adding it to `SyncEvent` itself would either make it mandatory\n * where `LocalShadowObjectEnv` never sets it, or optional on a public type whose neighbors need\n * it required. Kept local instead: it says exactly what this message is without touching the\n * exported type surface.\n */\ninterface ChangeTrailMessage extends SyncEvent {\n  type: typeof ChangeTrail;\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/**\n * The reason a request is rejected with when the worker reported a failure of its own -- a\n * module that would not import, a change trail its Kernel refused. An error does not survive\n * structured cloning as the object it is, so the two fields that do are rebuilt here, and\n * `name` is the name the error called itself inside the worker: a caller reads it the same\n * way it reads the name of an error a `LocalShadowObjectEnv` hands it. A name that is missing\n * or empty names no class, and `Error` is what such a reason is called -- the same name a\n * plain `new Error(message)` carries on the local side.\n *\n * What does not come across is the class and everything it added. `instanceof EntityUuidInUseError`\n * is `false` here and there is no `uuid` field, whatever `name` says; `instanceof WorkerReportedError`\n * is what tells such a reason apart from one raised on this side.\n */\nexport class WorkerReportedError extends Error {\n  constructor(name: string | undefined, message: string) {\n    super(message);\n    this.name = name || 'Error';\n  }\n}\n\n/**\n * How long a {@link RemoteWorkerEnv} waits for each of the five replies a worker owes it,\n * in milliseconds.\n */\nexport interface WorkerTimeouts {\n  /** the `Loaded` handshake at the start */\n  loadTimeout: number;\n  /** the `ImportedModule` reply to an `importScript()` */\n  configureTimeout: number;\n  /** the `AppliedChangeTrail` confirmation of a change trail sent with `waitForConfirmation` */\n  changeTrailTimeout: number;\n  /** the `Inspected` answer to an `inspect()` */\n  inspectTimeout: number;\n  /** the `Destroyed` acknowledgement of a teardown */\n  destroyTimeout: number;\n}\n\n/**\n * What {@link RemoteWorkerEnv} takes. Every value left out keeps its default \u2014 the five\n * `Worker*Timeout` constants. A value that is not a number of milliseconds from 1 to\n * 2147483647 \u2014 close to 25 days, the longest delay a timer keeps \u2014 is reported through the\n * logger and the default applies.\n */\nexport type RemoteWorkerEnvOptions = Partial<WorkerTimeouts>;\n\nconst DefaultWorkerTimeouts: WorkerTimeouts = {\n  loadTimeout: WorkerLoadTimeout,\n  configureTimeout: WorkerConfigureTimeout,\n  changeTrailTimeout: WorkerChangeTrailTimeout,\n  inspectTimeout: WorkerInspectTimeout,\n  destroyTimeout: WorkerDestroyTimeout,\n};\n\n/**\n * Resolves the options against the defaults. A timeout is a number of milliseconds from 1 to\n * {@link MaxWorkerTimeout}; anything else is refused and reported, and the default stays.\n *\n * Zero and Infinity are refused along with the rest, and that is the point of the rule rather\n * than an oversight: `waitForMessageOfType()` arms no timer for either of them, so a teardown\n * given one of the two would wait for an acknowledgement a dead worker never sends \u2014 and the\n * `terminate()` that ends the teardown hangs on that very chain. One rule for all five values\n * is easier to hold on to than four that allow it and one that does not, and {@link MaxWorkerTimeout}\n * \u2014 close to 25 days \u2014 is as long as a wait can honestly be made.\n */\nconst resolveTimeouts = (options: RemoteWorkerEnvOptions | undefined, logger: ConsoleLogger): WorkerTimeouts => {\n  const resolved: WorkerTimeouts = {...DefaultWorkerTimeouts};\n  if (options == null) return resolved;\n\n  for (const key of Object.keys(DefaultWorkerTimeouts) as (keyof WorkerTimeouts)[]) {\n    // own keys only: what an object inherits from its prototype is not what its author wrote down\n    if (!Object.hasOwn(options, key)) continue;\n\n    const value = options[key];\n    if (value === undefined) continue;\n\n    if (isTimeout(value)) {\n      resolved[key] = value;\n    } else {\n      logger.error(`ignoring the ${key} option: expected a number of milliseconds from 1 to ${MaxWorkerTimeout}, got`, value);\n    }\n  }\n\n  return resolved;\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 | undefined;\n  #isDestroyed = false;\n  #changeTrailSerial = 0;\n  #inspectSerial = 0;\n\n  /**\n   * Aborted exactly once, with the error that ends this environment: a {@link WorkerFailedError}\n   * when the worker broke down, a {@link WorkerDestroyedError} when it was torn down. Whichever\n   * comes first keeps the signal, so a teardown never buries the failure that provoked it.\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  /** The logger this environment reports through. */\n  get logger(): ConsoleLogger {\n    return this.#logger;\n  }\n\n  readonly #timeouts: Readonly<WorkerTimeouts>;\n\n  /**\n   * The five timeouts this environment holds itself to, resolved once when it is built. The\n   * object is frozen and the slot holds no setter, so the constructor is the one way in --\n   * and `resolveTimeouts()` vets every value that goes through it.\n   */\n  get timeouts(): Readonly<WorkerTimeouts> {\n    return this.#timeouts;\n  }\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   * @throws {WorkerDestroyedError} once the environment has been torn down \u2014 including every\n   *   read after a load that had already succeeded, because there is no environment left to hand out\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(options?: RemoteWorkerEnvOptions) {\n    // the logger is a field initializer and is therefore already in place\n    this.#timeouts = Object.freeze(resolveTimeouts(options, this.logger));\n\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 endings of this environment abort the signal, and it keeps the reason of whichever\n    // came first. A finished environment must not spawn a worker: nothing would ever reach it,\n    // and nothing would ever shut it down again\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) throw signal.reason;\n\n    if (this.#worker) {\n      this.logger.warn('already started');\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);\n    worker.addEventListener('messageerror', this.onWorkerMessageError);\n\n    this.configureConsoleLogger(worker);\n\n    try {\n      await waitForMessageOfType(worker, Loaded, this.timeouts.loadTimeout, undefined, signal);\n\n      // the handshake completed but the environment ended while its reply was on the way here.\n      // The reason of that ending is what the caller gets \u2014 a fresh error of our own would read\n      // as a start that went wrong, and the catch below would report it as one\n      if (this.isDestroyed) {\n        throw signal.aborted ? signal.reason : new WorkerDestroyedError();\n      }\n\n      worker.addEventListener('message', this.onMessageFromWorker);\n\n      queueMicrotask(() => {\n        this.announceLoaded();\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.stopListeningTo(worker);\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 {changeTrail: outbound, transferables} = splitTransferables(changeTrail);\n    const message: ChangeTrailMessage = {type: ChangeTrail, changeTrail: outbound};\n\n    if (!waitForConfirmation) {\n      worker.postMessage(message, transferables ?? []);\n      return Promise.resolve();\n    }\n\n    // the counter moves only where a number actually goes on the wire: it is the sole link\n    // between a request and its confirmation, and a sequence with invisible jumps in it tells\n    // a later diagnosis nothing\n    const serial = ++this.#changeTrailSerial;\n    message.serial = serial;\n\n    worker.postMessage(message, transferables ?? []);\n\n    return waitForMessageOfType(\n      worker,\n      AppliedChangeTrail,\n      this.timeouts.changeTrailTimeout,\n      (data: AppliedChangeTrailEvent) => {\n        // the serial decides who a confirmation concerns -- an error belonging to another\n        // trail would otherwise reject the request that happens to be waiting here\n        if (data.serial !== serial) return false;\n        if (data.error) {\n          const reason = new WorkerReportedError(data.errorName, data.error);\n          // Only a confirmation that names the count can move the line the view draws between\n          // applied and pending; one that does not carries no more than the reason itself, and\n          // is handed on as that reason.\n          if (typeof data.appliedCount === 'number') {\n            throw new ChangeTrailRefusedError(data.appliedCount, changeTrail.length, {cause: reason});\n          }\n          throw reason;\n        }\n        return true;\n      },\n      signal,\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      this.timeouts.configureTimeout,\n      (data: ImportedModuleEvent) => {\n        if (data.url !== url) return false;\n        if (data.error) throw new WorkerReportedError(data.errorName, data.error);\n        return true;\n      },\n      signal,\n    );\n  }\n\n  /**\n   * Asks the worker for a snapshot of its Kernel. The request travels as an `Inspect` message\n   * under a serial of its own, and the `Inspected` answer that carries the same serial settles\n   * the call: with the snapshot, or with a `WorkerReportedError` rebuilt from the failure the\n   * worker described. An answer that stays out past `inspectTimeout` rejects with a\n   * `WorkerTimeoutError`; a worker that failed or an environment that was torn down rejects right\n   * away, before or while the answer is awaited.\n   *\n   * The caller's `signal` ends the wait with its own reason. The worker is not told: an answer\n   * that arrives afterwards carries a serial nobody waits for any more and is discarded like any\n   * other unmatched message.\n   *\n   * The message runs through the same queue as the change trails, so the snapshot reflects every\n   * trail posted before this call and none posted after it.\n   */\n  inspect(request: InspectRequest = {}, signal?: AbortSignal): Promise<KernelSnapshot> {\n    const {signal: failure} = this.#workerFailure;\n    if (failure.aborted) return Promise.reject(failure.reason);\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    // a sequence of its own next to the one the change trails count on: the two answers are told\n    // apart by their type, so neither sequence has to know about the other\n    const serial = ++this.#inspectSerial;\n    const message: InspectEvent = {type: Inspect, serial, request};\n    worker.postMessage(message);\n\n    let snapshot: KernelSnapshot | undefined;\n\n    return waitForMessageOfType(\n      worker,\n      Inspected,\n      this.timeouts.inspectTimeout,\n      (data: InspectedEvent) => {\n        if (data.serial !== serial) return false;\n        if (data.error) throw new WorkerReportedError(data.errorName, data.error);\n        snapshot = data.snapshot;\n        return true;\n      },\n      signal === undefined ? failure : AbortSignal.any([failure, signal]),\n    ).then(() => {\n      // a reply that names neither a snapshot nor an error comes from a sender that does not\n      // speak this protocol; it is a rejection, not a value the caller then reads through\n      if (snapshot === undefined) {\n        throw new WorkerReportedError(undefined, 'the worker answered the inspection without a snapshot');\n      }\n      return snapshot;\n    });\n  }\n\n  destroy(): void {\n    // the teardown counts even when there is no worker to tear down: everything that comes\n    // afterwards has to meet an environment that is gone\n    this.#isDestroyed = true;\n\n    // releasing the reference here is what makes the teardown idempotent: a repeated call finds\n    // nothing left, sends no second Destroy and terminates nothing twice\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    // settles everything still waiting for a reply: a start() in the middle of its load handshake\n    // would otherwise sit out its load timeout, and workerLoaded would never hear anything again\n    this.#workerFailure.abort(new WorkerDestroyedError());\n\n    if (worker == null) return;\n\n    this.stopListeningTo(worker);\n\n    worker.postMessage({type: Destroy});\n\n    waitForMessageOfType(worker, Destroyed, this.timeouts.destroyTimeout)\n      .catch((error) => {\n        // `.finally()` passes a rejection on, so without this the silence of a worker ends as an\n        // unhandled rejection once the destroy timeout is up. It is terminated either way, and\n        // by then there is nobody left to hand the error to\n        this.logger.warn('the worker did not acknowledge the teardown', error);\n      })\n      .finally(() => {\n        worker.terminate();\n      });\n  }\n\n  private readonly onWorkerError = (event: ErrorEvent): void => {\n    this.handleWorkerFailure('error', event, event.message || 'the worker reported an error');\n  };\n\n  private readonly onWorkerMessageError = (event: MessageEvent): void => {\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    if (worker != null) this.stopListeningTo(worker);\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    this.announceFailure({env: this, type, message, reason, event});\n  }\n\n  /**\n   * Announces the completed handshake to the consumers.\n   *\n   * `emitStrict()` rather than `emit()`, and the retain policy is what decides it. `workerLoaded`\n   * reads the retained value, and eventize writes that value only once the dispatch has run\n   * through: under the plain dispatch a single listener that throws would take the replay for\n   * every later subscriber with it, and every later read of `workerLoaded` would wait for a\n   * failure or a teardown instead of resolving. The guarded dispatch serves every listener and\n   * writes the retained value, because the event was delivered.\n   *\n   * What the listeners threw arrives here afterwards -- one of them unchanged, several as an\n   * `AggregateError` in dispatch order -- and is reported. It goes no further: this runs from a\n   * microtask, where a throw has no caller left to reach and would surface as an unhandled error.\n   */\n  private announceLoaded(): void {\n    try {\n      emitStrict(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, this);\n    } catch (error) {\n      this.logger.error('a workerLoaded listener threw', error);\n    }\n  }\n\n  /**\n   * Announces the failure to the consumers. The same guarded dispatch as\n   * {@link RemoteWorkerEnv.announceLoaded}, for the same reason: `WorkerFailed` is documented as\n   * retained, and a consumer that subscribes only after the failure has to be able to hear about\n   * it. Every listener is served, the retained value is written, and whatever was thrown is\n   * reported here and reaches no caller.\n   */\n  private announceFailure(payload: WorkerFailedEvent): void {\n    try {\n      emitStrict(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerFailed, payload);\n    } catch (error) {\n      this.logger.error('a workerFailed listener threw', error);\n    }\n  }\n\n  private readonly onMessageFromWorker = (event: MessageEvent): void => {\n    if (event.data?.type === MessageToView) {\n      (this as IShadowObjectEnvProxy).onMessageToView?.(event.data.data);\n    } else {\n      this.logger.debug('message from worker', event);\n    }\n  };\n\n  /**\n   * Takes every listener of this environment off a worker. Whoever registered them takes them\n   * off again -- between the teardown and the `terminate()` that ends it the worker stays\n   * alive, and through its listeners it keeps this environment and everything it references\n   * reachable for exactly that long.\n   */\n  private stopListeningTo(worker: Worker): void {\n    worker.removeEventListener('error', this.onWorkerError);\n    worker.removeEventListener('messageerror', this.onWorkerMessageError);\n    worker.removeEventListener('message', this.onMessageFromWorker);\n  }\n\n  private configureConsoleLogger(worker: Worker) {\n    const configKey = ['RemoteWorkerEnv', 'workerConfig'];\n    const storageKey = consoleLoggerConfigKey(configKey);\n    const workerConfig = this.readWorkerConfig(configKey, storageKey);\n\n    this.logger.info('load console-logger worker config', {storageKey, workerConfig});\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\n  /**\n   * The console-logger config for the worker, read from the storage key this environment\n   * announces. The key is a diagnostic switch, set by hand and sharing its namespace with\n   * everything else on this origin, so its content decides nothing about whether the worker\n   * comes up: anything that is not a plain JSON object counts as no config at all, exactly\n   * like an absent key.\n   */\n  private readWorkerConfig(configKey: string[], storageKey: string): Record<string, unknown> {\n    const stored = loadConsoleLoggerConfig(configKey, '{}');\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(stored);\n    } catch (error) {\n      // error, not warn: whoever writes this key wants the worker to talk, and a silent\n      // fallback would send them looking for the reason inside the worker\n      this.logger.error(`ignoring the unreadable console-logger worker config at \"${storageKey}\"`, stored, error);\n      return {};\n    }\n\n    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n      this.logger.error(`ignoring the console-logger worker config at \"${storageKey}\": expected a JSON object`, stored);\n      return {};\n    }\n\n    return parsed as Record<string, unknown>;\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/src/view/ShadowEnv.d.ts

@@ -1,3 +1,4 @@
+import type { EnvSnapshot, InspectRequest } from '../inspect/types.js';
 import type { ChangeTrailType, NamespaceType } from '../types.js';
 import { ConsoleLogger } from '../utils/ConsoleLogger.js';
 import { ComponentContext } from './ComponentContext.js';
@@ -15,11 +16,31 @@ export declare class ShadowEnvDestroyedError extends Error {
 export declare class ShadowEnv {
     #private;
     static AfterSync: string;
+    static SyncFailed: string;
     static ContextLost: string;
     static ContextCreated: string;
     static ProxyFailed: string;
     static get(ns: NamespaceType): ShadowEnv | undefined;
-    readonly logger: ConsoleLogger;
+    /**
+     * Every environment that holds a namespace, in registration order, each described by
+     * {@link ShadowEnv.inspect}. One environment that cannot answer costs its own entry and not the
+     * list: the per-environment failures are reported under `error`, and an environment destroyed
+     * while it answers drops out of the list. Rejects only for the caller's reasons -- an aborted
+     * signal.
+     *
+     * `only` narrows the list before anything is asked: it is called with the namespace an
+     * environment is registered under, and an environment it refuses is neither inspected nor
+     * listed. That is what lets a caller keep an environment out of a picture without touching it.
+     */
+    static inspectAll(request?: InspectRequest, signal?: AbortSignal, only?: (ns: NamespaceType) => boolean): Promise<EnvSnapshot[]>;
+    /** The logger this environment reports through. */
+    get logger(): ConsoleLogger;
+    /**
+     * The namespace of the {@link ComponentContext} this environment observes, and `undefined`
+     * while it observes none. The `view` setter writes it, so it carries the name
+     * {@link ShadowEnv.get} finds this environment under, unless another environment has since
+     * taken that namespace over; a `destroy()` leaves it on `undefined`.
+     */
     readonly ns$: import("@spearwolf/signalize").Signal<NamespaceType | undefined>;
     accessor viewReady: boolean;
     accessor proxyReady: boolean;
@@ -36,13 +57,69 @@ export declare class ShadowEnv {
      * @throws {ShadowEnvDestroyedError} if the environment is destroyed before that happens
      */
     readonly ready: () => Promise<ShadowEnv>;
+    /**
+     * Send the change trail without asking the Shadow Environment to confirm it --
+     * {@link ShadowEnv.syncWait} is the call that asks.
+     *
+     * What becomes of a refusal is then the proxy's decision, and the two shipped ones differ.
+     * `LocalShadowObjectEnv` runs the Kernel synchronously, inside the call the environment makes to
+     * the proxy -- one microtask after `sync()` returned, not inside the call to `sync()` itself --
+     * and rejects with what it threw, so a refusal reaches {@link ShadowEnv.SyncFailed} here as well,
+     * carrying its number.
+     * `RemoteWorkerEnv` sends no serial without a confirmation and gets no answer back, so a
+     * refusal stays in the worker: it is written to the console there, `SyncFailed` stays silent, and
+     * the whole trail is booked as applied.
+     *
+     * {@link ShadowEnv.syncWait} is the way both proxies answer on.
+     */
     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
+     * A cycle whose change trail the Shadow Environment could not apply rejects instead, with the
+     * reason the proxy gave. Where the Kernel itself refused the trail that reason is a
+     * {@link ChangeTrailRefusedError}: it names how many entries the Kernel applied, this side folds
+     * exactly those into its bookkeeping, and everything behind that line stays pending and goes out
+     * again with the next cycle. A trail whose cause of refusal stays put is refused every time, which
+     * is what {@link ShadowEnv.SyncFailed} is the place to act on.
+     *
+     * A reason that says nothing about how far the Kernel got -- a confirmation window that ran out,
+     * a proxy whose environment is gone -- counts the whole trail as applied, because a Shadow
+     * Environment that fell silent may well hold all of it. Then the trail is gone, and only a
+     * re-creation from the Component Memory brings it back. That re-creation belongs to a fresh
+     * proxy: an environment that still holds the entities refuses a creation for a uuid it already
+     * has. Handing {@link ShadowEnv.envProxy} a new proxy is therefore the way back -- the Shadow
+     * Environment calls {@link ComponentContext.reCreateChanges} itself once the new proxy is ready.
+     * Making that call is the consumer's decision, the same way recovering from a
+     * {@link ShadowEnv.ProxyFailed} is.
+     *
+     * Which cycle a caller gets is decided when the change trail is built. Everyone who arrives
+     * before that point waits on the same promise -- they all ride the same trail. From the build
+     * on the trail is fixed, and a call after it belongs to the next cycle, the one that carries
+     * the changes made since. That holds inside a listener of {@link ShadowEnv.AfterSync} or
+     * {@link ShadowEnv.SyncFailed} as well: the cycle it was told about is over, so the call opens
+     * the one behind it.
+     *
+     * @throws {ShadowEnvDestroyedError} if the environment is destroyed before the cycle completes
      */
     syncWait(): Promise<ChangeTrailType>;
+    /**
+     * Describe this environment: the View's component tree and, where the proxy is ready and
+     * implements `inspect`, the Kernel's Entity Tree behind it.
+     *
+     * Never rejects for a reason inside the environment -- a proxy that cannot answer, a Kernel that
+     * threw, a View snapshot that threw -- and reports those under `error`, with the half that failed
+     * absent. Where both halves fail, `error` carries the View's reason. A proxy that is not ready yet
+     * is not an error either: `state.proxyReady` says so, and `kernel` is simply absent. It rejects
+     * only for a reason of the caller's: an aborted signal, or an environment that is destroyed
+     * before or while the proxy answers. The signal is raced here as well, so an abort settles the
+     * call whether or not the proxy honours the signal it was handed.
+     *
+     * A caller that wants the View and the Kernel to agree after its own change awaits
+     * {@link ShadowEnv.syncWait} first; the View snapshot reads the committed Component Memory,
+     * not the pending changes.
+     */
+    inspect(request?: InspectRequest, signal?: AbortSignal): Promise<EnvSnapshot>;
     /**
      * 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

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;;;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"}
+{"version":3,"file":"ShadowEnv.d.ts","sourceRoot":"","sources":["../../../src/view/ShadowEnv.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,WAAW,EAAE,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAErF,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;AAGtE,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAO,SAA8C,EAGhE;CACF;AA4CD,qBAAa,SAAS;;IACpB,MAAM,CAAC,SAAS,SAAe;IAC/B,MAAM,CAAC,UAAU,SAAgB;IACjC,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,CAGnD;IAED;;;;;;;;;;OAUG;IACH,OAAa,UAAU,CACrB,OAAO,GAAE,cAAmB,EAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,OAAO,GACpC,OAAO,CAAC,WAAW,EAAE,CAAC,CAexB;IAWD,mDAAmD;IACnD,IAAI,MAAM,IAAI,aAAa,CAE1B;IAED;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,mEAA6C;IAE/C,QAAQ,CAAC,SAAS,UAAS;IAC3B,QAAQ,CAAC,UAAU,UAAS;IAItC,IAAI,WAAW,YAEd;IAED,cAWC;IAoDD,IAAI,IAAI,IAAI,gBAAgB,GAAG,SAAS,CAEvC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EA0BhD;IAkBD,IAAI,QAAQ,IAAI,qBAAqB,GAAG,SAAS,CAEhD;IAMD,IAAI,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EA+C3D;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAuBD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,QAAa,OAAO,CAAC,SAAS,CAAC,CAI3C;IAEF;;;;;;;;;;;;;;OAcG;IACH,IAAI,IAAI,IAAI,CASX;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC,CAanC;IAED;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,OAAO,GAAE,cAAmB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CA+CtF;IAwBD;;;;;OAKG;IACH,OAAO,SAgCN;CA2JF"}