fluxplugin 1.0.0

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

@@ -0,0 +1,78 @@
+import { LogStore, PluginManager, type Bootstrap, type InvokeRequest, type InvokeResponse, type PluginManagerOptions } from "../core/index.js";
+import { type DiscoverOptions } from "./discover.js";
+import { PluginInstaller, type PluginRegistry } from "./registry.js";
+export interface MainFrameworkOptions {
+    /** Directories scanned for plugins (each sub-directory with a plugin.json). */
+    pluginDirs: string[];
+    /** Where plugin storage/config/state lives (typically `app.getPath("userData")/plugins-data`). */
+    dataDir: string;
+    /** Where installs/uninstalls happen. Defaults to the first of `pluginDirs`. */
+    installDir?: string;
+    registries?: PluginRegistry[];
+    /** Third-party plugins start with no permissions until the user approves them. Default: false (all declared granted). */
+    requireApproval?: boolean;
+    /** Reject plugins without a valid signature from one of these keys. */
+    trustedKeys?: string[];
+    requireSignature?: boolean;
+    /** Re-load plugins when files change on disk. Default false (enable in development). */
+    hotReload?: boolean;
+    /** Builds the URL used by the renderer to import `<pluginId>/<relative file>` (custom protocol or dev server). */
+    assetUrl?: (pluginId: string, relativePath: string) => string;
+    /** Channels the renderer may call in addition to those exposed by plugins. */
+    allowedRendererChannels?: string[];
+    /** Whether renderer code may use `flux.plugins.*` management channels. Default true (the host UI needs them). */
+    allowManagement?: boolean;
+    frameworkVersion?: string;
+    manager?: Partial<PluginManagerOptions>;
+    /** Replaces discovery loader (tests). */
+    discover?: DiscoverOptions;
+}
+type BroadcastListener = (channel: string, payload: unknown, target?: number | string) => void;
+/**
+ * Everything the main process needs, with no dependency on Electron. Adapters (`attachElectron`, `attachHttp`)
+ * connect it to a transport. This keeps the logic testable and lets the same framework run under
+ * Electron, a dev HTTP server, or an integration test.
+ */
+export declare class MainFramework {
+    readonly options: MainFrameworkOptions;
+    readonly manager: PluginManager;
+    readonly logs: LogStore;
+    readonly installer: PluginInstaller;
+    private readonly permissions;
+    private readonly state;
+    private readonly broadcastListeners;
+    private watchers;
+    private revision;
+    private reloadTimers;
+    private started;
+    constructor(options: MainFrameworkOptions);
+    start(): Promise<void>;
+    private discoverOpts;
+    /** (Re)scans the plugin directories and registers plugins that are new. */
+    scan(): Promise<void>;
+    stop(): Promise<void>;
+    /** Watches plugin directories and reloads the affected plugin (debounced). */
+    private watch;
+    private hotReloadFolder;
+    onBroadcast(l: BroadcastListener): () => void;
+    broadcast(channel: string, payload: unknown, target?: number | string): void;
+    bootstrap(): Bootstrap;
+    private exposedChannels;
+    /**
+     * Handles an invoke coming from a renderer. Policy: the renderer may only call channels that a plugin explicitly
+     * exposed through `preload.expose`, channels the host allow-listed, and (optionally) `flux.plugins.*`.
+     */
+    handleInvoke(req: InvokeRequest, senderId?: number | string): Promise<InvokeResponse>;
+    handleSend(channel: string, payload: unknown, caller?: string, senderId?: number | string): void;
+    private registerManagementApi;
+    private requireConfig;
+    private installAndLoad;
+    /** Channels used by transports. */
+    static readonly channels: {
+        readonly invoke: "flux:invoke";
+        readonly send: "flux:send";
+        readonly event: "flux:event";
+        readonly bootstrap: "flux:bootstrap";
+    };
+}
+export {};

package/dist/types/main/fs-storage.d.ts

