@electrojs/runtime 1.0.8 → 1.0.9

package/dist/index.d.mts

@@ -473,64 +473,318 @@ declare class AppKernel {
   private safeDisposeServices;
 }
 //#endregion
-//#region src/container/inject.d.ts
+//#region src/desktop/view-manager.d.ts
 /**
- * Resolve a dependency from the current injection context.
+ * Framework-internal registry that tracks all `@View()` providers in the application.
  *
- * 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}.
+ * 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.
  *
- * @remarks
- * `inject()` is only available inside a framework-managed execution scope:
- * - **Construction** -- property initializers of `@Injectable()`, `@Module()`, `@View()`, or `@Window()` classes
- * - **Lifecycle hooks** -- `onInit`, `onStart`, `onReady`, `onShutdown`, `onDispose`
- * - **Capability handlers** -- methods decorated with `@command`, `@query`, `@signal`, or `@job`
+ * @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()`.
  *
- * Calling it anywhere else (e.g. in a `setTimeout` callback or a plain function)
- * throws {@link DIError} with code `ELECTRO_DI_NO_INJECTION_CONTEXT`.
+ * 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
- * @Injectable()
- * class MyService {
- *   private readonly config = inject(AppConfig);
+ * @View({ source: 'view:main', access: ['app:getVersion'] })
+ * class MainView extends ViewProvider {
+ *     async onStart() {
+ *         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.
  *
- * @throws {@link DIError} if no injection context is active or the token cannot be resolved.
+ * 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 function inject<T>(token: InjectionToken<T>): T;
+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/container/injection-context.d.ts
+//#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;
+}
 /**
- * Ambient injection context backed by `AsyncLocalStorage`.
+ * Abstract base class for window providers decorated with `@Window()`.
  *
- * 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.
+ * 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
- * This is a framework-internal API. Application code should use {@link inject} instead
- * of interacting with `InjectionContext` directly.
+ * @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.
  *
- * @internal
+ * @example
+ * ```ts
+ * @Window({ width: 800, height: 600, show: false })
+ * class MainWindow extends WindowProvider {
+ *     async onStart() {
+ *         this.create();
+ *         this.mount(this.mainView);
+ *         this.show();
+ *     }
+ * }
+ * ```
  */
-declare const InjectionContext: {
+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;
   /**
-   * Execute `fn` within the scope of the given injector.
-   * Any {@link inject} call made synchronously inside `fn` will resolve from this injector.
+   * 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.
    */
-  readonly run: <T>(injector: Injector, fn: () => T) => T;
+  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/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;
   /**
-   * Execute `fn` within the scope of the given injector, additionally tracking `owner`
-   * as the object currently being constructed or invoked.
+   * Report execution progress.
+   *
+   * @remarks Values are clamped to the 0-100 range.
    */
-  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;
-};
+  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/modules/registry.d.ts
 /**
@@ -591,24 +845,6 @@ declare class ModuleRegistry {
   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.
@@ -684,399 +920,264 @@ 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.
+   * Register a handler for the given signal.
    *
-   * @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.
+   * The handler is bound to the current injection context at call time, so
+   * `inject()` resolves correctly even though the handler runs asynchronously.
    *
-   * Waits for the running execution (if any) to settle before returning. The job
-   * transitions to `"idle"` once fully stopped.
+   * @returns A dispose function that removes the subscription.
    */
-  stop(jobId: string): Promise<void>;
+  subscribe<T>(signalId: string, handler: SignalListener<T>): () => void;
+  subscribe<T>(signalId: string, handler: ContextualSignalHandler<T>): () => void;
   /**
-   * Request cooperative cancellation of the currently running execution.
+   * Publish a signal to all registered handlers.
    *
-   * Sets the `isCanceled` flag on the job's {@link JobContext}. The handler is
-   * responsible for checking this flag and aborting work accordingly.
+   * 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')`).
    */
-  cancel(jobId: string): void;
-  /** @internal */
-  dispose(): Promise<void>;
-  private getJobOrThrow;
-  private startScheduler;
-  private executeJob;
+  publish<T = void>(signalId: string, payload?: T): void;
+  /** @internal Connect a relay listener (used by renderer registry). */
+  connectRelay(listener: SignalPublishListener): () => void;
 }
 //#endregion
-//#region src/desktop/renderer-session.d.ts
+//#region src/contracts/authoring.d.ts
 /**
- * Tracks the capabilities of a single renderer process (identified by `webContentsId`).
+ * Codegen contract types for `@electrojs/runtime`.
  *
- * 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.
+ * 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.
  *
- * @internal Created and managed by {@link RendererRegistry}.
+ * @module contracts/authoring
  */
