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

package/autoload/autoload.d.ts

@@ -0,0 +1,37 @@
+import { ComponentLoader, type LoaderDependencies } from './loader.js';
+import type { ComponentManifest } from './types.js';
+export interface AutoloadOptions {
+    /**
+     * One or more manifests to compose into a single lookup table. When two manifests declare the
+     * same token, the entry from the manifest that appears later in the array wins.
+     */
+    manifests: readonly ComponentManifest[];
+    /** The DOM scope to scan and observe for `data-component` elements. Defaults to `document`. */
+    root?: Document | Element;
+    /** Tokens to force-load eagerly regardless of their manifest strategy or `data-load` attribute. */
+    eager?: readonly string[];
+    /** Loader dependency-injection seams, kept for testability. */
+    dependencies?: Partial<LoaderDependencies>;
+}
+/** The runtime handle returned by {@link autoload}. */
+export interface AutoloadHandle {
+    /** The underlying loader instance. */
+    loader: ComponentLoader;
+    /** The composed manifest the loader was started with. */
+    manifest: ComponentManifest;
+    /** Stop discovery and release every scheduled trigger. */
+    stop(): void;
+}
+/**
+ * Compose several manifests into one. Later manifests take precedence over earlier ones when they
+ * declare the same token, so callers can layer overrides on top of a base manifest.
+ */
+export declare function composeManifests(manifests: readonly ComponentManifest[]): ComponentManifest;
+/**
+ * Start the declarative autoloader for the given manifests.
+ *
+ * Calling this function is the only thing that touches the DOM — importing the module does nothing
+ * on its own. It composes the manifests, creates a {@link ComponentLoader}, starts discovery and
+ * returns a handle that exposes the loader, the composed manifest and a `stop()` method.
+ */
+export declare function autoload(options: AutoloadOptions): AutoloadHandle;

package/autoload/autoload.js

@@ -0,0 +1,29 @@
+import { ComponentLoader } from "./loader.js";
+function composeManifests(manifests) {
+  const composed = {};
+  for (const manifest of manifests) {
+    for (const token of Object.keys(manifest)) {
+      composed[token] = manifest[token];
+    }
+  }
+  return composed;
+}
+function autoload(options) {
+  const manifest = composeManifests(options.manifests);
+  const loader = new ComponentLoader({
+    manifest,
+    root: options.root,
+    dependencies: options.dependencies
+  });
+  loader.start({ eagerComponents: options.eager ?? [] });
+  return {
+    loader,
+    manifest,
+    stop: () => loader.stop()
+  };
+}
+export {
+  autoload,
+  composeManifests
+};
+//# sourceMappingURL=autoload.js.map

