@electrojs/runtime 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1476 @@
+import { a as createBridgeClient, i as PreloadBridgeApi, n as ElectroIpcRenderer, r as IPC_CHANNELS, t as BridgeClientConfig } from "./client-CVXQ55OB.mjs";
+import * as electron from "electron";
+import { BaseWindow, BaseWindowConstructorOptions, Rectangle, WebContents, WebContentsView, WebPreferences } from "electron";
+import { Constructor, InjectionToken, Provider, ProviderScope } from "@electrojs/common";
+
+//#region src/logging.d.ts
+type ElectroLogLevel = "debug" | "info" | "warn" | "error";
+interface ElectroLogBindings {
+  readonly target?: string;
+}
+interface ElectroLogContext {
+  readonly [key: string]: unknown;
+}
+interface ElectroLogger {
+  debug(message: string, context?: ElectroLogContext): void;
+  info(message: string, context?: ElectroLogContext): void;
+  warn(message: string, context?: ElectroLogContext): void;
+  error(message: string, context?: ElectroLogContext): void;
+  child(bindings: ElectroLogBindings): ElectroLogger;
+}
+declare function createConsoleLogger(): ElectroLogger;
+//#endregion
+//#region src/container/injector.d.ts
+/**
+ * Hierarchical dependency injection container.
+ *
+ * Each module in the runtime graph owns an `Injector` instance. Injectors form a parent-child
+ * tree: when a token is not found locally, resolution walks up to the parent injector.
+ *
+ * Providers are registered via {@link Injector.provide} (class-based) or
+ * {@link Injector.provideValue} (pre-existing value). Resolution is triggered by
+ * {@link Injector.get} or indirectly by calling {@link inject} inside a framework-managed context.
+ *
+ * @remarks
+ * - Singleton providers are instantiated once per injector and cached.
+ * - Transient providers create a new instance on every resolution.
+ * - Circular dependencies are detected at resolution time and throw {@link DIError}.
+ *
+ * @example
+ * ```ts
+ * const root = new Injector();
+ * root.provide(MyService);
+ *
+ * const child = root.createChild();
+ * child.get(MyService); // resolves from root
+ * ```
+ */
+declare class Injector {
+  private readonly parent?;
+  private readonly providers;
+  private readonly instances;
+  private readonly resolutionPath;
+  constructor(parent?: Injector | undefined);
+  /** Create a child injector that delegates unresolved tokens to this injector. */
+  createChild(): Injector;
+  /**
+   * Register a class-based provider.
+   *
+   * Accepts either a bare `@Injectable()` class or a `{ provide, useClass }` object.
+   *
+   * @throws {@link DIError} if a provider with the same token is already registered in this injector.
+   */
+  provide(provider: Provider): void;
+  /**
+   * Register a pre-existing value as a provider.
+   *
+   * Use this for configuration objects, constants, or instances created outside the DI system.
+   *
+   * @throws {@link DIError} if a provider with the same token is already registered in this injector.
+   */
+  provideValue<T>(token: InjectionToken<T>, value: T): void;
+  /** Check whether a provider is registered for the given token in this injector or any ancestor. */
+  has(token: InjectionToken): boolean;
+  /**
+   * Resolve a provider by token, instantiating it if necessary.
+   *
+   * Resolution walks up the injector hierarchy until a matching provider is found.
+   *
+   * @throws {@link DIError} if no provider is found, a circular dependency is detected,
+   *         or the target class is not framework-managed.
+   */
+  get<T>(token: InjectionToken<T>): T;
+  private resolve;
+  private resolveRecord;
+  private resolveSingleton;
+  private instantiate;
+  private resolveWithPath;
+}
+//#endregion
+//#region src/modules/scanner.d.ts
+/** Discriminates the role of a provider: plain service, renderer view, or window host. */
+type ProviderKind = "provider" | "view" | "window";
+/** Discriminates bridge method semantics: commands mutate state, queries are read-only. */
+type BridgeMethodKind = "command" | "query";
+/**
+ * Static, serializable description of a module extracted from `@Module()` decorator metadata.
+ * This is the first layer of the two-layer entity model -- it captures the declaration
+ * without instantiating anything, making it suitable for static analysis and tooling.
+ */
+interface ModuleDefinition {
+  /** Unique module identifier, derived from the class name or explicit `@Module({ id })`. */
+  readonly id: string;
+  /** The decorated module class constructor. */
+  readonly target: Constructor;
+  /** Module constructors this module imports (resolved from `@Module({ imports })`). */
+  readonly imports: readonly Constructor[];
+  /** Runtime-managed declarations declared in this module, fully scanned with capabilities. */
+  readonly providers: readonly ProviderDefinition[];
+  /** Provider constructors this module exports to importers. */
+  readonly exportTargets: readonly Constructor[];
+}
+/**
+ * Static description of a provider (service, view, or window) within a module.
+ * Aggregates all capability metadata (bridge methods, signal handlers, jobs) discovered
+ * from the provider's decorated methods.
+ */
+interface ProviderDefinition {
+  /** Provider identifier, defaults to the class name. */
+  readonly id: string;
+  readonly target: Constructor;
+  /** ID of the module that owns this provider. */
+  readonly ownerModuleId: string;
+  readonly scope: ProviderScope;
+  readonly kind: ProviderKind;
+  /** Present only if the provider is decorated with `@View()`. */
+  readonly view?: ViewDefinition;
+  /** Present only if the provider is decorated with `@Window()`. */
+  readonly window?: WindowDefinition;
+  /** Bridge command/query methods exposed by this provider. */
+  readonly bridgeMethods: readonly BridgeMethodDefinition[];
+  /** Signal subscriptions declared by this provider. */
+  readonly signalHandlers: readonly SignalHandlerDefinition[];
+  /** Scheduled jobs declared by this provider. */
+  readonly jobs: readonly JobDefinition[];
+}
+/**
+ * Static description of a renderer view, extracted from `@View()` decorator metadata.
+ * Views represent web content (HTML pages or routes) rendered inside a `BrowserWindow`.
+ */
+interface ViewDefinition {
+  readonly id: string;
+  readonly ownerModuleId: string;
+  /** Path or URL to the HTML/renderer entry for this view. */
+  readonly source: string;
+  /** Bridge channels this view is allowed to invoke (allowlist for access control). */
+  readonly access: readonly string[];
+  /** Signal IDs this view is allowed to receive. */
+  readonly signals: readonly string[];
+  readonly target: Constructor;
+  /** Optional Electron configuration from `@View({ configuration })` (webPreferences, etc). */
+  readonly configuration?: {
+    readonly webPreferences?: electron.WebPreferences;
+  };
+}
+/**
+ * Static description of an Electron `BrowserWindow` host, extracted from `@Window()` decorator metadata.
+ */
+interface WindowDefinition {
+  readonly id: string;
+  readonly ownerModuleId: string;
+  readonly target: Constructor;
+  /** Optional Electron `BrowserWindow` configuration overrides. */
+  readonly configuration?: object;
+}
+/**
+ * Static description of a bridge method (IPC handler) exposed to the renderer process.
+ * Channel names are derived as `moduleId:methodId`.
+ */
+interface BridgeMethodDefinition {
+  /** Fully qualified IPC channel name (`moduleId:methodId`). */
+  readonly channel: string;
+  readonly kind: BridgeMethodKind;
+  readonly moduleId: string;
+  readonly providerName: string;
+  /** Name of the method on the provider class that handles this channel. */
+  readonly methodName: string;
+}
+/**
+ * Static description of a signal handler that subscribes to an application signal.
+ * Signal IDs come from the `@signal()` decorator's `id` option, or default to the method name.
+ */
+interface SignalHandlerDefinition {
+  /** Signal identifier this handler subscribes to (from `@signal({ id })` or method name). */
+  readonly signalId: string;
+  readonly moduleId: string;
+  readonly providerName: string;
+  /** Name of the method on the provider class that handles this signal. */
+  readonly methodName: string;
+}
+/**
+ * Static description of a scheduled job declared via `@Job()` decorator.
+ */
+interface JobDefinition {
+  /** Fully qualified job identifier (`moduleId:methodId`). */
+  readonly jobId: string;
+  readonly moduleId: string;
+  readonly providerName: string;
+  /** Name of the method on the provider class that executes this job. */
+  readonly methodName: string;
+  /** Optional cron expression for recurring execution. */
+  readonly cron?: string;
+}
+/**
+ * Complete static description of an application's module graph and all capabilities.
+ *
+ * This is the top-level output of {@link scanModules} and the first layer of the
+ * two-layer entity model. It is fully serializable (except `target` constructor
+ * references) for use by CLI tooling, validation, and static analysis.
+ */
+interface AppDefinition {
+  /** The root module constructor that was passed to {@link scanModules}. */
+  readonly rootModule: Constructor;
+  /** All discovered modules in traversal order (root-first). */
+  readonly modules: readonly ModuleDefinition[];
+  /** All providers across all modules. */
+  readonly providers: readonly ProviderDefinition[];
+  /** All views across all modules. */
+  readonly views: readonly ViewDefinition[];
+  /** All windows across all modules. */
+  readonly windows: readonly WindowDefinition[];
+  /** All bridge methods (commands and queries) across all providers. */
+  readonly bridgeMethods: readonly BridgeMethodDefinition[];
+  /** All signal handlers across all providers. */
+  readonly signalHandlers: readonly SignalHandlerDefinition[];
+  /** All scheduled jobs across all providers. */
+  readonly jobs: readonly JobDefinition[];
+}
+/**
+ * Recursively walks the module graph starting from `rootModule`, reading `@Module()`,
+ * `@Injectable()`, `@View()`, `@Window()`, and method decorators to produce a complete
+ * {@link AppDefinition}.
+ *
+ * This is a pure metadata read -- no instances are created. The resulting definition
+ * is passed to {@link validateAppDefinition} and then to the instance loader.
+ *
+ * @throws {BootstrapError} If a module or provider is missing required decorator metadata,
+ *   or if an imported class is not a valid module.
+ */
+declare function scanModules(rootModule: Constructor): AppDefinition;
+//#endregion
+//#region src/modules/refs.d.ts
+/**
+ * Optional lifecycle hooks that modules and providers can implement to participate
+ * in the application startup/shutdown sequence.
+ *
+ * Hooks are called per-module in dependency-first topological order during startup,
+ * and in reverse order during shutdown. Within each module, provider hooks run
+ * before the module's own hook.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class DatabaseService implements LifecycleTarget {
+ *     async onInit() { await this.connect(); }
+ *     async onShutdown() { await this.disconnect(); }
+ * }
+ * ```
+ *
+ * @remarks
+ * All hooks may be synchronous or asynchronous. A thrown error in any startup hook
+ * triggers automatic rollback of already-initialized modules.
+ */
+interface LifecycleTarget {
+  /** Called during initialization phase. Use for setting up connections, state, etc. */
+  onInit?(): void | Promise<void>;
+  /** Called after all modules have been initialized. Use for cross-module coordination. */
+  onReady?(): void | Promise<void>;
+  /** Called during graceful shutdown. Use for releasing resources, closing connections. */
+  onShutdown?(): void | Promise<void>;
+  /** Called after shutdown completes. Use for final cleanup (file handles, timers, etc.). */
+  onDispose?(): void | Promise<void>;
+}
+/**
+ * Represents the current phase of a module's lifecycle.
+ *
+ * Transitions follow a strict state machine: creating -> ready -> started -> stopping -> stopped.
+ * Any state can also transition to "failed".
+ */
+type ModuleStatus = "creating" | "ready" | "started" | "stopping" | "stopped" | "failed";
+/**
+ * Live runtime representation of a provider (service, view, or window) within a module.
+ *
+ * Wraps the instantiated provider together with its static definition and the
+ * module-scoped injector it was resolved from. Used internally by the framework
+ * to invoke bridge handlers, lifecycle hooks, and capability installations.
+ */
+declare class ProviderRef {
+  /** The static definition this provider was created from. */
+  readonly definition: ProviderDefinition;
+  /** The live provider instance, potentially implementing {@link LifecycleTarget}. */
+  readonly instance: LifecycleTarget;
+  /** The module-scoped injector that resolved this provider. */
+  readonly injector: Injector;
+  constructor(/** The static definition this provider was created from. */
+
+  definition: ProviderDefinition, /** The live provider instance, potentially implementing {@link LifecycleTarget}. */
+
+  instance: LifecycleTarget, /** The module-scoped injector that resolved this provider. */
+
+  injector: Injector);
+  get id(): string;
+  get target(): Constructor;
+  get ownerModuleId(): string;
+  /**
+   * Resolves a method on the provider instance by name.
+   * Returns `undefined` if the property does not exist or is not a function.
+   */
+  getMethod(methodName: string): ((...args: unknown[]) => unknown) | undefined;
+}
+/**
+ * Live runtime representation of a loaded module.
+ *
+ * Each `ModuleRef` holds the instantiated module class, its child injector, resolved
+ * providers, and lifecycle status. This is the second layer of the two-layer entity
+ * model: `ModuleDefinition` (static, serializable) is produced by the scanner, then
+ * `ModuleRef` is created during bootstrap when the module is actually instantiated.
+ *
+ * @remarks
+ * Status transitions are validated against an internal state machine and will throw
+ * {@link LifecycleError} on illegal transitions.
+ */
+declare class ModuleRef {
+  /** Unique module identifier, derived from the class name or `@Module({ id })`. */
+  readonly id: string;
+  /** The decorated module class constructor. */
+  readonly target: Constructor;
+  /** Module-scoped child injector containing this module's providers. */
+  readonly injector: Injector;
+  /** The live module class instance, potentially implementing {@link LifecycleTarget}. */
+  readonly instance: LifecycleTarget;
+  /** All providers declared in this module. */
+  readonly providers: readonly ProviderRef[];
+  /** Set of provider constructors that this module exports to importing modules. */
+  readonly exportTargets: ReadonlySet<Constructor>;
+  private statusInternal;
+  private importsInternal;
+  constructor(/** Unique module identifier, derived from the class name or `@Module({ id })`. */
+
+  id: string, /** The decorated module class constructor. */
+
+  target: Constructor, /** Module-scoped child injector containing this module's providers. */
+
+  injector: Injector, /** The live module class instance, potentially implementing {@link LifecycleTarget}. */
+
+  instance: LifecycleTarget, /** All providers declared in this module. */
+
+  providers: readonly ProviderRef[], /** Set of provider constructors that this module exports to importing modules. */
+
+  exportTargets: ReadonlySet<Constructor>);
+  get status(): ModuleStatus;
+  get imports(): readonly ModuleRef[];
+  /** Subset of {@link providers} that are listed in this module's exports. */
+  get exportedProviders(): readonly ProviderRef[];
+  /**
+   * @internal Sets the resolved import references after all modules are loaded.
+   * Called once during bootstrap by the instance loader.
+   */
+  linkImports(imports: readonly ModuleRef[]): void;
+  /**
+   * @internal Advances the module to the next lifecycle state.
+   * @throws {LifecycleError} If the transition is not permitted by the state machine.
+   */
+  transitionTo(next: ModuleStatus): void;
+}
+//#endregion
+//#region src/app/kernel.d.ts
+/**
+ * Represents the current phase of the application kernel's lifecycle.
+ *
+ * The state machine follows a linear progression:
+ * `idle` -> `initializing` -> `initialized` -> `starting` -> `started` -> `stopping` -> `stopped`.
+ * Any state except `stopped` can also transition to `failed`.
+ */
+type KernelState = "idle" | "initializing" | "initialized" | "starting" | "started" | "stopping" | "stopped" | "failed";
+interface AppKernelOptions {
+  readonly logger?: ElectroLogger;
+}
+/**
+ * The main entry point for an `@electrojs/runtime` application.
+ *
+ * `AppKernel` orchestrates the full application lifecycle: scanning decorator metadata,
+ * validating the module graph, creating the DI container, loading modules, installing
+ * capabilities (bridge handlers, signals, jobs, desktop providers), and running
+ * lifecycle hooks in the correct order.
+ *
+ * @example
+ * ```ts
+ * const kernel = AppKernel.create(AppModule);
+ * await kernel.start();
+ *
+ * // ... app is running ...
+ *
+ * await kernel.shutdown();
+ * ```
+ *
+ * @remarks
+ * - Calling {@link start} when already started is a no-op.
+ * - If startup fails, the kernel automatically rolls back initialized modules and
+ *   transitions to `failed`.
+ * - {@link shutdown} can only be called from the `started` state.
+ */
+declare class AppKernel {
+  private state;
+  private composition?;
+  private services?;
+  private readonly rootModule;
+  private readonly logger;
+  private readonly stateListeners;
+  private readonly disposers;
+  private constructor();
+  /**
+   * Creates a new kernel instance for the given root module.
+   * The kernel starts in the `idle` state -- call {@link start} to bootstrap the application.
+   */
+  static create(rootModule: Constructor, options?: AppKernelOptions): AppKernel;
+  /**
+   * Bootstraps and starts the application.
+   *
+   * Performs module scanning, validation, DI container creation, module instantiation,
+   * capability installation, and runs `onInit` / `onReady` lifecycle hooks.
+   * On failure, automatically rolls back and transitions to `failed`.
+   *
+   * @remarks No-op if already started. Must be called from `idle` state.
+   * @throws {BootstrapError} On invalid module graph or decorator metadata.
+   * @throws {LifecycleError} On lifecycle hook failure.
+   */
+  start(): Promise<void>;
+  /**
+   * Gracefully shuts down the application.
+   *
+   * Runs `onShutdown` / `onDispose` lifecycle hooks in reverse module order,
+   * then disposes framework services (jobs, windows, views).
+   *
+   * @remarks No-op if `idle` or already `stopped`. Throws if not in `started` state.
+   * @throws {LifecycleError} If the kernel is not in the `started` state.
+   */
+  shutdown(): Promise<void>;
+  /** Returns the current kernel lifecycle state. */
+  getState(): KernelState;
+  /** Convenience check: returns `true` only when the kernel is in the `started` state. */
+  isStarted(): boolean;
+  /** Returns the scanned app definition, or `undefined` if the kernel has not been started yet. */
+  getDefinition(): AppDefinition | undefined;
+  /** Returns the live module references, or an empty array if the kernel has not been started yet. */
+  getModuleRefs(): readonly ModuleRef[];
+  /** @internal Hook for subsystems that need to react to kernel state changes. */
+  onStateChange(callback: (state: KernelState) => void): void;
+  private registerFrameworkServices;
+  private disposeServices;
+  private transitionTo;
+  private safeDisposeServices;
+}
+//#endregion
+//#region src/container/inject.d.ts
+/**
+ * Resolve a dependency from the current injection context.
+ *
+ * This is the primary way framework-managed classes obtain their dependencies.
+ * It reads the active {@link Injector} from `AsyncLocalStorage` and delegates to
+ * {@link Injector.get}.
+ *
+ * @remarks
+ * `inject()` is only available inside a framework-managed execution scope:
+ * - **Construction** -- property initializers of `@Injectable()`, `@Module()`, `@View()`, or `@Window()` classes
+ * - **Lifecycle hooks** -- `onInit`, `onReady`, `onShutdown`, `onDispose`
+ * - **Capability handlers** -- methods decorated with `@command`, `@query`, `@signal`, or `@job`
+ *
+ * Calling it anywhere else (e.g. in a `setTimeout` callback or a plain function)
+ * throws {@link DIError} with code `ELECTRO_DI_NO_INJECTION_CONTEXT`.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyService {
+ *   private readonly config = inject(AppConfig);
+ * }
+ * ```
+ *
+ * @throws {@link DIError} if no injection context is active or the token cannot be resolved.
+ */
+declare function inject<T>(token: InjectionToken<T>): T;
+//#endregion
+//#region src/container/injection-context.d.ts
+/**
+ * Ambient injection context backed by `AsyncLocalStorage`.
+ *
+ * The framework uses `InjectionContext` to make the current {@link Injector} available
+ * to {@link inject} calls without requiring explicit injector references. It is set
+ * automatically during provider construction, lifecycle hooks, and capability handlers.
+ *
+ * @remarks
+ * This is a framework-internal API. Application code should use {@link inject} instead
+ * of interacting with `InjectionContext` directly.
+ *
+ * @internal
+ */
+declare const InjectionContext: {
+  /**
+   * Execute `fn` within the scope of the given injector.
+   * Any {@link inject} call made synchronously inside `fn` will resolve from this injector.
+   */
+  readonly run: <T>(injector: Injector, fn: () => T) => T;
+  /**
+   * Execute `fn` within the scope of the given injector, additionally tracking `owner`
+   * as the object currently being constructed or invoked.
+   */
+  readonly runOwned: <T>(injector: Injector, owner: object, fn: () => T) => T; /** Return the injector for the current execution context, or `undefined` if none is active. */
+  readonly current: () => Injector | undefined; /** Return the owner object of the current execution context, or `undefined` if not set. */
+  readonly currentOwner: () => object | undefined; /** Whether a framework-managed injection context is currently active. */
+  readonly isActive: () => boolean;
+};
+//#endregion
+//#region src/modules/registry.d.ts
+/**
+ * Serializable point-in-time view of a provider's registration state.
+ * Produced by {@link ModuleRegistry.snapshot} for runtime introspection and tooling.
+ */
+interface ProviderSnapshot {
+  readonly id: string;
+  readonly target: string;
+  readonly kind: "provider" | "view" | "window";
+  readonly scope: string;
+  /** Bridge channels this provider exposes (commands and queries). */
+  readonly bridgeChannels: readonly string[];
+  /** Signal IDs this provider subscribes to. */
+  readonly signalIds: readonly string[];
+  /** Scheduled job IDs registered by this provider. */
+  readonly jobIds: readonly string[];
+}
+/**
+ * Serializable point-in-time view of a module's registration and lifecycle state.
+ * Produced by {@link ModuleRegistry.snapshot} for runtime introspection and tooling (e.g. CLI module graph).
+ */
+interface ModuleSnapshot {
+  readonly id: string;
+  readonly target: string;
+  readonly status: ModuleStatus;
+  /** IDs of modules this module imports. */
+  readonly imports: readonly string[];
+  /** Class names of providers this module exports. */
+  readonly exports: readonly string[];
+  readonly providers: readonly ProviderSnapshot[];
+}
+/**
+ * Central registry of all loaded modules in the application.
+ *
+ * Provides lookup by class constructor or module ID, and produces serializable
+ * snapshots for runtime introspection (e.g. CLI `inspect` commands, debug tooling).
+ * Populated once during bootstrap by the capability installer.
+ *
+ * @example
+ * ```ts
+ * const registry = injector.get(ModuleRegistry);
+ * const snapshot = registry.snapshot(); // serializable module graph
+ * ```
+ */
+declare class ModuleRegistry {
+  private readonly modulesByTarget;
+  private readonly modulesById;
+  /** @internal Populate the registry from bootstrap. Called once by the capability installer. */
+  load(moduleRefs: readonly ModuleRef[]): void;
+  /** Looks up a module by its decorated class constructor. */
+  getByTarget(target: Constructor): ModuleRef | undefined;
+  /** Looks up a module by its unique string identifier. */
+  getById(moduleId: string): ModuleRef | undefined;
+  /** Returns all registered modules. */
+  getAll(): readonly ModuleRef[];
+  /** Produces a serializable snapshot of the entire module graph for introspection. */
+  snapshot(): readonly ModuleSnapshot[];
+}
+//#endregion
+//#region src/modules/validator.d.ts
+/**
+ * Validates a scanned {@link AppDefinition} for structural correctness before bootstrap.
+ *
+ * Checks performed:
+ * - Unique module IDs
+ * - Exports reference declared providers
+ * - No cyclic module imports
+ * - Unique view/window IDs
+ * - Unique bridge channel names
+ * - Unique job IDs
+ * - Provider role exclusivity (a class cannot be both a view and a window)
+ * - View access references point to existing bridge channels
+ *
+ * @throws {BootstrapError} On the first validation failure encountered.
+ */
+declare function validateAppDefinition(definition: AppDefinition): void;
+//#endregion
+//#region src/signals/relay.d.ts
+/**
+ * Callback invoked by {@link PublicationRelay} whenever a signal is published.
+ *
+ * Typically used by the renderer registry to forward signals from the main process
+ * to renderer processes that have opted in via `@View({ signals: [...] })`.
+ */
+type SignalPublishListener = (signalId: string, payload: unknown) => void;
+//#endregion
+//#region src/signals/context.d.ts
+/**
+ * Metadata object passed to {@link ContextualSignalHandler} callbacks when a signal is published.
+ *
+ * Provides contextual information about the publication event. Handlers that need
+ * access to this metadata should declare two parameters (context, payload) so the
+ * {@link SignalBus} treats them as contextual handlers.
+ */
+declare class SignalContext {
+  /** Epoch timestamp (milliseconds) captured at the moment the signal was dispatched to this handler. */
+  readonly timestamp: number;
+}
+//#endregion
+//#region src/signals/bus.d.ts
+/**
+ * A callback that receives only the signal payload.
+ *
+ * Use this form when the handler does not need access to the {@link SignalContext}.
+ */
+type SignalListener<T = unknown> = (payload: T) => void | Promise<void>;
+/**
+ * A callback that receives both a {@link SignalContext} and the signal payload.
+ *
+ * Use this form when the handler needs metadata about the publication (e.g. timestamp).
+ */
+type ContextualSignalHandler<T = unknown> = (context: SignalContext, payload: T) => void | Promise<void>;
+/**
+ * Union of the two supported handler signatures for {@link SignalBus.subscribe}.
+ *
+ * The bus distinguishes between the two forms by arity: handlers with two or more
+ * parameters are treated as {@link ContextualSignalHandler}, all others as {@link SignalListener}.
+ */
+type SignalHandler<T = unknown> = SignalListener<T> | ContextualSignalHandler<T>;
+/**
+ * Fire-and-forget publish/subscribe signal bus for decoupled inter-module communication.
+ *
+ * Handlers are dispatched asynchronously via `queueMicrotask`, so `publish()` never blocks
+ * the caller. Each handler runs inside the dependency-injection context that was active at
+ * the time `subscribe()` was called, which means `inject()` works correctly inside handlers.
+ *
+ * @example
+ * ```ts
+ * // Subscribe to a signal (returns an unsubscribe function)
+ * const unsub = signalBus.subscribe('user:login', (payload) => {
+ *     console.log('User logged in:', payload.userId);
+ * });
+ *
+ * // Publish a signal — all handlers run asynchronously
+ * signalBus.publish('user:login', { userId: '42' });
+ *
+ * // Unsubscribe when no longer needed
+ * unsub();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Contextual handler with access to SignalContext
+ * signalBus.subscribe('data:sync', (context, payload) => {
+ *     console.log('Signal published at:', context.timestamp);
+ * });
+ * ```
+ */
+declare class SignalBus {
+  private readonly handlers;
+  private readonly relay;
+  /**
+   * Register a handler for the given signal.
+   *
+   * The handler is bound to the current injection context at call time, so
+   * `inject()` resolves correctly even though the handler runs asynchronously.
+   *
+   * @returns A dispose function that removes the subscription.
+   */
+  subscribe<T>(signalId: string, handler: SignalHandler<T>): () => void;
+  /**
+   * Publish a signal to all registered handlers.
+   *
+   * Handlers are invoked asynchronously via `queueMicrotask` and their errors are
+   * logged but never propagated to the publisher. The signal is also forwarded to
+   * any connected {@link PublicationRelay} listeners (e.g. renderer processes).
+   *
+   * @remarks Payload is optional for signals that carry no data (`SignalBus.publish<void>('app:ready')`).
+   */
+  publish<T = void>(signalId: string, payload?: T): void;
+  /** @internal Connect a relay listener (used by renderer registry). */
+  connectRelay(listener: SignalPublishListener): () => void;
+}
+//#endregion
+//#region src/jobs/context.d.ts
+/**
+ * Execution context passed to every job handler invocation.
+ *
+ * Provides cooperative cancellation and progress reporting. The handler should
+ * periodically check {@link isCanceled} and abort work when it returns `true`.
+ *
+ * @example
+ * ```ts
+ * async function cleanupHandler(ctx: JobContext) {
+ *     const items = await fetchItems();
+ *     for (let i = 0; i < items.length; i++) {
+ *         if (ctx.isCanceled) return;
+ *         await processItem(items[i]);
+ *         ctx.setProgress((i / items.length) * 100);
+ *     }
+ * }
+ * ```
+ */
+declare class JobContext {
+  private canceledInternal;
+  private progressInternal;
+  /** Whether cancellation has been requested for this execution. */
+  get isCanceled(): boolean;
+  /** Current progress value, clamped to 0-100. */
+  get progress(): number;
+  /**
+   * Report execution progress.
+   *
+   * @remarks Values are clamped to the 0-100 range.
+   */
+  setProgress(value: number): void;
+  /** @internal */
+  cancel(): void;
+}
+//#endregion
+//#region src/jobs/registry.d.ts
+type Awaitable$1<T> = T | PromiseLike<T>;
+/**
+ * Describes a job as provided during module bootstrap.
+ *
+ * @internal Consumed by {@link JobRegistry.register}; not intended for direct consumer use.
+ */
+interface JobDefinitionRecord {
+  readonly jobId: string;
+  /** Cron expression (Croner syntax). Omit for manually-triggered-only jobs. */
+  readonly cron?: string;
+  /** The handler to execute. Receives a {@link JobContext} for cancellation/progress, plus any extra args from manual runs. */
+  readonly handler: (context: JobContext, ...args: unknown[]) => Awaitable$1<unknown>;
+  /** Injector used to restore the DI context when the handler runs. */
+  readonly injector: Injector;
+}
+/** Lifecycle state of a registered job. */
+type JobStatus = "idle" | "scheduled" | "running";
+/** Read-only snapshot of a job's current runtime state. */
+interface JobRuntimeState {
+  readonly jobId: string;
+  readonly status: JobStatus;
+  /** Last reported progress value (0-100). */
+  readonly progress: number;
+  /** Epoch timestamp of the last completed execution, if any. */
+  readonly lastRunAt?: number;
+}
+/**
+ * Manages the lifecycle of scheduled and manually-triggered jobs.
+ *
+ * Jobs are registered during bootstrap (via `@internal` {@link register}), then consumers
+ * interact through `start`, `stop`, `run`, and `cancel`. Scheduled jobs use Croner for
+ * cron-based timing; each execution receives a fresh {@link JobContext} for progress
+ * reporting and cooperative cancellation.
+ *
+ * @example
+ * ```ts
+ * // Start the cron scheduler for a registered job
+ * jobRegistry.start('data:cleanup');
+ *
+ * // Trigger an immediate (manual) execution
+ * await jobRegistry.run('data:cleanup');
+ *
+ * // Cancel a running execution cooperatively
+ * jobRegistry.cancel('data:cleanup');
+ *
+ * // Stop the cron scheduler and wait for any running execution to finish
+ * await jobRegistry.stop('data:cleanup');
+ * ```
+ */
+declare class JobRegistry {
+  private readonly jobs;
+  /** @internal Register a job definition during bootstrap. */
+  register(definition: JobDefinitionRecord): void;
+  /** Return a snapshot of all registered jobs and their current state. */
+  list(): readonly JobRuntimeState[];
+  /** Return the current state of a single job, or `undefined` if not registered. */
+  getStatus(jobId: string): JobRuntimeState | undefined;
+  /**
+   * Start the cron scheduler for a job if it is not already scheduled.
+   *
+   * Unlike {@link start}, this is idempotent and will not throw if the scheduler
+   * is already running.
+   */
+  ensure(jobId: string): void;
+  /**
+   * Start the cron scheduler for a job.
+   *
+   * @throws {JobError} If the job already has an active scheduler.
+   */
+  start(jobId: string): void;
+  /**
+   * Trigger an immediate (manual) execution of a job, bypassing the cron schedule.
+   *
+   * @throws {JobError} If the job is already running.
+   * @returns The value returned by the job handler.
+   */
+  run(jobId: string, ...args: unknown[]): Promise<unknown>;
+  /**
+   * Stop the cron scheduler and cancel any in-flight execution.
+   *
+   * Waits for the running execution (if any) to settle before returning. The job
+   * transitions to `"idle"` once fully stopped.
+   */
+  stop(jobId: string): Promise<void>;
+  /**
+   * Request cooperative cancellation of the currently running execution.
+   *
+   * Sets the `isCanceled` flag on the job's {@link JobContext}. The handler is
+   * responsible for checking this flag and aborting work accordingly.
+   */
+  cancel(jobId: string): void;
+  /** @internal */
+  dispose(): Promise<void>;
+  private getJobOrThrow;
+  private startScheduler;
+  private executeJob;
+}
+//#endregion
+//#region src/desktop/renderer-session.d.ts
+/**
+ * Tracks the capabilities of a single renderer process (identified by `webContentsId`).
+ *
+ * Each session records which bridge channels the renderer may invoke and which signals
+ * it is allowed to receive, as declared in the `@View()` decorator metadata. The
+ * {@link BridgeAccessGuard} and signal relay use this information to enforce per-view
+ * access control.
+ *
+ * @internal Created and managed by {@link RendererRegistry}.
+ */
+declare class RendererSession {
+  /** The Electron `webContents.id` that uniquely identifies this renderer process. */
+  readonly rendererId: number;
+  /** The view ID this renderer is associated with. */
+  readonly viewId: string;
+  /** Set of bridge channel names this renderer is allowed to invoke. */
+  readonly access: ReadonlySet<string>;
+  /** Set of signal IDs this renderer is allowed to receive. */
+  readonly allowedSignals: ReadonlySet<string>;
+  constructor(/** The Electron `webContents.id` that uniquely identifies this renderer process. */
+
+  rendererId: number, viewDef: ViewDefinition);
+  /** Check whether this renderer has access to the given bridge channel. */
+  hasAccess(channel: string): boolean;
+  /** Check whether this renderer is allowed to receive the given signal. */
+  canReceiveSignal(signalId: string): boolean;
+}
+//#endregion
+//#region src/desktop/renderer-registry.d.ts
+/**
+ * Maps Electron `webContentsId` values to {@link RendererSession} instances.
+ *
+ * Used by the bridge layer to look up which renderer process is making an IPC request
+ * and determine what channels and signals it is allowed to access. View definitions are
+ * registered at bootstrap time; sessions are created lazily when a renderer first
+ * communicates.
+ *
+ * @internal
+ */
+declare class RendererRegistry {
+  private readonly sessions;
+  private readonly viewDefinitions;
+  /** Store a view definition so that sessions can be created for it later. */
+  registerView(viewDef: ViewDefinition): void;
+  /**
+   * Return the existing session for a `webContentsId`, or create one if this is
+   * the first request from that renderer.
+   *
+   * @throws {BridgeError} If the `viewId` does not match any registered view definition.
+   */
+  getOrCreateSession(webContentsId: number, viewId: string): RendererSession;
+  /** Look up an existing session by its `webContentsId`, or `undefined` if none exists. */
+  getSession(webContentsId: number): RendererSession | undefined;
+  /** Remove a session when its renderer process is destroyed. */
+  removeSession(webContentsId: number): void;
+  /** Return all active renderer sessions. */
+  getAllSessions(): readonly RendererSession[];
+}
+//#endregion
+//#region src/desktop/view-manager.d.ts
+/**
+ * Framework-internal registry that tracks all `@View()` providers in the application.
+ *
+ * Handles registration (including injecting the source URL into the base class)
+ * and provides lookup by view ID. Consumers typically interact with views through
+ * their {@link ViewProvider} subclass rather than this manager directly.
+ *
+ * @internal
+ */
+declare class ViewManager {
+  private readonly views;
+  /**
+   * Register a view provider and apply its `@View()` source URL.
+   *
+   * @remarks Silently skips providers that do not have view metadata.
+   */
+  register(providerRef: ProviderRef): void;
+  /** Look up a registered view provider by its view ID. */
+  get(viewId: string): ProviderRef | undefined;
+  /** Return all registered view providers. */
+  list(): readonly ProviderRef[];
+  /** Clear the registry. Does not destroy any underlying web contents. */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/desktop/view-provider.d.ts
+declare const VIEW_STATE: unique symbol;
+interface ViewAuthoringSurface {
+  readonly contentView: WebContentsView | undefined;
+  readonly webContents: WebContents | undefined;
+  load(): Promise<void>;
+  setBounds(bounds: Rectangle): void;
+  setBackgroundColor(color: string): void;
+  focus(): void;
+  setWindowButtonVisibility(visible: boolean): void;
+}
+/**
+ * Abstract base class for view providers decorated with `@View()`.
+ *
+ * Extend this class to define a renderable view in your application. The framework
+ * injects the source URL from the `@View()` decorator, and your subclass gains access
+ * to methods for loading content, positioning, and styling.
+ *
+ * Views are created with strict security defaults: `sandbox: true`,
+ * `contextIsolation: true`, and `nodeIntegration: false`.
+ *
+ * @remarks The `WebContentsView` is lazily created on the first call to {@link load}.
+ *
+ * @example
+ * ```ts
+ * @View({ source: 'view:main', access: ['app:getVersion'] })
+ * class MainView extends ViewProvider {
+ *     async onReady() {
+ *         await this.load();
+ *         this.setBounds({ x: 0, y: 0, width: 800, height: 600 });
+ *     }
+ * }
+ * ```
+ */
+declare abstract class ViewProvider {
+  private [VIEW_STATE];
+  /** The underlying Electron `WebContentsView`, or `undefined` if not yet created. */
+  get contentView(): WebContentsView | undefined;
+  /** The `WebContents` associated with this view, or `undefined` if not yet created. */
+  get webContents(): WebContents | undefined;
+  /**
+   * Create the underlying `WebContentsView` (if needed) and load the configured source URL.
+   *
+   * The view is lazily created on the first call. Subsequent calls reload the source.
+   * If the previous view was destroyed (e.g. parent window closed), a new one is created.
+   * No-ops if no source URL has been configured.
+   */
+  load(): Promise<void>;
+  /** Set the position and size of this view within its parent window. */
+  setBounds(bounds: Rectangle): void;
+  /** Set the background color of the view (e.g. `"#ffffff"` or `"transparent"`). */
+  setBackgroundColor(color: string): void;
+  /** Give keyboard focus to this view's web contents. */
+  focus(): void;
+  /** Show or hide the native window traffic-light buttons for this view (macOS). */
+  setWindowButtonVisibility(visible: boolean): void;
+  private createView;
+  private static resolveSource;
+  /** @internal Called by the framework to set the view source from @View metadata. */
+  static __setSource(instance: ViewProvider, source: string): void;
+  /** @internal Called by the framework to set web preferences from @View metadata. */
+  static __setWebPreferences(instance: ViewProvider, webPreferences: WebPreferences): void;
+}
+//#endregion
+//#region src/desktop/window-manager.d.ts
+/**
+ * Framework-internal registry that tracks all `@Window()` providers in the application.
+ *
+ * Handles registration (including injecting `@Window()` configuration into the base class)
+ * and provides lookup by window ID. Consumers typically interact with windows through
+ * their {@link WindowProvider} subclass rather than this manager directly.
+ *
+ * @internal
+ */
+declare class WindowManager {
+  private readonly windows;
+  /**
+   * Register a window provider and apply its `@Window()` configuration.
+   *
+   * @remarks Silently skips providers that do not have window metadata.
+   */
+  register(providerRef: ProviderRef): void;
+  /** Look up a registered window provider by its window ID. */
+  get(windowId: string): ProviderRef | undefined;
+  /** Return all registered window providers. */
+  list(): readonly ProviderRef[];
+  /** Close all managed windows and clear the registry. */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/desktop/window-provider.d.ts
+declare const WINDOW_STATE: unique symbol;
+interface WindowAuthoringSurface {
+  readonly window: BaseWindow | undefined;
+  create(): void;
+  mount(view: Pick<ViewProvider, "contentView">): void;
+  show(): void;
+  hide(): void;
+  focus(): void;
+  close(): void;
+  getBounds(): Rectangle | undefined;
+}
+/**
+ * Abstract base class for window providers decorated with `@Window()`.
+ *
+ * Extend this class to define a window in your application. The framework injects
+ * configuration from the `@Window()` decorator metadata, and your subclass gains
+ * access to lifecycle methods like {@link create}, {@link show}, {@link mount}, and {@link close}.
+ *
+ * @remarks The native `BaseWindow` instance is only available after calling {@link create}.
+ * Calling lifecycle methods before `create()` is safe (they no-op) but the window
+ * will not exist on screen.
+ *
+ * @example
+ * ```ts
+ * @Window({ width: 800, height: 600, show: false })
+ * class MainWindow extends WindowProvider {
+ *     async onReady() {
+ *         this.create();
+ *         this.mount(this.mainView);
+ *         this.show();
+ *     }
+ * }
+ * ```
+ */
+declare abstract class WindowProvider {
+  private [WINDOW_STATE];
+  /** The underlying Electron `BaseWindow` instance, or `undefined` if not yet created. */
+  get window(): BaseWindow | undefined;
+  /** Create the native `BaseWindow` using configuration from the `@Window()` decorator. */
+  create(): void;
+  /**
+   * Attach a view's content to this window.
+   *
+   * The view's `WebContentsView` is added as a child view of the window's content area.
+   * No-ops silently if the window or view has not been created yet.
+   */
+  mount(view: ViewProvider): void;
+  /** Show the window. No-ops if the window has not been created. */
+  show(): void;
+  /** Hide the window without destroying it. */
+  hide(): void;
+  /** Bring the window to the front and give it focus. */
+  focus(): void;
+  /** Close and destroy the native window, releasing its resources. */
+  close(): void;
+  /** Return the window's current screen bounds, or `undefined` if not created. */
+  getBounds(): Rectangle | undefined;
+  /** @internal Called by the framework to set the window configuration from @Window metadata. */
+  static __setConfiguration(instance: WindowProvider, configuration?: BaseWindowConstructorOptions): void;
+}
+//#endregion
+//#region src/bridge/access-guard.d.ts
+/**
+ * Enforces access control for bridge IPC calls.
+ *
+ * Checks two conditions before a bridge request is allowed through:
+ * 1. The application kernel must be in the `"started"` state.
+ * 2. The requesting renderer's {@link RendererSession} must have the target channel
+ *    in its access set (as declared in `@View({ access: [...] })`).
+ *
+ * @internal Used by {@link BridgeDispatcher}; not intended for direct consumer use.
+ */
+declare class BridgeAccessGuard {
+  private kernelState;
+  /** Update the tracked kernel state. Called by the kernel during lifecycle transitions. */
+  setKernelState(state: KernelState): void;
+  /**
+   * Assert that the kernel is in the `"started"` state.
+   *
+   * @throws {BridgeError} If the kernel is not ready to handle requests.
+   */
+  assertKernelReady(): void;
+  /**
+   * Assert that the renderer session has access to the given bridge channel.
+   *
+   * @throws {BridgeError} If the view's `access` list does not include the channel.
+   */
+  assertAccess(session: RendererSession, channel: string): void;
+}
+//#endregion
+//#region src/bridge/handler.d.ts
+type Awaitable<T> = T | PromiseLike<T>;
+/**
+ * A bound function that executes a provider method with the given arguments.
+ *
+ * Created during bootstrap by binding the method to its provider instance.
+ */
+type BridgeInvoker = (...args: unknown[]) => Awaitable<unknown>;
+/**
+ * Wraps a provider method so it can be invoked via IPC from a renderer process.
+ *
+ * Each handler is bound to a specific bridge channel and restores the correct
+ * dependency-injection context before calling the underlying provider method,
+ * ensuring that `inject()` works as expected inside bridge handlers.
+ *
+ * @internal Created during module bootstrap; not instantiated by consumers.
+ */
+declare class BridgeHandler {
+  /** The bridge channel this handler responds to (e.g. `"app:getVersion"`). */
+  readonly channel: string;
+  /** Whether this bridge method is a `"command"` (mutating) or `"query"` (read-only). */
+  readonly kind: "command" | "query";
+  /** The ID of the module that owns this handler. */
+  readonly moduleId: string;
+  private readonly invoker;
+  private readonly injector;
+  constructor(definition: BridgeMethodDefinition, invoker: BridgeInvoker, injector: Injector);
+  /**
+   * Execute the underlying provider method within the correct injection context.
+   *
+   * @returns The value returned by the provider method.
+   */
+  invoke(args: unknown[]): Promise<unknown>;
+}
+//#endregion
+//#region src/bridge/dispatcher.d.ts
+/** Incoming IPC request from a renderer process. */
+interface BridgeRequest {
+  /** Unique identifier for correlating request/response pairs. */
+  readonly callId: string;
+  /** The bridge channel name to invoke (e.g. `"app:getVersion"`). */
+  readonly channel: string;
+  /** Arguments to pass to the bridge handler. */
+  readonly args: unknown[];
+}
+/** IPC response sent back to the renderer process. */
+interface BridgeResponse {
+  /** Matches the `callId` of the originating {@link BridgeRequest}. */
+  readonly callId: string;
+  /** The handler's return value on success. */
+  readonly result?: unknown;
+  /** Serialized error information on failure. */
+  readonly error?: {
+    message: string;
+    code?: string;
+    context?: Record<string, unknown>;
+  };
+}
+/**
+ * Routes IPC requests from renderer processes to the appropriate {@link BridgeHandler}.
+ *
+ * For each incoming request the dispatcher verifies that the kernel is ready,
+ * that the requesting renderer has an active session, and that the session grants
+ * access to the requested channel. If all checks pass the corresponding handler
+ * is invoked; otherwise a serialized error is returned. Errors never propagate as
+ * exceptions -- they are always returned as part of the {@link BridgeResponse}.
+ *
+ * @internal
+ */
+declare class BridgeDispatcher {
+  private readonly rendererRegistry;
+  private readonly accessGuard;
+  private readonly handlers;
+  constructor(rendererRegistry: RendererRegistry, accessGuard: BridgeAccessGuard);
+  /** Register a handler for a bridge channel. */
+  registerHandler(handler: BridgeHandler): void;
+  /**
+   * Process an IPC request from a renderer identified by its `webContentsId`.
+   *
+   * Performs kernel-readiness, session-existence, and channel-access checks before
+   * delegating to the registered handler. All errors are caught and returned as
+   * serialized error objects in the response.
+   */
+  dispatch(webContentsId: number, request: BridgeRequest): Promise<BridgeResponse>;
+}
+//#endregion
+//#region src/bridge/serializer.d.ts
+/**
+ * Convert an error into a plain object suitable for IPC transport.
+ *
+ * Extracts `message`, optional `code`, and optional `context` from `Error` instances.
+ * Non-Error values are coerced to a string message.
+ */
+declare function serializeBridgeError(error: unknown): {
+  message: string;
+  code?: string;
+  context?: Record<string, unknown>;
+};
+//#endregion
+//#region src/errors/runtime.d.ts
+/**
+ * Abstract base class for all framework errors in `@electrojs/runtime`.
+ *
+ * Every concrete error subclass (e.g. {@link BootstrapError}, {@link DIError}) extends this class
+ * and exposes static factory methods that produce pre-formatted, coded error instances.
+ *
+ * @remarks
+ * Each error carries a unique {@link RuntimeError.code | code} string (e.g. `"ELECTRO_DI_PROVIDER_NOT_FOUND"`)
+ * and an optional {@link RuntimeError.context | context} bag of structured data for programmatic inspection.
+ * Application code should catch specific subclasses rather than `RuntimeError` directly.
+ */
+declare abstract class RuntimeError extends Error {
+  /** Machine-readable error code, unique per failure scenario (e.g. `"ELECTRO_DI_CIRCULAR_DEPENDENCY"`). */
+  readonly code: string;
+  /** Structured context data describing the error. Keys vary by error code. */
+  readonly context?: Readonly<Record<string, unknown>>;
+  protected constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+}
+//#endregion
+//#region src/errors/bootstrap.d.ts
+/**
+ * Errors thrown during application bootstrap — the phase where modules, providers,
+ * views, windows, and bridge channels are validated and assembled into the runtime graph.
+ *
+ * All instances are created through static factory methods; direct construction is not allowed.
+ *
+ * @remarks
+ * Bootstrap errors indicate misconfiguration that must be fixed before the app can start.
+ * They are always thrown synchronously during {@link Kernel.start} (or equivalent bootstrap entry point).
+ */
+declare class BootstrapError extends RuntimeError {
+  private constructor();
+  /** The class passed as root module is missing the `@Module()` decorator. */
+  static rootModuleNotDecorated(className: string): BootstrapError;
+  /** A module's `imports` array contains a class that is not decorated with `@Module()`. */
+  static invalidImportedModule(parentModule: string, importedName: string): BootstrapError;
+  /** A module's `providers` array contains a class that is not decorated with `@Injectable()`. */
+  static invalidModuleProvider(moduleName: string, providerName: string): BootstrapError;
+  /** A module's `views` array contains a class that is not decorated with `@View()`. */
+  static invalidModuleView(moduleName: string, viewName: string): BootstrapError;
+  /** A module's `windows` array contains a class that is not decorated with `@Window()`. */
+  static invalidModuleWindow(moduleName: string, windowName: string): BootstrapError;
+  /**
+   * Two or more modules import each other, forming a cycle.
+   *
+   * @remarks
+   * The `cycle` context field contains the full import chain (e.g. `["A", "B", "C", "A"]`).
+   */
+  static circularModuleImport(cycle: readonly string[]): BootstrapError;
+  /** Two modules resolved to the same module id. Module ids must be unique across the application. */
+  static duplicateModuleId(moduleId: string): BootstrapError;
+  /** A module exports a token that is not present in its own `providers` array. */
+  static invalidExport(moduleName: string, exportName: string): BootstrapError;
+  /** Two views resolved to the same view id. View ids must be unique across the application. */
+  static duplicateViewId(viewId: string): BootstrapError;
+  /** Two windows resolved to the same window id. Window ids must be unique across the application. */
+  static duplicateWindowId(windowId: string): BootstrapError;
+  /** Two bridge handlers registered the same channel name. Bridge channels must be unique. */
+  static duplicateBridgeChannel(channel: string): BootstrapError;
+  /** Two job handlers registered the same job id. Job ids must be unique across the application. */
+  static duplicateJobId(jobId: string): BootstrapError;
+  /** A provider is decorated with both `@View()` and `@Window()`. A provider can only have one role. */
+  static invalidProviderRoleCombination(providerName: string): BootstrapError;
+  /** A view's `access` list references a bridge channel that was not registered by any provider. */
+  static invalidViewAccessReference(viewId: string, channel: string): BootstrapError;
+  /** A view's `signals` list references a signal id that has no corresponding `@signal()` handler. */
+  static invalidViewSignalReference(viewId: string, signalId: string): BootstrapError;
+  /** A module imports another module that has not been loaded into the runtime graph yet. */
+  static importedModuleNotLoaded(parentModule: string, importedModule: string): BootstrapError;
+  /** A capability decorator (e.g. `@command`, `@query`) points to a property that is not a function. */
+  static invalidCapabilityMethod(providerName: string, capability: string, methodName: string): BootstrapError;
+}
+//#endregion
+//#region src/errors/bridge.d.ts
+/**
+ * Errors thrown by the IPC bridge subsystem when renderer-to-main communication fails.
+ *
+ * All instances are created through static factory methods; direct construction is not allowed.
+ */
+declare class BridgeError extends RuntimeError {
+  private constructor();
+  /** The originating view is not whitelisted for the requested bridge channel. */
+  static accessDenied(viewId: string, channel: string): BridgeError;
+  /** No handler has been registered for the given bridge channel. */
+  static routeNotFound(channel: string): BridgeError;
+  /**
+   * A bridge handler threw while processing a request.
+   *
+   * @remarks
+   * The original error is attached as {@link Error.cause}.
+   */
+  static handlerFailed(channel: string, cause: unknown): BridgeError;
+  /** A bridge call arrived before the kernel finished starting or after it began shutting down. */
+  static kernelNotReady(): BridgeError;
+  /** A bridge request came from a `webContents` that is not associated with any known view. */
+  static unknownRenderer(webContentsId: number): BridgeError;
+}
+//#endregion
+//#region src/errors/di.d.ts
+/**
+ * Errors thrown by the dependency injection container during provider resolution and registration.
+ *
+ * All instances are created through static factory methods; direct construction is not allowed.
+ */
+declare class DIError extends RuntimeError {
+  private constructor();
+  /** The requested injection token has no matching provider in this injector or any ancestor. */
+  static providerNotFound(token: string): DIError;
+  /** A provider with the same token is already registered in this injector. */
+  static duplicateProvider(token: string): DIError;
+  /**
+   * Two or more providers depend on each other, forming a cycle that cannot be resolved.
+   *
+   * @remarks
+   * The `path` context field contains the full resolution chain (e.g. `["A", "B", "C", "A"]`).
+   */
+  static circularDependency(path: readonly string[]): DIError;
+  /** A class was passed as a provider but is missing a framework decorator (`@Injectable()`, `@Module()`, `@View()`, or `@Window()`). */
+  static invalidClassProvider(token: string): DIError;
+  /**
+   * {@link inject} was called outside of a framework-managed execution context.
+   *
+   * @remarks
+   * `inject()` is only available during construction (property initializers),
+   * lifecycle hooks (`onInit`/`onReady`/`onShutdown`/`onDispose`),
+   * and capability handlers (`@command`, `@query`, `@signal`, `@job`).
+   */
+  static noInjectionContext(): DIError;
+}
+//#endregion
+//#region src/errors/job.d.ts
+/**
+ * Errors thrown by the job scheduling and execution subsystem.
+ *
+ * All instances are created through static factory methods; direct construction is not allowed.
+ */
+declare class JobError extends RuntimeError {
+  private constructor();
+  /** No job handler has been registered under the given job id. */
+  static notFound(jobId: string): JobError;
+  /** The job is already executing and does not support concurrent runs. */
+  static alreadyRunning(jobId: string): JobError;
+  /**
+   * A job handler threw during execution.
+   *
+   * @remarks
+   * The original error is attached as {@link Error.cause}.
+   */
+  static executionFailed(jobId: string, cause: unknown): JobError;
+}
+//#endregion
+//#region src/errors/lifecycle.d.ts
+/**
+ * Errors thrown during kernel and module lifecycle transitions (start, shutdown, hook execution).
+ *
+ * All instances are created through static factory methods; direct construction is not allowed.
+ */
+declare class LifecycleError extends RuntimeError {
+  private constructor();
+  /**
+   * A lifecycle hook (`onInit`, `onReady`, etc.) threw during the startup sequence.
+   *
+   * @remarks
+   * The original error is attached as {@link Error.cause}.
+   */
+  static startupFailed(hookName: string, targetName: string, cause: unknown): LifecycleError;
+  /** The kernel was asked to move to a state that is not reachable from its current state. */
+  static invalidKernelTransition(from: string, to: string): LifecycleError;
+  /** A module was asked to move to a state that is not reachable from its current state. */
+  static invalidModuleTransition(moduleId: string, from: string, to: string): LifecycleError;
+  /** Shutdown was requested but the kernel has not been started yet. */
+  static kernelNotStarted(): LifecycleError;
+  /** Start was requested but the kernel is already started or in the process of starting. */
+  static kernelAlreadyStarted(): LifecycleError;
+}
+//#endregion
+//#region src/errors/signal.d.ts
+/**
+ * Errors thrown when signal dispatching or registration fails.
+ *
+ * All instances are created through static factory methods; direct construction is not allowed.
+ */
+declare class SignalError extends RuntimeError {
+  private constructor();
+  /** The provided signal id is not a non-empty string. */
+  static invalidSignalId(signalId: unknown): SignalError;
+}
+//#endregion
+//#region src/contracts/authoring.d.ts
+/**
+ * Codegen contract types for `@electrojs/runtime`.
+ *
+ * These interfaces and types are used by `@electrojs/codegen` to generate
+ * type-safe authoring APIs. The codegen augments the empty registry interfaces
+ * via `declare module "@electro"` to populate them with app-specific types.
+ *
+ * @module contracts/authoring
+ */
+/** Maps `"moduleId:methodId"` to the method's type reference. Augmented by codegen. */
+interface ModuleMethodMap {}
+/** Maps module IDs to their method type objects. Augmented by codegen. */
+interface ModuleApiRegistry {}
+/** Maps signal keys to their payload types. Augmented by codegen. */
+interface ModuleSignalPayloadMap {}
+/** Maps module IDs to their job ID unions. Augmented by codegen. */
+interface ModuleJobRegistry {}
+/** Maps injectable class names to their class types. Augmented by codegen. */
+interface InjectableClassRegistry {}
+/** Maps window IDs to their `@Window()` class types. Augmented by codegen. */
+interface WindowClassRegistry {}
+/** Maps view IDs to their `@View()` class types. Augmented by codegen. */
+interface ViewClassRegistry {}
+/** Union of all registered module IDs. Derived from `ModuleApiRegistry` keys. */
+type ModuleRegistryId = keyof ModuleApiRegistry;
+type JobIdFor<TModuleId extends ModuleRegistryId> = Extract<ModuleJobRegistry[TModuleId], string>;
+type SignalId = Extract<keyof ModuleSignalPayloadMap, string>;
+type VoidSignalId = { [TKey in SignalId]: ModuleSignalPayloadMap[TKey] extends void ? TKey : never }[SignalId];
+type NonVoidSignalId = Exclude<SignalId, VoidSignalId>;
+/** A class decorated with `@Module()`. Used in generated registry arrays. */
+type ModuleClass = Constructor;
+/** A class decorated with `@View()`. Used in generated registry arrays. */
+type ViewClass = Constructor;
+/** A class decorated with `@Window()`. Used in generated registry arrays. */
+type WindowClass = Constructor;
+/**
+ * Shape of the static kernel definition object generated by codegen.
+ *
+ * Used by the generated `electroAppDefinition` constant which can be
+ * passed to `AppKernel.create()` for fully typed bootstrapping.
+ */
+interface AppKernelDefinition {
+  readonly root: Constructor;
+  readonly modules: readonly Constructor[];
+  readonly windows: readonly Constructor[];
+  readonly views: readonly Constructor[];
+}
+interface TypedSignalBus {
+  publish<TSignalId extends VoidSignalId>(signalId: TSignalId): void;
+  publish<TSignalId extends NonVoidSignalId>(signalId: TSignalId, payload: ModuleSignalPayloadMap[TSignalId]): void;
+  subscribe<TSignalId extends SignalId>(signalId: TSignalId, handler: SignalHandler<ModuleSignalPayloadMap[TSignalId]>): () => void;
+}
+interface TypedJobRegistry<TJobId extends string = string> {
+  ensure(jobId: TJobId): void;
+  start(jobId: TJobId): void;
+  run(jobId: TJobId, ...args: unknown[]): Promise<unknown>;
+  stop(jobId: TJobId): Promise<void>;
+  cancel(jobId: TJobId): void;
+  getStatus(jobId: TJobId): JobRuntimeState | undefined;
+  list(): readonly JobRuntimeState[];
+}
+/**
+ * Base type augmented onto module and provider classes by codegen.
+ *
+ * Codegen generates `interface MyModule extends ModuleAuthoringApi<"myModuleId"> {}`
+ * which gives the class access to typed methods based on the module's registered
+ * commands, queries, signals, and jobs.
+ *
+ */
+interface ModuleAuthoringApi<TModuleId extends ModuleRegistryId> {
+  readonly moduleId: TModuleId;
+  readonly api: ModuleApiRegistry[TModuleId];
+  readonly signals: TypedSignalBus;
+  readonly jobs: TypedJobRegistry<JobIdFor<TModuleId>>;
+  readonly modules: ModuleRegistry;
+  readonly windows: WindowManager;
+  readonly views: ViewManager;
+  readonly logger: ElectroLogger;
+}
+/**
+ * Base type augmented onto `@Window()` classes by codegen.
+ *
+ * Provides typed window management capabilities when extended by codegen-generated
+ * interface augmentations.
+ */
+interface WindowAuthoringApi extends WindowAuthoringSurface {
+  readonly logger: ElectroLogger;
+}
+/**
+ * Base type augmented onto `@View()` classes by codegen.
+ *
+ * Provides typed view management capabilities when extended by codegen-generated
+ * interface augmentations.
+ */
+interface ViewAuthoringApi extends ViewAuthoringSurface {
+  readonly logger: ElectroLogger;
+}
+//#endregion
+export { type AppDefinition, AppKernel, type AppKernelDefinition, type AppKernelOptions, BootstrapError, BridgeAccessGuard, type BridgeClientConfig, BridgeDispatcher, BridgeError, BridgeHandler, type BridgeMethodDefinition, type BridgeMethodKind, type BridgeRequest, type BridgeResponse, type ContextualSignalHandler, DIError, type ElectroIpcRenderer, type ElectroLogBindings, type ElectroLogContext, type ElectroLogLevel, type ElectroLogger, IPC_CHANNELS, type InjectableClassRegistry, InjectionContext, Injector, JobContext, type JobDefinition, JobError, JobRegistry, type JobRuntimeState, type JobStatus, type KernelState, LifecycleError, type LifecycleTarget, type ModuleApiRegistry, type ModuleAuthoringApi, type ModuleClass, type ModuleDefinition, type ModuleJobRegistry, type ModuleMethodMap, ModuleRef, ModuleRegistry, type ModuleRegistryId, type ModuleSignalPayloadMap, type ModuleSnapshot, type ModuleStatus, type PreloadBridgeApi, type ProviderDefinition, type ProviderKind, ProviderRef, type ProviderSnapshot, RendererRegistry, RendererSession, RuntimeError, SignalBus, SignalContext, SignalError, type SignalHandler, type SignalHandlerDefinition, type SignalListener, type TypedJobRegistry, type TypedSignalBus, type ViewAuthoringApi, type ViewClass, type ViewClassRegistry, type ViewDefinition, ViewManager, ViewProvider, type WindowAuthoringApi, type WindowClass, type WindowClassRegistry, type WindowDefinition, WindowManager, WindowProvider, createBridgeClient, createConsoleLogger, inject, scanModules, serializeBridgeError, validateAppDefinition };