@@ -0,0 +1,33 @@
+import type { StorageBackend } from "../core/index.js";
+/** One JSON file per plugin namespace, written atomically (tmp + rename). */
+export declare class FsStorageBackend implements StorageBackend {
+    private readonly dir;
+    constructor(dir: string);
+    private file;
+    read(ns: string): Promise<Record<string, unknown>>;
+    write(ns: string, data: Record<string, unknown>): Promise<void>;
+    remove(ns: string): Promise<void>;
+}
+/** Persists the list of disabled plugins and approved permissions. Updates are serialized (no lost writes). */
+export declare class JsonStateFile {
+    private readonly file;
+    private queue;
+    constructor(file: string);
+    readAll(): Promise<{
+        disabled: string[];
+        approved: Record<string, string[]>;
+    }>;
+    /** Merges `patch(current)` into the file. Concurrent calls run one after the other. */
+    update(patch: Partial<{
+        disabled: string[];
+        approved: Record<string, string[]>;
+    }> | ((cur: {
+        disabled: string[];
+        approved: Record<string, string[]>;
+    }) => Partial<{
+        disabled: string[];
+        approved: Record<string, string[]>;
+    }>)): Promise<void>;
+    /** Resolves once every queued write has hit the disk. */
+    flush(): Promise<void>;
+}

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

@@ -0,0 +1,8 @@
+export * from "./framework.js";
+export * from "./adapters.js";
+export * from "./discover.js";
+export * from "./security.js";
+export * from "./registry.js";
+export * from "./fs-storage.js";
+export * from "./tar.js";
+export * from "./serve-web.js";

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

@@ -0,0 +1,75 @@
+import { type PluginManifest } from "../core/index.js";
+import { createTarGz } from "./tar.js";
+export interface RegistryEntry {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    permissions: string[];
+    /** Opaque location understood by the registry that produced the entry. */
+    location: string;
+    source: string;
+    /** sha256 hex of the archive when the registry knows it. */
+    sha256?: string;
+}
+/**
+ * Abstraction over where plugins come from. Implement it for npm, GitHub releases, a private HTTP registry,
+ * or a marketplace. The framework only needs `search` and `fetch` (a directory with a plugin.json).
+ */
+export interface PluginRegistry {
+    readonly name: string;
+    search(query?: string): Promise<RegistryEntry[]>;
+    /** Materializes a plugin into `destDir` (which does not exist yet). Returns its manifest. */
+    fetch(entry: RegistryEntry, destDir: string): Promise<PluginManifest>;
+}
+export declare function copyDir(src: string, dest: string): Promise<void>;
+/** A directory whose sub-directories are plugins (e.g. a shared network folder or a repo checkout). */
+export declare class LocalRegistry implements PluginRegistry {
+    private readonly dir;
+    readonly name: string;
+    constructor(dir: string, name?: string);
+    search(query?: string): Promise<RegistryEntry[]>;
+    fetch(entry: RegistryEntry, dest: string): Promise<PluginManifest>;
+}
+/**
+ * HTTP registry: GET `<baseUrl>/index.json` → `{ plugins: [{ id, name, version, description, author, permissions, url, sha256 }] }`
+ * where `url` points at a `.tgz` produced by `fluxplugin package`. Downloads are verified against `sha256` when given.
+ */
+export declare class HttpRegistry implements PluginRegistry {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    readonly name: string;
+    constructor(baseUrl: string, fetchImpl?: typeof fetch);
+    search(query?: string): Promise<RegistryEntry[]>;
+    fetch(entry: RegistryEntry, dest: string): Promise<PluginManifest>;
+}
+export interface InstallResult {
+    id: string;
+    version: string;
+    previousVersion?: string;
+}
+/**
+ * Installs plugins into a directory, keeping the previous version as a backup so `rollback` works.
+ * Layout: `<pluginsDir>/<id>/` (active) and `<backupDir>/<id>/<version>/` (previous versions).
+ */
+export declare class PluginInstaller {
+    private readonly pluginsDir;
+    private readonly backupDir;
+    private readonly registries;
+    constructor(pluginsDir: string, backupDir: string, registries?: PluginRegistry[]);
+    addRegistry(r: PluginRegistry): void;
+    search(query?: string): Promise<RegistryEntry[]>;
+    installed(): Promise<PluginManifest[]>;
+    private dirOf;
+    /** Installs (or updates) `entry`. The plugin directory is replaced atomically from a staging directory. */
+    install(entry: RegistryEntry): Promise<InstallResult>;
+    /** Removes the plugin directory (backups are kept so the user can still roll back/reinstall). */
+    uninstall(id: string): Promise<void>;
+    versions(id: string): Promise<string[]>;
+    /** Restores the newest backup (or `version`) and keeps the replaced version as a backup. */
+    rollback(id: string, version?: string): Promise<InstallResult>;
+    /** Entries from registries that are newer than what is installed. */
+    updates(): Promise<RegistryEntry[]>;
+}
+export { createTarGz };

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