package/autoload/autoload.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../packages/js-toolkit/autoload/autoload.ts"],
+  "sourcesContent": ["import { ComponentLoader, type LoaderDependencies } from './loader.js';\nimport type { ComponentManifest } from './types.js';\n\nexport interface AutoloadOptions {\n  /**\n   * One or more manifests to compose into a single lookup table. When two manifests declare the\n   * same token, the entry from the manifest that appears later in the array wins.\n   */\n  manifests: readonly ComponentManifest[];\n  /** The DOM scope to scan and observe for `data-component` elements. Defaults to `document`. */\n  root?: Document | Element;\n  /** Tokens to force-load eagerly regardless of their manifest strategy or `data-load` attribute. */\n  eager?: readonly string[];\n  /** Loader dependency-injection seams, kept for testability. */\n  dependencies?: Partial<LoaderDependencies>;\n}\n\n/** The runtime handle returned by {@link autoload}. */\nexport interface AutoloadHandle {\n  /** The underlying loader instance. */\n  loader: ComponentLoader;\n  /** The composed manifest the loader was started with. */\n  manifest: ComponentManifest;\n  /** Stop discovery and release every scheduled trigger. */\n  stop(): void;\n}\n\n/**\n * Compose several manifests into one. Later manifests take precedence over earlier ones when they\n * declare the same token, so callers can layer overrides on top of a base manifest.\n */\nexport function composeManifests(manifests: readonly ComponentManifest[]): ComponentManifest {\n  const composed: ComponentManifest = {};\n  for (const manifest of manifests) {\n    for (const token of Object.keys(manifest)) {\n      composed[token] = manifest[token];\n    }\n  }\n  return composed;\n}\n\n/**\n * Start the declarative autoloader for the given manifests.\n *\n * Calling this function is the only thing that touches the DOM \u2014 importing the module does nothing\n * on its own. It composes the manifests, creates a {@link ComponentLoader}, starts discovery and\n * returns a handle that exposes the loader, the composed manifest and a `stop()` method.\n */\nexport function autoload(options: AutoloadOptions): AutoloadHandle {\n  const manifest = composeManifests(options.manifests);\n  const loader = new ComponentLoader({\n    manifest,\n    root: options.root,\n    dependencies: options.dependencies,\n  });\n  loader.start({ eagerComponents: options.eager ?? [] });\n  return {\n    loader,\n    manifest,\n    stop: () => loader.stop(),\n  };\n}\n"],
+  "mappings": "AAAA,SAAS,uBAAgD;AA+BlD,SAAS,iBAAiB,WAA4D;AAC3F,QAAM,WAA8B,CAAC;AACrC,aAAW,YAAY,WAAW;AAChC,eAAW,SAAS,OAAO,KAAK,QAAQ,GAAG;AACzC,eAAS,KAAK,IAAI,SAAS,KAAK;AAAA,IAClC;AAAA,EACF;AACA,SAAO;AACT;AASO,SAAS,SAAS,SAA0C;AACjE,QAAM,WAAW,iBAAiB,QAAQ,SAAS;AACnD,QAAM,SAAS,IAAI,gBAAgB;AAAA,IACjC;AAAA,IACA,MAAM,QAAQ;AAAA,IACd,cAAc,QAAQ;AAAA,EACxB,CAAC;AACD,SAAO,MAAM,EAAE,iBAAiB,QAAQ,SAAS,CAAC,EAAE,CAAC;AACrD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,MAAM,MAAM,OAAO,KAAK;AAAA,EAC1B;AACF;",
+  "names": []
+}

package/autoload/define-manifest.d.ts

@@ -0,0 +1,60 @@
+import type { ComponentLoadStrategy, ComponentManifest } from './types.js';
+/**
+ * A map of module keys to lazy importers, as produced by bundler glob helpers.
+ *
+ * This is the shape Vite's `import.meta.glob('./x/*.ts')` returns, and the shape the
+ * {@link fromWebpackContext} adapter normalizes a webpack context to. Every value is a function
+ * that imports the module and resolves its namespace object.
+ */
+export type ModuleRecord = Record<string, () => Promise<Record<string, unknown>>>;
+/**
+ * A per-token override applied on top of the values {@link defineManifest} derives from a module
+ * key. Every field is optional; an omitted field keeps the derived or option-level default.
+ */
+export interface ComponentOverride {
+    /** Replace the token derived from the module key. */
+    token?: string;
+    /** Override the load strategy for this component. */
+    strategy?: ComponentLoadStrategy;
+    /** Override the grouping key for this component. */
+    group?: string;
+    /** The named export to resolve from the module; defaults to the derived token. */
+    exportName?: string;
+    /** The tokens of the constructor's configured child components, for recursive registration. */
+    children?: readonly string[];
+    /** Stylesheet paths associated with this component (informational). */
+    styles?: readonly string[];
+    /** Optional integration keys associated with this component (informational). */
+    integrations?: readonly string[];
+}
+/** Options accepted by {@link defineManifest}. */
+export interface DefineManifestOptions {
+    /**
+     * The lazy importers to build entries from, keyed by module path. Feed it a bundler glob directly
+     * or normalize one first with {@link fromMetaGlob} / {@link fromWebpackContext}.
+     */
+    modules: ModuleRecord;
+    /** The npm package the components belong to (optional informational metadata). */
+    packageName?: string;
+    /** The default load strategy for every component. Defaults to `'eager'`. */
+    strategy?: ComponentLoadStrategy;
+    /** The default grouping key for every component. Defaults to each component's token. */
+    group?: string;
+    /** Per-token overrides, keyed by the token derived from the module key. */
+    components?: Record<string, ComponentOverride>;
+}
+/**
+ * Build a {@link ComponentManifest} from a record of lazy importers — the pure counterpart of a
+ * generated per-package manifest, for app developers autoloading their own js-toolkit components.
+ *
+ * For every `[key, importer]` in `options.modules` it derives a token from the key (see
+ * {@link deriveToken}), resolves the named export matching the token (falling back to the module's
+ * `default` export), and applies the option-level and per-token defaults. The loader validates that
+ * the resolved value is a js-toolkit `Base` constructor and reports an error event otherwise, so no
+ * validation happens here.
+ *
+ * This factory is pure: it never touches the DOM and never registers anything. Pass its result to
+ * {@link registerManifests} (or {@link autoload}) to actually start discovery. When two module keys
+ * derive the same token a `console.warn` is emitted and the later key wins.
+ */
+export declare function defineManifest(options: DefineManifestOptions): ComponentManifest;

