@studiometa/js-toolkit 3.8.1 → 3.9.0-beta.0

package/autoload/loader.js

@@ -0,0 +1,381 @@
+import { registerComponent } from "../helpers/registerComponent.js";
+const COMPONENT_SELECTOR = "[data-component]";
+const LOAD_STRATEGIES = [
+  "eager",
+  "visible",
+  "idle",
+  "interaction"
+];
+const DEFAULT_DIAGNOSTIC_PREFIX = "[@studiometa/js-toolkit/autoload]";
+const VISIBLE_ROOT_MARGIN = "200px 0px";
+const IDLE_TIMEOUT = 2e3;
+function isLoadStrategy(value) {
+  return LOAD_STRATEGIES.includes(value);
+}
+function isBaseConstructor(value) {
+  if (typeof value !== "function") {
+    return false;
+  }
+  const Constructor = value;
+  return Constructor.$isBase === true && typeof Constructor.$register === "function";
+}
+function createDependencies(overrides = {}) {
+  const scope = globalThis;
+  return {
+    document,
+    MutationObserver: globalThis.MutationObserver,
+    IntersectionObserver: globalThis.IntersectionObserver,
+    requestIdleCallback: scope.requestIdleCallback?.bind(scope),
+    cancelIdleCallback: scope.cancelIdleCallback?.bind(scope),
+    setTimeout: globalThis.setTimeout.bind(globalThis),
+    clearTimeout: globalThis.clearTimeout.bind(globalThis),
+    registerComponent,
+    console,
+    CustomEvent,
+    diagnosticPrefix: DEFAULT_DIAGNOSTIC_PREFIX,
+    ...overrides
+  };
+}
+class ComponentLoader {
+  /** @private */
+  __manifest;
+  /** @private */
+  __dependencies;
+  /** @private */
+  __root;
+  /** @private */
+  __records = /* @__PURE__ */ new Map();
+  /** @private */
+  __eagerComponents = /* @__PURE__ */ new Set();
+  /** @private */
+  __elementSchedules = /* @__PURE__ */ new WeakMap();
+  /** @private */
+  __elementCleanups = /* @__PURE__ */ new WeakMap();
+  /** @private */
+  __mutationObserver;
+  /** @private */
+  __started = false;
+  constructor({ manifest, root, dependencies }) {
+    this.__manifest = manifest;
+    this.__dependencies = createDependencies(dependencies);
+    this.__root = root ?? this.__dependencies.document;
+  }
+  start({ eagerComponents = [] } = {}) {
+    if (this.__started) {
+      return;
+    }
+    this.__started = true;
+    const MutationObserverConstructor = this.__dependencies.MutationObserver;
+    if (MutationObserverConstructor) {
+      this.__mutationObserver = new MutationObserverConstructor((records) => {
+        for (const record of records) {
+          for (const node of record.addedNodes) {
+            if (node instanceof Element) {
+              this.__scan(node);
+            }
+          }
+          for (const node of record.removedNodes) {
+            if (node instanceof Element) {
+              this.__cleanSubtree(node);
+            }
+          }
+        }
+      });
+      this.__mutationObserver.observe(this.__root, {
+        childList: true,
+        subtree: true
+      });
+    } else {
+      this.__warn("MutationObserver is unavailable; added components will not be discovered.");
+    }
+    for (const token of new Set(eagerComponents)) {
+      if (!this.__getEntry(token)) {
+        this.__warn("An unknown eager component was ignored.");
+        continue;
+      }
+      this.__eagerComponents.add(token);
+      this.__schedule(token, "eager");
+    }
+    this.__scan(this.__root);
+  }
+  stop() {
+    this.__mutationObserver?.disconnect();
+    for (const record of this.__records.values()) {
+      this.__clean(record);
+    }
+  }
+  /** @private */
+  __scan(root) {
+    if (root instanceof Element && root.matches(COMPONENT_SELECTOR)) {
+      this.__discover(root);
+    }
+    for (const element of root.querySelectorAll(COMPONENT_SELECTOR)) {
+      this.__discover(element);
+    }
+  }
+  /** @private */
+  __discover(element) {
+    const rawTokens = element.getAttribute("data-component") ?? "";
+    const tokens = new Set(rawTokens.split(/\s+/).filter(Boolean));
+    for (const token of tokens) {
+      const entry = this.__getEntry(token);
+      if (!entry) {
+        this.__warn("An unknown component token was ignored.");
+        continue;
+      }
+      const strategy = this.__getStrategy(element, entry);
+      const scheduleKey = `${token}:${strategy}`;
+      const elementSchedules = this.__elementSchedules.get(element) ?? /* @__PURE__ */ new Set();
+      if (elementSchedules.has(scheduleKey)) {
+        continue;
+      }
+      elementSchedules.add(scheduleKey);
+      this.__elementSchedules.set(element, elementSchedules);
+      this.__schedule(token, strategy, element);
+    }
+  }
+  /** @private */
+  __getEntry(token) {
+    if (!Object.prototype.hasOwnProperty.call(this.__manifest, token)) {
+      return void 0;
+    }
+    return this.__manifest[token];
+  }
+  /** @private */
+  __getStrategy(element, entry) {
+    if (this.__eagerComponents.has(entry.token)) {
+      return "eager";
+    }
+    const attribute = element.getAttribute("data-load");
+    if (attribute !== null) {
+      if (isLoadStrategy(attribute)) {
+        return attribute;
+      }
+      this.__warn(`Component "${entry.token}" has an invalid data-load value; using its default.`);
+    }
+    if (isLoadStrategy(entry.strategy)) {
+      return entry.strategy;
+    }
+    this.__warn(`Component "${entry.token}" has an invalid manifest strategy; loading eagerly.`);
+    return "eager";
+  }
+  /** @private */
+  __getRecord(token) {
+    let record = this.__records.get(token);
+    if (!record) {
+      record = {
+        state: "scheduled",
+        cleanups: /* @__PURE__ */ new Set(),
+        scheduledStrategies: /* @__PURE__ */ new Set()
+      };
+      this.__records.set(token, record);
+    }
+    return record;
+  }
+  /** @private */
+  __schedule(token, strategy, element) {
+    const record = this.__getRecord(token);
+    if (record.state !== "scheduled") {
+      return;
+    }
+    if (strategy === "eager") {
+      this.__begin(token, record);
+      return;
+    }
+    if (strategy === "visible") {
+      if (!element) {
+        this.__begin(token, record);
+        return;
+      }
+      const IntersectionObserverConstructor = this.__dependencies.IntersectionObserver;
+      if (!IntersectionObserverConstructor) {
+        this.__warn(`IntersectionObserver is unavailable; loading component "${token}" eagerly.`);
+        this.__begin(token, record);
+        return;
+      }
+      const observer = new IntersectionObserverConstructor(
+        (entries) => {
+          if (entries.some((entry) => entry.isIntersecting)) {
+            this.__begin(token, record);
+          }
+        },
+        { rootMargin: VISIBLE_ROOT_MARGIN }
+      );
+      observer.observe(element);
+      this.__addCleanup(record, () => observer.disconnect(), element);
+      return;
+    }
+    if (strategy === "idle") {
+      if (record.scheduledStrategies.has(strategy)) {
+        return;
+      }
+      record.scheduledStrategies.add(strategy);
+      const requestIdleCallback = this.__dependencies.requestIdleCallback;
+      if (requestIdleCallback) {
+        const handle2 = requestIdleCallback(() => this.__begin(token, record), {
+          timeout: IDLE_TIMEOUT
+        });
+        this.__addCleanup(record, () => this.__dependencies.cancelIdleCallback?.(handle2));
+        return;
+      }
+      this.__warn(`requestIdleCallback is unavailable; using a timeout for component "${token}".`);
+      const handle = this.__dependencies.setTimeout(
+        () => this.__begin(token, record),
+        IDLE_TIMEOUT
+      );
+      this.__addCleanup(record, () => this.__dependencies.clearTimeout(handle));
+      return;
+    }
+    if (!element) {
+      this.__begin(token, record);
+      return;
+    }
+    const listener = () => this.__begin(token, record);
+    for (const eventName of ["pointerover", "pointerdown", "focusin"]) {
+      element.addEventListener(eventName, listener, { once: true });
+      this.__addCleanup(record, () => element.removeEventListener(eventName, listener), element);
+    }
+  }
+  /** @private */
+  __begin(token, record) {
+    if (record.state !== "scheduled") {
+      return;
+    }
+    const entry = this.__getEntry(token);
+    if (!entry) {
+      return;
+    }
+    record.state = "loading";
+    this.__clean(record);
+    record.promise = Promise.resolve().then(() => entry.load()).then((Constructor) => {
+      if (!isBaseConstructor(Constructor)) {
+        throw new TypeError("The manifest loader did not resolve to a Base constructor.");
+      }
+      return Constructor;
+    }).catch((error) => {
+      record.state = "failed";
+      this.__reportError(token, "import", error);
+      return void 0;
+    }).then(async (Constructor) => {
+      if (!Constructor) {
+        return;
+      }
+      try {
+        await this.__dependencies.registerComponent(Constructor, token);
+        record.Constructor = Constructor;
+        record.state = "registered";
+        await this.__registerConfiguredChildren(token, Constructor, /* @__PURE__ */ new Set([token]));
+      } catch (error) {
+        record.state = "failed";
+        this.__reportError(token, "registration", error);
+      }
+    });
+  }
+  /** @private */
+  async __registerConfiguredChildren(parentToken, ParentConstructor, visited) {
+    const configuredChildren = ParentConstructor.config.components ?? {};
+    for (const token of this.__getEntry(parentToken)?.children ?? []) {
+      if (visited.has(token)) {
+        continue;
+      }
+      const Constructor = configuredChildren[token];
+      if (!isBaseConstructor(Constructor)) {
+        continue;
+      }
+      visited.add(token);
+      const record = this.__getRecord(token);
+      if (record.state === "loading") {
+        continue;
+      }
+      if (record.state !== "registered") {
+        record.state = "loading";
+        this.__clean(record);
+        record.promise = this.__registerConfiguredChild(token, Constructor, record, visited);
+        await record.promise;
+      } else {
+        await this.__registerConfiguredChildren(token, record.Constructor ?? Constructor, visited);
+      }
+    }
+  }
+  /** @private */
+  async __registerConfiguredChild(token, Constructor, record, visited) {
+    try {
+      await this.__dependencies.registerComponent(Constructor, token);
+      record.Constructor = Constructor;
+      record.state = "registered";
+      await this.__registerConfiguredChildren(token, Constructor, visited);
+    } catch (error) {
+      record.state = "failed";
+      this.__reportError(token, "registration", error);
+    }
+  }
+  /** @private */
+  __addCleanup(record, cleanup, element) {
+    let active = true;
+    const run = () => {
+      if (!active) {
+        return;
+      }
+      active = false;
+      cleanup();
+      record.cleanups.delete(run);
+      if (element) {
+        const elementCleanups = this.__elementCleanups.get(element);
+        elementCleanups?.delete(run);
+        if (elementCleanups?.size === 0) {
+          this.__elementCleanups.delete(element);
+        }
+      }
+    };
+    record.cleanups.add(run);
+    if (element) {
+      const elementCleanups = this.__elementCleanups.get(element) ?? /* @__PURE__ */ new Set();
+      elementCleanups.add(run);
+      this.__elementCleanups.set(element, elementCleanups);
+    }
+  }
+  /** @private */
+  __cleanSubtree(root) {
+    for (const element of [root, ...root.querySelectorAll("*")]) {
+      if (element.isConnected) {
+        continue;
+      }
+      for (const cleanup of [...this.__elementCleanups.get(element) ?? []]) {
+        cleanup();
+      }
+      this.__elementSchedules.delete(element);
+    }
+  }
+  /** @private */
+  __clean(record) {
+    for (const cleanup of record.cleanups) {
+      cleanup();
+    }
+    record.cleanups.clear();
+  }
+  /** @private */
+  __warn(message) {
+    this.__dependencies.console.warn(`${this.__dependencies.diagnosticPrefix} ${message}`);
+  }
+  /** @private */
+  __reportError(token, stage, error) {
+    this.__dependencies.console.error(
+      `${this.__dependencies.diagnosticPrefix} Failed during ${stage} for component "${token}".`,
+      error
+    );
+    const event = new this.__dependencies.CustomEvent("js-toolkit:error", {
+      bubbles: true,
+      detail: { token, stage, error }
+    });
+    (this.__dependencies.document.documentElement ?? this.__dependencies.document).dispatchEvent(
+      event
+    );
+  }
+}
+export {
+  ComponentLoader,
+  DEFAULT_DIAGNOSTIC_PREFIX,
+  IDLE_TIMEOUT,
+  VISIBLE_ROOT_MARGIN
+};
+//# sourceMappingURL=loader.js.map

