fluxplugin 1.0.0

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

@@ -0,0 +1,86 @@
+import type { PluginInfo } from "./plugin.js";
+import type { PluginManifest, Permission } from "./manifest.js";
+import type { IpcErrorPayload, PreloadApiSpec } from "./ipc.js";
+/** Electron IPC channel names used by the framework (all prefixed to avoid clashing with host channels). */
+export declare const CHANNELS: {
+    readonly invoke: "flux:invoke";
+    readonly send: "flux:send";
+    readonly event: "flux:event";
+    readonly bootstrap: "flux:bootstrap";
+};
+export interface RendererPluginDescriptor {
+    id: string;
+    manifest: PluginManifest;
+    enabled: boolean;
+    /** URL the renderer imports for this plugin's renderer entry (undefined when it has none). */
+    rendererUrl?: string;
+    /** URLs of CSS files declared in the manifest `styles`. */
+    styleUrls: string[];
+    granted: Permission[];
+    state: PluginInfo["state"];
+}
+export interface Bootstrap {
+    frameworkVersion: string;
+    plugins: RendererPluginDescriptor[];
+    preload: Record<string, PreloadApiSpec>;
+    /** Monotonic counter bumped whenever the plugin set / state changes. */
+    revision: number;
+}
+export interface InvokeRequest {
+    channel: string;
+    input?: unknown;
+    /** Plugin on whose behalf the renderer calls (used for permission checks). */
+    caller?: string;
+}
+export type InvokeResponse = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: IpcErrorPayload;
+};
+export interface EventMessage {
+    channel: string;
+    payload: unknown;
+}
+/** The only surface the preload exposes to renderer code (`window.__fluxplugin`). Everything is plain data + functions. */
+export interface FluxBridge {
+    invoke(channel: string, input?: unknown, caller?: string): Promise<unknown>;
+    send(channel: string, payload?: unknown, caller?: string): void;
+    on(channel: string, listener: (payload: unknown) => void): () => void;
+    bootstrap(): Promise<Bootstrap>;
+}
+/** Management channels served by the main framework to the host UI (`flux.plugins.*`). */
+export declare const MGMT: {
+    readonly list: "flux.plugins.list";
+    readonly enable: "flux.plugins.enable";
+    readonly disable: "flux.plugins.disable";
+    readonly reload: "flux.plugins.reload";
+    readonly grant: "flux.plugins.grant";
+    readonly revoke: "flux.plugins.revoke";
+    readonly uninstall: "flux.plugins.uninstall";
+    readonly install: "flux.plugins.install";
+    readonly update: "flux.plugins.update";
+    readonly rollback: "flux.plugins.rollback";
+    readonly search: "flux.plugins.search";
+    readonly updates: "flux.plugins.updates";
+    readonly configGet: "flux.plugins.config.get";
+    readonly configSet: "flux.plugins.config.set";
+    readonly configReset: "flux.plugins.config.reset";
+    readonly configSchema: "flux.plugins.config.schema";
+    readonly logs: "flux.plugins.logs";
+    readonly diagnostics: "flux.plugins.diagnostics";
+    readonly changed: "flux.plugins.changed";
+};
+/** Serializable description of a plugin offered by a registry (marketplace entry). */
+export interface RegistryEntryLike {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    permissions: string[];
+    location: string;
+    source: string;
+    sha256?: string;
+}

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

