@spearwolf/shadow-objects 0.32.0 → 0.34.0

package/src/utils/ConsoleLogger.d.ts

@@ -1,19 +1,53 @@
 export declare const CONSOLE_LOGGER = "ConsoleLogger";
 export declare const CONSOLE_LOGGER_STORAGE = "ConsoleLoggerStorage";
+declare const ConsoleLogger$: unique symbol;
+export interface ConsoleLoggerConfig {
+    [ConsoleLogger$]?: boolean;
+    enable: boolean;
+    debug: boolean;
+    info: boolean;
+    warn: boolean;
+    'styles.debug': string;
+    'styles.info': string;
+    'styles.warn': string;
+    'styles.error': string;
+    [key: string]: string | boolean | undefined;
+}
+export interface ConsoleLoggerControl {
+    [ConsoleLogger$]?: boolean;
+    enable: boolean;
+    debug: boolean;
+    info: boolean;
+    warn: boolean;
+}
+/**
+ * The key a config value is stored under. Prefixed with {@link CONSOLE_LOGGER} when it goes
+ * into a real Storage, where it shares the namespace with everything else on this origin.
+ */
+export declare const consoleLoggerConfigKey: (key: string | string[]) => string;
+/**
+ * Reads a raw config value through whatever storage the capability probe accepted, or from the
+ * fallback object store when none did. The way to reach the config from outside this module:
+ * `globalThis.localStorage` may be missing, inert or hostile, and asking it directly throws.
+ */
+export declare const loadConsoleLoggerConfig: (key: string | string[], defaultValue: string) => string;
+/**
+ * Installs a config object as the fallback store, bypassing the storage probe. `WorkerRuntime`
+ * calls this with the config a `RemoteWorkerEnv` forwards from the main thread, where there is no
+ * `localStorage` to probe in the first place.
+ *
+ * Once a logger exists in such a thread, `ConsoleLogger.sharedConfig` *is* that store, and the
+ * values are written into it rather than a fresh object taking its place in the slot: the shared
+ * switches reach every logger of the thread, the ones already built included. One flag stays
+ * behind -- a logger reads its own `<namespace>.enable` key when it is built, and a config that
+ * arrives afterwards no longer moves it.
+ */
+export declare function setConsoleLoggerStorage(config: ConsoleLoggerConfig): void;
 export declare class ConsoleLogger {
     #private;
     namespace?: string;
     enable: boolean;
-    static sharedConfig: {
-        enable: boolean;
-        debug: boolean;
-        info: boolean;
-        warn: boolean;
-        'styles.debug': string;
-        'styles.info': string;
-        'styles.warn': string;
-        'styles.error': string;
-    };
+    static sharedConfig: ConsoleLoggerConfig;
     static get isEnabled(): boolean;
     static get isDebug(): boolean;
     static sharedStyles: {
@@ -33,4 +67,5 @@ export declare class ConsoleLogger {
     warn(...args: any[]): void;
     error(...args: any[]): void;
 }
+export {};
 //# sourceMappingURL=ConsoleLogger.d.ts.map

package/src/utils/ConsoleLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConsoleLogger.d.ts","sourceRoot":"","sources":["../../../src/utils/ConsoleLogger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAC9C,eAAO,MAAM,sBAAsB,yBAA6B,CAAC;AAgDjE,qBAAa,aAAa;;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,MAAM,UAAQ;IAEd,MAAM,CAAC,YAAY;;;;;;;;;MAWjB;IAEF,MAAM,KAAK,SAAS,YAEnB;IAED,MAAM,KAAK,OAAO,YAEjB;IAED,MAAM,CAAC,YAAY;eAIF,MAAM;cAMP,MAAM;cAMN,MAAM;eAML,MAAM;MAGrB;IAEF,MAAM,CAAC,UAAU;gBA4EL,SAAS,EAAE,MAAM;IAa7B,IAAI,SAAS,YAEZ;IAED,IAAI,OAAO,YAEV;IAED,IAAI,MAAM,YAET;IAED,IAAI,MAAM,YAET;IAED,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAIpB,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAInB,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAInB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;CAOrB"}
+{"version":3,"file":"ConsoleLogger.d.ts","sourceRoot":"","sources":["../../../src/utils/ConsoleLogger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAC9C,eAAO,MAAM,sBAAsB,yBAA6B,CAAC;AAmDjE,QAAA,MAAM,cAAc,EAAE,OAAO,MAAmC,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC,CAAC,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,CAAC,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAgDD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAS,MAAM,GAAG,MAAM,EAAE,KAAG,MAAyB,CAAC;AAE1F;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,MAAM,GAAG,MAAM,EAAE,gBAAgB,MAAM,KAAG,MACxC,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CASzE;AAED,qBAAa,aAAa;;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,MAAM,UAAQ;IAEd,MAAM,CAAC,YAAY,EAAE,mBAAmB,CAWtC;IAEF,MAAM,KAAK,SAAS,YAEnB;IAED,MAAM,KAAK,OAAO,YAEjB;IAED,MAAM,CAAC,YAAY;eAIF,MAAM;cAMP,MAAM;cAMN,MAAM;eAML,MAAM;MAGrB;IAEF,MAAM,CAAC,UAAU,SA8DhB;IAED,YAAY,SAAS,EAAE,MAAM,EAY5B;IAED,IAAI,SAAS,YAEZ;IAED,IAAI,OAAO,YAEV;IAED,IAAI,MAAM,YAET;IAED,IAAI,MAAM,YAET;IAED,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,QAGnB;IAED,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,QAGlB;IAED,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,QAGlB;IAID,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,QAEnB;CAKF"}

package/src/utils/ConsoleLogger.js

@@ -1,8 +1,27 @@
 const CONSOLE_LOGGER = "ConsoleLogger";
 const CONSOLE_LOGGER_STORAGE = `${CONSOLE_LOGGER}Storage`;
-const IS_LOCALHOST = Boolean(globalThis.location?.host?.startsWith("localhost") ?? false);
-const HAS_LOCAL_STORAGE = "localStorage" in globalThis;
+const LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+const IS_LOOPBACK_HOST = LOOPBACK_HOSTNAMES.has(globalThis.location?.hostname ?? "");
+const gLocalStorage = (() => {
+  try {
+    const storage = globalThis.localStorage;
+    if (typeof storage?.getItem !== "function" || typeof storage.setItem !== "function" || typeof storage.removeItem !== "function") {
+      return void 0;
+    }
+    const probeKey = `${CONSOLE_LOGGER}.probe`;
+    try {
+      storage.setItem(probeKey, probeKey);
+    } finally {
+      storage.removeItem(probeKey);
+    }
+    return storage;
+  } catch {
+    return void 0;
+  }
+})();
+const HAS_LOCAL_STORAGE = gLocalStorage != null;
 const ConsoleLogger$ = Symbol.for(CONSOLE_LOGGER);
+const gGlobalSlots = globalThis;
 let gInitialized = false;
 const asBoolean = (val) => {
   if (typeof val === "boolean") return val;
@@ -16,22 +35,27 @@ const asBoolean = (val) => {
   }
 };
 const getKeyPath = (key) => [HAS_LOCAL_STORAGE ? CONSOLE_LOGGER : void 0, ...Array.isArray(key) ? key : [key]].filter(Boolean).join(".");
-function loadConfigValue(key, as = void 0, defaultValue) {
+function loadConfigValue(key, as, defaultValue) {
   const _key = getKeyPath(key);
-  const value = HAS_LOCAL_STORAGE ? localStorage.getItem(_key) : globalThis[CONSOLE_LOGGER_STORAGE]?.[_key];
-  return value != void 0 ? as(value) : defaultValue;
+  const value = gLocalStorage ? gLocalStorage.getItem(_key) : gGlobalSlots.ConsoleLoggerStorage?.[_key];
+  if (value == void 0) return defaultValue;
+  return as ? as(value) : value;
 }
 function saveConfigValue(key, val) {
-  if (HAS_LOCAL_STORAGE) {
-    localStorage.setItem(getKeyPath(key), val);
-  } else {
-    if (globalThis[CONSOLE_LOGGER_STORAGE] == void 0) {
-      globalThis[CONSOLE_LOGGER_STORAGE] = {};
-      console.debug(`${CONSOLE_LOGGER}: Initialize`, { [CONSOLE_LOGGER_STORAGE]: globalThis[CONSOLE_LOGGER_STORAGE] });
-    }
-    globalThis[CONSOLE_LOGGER_STORAGE][getKeyPath(key)] = val;
+  if (gLocalStorage) {
+    gLocalStorage.setItem(getKeyPath(key), val);
   }
 }
+const consoleLoggerConfigKey = (key) => getKeyPath(key);
+const loadConsoleLoggerConfig = (key, defaultValue) => loadConfigValue(key, void 0, defaultValue);
+function setConsoleLoggerStorage(config) {
+  const store = gGlobalSlots.ConsoleLoggerStorage;
+  if (store != null && store === ConsoleLogger.sharedConfig) {
+    Object.assign(store, config, { [ConsoleLogger$]: true });
+    return;
+  }
+  gGlobalSlots.ConsoleLoggerStorage = config;
+}
 class ConsoleLogger {
   constructor(namespace) {
     this.enable = true;
@@ -42,11 +66,10 @@ class ConsoleLogger {
     }
     const key = [this.namespace, "enable"];
     this.enable = loadConfigValue(key, asBoolean, this.enable);
-    saveConfigValue(key, HAS_LOCAL_STORAGE ? this.enable ? "true" : "false" : this.enable);
   }
   static {
     this.sharedConfig = {
-      enable: IS_LOCALHOST,
+      enable: IS_LOOPBACK_HOST,
       debug: false,
       info: true,
       warn: true,
@@ -101,8 +124,8 @@ class ConsoleLogger {
       if (ConsoleLogger.isDebug) {
         console.debug(`${CONSOLE_LOGGER}: Load config from localStorage`, ConsoleLogger.sharedConfig);
       }
-      if (!globalThis[CONSOLE_LOGGER]?.[ConsoleLogger$]) {
-        globalThis[CONSOLE_LOGGER] ??= {
+      if (!gGlobalSlots.ConsoleLogger?.[ConsoleLogger$]) {
+        gGlobalSlots.ConsoleLogger ??= {
           [ConsoleLogger$]: true,
           get enable() {
             return ConsoleLogger.sharedConfig.enable;
@@ -135,20 +158,15 @@ class ConsoleLogger {
         };
       }
     } else {
-      if (!globalThis[CONSOLE_LOGGER_STORAGE]?.[ConsoleLogger$]) {
-        globalThis[CONSOLE_LOGGER_STORAGE] = {
+      if (!gGlobalSlots.ConsoleLoggerStorage?.[ConsoleLogger$]) {
+        gGlobalSlots.ConsoleLoggerStorage = {
           [ConsoleLogger$]: true,
           ...ConsoleLogger.sharedConfig,
-          // @ts-ignore
-          ...globalThis[CONSOLE_LOGGER_STORAGE]
+          ...gGlobalSlots.ConsoleLoggerStorage
         };
-        ConsoleLogger.sharedConfig = globalThis[CONSOLE_LOGGER_STORAGE];
+        ConsoleLogger.sharedConfig = gGlobalSlots.ConsoleLoggerStorage;
         if (ConsoleLogger.isDebug) {
-          console.debug(
-            `${CONSOLE_LOGGER}: Load config from ${CONSOLE_LOGGER_STORAGE}`,
-            // @ts-ignore
-            globalThis[CONSOLE_LOGGER_STORAGE]
-          );
+          console.debug(`${CONSOLE_LOGGER}: Load config from ${CONSOLE_LOGGER_STORAGE}`, gGlobalSlots.ConsoleLoggerStorage);
         }
       }
     }
@@ -166,14 +184,19 @@ class ConsoleLogger {
     return this.isEnabled && ConsoleLogger.sharedConfig.warn;
   }
   debug(...args) {
+    if (!this.isDebug) return;
     this.#print("debug", ConsoleLogger.sharedStyles.debug, args);
   }
   info(...args) {
+    if (!this.isInfo) return;
     this.#print("info", ConsoleLogger.sharedStyles.info, args);
   }
   warn(...args) {
+    if (!this.isWarn) return;
     this.#print("warn", ConsoleLogger.sharedStyles.warn, args);
   }
+  // An error report names a fault in the calling code, and its author has to see it wherever
+  // the application runs -- not only on a loopback host, so `error()` asks no getter.
   error(...args) {
     this.#print("error", ConsoleLogger.sharedStyles.error, args);
   }
@@ -184,6 +207,9 @@ class ConsoleLogger {
 export {
   CONSOLE_LOGGER,
   CONSOLE_LOGGER_STORAGE,
-  ConsoleLogger
+  ConsoleLogger,
+  consoleLoggerConfigKey,
+  loadConsoleLoggerConfig,
+  setConsoleLoggerStorage
 };
 //# sourceMappingURL=ConsoleLogger.js.map

package/src/utils/ConsoleLogger.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/utils/ConsoleLogger.ts"],
-  "sourcesContent": ["// https://developer.chrome.com/docs/devtools/console/format-style?hl=de\n\nexport const CONSOLE_LOGGER = 'ConsoleLogger';\nexport const CONSOLE_LOGGER_STORAGE = `${CONSOLE_LOGGER}Storage`;\n\nconst IS_LOCALHOST = Boolean(globalThis.location?.host?.startsWith('localhost') ?? false);\n\nconst HAS_LOCAL_STORAGE = 'localStorage' in globalThis;\n\nconst ConsoleLogger$ = Symbol.for(CONSOLE_LOGGER);\n\nlet gInitialized = false;\n\nconst asBoolean = (val: string | boolean) => {\n  if (typeof val === 'boolean') return val;\n  switch (val.toLowerCase()) {\n    case 'true':\n    case 'yes':\n    case 'on':\n      return true;\n    default:\n      return false;\n  }\n};\n\nconst getKeyPath = (key: string | string[]): string =>\n  [HAS_LOCAL_STORAGE ? CONSOLE_LOGGER : undefined, ...(Array.isArray(key) ? key : [key])].filter(Boolean).join('.');\n\nfunction loadConfigValue<T>(key: string | string[], as: (val: string) => T = undefined, defaultValue: T): T {\n  const _key = getKeyPath(key);\n  // @ts-ignore\n  const value = HAS_LOCAL_STORAGE ? localStorage.getItem(_key) : globalThis[CONSOLE_LOGGER_STORAGE]?.[_key];\n  return value != undefined ? as(value) : defaultValue;\n}\n\nfunction saveConfigValue(key: string | string[], val: any) {\n  if (HAS_LOCAL_STORAGE) {\n    localStorage.setItem(getKeyPath(key), val);\n  } else {\n    // @ts-ignore\n    if (globalThis[CONSOLE_LOGGER_STORAGE] == undefined) {\n      // @ts-ignore\n      globalThis[CONSOLE_LOGGER_STORAGE] = {};\n      // @ts-ignore\n      console.debug(`${CONSOLE_LOGGER}: Initialize`, {[CONSOLE_LOGGER_STORAGE]: globalThis[CONSOLE_LOGGER_STORAGE]});\n    }\n    // @ts-ignore\n    globalThis[CONSOLE_LOGGER_STORAGE][getKeyPath(key)] = val;\n  }\n}\n\nexport class ConsoleLogger {\n  namespace?: string;\n\n  enable = true;\n\n  static sharedConfig = {\n    enable: IS_LOCALHOST,\n\n    debug: false,\n    info: true,\n    warn: true,\n\n    'styles.debug': 'color: #111; background: #999; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n    'styles.info': 'color: #020; background: #8a8; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n    'styles.warn': 'color: #fa0; background: #a98; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n    'styles.error': 'color: #ff0; background: #a00; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n  };\n\n  static get isEnabled() {\n    return ConsoleLogger.sharedConfig.enable;\n  }\n\n  static get isDebug() {\n    return ConsoleLogger.sharedConfig.enable && ConsoleLogger.sharedConfig.debug;\n  }\n\n  static sharedStyles = {\n    get debug() {\n      return ConsoleLogger.sharedConfig['styles.debug'];\n    },\n    set debug(val: string) {\n      ConsoleLogger.sharedConfig['styles.debug'] = val;\n    },\n    get info() {\n      return ConsoleLogger.sharedConfig['styles.info'];\n    },\n    set info(val: string) {\n      ConsoleLogger.sharedConfig['styles.info'] = val;\n    },\n    get warn() {\n      return ConsoleLogger.sharedConfig['styles.warn'];\n    },\n    set warn(val: string) {\n      ConsoleLogger.sharedConfig['styles.warn'] = val;\n    },\n    get error() {\n      return ConsoleLogger.sharedConfig['styles.error'];\n    },\n    set error(val: string) {\n      ConsoleLogger.sharedConfig['styles.error'] = val;\n    },\n  };\n\n  static loadConfig() {\n    if (HAS_LOCAL_STORAGE) {\n      ['enable', 'debug', 'info', 'warn'].forEach((key) => {\n        // @ts-ignore\n        this.sharedConfig[key] = loadConfigValue(key, asBoolean, this.sharedConfig[key]);\n      });\n\n      ['debug', 'info', 'warn', 'error'].forEach((key) => {\n        // @ts-ignore\n        this.sharedStyles[key] = loadConfigValue(['styles', key], undefined, this.sharedStyles[key]);\n      });\n\n      if (ConsoleLogger.isDebug) {\n        console.debug(`${CONSOLE_LOGGER}: Load config from localStorage`, ConsoleLogger.sharedConfig);\n      }\n\n      // @ts-ignore\n      if (!globalThis[CONSOLE_LOGGER]?.[ConsoleLogger$]) {\n        // @ts-ignore\n        globalThis[CONSOLE_LOGGER] ??= {\n          [ConsoleLogger$]: true,\n\n          get enable() {\n            return ConsoleLogger.sharedConfig.enable;\n          },\n          set enable(val: boolean) {\n            ConsoleLogger.sharedConfig.enable = val;\n            saveConfigValue('enable', val ? 'true' : 'false');\n          },\n          get debug() {\n            return ConsoleLogger.sharedConfig.debug;\n          },\n          set debug(val: boolean) {\n            ConsoleLogger.sharedConfig.debug = val;\n            saveConfigValue('debug', val ? 'true' : 'false');\n          },\n          get info() {\n            return ConsoleLogger.sharedConfig.info;\n          },\n          set info(val: boolean) {\n            ConsoleLogger.sharedConfig.info = val;\n            saveConfigValue('info', val ? 'true' : 'false');\n          },\n          get warn() {\n            return ConsoleLogger.sharedConfig.warn;\n          },\n          set warn(val: boolean) {\n            ConsoleLogger.sharedConfig.warn = val;\n            saveConfigValue('warn', val ? 'true' : 'false');\n          },\n        };\n      }\n    } else {\n      // no localStorage available: in this case we just use globalThis[STORAGE_KEY]\n      // @ts-ignore\n      if (!globalThis[CONSOLE_LOGGER_STORAGE]?.[ConsoleLogger$]) {\n        // @ts-ignore\n        globalThis[CONSOLE_LOGGER_STORAGE] = {\n          [ConsoleLogger$]: true,\n          ...ConsoleLogger.sharedConfig,\n          // @ts-ignore\n          ...globalThis[CONSOLE_LOGGER_STORAGE],\n        };\n        // @ts-ignore\n        ConsoleLogger.sharedConfig = globalThis[CONSOLE_LOGGER_STORAGE];\n        if (ConsoleLogger.isDebug) {\n          console.debug(\n            `${CONSOLE_LOGGER}: Load config from ${CONSOLE_LOGGER_STORAGE}`,\n            // @ts-ignore\n            globalThis[CONSOLE_LOGGER_STORAGE],\n          );\n        }\n      }\n    }\n  }\n\n  constructor(namespace: string) {\n    this.namespace = (namespace || '').trim() || CONSOLE_LOGGER;\n\n    if (!gInitialized) {\n      ConsoleLogger.loadConfig();\n      gInitialized = true;\n    }\n\n    const key = [this.namespace, 'enable'];\n    this.enable = loadConfigValue(key, asBoolean, this.enable);\n    saveConfigValue(key, HAS_LOCAL_STORAGE ? (this.enable ? 'true' : 'false') : this.enable);\n  }\n\n  get isEnabled() {\n    return this.enable && ConsoleLogger.sharedConfig.enable;\n  }\n\n  get isDebug() {\n    return this.isEnabled && ConsoleLogger.sharedConfig.debug;\n  }\n\n  get isInfo() {\n    return this.isEnabled && ConsoleLogger.sharedConfig.info;\n  }\n\n  get isWarn() {\n    return this.isEnabled && ConsoleLogger.sharedConfig.warn;\n  }\n\n  debug(...args: any[]) {\n    this.#print('debug', ConsoleLogger.sharedStyles.debug, args);\n  }\n\n  info(...args: any[]) {\n    this.#print('info', ConsoleLogger.sharedStyles.info, args);\n  }\n\n  warn(...args: any[]) {\n    this.#print('warn', ConsoleLogger.sharedStyles.warn, args);\n  }\n\n  error(...args: any[]) {\n    this.#print('error', ConsoleLogger.sharedStyles.error, args);\n  }\n\n  #print(level: 'debug' | 'info' | 'warn' | 'error', styles: string, args: any[]) {\n    console[level](`%c${this.namespace}`, styles, ...args);\n  }\n}"],
-  "mappings": "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",
+  "sourcesContent": ["// https://developer.chrome.com/docs/devtools/console/format-style?hl=de\n\nexport const CONSOLE_LOGGER = 'ConsoleLogger';\nexport const CONSOLE_LOGGER_STORAGE = `${CONSOLE_LOGGER}Storage`;\n\n// A loopback host is the one place this library talks by default. `host` carries the port,\n// which a prefix test would have to get past -- and a prefix test says yes to every name that\n// merely begins with the word, `localhost.example.com` among them, while saying no to the\n// addresses that carry no name at all. So the port-free `hostname` is compared against the\n// exact set. A browser hands an IPv6 host over in brackets; the bare form is there for a\n// realm that does not.\nconst LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);\n\nconst IS_LOOPBACK_HOST = LOOPBACK_HOSTNAMES.has(globalThis.location?.hostname ?? '');\n\n// The name `localStorage` says nothing about a usable Storage behind it: node defines an inert\n// object on `globalThis`, and a browser with disabled cookies throws a `SecurityError` -- on the\n// property access or on the first write. So the capability is probed, not looked up, and the\n// storage that passes is kept by reference. Whatever fails here falls back to the plain object\n// under `globalThis.ConsoleLoggerStorage`.\nconst gLocalStorage: Storage | undefined = (() => {\n  try {\n    const storage = (globalThis as {localStorage?: Storage}).localStorage;\n    if (\n      typeof storage?.getItem !== 'function' ||\n      typeof storage.setItem !== 'function' ||\n      typeof storage.removeItem !== 'function'\n    ) {\n      return undefined;\n    }\n    // The write is what separates a Storage that only looks usable from one that is: cookies\n    // may be off, or the quota full. This probe key is the only thing the library writes into a\n    // host's storage on its own, and it is removed in the same breath -- everything past this\n    // point only reads, until a caller reaches through the handle under `globalThis.ConsoleLogger`.\n    // Two costs are accepted for the probe itself: one `storage` event pair for the other tabs of\n    // this origin, and a full quota that sends an otherwise readable Storage into the fallback.\n    const probeKey = `${CONSOLE_LOGGER}.probe`;\n    try {\n      storage.setItem(probeKey, probeKey);\n    } finally {\n      // reached even when `setItem` throws: a storage that takes the write and then fails would\n      // otherwise fall through to the fallback with the probe key left behind. One way past\n      // \"removed in the same breath\" stays open -- a `removeItem` that throws is the very call\n      // this `finally` makes, and the key survives.\n      storage.removeItem(probeKey);\n    }\n    return storage;\n  } catch {\n    return undefined;\n  }\n})();\n\nconst HAS_LOCAL_STORAGE = gLocalStorage != null;\n\nconst ConsoleLogger$: unique symbol = Symbol.for(CONSOLE_LOGGER);\n\nexport interface ConsoleLoggerConfig {\n  [ConsoleLogger$]?: boolean;\n  enable: boolean;\n  debug: boolean;\n  info: boolean;\n  warn: boolean;\n  'styles.debug': string;\n  'styles.info': string;\n  'styles.warn': string;\n  'styles.error': string;\n  [key: string]: string | boolean | undefined;\n}\n\nexport interface ConsoleLoggerControl {\n  [ConsoleLogger$]?: boolean;\n  enable: boolean;\n  debug: boolean;\n  info: boolean;\n  warn: boolean;\n}\n\n// A module-local view of the two globals this library touches, in place of a `declare global`:\n// the re-exports in this package's emitted `dist/src/index.d.ts`, published as `src/index.d.ts`,\n// reach every consumer's global type space through `ShadowEnv.d.ts`'s import of this module, and\n// `ConsoleLogger` is too common a name to claim there uninvited -- an ambient `var ConsoleLogger`\n// would collide with a consumer's own global of that name (`TS2403`) and turn a forgotten import\n// of this class into a silent pass against the handle instead of a compile error.\nconst gGlobalSlots = globalThis as typeof globalThis & {\n  ConsoleLogger?: ConsoleLoggerControl;\n  ConsoleLoggerStorage?: ConsoleLoggerConfig;\n};\n\nlet gInitialized = false;\n\nconst asBoolean = (val: string | boolean) => {\n  if (typeof val === 'boolean') return val;\n  switch (val.toLowerCase()) {\n    case 'true':\n    case 'yes':\n    case 'on':\n      return true;\n    default:\n      return false;\n  }\n};\n\nconst getKeyPath = (key: string | string[]): string =>\n  [HAS_LOCAL_STORAGE ? CONSOLE_LOGGER : undefined, ...(Array.isArray(key) ? key : [key])].filter(Boolean).join('.');\n\nfunction loadConfigValue<T>(key: string | string[], as: ((val: string | boolean) => T) | undefined, defaultValue: T): T {\n  const _key = getKeyPath(key);\n  const value = gLocalStorage ? gLocalStorage.getItem(_key) : gGlobalSlots.ConsoleLoggerStorage?.[_key];\n  if (value == undefined) return defaultValue;\n  // without a converter the stored value is the value: that is how the styles are read\n  return as ? as(value) : (value as T);\n}\n\n// The four setters of the `globalThis.ConsoleLogger` handle below are the only callers, and those\n// exist only inside the `HAS_LOCAL_STORAGE` branch of `loadConfig()` -- so `gLocalStorage` is\n// always set whenever this runs. The fallback store under `globalThis.ConsoleLoggerStorage` is\n// written by `loadConfig()` alone, and in the worker through `setConsoleLoggerStorage()`.\nfunction saveConfigValue(key: string | string[], val: any) {\n  if (gLocalStorage) {\n    gLocalStorage.setItem(getKeyPath(key), val);\n  }\n}\n\n/**\n * The key a config value is stored under. Prefixed with {@link CONSOLE_LOGGER} when it goes\n * into a real Storage, where it shares the namespace with everything else on this origin.\n */\nexport const consoleLoggerConfigKey = (key: string | string[]): string => getKeyPath(key);\n\n/**\n * Reads a raw config value through whatever storage the capability probe accepted, or from the\n * fallback object store when none did. The way to reach the config from outside this module:\n * `globalThis.localStorage` may be missing, inert or hostile, and asking it directly throws.\n */\nexport const loadConsoleLoggerConfig = (key: string | string[], defaultValue: string): string =>\n  loadConfigValue(key, undefined, defaultValue);\n\n/**\n * Installs a config object as the fallback store, bypassing the storage probe. `WorkerRuntime`\n * calls this with the config a `RemoteWorkerEnv` forwards from the main thread, where there is no\n * `localStorage` to probe in the first place.\n *\n * Once a logger exists in such a thread, `ConsoleLogger.sharedConfig` *is* that store, and the\n * values are written into it rather than a fresh object taking its place in the slot: the shared\n * switches reach every logger of the thread, the ones already built included. One flag stays\n * behind -- a logger reads its own `<namespace>.enable` key when it is built, and a config that\n * arrives afterwards no longer moves it.\n */\nexport function setConsoleLoggerStorage(config: ConsoleLoggerConfig): void {\n  const store = gGlobalSlots.ConsoleLoggerStorage;\n  if (store != null && store === ConsoleLogger.sharedConfig) {\n    // the marker travels with the merge: it says this object is the live config, and a config\n    // that crossed a worker boundary carries no symbol key to say so for itself\n    Object.assign(store, config, {[ConsoleLogger$]: true});\n    return;\n  }\n  gGlobalSlots.ConsoleLoggerStorage = config;\n}\n\nexport class ConsoleLogger {\n  namespace?: string;\n\n  enable = true;\n\n  static sharedConfig: ConsoleLoggerConfig = {\n    enable: IS_LOOPBACK_HOST,\n\n    debug: false,\n    info: true,\n    warn: true,\n\n    'styles.debug': 'color: #111; background: #999; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n    'styles.info': 'color: #020; background: #8a8; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n    'styles.warn': 'color: #fa0; background: #a98; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n    'styles.error': 'color: #ff0; background: #a00; display: inline-block; padding: 0 0.25em; margin: 0; border-radius: 0.25em',\n  };\n\n  static get isEnabled() {\n    return ConsoleLogger.sharedConfig.enable;\n  }\n\n  static get isDebug() {\n    return ConsoleLogger.sharedConfig.enable && ConsoleLogger.sharedConfig.debug;\n  }\n\n  static sharedStyles = {\n    get debug() {\n      return ConsoleLogger.sharedConfig['styles.debug'];\n    },\n    set debug(val: string) {\n      ConsoleLogger.sharedConfig['styles.debug'] = val;\n    },\n    get info() {\n      return ConsoleLogger.sharedConfig['styles.info'];\n    },\n    set info(val: string) {\n      ConsoleLogger.sharedConfig['styles.info'] = val;\n    },\n    get warn() {\n      return ConsoleLogger.sharedConfig['styles.warn'];\n    },\n    set warn(val: string) {\n      ConsoleLogger.sharedConfig['styles.warn'] = val;\n    },\n    get error() {\n      return ConsoleLogger.sharedConfig['styles.error'];\n    },\n    set error(val: string) {\n      ConsoleLogger.sharedConfig['styles.error'] = val;\n    },\n  };\n\n  static loadConfig() {\n    if (HAS_LOCAL_STORAGE) {\n      (['enable', 'debug', 'info', 'warn'] as const).forEach((key) => {\n        this.sharedConfig[key] = loadConfigValue(key, asBoolean, this.sharedConfig[key]);\n      });\n\n      (['debug', 'info', 'warn', 'error'] as const).forEach((key) => {\n        this.sharedStyles[key] = loadConfigValue(['styles', key], undefined, this.sharedStyles[key]);\n      });\n\n      if (ConsoleLogger.isDebug) {\n        console.debug(`${CONSOLE_LOGGER}: Load config from localStorage`, ConsoleLogger.sharedConfig);\n      }\n\n      if (!gGlobalSlots.ConsoleLogger?.[ConsoleLogger$]) {\n        gGlobalSlots.ConsoleLogger ??= {\n          [ConsoleLogger$]: true,\n\n          get enable() {\n            return ConsoleLogger.sharedConfig.enable;\n          },\n          set enable(val: boolean) {\n            ConsoleLogger.sharedConfig.enable = val;\n            saveConfigValue('enable', val ? 'true' : 'false');\n          },\n          get debug() {\n            return ConsoleLogger.sharedConfig.debug;\n          },\n          set debug(val: boolean) {\n            ConsoleLogger.sharedConfig.debug = val;\n            saveConfigValue('debug', val ? 'true' : 'false');\n          },\n          get info() {\n            return ConsoleLogger.sharedConfig.info;\n          },\n          set info(val: boolean) {\n            ConsoleLogger.sharedConfig.info = val;\n            saveConfigValue('info', val ? 'true' : 'false');\n          },\n          get warn() {\n            return ConsoleLogger.sharedConfig.warn;\n          },\n          set warn(val: boolean) {\n            ConsoleLogger.sharedConfig.warn = val;\n            saveConfigValue('warn', val ? 'true' : 'false');\n          },\n        };\n      }\n    } else {\n      // no localStorage available: in this case we just use gGlobalSlots.ConsoleLoggerStorage\n      if (!gGlobalSlots.ConsoleLoggerStorage?.[ConsoleLogger$]) {\n        gGlobalSlots.ConsoleLoggerStorage = {\n          [ConsoleLogger$]: true,\n          ...ConsoleLogger.sharedConfig,\n          ...gGlobalSlots.ConsoleLoggerStorage,\n        };\n        ConsoleLogger.sharedConfig = gGlobalSlots.ConsoleLoggerStorage;\n        if (ConsoleLogger.isDebug) {\n          console.debug(`${CONSOLE_LOGGER}: Load config from ${CONSOLE_LOGGER_STORAGE}`, gGlobalSlots.ConsoleLoggerStorage);\n        }\n      }\n    }\n  }\n\n  constructor(namespace: string) {\n    this.namespace = (namespace || '').trim() || CONSOLE_LOGGER;\n\n    if (!gInitialized) {\n      ConsoleLogger.loadConfig();\n      gInitialized = true;\n    }\n\n    // reads only: the storage of the host is never written here. The only way this library\n    // writes to it is through the four setters of the `globalThis.ConsoleLogger` handle above.\n    const key = [this.namespace, 'enable'];\n    this.enable = loadConfigValue(key, asBoolean, this.enable);\n  }\n\n  get isEnabled() {\n    return this.enable && ConsoleLogger.sharedConfig.enable;\n  }\n\n  get isDebug() {\n    return this.isEnabled && ConsoleLogger.sharedConfig.debug;\n  }\n\n  get isInfo() {\n    return this.isEnabled && ConsoleLogger.sharedConfig.info;\n  }\n\n  get isWarn() {\n    return this.isEnabled && ConsoleLogger.sharedConfig.warn;\n  }\n\n  debug(...args: any[]) {\n    if (!this.isDebug) return;\n    this.#print('debug', ConsoleLogger.sharedStyles.debug, args);\n  }\n\n  info(...args: any[]) {\n    if (!this.isInfo) return;\n    this.#print('info', ConsoleLogger.sharedStyles.info, args);\n  }\n\n  warn(...args: any[]) {\n    if (!this.isWarn) return;\n    this.#print('warn', ConsoleLogger.sharedStyles.warn, args);\n  }\n\n  // An error report names a fault in the calling code, and its author has to see it wherever\n  // the application runs -- not only on a loopback host, so `error()` asks no getter.\n  error(...args: any[]) {\n    this.#print('error', ConsoleLogger.sharedStyles.error, args);\n  }\n\n  #print(level: 'debug' | 'info' | 'warn' | 'error', styles: string, args: any[]) {\n    console[level](`%c${this.namespace}`, styles, ...args);\n  }\n}\n"],
+  "mappings": "AAEO,MAAM,iBAAiB;AACvB,MAAM,yBAAyB,GAAG,cAAc;AAQvD,MAAM,qBAAqB,oBAAI,IAAI,CAAC,aAAa,aAAa,OAAO,OAAO,CAAC;AAE7E,MAAM,mBAAmB,mBAAmB,IAAI,WAAW,UAAU,YAAY,EAAE;AAOnF,MAAM,iBAAsC,MAAM;AAChD,MAAI;AACF,UAAM,UAAW,WAAwC;AACzD,QACE,OAAO,SAAS,YAAY,cAC5B,OAAO,QAAQ,YAAY,cAC3B,OAAO,QAAQ,eAAe,YAC9B;AACA,aAAO;AAAA,IACT;AAOA,UAAM,WAAW,GAAG,cAAc;AAClC,QAAI;AACF,cAAQ,QAAQ,UAAU,QAAQ;AAAA,IACpC,UAAE;AAKA,cAAQ,WAAW,QAAQ;AAAA,IAC7B;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF,GAAG;AAEH,MAAM,oBAAoB,iBAAiB;AAE3C,MAAM,iBAAgC,OAAO,IAAI,cAAc;AA6B/D,MAAM,eAAe;AAKrB,IAAI,eAAe;AAEnB,MAAM,YAAY,CAAC,QAA0B;AAC3C,MAAI,OAAO,QAAQ,UAAW,QAAO;AACrC,UAAQ,IAAI,YAAY,GAAG;AAAA,IACzB,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAEA,MAAM,aAAa,CAAC,QAClB,CAAC,oBAAoB,iBAAiB,QAAW,GAAI,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,GAAG,CAAE,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG;AAElH,SAAS,gBAAmB,KAAwB,IAAgD,cAAoB;AACtH,QAAM,OAAO,WAAW,GAAG;AAC3B,QAAM,QAAQ,gBAAgB,cAAc,QAAQ,IAAI,IAAI,aAAa,uBAAuB,IAAI;AACpG,MAAI,SAAS,OAAW,QAAO;AAE/B,SAAO,KAAK,GAAG,KAAK,IAAK;AAC3B;AAMA,SAAS,gBAAgB,KAAwB,KAAU;AACzD,MAAI,eAAe;AACjB,kBAAc,QAAQ,WAAW,GAAG,GAAG,GAAG;AAAA,EAC5C;AACF;AAMO,MAAM,yBAAyB,CAAC,QAAmC,WAAW,GAAG;AAOjF,MAAM,0BAA0B,CAAC,KAAwB,iBAC9D,gBAAgB,KAAK,QAAW,YAAY;AAavC,SAAS,wBAAwB,QAAmC;AACzE,QAAM,QAAQ,aAAa;AAC3B,MAAI,SAAS,QAAQ,UAAU,cAAc,cAAc;AAGzD,WAAO,OAAO,OAAO,QAAQ,EAAC,CAAC,cAAc,GAAG,KAAI,CAAC;AACrD;AAAA,EACF;AACA,eAAa,uBAAuB;AACtC;AAEO,MAAM,cAAc;AAAA,EAqHzB,YAAY,WAAmB;AAlH/B,kBAAS;AAmHP,SAAK,aAAa,aAAa,IAAI,KAAK,KAAK;AAE7C,QAAI,CAAC,cAAc;AACjB,oBAAc,WAAW;AACzB,qBAAe;AAAA,IACjB;AAIA,UAAM,MAAM,CAAC,KAAK,WAAW,QAAQ;AACrC,SAAK,SAAS,gBAAgB,KAAK,WAAW,KAAK,MAAM;AAAA,EAC3D;AAAA,EA5HA;AAAA,SAAO,eAAoC;AAAA,MACzC,QAAQ;AAAA,MAER,OAAO;AAAA,MACP,MAAM;AAAA,MACN,MAAM;AAAA,MAEN,gBAAgB;AAAA,MAChB,eAAe;AAAA,MACf,eAAe;AAAA,MACf,gBAAgB;AAAA,IAClB;AAAA;AAAA,EAEA,WAAW,YAAY;AACrB,WAAO,cAAc,aAAa;AAAA,EACpC;AAAA,EAEA,WAAW,UAAU;AACnB,WAAO,cAAc,aAAa,UAAU,cAAc,aAAa;AAAA,EACzE;AAAA,EAEA;AAAA,SAAO,eAAe;AAAA,MACpB,IAAI,QAAQ;AACV,eAAO,cAAc,aAAa,cAAc;AAAA,MAClD;AAAA,MACA,IAAI,MAAM,KAAa;AACrB,sBAAc,aAAa,cAAc,IAAI;AAAA,MAC/C;AAAA,MACA,IAAI,OAAO;AACT,eAAO,cAAc,aAAa,aAAa;AAAA,MACjD;AAAA,MACA,IAAI,KAAK,KAAa;AACpB,sBAAc,aAAa,aAAa,IAAI;AAAA,MAC9C;AAAA,MACA,IAAI,OAAO;AACT,eAAO,cAAc,aAAa,aAAa;AAAA,MACjD;AAAA,MACA,IAAI,KAAK,KAAa;AACpB,sBAAc,aAAa,aAAa,IAAI;AAAA,MAC9C;AAAA,MACA,IAAI,QAAQ;AACV,eAAO,cAAc,aAAa,cAAc;AAAA,MAClD;AAAA,MACA,IAAI,MAAM,KAAa;AACrB,sBAAc,aAAa,cAAc,IAAI;AAAA,MAC/C;AAAA,IACF;AAAA;AAAA,EAEA,OAAO,aAAa;AAClB,QAAI,mBAAmB;AACrB,MAAC,CAAC,UAAU,SAAS,QAAQ,MAAM,EAAY,QAAQ,CAAC,QAAQ;AAC9D,aAAK,aAAa,GAAG,IAAI,gBAAgB,KAAK,WAAW,KAAK,aAAa,GAAG,CAAC;AAAA,MACjF,CAAC;AAED,MAAC,CAAC,SAAS,QAAQ,QAAQ,OAAO,EAAY,QAAQ,CAAC,QAAQ;AAC7D,aAAK,aAAa,GAAG,IAAI,gBAAgB,CAAC,UAAU,GAAG,GAAG,QAAW,KAAK,aAAa,GAAG,CAAC;AAAA,MAC7F,CAAC;AAED,UAAI,cAAc,SAAS;AACzB,gBAAQ,MAAM,GAAG,cAAc,mCAAmC,cAAc,YAAY;AAAA,MAC9F;AAEA,UAAI,CAAC,aAAa,gBAAgB,cAAc,GAAG;AACjD,qBAAa,kBAAkB;AAAA,UAC7B,CAAC,cAAc,GAAG;AAAA,UAElB,IAAI,SAAS;AACX,mBAAO,cAAc,aAAa;AAAA,UACpC;AAAA,UACA,IAAI,OAAO,KAAc;AACvB,0BAAc,aAAa,SAAS;AACpC,4BAAgB,UAAU,MAAM,SAAS,OAAO;AAAA,UAClD;AAAA,UACA,IAAI,QAAQ;AACV,mBAAO,cAAc,aAAa;AAAA,UACpC;AAAA,UACA,IAAI,MAAM,KAAc;AACtB,0BAAc,aAAa,QAAQ;AACnC,4BAAgB,SAAS,MAAM,SAAS,OAAO;AAAA,UACjD;AAAA,UACA,IAAI,OAAO;AACT,mBAAO,cAAc,aAAa;AAAA,UACpC;AAAA,UACA,IAAI,KAAK,KAAc;AACrB,0BAAc,aAAa,OAAO;AAClC,4BAAgB,QAAQ,MAAM,SAAS,OAAO;AAAA,UAChD;AAAA,UACA,IAAI,OAAO;AACT,mBAAO,cAAc,aAAa;AAAA,UACpC;AAAA,UACA,IAAI,KAAK,KAAc;AACrB,0BAAc,aAAa,OAAO;AAClC,4BAAgB,QAAQ,MAAM,SAAS,OAAO;AAAA,UAChD;AAAA,QACF;AAAA,MACF;AAAA,IACF,OAAO;AAEL,UAAI,CAAC,aAAa,uBAAuB,cAAc,GAAG;AACxD,qBAAa,uBAAuB;AAAA,UAClC,CAAC,cAAc,GAAG;AAAA,UAClB,GAAG,cAAc;AAAA,UACjB,GAAG,aAAa;AAAA,QAClB;AACA,sBAAc,eAAe,aAAa;AAC1C,YAAI,cAAc,SAAS;AACzB,kBAAQ,MAAM,GAAG,cAAc,sBAAsB,sBAAsB,IAAI,aAAa,oBAAoB;AAAA,QAClH;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAgBA,IAAI,YAAY;AACd,WAAO,KAAK,UAAU,cAAc,aAAa;AAAA,EACnD;AAAA,EAEA,IAAI,UAAU;AACZ,WAAO,KAAK,aAAa,cAAc,aAAa;AAAA,EACtD;AAAA,EAEA,IAAI,SAAS;AACX,WAAO,KAAK,aAAa,cAAc,aAAa;AAAA,EACtD;AAAA,EAEA,IAAI,SAAS;AACX,WAAO,KAAK,aAAa,cAAc,aAAa;AAAA,EACtD;AAAA,EAEA,SAAS,MAAa;AACpB,QAAI,CAAC,KAAK,QAAS;AACnB,SAAK,OAAO,SAAS,cAAc,aAAa,OAAO,IAAI;AAAA,EAC7D;AAAA,EAEA,QAAQ,MAAa;AACnB,QAAI,CAAC,KAAK,OAAQ;AAClB,SAAK,OAAO,QAAQ,cAAc,aAAa,MAAM,IAAI;AAAA,EAC3D;AAAA,EAEA,QAAQ,MAAa;AACnB,QAAI,CAAC,KAAK,OAAQ;AAClB,SAAK,OAAO,QAAQ,cAAc,aAAa,MAAM,IAAI;AAAA,EAC3D;AAAA;AAAA;AAAA,EAIA,SAAS,MAAa;AACpB,SAAK,OAAO,SAAS,cAAc,aAAa,OAAO,IAAI;AAAA,EAC7D;AAAA,EAEA,OAAO,OAA4C,QAAgB,MAAa;AAC9E,YAAQ,KAAK,EAAE,KAAK,KAAK,SAAS,IAAI,QAAQ,GAAG,IAAI;AAAA,EACvD;AACF;",
   "names": []
 }

package/src/utils/FrameLoop.d.ts

@@ -1,8 +1,47 @@
+import { type ListenerFuncType } from '@spearwolf/eventize';
+/**
+ * The payload of every {@link FrameLoop.OnFrame} event. All times are in seconds.
+ */
+export interface FrameData {
+    /** the timestamp of this frame */
+    now: number;
+    /** the timestamp of the frame before this one — equal to {@link FrameData.now} on the first frame */
+    lastNow: number;
+    /** the number of this frame, counted from one at the start of every run */
+    frameNo: number;
+    /** the time elapsed since the frame before this one — zero on the first frame */
+    deltaTime: number;
+}
+/**
+ * A loop that emits a frame to all of its targets as long as at least one of them listens.
+ *
+ * While no target listens, the loop asks for no frames at all.
+ *
+ * A target that throws costs itself its frame and nothing else: the frame still reaches every
+ * other target, and the loop asks for the frame behind it. The failure is reported through
+ * `console.warn` and reaches no caller -- see `#onFrame()` for why this loop answers a failing
+ * target that way and not through the `ConsoleLogger` the rest of this package reports through.
+ */
 export declare class FrameLoop {
     #private;
     static OnFrame: symbol;
-    constructor();
-    start(target: object | Function): () => void;
-    stop(target: object | Function): void;
+    /**
+     * The loop that every caller shares. It is created on first read and answers the same instance
+     * afterwards. It has no cap on the frame rate.
+     */
+    static get(): FrameLoop;
+    constructor(maxFps?: number);
+    /** The upper bound on the frame rate. Zero means: no bound. */
+    get maxFps(): number;
+    set maxFps(fps: number);
+    /**
+     * How many targets listen for frames.
+     *
+     * OnFrame is the only event this object knows, so the total number of subscriptions is the
+     * number of frame targets.
+     */
+    get subscriptionCount(): number;
+    start(target: object | ListenerFuncType): (() => void) | undefined;
+    stop(target: object | ListenerFuncType): void;
 }
 //# sourceMappingURL=FrameLoop.d.ts.map

package/src/utils/FrameLoop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrameLoop.d.ts","sourceRoot":"","sources":["../../../src/utils/FrameLoop.ts"],"names":[],"mappings":"AAIA,qBAAa,SAAS;;IACpB,MAAM,CAAC,OAAO,SAAqB;;IAWnC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAgB/B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;CAqB/B"}
+{"version":3,"file":"FrameLoop.d.ts","sourceRoot":"","sources":["../../../src/utils/FrameLoop.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2C,KAAK,gBAAgB,EAAU,MAAM,qBAAqB,CAAC;AAI7G;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAS;;IACpB,MAAM,CAAC,OAAO,SAAqB;IAEnC;;;OAGG;IACH,MAAM,CAAC,GAAG,IAAI,SAAS,CAGtB;IAsBD,YAAY,MAAM,SAAI,EAGrB;IAED,+DAA+D;IAC/D,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,MAAM,CAAC,GAAG,EAAE,MAAM,EAErB;IAED;;;;;OAKG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,4BAUtC;IAED,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,QAYrC;CA8DF"}

package/src/utils/FrameLoop.js

@@ -1,41 +1,100 @@
-import { emit, eventize, getSubscriptionCount, off, on } from "@spearwolf/eventize";
+import { emitSafe, eventize, getSubscriptionCount, off, on } from "@spearwolf/eventize";
 let gUniqInstance = null;
 class FrameLoop {
   static {
     this.OnFrame = /* @__PURE__ */ Symbol("onFrame");
   }
+  /**
+   * The loop that every caller shares. It is created on first read and answers the same instance
+   * afterwards. It has no cap on the frame rate.
+   */
+  static get() {
+    gUniqInstance ??= new FrameLoop();
+    return gUniqInstance;
+  }
+  /**
+   * The share of the nominal frame time after which the next frame is due.
+   *
+   * Animation frames do not arrive at the nominal distance, and the browsers differ in how coarsely
+   * they round the timestamps they hand out. With `D` for the distance between real frames and `j`
+   * for the jitter on top of it, the factor has to sit between two bounds:
+   *
+   * - a cap at or above the refresh rate must lose no frame: `factor <= 1 - j / D`
+   * - a cap at half the refresh rate must drop every second frame: `factor > 0.5 + j / (2 * D)`
+   *
+   * At 60 Hz with the coarsest rounding measured — around 0.6 ms of jitter on a 16.67 ms
+   * distance — that leaves the range 0.52 to 0.96, and this value keeps its distance to both ends.
+   */
+  static #DueFactor = 0.75;
   #rafID = 0;
-  #subscriptionCount = 0;
-  constructor() {
-    if (gUniqInstance) return gUniqInstance;
+  #maxFps = 0;
+  #frameNo = 0;
+  #lastNow = void 0;
+  constructor(maxFps = 0) {
     eventize(this);
-    gUniqInstance = this;
+    this.maxFps = maxFps;
+  }
+  /** The upper bound on the frame rate. Zero means: no bound. */
+  get maxFps() {
+    return this.#maxFps;
+  }
+  set maxFps(fps) {
+    this.#maxFps = Number.isFinite(fps) && fps > 0 ? fps : 0;
+  }
+  /**
+   * How many targets listen for frames.
+   *
+   * OnFrame is the only event this object knows, so the total number of subscriptions is the
+   * number of frame targets.
+   */
+  get subscriptionCount() {
+    return getSubscriptionCount(this);
   }
   start(target) {
     if (target == null) return;
-    if (getSubscriptionCount(this) === 0) {
-      this.#requestAnimationFrame();
-    }
     on(this, FrameLoop.OnFrame, target);
-    this.#subscriptionCount++;
+    this.#requestAnimationFrame();
     return () => {
       this.stop(target);
     };
   }
   stop(target) {
+    if (target == null) return;
     off(this, FrameLoop.OnFrame, target);
-    if (getSubscriptionCount(this) === 0) {
+    if (this.subscriptionCount === 0) {
       this.#cancelAnimationFrame();
+      this.#lastNow = void 0;
+      this.#frameNo = 0;
     }
   }
   #onFrame = (now) => {
-    emit(this, FrameLoop.OnFrame, now);
-    this.#requestAnimationFrame();
+    this.#rafID = 0;
+    if (this.#isDue(now)) {
+      const lastNow = this.#lastNow ?? now;
+      this.#lastNow = now;
+      this.#frameNo += 1;
+      const frameData = {
+        now: now / 1e3,
+        lastNow: lastNow / 1e3,
+        frameNo: this.#frameNo,
+        deltaTime: (now - lastNow) / 1e3
+      };
+      emitSafe(this, FrameLoop.OnFrame, frameData);
+    }
+    if (this.subscriptionCount > 0) {
+      this.#requestAnimationFrame();
+    }
   };
+  #isDue(now) {
+    if (this.#maxFps === 0 || this.#lastNow === void 0) return true;
+    return now - this.#lastNow >= FrameLoop.#DueFactor * (1e3 / this.#maxFps);
+  }
   #requestAnimationFrame() {
+    if (this.#rafID !== 0) return;
     this.#rafID = requestAnimationFrame(this.#onFrame);
   }
   #cancelAnimationFrame() {
+    if (this.#rafID === 0) return;
     cancelAnimationFrame(this.#rafID);
     this.#rafID = 0;
   }

package/src/utils/FrameLoop.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/utils/FrameLoop.ts"],
-  "sourcesContent": ["import {emit, eventize, getSubscriptionCount, off, on} from '@spearwolf/eventize';\n\nlet gUniqInstance: FrameLoop = null;\n\nexport class FrameLoop {\n  static OnFrame = Symbol('onFrame');\n\n  #rafID = 0;\n  #subscriptionCount = 0;\n\n  constructor() {\n    if (gUniqInstance) return gUniqInstance;\n    eventize(this);\n    gUniqInstance = this;\n  }\n\n  start(target: object | Function) {\n    if (target == null) return;\n\n    if (getSubscriptionCount(this) === 0) {\n      this.#requestAnimationFrame();\n    }\n\n    on(this as FrameLoop, FrameLoop.OnFrame, target);\n\n    this.#subscriptionCount++;\n\n    return () => {\n      this.stop(target);\n    };\n  }\n\n  stop(target: object | Function) {\n    off(this, FrameLoop.OnFrame, target);\n\n    if (getSubscriptionCount(this) === 0) {\n      this.#cancelAnimationFrame();\n    }\n  }\n\n  #onFrame = (now: number) => {\n    emit(this as FrameLoop, FrameLoop.OnFrame, now);\n    this.#requestAnimationFrame();\n  };\n\n  #requestAnimationFrame() {\n    this.#rafID = requestAnimationFrame(this.#onFrame);\n  }\n\n  #cancelAnimationFrame() {\n    cancelAnimationFrame(this.#rafID);\n    this.#rafID = 0;\n  }\n}"],
-  "mappings": "AAAA,SAAQ,MAAM,UAAU,sBAAsB,KAAK,UAAS;AAE5D,IAAI,gBAA2B;AAExB,MAAM,UAAU;AAAA,EACrB;AAAA,SAAO,UAAU,uBAAO,SAAS;AAAA;AAAA,EAEjC,SAAS;AAAA,EACT,qBAAqB;AAAA,EAErB,cAAc;AACZ,QAAI,cAAe,QAAO;AAC1B,aAAS,IAAI;AACb,oBAAgB;AAAA,EAClB;AAAA,EAEA,MAAM,QAA2B;AAC/B,QAAI,UAAU,KAAM;AAEpB,QAAI,qBAAqB,IAAI,MAAM,GAAG;AACpC,WAAK,uBAAuB;AAAA,IAC9B;AAEA,OAAG,MAAmB,UAAU,SAAS,MAAM;AAE/C,SAAK;AAEL,WAAO,MAAM;AACX,WAAK,KAAK,MAAM;AAAA,IAClB;AAAA,EACF;AAAA,EAEA,KAAK,QAA2B;AAC9B,QAAI,MAAM,UAAU,SAAS,MAAM;AAEnC,QAAI,qBAAqB,IAAI,MAAM,GAAG;AACpC,WAAK,sBAAsB;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,WAAW,CAAC,QAAgB;AAC1B,SAAK,MAAmB,UAAU,SAAS,GAAG;AAC9C,SAAK,uBAAuB;AAAA,EAC9B;AAAA,EAEA,yBAAyB;AACvB,SAAK,SAAS,sBAAsB,KAAK,QAAQ;AAAA,EACnD;AAAA,EAEA,wBAAwB;AACtB,yBAAqB,KAAK,MAAM;AAChC,SAAK,SAAS;AAAA,EAChB;AACF;",
+  "sourcesContent": ["import {emitSafe, eventize, getSubscriptionCount, type ListenerFuncType, off, on} from '@spearwolf/eventize';\n\nlet gUniqInstance: FrameLoop | null = null;\n\n/**\n * The payload of every {@link FrameLoop.OnFrame} event. All times are in seconds.\n */\nexport interface FrameData {\n  /** the timestamp of this frame */\n  now: number;\n  /** the timestamp of the frame before this one \u2014 equal to {@link FrameData.now} on the first frame */\n  lastNow: number;\n  /** the number of this frame, counted from one at the start of every run */\n  frameNo: number;\n  /** the time elapsed since the frame before this one \u2014 zero on the first frame */\n  deltaTime: number;\n}\n\n/**\n * A loop that emits a frame to all of its targets as long as at least one of them listens.\n *\n * While no target listens, the loop asks for no frames at all.\n *\n * A target that throws costs itself its frame and nothing else: the frame still reaches every\n * other target, and the loop asks for the frame behind it. The failure is reported through\n * `console.warn` and reaches no caller -- see `#onFrame()` for why this loop answers a failing\n * target that way and not through the `ConsoleLogger` the rest of this package reports through.\n */\nexport class FrameLoop {\n  static OnFrame = Symbol('onFrame');\n\n  /**\n   * The loop that every caller shares. It is created on first read and answers the same instance\n   * afterwards. It has no cap on the frame rate.\n   */\n  static get(): FrameLoop {\n    gUniqInstance ??= new FrameLoop();\n    return gUniqInstance;\n  }\n\n  /**\n   * The share of the nominal frame time after which the next frame is due.\n   *\n   * Animation frames do not arrive at the nominal distance, and the browsers differ in how coarsely\n   * they round the timestamps they hand out. With `D` for the distance between real frames and `j`\n   * for the jitter on top of it, the factor has to sit between two bounds:\n   *\n   * - a cap at or above the refresh rate must lose no frame: `factor <= 1 - j / D`\n   * - a cap at half the refresh rate must drop every second frame: `factor > 0.5 + j / (2 * D)`\n   *\n   * At 60 Hz with the coarsest rounding measured \u2014 around 0.6 ms of jitter on a 16.67 ms\n   * distance \u2014 that leaves the range 0.52 to 0.96, and this value keeps its distance to both ends.\n   */\n  static #DueFactor = 0.75;\n\n  #rafID = 0;\n  #maxFps = 0;\n  #frameNo = 0;\n  #lastNow: number | undefined = undefined;\n\n  constructor(maxFps = 0) {\n    eventize(this);\n    this.maxFps = maxFps;\n  }\n\n  /** The upper bound on the frame rate. Zero means: no bound. */\n  get maxFps(): number {\n    return this.#maxFps;\n  }\n\n  set maxFps(fps: number) {\n    this.#maxFps = Number.isFinite(fps) && fps > 0 ? fps : 0;\n  }\n\n  /**\n   * How many targets listen for frames.\n   *\n   * OnFrame is the only event this object knows, so the total number of subscriptions is the\n   * number of frame targets.\n   */\n  get subscriptionCount(): number {\n    return getSubscriptionCount(this);\n  }\n\n  start(target: object | ListenerFuncType) {\n    if (target == null) return;\n\n    on(this as FrameLoop, FrameLoop.OnFrame, target);\n\n    this.#requestAnimationFrame();\n\n    return () => {\n      this.stop(target);\n    };\n  }\n\n  stop(target: object | ListenerFuncType) {\n    if (target == null) return;\n\n    off(this, FrameLoop.OnFrame, target);\n\n    if (this.subscriptionCount === 0) {\n      this.#cancelAnimationFrame();\n      // the next target to arrive starts a fresh run of frames: its first frame is frame one and\n      // reports no delta, rather than the whole length of the pause\n      this.#lastNow = undefined;\n      this.#frameNo = 0;\n    }\n  }\n\n  #onFrame = (now: number) => {\n    // the frame this id stands for has fired, nothing is pending any more \u2014 a target that leaves\n    // during the emit below must be able to see that\n    this.#rafID = 0;\n\n    if (this.#isDue(now)) {\n      const lastNow = this.#lastNow ?? now;\n\n      this.#lastNow = now;\n      this.#frameNo += 1;\n\n      const frameData: FrameData = {\n        now: now / 1000,\n        lastNow: lastNow / 1000,\n        frameNo: this.#frameNo,\n        deltaTime: (now - lastNow) / 1000,\n      };\n\n      // `emitSafe()` rather than `emit()`, and the reason is the singleton above: one loop serves\n      // every target in the realm, so a target that throws may cost neither the targets behind it\n      // their frame nor the loop its next one. The plain dispatch would do both -- it ends at the\n      // first listener that throws and hands the error back to the `requestAnimationFrame()`\n      // callback, past the line below that asks for the frame after this one. `#rafID` is already\n      // back at 0 at that point, so nothing would ever ask again and the loop would stand still\n      // for the whole page without a word.\n      //\n      // What a target loses in exchange is the report: `emitSafe()` writes to `console.warn` and\n      // hands out no error. That is the right trade here. `FrameLoop` is a singleton with no\n      // `ConsoleLogger` of its own, and a frame target that throws does so at the frame rate --\n      // whichever channel carries it, the first report says everything the hundredth does.\n      emitSafe(this as FrameLoop, FrameLoop.OnFrame, frameData);\n    }\n\n    if (this.subscriptionCount > 0) {\n      // a skipped frame arms again just like an emitted one, otherwise the cap would bring the\n      // loop to a halt after the first frame it holds back\n      this.#requestAnimationFrame();\n    }\n  };\n\n  #isDue(now: number): boolean {\n    if (this.#maxFps === 0 || this.#lastNow === undefined) return true;\n\n    return now - this.#lastNow >= FrameLoop.#DueFactor * (1000 / this.#maxFps);\n  }\n\n  #requestAnimationFrame() {\n    // idempotent: two pending frames would mean two loops, and only the second of them could ever\n    // be cancelled again\n    if (this.#rafID !== 0) return;\n\n    this.#rafID = requestAnimationFrame(this.#onFrame);\n  }\n\n  #cancelAnimationFrame() {\n    if (this.#rafID === 0) return;\n\n    cancelAnimationFrame(this.#rafID);\n    this.#rafID = 0;\n  }\n}\n"],
+  "mappings": "AAAA,SAAQ,UAAU,UAAU,sBAA6C,KAAK,UAAS;AAEvF,IAAI,gBAAkC;AA0B/B,MAAM,UAAU;AAAA,EACrB;AAAA,SAAO,UAAU,uBAAO,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjC,OAAO,MAAiB;AACtB,sBAAkB,IAAI,UAAU;AAChC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,OAAO,aAAa;AAAA,EAEpB,SAAS;AAAA,EACT,UAAU;AAAA,EACV,WAAW;AAAA,EACX,WAA+B;AAAA,EAE/B,YAAY,SAAS,GAAG;AACtB,aAAS,IAAI;AACb,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA,EAGA,IAAI,SAAiB;AACnB,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,OAAO,KAAa;AACtB,SAAK,UAAU,OAAO,SAAS,GAAG,KAAK,MAAM,IAAI,MAAM;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,oBAA4B;AAC9B,WAAO,qBAAqB,IAAI;AAAA,EAClC;AAAA,EAEA,MAAM,QAAmC;AACvC,QAAI,UAAU,KAAM;AAEpB,OAAG,MAAmB,UAAU,SAAS,MAAM;AAE/C,SAAK,uBAAuB;AAE5B,WAAO,MAAM;AACX,WAAK,KAAK,MAAM;AAAA,IAClB;AAAA,EACF;AAAA,EAEA,KAAK,QAAmC;AACtC,QAAI,UAAU,KAAM;AAEpB,QAAI,MAAM,UAAU,SAAS,MAAM;AAEnC,QAAI,KAAK,sBAAsB,GAAG;AAChC,WAAK,sBAAsB;AAG3B,WAAK,WAAW;AAChB,WAAK,WAAW;AAAA,IAClB;AAAA,EACF;AAAA,EAEA,WAAW,CAAC,QAAgB;AAG1B,SAAK,SAAS;AAEd,QAAI,KAAK,OAAO,GAAG,GAAG;AACpB,YAAM,UAAU,KAAK,YAAY;AAEjC,WAAK,WAAW;AAChB,WAAK,YAAY;AAEjB,YAAM,YAAuB;AAAA,QAC3B,KAAK,MAAM;AAAA,QACX,SAAS,UAAU;AAAA,QACnB,SAAS,KAAK;AAAA,QACd,YAAY,MAAM,WAAW;AAAA,MAC/B;AAcA,eAAS,MAAmB,UAAU,SAAS,SAAS;AAAA,IAC1D;AAEA,QAAI,KAAK,oBAAoB,GAAG;AAG9B,WAAK,uBAAuB;AAAA,IAC9B;AAAA,EACF;AAAA,EAEA,OAAO,KAAsB;AAC3B,QAAI,KAAK,YAAY,KAAK,KAAK,aAAa,OAAW,QAAO;AAE9D,WAAO,MAAM,KAAK,YAAY,UAAU,cAAc,MAAO,KAAK;AAAA,EACpE;AAAA,EAEA,yBAAyB;AAGvB,QAAI,KAAK,WAAW,EAAG;AAEvB,SAAK,SAAS,sBAAsB,KAAK,QAAQ;AAAA,EACnD;AAAA,EAEA,wBAAwB;AACtB,QAAI,KAAK,WAAW,EAAG;AAEvB,yBAAqB,KAAK,MAAM;AAChC,SAAK,SAAS;AAAA,EAChB;AACF;",
   "names": []
 }

package/src/utils/MicrotaskCollector.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The arguments of {@link MicrotaskCollector.add}: a collector without a payload is asked for the
+ * key alone, one that carries a payload is asked for both.
+ */
+type AddArgs<K, V> = undefined extends V ? [key: K, value?: V] : [key: K, value: V];
+/**
+ * Collects what is written in one task and hands it over a microtask later, in one batch.
+ *
+ * A second value for the same key replaces the one waiting, so a key written twice in a task
+ * reaches the delivery once, with the value that stood at the end of it.
+ *
+ * Two rules live here so that no site has to decide them again:
+ *
+ * The batch is taken out and emptied **before** the first delivery. A delivery can write to this
+ * collector -- a reader of a context value writes a context of its own, an entity that arrives
+ * while a round goes out asks for a round -- and that write belongs to the round behind this one
+ * rather than to the batch being walked. Emptying afterwards would also lose the batch to a
+ * delivery that throws: the flag is already down by then, so the next write queues a fresh
+ * microtask and hands the stale entries over a second time.
+ *
+ * Every delivery a site makes runs under `runGuarded()`. Entries that arrived in the same task are
+ * independent of one another, and one that fails costs itself and nothing behind it -- the promise
+ * `docs/api-reference.md` already spells out for context values. What counts as one delivery is
+ * the site's to say: `Entity` delivers per entry, `ComponentContext` groups its senders
+ * into rounds first and delivers per round.
+ *
+ * For a booking that has to be callable off again, see `DeferredTeardown`; for a single
+ * deferred action without a batch, `MicrotaskGate`.
+ */
+export declare class MicrotaskCollector<K, V = undefined> {
+    #private;
+    constructor(deliver: (entries: Map<K, V>) => void);
+    /** Put an entry into the batch and make sure someone comes to fetch it. */
+    add(...[key, value]: AddArgs<K, V>): void;
+    /**
+     * Hand the batch over now.
+     *
+     * For a caller that needs the batch delivered at a point of its own choosing rather than
+     * whenever the microtask comes round. A queued microtask that finds nothing left returns without
+     * a delivery, so an early flush costs nothing but the ordering it was asked for.
+     */
+    flush(): void;
+}
+export {};
+//# sourceMappingURL=MicrotaskCollector.d.ts.map

package/src/utils/MicrotaskCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicrotaskCollector.d.ts","sourceRoot":"","sources":["../../../src/utils/MicrotaskCollector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,IAAI,SAAS,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAkB,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS;;IAM9C,YAAY,OAAO,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,EAEhD;IAED,2EAA2E;IAC3E,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAOxC;IAED;;;;;;OAMG;IACH,KAAK,IAAI,IAAI,CASZ;CACF"}

package/src/utils/MicrotaskCollector.js

@@ -0,0 +1,33 @@
+class MicrotaskCollector {
+  #entries = /* @__PURE__ */ new Map();
+  #scheduled = false;
+  #deliver;
+  constructor(deliver) {
+    this.#deliver = deliver;
+  }
+  /** Put an entry into the batch and make sure someone comes to fetch it. */
+  add(...[key, value]) {
+    this.#entries.set(key, value);
+    if (this.#scheduled) return;
+    this.#scheduled = true;
+    queueMicrotask(() => this.flush());
+  }
+  /**
+   * Hand the batch over now.
+   *
+   * For a caller that needs the batch delivered at a point of its own choosing rather than
+   * whenever the microtask comes round. A queued microtask that finds nothing left returns without
+   * a delivery, so an early flush costs nothing but the ordering it was asked for.
+   */
+  flush() {
+    this.#scheduled = false;
+    if (this.#entries.size === 0) return;
+    const entries = this.#entries;
+    this.#entries = /* @__PURE__ */ new Map();
+    this.#deliver(entries);
+  }
+}
+export {
+  MicrotaskCollector
+};
+//# sourceMappingURL=MicrotaskCollector.js.map

package/src/utils/MicrotaskCollector.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/MicrotaskCollector.ts"],
+  "sourcesContent": ["/**\n * The arguments of {@link MicrotaskCollector.add}: a collector without a payload is asked for the\n * key alone, one that carries a payload is asked for both.\n */\ntype AddArgs<K, V> = undefined extends V ? [key: K, value?: V] : [key: K, value: V];\n\n/**\n * Collects what is written in one task and hands it over a microtask later, in one batch.\n *\n * A second value for the same key replaces the one waiting, so a key written twice in a task\n * reaches the delivery once, with the value that stood at the end of it.\n *\n * Two rules live here so that no site has to decide them again:\n *\n * The batch is taken out and emptied **before** the first delivery. A delivery can write to this\n * collector -- a reader of a context value writes a context of its own, an entity that arrives\n * while a round goes out asks for a round -- and that write belongs to the round behind this one\n * rather than to the batch being walked. Emptying afterwards would also lose the batch to a\n * delivery that throws: the flag is already down by then, so the next write queues a fresh\n * microtask and hands the stale entries over a second time.\n *\n * Every delivery a site makes runs under `runGuarded()`. Entries that arrived in the same task are\n * independent of one another, and one that fails costs itself and nothing behind it -- the promise\n * `docs/api-reference.md` already spells out for context values. What counts as one delivery is\n * the site's to say: `Entity` delivers per entry, `ComponentContext` groups its senders\n * into rounds first and delivers per round.\n *\n * For a booking that has to be callable off again, see `DeferredTeardown`; for a single\n * deferred action without a batch, `MicrotaskGate`.\n */\nexport class MicrotaskCollector<K, V = undefined> {\n  #entries = new Map<K, V>();\n  #scheduled = false;\n\n  readonly #deliver: (entries: Map<K, V>) => void;\n\n  constructor(deliver: (entries: Map<K, V>) => void) {\n    this.#deliver = deliver;\n  }\n\n  /** Put an entry into the batch and make sure someone comes to fetch it. */\n  add(...[key, value]: AddArgs<K, V>): void {\n    this.#entries.set(key, value as V);\n\n    if (this.#scheduled) return;\n    this.#scheduled = true;\n\n    queueMicrotask(() => this.flush());\n  }\n\n  /**\n   * Hand the batch over now.\n   *\n   * For a caller that needs the batch delivered at a point of its own choosing rather than\n   * whenever the microtask comes round. A queued microtask that finds nothing left returns without\n   * a delivery, so an early flush costs nothing but the ordering it was asked for.\n   */\n  flush(): void {\n    this.#scheduled = false;\n\n    if (this.#entries.size === 0) return;\n\n    const entries = this.#entries;\n    this.#entries = new Map();\n\n    this.#deliver(entries);\n  }\n}\n"],
+  "mappings": "AA8BO,MAAM,mBAAqC;AAAA,EAChD,WAAW,oBAAI,IAAU;AAAA,EACzB,aAAa;AAAA,EAEJ;AAAA,EAET,YAAY,SAAuC;AACjD,SAAK,WAAW;AAAA,EAClB;AAAA;AAAA,EAGA,OAAO,CAAC,KAAK,KAAK,GAAwB;AACxC,SAAK,SAAS,IAAI,KAAK,KAAU;AAEjC,QAAI,KAAK,WAAY;AACrB,SAAK,aAAa;AAElB,mBAAe,MAAM,KAAK,MAAM,CAAC;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,QAAc;AACZ,SAAK,aAAa;AAElB,QAAI,KAAK,SAAS,SAAS,EAAG;AAE9B,UAAM,UAAU,KAAK;AACrB,SAAK,WAAW,oBAAI,IAAI;AAExB,SAAK,SAAS,OAAO;AAAA,EACvB;AACF;",
+  "names": []
+}

package/src/utils/MicrotaskGate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runs one action a microtask after it was asked for, however often it is asked for.
+ *
+ * The flag falls before the action rather than behind it: an action that asks again books a fresh
+ * round instead of writing into a flag the line behind it would clear.
+ *
+ * No batch and no guard: there is one action, so there are no neighbours a failure could cost --
+ * what it throws goes where an uncaught microtask goes. A gate that carries entries is
+ * `MicrotaskCollector`, a booking that can be called off again is `DeferredTeardown`.
+ */
+export declare class MicrotaskGate {
+    #private;
+    constructor(run: () => void);
+    /** Ask for the action. */
+    schedule(): void;
+}
+//# sourceMappingURL=MicrotaskGate.d.ts.map

package/src/utils/MicrotaskGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicrotaskGate.d.ts","sourceRoot":"","sources":["../../../src/utils/MicrotaskGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,aAAa;;IAKxB,YAAY,GAAG,EAAE,MAAM,IAAI,EAE1B;IAED,0BAA0B;IAC1B,QAAQ,IAAI,IAAI,CAQf;CACF"}