@@ -0,0 +1,24 @@
+import type { PluginManifest } from "../core/index.js";
+export declare class IntegrityError extends Error {
+    constructor(message: string);
+}
+export declare const sha256File: (file: string) => Promise<string>;
+/** Deterministic JSON (sorted keys) so signatures do not depend on key order. */
+export declare function canonicalJson(v: unknown): string;
+/** Fills `integrity` for every entry file of a manifest. Used by `fluxplugin package`. */
+export declare function computeIntegrity(root: string, manifest: Pick<PluginManifest, "main" | "preload" | "renderer" | "styles">): Promise<Record<string, string>>;
+export declare function generateSigningKeyPair(): {
+    publicKey: string;
+    privateKey: string;
+};
+export declare function signManifest(manifest: Record<string, unknown>, privateKeyB64: string): Record<string, unknown>;
+export interface VerifyOptions {
+    /** Verify the hashes listed in `manifest.integrity` (default true). */
+    verifyIntegrity?: boolean;
+    /** Public keys (base64 SPKI DER) allowed to sign plugins. */
+    trustedKeys?: string[];
+    /** Refuse plugins without a valid signature from a trusted key. Default false. */
+    requireSignature?: boolean;
+}
+/** Throws `IntegrityError` when a check fails. Returns warnings otherwise. */
+export declare function verifyPlugin(root: string, raw: Record<string, unknown>, manifest: PluginManifest, opts?: VerifyOptions): Promise<string[]>;

package/dist/types/main/serve-web.d.ts

@@ -0,0 +1,14 @@
+import type { MainFramework } from "./framework.js";
+/**
+ * Runs the app in a plain browser: serves the built renderer (`distDir`) plus the framework wire protocol over HTTP/SSE.
+ * Intended for development, headless E2E tests and demos; binds to loopback by default.
+ */
+export declare function serveWeb(fw: MainFramework, opts: {
+    distDir: string;
+    port?: number;
+    host?: string;
+}): Promise<{
+    server: import("http").Server;
+    port: number;
+    close(): Promise<void>;
+}>;

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

@@ -0,0 +1,10 @@
+/** Creates a .tgz (ustar) of a directory. Entries are placed under `package/` like npm does. */
+export declare function createTarGz(dir: string, prefix?: string): Promise<Buffer>;
+export interface TarEntry {
+    name: string;
+    type: "file" | "dir";
+    data: Buffer;
+}
+export declare function readTarGz(buf: Buffer): Promise<TarEntry[]>;
+/** Extracts into `dest`, stripping the first path component. Rejects traversal and absolute paths. */
+export declare function extractTarGz(buf: Buffer, dest: string): Promise<void>;

package/dist/types/manager-ui/index.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+/** Auto-generated settings form from a plugin's config schema (`ctx.config.describe()`). */
+export declare function ConfigForm({ id }: {
+    id: string;
+}): React.ReactElement | null;
+/** Full plugin manager screen. Extensible through the `manager.plugin.actions` / `manager.plugin.details` slots. */
+export declare function PluginManagerUI(): React.ReactElement;

package/dist/types/preload/index.d.ts

@@ -0,0 +1,27 @@
+import { type FluxBridge, type IpcErrorPayload } from "../core/index.js";
+/** Structural types for Electron's `contextBridge` / `ipcRenderer` — no `electron` import, works in sandboxed preloads. */
+export interface IpcRendererLike {
+    invoke(channel: string, ...args: unknown[]): Promise<any>;
+    send(channel: string, ...args: unknown[]): void;
+    on(channel: string, listener: (event: unknown, ...args: any[]) => void): unknown;
+    removeListener(channel: string, listener: (...args: any[]) => void): unknown;
+}
+export interface ContextBridgeLike {
+    exposeInMainWorld(key: string, api: unknown): void;
+}
+export declare class IpcCallError extends Error {
+    readonly payload: IpcErrorPayload;
+    constructor(payload: IpcErrorPayload);
+    get code(): string;
+}
+/**
+ * Creates the bridge object. It is deliberately tiny and generic: it knows nothing about plugins.
+ * Per-plugin APIs (`window.plugins.analytics.getStats()`) are generated *in the renderer* from the preload
+ * manifest (see `fluxplugin/react` → `installWindowPlugins`), so plugins can be enabled/disabled at runtime —
+ * `contextBridge` can only expose objects once, at preload time.
+ *
+ * Nothing from Node, `ipcRenderer` itself, or `event` objects ever reaches the page: only the five functions below.
+ */
+export declare function createBridge(ipcRenderer: IpcRendererLike): FluxBridge;
+/** Call from your preload script: `exposeFluxBridge(contextBridge, ipcRenderer)`. */
+export declare function exposeFluxBridge(contextBridge: ContextBridgeLike, ipcRenderer: IpcRendererLike, key?: string): FluxBridge;