package/autoload/loader.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../packages/js-toolkit/autoload/loader.ts"],
+  "sourcesContent": ["import { registerComponent } from '../helpers/registerComponent.js';\nimport type { BaseConstructor } from '../Base/index.js';\nimport type { ComponentLoadStrategy, ComponentManifest, ComponentManifestEntry } from './types.js';\n\nconst COMPONENT_SELECTOR = '[data-component]';\nconst LOAD_STRATEGIES: readonly ComponentLoadStrategy[] = [\n  'eager',\n  'visible',\n  'idle',\n  'interaction',\n];\n\n/** The diagnostic prefix used when the host does not inject its own. */\nexport const DEFAULT_DIAGNOSTIC_PREFIX = '[@studiometa/js-toolkit/autoload]';\n\n/** Start loading visible components shortly before they enter the viewport. */\nexport const VISIBLE_ROOT_MARGIN = '200px 0px';\n/** Ensure idle components eventually load even when the main thread remains busy. */\nexport const IDLE_TIMEOUT = 2_000;\n\ninterface IdleDeadlineLike {\n  readonly didTimeout: boolean;\n  timeRemaining: () => number;\n}\n\ntype IdleHandle = number;\ntype RequestIdleCallbackLike = (\n  callback: (deadline: IdleDeadlineLike) => void,\n  options?: { timeout: number },\n) => IdleHandle;\ntype CancelIdleCallbackLike = (handle: IdleHandle) => void;\ntype RegisterComponent = (\n  Constructor: BaseConstructor,\n  token: string,\n) => Promise<unknown> | unknown;\n\ntype ComponentState = 'scheduled' | 'loading' | 'registered' | 'failed';\n\ninterface ComponentRecord {\n  state: ComponentState;\n  promise?: Promise<void>;\n  Constructor?: BaseConstructor;\n  cleanups: Set<() => void>;\n  scheduledStrategies: Set<ComponentLoadStrategy>;\n}\n\nexport interface LoaderDependencies {\n  document: Document;\n  MutationObserver?: typeof MutationObserver;\n  IntersectionObserver?: typeof IntersectionObserver;\n  requestIdleCallback?: RequestIdleCallbackLike;\n  cancelIdleCallback?: CancelIdleCallbackLike;\n  setTimeout: typeof globalThis.setTimeout;\n  clearTimeout: typeof globalThis.clearTimeout;\n  registerComponent: RegisterComponent;\n  console: Pick<Console, 'warn' | 'error'>;\n  CustomEvent: typeof CustomEvent;\n  /** The prefix prepended to every diagnostic message emitted by the loader. */\n  diagnosticPrefix: string;\n}\n\nexport interface ComponentLoaderOptions {\n  manifest: ComponentManifest;\n  /** The DOM scope to scan and observe. Defaults to the injected `document`. */\n  root?: Document | Element;\n  dependencies?: Partial<LoaderDependencies>;\n}\n\nexport interface ComponentLoaderStartOptions {\n  eagerComponents?: Iterable<string>;\n}\n\nfunction isLoadStrategy(value: string): value is ComponentLoadStrategy {\n  return LOAD_STRATEGIES.includes(value as ComponentLoadStrategy);\n}\n\nfunction isBaseConstructor(value: unknown): value is BaseConstructor {\n  if (typeof value !== 'function') {\n    return false;\n  }\n\n  const Constructor = value as unknown as Record<string, unknown>;\n  return Constructor.$isBase === true && typeof Constructor.$register === 'function';\n}\n\nfunction createDependencies(overrides: Partial<LoaderDependencies> = {}): LoaderDependencies {\n  const scope = globalThis as typeof globalThis & {\n    requestIdleCallback?: RequestIdleCallbackLike;\n    cancelIdleCallback?: CancelIdleCallbackLike;\n  };\n\n  return {\n    document,\n    MutationObserver: globalThis.MutationObserver,\n    IntersectionObserver: globalThis.IntersectionObserver,\n    requestIdleCallback: scope.requestIdleCallback?.bind(scope),\n    cancelIdleCallback: scope.cancelIdleCallback?.bind(scope),\n    setTimeout: globalThis.setTimeout.bind(globalThis),\n    clearTimeout: globalThis.clearTimeout.bind(globalThis),\n    registerComponent,\n    console,\n    CustomEvent,\n    diagnosticPrefix: DEFAULT_DIAGNOSTIC_PREFIX,\n    ...overrides,\n  };\n}\n\n/**\n * Discover declarative components and schedule each constructor exactly once.\n *\n * The loader is generic: it knows nothing hard-coded about any component package and works purely\n * from the manifest it is given. Importing this module has no side effects \u2014 discovery only starts\n * when {@link ComponentLoader.start} is called.\n */\nexport class ComponentLoader {\n  /** @private */\n  __manifest: ComponentManifest;\n  /** @private */\n  __dependencies: LoaderDependencies;\n  /** @private */\n  __root: Document | Element;\n  /** @private */\n  __records = new Map<string, ComponentRecord>();\n  /** @private */\n  __eagerComponents = new Set<string>();\n  /** @private */\n  __elementSchedules = new WeakMap<Element, Set<string>>();\n  /** @private */\n  __elementCleanups = new WeakMap<Element, Set<() => void>>();\n  /** @private */\n  __mutationObserver?: MutationObserver;\n  /** @private */\n  __started = false;\n\n  constructor({ manifest, root, dependencies }: ComponentLoaderOptions) {\n    this.__manifest = manifest;\n    this.__dependencies = createDependencies(dependencies);\n    this.__root = root ?? this.__dependencies.document;\n  }\n\n  start({ eagerComponents = [] }: ComponentLoaderStartOptions = {}): void {\n    if (this.__started) {\n      return;\n    }\n    this.__started = true;\n\n    const MutationObserverConstructor = this.__dependencies.MutationObserver;\n    if (MutationObserverConstructor) {\n      this.__mutationObserver = new MutationObserverConstructor((records) => {\n        for (const record of records) {\n          for (const node of record.addedNodes) {\n            if (node instanceof Element) {\n              this.__scan(node);\n            }\n          }\n          for (const node of record.removedNodes) {\n            if (node instanceof Element) {\n              this.__cleanSubtree(node);\n            }\n          }\n        }\n      });\n      this.__mutationObserver.observe(this.__root, {\n        childList: true,\n        subtree: true,\n      });\n    } else {\n      this.__warn('MutationObserver is unavailable; added components will not be discovered.');\n    }\n\n    for (const token of new Set(eagerComponents)) {\n      if (!this.__getEntry(token)) {\n        this.__warn('An unknown eager component was ignored.');\n        continue;\n      }\n      this.__eagerComponents.add(token);\n      this.__schedule(token, 'eager');\n    }\n\n    this.__scan(this.__root);\n  }\n\n  stop(): void {\n    this.__mutationObserver?.disconnect();\n    for (const record of this.__records.values()) {\n      this.__clean(record);\n    }\n  }\n\n  /** @private */\n  __scan(root: Document | Element): void {\n    if (root instanceof Element && root.matches(COMPONENT_SELECTOR)) {\n      this.__discover(root);\n    }\n\n    for (const element of root.querySelectorAll(COMPONENT_SELECTOR)) {\n      this.__discover(element);\n    }\n  }\n\n  /** @private */\n  __discover(element: Element): void {\n    const rawTokens = element.getAttribute('data-component') ?? '';\n    const tokens = new Set(rawTokens.split(/\\s+/).filter(Boolean));\n\n    for (const token of tokens) {\n      const entry = this.__getEntry(token);\n      if (!entry) {\n        this.__warn('An unknown component token was ignored.');\n        continue;\n      }\n\n      const strategy = this.__getStrategy(element, entry);\n      const scheduleKey = `${token}:${strategy}`;\n      const elementSchedules = this.__elementSchedules.get(element) ?? new Set<string>();\n      if (elementSchedules.has(scheduleKey)) {\n        continue;\n      }\n      elementSchedules.add(scheduleKey);\n      this.__elementSchedules.set(element, elementSchedules);\n      this.__schedule(token, strategy, element);\n    }\n  }\n\n  /** @private */\n  __getEntry(token: string): ComponentManifestEntry | undefined {\n    if (!Object.prototype.hasOwnProperty.call(this.__manifest, token)) {\n      return undefined;\n    }\n    return this.__manifest[token];\n  }\n\n  /** @private */\n  __getStrategy(element: Element, entry: ComponentManifestEntry): ComponentLoadStrategy {\n    if (this.__eagerComponents.has(entry.token)) {\n      return 'eager';\n    }\n\n    const attribute = element.getAttribute('data-load');\n    if (attribute !== null) {\n      if (isLoadStrategy(attribute)) {\n        return attribute;\n      }\n      this.__warn(`Component \"${entry.token}\" has an invalid data-load value; using its default.`);\n    }\n\n    if (isLoadStrategy(entry.strategy)) {\n      return entry.strategy;\n    }\n\n    this.__warn(`Component \"${entry.token}\" has an invalid manifest strategy; loading eagerly.`);\n    return 'eager';\n  }\n\n  /** @private */\n  __getRecord(token: string): ComponentRecord {\n    let record = this.__records.get(token);\n    if (!record) {\n      record = {\n        state: 'scheduled',\n        cleanups: new Set(),\n        scheduledStrategies: new Set(),\n      };\n      this.__records.set(token, record);\n    }\n    return record;\n  }\n\n  /** @private */\n  __schedule(token: string, strategy: ComponentLoadStrategy, element?: Element): void {\n    const record = this.__getRecord(token);\n    if (record.state !== 'scheduled') {\n      return;\n    }\n\n    if (strategy === 'eager') {\n      this.__begin(token, record);\n      return;\n    }\n\n    if (strategy === 'visible') {\n      if (!element) {\n        this.__begin(token, record);\n        return;\n      }\n      const IntersectionObserverConstructor = this.__dependencies.IntersectionObserver;\n      if (!IntersectionObserverConstructor) {\n        this.__warn(`IntersectionObserver is unavailable; loading component \"${token}\" eagerly.`);\n        this.__begin(token, record);\n        return;\n      }\n      const observer = new IntersectionObserverConstructor(\n        (entries) => {\n          if (entries.some((entry) => entry.isIntersecting)) {\n            this.__begin(token, record);\n          }\n        },\n        { rootMargin: VISIBLE_ROOT_MARGIN },\n      );\n      observer.observe(element);\n      this.__addCleanup(record, () => observer.disconnect(), element);\n      return;\n    }\n\n    if (strategy === 'idle') {\n      if (record.scheduledStrategies.has(strategy)) {\n        return;\n      }\n      record.scheduledStrategies.add(strategy);\n      const requestIdleCallback = this.__dependencies.requestIdleCallback;\n      if (requestIdleCallback) {\n        const handle = requestIdleCallback(() => this.__begin(token, record), {\n          timeout: IDLE_TIMEOUT,\n        });\n        this.__addCleanup(record, () => this.__dependencies.cancelIdleCallback?.(handle));\n        return;\n      }\n      this.__warn(`requestIdleCallback is unavailable; using a timeout for component \"${token}\".`);\n      const handle = this.__dependencies.setTimeout(\n        () => this.__begin(token, record),\n        IDLE_TIMEOUT,\n      );\n      this.__addCleanup(record, () => this.__dependencies.clearTimeout(handle));\n      return;\n    }\n\n    if (!element) {\n      this.__begin(token, record);\n      return;\n    }\n\n    const listener = () => this.__begin(token, record);\n    for (const eventName of ['pointerover', 'pointerdown', 'focusin']) {\n      element.addEventListener(eventName, listener, { once: true });\n      this.__addCleanup(record, () => element.removeEventListener(eventName, listener), element);\n    }\n  }\n\n  /** @private */\n  __begin(token: string, record: ComponentRecord): void {\n    if (record.state !== 'scheduled') {\n      return;\n    }\n\n    const entry = this.__getEntry(token);\n    if (!entry) {\n      return;\n    }\n\n    record.state = 'loading';\n    this.__clean(record);\n    record.promise = Promise.resolve()\n      .then(() => entry.load())\n      .then((Constructor) => {\n        if (!isBaseConstructor(Constructor)) {\n          throw new TypeError('The manifest loader did not resolve to a Base constructor.');\n        }\n        return Constructor;\n      })\n      .catch((error: unknown) => {\n        record.state = 'failed';\n        this.__reportError(token, 'import', error);\n        return undefined;\n      })\n      .then(async (Constructor) => {\n        if (!Constructor) {\n          return;\n        }\n        try {\n          await this.__dependencies.registerComponent(Constructor, token);\n          record.Constructor = Constructor;\n          record.state = 'registered';\n          await this.__registerConfiguredChildren(token, Constructor, new Set([token]));\n        } catch (error: unknown) {\n          record.state = 'failed';\n          this.__reportError(token, 'registration', error);\n        }\n      });\n  }\n\n  /** @private */\n  async __registerConfiguredChildren(\n    parentToken: string,\n    ParentConstructor: BaseConstructor,\n    visited: Set<string>,\n  ): Promise<void> {\n    const configuredChildren = ParentConstructor.config.components ?? {};\n\n    for (const token of this.__getEntry(parentToken)?.children ?? []) {\n      if (visited.has(token)) {\n        continue;\n      }\n\n      const Constructor = configuredChildren[token];\n      if (!isBaseConstructor(Constructor)) {\n        continue;\n      }\n\n      visited.add(token);\n      const record = this.__getRecord(token);\n      if (record.state === 'loading') {\n        continue;\n      }\n\n      if (record.state !== 'registered') {\n        record.state = 'loading';\n        this.__clean(record);\n        record.promise = this.__registerConfiguredChild(token, Constructor, record, visited);\n        await record.promise;\n      } else {\n        await this.__registerConfiguredChildren(token, record.Constructor ?? Constructor, visited);\n      }\n    }\n  }\n\n  /** @private */\n  async __registerConfiguredChild(\n    token: string,\n    Constructor: BaseConstructor,\n    record: ComponentRecord,\n    visited: Set<string>,\n  ): Promise<void> {\n    try {\n      await this.__dependencies.registerComponent(Constructor, token);\n      record.Constructor = Constructor;\n      record.state = 'registered';\n      await this.__registerConfiguredChildren(token, Constructor, visited);\n    } catch (error: unknown) {\n      record.state = 'failed';\n      this.__reportError(token, 'registration', error);\n    }\n  }\n\n  /** @private */\n  __addCleanup(record: ComponentRecord, cleanup: () => void, element?: Element): void {\n    let active = true;\n    const run = () => {\n      if (!active) {\n        return;\n      }\n      active = false;\n      cleanup();\n      record.cleanups.delete(run);\n      if (element) {\n        const elementCleanups = this.__elementCleanups.get(element);\n        elementCleanups?.delete(run);\n        if (elementCleanups?.size === 0) {\n          this.__elementCleanups.delete(element);\n        }\n      }\n    };\n\n    record.cleanups.add(run);\n    if (element) {\n      const elementCleanups = this.__elementCleanups.get(element) ?? new Set();\n      elementCleanups.add(run);\n      this.__elementCleanups.set(element, elementCleanups);\n    }\n  }\n\n  /** @private */\n  __cleanSubtree(root: Element): void {\n    for (const element of [root, ...root.querySelectorAll('*')]) {\n      if (element.isConnected) {\n        continue;\n      }\n      for (const cleanup of [...(this.__elementCleanups.get(element) ?? [])]) {\n        cleanup();\n      }\n      this.__elementSchedules.delete(element);\n    }\n  }\n\n  /** @private */\n  __clean(record: ComponentRecord): void {\n    for (const cleanup of record.cleanups) {\n      cleanup();\n    }\n    record.cleanups.clear();\n  }\n\n  /** @private */\n  __warn(message: string): void {\n    this.__dependencies.console.warn(`${this.__dependencies.diagnosticPrefix} ${message}`);\n  }\n\n  /** @private */\n  __reportError(token: string, stage: 'import' | 'registration', error: unknown): void {\n    this.__dependencies.console.error(\n      `${this.__dependencies.diagnosticPrefix} Failed during ${stage} for component \"${token}\".`,\n      error,\n    );\n    const event = new this.__dependencies.CustomEvent('js-toolkit:error', {\n      bubbles: true,\n      detail: { token, stage, error },\n    });\n    (this.__dependencies.document.documentElement ?? this.__dependencies.document).dispatchEvent(\n      event,\n    );\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["handle"]
+}