package/autoload/define-manifest.js

@@ -0,0 +1,51 @@
+import { DEFAULT_DIAGNOSTIC_PREFIX } from "./loader.js";
+function deriveToken(key) {
+  const segments = key.split("/").filter((segment) => segment && segment !== ".");
+  const last = segments.at(-1) ?? "";
+  const base = last.replace(/\.[^.]+$/, "");
+  if (base === "index" && segments.length >= 2) {
+    return segments.at(-2);
+  }
+  return base;
+}
+function defineManifest(options) {
+  const overrides = options.components ?? {};
+  const defaultStrategy = options.strategy ?? "eager";
+  const manifest = {};
+  for (const [key, importer] of Object.entries(options.modules)) {
+    const derivedToken = deriveToken(key);
+    const override = overrides[derivedToken] ?? {};
+    const token = override.token ?? derivedToken;
+    const exportName = override.exportName ?? token;
+    if (Object.prototype.hasOwnProperty.call(manifest, token)) {
+      console.warn(
+        `${DEFAULT_DIAGNOSTIC_PREFIX} Duplicate component token "${token}" derived from "${key}"; the later module wins.`
+      );
+    }
+    const entry = {
+      token,
+      strategy: override.strategy ?? defaultStrategy,
+      group: override.group ?? options.group ?? token,
+      exportName,
+      load: () => importer().then((module) => module[exportName] ?? module.default)
+    };
+    if (options.packageName !== void 0) {
+      entry.packageName = options.packageName;
+    }
+    if (override.children !== void 0) {
+      entry.children = override.children;
+    }
+    if (override.styles !== void 0) {
+      entry.styles = override.styles;
+    }
+    if (override.integrations !== void 0) {
+      entry.integrations = override.integrations;
+    }
+    manifest[token] = entry;
+  }
+  return manifest;
+}
+export {
+  defineManifest
+};
+//# sourceMappingURL=define-manifest.js.map