package/dist/types/react/base-css.d.ts

@@ -0,0 +1,2 @@
+/** Minimal CSS for the framework's own components. Uses CSS variables so hosts can theme it; Tailwind is not required. */
+export declare const baseCss = "\n:root{--flux-bg:#fff;--flux-fg:#0f172a;--flux-muted:#64748b;--flux-border:#e2e8f0;--flux-accent:#4f46e5;--flux-accent-fg:#fff;--flux-surface:#f8fafc;--flux-danger:#dc2626;--flux-ok:#16a34a;--flux-warn:#d97706;--flux-radius:10px}\n@media (prefers-color-scheme: dark){:root:not([data-theme=\"light\"]){--flux-bg:#0b1020;--flux-fg:#e5e7eb;--flux-muted:#94a3b8;--flux-border:#1f2a44;--flux-surface:#111936}}\n.fluxplugin-error{padding:8px 12px;border:1px solid var(--flux-danger);border-radius:var(--flux-radius);color:var(--flux-danger);font-size:13px}\n.flux-breadcrumbs{font-size:13px;color:var(--flux-muted)}.flux-breadcrumbs a{color:inherit}\n.flux-not-found,.flux-forbidden,.flux-loading{padding:24px;color:var(--flux-muted)}\n.flux-palette-backdrop{position:fixed;inset:0;background:rgba(2,6,23,.45);display:flex;justify-content:center;align-items:flex-start;padding-top:14vh;z-index:9999}\n.flux-palette{width:min(560px,92vw);background:var(--flux-bg);color:var(--flux-fg);border:1px solid var(--flux-border);border-radius:14px;box-shadow:0 24px 60px rgba(0,0,0,.35);overflow:hidden}\n.flux-palette-input{width:100%;box-sizing:border-box;padding:14px 16px;border:0;border-bottom:1px solid var(--flux-border);background:transparent;color:inherit;font-size:15px;outline:none}\n.flux-palette-list{list-style:none;margin:0;padding:6px;max-height:340px;overflow:auto}\n.flux-palette-item{display:flex;justify-content:space-between;align-items:center;gap:12px;padding:9px 12px;border-radius:8px;cursor:pointer;font-size:14px}\n.flux-palette-item.is-active{background:var(--flux-accent);color:var(--flux-accent-fg)}\n.flux-palette-cat{opacity:.65}.flux-palette-empty{padding:14px;color:var(--flux-muted);font-size:14px}\n.flux-palette kbd{font:11px ui-monospace,monospace;padding:2px 6px;border:1px solid currentColor;border-radius:5px;opacity:.7}\n";

package/dist/types/react/components.d.ts