package/autoload/modules.d.ts

@@ -0,0 +1,31 @@
+import type { ModuleRecord } from './define-manifest.js';
+/**
+ * The structural shape of a webpack context function returned by
+ * `import.meta.webpackContext(dir, options)`: it is callable to resolve a module by id and exposes
+ * a `keys()` method listing every matched id. Typed structurally to avoid a webpack dependency.
+ */
+export interface WebpackContextLike {
+    /** List every module id the context matched. */
+    keys(): string[];
+    /** Resolve a module by its id. */
+    (id: string): unknown;
+}
+/**
+ * Normalize the record returned by Vite's `import.meta.glob('./x/*.ts')` into a {@link ModuleRecord}.
+ *
+ * The lazy form of `import.meta.glob` already returns `Record<string, () => Promise<Module>>`, so
+ * this is an identity pass with a guard: it throws when any value is not a function, which means the
+ * caller passed an eager glob (`import.meta.glob('...', { eager: true })`) — an unsupported shape,
+ * because eager globs resolve the modules synchronously and defeat on-demand loading.
+ */
+export declare function fromMetaGlob(glob: Record<string, unknown>): ModuleRecord;
+/**
+ * Normalize a webpack context — the value returned by
+ * `import.meta.webpackContext(dir, { recursive, regExp, mode })` — into a {@link ModuleRecord}.
+ *
+ * A webpack context is a callable with a `keys()` method rather than a record of importers, so this
+ * wraps each key in `() => Promise.resolve(context(key))`. `Promise.resolve` tolerates both a
+ * synchronous module (`mode: 'sync'`) and a promise (`mode: 'lazy'`) uniformly. Use `mode: 'lazy'`
+ * for real code-splitting and on-demand loading; the other modes bundle every match eagerly.
+ */
+export declare function fromWebpackContext(context: WebpackContextLike): ModuleRecord;