@@ -0,0 +1,88 @@
+import { type Disposable } from "./common.js";
+import type { MenuLocation } from "./manifest.js";
+/** Base registry with ownership tracking, change notification and a version counter (for `useSyncExternalStore`). */
+export declare class Registry<T> {
+    protected readonly kind: string;
+    protected table: Map<string, {
+        item: T;
+        owner?: string;
+    }>;
+    private subscribers;
+    private _version;
+    constructor(kind: string);
+    get version(): number;
+    protected add(key: string, item: T, owner?: string): Disposable;
+    has(key: string): boolean;
+    get(key: string): T | undefined;
+    ownerOf(key: string): string | undefined;
+    list(): T[];
+    listByOwner(owner: string): T[];
+    unregisterByOwner(owner: string): number;
+    clear(): void;
+    /** Subscribes to any change. Returns an unsubscribe function compatible with `useSyncExternalStore`. */
+    subscribe: (listener: () => void) => (() => void);
+    protected changed(): void;
+}
+export interface CommandDefinition<A extends unknown[] = any[], R = unknown> {
+    id: string;
+    title: string;
+    category?: string;
+    description?: string;
+    /** Keyboard shortcut, e.g. `Mod+Shift+A` (`Mod` = Ctrl on Windows/Linux, Cmd on macOS). */
+    keybinding?: string;
+    icon?: unknown;
+    /** Evaluated by hosts to hide or disable the command in menus / palette. */
+    when?: () => boolean;
+    execute: (...args: A) => R | Promise<R>;
+}
+export declare class CommandRegistry extends Registry<CommandDefinition> {
+    /** Set by the plugin manager: activates plugins that declared `onCommand:<id>` before execution. */
+    beforeExecute?: (id: string) => Promise<void>;
+    /** Observer used for diagnostics / hooks. */
+    onExecuted?: (id: string, error?: unknown) => void;
+    constructor();
+    register(command: CommandDefinition<any[], any>, owner?: string): Disposable;
+    execute<R = unknown>(id: string, ...args: unknown[]): Promise<R>;
+    /** Commands sorted for display in a palette. */
+    palette(query?: string): CommandDefinition[];
+    /** Finds the command bound to a keyboard shortcut. */
+    byKeybinding(binding: string): CommandDefinition | undefined;
+}
+export interface MenuItemDefinition {
+    id: string;
+    location: MenuLocation;
+    label: string;
+    icon?: unknown;
+    /** Command executed on click. */
+    command?: string;
+    args?: unknown[];
+    /** Visual grouping and ordering inside the location. */
+    group?: string;
+    order?: number;
+    when?: () => boolean;
+    separator?: boolean;
+    children?: Omit<MenuItemDefinition, "location">[];
+    /** Short label shown as a badge. */
+    badge?: string | number;
+    /** Route path, for sidebar entries that navigate without a command. */
+    path?: string;
+}
+export declare class MenuRegistry extends Registry<MenuItemDefinition> {
+    constructor();
+    register(item: MenuItemDefinition, owner?: string): Disposable;
+    items(location: MenuLocation): MenuItemDefinition[];
+}
+export interface ServiceEntry<T = unknown> {
+    id: string;
+    implementation: T;
+}
+export declare class ServiceRegistry extends Registry<ServiceEntry> {
+    /** Set by the plugin manager: activates plugins declaring `onService:<name>` on first lookup. */
+    beforeResolve?: (name: string) => Promise<void>;
+    constructor();
+    register<T>(name: string, implementation: T, owner?: string): Disposable;
+    /** Synchronous lookup — returns undefined when the providing plugin is not active. */
+    resolve<T = unknown>(name: string): T | undefined;
+    /** Looks a service up, activating its provider lazily if necessary. */
+    resolveAsync<T = unknown>(name: string): Promise<T>;
+}

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