package/autoload/define-manifest.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../packages/js-toolkit/autoload/define-manifest.ts"],
+  "sourcesContent": ["import type { BaseConstructor } from '../Base/index.js';\nimport { DEFAULT_DIAGNOSTIC_PREFIX } from './loader.js';\nimport type { ComponentLoadStrategy, ComponentManifest, ComponentManifestEntry } from './types.js';\n\n/**\n * A map of module keys to lazy importers, as produced by bundler glob helpers.\n *\n * This is the shape Vite's `import.meta.glob('./x/*.ts')` returns, and the shape the\n * {@link fromWebpackContext} adapter normalizes a webpack context to. Every value is a function\n * that imports the module and resolves its namespace object.\n */\nexport type ModuleRecord = Record<string, () => Promise<Record<string, unknown>>>;\n\n/**\n * A per-token override applied on top of the values {@link defineManifest} derives from a module\n * key. Every field is optional; an omitted field keeps the derived or option-level default.\n */\nexport interface ComponentOverride {\n  /** Replace the token derived from the module key. */\n  token?: string;\n  /** Override the load strategy for this component. */\n  strategy?: ComponentLoadStrategy;\n  /** Override the grouping key for this component. */\n  group?: string;\n  /** The named export to resolve from the module; defaults to the derived token. */\n  exportName?: string;\n  /** The tokens of the constructor's configured child components, for recursive registration. */\n  children?: readonly string[];\n  /** Stylesheet paths associated with this component (informational). */\n  styles?: readonly string[];\n  /** Optional integration keys associated with this component (informational). */\n  integrations?: readonly string[];\n}\n\n/** Options accepted by {@link defineManifest}. */\nexport interface DefineManifestOptions {\n  /**\n   * The lazy importers to build entries from, keyed by module path. Feed it a bundler glob directly\n   * or normalize one first with {@link fromMetaGlob} / {@link fromWebpackContext}.\n   */\n  modules: ModuleRecord;\n  /** The npm package the components belong to (optional informational metadata). */\n  packageName?: string;\n  /** The default load strategy for every component. Defaults to `'eager'`. */\n  strategy?: ComponentLoadStrategy;\n  /** The default grouping key for every component. Defaults to each component's token. */\n  group?: string;\n  /** Per-token overrides, keyed by the token derived from the module key. */\n  components?: Record<string, ComponentOverride>;\n}\n\n/**\n * Derive a component token from a module key: the basename without its extension, falling back to\n * the parent directory name when the basename is `index` (so `./a/b/Foo/index.ts` yields `Foo`).\n */\nfunction deriveToken(key: string): string {\n  const segments = key.split('/').filter((segment) => segment && segment !== '.');\n  const last = segments.at(-1) ?? '';\n  const base = last.replace(/\\.[^.]+$/, '');\n  if (base === 'index' && segments.length >= 2) {\n    return segments.at(-2) as string;\n  }\n  return base;\n}\n\n/**\n * Build a {@link ComponentManifest} from a record of lazy importers \u2014 the pure counterpart of a\n * generated per-package manifest, for app developers autoloading their own js-toolkit components.\n *\n * For every `[key, importer]` in `options.modules` it derives a token from the key (see\n * {@link deriveToken}), resolves the named export matching the token (falling back to the module's\n * `default` export), and applies the option-level and per-token defaults. The loader validates that\n * the resolved value is a js-toolkit `Base` constructor and reports an error event otherwise, so no\n * validation happens here.\n *\n * This factory is pure: it never touches the DOM and never registers anything. Pass its result to\n * {@link registerManifests} (or {@link autoload}) to actually start discovery. When two module keys\n * derive the same token a `console.warn` is emitted and the later key wins.\n */\nexport function defineManifest(options: DefineManifestOptions): ComponentManifest {\n  const overrides = options.components ?? {};\n  const defaultStrategy = options.strategy ?? 'eager';\n  const manifest: ComponentManifest = {};\n\n  for (const [key, importer] of Object.entries(options.modules)) {\n    const derivedToken = deriveToken(key);\n    const override = overrides[derivedToken] ?? {};\n    const token = override.token ?? derivedToken;\n    const exportName = override.exportName ?? token;\n\n    if (Object.prototype.hasOwnProperty.call(manifest, token)) {\n      console.warn(\n        `${DEFAULT_DIAGNOSTIC_PREFIX} Duplicate component token \"${token}\" derived from \"${key}\"; the later module wins.`,\n      );\n    }\n\n    const entry: ComponentManifestEntry = {\n      token,\n      strategy: override.strategy ?? defaultStrategy,\n      group: override.group ?? options.group ?? token,\n      exportName,\n      load: () =>\n        importer().then((module) => (module[exportName] ?? module.default) as BaseConstructor),\n    };\n\n    if (options.packageName !== undefined) {\n      entry.packageName = options.packageName;\n    }\n    if (override.children !== undefined) {\n      entry.children = override.children;\n    }\n    if (override.styles !== undefined) {\n      entry.styles = override.styles;\n    }\n    if (override.integrations !== undefined) {\n      entry.integrations = override.integrations;\n    }\n\n    manifest[token] = entry;\n  }\n\n  return manifest;\n}\n"],
+  "mappings": "AACA,SAAS,iCAAiC;AAsD1C,SAAS,YAAY,KAAqB;AACxC,QAAM,WAAW,IAAI,MAAM,GAAG,EAAE,OAAO,CAAC,YAAY,WAAW,YAAY,GAAG;AAC9E,QAAM,OAAO,SAAS,GAAG,EAAE,KAAK;AAChC,QAAM,OAAO,KAAK,QAAQ,YAAY,EAAE;AACxC,MAAI,SAAS,WAAW,SAAS,UAAU,GAAG;AAC5C,WAAO,SAAS,GAAG,EAAE;AAAA,EACvB;AACA,SAAO;AACT;AAgBO,SAAS,eAAe,SAAmD;AAChF,QAAM,YAAY,QAAQ,cAAc,CAAC;AACzC,QAAM,kBAAkB,QAAQ,YAAY;AAC5C,QAAM,WAA8B,CAAC;AAErC,aAAW,CAAC,KAAK,QAAQ,KAAK,OAAO,QAAQ,QAAQ,OAAO,GAAG;AAC7D,UAAM,eAAe,YAAY,GAAG;AACpC,UAAM,WAAW,UAAU,YAAY,KAAK,CAAC;AAC7C,UAAM,QAAQ,SAAS,SAAS;AAChC,UAAM,aAAa,SAAS,cAAc;AAE1C,QAAI,OAAO,UAAU,eAAe,KAAK,UAAU,KAAK,GAAG;AACzD,cAAQ;AAAA,QACN,GAAG,yBAAyB,+BAA+B,KAAK,mBAAmB,GAAG;AAAA,MACxF;AAAA,IACF;AAEA,UAAM,QAAgC;AAAA,MACpC;AAAA,MACA,UAAU,SAAS,YAAY;AAAA,MAC/B,OAAO,SAAS,SAAS,QAAQ,SAAS;AAAA,MAC1C;AAAA,MACA,MAAM,MACJ,SAAS,EAAE,KAAK,CAAC,WAAY,OAAO,UAAU,KAAK,OAAO,OAA2B;AAAA,IACzF;AAEA,QAAI,QAAQ,gBAAgB,QAAW;AACrC,YAAM,cAAc,QAAQ;AAAA,IAC9B;AACA,QAAI,SAAS,aAAa,QAAW;AACnC,YAAM,WAAW,SAAS;AAAA,IAC5B;AACA,QAAI,SAAS,WAAW,QAAW;AACjC,YAAM,SAAS,SAAS;AAAA,IAC1B;AACA,QAAI,SAAS,iBAAiB,QAAW;AACvC,YAAM,eAAe,SAAS;AAAA,IAChC;AAEA,aAAS,KAAK,IAAI;AAAA,EACpB;AAEA,SAAO;AACT;",
+  "names": []
+}

