fluxplugin 1.0.0

package/dist/types/core/ipc.d.ts

@@ -0,0 +1,148 @@
+import { FrameworkError, type Disposable } from "./common.js";
+import type { Permission } from "./manifest.js";
+import { type Infer, type Schema } from "./schema.js";
+import { Registry } from "./registry.js";
+/** A shared description of one IPC endpoint. Import it from both main and renderer code to get end-to-end types. */
+export interface IpcContract<I = unknown, O = unknown> {
+    readonly name: string;
+    readonly input?: Schema<I>;
+    readonly output?: Schema<O>;
+    /** Permission the *calling* plugin must hold when the call originates from a plugin. */
+    readonly permission?: Permission;
+    /** Phantom fields carrying the types (never set at runtime). */
+    readonly _in?: I;
+    readonly _out?: O;
+}
+export interface IpcCallContext {
+    /** Plugin that owns the handler. */
+    pluginId: string;
+    /** Plugin (or `host`) that issued the call. */
+    caller: string;
+    /** Opaque identifier of the sender (e.g. webContents id) provided by the transport. */
+    senderId?: number | string;
+}
+export type IpcHandler<I, O> = (input: I, ctx: IpcCallContext) => O | Promise<O>;
+export interface IpcDefinition<I = unknown, O = unknown> extends IpcContract<I, O> {
+    readonly handler: IpcHandler<I, O>;
+    readonly contract: IpcContract<I, O>;
+}
+export declare function defineIpcContract<I = void, O = unknown>(c: {
+    name: string;
+    input?: Schema<I>;
+    output?: Schema<O>;
+    permission?: Permission;
+}): IpcContract<I, O>;
+/** Declares an IPC endpoint with its handler. Types of `handler` are inferred from the schemas. */
+export declare function defineIPC<IS extends Schema<any> | undefined = undefined, OS extends Schema<any> | undefined = undefined>(def: {
+    name: string;
+    input?: IS;
+    output?: OS;
+    permission?: Permission;
+    handler: IpcHandler<IS extends Schema<any> ? Infer<IS> : void, OS extends Schema<any> ? Infer<OS> : unknown>;
+}): IpcDefinition<IS extends Schema<any> ? Infer<IS> : void, OS extends Schema<any> ? Infer<OS> : unknown>;
+export type Unsubscribe = () => void;
+/** What the main-side registry needs from the environment to talk to renderers. */
+export interface IpcTransport {
+    /** Sends an event from main to every renderer (or one target when `target` is given). */
+    broadcast(channel: string, payload: unknown, target?: number | string): void;
+}
+interface HandlerEntry {
+    name: string;
+    handler: IpcHandler<any, any>;
+    input?: Schema<any>;
+    output?: Schema<any>;
+    permission?: Permission;
+    owner: string;
+}
+export interface InvokeOptions {
+    caller?: string;
+    senderId?: number | string;
+}
+export declare class IpcError extends FrameworkError {
+    readonly channel: string;
+    constructor(message: string, code: string, channel: string);
+}
+/** Serializable error shape sent back to renderers (stack traces never cross the boundary). */
+export interface IpcErrorPayload {
+    code: string;
+    message: string;
+    issues?: {
+        path: string;
+        message: string;
+    }[];
+}
+export declare function serializeError(e: unknown): IpcErrorPayload;
+export declare class IpcRegistry extends Registry<HandlerEntry> {
+    private oneWay;
+    private transport;
+    /** Hook for the manager: ensures the owner plugin is active (`onIPC:<name>`) and checks caller permissions. */
+    beforeInvoke?: (name: string, opts: InvokeOptions) => Promise<void>;
+    /** Permission check provided by the manager. */
+    assertCallerPermission?: (caller: string, permission: Permission, channel: string) => void;
+    /** Observer used for diagnostics. */
+    onCall?: (info: {
+        name: string;
+        owner: string;
+        caller: string;
+        ms: number;
+        error?: unknown;
+    }) => void;
+    constructor();
+    setTransport(t: IpcTransport | undefined): void;
+    handle<I, O>(def: IpcContract<I, O>, handler: IpcHandler<I, O>, owner: string): Disposable;
+    handle<I = unknown, O = unknown>(name: string, handler: IpcHandler<I, O>, owner: string, opts?: {
+        input?: Schema<I>;
+        output?: Schema<O>;
+        permission?: Permission;
+    }): Disposable;
+    /** Registers a full `IpcDefinition` (contract + handler). */
+    register(def: IpcDefinition<any, any>, owner: string): Disposable;
+    /** Dispatches a call: validate input → permission → handler → validate output. */
+    invoke<O = unknown>(name: string, input: unknown, opts?: InvokeOptions): Promise<O>;
+    /** Fire-and-forget messages from renderer/other plugins to main (`ipc.on`). */
+    on(name: string, fn: (payload: unknown, ctx: IpcCallContext) => void, owner: string): Disposable;
+    /** Delivers a one-way message to main-side listeners. */
+    dispatch(name: string, payload: unknown, opts?: InvokeOptions): number;
+    /** Main → renderer push. */
+    send(channel: string, payload: unknown, target?: number | string): void;
+    removeListenersByOwner(owner: string): void;
+}
+export type PreloadMember = {
+    kind: "invoke";
+    channel: string;
+} | {
+    kind: "send";
+    channel: string;
+} | {
+    kind: "event";
+    channel: string;
+};
+export type PreloadApiSpec = Record<string, PreloadMember>;
+export type PreloadMemberInput = string | PreloadMember;
+/** Helpers mirroring the declarative shape so plugin code reads naturally. */
+export declare const preloadMember: {
+    invoke: (channel: string) => PreloadMember;
+    send: (channel: string) => PreloadMember;
+    event: (channel: string) => PreloadMember;
+};
+export interface PreloadExposure {
+    id: string;
+    namespace: string;
+    spec: PreloadApiSpec;
+    owner: string;
+}
+/**
+ * Registry of the APIs plugins want available to the renderer under `window.plugins.<namespace>`.
+ * The sandboxed preload cannot execute plugin code, so exposures are *data*: each member maps to an IPC
+ * channel. The generic preload bridge (see `fluxplugin/preload`) turns them into callable functions.
+ */
+export declare class PreloadRegistry extends Registry<PreloadExposure> {
+    constructor();
+    expose(namespace: string, members: Record<string, PreloadMemberInput>, owner: string): Disposable;
+    /** JSON-serializable manifest sent to the preload bridge. */
+    manifest(): Record<string, PreloadApiSpec>;
+}
+/** Augment in your host or plugin to get typed access to `window.plugins`: `interface PluginApis { analytics: AnalyticsApi }` */
+export interface PluginApis {
+}
+export {};