@@ -0,0 +1,89 @@
+import React, { Component, type ErrorInfo, type ReactNode } from "react";
+import { type IpcContract, type PluginConfig, type PluginInfo } from "../core/index.js";
+import { RendererFramework } from "./runtime.js";
+export declare function PluginProvider({ framework, children }: {
+    framework: RendererFramework;
+    children: ReactNode;
+}): React.ReactElement;
+export declare function usePluginFramework(): RendererFramework;
+interface BoundaryProps {
+    owner: string;
+    children: ReactNode;
+    fallback?: (error: Error, reset: () => void) => ReactNode;
+}
+/** Isolates a plugin's UI: a throwing component renders a small fallback and is reported to the runtime. */
+export declare class PluginErrorBoundary extends Component<BoundaryProps & {
+    framework: RendererFramework;
+}, {
+    error: Error | null;
+}> {
+    state: {
+        error: Error | null;
+    };
+    static getDerivedStateFromError(error: Error): {
+        error: Error;
+    };
+    componentDidCatch(error: Error, _info: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+/** Wraps plugin-provided UI: error boundary + `data-fluxplugin` attribute (used by scoped styles). */
+export declare function PluginBoundary({ owner, children }: {
+    owner: string;
+    children: ReactNode;
+}): React.ReactElement;
+export interface PluginSlotProps {
+    name: string;
+    /** Host default content: kept, wrapped, or replaced depending on plugin contributions. */
+    children?: ReactNode;
+    /** Props handed to every contributed component. */
+    props?: Record<string, unknown>;
+}
+/**
+ * Declares an extension point in the host UI.
+ * `before`/`prepend` contributions render above the default content, `after`/`append` below it and
+ * a `replace` contribution takes its place.
+ */
+export declare function PluginSlot({ name, children, props }: PluginSlotProps): React.ReactElement;
+/** Data contributions to a declarative extension point (`ui.extend("dashboard", { toolbar: [...] })`). */
+export declare function useExtensionItems<T = unknown>(point: string, key: string): T[];
+export declare function usePlugin(id: string): PluginInfo | undefined;
+export declare function usePlugins(): PluginInfo[];
+/** Reactive per-plugin state (same store as `ctx.state` inside the plugin). */
+export declare function usePluginState<T>(pluginId: string, key: string, initial: T): [T, (v: T | ((prev: T) => T)) => void];
+/**
+ * Subscribes to an event. Looks at the renderer event bus *and* at pushes from the main process
+ * (`ctx.ipc.send(channel, payload)` and broadcast events). Returns the latest payload.
+ */
+export declare function usePluginEvent<T = unknown>(name: string, onEvent?: (payload: T) => void): T | undefined;
+export declare function usePluginCommand<R = unknown>(id: string): {
+    run: (...args: unknown[]) => Promise<R>;
+    available: boolean;
+    title?: string;
+};
+export declare function usePluginService<T = unknown>(name: string): T | undefined;
+export interface InvokeState<O> {
+    data: O | undefined;
+    error: Error | undefined;
+    loading: boolean;
+}
+/** Calls an IPC endpoint (by name or shared contract) with loading/error state. */
+export declare function usePluginIPC<I = unknown, O = unknown>(endpoint: string | IpcContract<I, O>, opts?: {
+    caller?: string;
+}): InvokeState<O> & {
+    call: (input?: I) => Promise<O>;
+};
+/** Current route match: params, breadcrumbs and route meta. */
+export { usePluginRoute } from "./router.js";
+export declare function usePluginConfig<T extends Record<string, any> = Record<string, any>>(pluginId: string): {
+    config: T | undefined;
+    loading: boolean;
+    error: Error | undefined;
+    set: PluginConfig<T>["set"];
+    reset: PluginConfig<T>["reset"];
+};
+/**
+ * Mirrors the style registry into the document: `<style>` for inline css, `<link>` for hrefs.
+ * Disabling/reloading a plugin removes or replaces its styles because the registry entries disappear.
+ */
+export declare function StyleHost(): null;

package/dist/types/react/http-bridge.d.ts

@@ -0,0 +1,10 @@
+import type { FluxBridge } from "../core/index.js";
+export declare class HttpBridgeError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Bridge over HTTP + Server-Sent Events, for running the renderer in a plain browser against `attachHttp()`
+ * (development, headless E2E tests, screenshots). In Electron the preload bridge is used instead.
+ */
+export declare function createHttpBridge(baseUrl?: string): FluxBridge;

package/dist/types/react/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./runtime.js";
+export * from "./components.js";
+export * from "./router.js";
+export * from "./palette.js";
+export { baseCss } from "./base-css.js";
+export * from "./http-bridge.js";

package/dist/types/react/palette.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+/** Global keybindings: runs the command bound to the pressed shortcut. `Mod` = Ctrl (Win/Linux) or Cmd (macOS). */
+export declare function useKeybindings(opts?: {
+    enabled?: boolean;
+}): void;
+/** Searchable command palette (opens with Mod+K, or controlled through `open`). */
+export declare function CommandPalette({ open, onClose }: {
+    open?: boolean;
+    onClose?: () => void;
+}): React.ReactElement | null;

package/dist/types/react/router.d.ts

@@ -0,0 +1,47 @@
+import React, { type ComponentType, type ReactNode } from "react";
+import { type Breadcrumb, type RouteMatch, type RouteParams } from "../core/index.js";
+export declare function navigate(to: string, opts?: {
+    replace?: boolean;
+}): void;
+export declare function useLocation(): string;
+export declare function useNavigate(): typeof navigate;
+export declare function Link({ to, children, ...rest }: {
+    to: string;
+    children: ReactNode;
+} & React.AnchorHTMLAttributes<HTMLAnchorElement>): React.ReactElement;
+interface RouteState {
+    match: RouteMatch<any> | undefined;
+    params: RouteParams;
+    breadcrumbs: Breadcrumb[];
+    path: string;
+}
+/**
+ * Current route (params, breadcrumbs, match). Works anywhere under `PluginProvider` — e.g. a header rendering
+ * breadcrumbs outside `<PluginRoutes>` — because it derives from the location and the route registry.
+ */
+export declare function usePluginRoute(): RouteState;
+export declare const useParams: () => RouteParams;
+export declare function Breadcrumbs({ separator }: {
+    separator?: ReactNode;
+}): React.ReactElement | null;
+export interface PluginRoutesProps {
+    notFound?: ReactNode;
+    forbidden?: (reason: string) => ReactNode;
+    loading?: ReactNode;
+    /** Layout used when a route does not name one. */
+    defaultLayout?: ComponentType<{
+        children: ReactNode;
+    }>;
+}
+/**
+ * Renders the route matching the current location from the dynamic route registry.
+ * Plugins can add routes at any time; the router re-renders automatically. Routes owned by lazily-activated
+ * plugins (`onRoute:` activation events) trigger activation on first navigation.
+ */
+export declare function PluginRoutes({ notFound, forbidden, loading, defaultLayout: DefaultLayout }: PluginRoutesProps): React.ReactElement;
+/** Menu entries for a location with active-route highlighting (sidebar, toolbar...). */
+export declare function useMenu(location: import("../core/index.js").MenuLocation): {
+    items: import("../core/registry.js").MenuItemDefinition[];
+    run: (item: import("../core/index.js").MenuItemDefinition) => Promise<unknown> | undefined;
+};
+export {};

package/dist/types/react/runtime.d.ts

@@ -0,0 +1,99 @@
+import { PluginManager, type Bootstrap, type FluxBridge, type IpcContract, type IpcErrorPayload, type Permission, type PluginConfig, type PluginInfo, type PluginManagerOptions, type PreloadApiSpec, type RegistryEntryLike, type RendererPluginDescriptor } from "../core/index.js";
+export declare class RemoteError extends Error {
+    readonly payload: IpcErrorPayload;
+    constructor(payload: IpcErrorPayload);
+    get code(): string;
+}
+/** Typed client for the `flux.plugins.*` management API served by the main process. */
+export declare class PluginsClient {
+    private readonly bridge;
+    constructor(bridge: FluxBridge);
+    private call;
+    list: () => Promise<PluginInfo[]>;
+    enable: (id: string) => Promise<PluginInfo[]>;
+    disable: (id: string) => Promise<PluginInfo[]>;
+    reload: (id: string) => Promise<PluginInfo[]>;
+    grant: (id: string, permission: Permission) => Promise<PluginInfo>;
+    revoke: (id: string, permission: Permission) => Promise<PluginInfo>;
+    uninstall: (id: string) => Promise<PluginInfo[]>;
+    search: (query?: string) => Promise<RegistryEntryLike[]>;
+    updates: () => Promise<RegistryEntryLike[]>;
+    install: (entry: RegistryEntryLike) => Promise<{
+        id: string;
+        version: string;
+    }>;
+    update: (entry: RegistryEntryLike) => Promise<{
+        id: string;
+        version: string;
+    }>;
+    rollback: (id: string, version?: string) => Promise<{
+        id: string;
+        version: string;
+    }>;
+    configGet: <T = Record<string, unknown>>(id: string) => Promise<T>;
+    configSet: <T = Record<string, unknown>>(id: string, patch: Partial<T>) => Promise<T>;
+    configReset: <T = Record<string, unknown>>(id: string) => Promise<T>;
+    configSchema: (id: string) => Promise<import("../core/schema.js").SchemaDescription | null>;
+    logs: (id?: string) => Promise<import("../core/common.js").LogEntry[]>;
+    diagnostics: (id: string) => Promise<{
+        info: PluginInfo;
+        logs: import("../core/index.js").LogEntry[];
+        contributions: Record<string, number>;
+    }>;
+}
+export interface RendererFrameworkOptions {
+    bridge: FluxBridge;
+    /**
+     * How to import a plugin's renderer entry. Defaults to a dynamic `import(url)`.
+     * Hosts using a bundler can map ids to static imports (e.g. `import.meta.glob`) for dev.
+     */
+    importPlugin?: (url: string, descriptor: RendererPluginDescriptor) => Promise<unknown>;
+    /** Called when a plugin component keeps crashing; defaults to disabling it in main + renderer. */
+    maxRenderErrors?: number;
+    manager?: Partial<PluginManagerOptions>;
+}
+/**
+ * The renderer half of the framework. The main process stays the source of truth for *which* plugins exist, are
+ * enabled and which permissions were granted; the renderer mirrors that state (`sync`) and runs the renderer
+ * entries inside its own `PluginManager` (runtime = "renderer").
+ */
+export declare class RendererFramework {
+    private readonly opts;
+    readonly bridge: FluxBridge;
+    readonly client: PluginsClient;
+    readonly manager: PluginManager;
+    private readonly permissions;
+    private revision;
+    private bootstrap;
+    private syncing;
+    private renderErrors;
+    private unsubscribers;
+    private storeListeners;
+    private _storeVersion;
+    constructor(opts: RendererFrameworkOptions);
+    /** `useSyncExternalStore` plumbing for the bootstrap-derived view (plugin list etc.). */
+    get storeVersion(): number;
+    subscribe: (l: () => void) => (() => void);
+    private touch;
+    get currentBootstrap(): Bootstrap | undefined;
+    /** Fetches the bootstrap, activates enabled plugins and starts listening for changes. */
+    start(): Promise<void>;
+    stop(): void;
+    private hotReload;
+    private cacheBust;
+    /** Mirrors main-process state into the renderer manager. Calls are serialized. */
+    sync(force?: boolean): Promise<void>;
+    private reconcile;
+    private load;
+    /** Called by plugin error boundaries. Repeated render failures disable the plugin. */
+    reportRenderError(pluginId: string, error: unknown): void;
+    /** Builds `window.plugins.<ns>.<member>` from the preload manifest. Rebuilt on every sync. */
+    private installWindowPlugins;
+    /** Config handle usable from React (mirrors ctx.config through the management API). */
+    configOf<T extends Record<string, any>>(id: string): Pick<PluginConfig<T>, "get" | "set" | "reset">;
+}
+/** Generates the object behind `window.plugins` from a preload manifest. Functions only; no references to Node. */
+export declare function buildPluginApis(bridge: FluxBridge, spec: Record<string, PreloadApiSpec>): Record<string, Record<string, (...args: any[]) => any>>;
+/** Shares singletons (React, the runtime...) with plugin bundles, which import them from `globalThis.__FLUXPLUGIN_SHARED__`. */
+export declare function installSharedModules(modules: Record<string, unknown>): void;
+export type { IpcContract };

package/docs/ARCHITECTURE.md

@@ -0,0 +1,31 @@
+# Architecture
+
+**Single source of truth = main process.** `MainFramework` discovers/validates plugins, persists enabled state and permission
+grants, owns IPC handlers. The renderer mirrors that via `flux:bootstrap` and runs renderer entries in its own `PluginManager`
+(`runtime: "renderer"`). Same `fluxplugin` code runs on both sides.
+
+## Lifecycle (per plugin)
+`discovered → validated → loaded → initialized → activated → ready → deactivated → unloaded` (+ `disabled`, `error`).
+Every phase has a timeout. A failure rolls back everything the plugin registered (ownership sweep), is logged, and never
+reaches other plugins. 3 failures in 60 s auto-disable the plugin (persisted). Dependencies activate first and deactivate last;
+cycles, missing deps and version mismatches block activation with a precise reason.
+
+## Lazy activation
+`activationEvents`: `onStartup`, `*`, `onCommand:<id>`, `onRoute:<pattern>`, `onEvent:<pattern>`, `onService:<name>`,
+`onSlot:<name>`, `onIPC:<name>`. Statically declared `contributes.commands/menus` appear (as proxies) before the plugin loads.
+
+## Extension surface (`PluginContext`)
+events (typed, wildcard, priority, cancel) · hooks (`validate/before/around/transform/after/filter`) · commands (palette,
+keybindings) · routes (params, lazy, layouts, guards, breadcrumbs, auto menu) · menus · UI slots (`before/after/replace/
+append/prepend`) · declarative extension points (host-schema-validated data) · services · IPC (schema-validated, shared
+contracts) · preload APIs (data-only, → `window.plugins.<ns>`) · storage · config (schema, defaults, migrations) · state ·
+styles (removed on disable) · host APIs (`host.provide`, permission-gated).
+
+## Why `window.plugins` is built in the renderer
+`contextBridge` exposes objects once at preload time; plugins come and go at runtime. The preload exposes only `window.__fluxplugin`
+(5 functions); the renderer builds the frozen `window.plugins` from the preload manifest on every change.
+
+## Plugin bundles
+`fluxplugin build` (esbuild) rewrites `react`, `@epf/*` imports to `globalThis.__FLUXPLUGIN_SHARED__` so there is exactly one
+React/runtime instance. Hosts call `installSharedModules({...})` (see `examples/host/src/renderer.tsx`).
+Renderer entries load via `fluxplugin://<id>/…` (Electron) or `/@plugins/<id>/…` (web mode); `main`/`plugin.json` are never served.

package/docs/PLUGIN-AUTHORS.md

@@ -0,0 +1,11 @@
+# Plugin authors
+
+1. `fluxplugin create my-plugin -t basic|dashboard|backend`
+2. Edit `plugin.json` (id, version, `activationEvents`, `permissions`, `dependencies`, `engines`) and `src/main.ts`, `src/renderer.tsx`, `src/styles/*.css`.
+3. `fluxplugin dev` → host hot-reloads. `validate` → `package --sign-key key` → `<id>-<version>.tgz`.
+4. Install: `fluxplugin install my.tgz --dir plugins`, via the Plugin Manager UI, or any `PluginRegistry`.
+
+Rules: register everything through `ctx`/declarative fields (auto-cleaned); clean timers in `ctx.lifecycle.onDeactivate`;
+declare every permission you use; version with semver and declare `engines["fluxplugin"]`.
+Hooks: `before.<op>` / `after.<op>` / `around.<op>` / `transform.<op>` / `validate.<op>` / `filter.<name>`.
+Global typing: `declare module "fluxplugin" { interface PluginApis { stats: {...} } }` then `pluginApi("stats")`.

package/docs/RELEASE.md

@@ -0,0 +1,20 @@
+# Publishing & verifying a release
+
+```bash
+pnpm install
+pnpm typecheck && pnpm test         # 121 tests
+pnpm build                          # dist/ (ESM, shared chunks) + dist/types (.d.ts)
+npm pack                            # fluxplugin-1.0.0.tgz — inspect with `tar tzf`
+
+# Verify like a user, before publishing (offline-safe: installs the tarball):
+export ELECTRON_SKIP_BINARY_DOWNLOAD=1
+mkdir /tmp/t && cd /tmp/t && npm init -y && npm i /path/to/fluxplugin-1.0.0.tgz
+FLUXPLUGIN_SPEC=file:/path/to/fluxplugin-1.0.0.tgz npx fluxplugin init my-app
+cd my-app && npm install && npm run build && npm run dev:web
+
+# Publish (both packages; `fluxplugin` first):
+npm publish                          # in the repo root  → fluxplugin
+cd create-fluxplugin && npm publish  # → create-fluxplugin  (enables `npm create fluxplugin@latest`)
+```
+Check the names are free on npm first (`npm view fluxplugin`); if not, use a scope (`@you/fluxplugin`) and
+search/replace the package name and `SHARED_MODULES` ids in `src/cli/shared-modules.ts`.

package/docs/SECURITY.md

@@ -0,0 +1,18 @@
+# Security model (honest version)
+
+**What is enforced**
+* Renderer ↔ main: sandboxed preload exposes only `window.__fluxplugin`. The renderer may call **only** channels a plugin explicitly
+  exposed via `preload.expose`, host allow-listed channels, and `flux.plugins.*` (disable with `allowManagement:false`).
+* IPC input/output validated by schema; stack traces never cross the boundary; `flux.*` names are reserved.
+* Permissions are declared in the manifest, granted by the host (`requireApproval:true` → nothing until the user approves),
+  checked on every scoped API, persisted, and revocable live. Host APIs can be permission-gated.
+* Integrity: sha256 of entry files in `integrity`; ed25519 manifest signatures with trusted keys (`trustedKeys`, `requireSignature`).
+* Archives: path-traversal-safe extraction; HTTP registry checksums verified; asset protocol rejects traversal, manifest and main entry.
+* Crash isolation: timeouts, rollback, error boundaries, auto-disable.
+
+**What is NOT enforced — do not rely on it**
+* Plugin `main` code runs in the Electron main process with full Node access. Permissions are an API contract, **not a sandbox**:
+  a malicious plugin can `require("fs")`. Only install plugins you trust; use signatures + `requireSignature`.
+* Renderer plugin code shares the host page's JS realm; it can reach `window.__fluxplugin` and the management API.
+  For untrusted plugins you need iframe/utility-process isolation (not implemented).
+* `@scope` scoped styles need Chromium ≥ 118.