package/autoload/index.d.ts

@@ -0,0 +1,6 @@
+export type { ComponentLoadStrategy, ComponentManifestEntry, ComponentManifest } from './types.js';
+export { ComponentLoader, DEFAULT_DIAGNOSTIC_PREFIX, VISIBLE_ROOT_MARGIN, IDLE_TIMEOUT, type LoaderDependencies, type ComponentLoaderOptions, type ComponentLoaderStartOptions, } from './loader.js';
+export { autoload, composeManifests, type AutoloadOptions, type AutoloadHandle, } from './autoload.js';
+export { registerManifest, registerManifests, readEagerTokens, type AutoloadRuntime, type RegisterManifestOptions, } from './runtime.js';
+export { defineManifest, type ModuleRecord, type ComponentOverride, type DefineManifestOptions, } from './define-manifest.js';
+export { fromMetaGlob, fromWebpackContext, type WebpackContextLike } from './modules.js';

package/autoload/index.js

@@ -0,0 +1,34 @@
+import {
+  ComponentLoader,
+  DEFAULT_DIAGNOSTIC_PREFIX,
+  VISIBLE_ROOT_MARGIN,
+  IDLE_TIMEOUT
+} from "./loader.js";
+import {
+  autoload,
+  composeManifests
+} from "./autoload.js";
+import {
+  registerManifest,
+  registerManifests,
+  readEagerTokens
+} from "./runtime.js";
+import {
+  defineManifest
+} from "./define-manifest.js";
+import { fromMetaGlob, fromWebpackContext } from "./modules.js";
+export {
+  ComponentLoader,
+  DEFAULT_DIAGNOSTIC_PREFIX,
+  IDLE_TIMEOUT,
+  VISIBLE_ROOT_MARGIN,
+  autoload,
+  composeManifests,
+  defineManifest,
+  fromMetaGlob,
+  fromWebpackContext,
+  readEagerTokens,
+  registerManifest,
+  registerManifests
+};
+//# sourceMappingURL=index.js.map