package/autoload/modules.js

@@ -0,0 +1,21 @@
+import { DEFAULT_DIAGNOSTIC_PREFIX } from "./loader.js";
+function fromMetaGlob(glob) {
+  for (const [key, value] of Object.entries(glob)) {
+    if (typeof value !== "function") {
+      throw new TypeError(
+        `${DEFAULT_DIAGNOSTIC_PREFIX} fromMetaGlob() expects a lazy glob but "${key}" is not an importer function; drop the { eager: true } option.`
+      );
+    }
+  }
+  return glob;
+}
+function fromWebpackContext(context) {
+  return Object.fromEntries(
+    context.keys().map((key) => [key, () => Promise.resolve(context(key))])
+  );
+}
+export {
+  fromMetaGlob,
+  fromWebpackContext
+};
+//# sourceMappingURL=modules.js.map

package/autoload/modules.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../packages/js-toolkit/autoload/modules.ts"],
+  "sourcesContent": ["import { DEFAULT_DIAGNOSTIC_PREFIX } from './loader.js';\nimport type { ModuleRecord } from './define-manifest.js';\n\n/**\n * The structural shape of a webpack context function returned by\n * `import.meta.webpackContext(dir, options)`: it is callable to resolve a module by id and exposes\n * a `keys()` method listing every matched id. Typed structurally to avoid a webpack dependency.\n */\nexport interface WebpackContextLike {\n  /** List every module id the context matched. */\n  keys(): string[];\n  /** Resolve a module by its id. */\n  (id: string): unknown;\n}\n\n/**\n * Normalize the record returned by Vite's `import.meta.glob('./x/*.ts')` into a {@link ModuleRecord}.\n *\n * The lazy form of `import.meta.glob` already returns `Record<string, () => Promise<Module>>`, so\n * this is an identity pass with a guard: it throws when any value is not a function, which means the\n * caller passed an eager glob (`import.meta.glob('...', { eager: true })`) \u2014 an unsupported shape,\n * because eager globs resolve the modules synchronously and defeat on-demand loading.\n */\nexport function fromMetaGlob(glob: Record<string, unknown>): ModuleRecord {\n  for (const [key, value] of Object.entries(glob)) {\n    if (typeof value !== 'function') {\n      throw new TypeError(\n        `${DEFAULT_DIAGNOSTIC_PREFIX} fromMetaGlob() expects a lazy glob but \"${key}\" is not an importer function; drop the { eager: true } option.`,\n      );\n    }\n  }\n  return glob as ModuleRecord;\n}\n\n/**\n * Normalize a webpack context \u2014 the value returned by\n * `import.meta.webpackContext(dir, { recursive, regExp, mode })` \u2014 into a {@link ModuleRecord}.\n *\n * A webpack context is a callable with a `keys()` method rather than a record of importers, so this\n * wraps each key in `() => Promise.resolve(context(key))`. `Promise.resolve` tolerates both a\n * synchronous module (`mode: 'sync'`) and a promise (`mode: 'lazy'`) uniformly. Use `mode: 'lazy'`\n * for real code-splitting and on-demand loading; the other modes bundle every match eagerly.\n */\nexport function fromWebpackContext(context: WebpackContextLike): ModuleRecord {\n  return Object.fromEntries(\n    context\n      .keys()\n      .map((key) => [key, () => Promise.resolve(context(key) as Record<string, unknown>)]),\n  ) as ModuleRecord;\n}\n"],
+  "mappings": "AAAA,SAAS,iCAAiC;AAuBnC,SAAS,aAAa,MAA6C;AACxE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,QAAI,OAAO,UAAU,YAAY;AAC/B,YAAM,IAAI;AAAA,QACR,GAAG,yBAAyB,4CAA4C,GAAG;AAAA,MAC7E;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAWO,SAAS,mBAAmB,SAA2C;AAC5E,SAAO,OAAO;AAAA,IACZ,QACG,KAAK,EACL,IAAI,CAAC,QAAQ,CAAC,KAAK,MAAM,QAAQ,QAAQ,QAAQ,GAAG,CAA4B,CAAC,CAAC;AAAA,EACvF;AACF;",
+  "names": []
+}