@@ -0,0 +1,105 @@
+import { type Disposable } from "./common.js";
+import type { MenuLocation, Permission } from "./manifest.js";
+import { Registry } from "./registry.js";
+export type RouteParams = Record<string, string>;
+export interface RouteGuardContext {
+    path: string;
+    params: RouteParams;
+    route: ResolvedRoute;
+    /** Host-provided state (current user, feature flags...) — see `RouteRegistry.guardContext`. */
+    host: Record<string, unknown>;
+}
+/** Return `true`/`undefined` to allow, `false` to block, or a string path to redirect. */
+export type RouteGuard = (ctx: RouteGuardContext) => boolean | string | void | Promise<boolean | string | void>;
+export interface RouteMeta {
+    title?: string;
+    icon?: unknown;
+    /** Static label or function computing it from params (e.g. loaded entity name). */
+    breadcrumb?: string | ((params: RouteParams) => string);
+    /** Adds an automatic menu entry for this route. */
+    menu?: false | {
+        location?: MenuLocation;
+        label?: string;
+        order?: number;
+        group?: string;
+    };
+    [key: string]: unknown;
+}
+export interface RouteDefinition<C = unknown> {
+    path: string;
+    /** Component to render (any framework — the core does not care). */
+    component?: C;
+    /** Code-split loader. Resolved by the renderer adapter. */
+    lazy?: () => Promise<{
+        default: C;
+    } | C>;
+    /** Id of a registered layout, or a component used directly as the layout. */
+    layout?: string | C;
+    children?: RouteDefinition<C>[];
+    /** `protected` routes require the host `isAuthenticated` guard (see RouteRegistry.guardContext) — default is `public`. */
+    access?: "public" | "protected";
+    /** Permission the *plugin* must hold (declared in manifest) to register this route. */
+    permission?: Permission;
+    guards?: RouteGuard[];
+    meta?: RouteMeta;
+}
+export interface ResolvedRoute<C = unknown> {
+    /** Full normalized path pattern, e.g. `/settings/analytics/:id`. */
+    fullPath: string;
+    definition: RouteDefinition<C>;
+    owner?: string;
+    /** Ancestors from root to this route (excluding itself). */
+    parents: ResolvedRoute<C>[];
+    segments: Seg[];
+    score: number;
+}
+type Seg = {
+    type: "static";
+    value: string;
+} | {
+    type: "param";
+    name: string;
+} | {
+    type: "splat";
+};
+export interface RouteMatch<C = unknown> {
+    route: ResolvedRoute<C>;
+    params: RouteParams;
+    /** Ancestors + route, root first (used to nest layouts and build breadcrumbs). */
+    chain: ResolvedRoute<C>[];
+}
+export interface Breadcrumb {
+    label: string;
+    path: string;
+}
+export type GuardResult = {
+    allow: true;
+} | {
+    allow: false;
+    redirect?: string;
+    reason: string;
+};
+export declare function normalizePath(path: string): string;
+export declare class RouteRegistry<C = unknown> extends Registry<ResolvedRoute<C>> {
+    /** Host-provided values handed to guards (e.g. `{ isAuthenticated: true }`). */
+    guardContext: Record<string, unknown>;
+    /** Set by the plugin manager to lazily activate plugins declaring `onRoute:<path>`. */
+    beforeResolve?: (path: string) => Promise<void>;
+    /** Called for every route with `meta.menu`: lets the manager create sidebar entries automatically. */
+    onRouteRegistered?: (route: ResolvedRoute<C>, owner?: string) => Disposable | void;
+    private layouts;
+    constructor();
+    registerLayout(id: string, component: C): Disposable;
+    getLayout(id: string): C | undefined;
+    private bump;
+    /** Registers a route (and its children). Returns one disposable removing all of them. */
+    register(def: RouteDefinition<C>, owner?: string): Disposable;
+    /** Finds the best route for a concrete pathname. */
+    match(pathname: string): RouteMatch<C> | undefined;
+    /** Same as `match` but first lets lazily-activated plugins register their routes. */
+    matchAsync(pathname: string): Promise<RouteMatch<C> | undefined>;
+    /** Evaluates `access`, then every guard from the root layout down to the route itself. */
+    checkGuards(m: RouteMatch<C>, pathname: string): Promise<GuardResult>;
+    breadcrumbs(m: RouteMatch<C>): Breadcrumb[];
+}
+export {};

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