package/autoload/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../packages/js-toolkit/autoload/index.ts"],
+  "sourcesContent": ["export type { ComponentLoadStrategy, ComponentManifestEntry, ComponentManifest } from './types.js';\nexport {\n  ComponentLoader,\n  DEFAULT_DIAGNOSTIC_PREFIX,\n  VISIBLE_ROOT_MARGIN,\n  IDLE_TIMEOUT,\n  type LoaderDependencies,\n  type ComponentLoaderOptions,\n  type ComponentLoaderStartOptions,\n} from './loader.js';\nexport {\n  autoload,\n  composeManifests,\n  type AutoloadOptions,\n  type AutoloadHandle,\n} from './autoload.js';\nexport {\n  registerManifest,\n  registerManifests,\n  readEagerTokens,\n  type AutoloadRuntime,\n  type RegisterManifestOptions,\n} from './runtime.js';\nexport {\n  defineManifest,\n  type ModuleRecord,\n  type ComponentOverride,\n  type DefineManifestOptions,\n} from './define-manifest.js';\nexport { fromMetaGlob, fromWebpackContext, type WebpackContextLike } from './modules.js';\n"],
+  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,OAIK;AACP,SAAS,cAAc,0BAAmD;",
+  "names": []
+}

package/autoload/loader.d.ts