package/dist/types/core/manager.d.ts

@@ -0,0 +1,155 @@
+import { LogStore, type Disposable } from "./common.js";
+import { EventBus } from "./events.js";
+import { HookSystem } from "./hooks.js";
+import { IpcRegistry, PreloadRegistry } from "./ipc.js";
+import { type Permission, type PluginManifest } from "./manifest.js";
+import { PermissionManager } from "./permissions.js";
+import type { PluginContext, PluginDefinition, PluginInfo, Runtime } from "./plugin.js";
+import { CommandRegistry, MenuRegistry, ServiceRegistry } from "./registry.js";
+import { RouteRegistry } from "./routes.js";
+import { ExtensionPointRegistry, SlotRegistry } from "./slots.js";
+import { type PluginConfig, type PluginState_, type StorageBackend } from "./storage.js";
+import { StyleRegistry } from "./styles.js";
+export interface PluginSource {
+    /** Raw manifest (validated on registration). */
+    manifest: unknown;
+    /** Absolute plugin directory (main process). */
+    root?: string;
+    /** Human-readable origin, e.g. `dir:/plugins/foo`. */
+    origin?: string;
+    /** Imports the plugin entry for this runtime. Must return a *fresh* module on every call (hot reload). */
+    load(): Promise<PluginDefinition<any>>;
+}
+export type Phase = "load" | "initialize" | "activate" | "ready" | "deactivate" | "unload";
+export interface IpcBridge {
+    invoke(name: string, input: unknown, caller: string): Promise<unknown>;
+    send(channel: string, payload: unknown, caller: string): void;
+    on(channel: string, fn: (payload: unknown) => void): Disposable;
+}
+export interface HostApiProvider<T = unknown> {
+    factory: (who: {
+        pluginId: string;
+        root?: string;
+        manifest: PluginManifest;
+    }) => T;
+    permission?: Permission;
+}
+export interface PluginManagerOptions {
+    runtime: Runtime;
+    storage?: StorageBackend;
+    permissions?: PermissionManager;
+    logs?: LogStore;
+    frameworkVersion?: string;
+    timeouts?: Partial<Record<Phase, number>>;
+    /** Plugins crashing this many times inside `crashWindowMs` are disabled automatically. Default 3. */
+    maxCrashes?: number;
+    crashWindowMs?: number;
+    /** Persists the list of disabled plugin ids. */
+    stateStore?: {
+        load(): Promise<string[]>;
+        save(ids: string[]): Promise<void>;
+    };
+    /** Renderer runtimes route IPC through this bridge instead of the (empty) local registry. */
+    ipcBridge?: IpcBridge;
+    /** Called when a plugin emits an event with `{ broadcast: true }` (forward it to the other process). */
+    onBroadcastEvent?: (name: string, payload: unknown, source: string) => void;
+    /** Reject slot contributions to slots the host did not declare. */
+    strictSlots?: boolean;
+}
+export declare class PluginManager {
+    private readonly opts;
+    readonly runtime: Runtime;
+    readonly logs: LogStore;
+    readonly permissions: PermissionManager;
+    readonly events: EventBus;
+    readonly hooks: HookSystem;
+    readonly commands: CommandRegistry;
+    readonly menus: MenuRegistry;
+    readonly routes: RouteRegistry<any>;
+    readonly services: ServiceRegistry;
+    readonly slots: SlotRegistry<any>;
+    readonly extensionPoints: ExtensionPointRegistry;
+    readonly ipc: IpcRegistry;
+    readonly preload: PreloadRegistry;
+    readonly styles: StyleRegistry;
+    readonly storageBackend: StorageBackend;
+    private readonly records;
+    private readonly states;
+    private readonly hostApis;
+    private readonly timeouts;
+    private readonly log;
+    private listeners;
+    private _version;
+    private disposedFlag;
+    constructor(opts: PluginManagerOptions);
+    get version(): number;
+    subscribe: (l: () => void) => (() => void);
+    private changed;
+    /** Exposes a controlled capability to plugins (`context.host.api(name)`), optionally gated by a permission. */
+    provide<T>(name: string, factory: HostApiProvider<T>["factory"], permission?: Permission): Disposable;
+    /** Persisted state (disabled plugins) must be loaded before registering sources. */
+    init(): Promise<void>;
+    private persistedDisabled;
+    /**
+     * Discovers + validates one plugin. Invalid plugins are recorded in the `error` state (so the UI can show why)
+     * and never throw — one broken plugin must not stop the others.
+     */
+    register(source: PluginSource): PluginInfo;
+    unregister(id: string): Promise<void>;
+    has(id: string): boolean;
+    list(): PluginInfo[];
+    info(id: string): PluginInfo;
+    /** Reactive per-plugin state store (same instance as `ctx.state`). Survives reloads. */
+    stateOf(id: string): PluginState_;
+    /** Validated manifest (or the best-effort one for plugins rejected at validation). */
+    manifest(id: string): PluginManifest;
+    getConfig<T extends Record<string, any> = Record<string, any>>(id: string): PluginConfig<T> | undefined;
+    /** Active plugin's context (for hosts and tests). */
+    contextOf(id: string): PluginContext | undefined;
+    diagnostics(id: string): {
+        info: PluginInfo;
+        logs: ReturnType<LogStore["query"]>;
+        contributions: Record<string, number>;
+    };
+    private mustGet;
+    private graph;
+    /** Activates every plugin that wants to start with the application (`onStartup`, `*`, or no activation events). */
+    startup(): Promise<void>;
+    /** Activates `id` and, first, everything it depends on. Rejects with a `LifecycleError` on failure. */
+    activate(id: string): Promise<void>;
+    private ensureReady;
+    private phase;
+    private setState;
+    private bringUp;
+    /** Records a failure, tears down everything the plugin registered and auto-disables repeat offenders. */
+    private fail;
+    /** Disposes every contribution of a plugin (store + owner-based sweep as a safety net). */
+    private teardown;
+    private sweep;
+    /** Deactivates `id` after deactivating every active plugin that depends on it. Never throws for plugin errors. */
+    deactivate(id: string): Promise<void>;
+    private deactivateOne;
+    unload(id: string): Promise<void>;
+    disable(id: string): Promise<void>;
+    enable(id: string, opts?: {
+        activate?: boolean;
+    }): Promise<void>;
+    /** Development hot reload: deactivate → unload → load a fresh module → activate (if it was active). */
+    reload(id: string): Promise<void>;
+    private persistDisabled;
+    dispose(): Promise<void>;
+    /** Activates plugins whose manifest lists `event` (or `*`). Used internally and by hosts for custom events. */
+    trigger(event: string): Promise<void>;
+    private eventMatches;
+    private wireLazyActivation;
+    /**
+     * Before a plugin is active, its statically declared commands/menus (manifest `contributes`) are visible
+     * as lightweight proxies: using one activates the plugin on demand. Replaced by the real registrations on activate.
+     */
+    private installLazyProxies;
+    private removeLazyProxies;
+    private applyDeclarative;
+    private createContext;
+}
+/** `onRoute:/students/:id` style patterns: `:param` matches one segment, `*` matches the rest. */
+export declare function routePatternMatches(pattern: string, path: string): boolean;