@@ -0,0 +1,99 @@
+/**
+ * Tiny dependency-free schema library used for manifest validation,
+ * IPC input/output validation and plugin configuration.
+ * Provides static type inference via `Infer<T>`.
+ */
+export interface Issue {
+    path: string;
+    message: string;
+}
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: Issue[];
+};
+export interface SchemaDescription {
+    type: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: readonly unknown[];
+    properties?: Record<string, SchemaDescription>;
+    required?: string[];
+    items?: SchemaDescription;
+    optional?: boolean;
+    min?: number;
+    max?: number;
+}
+export interface Schema<T> {
+    readonly kind: string;
+    readonly _type?: T;
+    parse(input: unknown, path?: string): ParseResult<T>;
+    /** Describes the schema as JSON-schema-like data (used to auto-generate config UIs). */
+    describe(): SchemaDescription;
+    optional(): Schema<T | undefined>;
+    default(value: T): Schema<T>;
+}
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+export declare class ValidationError extends Error {
+    readonly issues: Issue[];
+    constructor(issues: Issue[], what?: string);
+}
+export interface StringOpts {
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+    title?: string;
+    description?: string;
+}
+export interface NumberOpts {
+    min?: number;
+    max?: number;
+    int?: boolean;
+    title?: string;
+    description?: string;
+}
+type OptionalKeys<P> = {
+    [K in keyof P]: undefined extends Infer<P[K]> ? K : never;
+}[keyof P];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type ObjectOf<P extends Record<string, Schema<any>>> = Simplify<{
+    [K in Exclude<keyof P, OptionalKeys<P>>]: Infer<P[K]>;
+} & {
+    [K in OptionalKeys<P>]?: Exclude<Infer<P[K]>, undefined>;
+}>;
+export declare const s: {
+    string(o?: StringOpts): Schema<string>;
+    number(o?: NumberOpts): Schema<number>;
+    boolean(o?: {
+        title?: string;
+        description?: string;
+    }): Schema<boolean>;
+    unknown(): Schema<unknown>;
+    literal<const V extends string | number | boolean>(v: V): Schema<V>;
+    enum<const V extends readonly string[]>(values: V, o?: {
+        title?: string;
+        description?: string;
+    }): Schema<V[number]>;
+    array<T>(item: Schema<T>, o?: {
+        min?: number;
+        max?: number;
+    }): Schema<T[]>;
+    record<T>(value: Schema<T>): Schema<Record<string, T>>;
+    object<P extends Record<string, Schema<any>>>(shape: P, o?: {
+        strict?: boolean;
+        title?: string;
+        description?: string;
+    }): Schema<ObjectOf<P>>;
+    /** Accepts a value if any of the schemas matches. */
+    union<T extends readonly Schema<any>[]>(...options: T): Schema<Infer<T[number]>>;
+    /** Escape hatch for values that cannot be validated structurally (functions, React components...). */
+    custom<T>(check: (v: unknown) => boolean, message?: string): Schema<T>;
+    fn<T = (...args: any[]) => any>(): Schema<T>;
+};
+export declare function parseOrThrow<T>(schema: Schema<T>, input: unknown, what?: string): T;
+export {};

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

@@ -0,0 +1,16 @@
+/**
+ * Minimal, dependency-free semver implementation covering what the framework needs:
+ * parse, compare, and range satisfaction for `^`, `~`, `>=`, `>`, `<=`, `<`, `=`, `*`, `x`-ranges
+ * and space-separated comparator sets (AND) as well as `||` (OR).
+ */
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string[];
+}
+export declare function parseVersion(v: string): SemVer | null;
+export declare function isValidVersion(v: string): boolean;
+export declare function compareVersions(a: string, b: string): number;
+export declare function isValidRange(range: string): boolean;
+export declare function satisfies(version: string, range: string): boolean;

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

