@cordy/electro 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,791 @@
+import { BaseWindow } from "electron";
+import { UserConfig } from "vite";
+
+//#region src/config/types.d.ts
+declare const RUNTIME_BRAND: unique symbol;
+declare const WINDOW_BRAND: unique symbol;
+declare const CONFIG_BRAND: unique symbol;
+type WindowLifecycle = "singleton" | "multi";
+type WindowCloseBehavior = "hide" | "destroy";
+type WindowType = "base-window" | "browser-window";
+interface WindowBehavior {
+  close: WindowCloseBehavior;
+}
+interface RuntimeDefinition {
+  readonly [RUNTIME_BRAND]: true;
+  readonly entry: string;
+  readonly vite?: UserConfig;
+  /** @internal Caller path captured by defineRuntime(). */
+  readonly __source: string;
+}
+interface WindowDefinition {
+  readonly [WINDOW_BRAND]: true;
+  readonly name: string;
+  readonly entry: string;
+  readonly type?: WindowType;
+  readonly features?: readonly string[];
+  readonly vite?: UserConfig;
+  readonly preload?: string;
+  readonly lifecycle?: WindowLifecycle;
+  readonly autoShow?: boolean;
+  readonly behavior?: WindowBehavior;
+  readonly window?: Record<string, unknown>;
+  /** @internal Caller path captured by defineWindow(). */
+  readonly __source: string;
+}
+interface ElectroConfig {
+  readonly [CONFIG_BRAND]: true;
+  readonly runtime: RuntimeDefinition;
+  readonly windows?: readonly WindowDefinition[];
+}
+interface DefineRuntimeInput {
+  entry: string;
+  vite?: UserConfig;
+}
+interface DefineWindowInput {
+  name: string;
+  entry: string;
+  type?: WindowType;
+  features?: readonly string[];
+  vite?: UserConfig;
+  preload?: string;
+  lifecycle?: WindowLifecycle;
+  autoShow?: boolean;
+  behavior?: WindowBehavior;
+  window?: Record<string, unknown>;
+}
+interface DefineConfigInput {
+  runtime: RuntimeDefinition;
+  windows?: readonly WindowDefinition[];
+}
+//#endregion
+//#region src/config/define-config.d.ts
+declare function defineConfig(input: DefineConfigInput): ElectroConfig;
+//#endregion
+//#region src/config/define-runtime.d.ts
+declare function defineRuntime(input: DefineRuntimeInput): RuntimeDefinition;
+//#endregion
+//#region src/config/define-window.d.ts
+declare function defineWindow(input: DefineWindowInput): WindowDefinition;
+//#endregion
+//#region src/core/event-bus/types.d.ts
+type EventHandler = (payload: unknown) => void;
+type EventSubscription = {
+  channel: string;
+  handler: EventHandler;
+  ownerId: string;
+};
+type EventId = string;
+/**
+* Type-erased event interface for heterogeneous collections.
+*/
+interface EventInstance {
+  readonly id: EventId;
+  readonly defaults: unknown;
+}
+/**
+* Public interface returned by {@link createEvent}.
+*
+* Generic parameter preserves payload type for codegen inference
+* (`_EventPayload<T>` infers `T` from `payload()` phantom method).
+*/
+interface CreatedEvent<T = void> extends EventInstance {
+  readonly id: EventId;
+  readonly defaults: T | undefined;
+  /** @internal Phantom method for codegen type extraction. Never called. */
+  payload(): T;
+}
+//#endregion
+//#region src/core/event-bus/event-bus.d.ts
+declare class EventBus {
+  private readonly subscriptions;
+  publish(channel: string, payload?: unknown): void;
+  subscribe(channel: string, handler: EventHandler, ownerId: string): () => void;
+  removeByOwner(ownerId: string): void;
+}
+//#endregion
+//#region src/core/event-bus/accessor.d.ts
+/**
+* Scoped event access per feature.
+*
+* - `publish("name", payload)` -> publishes as `"ownerId:name"`
+* - `on("dep:name", handler)` -> validates `dep` is a declared dependency
+* - `on("name", handler)` -> subscribes to own `"ownerId:name"`
+*/
+declare class EventAccessor {
+  private readonly bus;
+  private readonly ownerId;
+  private readonly declaredDeps;
+  constructor(bus: EventBus, ownerId: string, declaredDeps: Set<string>);
+  publish(event: string, payload?: unknown): void;
+  on(event: string, handler: EventHandler): () => void;
+}
+//#endregion
+//#region src/core/event-bus/helpers.d.ts
+/**
+* Creates a typed event definition.
+*
+* @overload Explicit generic — `createEvent<{ version: string }>("ready")`
+* @overload Infer from defaults — `createEvent("ready", { version: "unknown" })`
+*/
+declare function createEvent<T = void>(id: EventId): CreatedEvent<T>;
+declare function createEvent<T>(id: EventId, defaults: T): CreatedEvent<T>;
+//#endregion
+//#region src/core/feature/enums.d.ts
+declare enum FeatureStatus {
+  NONE = "none",
+  REGISTERED = "registered",
+  INITIALIZING = "initializing",
+  READY = "ready",
+  ACTIVATING = "activating",
+  ACTIVATED = "activated",
+  DEACTIVATING = "deactivating",
+  DEACTIVATED = "deactivated",
+  DESTROYING = "destroying",
+  DESTROYED = "destroyed",
+  ERROR = "error"
+}
+//#endregion
+//#region src/window/types.d.ts
+/** A window with an auto-loading `load()` method that resolves dev/prod URLs. */
+type ElectroWindow<T extends BaseWindow = BaseWindow> = T & {
+  load(): Promise<void>;
+};
+/** Factory interface for creating platform windows from definitions. */
+interface WindowFactory {
+  create(definition: WindowDefinition): BaseWindow;
+}
+/** Snapshot of a tracked window. */
+interface WindowInfo {
+  name: string;
+  windowId: number;
+  destroyed: boolean;
+}
+//#endregion
+//#region src/window/manager.d.ts
+/**
+* WindowManager — registry, creation, and lifecycle coordinator for windows.
+*
+* Manages window definitions and their instances through a WindowFactory
+* abstraction. Enforces singleton/multi lifecycle semantics and provides
+* querying and bulk destruction capabilities.
+*/
+declare class WindowManager {
+  private readonly factory;
+  private readonly definitions;
+  private readonly instances;
+  constructor(factory: WindowFactory);
+  /** Register a window definition. Throws on duplicate name. */
+  registerDefinition(definition: WindowDefinition): void;
+  /** Check whether a definition is registered for the given name. */
+  hasDefinition(name: string): boolean;
+  /**
+  * Create a window from a registered definition.
+  *
+  * - Throws if no definition exists for `name`.
+  * - For singleton lifecycle (the default), throws if a live instance already exists.
+  * - For multi lifecycle, always creates a new instance.
+  */
+  createWindow(name: string): ElectroWindow;
+  /**
+  * Get the first alive window for the given name, or null.
+  * Cleans up destroyed instances as a side effect.
+  */
+  getWindow(name: string): ElectroWindow | null;
+  /** Destroy all instances for the given name. No-op if name is unknown. */
+  destroyWindow(name: string): void;
+  /** Destroy all tracked windows across all names. */
+  destroyAll(): void;
+  /** Returns a snapshot of all tracked windows (including destroyed ones). */
+  list(): WindowInfo[];
+  /** Return alive (non-destroyed) instances for a given name. */
+  private getAliveInstances;
+}
+//#endregion
+//#region src/core/task/enums.d.ts
+declare enum TaskOverlapStrategy {
+  Skip = "skip",
+  Queue = "queue",
+  Parallel = "parallel"
+}
+declare enum TaskStatus {
+  Registered = "registered",
+  Scheduled = "scheduled",
+  Running = "running",
+  Stopped = "stopped",
+  Failed = "failed"
+}
+declare enum TaskRetryStrategy {
+  Fixed = "fixed",
+  Exponential = "exponential"
+}
+//#endregion
+//#region src/core/task/types.d.ts
+type TaskId = string;
+type StopMode = "graceful" | "force";
+type TaskRetryConfig = {
+  attempts: number;
+  strategy: TaskRetryStrategy;
+  delayMs: number;
+};
+type TaskExecutionContext = {
+  signal: AbortSignal;
+  attempt: number;
+};
+type TaskConfig<TId extends TaskId, TPayload = void> = {
+  id: TId;
+  cron?: string;
+  autoStart?: boolean;
+  overlap?: TaskOverlapStrategy;
+  dedupeKey?: (payload: TPayload) => string;
+  timeoutMs?: number;
+  retry?: TaskRetryConfig;
+  execute: (ctx: FeatureContext<_TaskOwner<TId>, never, TId>, payload: TPayload, execCtx: TaskExecutionContext) => void | Promise<void>;
+};
+/**
+* Type-erased task interface for heterogeneous collections.
+*
+* Using a non-generic interface (instead of `Task<TaskId, unknown>`)
+* avoids TypeScript variance issues: `TaskConfig.execute` has `payload: TPayload`
+* in a contravariant position, making `Task` invariant in `TPayload`.
+* Interface methods are bivariant, so any `Task<TId, TPayload>` is
+* structurally assignable to `TaskInstance`.
+*/
+interface TaskInstance {
+  readonly id: TaskId;
+  enable(ctx: FeatureContext<any>): void;
+  disable(mode?: StopMode): void;
+  start(payload?: unknown): Promise<void>;
+  queue(payload: unknown): void;
+  stop(): void;
+  clear(): void;
+  status(): TaskStatusInfo;
+}
+interface TaskStatusInfo {
+  taskId: string;
+  state: TaskStatus;
+  running: boolean;
+  queueSize: number;
+  lastRunAt: number | null;
+  lastSuccessAt: number | null;
+  lastErrorAt: number | null;
+  lastError: Error | null;
+}
+/**
+* Public interface returned by {@link createTask}.
+*
+* Hides class internals (private fields) so consumers can safely
+* `export const myTask = createTask({...})` without TypeScript
+* "cannot be named" errors in declaration emit.
+*
+* Generic parameters preserve payload type for codegen inference
+* (`_TaskPayload<T>` infers `TPayload` from `start(payload?)`).
+*/
+interface CreatedTask<TId extends TaskId = TaskId, TPayload = void> {
+  readonly id: TId;
+  enable(ctx: FeatureContext<any>): void;
+  disable(mode?: StopMode): void;
+  start(payload?: TPayload): Promise<void>;
+  queue(payload: TPayload): void;
+  stop(): void;
+  clear(): void;
+  status(): TaskStatusInfo;
+}
+//#endregion
+//#region src/core/task/handle.d.ts
+/**
+* Ergonomic handle for a single {@link Task}.
+*
+* Provides per-task control: start, queue, stop, enable, disable, clear, status.
+* Created by Feature and bound to `ctx.getTask(name)`.
+*/
+declare class TaskHandle<TPayload = unknown> {
+  private readonly task;
+  private readonly ctx;
+  constructor(task: TaskInstance, ctx?: FeatureContext<any> | undefined);
+  /** Execute immediately (respects overlap policy). */
+  start(payload?: TPayload): Promise<void>;
+  /** Push payload to FIFO queue, processes sequentially. */
+  queue(payload: TPayload): void;
+  /** Abort current execution. Queue continues processing. */
+  stop(): void;
+  /** Re-enable the task (cron, ready for start/queue). */
+  enable(): void;
+  /** Abort current + clear queue + stop cron. */
+  disable(mode?: StopMode): void;
+  /** Clear the FIFO queue without stopping current execution. */
+  clear(): void;
+  /** Snapshot of the task's current state. */
+  status(): TaskStatusInfo;
+}
+//#endregion
+//#region src/core/types.d.ts
+/**
+* Declaration-merging registry.
+* Codegen populates this via `declare module "@cordy/electro"`.
+*
+* Each key is a feature ID mapping to its services, tasks, and dependencies.
+*/
+interface FeatureMap {}
+/** Maps service ID → owning feature ID. Populated by codegen. */
+interface ServiceOwnerMap {}
+/** Maps task ID → owning feature ID. Populated by codegen. */
+interface TaskOwnerMap {}
+/** Declaration-merging registry for window types. Codegen populates this. */
+interface WindowMap {}
+/** Resolve the owning feature ID for a service. Falls back to `string` (→ BaseContext). */
+type _ServiceOwner<TId extends string> = TId extends keyof ServiceOwnerMap ? ServiceOwnerMap[TId] : string;
+/** Resolve the owning feature ID for a task. Falls back to `string` (→ BaseContext). */
+type _TaskOwner<TId extends string> = TId extends keyof TaskOwnerMap ? TaskOwnerMap[TId] : string;
+type _SuggestWindowKeys = (keyof WindowMap & string) | (string & {});
+type _ResolveWindow<K extends string> = K extends keyof WindowMap ? ElectroWindow<WindowMap[K]> : ElectroWindow;
+/** Extract the dependency IDs union for a feature. */
+type _DepIds<FId> = FId extends keyof FeatureMap ? FeatureMap[FId]["dependencies"] : never;
+/** Own service keys for a feature. */
+type _OwnSvcKeys<FId> = FId extends keyof FeatureMap ? keyof FeatureMap[FId]["services"] & string : never;
+/** Distributive helper — maps a single dep ID to its qualified service keys. */
+type _DepSvcOf<D> = D extends keyof FeatureMap & string ? `${D}:${keyof FeatureMap[D]["services"] & string}` : never;
+/** Qualified dependency service keys ("dep:svc"), distributes over the deps union. */
+type _DepSvcKeys<FId> = _DepSvcOf<_DepIds<FId>>;
+/** Resolve a service type from own or dependency services. */
+type _ResolveSvc<FId, K extends string> = FId extends keyof FeatureMap ? K extends keyof FeatureMap[FId]["services"] ? FeatureMap[FId]["services"][K] : K extends `${infer D}:${infer S}` ? D extends _DepIds<FId> & keyof FeatureMap ? S extends keyof FeatureMap[D]["services"] ? FeatureMap[D]["services"][S] : unknown : unknown : unknown : unknown;
+/** Resolve a task type from own tasks. FeatureMap stores payloads; wraps in TaskHandle. */
+type _ResolveTask<FId, K extends string> = FId extends keyof FeatureMap ? K extends keyof FeatureMap[FId]["tasks"] ? TaskHandle<FeatureMap[FId]["tasks"][K]> : unknown : unknown;
+/** Resolve a feature handle from dependency features. */
+type _ResolveFeature<FId, K extends string> = FId extends keyof FeatureMap ? K extends _DepIds<FId> & string ? FeatureHandle : unknown : unknown;
+type _SuggestSvcKeys<FId> = _OwnSvcKeys<FId> | _DepSvcKeys<FId>;
+type _SuggestTaskKeys<FId> = FId extends keyof FeatureMap ? keyof FeatureMap[FId]["tasks"] & string : never;
+type _SuggestDepKeys<FId> = _DepIds<FId> & string;
+/** Own event keys for a feature. */
+type _OwnEventKeys<FId> = FId extends keyof FeatureMap ? keyof FeatureMap[FId]["events"] & string : never;
+/** Distributive helper — maps a single dep ID to its qualified event keys. */
+type _DepEventOf<D> = D extends keyof FeatureMap & string ? `${D}:${keyof FeatureMap[D]["events"] & string}` : never;
+/** Qualified dependency event keys ("dep:event"), distributes over the deps union. */
+type _DepEventKeys<FId> = _DepEventOf<_DepIds<FId>>;
+/** Resolve own event payload. */
+type _ResolveOwnEvent<FId, K extends string> = FId extends keyof FeatureMap ? K extends keyof FeatureMap[FId]["events"] ? FeatureMap[FId]["events"][K] : unknown : unknown;
+/** Resolve any event payload (own or dep). */
+type _ResolveEvent<FId, K extends string> = FId extends keyof FeatureMap ? K extends keyof FeatureMap[FId]["events"] ? FeatureMap[FId]["events"][K] : K extends `${infer D}:${infer E}` ? D extends _DepIds<FId> & keyof FeatureMap ? E extends keyof FeatureMap[D]["events"] ? FeatureMap[D]["events"][E] : unknown : unknown : unknown : unknown;
+/** All service keys across all features (mapped type distributes over each feature). */
+type _AllSvcKeys = { [F in keyof FeatureMap]: keyof FeatureMap[F]["services"] & string }[keyof FeatureMap];
+/** All task keys across all features (mapped type distributes over each feature). */
+type _AllTaskKeys = { [F in keyof FeatureMap]: keyof FeatureMap[F]["tasks"] & string }[keyof FeatureMap];
+/** All feature IDs. */
+type _AllFeatureIds = keyof FeatureMap & string;
+/** All event keys across all features. */
+type _AllEventKeys = { [F in keyof FeatureMap]: keyof FeatureMap[F]["events"] & string }[keyof FeatureMap];
+type _SuggestAllSvc = _AllSvcKeys | (string & {});
+type _SuggestAllTask = _AllTaskKeys | (string & {});
+type _SuggestAllFeature = _AllFeatureIds | (string & {});
+type _SuggestAllEvent = _AllEventKeys | (string & {});
+/** Flat resolve for unscoped service lookup. */
+type _FlatResolveSvc<K extends string> = { [F in keyof FeatureMap]: K extends keyof FeatureMap[F]["services"] ? FeatureMap[F]["services"][K] : never }[keyof FeatureMap] extends infer U ? [U] extends [never] ? unknown : U : unknown;
+/** Flat resolve for unscoped task lookup. FeatureMap stores payloads; wraps in TaskHandle. */
+type _FlatResolveTask<K extends string> = { [F in keyof FeatureMap]: K extends keyof FeatureMap[F]["tasks"] ? TaskHandle<FeatureMap[F]["tasks"][K]> : never }[keyof FeatureMap] extends infer U ? [U] extends [never] ? unknown : U : unknown;
+/** Flat resolve for unscoped feature lookup. */
+type _FlatResolveFeature<K extends string> = K extends keyof FeatureMap ? FeatureHandle : unknown;
+/** Scoped context — used when `FId` is a concrete feature key. */
+type TypedContext<FId extends keyof FeatureMap, ExcludeSvc extends string = never, ExcludeTask extends string = never> = {
+  signal: AbortSignal;
+  logger: LoggerContext;
+  getService: <K extends Exclude<_SuggestSvcKeys<FId>, ExcludeSvc>>(name: K) => _ResolveSvc<FId, K & string>;
+  getTask: <K extends Exclude<_SuggestTaskKeys<FId>, ExcludeTask>>(name: K) => _ResolveTask<FId, K & string>;
+  getFeature: <K extends _SuggestDepKeys<FId>>(name: K) => _ResolveFeature<FId, K & string>;
+  events: {
+    publish<K extends _OwnEventKeys<FId>>(event: K, ...args: undefined extends _ResolveOwnEvent<FId, K> ? [payload?: _ResolveOwnEvent<FId, K>] : [payload: _ResolveOwnEvent<FId, K>]): void;
+    on<K extends _OwnEventKeys<FId> | _DepEventKeys<FId>>(event: K, handler: (payload: _ResolveEvent<FId, K>) => void): () => void;
+  };
+  createWindow: <K extends _SuggestWindowKeys>(name: K) => _ResolveWindow<K & string>;
+  getWindow: <K extends _SuggestWindowKeys>(name: K) => _ResolveWindow<K & string> | null;
+};
+/** Unscoped context — flat suggestions from all features. */
+type BaseContext = {
+  signal: AbortSignal;
+  logger: LoggerContext;
+  getService: <K extends _SuggestAllSvc>(name: K) => _FlatResolveSvc<K & string>;
+  getTask: <K extends _SuggestAllTask>(name: K) => _FlatResolveTask<K & string>;
+  getFeature: <K extends _SuggestAllFeature>(name: K) => _FlatResolveFeature<K & string>;
+  events: {
+    publish(event: _SuggestAllEvent, payload?: unknown): void;
+    on(event: string, handler: (payload: unknown) => void): () => void;
+  };
+  createWindow: <K extends _SuggestWindowKeys>(name: K) => _ResolveWindow<K & string>;
+  getWindow: <K extends _SuggestWindowKeys>(name: K) => _ResolveWindow<K & string> | null;
+};
+interface LoggerContext {
+  debug(code: string, message: string, details?: Record<string, unknown>): void;
+  warn(code: string, message: string, details?: Record<string, unknown>): void;
+  error(code: string, message: string, details?: Record<string, unknown>): void;
+}
+//#endregion
+//#region src/core/service/enums.d.ts
+declare enum ServiceScope {
+  PRIVATE = "private",
+  INTERNAL = "internal",
+  EXPOSED = "exposed"
+}
+declare enum ServiceStatus {
+  REGISTERED = "registered",
+  ACTIVE = "active",
+  DESTROYED = "destroyed"
+}
+//#endregion
+//#region src/core/service/types.d.ts
+type ServiceId = string;
+type ServiceConfig<Scope extends ServiceScope = ServiceScope, TApi = unknown, TId extends ServiceId = ServiceId> = {
+  id: TId;
+  scope?: Scope;
+  api: (ctx: FeatureContext<_ServiceOwner<TId>, TId>) => TApi;
+};
+interface ServiceInfo {
+  serviceId: ServiceId;
+  scope: ServiceScope;
+  state: ServiceStatus;
+}
+/**
+* Type-erased service interface for heterogeneous collections.
+*
+* Mirrors the public API of {@link Service} without exposing private fields.
+* Used internally by {@link ServiceManager} and {@link FeatureConfig}.
+*/
+interface ServiceInstance {
+  readonly id: ServiceId;
+  readonly scope: ServiceScope;
+  build(ctx: FeatureContext<any>): void;
+  destroy(): void;
+  api(): unknown;
+  status(): ServiceInfo;
+}
+/**
+* Public interface returned by {@link createService}.
+*
+* Hides class internals so consumers can safely
+* `export const myService = createService({...})` without TypeScript
+* "cannot be named" errors in declaration emit.
+*
+* Generic parameters preserve scope + API types for codegen inference
+* (`_SvcApi<T>` infers from `api()`).
+*/
+interface CreatedService<Scope extends ServiceScope = ServiceScope, TApi = unknown> {
+  readonly id: ServiceId;
+  readonly scope: Scope;
+  build(ctx: FeatureContext<any>): void;
+  destroy(): void;
+  api(): TApi | null;
+  status(): ServiceInfo;
+}
+//#endregion
+//#region src/core/feature/types.d.ts
+type FeatureId = string;
+type FeatureContext<FId extends FeatureId = string, ExcludeSvc extends string = never, ExcludeTask extends string = never> = FId extends keyof FeatureMap ? TypedContext<FId, ExcludeSvc, ExcludeTask> : BaseContext;
+/** Suggest known feature IDs while accepting arbitrary strings. */
+type SuggestFeatureIds = (keyof FeatureMap & string) | (string & {});
+type FeatureConfig<FId extends FeatureId> = {
+  id: FId;
+  critical?: boolean;
+  dependencies?: SuggestFeatureIds[];
+  services?: ServiceInstance[];
+  tasks?: TaskInstance[];
+  events?: EventInstance[];
+  /**
+  * OnInitialize
+  * Lifecycle hook called when feature starts initializing
+  * @param ctx Feature context
+  */
+  onInitialize?: (ctx: FeatureContext<FId>) => void | Promise<void>;
+  /**
+  * OnActivate
+  * Lifecycle hook called when feature starts activating
+  * @param ctx Feature context
+  */
+  onActivate?: (ctx: FeatureContext<FId>) => void | Promise<void>;
+  /**
+  * OnDeactivate
+  * Lifecycle hook called when feature starts deactivating
+  * @param ctx Feature context
+  */
+  onDeactivate?: (ctx: FeatureContext<FId>) => void | Promise<void>;
+  /**
+  * OnDestroy
+  * Lifecycle hook called when feature starts destroying
+  * @param ctx Feature context
+  */
+  onDestroy?: (ctx: FeatureContext<FId>) => void | Promise<void>;
+};
+//#endregion
+//#region src/core/service/manager.d.ts
+/**
+* Per-feature registry and lifecycle coordinator for {@link Service} instances.
+*
+* One service per id — `get()` returns `{ api, scope }` directly.
+*/
+declare class ServiceManager {
+  private readonly ctx;
+  /** Primary storage: `id` → Service */
+  private services;
+  private _isShutdown;
+  constructor(ctx: FeatureContext<any>);
+  /** Add a service to the registry. Throws on duplicate id. */
+  register(service: ServiceInstance): void;
+  /** Remove a service by id. Destroys it before removing. */
+  unregister(serviceId: ServiceId): void;
+  /** Build all registered services. No-op after shutdown. */
+  startup(): void;
+  /** Destroy all registered services. Marks manager as shut down. */
+  shutdown(): void;
+  /**
+  * Get a service by id, returning its API and scope.
+  *
+  * @returns `{ api, scope }` or `null` if service id is unknown or not yet built
+  */
+  get(serviceId: ServiceId): {
+    api: unknown;
+    scope: string;
+  } | null;
+  /** Return status for a given service id. Throws if unknown. */
+  status(serviceId: ServiceId): ServiceInfo;
+  /** Return status for all registered services. */
+  list(): ServiceInfo[];
+}
+//#endregion
+//#region src/core/state-machine/types.d.ts
+type StateMachineConfig<TState extends string> = {
+  transitions: Record<TState, TState[]>;
+  initial: TState;
+  name?: string;
+};
+type TransitionListener<TState extends string> = (from: TState, to: TState) => void;
+//#endregion
+//#region src/core/state-machine/state-machine.d.ts
+declare class StateMachine<TState extends string> {
+  private _current;
+  private readonly _transitions;
+  private readonly _name;
+  private readonly _listeners;
+  constructor(config: StateMachineConfig<TState>);
+  get current(): TState;
+  transition(target: TState): void;
+  canTransition(target: TState): boolean;
+  assertState(...allowed: TState[]): void;
+  onTransition(cb: TransitionListener<TState>): () => void;
+}
+//#endregion
+//#region src/core/feature/manager.d.ts
+declare class FeatureManager {
+  private logger;
+  private eventBus;
+  private readonly registry;
+  /** Global service ownership: serviceId → featureId. */
+  private readonly serviceOwners;
+  /** Global task ownership: taskId → featureId. */
+  private readonly taskOwners;
+  private windowManager;
+  constructor(logger: LoggerContext, eventBus?: EventBus | undefined);
+  /** @internal Set the window manager (called by Electron layer before bootstrap). */
+  setWindowManager(windowManager: WindowManager): void;
+  /**
+  * Register a feature or a list of features.
+  * If a feature with the same ID is already registered, a warning is logged and the feature is skipped.
+  * @throws If a service or task ID is already owned by another feature.
+  */
+  register(features: FeatureConfig<any> | FeatureConfig<any>[]): void;
+  get(id: FeatureId): Feature<FeatureId> | undefined;
+  /** Returns all registered features. */
+  list(): Feature<FeatureId>[];
+  /**
+  * Bootstrap all features in dependency order.
+  * Calls initialize -> activate on each feature.
+  * The feature receives a context built externally (by Runtime).
+  */
+  bootstrap(): Promise<void>;
+  /**
+  * Initialize a feature.
+  * Initializes the feature and sets its state to "ready" or "error".
+  */
+  private initialize;
+  /**
+  * Activate a feature.
+  * @param id The ID of the feature to activate.
+  * @param allowRetry When true, ERROR state features can be retried (used by enable()).
+  */
+  private activate;
+  /**
+  * Deactivate a feature.
+  * @param id The ID of the feature to deactivate.
+  */
+  private deactivate;
+  private destroy;
+  /** Public: re-activate a DEACTIVATED or ERROR feature. */
+  enable(id: FeatureId): Promise<void>;
+  /** Public: deactivate an ACTIVATED feature. */
+  disable(id: FeatureId): Promise<void>;
+  shutdown(): Promise<void>;
+  private reorder;
+}
+//#endregion
+//#region src/core/feature/feature.d.ts
+declare class Feature<FId extends FeatureId> {
+  readonly config: FeatureConfig<FId>;
+  readonly logger: LoggerContext;
+  readonly state: StateMachine<FeatureStatus>;
+  controller: AbortController;
+  context: FeatureContext<any>;
+  serviceManager: ServiceManager | null;
+  private taskManager;
+  private eventBus;
+  constructor(config: FeatureConfig<FId>, logger: LoggerContext);
+  get id(): FId;
+  get status(): FeatureStatus;
+  /**
+  * Validate and apply an FSM transition.
+  * @throws If the transition is not allowed from the current state.
+  */
+  transition(target: FeatureStatus): void;
+  initialize(features: Feature<FeatureId>[], manager: FeatureManager, eventBus?: EventBus, windowManager?: WindowManager): Promise<void>;
+  activate(): Promise<void>;
+  deactivate(): Promise<void>;
+  destroy(): Promise<void>;
+  private buildContext;
+}
+//#endregion
+//#region src/core/feature/handle.d.ts
+/**
+* Ergonomic handle for a declared dependency Feature.
+*
+* Provides per-feature control: status, enable, disable.
+* Created by Feature and bound to `ctx.getFeature(name)`.
+*/
+declare class FeatureHandle {
+  private readonly feature;
+  private readonly manager;
+  constructor(feature: Feature<FeatureId>, manager: FeatureManager);
+  /** Current lifecycle state. */
+  status(): FeatureStatus;
+  /** Re-activate the feature (from DEACTIVATED or ERROR). */
+  enable(): Promise<void>;
+  /** Deactivate the feature. */
+  disable(): Promise<void>;
+}
+//#endregion
+//#region src/core/feature/helpers.d.ts
+/**
+* Method for creating a feature
+* @param config - The configuration object for the feature
+* @returns The feature configuration object
+*/
+declare function createFeature<FId extends FeatureId>(config: FeatureConfig<FId>): FeatureConfig<FId>;
+//#endregion
+//#region src/core/logger/types.d.ts
+type LogLevel = "debug" | "warn" | "error";
+type LogEntry = {
+  level: LogLevel;
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  timestamp: number;
+};
+type LogHandler = (entry: LogEntry) => void;
+//#endregion
+//#region src/core/runtime/enums.d.ts
+declare enum RuntimeState {
+  CREATED = "created",
+  STARTING = "starting",
+  RUNNING = "running",
+  STOPPING = "stopping",
+  STOPPED = "stopped",
+  FAILED = "failed"
+}
+//#endregion
+//#region src/core/logger/logger.d.ts
+declare class Logger implements LoggerContext {
+  private readonly handlers;
+  addHandler(handler: LogHandler): void;
+  removeHandler(handler: LogHandler): void;
+  debug(code: string, message: string, details?: Record<string, unknown>): void;
+  warn(code: string, message: string, details?: Record<string, unknown>): void;
+  error(code: string, message: string, details?: Record<string, unknown>): void;
+  private emit;
+}
+//#endregion
+//#region src/core/runtime/types.d.ts
+type RuntimeConfig = {
+  features?: FeatureConfig<any>[];
+  logger?: {
+    handlers?: LogHandler[];
+  };
+};
+//#endregion
+//#region src/core/runtime/runtime.d.ts
+declare class Runtime {
+  readonly state: StateMachine<RuntimeState>;
+  readonly logger: Logger;
+  private readonly featureManager;
+  private readonly eventBus;
+  private windowManager;
+  constructor(config?: RuntimeConfig);
+  /** @internal Inject window manager (called by Electron layer before start). */
+  _injectWindowManager(windowManager: WindowManager): void;
+  register(features: FeatureConfig<any> | FeatureConfig<any>[]): void;
+  start(): Promise<void>;
+  shutdown(): Promise<void>;
+  enable(id: FeatureId): Promise<void>;
+  disable(id: FeatureId): Promise<void>;
+  isDegraded(): boolean;
+}
+//#endregion
+//#region src/core/runtime/helpers.d.ts
+declare function createRuntime(config?: RuntimeConfig): Runtime;
+//#endregion
+//#region src/core/service/helpers.d.ts
+/**
+* Creates a {@link Service} instance from a configuration object.
+*
+* @param config - Service configuration with `id`, `scope`, and `api`.
+* @returns A new `Service` instance ready for registration.
+* @throws If `config.id` is empty.
+*/
+declare function createService<Scope extends ServiceScope, TApi, TId extends ServiceId = ServiceId>(config: ServiceConfig<Scope, TApi, TId>): CreatedService<Scope, TApi>;
+//#endregion
+//#region src/core/task/helpers.d.ts
+/** Create a {@link Task} from a config object. Throws if `id` is empty. */
+declare function createTask<TId extends TaskId, TPayload = void>(config: TaskConfig<TId, TPayload>): CreatedTask<TId, TPayload>;
+//#endregion
+//#region src/policy/types.d.ts
+/** Outcome of a policy check. */
+declare enum PolicyDecision {
+  ALLOWED = "ALLOWED",
+  ACCESS_DENIED = "ACCESS_DENIED",
+  WINDOW_NOT_FOUND = "WINDOW_NOT_FOUND"
+}
+/** Result of a policy check with context. */
+interface PolicyResult {
+  readonly decision: PolicyDecision;
+  readonly windowName: string;
+  readonly featureId: string;
+}
+//#endregion
+//#region src/policy/engine.d.ts
+/**
+* Deny-by-default policy engine for window–feature access control.
+*
+* A window's renderer can only access exposed services of features
+* listed in its `features: []` config. Everything else is denied.
+*
+* Used at:
+* - **Build time** (codegen): generate preload stubs only for allowed features
+* - **Runtime** (IPC routing): gate incoming calls from renderer
+*/
+declare class PolicyEngine {
+  private readonly policies;
+  constructor(windows: readonly WindowDefinition[]);
+  /** Full policy check with decision code and context. */
+  check(windowName: string, featureId: string): PolicyResult;
+  /** Convenience: returns true only when access is ALLOWED. */
+  canAccess(windowName: string, featureId: string): boolean;
+  /** Returns the allowed feature IDs for a window. Throws if window unknown. */
+  getAllowedFeatures(windowName: string): readonly string[];
+  /** Returns all registered window names. */
+  getWindowNames(): string[];
+}
+//#endregion
+export { type BaseContext, type CreatedEvent, type CreatedService, type CreatedTask, type DefineConfigInput, type DefineRuntimeInput, type DefineWindowInput, type ElectroConfig, type ElectroWindow, EventAccessor, type EventHandler, type EventId, type EventInstance, type EventSubscription, type FeatureConfig, type FeatureContext, type FeatureHandle, type FeatureId, type FeatureMap, FeatureStatus, type LogEntry, type LogHandler, type LoggerContext, PolicyDecision, PolicyEngine, type PolicyResult, Runtime, type RuntimeConfig, type RuntimeDefinition, RuntimeState, type ServiceConfig, type ServiceId, type ServiceInfo, type ServiceOwnerMap, ServiceScope, ServiceStatus, type StopMode, type TaskConfig, type TaskExecutionContext, type TaskHandle, type TaskId, TaskOverlapStrategy, type TaskOwnerMap, TaskRetryStrategy, TaskStatus, type TaskStatusInfo, type TypedContext, type WindowBehavior, type WindowCloseBehavior, type WindowDefinition, type WindowFactory, type WindowInfo, type WindowLifecycle, type WindowMap, type WindowType, createEvent, createFeature, createRuntime, createService, createTask, defineConfig, defineRuntime, defineWindow };