-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;
+/** 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: SignalListener<ModuleSignalPayloadMap[TSignalId]>): () => void;
+  subscribe<TSignalId extends SignalId>(signalId: TSignalId, handler: ContextualSignalHandler<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[];
 }
-//#endregion
-//#region src/desktop/renderer-registry.d.ts
 /**
- * Maps Electron `webContentsId` values to {@link RendererSession} instances.
+ * Base type augmented onto module and provider classes by codegen.
  *
- * 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.
+ * 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.
  *
- * @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[];
+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;
 }
-//#endregion
-//#region src/desktop/view-manager.d.ts
 /**
- * Framework-internal registry that tracks all `@View()` providers in the application.
+ * Base type augmented onto `@Window()` classes by codegen.
  *
- * 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.
+ * 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.
  *
- * @internal
+ * Provides typed view management capabilities when extended by codegen-generated
+ * interface augmentations.
  */
-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>;
+interface ViewAuthoringApi extends ViewAuthoringSurface {
+  readonly logger: ElectroLogger;
 }
 //#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;
-}
+//#region src/container/inject.d.ts
 /**
- * Abstract base class for view providers decorated with `@View()`.
+ * Resolve a dependency from the current injection context.
  *
- * 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.
+ * 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}.
  *
- * Views are created with strict security defaults: `sandbox: true`,
- * `contextIsolation: true`, and `nodeIntegration: false`.
+ * @remarks
+ * `inject()` is only available inside a framework-managed execution scope:
+ * - **Construction** -- property initializers of `@Injectable()`, `@Module()`, `@View()`, or `@Window()` classes
+ * - **Lifecycle hooks** -- `onInit`, `onStart`, `onReady`, `onShutdown`, `onDispose`
+ * - **Capability handlers** -- methods decorated with `@command`, `@query`, `@signal`, or `@job`
  *
- * @remarks The `WebContentsView` is lazily created on the first call to {@link load}.
+ * 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
- * @View({ source: 'view:main', access: ['app:getVersion'] })
- * class MainView extends ViewProvider {
- *     async onStart() {
- *         await this.load();
- *         this.setBounds({ x: 0, y: 0, width: 800, height: 600 });
- *     }
+ * @Injectable()
+ * class MyService {
+ *   private readonly config = inject(AppConfig);
  * }
  * ```
+ *
+ * @throws {@link DIError} if no injection context is active or the token cannot be resolved.
  */
-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;
-}
+declare function inject<T>(token: InjectionToken<T>): T extends SignalBus ? TypedSignalBus : T;
 //#endregion
-//#region src/desktop/window-manager.d.ts
+//#region src/container/injection-context.d.ts
 /**
- * Framework-internal registry that tracks all `@Window()` providers in the application.
+ * Ambient injection context backed by `AsyncLocalStorage`.
  *
- * 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.
+ * 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 class WindowManager {
-  private readonly windows;
+declare const InjectionContext: {
   /**
-   * Register a window provider and apply its `@Window()` configuration.
-   *
-   * @remarks Silently skips providers that do not have window metadata.
+   * Execute `fn` within the scope of the given injector.
+   * Any {@link inject} call made synchronously inside `fn` will resolve from this injector.
    */
-  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>;
-}
+  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/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;
-}
+//#region src/modules/validator.d.ts
 /**
- * Abstract base class for window providers decorated with `@Window()`.
+ * Validates a scanned {@link AppDefinition} for structural correctness before bootstrap.
  *
- * 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}.
+ * 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
  *
- * @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.
+ * @throws {BootstrapError} On the first validation failure encountered.
+ */
+declare function validateAppDefinition(definition: AppDefinition): void;
+//#endregion
+//#region src/desktop/renderer-session.d.ts
+/**
+ * Tracks the capabilities of a single renderer process (identified by `webContentsId`).
  *
- * @example
- * ```ts
- * @Window({ width: 800, height: 600, show: false })
- * class MainWindow extends WindowProvider {
- *     async onStart() {
- *         this.create();
- *         this.mount(this.mainView);
- *         this.show();
- *     }
- * }
- * ```
+ * 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 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;
+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;
   /**
-   * Attach a view's content to this window.
+   * Return the existing session for a `webContentsId`, or create one if this is
+   * the first request from that renderer.
    *
-   * 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.
+   * @throws {BridgeError} If the `viewId` does not match any registered view definition.
    */
-  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;
+  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/bridge/access-guard.d.ts
@@ -1397,103 +1498,4 @@ declare class SignalError extends RuntimeError {
   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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electrojs/runtime",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Electron main-process runtime for ElectroJS with DI, lifecycle hooks, typed IPC, and jobs",
   "keywords": [
     "dependency-injection",
@@ -49,12 +49,12 @@
     "publint": "^0.3.18",
     "tsdown": "^0.21.4",
     "vitest": "^4.1.1",
-    "@electrojs/common": "1.0.8",
-    "@electrojs/config": "1.0.8"
+    "@electrojs/common": "1.0.9",
+    "@electrojs/config": "1.0.9"
   },
   "peerDependencies": {
-    "@electrojs/common": "1.0.8",
-    "@electrojs/config": "1.0.8",
+    "@electrojs/common": "1.0.9",
+    "@electrojs/config": "1.0.9",
     "@types/node": "^25.5.0",
     "electron": ">=41"
   },