@@ -0,0 +1,75 @@
+import { type Disposable } from "./common.js";
+import { Registry } from "./registry.js";
+import type { Schema } from "./schema.js";
+export type SlotMode = "before" | "after" | "replace" | "append" | "prepend";
+export interface SlotContribution<C = unknown> {
+    /** Optional id so the contribution can be overridden or inspected. Generated when omitted. */
+    id?: string;
+    slot: string;
+    component: C;
+    mode?: SlotMode;
+    /** Higher renders first within its group. Default 0. */
+    priority?: number;
+    /** Evaluated at render time with the slot props. */
+    when?: (props: Record<string, unknown>) => boolean;
+    /** Props merged into the component props. */
+    props?: Record<string, unknown>;
+}
+export interface ResolvedSlotContribution<C = unknown> extends Required<Pick<SlotContribution<C>, "id" | "slot" | "component" | "mode" | "priority">> {
+    props?: Record<string, unknown>;
+    owner?: string;
+}
+export interface ResolvedSlot<C = unknown> {
+    /** Everything rendered before the host default content (prepend, then before). */
+    before: ResolvedSlotContribution<C>[];
+    /** When set, replaces the host default content. */
+    replacement?: ResolvedSlotContribution<C>;
+    /** Everything rendered after the host default content (after, then append). */
+    after: ResolvedSlotContribution<C>[];
+}
+export declare class SlotRegistry<C = unknown> extends Registry<ResolvedSlotContribution<C> & {
+    when?: SlotContribution<C>["when"];
+}> {
+    private counter;
+    /** Set by the plugin manager to activate plugins declaring `onSlot:<name>`. */
+    onSlotRendered?: (slot: string) => void;
+    private declared;
+    constructor();
+    /** Hosts may declare their slots so typos in plugins are caught early. Declaring is optional. */
+    declareSlot(name: string): void;
+    declaredSlots(): string[];
+    register(c: SlotContribution<C>, owner?: string, opts?: {
+        strict?: boolean;
+    }): Disposable;
+    resolve(slot: string, props?: Record<string, unknown>): ResolvedSlot<C>;
+    /** Slots that currently have at least one contribution. */
+    activeSlots(): string[];
+}
+export interface ExtensionPointDefinition {
+    name: string;
+    description?: string;
+    /** Allowed contribution keys, each optionally validated by a schema applied to every contributed item. */
+    contributions: Record<string, Schema<any> | null>;
+}
+interface PointContribution {
+    priority: number;
+    value: Record<string, unknown>;
+}
+/**
+ * Declarative extension points: the host says *what* can be extended (`toolbar`, `tabs`, `actions`...),
+ * plugins contribute plain data validated against the host's schema. No DOM access, no monkey patching.
+ */
+export declare class ExtensionPointRegistry extends Registry<PointContribution & {
+    point: string;
+}> {
+    private points;
+    private counter;
+    constructor();
+    declare(def: ExtensionPointDefinition): Disposable;
+    definition(name: string): ExtensionPointDefinition | undefined;
+    declaredPoints(): ExtensionPointDefinition[];
+    contribute(point: string, value: Record<string, unknown>, owner?: string, priority?: number): Disposable;
+    /** Merged, priority-ordered items contributed under `key` of `point`. */
+    items<T = unknown>(point: string, key: string): T[];
+}
+export {};

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