package/dist/types/core/manifest.d.ts

@@ -0,0 +1,88 @@
+import { type Infer, type Issue } from "./schema.js";
+/** Version of the plugin API implemented by this framework build. Plugins declare compatibility via `engines`. */
+export declare const FRAMEWORK_VERSION = "1.0.0";
+export declare const FRAMEWORK_ENGINE_KEY = "fluxplugin";
+/** Built-in permission identifiers. Hosts may add their own with the `x.` namespace (e.g. `x.billing.read`). */
+export declare const BUILTIN_PERMISSIONS: readonly ["filesystem.read", "filesystem.write", "network", "database", "ipc", "window", "notifications", "storage", "services", "menus", "commands", "routes", "ui", "events", "hooks", "styles", "clipboard", "shell"];
+export type BuiltinPermission = (typeof BUILTIN_PERMISSIONS)[number];
+export type Permission = BuiltinPermission | `x.${string}`;
+export declare const menuLocations: readonly ["application", "context", "sidebar", "toolbar", "commandPalette", "tray", "settings"];
+export type MenuLocation = (typeof menuLocations)[number];
+export declare const manifestSchema: import("./schema.js").Schema<{
+    id: string;
+    name: string;
+    version: string;
+    activationEvents: string[];
+    deactivationEvents: string[];
+    permissions: Permission[];
+    dependencies: Record<string, string>;
+    optionalDependencies: Record<string, string>;
+    peerDependencies: Record<string, string>;
+    engines: Record<string, string>;
+    contributes: {
+        ipc?: string[] | undefined;
+        services?: string[] | undefined;
+        menus?: {
+            id: string;
+            location: "application" | "context" | "sidebar" | "toolbar" | "commandPalette" | "tray" | "settings";
+            label: string;
+            command?: string | undefined;
+        }[] | undefined;
+        commands?: {
+            id: string;
+            title: string;
+            category?: string | undefined;
+        }[] | undefined;
+        routes?: {
+            path: string;
+            icon?: string | undefined;
+            title?: string | undefined;
+            permission?: Permission | undefined;
+        }[] | undefined;
+        hooks?: string[] | undefined;
+        slots?: string[] | undefined;
+        configuration?: unknown;
+    };
+    styles?: string[] | undefined;
+    description?: string | undefined;
+    author?: string | {
+        name: string;
+        email?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
+    homepage?: string | undefined;
+    repository?: string | {
+        url: string;
+        type?: string | undefined;
+    } | undefined;
+    license?: string | undefined;
+    icon?: string | undefined;
+    main?: string | undefined;
+    preload?: string | undefined;
+    renderer?: string | undefined;
+    tailwind?: {
+        content?: string[] | undefined;
+        safelist?: string[] | undefined;
+        precompiled?: string | undefined;
+    } | undefined;
+    integrity?: Record<string, string> | undefined;
+    signature?: {
+        value: string;
+        algorithm: "ed25519";
+        publicKey: string;
+    } | undefined;
+}>;
+export type PluginManifest = Infer<typeof manifestSchema>;
+export interface ManifestValidation {
+    ok: boolean;
+    manifest?: PluginManifest;
+    issues: Issue[];
+    warnings: string[];
+}
+/**
+ * Validates a raw manifest object (e.g. parsed `plugin.json`). Also checks engine compatibility
+ * against the running framework version and reports non-fatal warnings.
+ */
+export declare function validateManifest(raw: unknown, opts?: {
+    frameworkVersion?: string;
+}): ManifestValidation;

package/dist/types/core/permissions.d.ts

@@ -0,0 +1,45 @@
+import { type Disposable } from "./common.js";
+import type { Permission } from "./manifest.js";
+export interface PermissionSnapshot {
+    declared: Permission[];
+    granted: Permission[];
+    denied: Permission[];
+}
+export interface PermissionManagerOptions {
+    /**
+     * When true (default) every permission declared in a manifest is granted automatically.
+     * Set to false for third-party plugins: declared permissions then need an explicit `grant()`
+     * (typically after the user approved them in the Plugin Manager UI), or a matching entry in `approved`.
+     */
+    autoGrant?: boolean;
+    /** Previously approved permissions (e.g. restored from disk). */
+    approved?: Record<string, Permission[]>;
+    /** Called whenever grants change so the host can persist them. */
+    onChange?: (pluginId: string, snapshot: PermissionSnapshot) => void;
+}
+/**
+ * Tracks which permissions each plugin declared and which were granted.
+ * Every scoped API of `PluginContext` calls `assert()` before doing anything privileged.
+ */
+export declare class PermissionManager {
+    private readonly opts;
+    private declared;
+    private granted;
+    private listeners;
+    private readonly autoGrant;
+    constructor(opts?: PermissionManagerOptions);
+    /** Restores grants persisted from a previous session (call before `declare`). */
+    restore(approved: Record<string, readonly Permission[]>): void;
+    /** Registers a plugin's requested permissions (called when its manifest is loaded). */
+    declare(pluginId: string, permissions: readonly Permission[]): void;
+    forget(pluginId: string): void;
+    has(pluginId: string, permission: Permission): boolean;
+    hasAll(pluginId: string, permissions: readonly Permission[]): boolean;
+    assert(pluginId: string, permission: Permission, api?: string): void;
+    grant(pluginId: string, permission: Permission): void;
+    grantAll(pluginId: string): void;
+    revoke(pluginId: string, permission: Permission): void;
+    snapshot(pluginId: string): PermissionSnapshot;
+    onChange(l: (pluginId: string) => void): Disposable;
+    private notify;
+}

package/dist/types/core/plugin.d.ts

@@ -0,0 +1,214 @@
+import type { Disposable, Logger } from "./common.js";
+import type { EventContext, EventListener, ListenerOptions, EmitResult } from "./events.js";
+import type { AroundNext, HookContext, HookOptions } from "./hooks.js";
+import type { IpcCallContext, IpcContract, IpcDefinition, IpcHandler, PreloadMemberInput } from "./ipc.js";
+import type { Permission, PluginManifest } from "./manifest.js";
+import type { CommandDefinition, MenuItemDefinition } from "./registry.js";
+import type { RouteDefinition } from "./routes.js";
+import type { Schema } from "./schema.js";
+import type { SlotContribution } from "./slots.js";
+import type { ConfigDefinition, PluginConfig, PluginState_, PluginStorage } from "./storage.js";
+import type { StyleInput } from "./styles.js";
+export type Runtime = "main" | "renderer";
+export type PluginState = "discovered" | "validated" | "loaded" | "initialized" | "activated" | "ready" | "deactivated" | "unloaded" | "disabled" | "error";
+export type MenuInput = Omit<MenuItemDefinition, "id" | "location"> & {
+    id: string;
+    location: MenuItemDefinition["location"];
+};
+export interface PluginContext<Cfg extends Record<string, any> = Record<string, any>> {
+    readonly pluginId: string;
+    readonly manifest: PluginManifest;
+    readonly runtime: Runtime;
+    /** Absolute directory of the plugin on disk (main process only). */
+    readonly root: string | undefined;
+    readonly logger: Logger;
+    readonly config: PluginConfig<Cfg>;
+    readonly storage: PluginStorage;
+    /** Volatile reactive state shared with `usePluginState` in React. */
+    readonly state: PluginState_;
+    readonly events: {
+        on<T = unknown>(pattern: string, listener: EventListener<T>, opts?: ListenerOptions): Disposable;
+        once<T = unknown>(pattern: string, listener: EventListener<T>, opts?: Omit<ListenerOptions, "once">): Disposable;
+        emit(name: string, payload?: unknown, opts?: {
+            broadcast?: boolean;
+        }): EmitResult;
+        emitAsync(name: string, payload?: unknown): Promise<EmitResult>;
+    };
+    readonly commands: {
+        register(command: CommandDefinition<any[], any>): Disposable;
+        execute<R = unknown>(id: string, ...args: unknown[]): Promise<R>;
+        list(): CommandDefinition[];
+    };
+    readonly routes: {
+        register<C = unknown>(route: RouteDefinition<C>): Disposable;
+        registerLayout<C = unknown>(id: string, component: C): Disposable;
+    };
+    readonly menus: {
+        register(item: MenuInput): Disposable;
+    };
+    readonly ui: {
+        /** Contributes a component to a host-defined slot. */
+        register<C = unknown>(contribution: SlotContribution<C>): Disposable;
+        /**
+         * Extends a host extension point. With `component` it behaves like a slot contribution
+         * (`ui.extend("user.profile", { mode: "append", component })`); other keys are validated data contributions.
+         */
+        extend(point: string, contribution: Record<string, unknown> & {
+            mode?: SlotContribution["mode"];
+            component?: unknown;
+            priority?: number;
+        }): Disposable;
+    };
+    readonly ipc: {
+        handle<I, O>(contract: IpcContract<I, O>, handler: IpcHandler<I, O>): Disposable;
+        handle<I = unknown, O = unknown>(name: string, handler: IpcHandler<I, O>, opts?: {
+            input?: Schema<I>;
+            output?: Schema<O>;
+            permission?: Permission;
+        }): Disposable;
+        define(def: IpcDefinition<any, any>): Disposable;
+        on(name: string, handler: (payload: unknown, ctx: IpcCallContext) => void): Disposable;
+        /** Main → renderer push (main) / renderer → main fire-and-forget (renderer). */
+        send(channel: string, payload?: unknown): void;
+        invoke<I, O>(contract: IpcContract<I, O>, input: I): Promise<O>;
+        invoke<O = unknown>(name: string, input?: unknown): Promise<O>;
+    };
+    readonly preload: {
+        expose(namespace: string, members: Record<string, PreloadMemberInput>): Disposable;
+    };
+    readonly services: {
+        register<T>(name: string, implementation: T): Disposable;
+        get<T = unknown>(name: string): T | undefined;
+        getAsync<T = unknown>(name: string): Promise<T>;
+    };
+    readonly hooks: {
+        use(name: string, handler: (...args: any[]) => any, opts?: Omit<HookOptions, "owner">): Disposable;
+        run<I, R>(operation: string, input: I, exec: (input: I, ctx: HookContext<I, R>) => R | Promise<R>): Promise<R>;
+        filter<V, X = unknown>(name: string, value: V, extra?: X): Promise<V>;
+    };
+    readonly styles: {
+        add(style: StyleInput): Disposable;
+    };
+    /** Controlled APIs exposed by the host (see `host.provide`), permission-checked per plugin. */
+    readonly host: {
+        api<T = unknown>(name: string): T;
+        has(name: string): boolean;
+    };
+    readonly permissions: {
+        has(permission: Permission): boolean;
+        assert(permission: Permission): void;
+        list(): {
+            declared: Permission[];
+            granted: Permission[];
+            denied: Permission[];
+        };
+    };
+    readonly lifecycle: {
+        readonly state: PluginState;
+        /** Registers cleanup executed on deactivate (in reverse order). */
+        onDeactivate(fn: () => void | Promise<void>): void;
+        /** Anything pushed here is disposed automatically when the plugin deactivates. */
+        readonly subscriptions: {
+            add<T extends Disposable>(d: T): T;
+        };
+    };
+}
+type Ctx<Cfg extends Record<string, any>> = PluginContext<Cfg>;
+export interface PluginDefinition<Cfg extends Record<string, any> = Record<string, any>> {
+    /** Optional: when present it must match the manifest id. */
+    id?: string;
+    name?: string;
+    version?: string;
+    /** Configuration schema; `context.config` and the auto-generated settings form use it. */
+    config?: ConfigDefinition<Cfg>;
+    routes?: RouteDefinition<any>[];
+    layouts?: Record<string, unknown>;
+    commands?: CommandDefinition<any[], any>[];
+    menus?: MenuInput[];
+    hooks?: {
+        name: string;
+        handler: (...args: any[]) => any;
+        priority?: number;
+    }[];
+    /** Service name → implementation, or a factory receiving the context. */
+    services?: Record<string, unknown> | ((ctx: Ctx<Cfg>) => Record<string, unknown>);
+    ipc?: IpcDefinition<any, any>[];
+    events?: {
+        name: string;
+        handler: EventListener<any>;
+        priority?: number;
+        once?: boolean;
+    }[];
+    /** Slot contributions. */
+    components?: SlotContribution<any>[];
+    /** Extension point contributions. */
+    extensions?: {
+        point: string;
+        contribution: Record<string, unknown>;
+        priority?: number;
+    }[];
+    styles?: (string | StyleInput)[];
+    /** Renderer-visible APIs: `{ analytics: { getStats: "analytics.getStats" } }`. */
+    preload?: Record<string, Record<string, PreloadMemberInput>>;
+    onLoad?(ctx: Ctx<Cfg>): void | Promise<void>;
+    onInitialize?(ctx: Ctx<Cfg>): void | Promise<void>;
+    /** Imperative registration point (alias: `activate`). Runs after declarative contributions are registered. */
+    onActivate?(ctx: Ctx<Cfg>): void | Promise<void>;
+    activate?(ctx: Ctx<Cfg>): void | Promise<void>;
+    onReady?(ctx: Ctx<Cfg>): void | Promise<void>;
+    onDeactivate?(ctx: Ctx<Cfg>): void | Promise<void>;
+    deactivate?(ctx: Ctx<Cfg>): void | Promise<void>;
+    onUnload?(ctx: Ctx<Cfg>): void | Promise<void>;
+}
+/** Identity helper giving full type inference for plugin definitions (and config types). */
+export declare function definePlugin<Cfg extends Record<string, any> = Record<string, any>>(def: PluginDefinition<Cfg>): PluginDefinition<Cfg>;
+export declare const defineRoute: <C = unknown>(r: RouteDefinition<C>) => RouteDefinition<C>;
+export declare const defineCommand: <A extends unknown[] = any[], R = unknown>(c: CommandDefinition<A, R>) => CommandDefinition<A, R>;
+export declare const defineService: <T extends Record<string, unknown>>(name: string, impl: T) => {
+    name: string;
+    implementation: T;
+};
+export declare const defineHook: <I = any, R = any>(name: string, handler: (ctx: HookContext<I, R>, next: AroundNext<R>) => any, priority?: number) => {
+    name: string;
+    handler: typeof handler;
+    priority?: number;
+};
+export declare const defineEvent: <T = unknown>(name: string, handler: EventListener<T>, opts?: ListenerOptions) => {
+    name: string;
+    handler: EventListener<T>;
+    priority?: number;
+    once?: boolean;
+};
+export declare const defineComponent: <C = unknown>(c: SlotContribution<C>) => SlotContribution<C>;
+export declare const defineMenu: (m: MenuInput) => MenuInput;
+export type { EventContext };
+/** Information about a plugin as exposed to UIs (manager screens, CLI...). Serializable. */
+export interface PluginInfo {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    state: PluginState;
+    enabled: boolean;
+    runtime: Runtime;
+    permissions: {
+        declared: Permission[];
+        granted: Permission[];
+        denied: Permission[];
+    };
+    dependencies: Record<string, string>;
+    dependents: string[];
+    activationEvents: string[];
+    contributes: PluginManifest["contributes"];
+    error?: {
+        message: string;
+        phase: string;
+        time: number;
+    };
+    crashes: number;
+    hasConfig: boolean;
+    root?: string;
+    origin?: string;
+    warnings: string[];
+}