package/autoload/runtime.d.ts

@@ -0,0 +1,93 @@
+import { type AutoloadHandle } from './autoload.js';
+import type { LoaderDependencies } from './loader.js';
+import type { ComponentManifest } from './types.js';
+/** The identity every copy of this package advertises on the shared global runtime. */
+declare const PACKAGE_NAME = "@studiometa/js-toolkit";
+/** Options accepted by {@link registerManifest}; every seam is optional and testability-oriented. */
+export interface RegisterManifestOptions {
+    /** The document to scan and to read the eager `<meta>` from. Defaults to the global `document`. */
+    document?: Document;
+    /** The object the shared runtime is stored on. Defaults to `globalThis`. */
+    globalObject?: object;
+    /** The identity used by the duplicate/conflict guard. Defaults to this package's version. */
+    version?: string;
+    /** The DOM scope handed to the loader. Defaults to the resolved document. */
+    root?: Document | Element;
+    /** Loader dependency-injection seams, forwarded to {@link autoload}. */
+    dependencies?: Partial<LoaderDependencies>;
+    /** The logger used by the duplicate/conflict guard. Defaults to the global `console`. */
+    console?: Pick<Console, 'warn'>;
+    /** Schedules the single coalesced start. Defaults to `queueMicrotask`. */
+    scheduleMicrotask?: (callback: () => void) => void;
+}
+/** The shared, cross-copy runtime object stored on `globalThis` under {@link RUNTIME_KEY}. */
+export interface AutoloadRuntime {
+    /** The owning package name, used by the conflict guard. */
+    readonly packageName: typeof PACKAGE_NAME;
+    /** The version that first claimed this runtime; conflicting versions are ignored. */
+    readonly version: string;
+    /** Every manifest registered so far, in registration order. */
+    manifests: ComponentManifest[];
+    /** The active autoload handle, present once a start has flushed. */
+    handle?: AutoloadHandle;
+    /** True while a (re)start is scheduled through a microtask but has not flushed yet. */
+    pending: boolean;
+    /**
+     * The resolved options for the next flush. The freshest registration wins so a late import can
+     * refresh the document/root before the coalesced start runs.
+     *
+     * @private
+     */
+    __pendingOptions?: ResolvedOptions;
+}
+interface ResolvedOptions {
+    documentObject: Document;
+    globalObject: object;
+    version: string;
+    root: Document | Element;
+    dependencies?: Partial<LoaderDependencies>;
+    logger: Pick<Console, 'warn'>;
+    scheduleMicrotask: (callback: () => void) => void;
+}
+/**
+ * Read the eager tokens declared by `<meta name="js-toolkit:eager" content="A, B, C">`.
+ *
+ * The `content` values of every matching meta (in document order) are concatenated, split on
+ * commas, trimmed, stripped of empties and deduplicated. When no such meta exists the list is
+ * empty.
+ */
+export declare function readEagerTokens(documentObject: Document): string[];
+/**
+ * Register a component manifest with the shared runtime and ensure the autoloader starts.
+ *
+ * This is the shared engine behind side-effect entries that activate a manifest. It is safe to call
+ * from several entries and several bundle copies at once:
+ *
+ * - The first registration schedules a single start through a microtask. Because every ES module
+ *   import in a graph evaluates before microtasks flush, importing several manifest-activating
+ *   entries at the top of a module registers every manifest synchronously and results in exactly
+ *   ONE {@link autoload} call over the COMPOSED set — never two loaders both scanning the DOM.
+ * - A manifest registered after the start already fired is not dropped: it triggers a fresh start
+ *   over the accumulated manifests. The previous loader is stopped first, so a single loader stays
+ *   active, and js-toolkit's idempotent `$register` prevents any double-mount.
+ * - A conflicting activation — a different {@link RegisterManifestOptions.version} claiming an
+ *   already-owned runtime — warns and no-ops.
+ *
+ * Returns the shared runtime, or `undefined` when a conflicting version already owns it.
+ */
+export declare function registerManifest(manifest: ComponentManifest, options?: RegisterManifestOptions): AutoloadRuntime | undefined;
+/**
+ * Register several manifests with the shared runtime in order, then let the single coalesced start
+ * flush over the composed set.
+ *
+ * This is the convenience wrapper an app uses to layer its own components on top of the packaged
+ * ones: `registerManifests(baseManifest, custom)`. Because {@link registerManifest} pushes each
+ * manifest onto the shared runtime in call order and the loader composes them later-wins, the LAST
+ * manifest wins on token collisions — so a custom manifest passed last can override any component
+ * that shares a token.
+ *
+ * Returns the shared runtime from the final registration, or `undefined` when a conflicting version
+ * already owns the runtime (or when no manifest was passed).
+ */
+export declare function registerManifests(...manifests: ComponentManifest[]): AutoloadRuntime | undefined;
+export {};