@@ -0,0 +1,55 @@
+import { type Disposable } from "./common.js";
+import { type Schema } from "./schema.js";
+/** Persistence backend: one JSON document per namespace (= plugin id). */
+export interface StorageBackend {
+    read(namespace: string): Promise<Record<string, unknown>>;
+    write(namespace: string, data: Record<string, unknown>): Promise<void>;
+    remove?(namespace: string): Promise<void>;
+}
+export declare class MemoryStorageBackend implements StorageBackend {
+    private data;
+    read(ns: string): Promise<Record<string, unknown>>;
+    write(ns: string, data: Record<string, unknown>): Promise<void>;
+    remove(ns: string): Promise<void>;
+}
+export interface PluginStorage {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    get<T>(key: string, fallback: T): Promise<T>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+/**
+ * Storage scoped to a single plugin. Writes are serialized per namespace so concurrent `set` calls never
+ * lose updates, and values are cloned (structured clone) so callers cannot mutate stored state by reference.
+ */
+export declare function createPluginStorage(backend: StorageBackend, namespace: string): PluginStorage;
+export interface ConfigDefinition<T extends Record<string, any> = Record<string, any>> {
+    schema: Schema<T>;
+    /** Current schema version. Stored configs with a lower version go through `migrate`. */
+    version?: number;
+    migrate?: (old: Record<string, unknown>, fromVersion: number) => Record<string, unknown>;
+}
+export interface PluginConfig<T extends Record<string, any> = Record<string, any>> {
+    /** Loads (and migrates/validates) the configuration; always resolves with a fully defaulted object. */
+    get(): Promise<T>;
+    /** Merges a partial update, validates the result and persists it. Rejects with `ValidationError`. */
+    set(patch: Partial<T>): Promise<T>;
+    reset(): Promise<T>;
+    onChange(listener: (next: T, prev: T) => void): Disposable;
+    /** JSON-schema-like description for building settings forms automatically. */
+    describe(): ReturnType<Schema<T>["describe"]>;
+}
+export declare function createPluginConfig<T extends Record<string, any>>(backend: StorageBackend, namespace: string, def: ConfigDefinition<T>, onChanged?: (next: T, prev: T) => void): PluginConfig<T>;
+export interface PluginState_ {
+    get<T = unknown>(key: string): T | undefined;
+    get<T>(key: string, fallback: T): T;
+    set<T>(key: string, value: T): void;
+    delete(key: string): void;
+    /** Subscribes to changes of one key (or every key when omitted). */
+    subscribe(listener: (key: string, value: unknown) => void, key?: string): Disposable;
+    snapshot(): Record<string, unknown>;
+}
+/** Volatile, reactive per-plugin state (lives as long as the plugin runtime; use `storage` for persistence). */
+export declare function createPluginState(): PluginState_;

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

@@ -0,0 +1,34 @@
+import { Registry } from "./registry.js";
+import type { Disposable } from "./common.js";
+export interface StyleEntry {
+    id: string;
+    /** Inline CSS text (already compiled). */
+    css?: string;
+    /** URL of a stylesheet (served by the host — e.g. `fluxplugin://<id>/styles/index.css`). */
+    href?: string;
+    /** Lower numbers load first; later entries win ties in the cascade. Default 100. */
+    priority: number;
+    /** Wrap rules in `@scope ([data-fluxplugin="<id>"])` so they only affect the plugin's own subtree. */
+    scoped: boolean;
+    owner: string;
+}
+export interface StyleInput {
+    id?: string;
+    css?: string;
+    href?: string;
+    priority?: number;
+    scoped?: boolean;
+}
+/**
+ * Data-only registry of the styles contributed by plugins. A renderer adapter (see `fluxplugin/react`'s
+ * `StyleHost`) mirrors this registry into `<style>`/`<link>` elements, which is what makes
+ * disable → remove and hot-reload → replace work without touching the DOM from plugin code.
+ */
+export declare class StyleRegistry extends Registry<StyleEntry> {
+    private n;
+    constructor();
+    register(input: StyleInput, owner: string): Disposable;
+    /** Entries in cascade order. */
+    ordered(): StyleEntry[];
+}
+export declare function scopeCss(css: string, pluginId: string): string;

package/dist/types/main/adapters.d.ts

@@ -0,0 +1,81 @@
+import http from "node:http";
+import type { MainFramework } from "./framework.js";
+/** Minimal structural types so this package never imports `electron` (works with any Electron version). */
+export interface IpcMainLike {
+    handle(channel: string, listener: (event: {
+        sender: {
+            id: number;
+        };
+    }, ...args: any[]) => unknown): void;
+    on(channel: string, listener: (event: {
+        sender: {
+            id: number;
+        };
+    }, ...args: any[]) => void): void;
+    removeHandler(channel: string): void;
+    removeListener(channel: string, listener: (...args: any[]) => void): void;
+}
+export interface WebContentsLike {
+    id: number;
+    send(channel: string, ...args: unknown[]): void;
+    isDestroyed(): boolean;
+}
+export interface ElectronLike {
+    ipcMain: IpcMainLike;
+    webContents: {
+        getAllWebContents(): WebContentsLike[];
+    };
+}
+/**
+ * Connects the framework to Electron's ipcMain. Call after `app.whenReady()`.
+ * Returns a detach function.
+ */
+export declare function attachElectron(fw: MainFramework, electron: ElectronLike): () => void;
+/** Privileged scheme definition. Must be passed to `protocol.registerSchemesAsPrivileged` *before* `app.ready`. */
+export declare const PLUGIN_SCHEME: {
+    readonly scheme: "fluxplugin";
+    readonly privileges: {
+        readonly standard: true;
+        readonly secure: true;
+        readonly supportFetchAPI: true;
+        readonly corsEnabled: true;
+        readonly stream: true;
+    };
+};
+/**
+ * Resolves `fluxplugin://<id>/<path>` to a file inside the plugin's directory. Rejects traversal and anything that
+ * is not an asset (the manifest and main entry are never served).
+ */
+export declare function resolvePluginAsset(fw: MainFramework, url: string): Promise<{
+    file: string;
+    mime: string;
+} | null>;
+/** Registers the `fluxplugin://` handler on an Electron `protocol` object (`protocol.handle`, Electron >= 25). */
+export declare function registerPluginProtocol(fw: MainFramework, protocol: {
+    handle(scheme: string, handler: (req: {
+        url: string;
+    }) => Promise<Response> | Response): void;
+}): void;
+export interface HttpAdapterOptions {
+    port?: number;
+    host?: string;
+    /** URL prefix under which plugin assets are served. Default `/@plugins`. */
+    assetPrefix?: string;
+    /** Extra request handler (e.g. serve the Vite build). Return true when handled. */
+    fallback?: (req: http.IncomingMessage, res: http.ServerResponse) => boolean | Promise<boolean>;
+}
+/**
+ * Serves the same wire protocol over HTTP (POST /flux/invoke, POST /flux/send, GET /flux/bootstrap, SSE /flux/events,
+ * GET /@plugins/<id>/<file>). Used for browser-based development, headless E2E tests and screenshots.
+ * Bind to loopback only: there is no authentication, exactly like the Electron-only bridge it replaces.
+ */
+export declare function attachHttp(fw: MainFramework, opts?: HttpAdapterOptions): Promise<{
+    server: http.Server;
+    port: number;
+    close(): Promise<void>;
+}>;
+/**
+ * In-process bridge connecting a renderer runtime directly to a `MainFramework` (no IPC, no serialization
+ * except a JSON round trip to mimic structured cloning). Used by integration tests and storybook-like setups.
+ */
+export declare function createLoopbackBridge(fw: MainFramework): import("../core/index.js").FluxBridge;

package/dist/types/main/discover.d.ts

@@ -0,0 +1,21 @@
+import type { PluginManifest, PluginSource } from "../core/index.js";
+import { type VerifyOptions } from "./security.js";
+export declare const MANIFEST_FILE = "plugin.json";
+export interface DiscoveredPlugin {
+    root: string;
+    manifest: Record<string, unknown>;
+    source: PluginSource;
+    /** Errors found while reading the plugin (it is still returned so the UI can display the failure). */
+    problem?: string;
+}
+/** Imports an ESM/CJS entry and returns its default export. A unique query string defeats the module cache (hot reload). */
+export declare function importFresh(file: string): Promise<unknown>;
+export interface DiscoverOptions extends VerifyOptions {
+    /** Entry loader override (tests, bundlers). */
+    loadEntry?: (file: string) => Promise<unknown>;
+}
+/** Reads one plugin directory. */
+export declare function readPluginDir(root: string, opts?: DiscoverOptions): Promise<DiscoveredPlugin>;
+/** Scans `dir` for sub-directories containing a plugin.json. Plugins that fail verification are reported, not skipped. */
+export declare function discoverPlugins(dir: string, opts?: DiscoverOptions): Promise<DiscoveredPlugin[]>;
+export type { PluginManifest };