@@ -0,0 +1,108 @@
+import type { BaseConstructor } from '../Base/index.js';
+import type { ComponentLoadStrategy, ComponentManifest, ComponentManifestEntry } from './types.js';
+/** The diagnostic prefix used when the host does not inject its own. */
+export declare const DEFAULT_DIAGNOSTIC_PREFIX = "[@studiometa/js-toolkit/autoload]";
+/** Start loading visible components shortly before they enter the viewport. */
+export declare const VISIBLE_ROOT_MARGIN = "200px 0px";
+/** Ensure idle components eventually load even when the main thread remains busy. */
+export declare const IDLE_TIMEOUT = 2000;
+interface IdleDeadlineLike {
+    readonly didTimeout: boolean;
+    timeRemaining: () => number;
+}
+type IdleHandle = number;
+type RequestIdleCallbackLike = (callback: (deadline: IdleDeadlineLike) => void, options?: {
+    timeout: number;
+}) => IdleHandle;
+type CancelIdleCallbackLike = (handle: IdleHandle) => void;
+type RegisterComponent = (Constructor: BaseConstructor, token: string) => Promise<unknown> | unknown;
+type ComponentState = 'scheduled' | 'loading' | 'registered' | 'failed';
+interface ComponentRecord {
+    state: ComponentState;
+    promise?: Promise<void>;
+    Constructor?: BaseConstructor;
+    cleanups: Set<() => void>;
+    scheduledStrategies: Set<ComponentLoadStrategy>;
+}
+export interface LoaderDependencies {
+    document: Document;
+    MutationObserver?: typeof MutationObserver;
+    IntersectionObserver?: typeof IntersectionObserver;
+    requestIdleCallback?: RequestIdleCallbackLike;
+    cancelIdleCallback?: CancelIdleCallbackLike;
+    setTimeout: typeof globalThis.setTimeout;
+    clearTimeout: typeof globalThis.clearTimeout;
+    registerComponent: RegisterComponent;
+    console: Pick<Console, 'warn' | 'error'>;
+    CustomEvent: typeof CustomEvent;
+    /** The prefix prepended to every diagnostic message emitted by the loader. */
+    diagnosticPrefix: string;
+}
+export interface ComponentLoaderOptions {
+    manifest: ComponentManifest;
+    /** The DOM scope to scan and observe. Defaults to the injected `document`. */
+    root?: Document | Element;
+    dependencies?: Partial<LoaderDependencies>;
+}
+export interface ComponentLoaderStartOptions {
+    eagerComponents?: Iterable<string>;
+}
+/**
+ * Discover declarative components and schedule each constructor exactly once.
+ *
+ * The loader is generic: it knows nothing hard-coded about any component package and works purely
+ * from the manifest it is given. Importing this module has no side effects — discovery only starts
+ * when {@link ComponentLoader.start} is called.
+ */
+export declare class ComponentLoader {
+    /** @private */
+    __manifest: ComponentManifest;
+    /** @private */
+    __dependencies: LoaderDependencies;
+    /** @private */
+    __root: Document | Element;
+    /** @private */
+    __records: Map<string, ComponentRecord>;
+    /** @private */
+    __eagerComponents: Set<string>;
+    /** @private */
+    __elementSchedules: WeakMap<Element, Set<string>>;
+    /** @private */
+    __elementCleanups: WeakMap<Element, Set<() => void>>;
+    /** @private */
+    __mutationObserver?: MutationObserver;
+    /** @private */
+    __started: boolean;
+    constructor({ manifest, root, dependencies }: ComponentLoaderOptions);
+    start({ eagerComponents }?: ComponentLoaderStartOptions): void;
+    stop(): void;
+    /** @private */
+    __scan(root: Document | Element): void;
+    /** @private */
+    __discover(element: Element): void;
+    /** @private */
+    __getEntry(token: string): ComponentManifestEntry | undefined;
+    /** @private */
+    __getStrategy(element: Element, entry: ComponentManifestEntry): ComponentLoadStrategy;
+    /** @private */
+    __getRecord(token: string): ComponentRecord;
+    /** @private */
+    __schedule(token: string, strategy: ComponentLoadStrategy, element?: Element): void;
+    /** @private */
+    __begin(token: string, record: ComponentRecord): void;
+    /** @private */
+    __registerConfiguredChildren(parentToken: string, ParentConstructor: BaseConstructor, visited: Set<string>): Promise<void>;
+    /** @private */
+    __registerConfiguredChild(token: string, Constructor: BaseConstructor, record: ComponentRecord, visited: Set<string>): Promise<void>;
+    /** @private */
+    __addCleanup(record: ComponentRecord, cleanup: () => void, element?: Element): void;
+    /** @private */
+    __cleanSubtree(root: Element): void;
+    /** @private */
+    __clean(record: ComponentRecord): void;
+    /** @private */
+    __warn(message: string): void;
+    /** @private */
+    __reportError(token: string, stage: 'import' | 'registration', error: unknown): void;
+}
+export {};