fluxplugin 1.0.0 → 1.0.2

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

@@ -0,0 +1,53 @@
+import React, { type ReactNode } from "react";
+import type { RendererFramework } from "./runtime.js";
+export type ThemeMode = "light" | "dark" | "system";
+export interface ThemeDefinition {
+    id: string;
+    label: string;
+    /** Whether this theme is dark (drives `data-theme` and native overlay colours). */
+    dark?: boolean;
+    /** CSS custom properties, e.g. `{ "--flux-accent": "#e11d48", "--flux-bg": "#fff" }`. */
+    tokens: Record<string, string>;
+}
+export interface SearchResult {
+    id: string;
+    title: string;
+    subtitle?: string;
+    group?: string;
+    run: () => void | Promise<void>;
+}
+export interface SearchProvider {
+    id: string;
+    label: string;
+    search: (query: string) => SearchResult[] | Promise<SearchResult[]>;
+}
+/** Declares the extension points used by the built-in theme and title-bar components. Call before `framework.start()`. */
+export declare function declareHostPoints(framework: RendererFramework): void;
+interface ThemeCtx {
+    mode: ThemeMode;
+    setMode(m: ThemeMode): void;
+    themeId: string | undefined;
+    setThemeId(id: string | undefined): void;
+    resolved: "light" | "dark";
+    themes: ThemeDefinition[];
+    toggle(): void;
+}
+/**
+ * Light / dark / system modes plus themes contributed by plugins (extension point `theme`).
+ * Applies `data-theme` and the theme's CSS variables on <html>, persists the choice, and reports the resolved
+ * colours so the host can update the native window controls (`onResolved`).
+ */
+export declare function ThemeProvider({ children, storageKey, onResolved }: {
+    children: ReactNode;
+    storageKey?: string;
+    onResolved?: (r: {
+        dark: boolean;
+        bg: string;
+        fg: string;
+        surface: string;
+    }) => void;
+}): React.JSX.Element;
+export declare function useTheme(): ThemeCtx;
+/** Sun/moon button; with plugin themes available it also offers a small picker. */
+export declare function ThemeSwitcher(): React.ReactElement;
+export {};

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

@@ -0,0 +1,28 @@
+import React, { type ReactNode } from "react";
+/** Application menu (File, Edit, View…) built from `menus` registered with `location: "application"`. Plugins add to it. */
+export declare function AppMenuBar(): React.ReactElement | null;
+/** Search box: commands, pages, and results from `titlebar.searchProviders` contributed by plugins. */
+export declare function SearchBox({ placeholder }: {
+    placeholder?: string;
+}): React.ReactElement;
+export declare function NotificationBell(): React.ReactElement;
+/** Transient toasts for new notifications (top-right, under the title bar). */
+export declare function ToastHost(): React.ReactElement;
+export interface TitleBarProps {
+    title?: string;
+    logo?: ReactNode;
+    searchPlaceholder?: string;
+    /** Hide parts you do not need. */
+    show?: {
+        menu?: boolean;
+        search?: boolean;
+        notifications?: boolean;
+        theme?: boolean;
+    };
+}
+/**
+ * Custom window title bar that adapts to the OS: macOS keeps the native traffic lights (space is reserved on the left),
+ * Windows/Linux keep native window buttons through the window-controls overlay (space reserved on the right).
+ * Layout: [logo · title · menu bar] [search] [slot titlebar.right · theme · notifications].
+ */
+export declare function TitleBar({ title, logo, searchPlaceholder, show }: TitleBarProps): React.ReactElement;

package/docs/CUSTOMIZING.md

@@ -0,0 +1,257 @@
+# Customizing your app and its API
+
+This guide shows, step by step, how to **extend what plugins can do** in your app: add your own APIs, custom
+permissions, hooks, a custom title/menu bar, search, notifications, themes, icons and Tailwind.
+Everything below lives in the `src/app/` folder that `fluxplugin init` generated.
+
+```
+src/app/shared/     names used by both processes            (constants.ts, types.ts)
+src/app/main/       Electron side                           (framework.ts, operations.ts, window.ts, window-api.ts)
+src/app/renderer/   React side                              (bootstrap.ts, extension-points.ts, menus.ts, shell/, pages/ …)
+```
+
+**The mental model.** Your app *offers* extension surfaces; plugins *contribute* to them; nothing is patched.
+
+| You want plugins to… | You offer… | Plugin uses… |
+|---|---|---|
+| add a screen | nothing (routes are open) | `routes`, `meta.menu` |
+| add a button/widget in your UI | a `<PluginSlot name="x" />` | `components: [{ slot: "x", component }]` |
+| add *data* to a list (toolbar actions, tabs…) | an extension point + schema | `extensions: [{ point, contribution }]` |
+| react to / change what your app does | a hook operation (`hooks.run`) or an event (`events.emit`) | `hooks`, `events` |
+| call your app's features | a host API (`manager.provide`) | `ctx.host.api("name")` |
+| talk to the main process | an IPC handler | `ipc`, `preload` |
+
+---
+
+## 1. Add your own API for the renderer (host operation)
+
+A *host operation* is a function in the main process that your UI calls. Wrap it in a **hook** so plugins can validate,
+change or veto it without touching your code.
+
+**`src/app/shared/constants.ts`** — name it once:
+```ts
+export const CHANNELS = { createItem: "host.item.create", renameItem: "host.item.rename" } as const;
+export const OPERATIONS = { createItem: "item.create", renameItem: "item.rename" } as const;
+```
+
+**`src/app/main/operations.ts`** — implement it (input is validated by the schema):
+```ts
+import { s } from "fluxplugin";
+fw.manager.ipc.handle(
+  CHANNELS.renameItem,
+  (input: { id: string; name: string }) =>
+    fw.manager.hooks.run(OPERATIONS.renameItem, input, (i) => db.rename(i.id, i.name)),   // ← plugins can hook here
+  "host",
+  { input: s.object({ id: s.string(), name: s.string({ min: 1 }) }) },
+);
+```
+
+**`src/app/main/framework.ts`** — allow the renderer to call it (the renderer can call *only* allow-listed channels):
+```ts
+allowedRendererChannels: [CHANNELS.createItem, CHANNELS.renameItem],
+```
+
+**`src/app/renderer/services/items.ts`** — one place that knows the channel:
+```ts
+renameItem: (bridge, id, name) => bridge.invoke(CHANNELS.renameItem, { id, name }),
+```
+
+A plugin can now change your operation **without** editing your app:
+```ts
+// plugin main entry
+export default definePlugin({
+  hooks: [
+    { name: "before.item.rename",    handler: (ctx) => { ctx.input = { ...ctx.input, name: ctx.input.name.trim() }; } },
+    { name: "validate.item.rename",  handler: (ctx) => { if (ctx.input.name === "admin") ctx.cancel("reserved name"); } },
+    { name: "transform.item.rename", handler: (ctx) => ({ ...ctx.result, renamedBy: "my-plugin" }) },
+    { name: "after.item.rename",     handler: (ctx) => void audit(ctx.input) },   // errors here never break the operation
+  ],
+});
+```
+Hook kinds: `validate` → `before` → `around` (middleware) → *your function* → `transform` → `after`. Plus `filter.<name>`
+for value pipelines (`await fw.manager.hooks.filter("menu.items", items)`). Plugins use `priority` to order themselves.
+
+## 2. Give plugins controlled access to your app (host APIs + custom permissions)
+
+Use this when a plugin needs *your* services (database, billing, files…), not just hooks.
+
+```ts
+// main/framework.ts
+fw.manager.provide(
+  "billing",                                              // name
+  ({ pluginId }) => ({                                    // factory: called per plugin, so you know who is asking
+    invoices: () => db.invoices.list({ requestedBy: pluginId }),
+  }),
+  "x.billing.read",                                       // permission required (custom permissions start with "x.")
+);
+```
+```jsonc
+// plugin.json
+{ "permissions": ["x.billing.read"] }
+```
+```ts
+// plugin code
+const billing = ctx.host.api<{ invoices(): Promise<Invoice[]> }>("billing");
+```
+* Without the permission the call throws `PermissionDeniedError` and the plugin is rolled back.
+* With `requireApproval: true` (framework.ts) users must approve each permission in **Plugins → Details**; they can revoke later, live.
+* Built-in permissions: `ipc services events hooks commands routes menus ui styles storage notifications network filesystem.read filesystem.write database window clipboard shell`.
+  *Only the framework's own APIs check them* — `network`, `filesystem.*` etc. are yours to enforce inside your host APIs.
+
+## 3. Events, services and slots
+
+```ts
+fw.manager.events.emit("item.created", item, "host");                  // host → plugins (listener: ctx.events.on / `events: []`)
+fw.manager.services.register("clock", { now: () => Date.now() }, "host"); // plugins: ctx.services.get("clock")
+```
+**Slots** (components) — declare by rendering one; plugins inject (`mode`: `before | after | replace | append | prepend`):
+```tsx
+<PluginSlot name="dashboard.after" props={{ userId }} />            // host
+// plugin:  components: [{ slot: "dashboard.after", component: Widget, priority: 10 }]
+```
+**Extension points** (validated data) — declare in `renderer/extension-points.ts`, read with a hook:
+```ts
+framework.manager.extensionPoints.declare({ name: "reports", contributions: { exporters: s.object({ id: s.string(), label: s.string(), run: s.fn() }) } });
+const exporters = useExtensionItems<Exporter>("reports", "exporters");   // host
+// plugin:  extensions: [{ point: "reports", contribution: { exporters: [{ id: "pdf", label: "PDF", run }] } }]
+```
+Declare points **before** `framework.start()` (bootstrap.ts does). Bad contributions are rejected with a clear message.
+
+---
+
+## 4. The custom title bar & menu bar
+
+`<TitleBar />` replaces Electron's native menu. It adapts to the OS:
+
+| | macOS | Windows / Linux |
+|---|---|---|
+| native window buttons | traffic lights stay (`titleBarStyle: "hiddenInset"`), the bar leaves 82 px on the left | min/max/close stay on the right (`titleBarOverlay`), the bar leaves their width free via `env(titlebar-area-width)` |
+| native menu | minimal one (so ⌘C/⌘V/⌘Q work) | none (`Menu.setApplicationMenu(null)`) |
+| shortcut labels | `⌘⇧R` | `Ctrl+Shift+R` |
+| overlay colour | n/a | follows the theme (`host.window.setTitleBarOverlay`) |
+
+Layout: **[logo · title · menu bar] [search] [slot `titlebar.right` · theme · notifications 🔔]**.
+All of it is in `renderer/shell/AppShell.tsx`; hide or replace parts:
+```tsx
+<TitleBar title="My App" logo={<img src={logo} />} show={{ search: false }} searchPlaceholder="Find anything…" />
+```
+or compose your own bar from the parts: `AppMenuBar`, `SearchBox`, `NotificationBell`, `ThemeSwitcher`, `PluginSlot`.
+
+### Menus (File / Edit / View …)
+Menus are data in `renderer/menus.ts`. Top-level entries have `children`; items run a **command** (shortcut shown automatically
+from the command's `keybinding`) or open a **route**:
+```ts
+commands.register({ id: "file.new", title: "New project", category: "File", keybinding: "Mod+N", execute: newProject }, "host");
+menus.register({ id: "app.file", location: "application", label: "File", order: 0, children: [
+  { id: "app.file.new", label: "New project", command: "file.new" },
+  { id: "app.file.sep", label: "", separator: true },
+  { id: "app.file.settings", label: "Settings", path: "/settings" },
+] }, "host");
+```
+A **plugin** adds a whole menu *or* items to yours (same `id` namespace; use `order` to place it):
+```ts
+definePlugin({ menus: [{ id: "p.menu", location: "application", label: "Reports", order: 30,
+  children: [{ id: "p.menu.run", label: "Run report", command: "p.run" }] }] })
+```
+Other menu locations: `sidebar`, `toolbar`, `commandPalette`, `context`, `tray`, `settings` (read them with `useMenu("toolbar")`).
+Use `when: () => boolean` to hide items dynamically.
+
+### Search bar
+The box searches **commands**, **sidebar pages** and anything plugins contribute:
+```ts
+// plugin
+extensions: [{ point: "titlebar", contribution: { searchProviders: [{
+  id: "tickets", label: "Tickets",
+  search: async (q) => (await api.find(q)).map((t) => ({ id: t.id, title: t.title, subtitle: "ticket", run: () => (location.hash = "#/tickets/" + t.id) })),
+}] } }]
+```
+`Ctrl/Cmd+F` focuses it, `↑ ↓ Enter` navigate. A provider that throws is ignored. Command palette: `Ctrl/Cmd+K`.
+
+### Notifications (bell + toasts)
+```ts
+ctx.notifications.push({ title: "Export finished", body: "report.pdf", level: "success",       // plugin (permission "notifications")
+  actions: [{ label: "Open", command: "reports.open", args: ["report.pdf"] }], timeoutMs: 8000 });   // 0 = bell only
+framework.manager.notifications.push({ title: "Saved" });                                           // host
+```
+Plugins running in the **main process** can push too; they are forwarded to the window. Unread count, history, dismiss and
+"clear all" are built in. These are *in-app* notifications; for OS-level ones call Electron's `Notification` from a host operation.
+
+### Your own window operations
+`main/window-api.ts` shows the pattern (BrowserWindow needed): register an IPC handler, add its channel to
+`allowedRendererChannels`, call it from a `renderer/services/*.ts` file. Example: maximize, always-on-top, zoom.
+
+---
+
+## 5. Themes, colours and icons
+
+Everything is styled with CSS variables, so one switch re-themes the app **and** plugins:
+
+| Variable | Meaning | Variable | Meaning |
+|---|---|---|---|
+| `--flux-bg` | page background | `--flux-accent` | brand/selection colour |
+| `--flux-fg` | text | `--flux-accent-fg` | text on accent |
+| `--flux-surface` | bars, cards, panels | `--flux-muted` | secondary text |
+| `--flux-border` | lines | `--flux-ok / -warn / -danger` | status colours |
+
+Light / dark / system works out of the box (`<ThemeProvider>` in `providers/AppProviders.tsx`, button in the title bar,
+choice persisted). **Plugins can ship themes**:
+```ts
+extensions: [{ point: "theme", contribution: { themes: [{
+  id: "ocean", label: "Ocean", dark: true,
+  tokens: { "--flux-bg": "#06202b", "--flux-surface": "#0a2c3a", "--flux-fg": "#e6f6ff", "--flux-border": "#14465a", "--flux-accent": "#22d3ee" },
+}] } }]
+```
+They appear in the title-bar picker. In code: `const { resolved, mode, setMode, themeId, setThemeId, themes } = useTheme();`.
+
+**Icons.** `<Icon name="search|bell|sun|moon|plug|settings|check|close|chevron|play|image|command" />` (24×24, `currentColor`) or
+`<Icon d="M…svg path…" />` for your own. Plugins have their own icon: `"icon": "./assets/icon.svg"` in `plugin.json`
+(shown in **Plugins**; png / svg / webp / jpg).
+
+## 6. Tailwind
+
+```bash
+npx fluxplugin init my-app --tailwindcss          # app preconfigured with Tailwind v4
+npx fluxplugin plugin new my-plugin --tailwindcss # plugin with its own compiled utilities
+```
+* `src/app/renderer/styles/tailwind.css` is compiled by `fluxplugin dev|build` into `dist/tailwind.css`.
+* Theme colours are mapped, so utilities follow light/dark/plugin themes: `bg-bg bg-surface text-fg text-muted border-border bg-accent`.
+* Dark variant: `dark:…` follows `data-theme="dark"`.
+* The app scans `plugins/*/dist` so classes used by bundled plugins are generated.
+* Plugins that users install **later** can't be scanned: create them with `--tailwindcss`, which ships a precompiled
+  `dist/tailwind.css` (utilities only, no reset) listed in `manifest.styles`. Plugin CSS is added when the plugin activates and
+  **removed when it is disabled**.
+* Need `npm install -D tailwindcss @tailwindcss/cli` if you add Tailwind to an existing app (then create `tailwind.css`).
+
+---
+
+## 7. The plugin "store page" (image, description, video)
+
+Each plugin gets a page in **Plugins → Details**, driven by `plugin.json` and its `README.md`:
+```jsonc
+{
+  "icon": "./assets/icon.svg",
+  "banner": "./assets/banner.png",
+  "screenshots": ["./assets/shot-1.png", "./assets/shot-2.png"],
+  "video": "https://www.youtube.com/watch?v=YOUR_ID",      // YouTube/Vimeo are embedded; other https links become a button
+  "readme": "./README.md",                                  // long description in Markdown (default README.md)
+  "categories": ["Productivity"], "keywords": ["reports"],
+  "links": { "docs": "https://…", "support": "https://…" },
+  "author": "Name", "license": "MIT"
+}
+```
+The README supports headings, lists, tables, code blocks, quotes, **bold**, *italic*, `code`, and https links.
+Raw HTML and images inside the README are **not** rendered (safety). Put images in `screenshots`/`banner`.
+Your app's CSP must allow the video hosts: `frame-src https://www.youtube-nocookie.com https://player.vimeo.com`
+(already in the generated `index.html`).
+
+## 8. Distributed plugins are JavaScript only
+
+Authors work in TypeScript (`src/`), but what is **installed and shipped** is only:
+`plugin.json`, `dist/` (built JS/CSS), `assets/`, `README.md`, `LICENSE`, `CHANGELOG`. `fluxplugin package` and every install
+through the Plugin Manager / registries copy *only* these files — never `src/`, `.ts/.tsx`, sourcemaps, `node_modules`, configs.
+Add `--sign-key` to sign the package (ed25519) and set `trustedKeys` + `requireSignature` in `framework.ts` to refuse the rest.
+
+## 9. Plugin stores (marketplace)
+
+Where *Plugins → Available* looks is your choice: the default GitHub store, your own catalog (HTTP/GitHub/local), or code of your own.
+Set it in `fluxplugin.config.json` → `"stores"`. Full guide — developing, publishing, running a store: **[STORE.md](STORE.md)**.

package/docs/PLUGIN-AUTHORS.md

@@ -1,11 +1,38 @@
 # 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")`.
+## 1. Create
+```bash
+npx fluxplugin plugin new my-plugin -t dashboard      # basic | dashboard | backend     (add --tailwindcss for Tailwind)
+cd plugins/my-plugin
+```
+You get `plugin.json`, `src/main.ts`, `src/renderer.tsx`, `src/styles/index.css`, `assets/icon.svg` and a detailed `README.md`.
+
+## 2. Develop (TypeScript)
+`npx fluxplugin dev` in the app rebuilds on save and the running app reloads your plugin. Imports come from the host,
+so there is one React and one runtime: `import { definePlugin, defineIPC, s } from "fluxplugin"` and
+`import { usePluginIPC, usePluginState } from "fluxplugin/react"`.
+
+Rules: register everything through `ctx` or the declarative fields (it is cleaned up automatically on disable);
+clear timers in `ctx.lifecycle.onDeactivate`; declare **every** permission you use; use `activationEvents`
+(`onStartup`, `onCommand:id`, `onRoute:/x`, `onService:x`, `onSlot:x`, `onIPC:x`, `onEvent:x`) to load lazily.
+
+## 3. Describe it (the plugin page)
+Fill `plugin.json` and `README.md` — users see them in **Plugins → Details**:
+`icon`, `banner`, `screenshots`, `video` (YouTube/Vimeo), `categories`, `keywords`, `links`, `author`, `license`, and a Markdown
+README (what it does, how to use it, permissions and why, changelog). See [CUSTOMIZING §7](CUSTOMIZING.md).
+
+## 4. Ship (JavaScript only)
+```bash
+npx fluxplugin validate .
+npx fluxplugin package . --out dist-packages --sign-key epf-signing.private.key
+# → com.acme.my-plugin-1.0.0.tgz   contains: plugin.json, dist/, assets/, README.md, LICENSE  — never src/ or .ts files
+```
+To **publish to the store** (GitHub): `npx fluxplugin publish` — see [STORE.md](STORE.md).
+Install: Plugin Manager (*Available*), `npx fluxplugin install <id>`, `install file.tgz`. Updates keep the previous version for rollback.
+
+## 5. What you can do
+Pages (`routes`, lazy, guards, layouts) · sidebar/menu-bar entries (`menus`) · commands & shortcuts · dashboard/any **slot**
+components · **extension points** (toolbar actions, search providers, themes) · hooks on host operations · events · services ·
+main-process IPC + `window.plugins.<ns>` · notifications · settings with auto-generated forms (`config`) · storage · styles.
+How the host *offers* these: [CUSTOMIZING](CUSTOMIZING.md). Typed `window.plugins`:
+`declare module "fluxplugin" { interface PluginApis { stats: { get(): Promise<Stats> } } }` then `pluginApi("stats").get()`.

package/docs/RELEASE.md

@@ -2,7 +2,7 @@
 
 ```bash
 pnpm install
-pnpm typecheck && pnpm test         # 121 tests
+pnpm typecheck && pnpm test         # ~138 tests
 pnpm build                          # dist/ (ESM, shared chunks) + dist/types (.d.ts)
 npm pack                            # fluxplugin-1.0.0.tgz — inspect with `tar tzf`
 

package/docs/SECURITY.md

@@ -10,6 +10,11 @@
 * 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.
 
+* Plugin pages: README Markdown is rendered without raw HTML or images; links must be https and open in the system browser; videos are
+  embedded only for YouTube (nocookie) / Vimeo through a sandboxed iframe allowed by the page CSP.
+* Distribution: only runtime files (`plugin.json`, `dist/`, `assets/`, README/LICENSE) are packaged or installed; sources never ship.
+* `npm audit fix --force` can silently jump Electron several majors — keep Electron updates deliberate (see TROUBLESHOOTING).
+
 **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`.

package/docs/STORE.md

@@ -0,0 +1,123 @@
+# Plugin stores: develop a plugin, publish it, install it
+
+A **store** is any place plugins are listed and downloaded from. fluxplugin ships three kinds, and **GitHub is the default**:
+
+| Store | You configure | How plugins get in | Best for |
+|---|---|---|---|
+| **GitHub topic** *(default)* | nothing | `fluxplugin publish` creates a release in *your own* repo; the repo topic `fluxplugin-plugin` makes it discoverable | open ecosystem, no approval needed |
+| **GitHub catalog** | `{ "type": "github", "repo": "acme/plugin-store" }` | pull requests to a repo containing `index.json` | curated / reviewed store |
+| **HTTP** | `{ "type": "http", "url": "https://plugins.acme.com/" }` | `fluxplugin store add` + upload the folder | company store, GitHub Pages, S3, CDN |
+| **Local** | `{ "type": "local", "path": "./store" }` | copy folders | offline / shared drive |
+
+Stores are listed in **`fluxplugin.config.json`** (`"stores"`). The same list is used by your **app** (*Plugins → Available*) and by the **CLI**
+(`fluxplugin search`, `fluxplugin install`). You can have several stores at once.
+
+---
+
+## A. Develop a plugin (5 minutes)
+
+```bash
+# inside your app, or anywhere
+npx fluxplugin plugin new weather -t backend         # basic | dashboard | backend   (add --tailwindcss if you like)
+cd plugins/weather
+npx fluxplugin dev                                    # rebuilds on save; the running app reloads the plugin
+```
+1. **Code** in `src/main.ts` (Electron side: IPC, services) and `src/renderer.tsx` (React: pages, widgets, menus). Learn the API in
+   [PLUGIN-AUTHORS](PLUGIN-AUTHORS.md); what the host offers is in [CUSTOMIZING](CUSTOMIZING.md).
+2. **Describe it** — this is your store page (*Plugins → Details*). Edit `plugin.json` and `README.md`:
+   ```jsonc
+   {
+     "id": "com.acme.weather",            // unique, lowercase, never changes
+     "name": "Weather", "version": "1.0.0",
+     "description": "Forecast widget for your dashboard.",
+     "author": "Acme", "license": "MIT",
+     "repository": "https://github.com/acme/weather-plugin",   // ← where `publish` will release it
+     "icon": "./assets/icon.svg",
+     "screenshots": ["./assets/shot-1.png"],
+     "video": "https://www.youtube.com/watch?v=YOUR_ID",
+     "categories": ["Productivity"], "keywords": ["weather"],
+     "permissions": ["ipc", "routes", "menus", "ui"],           // declare exactly what you use
+     "engines": { "fluxplugin": "^1.0.0" }
+   }
+   ```
+   `README.md` is rendered as the long description (headings, lists, tables, code, links; no raw HTML).
+3. **Check it**: `npx fluxplugin validate .` — then try it in your app. Remove dev leftovers; users only ever get `plugin.json`, `dist/`,
+   `assets/`, `README.md`, `LICENSE` — **never your TypeScript, `src/`, or `.map` files** (sourcemaps are only generated by `dev`).
+4. **Version it** with semver (`1.0.0` → `1.0.1` fix, `1.1.0` feature, `2.0.0` breaking). A published version can't be replaced.
+
+## B. Publish to the default store (GitHub)
+
+**Once**: create a *public* GitHub repository for the plugin (`github.com/acme/weather-plugin`), push your code, and create a token:
+GitHub → Settings → Developer settings → *Personal access tokens* → fine-grained, this repository, permissions **Contents: Read & write** and
+**Administration: Read & write** (needed only to add the topic). Export it:
+```bash
+export GITHUB_TOKEN=github_pat_xxx        # PowerShell:  $env:GITHUB_TOKEN="github_pat_xxx"
+```
+**Every release**:
+```bash
+npx fluxplugin publish --dry-run          # builds + packages, shows what would happen, touches nothing
+npx fluxplugin publish                    # does it
+```
+What `publish` does: builds the plugin (no sourcemaps) → creates `com.acme.weather-1.0.0.tgz` and `com.acme.weather-1.0.0.fluxplugin.json`
+(name, version, permissions, **sha256**) → creates the GitHub release `v1.0.0` → uploads both files → adds the topic `fluxplugin-plugin`.
+It refuses if the version already exists ("bump `version`"), the repo isn't reachable, or `description` / `icon` / `license` are missing.
+Add `--sign-key my.private.key` to sign the package (`npx fluxplugin keygen` creates the pair).
+
+New topics can take a few minutes to appear in GitHub search. Check with `npx fluxplugin search weather`.
+
+**Update**: change code → bump `version` → `npx fluxplugin publish`. Apps see it in *Plugins → Updates*; the previous version is kept for **rollback**.
+**Unpublish**: delete the release on GitHub (or remove the topic to hide the whole repository).
+
+**Automate with GitHub Actions** (publish when you push a tag):
+```yaml
+# .github/workflows/release.yml
+on: { push: { tags: ["v*"] } }
+permissions: { contents: write }
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci
+      - run: npx fluxplugin publish
+        env: { GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" }
+```
+(The built-in token can create releases but not edit topics; add the topic `fluxplugin-plugin` once in the repo settings.)
+
+## C. Install from the store
+
+* **In an app**: *Plugins → Available* lists plugins with their permissions; **Install**. Enabled automatically (or after the user approves permissions when your app uses `requireApproval`).
+* **CLI**: `npx fluxplugin search weather` · `npx fluxplugin install com.acme.weather` (or `@1.0.0`) · `npx fluxplugin install ./file.tgz`.
+* **Anonymous GitHub search is limited (60 requests/hour).** Set `GITHUB_TOKEN` (any token, no scopes) in the environment of the app or CLI to raise it.
+  The app caches results for a minute.
+
+## D. Run your own store
+
+```bash
+npx fluxplugin store init my-store                                   # creates my-store/index.json
+npx fluxplugin package ./weather --out .                             # → com.acme.weather-1.0.0.tgz
+npx fluxplugin store add com.acme.weather-1.0.0.tgz --dir my-store --base-url https://plugins.acme.com/
+```
+Upload the `my-store/` folder anywhere that serves static files, then add it to your app (and keep or drop the GitHub one):
+```jsonc
+// fluxplugin.config.json
+"stores": [
+  { "type": "http", "url": "https://plugins.acme.com/" },
+  { "type": "github", "topic": "fluxplugin-plugin" }
+]
+```
+* **Curated GitHub store**: put the same `my-store/` content in a repo `acme/plugin-store`, use `{ "type": "github", "repo": "acme/plugin-store" }`,
+  and review plugin submissions as pull requests that edit `index.json`.
+* **Code**: `new MainFramework({ stores: [...] })` or `registries: [new MyRegistry()]` — implement `PluginRegistry { name; search(query); fetch(entry, destDir) }` to talk to anything (npm, S3, your API).
+* Format of `index.json`: `{ "plugins": [{ "id", "name", "version", "description", "permissions", "url", "sha256" }] }` — `url` may be relative.
+
+## E. What protects your users
+
+* Downloads must be **https** (loopback http is allowed for local testing) and match the published **sha256**; entries without a checksum are refused.
+* Archives are extracted with path-traversal protection, size-limited (100 MB), and **sources, TypeScript, `.map` files and `node_modules` are deleted on install** even if a package contains them.
+* Permissions are shown **before** install; with `requireApproval: true` nothing runs until the user approves; they can revoke later.
+* Optional: `trustedKeys` + `requireSignature: true` in your `MainFramework` to accept only plugins signed by keys you trust.
+* Plugin `main` code is **not sandboxed** — a store is a trust decision. Use a curated store or signatures for untrusted ecosystems ([SECURITY](SECURITY.md)).
+* Limits today: public GitHub repositories only (private-repo downloads aren't supported yet).

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,35 @@
+# Troubleshooting
+
+## "Electron failed to install correctly"
+Your package manager blocked Electron's `postinstall` script (npm 11.16+/12 and pnpm 10 do this by default), so the binary was never
+downloaded. **`fluxplugin dev|start` now downloads it automatically.** To make installs clean:
+* the generated `package.json` already contains `"allowScripts": { "electron": true, "esbuild": true }` (npm) and
+  `"pnpm": { "onlyBuiltDependencies": ["electron", "esbuild"] }` (pnpm);
+* with an older project add those, or run `npx fluxplugin doctor`, or `node node_modules/electron/install.js`.
+* behind a proxy / in a restricted network: set `ELECTRON_MIRROR`.
+* Do **not** run `npm audit fix --force` on an app: it upgrades Electron across major versions on its own.
+
+## `fluxplugin doctor`
+Checks Node ≥ 20, the Electron binary (and repairs it), esbuild, the Tailwind CLI and the `allowScripts` setting.
+
+## Linux: "Running as root without --no-sandbox" / SUID sandbox
+`fluxplugin dev` detects it and starts Electron with `--no-sandbox`, telling you how to fix it properly:
+`sudo chown root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox`.
+
+## A plugin is "disabled" and I did not disable it
+A plugin that crashes 3 times within a minute (activation or rendering) is disabled **and the state is saved**. Open
+**Plugins → Details → Logs** to see why, fix it, then **Enable**.
+
+## Debugging Electron
+`FLUXPLUGIN_ELECTRON_ARGS="--remote-debugging-port=9222" npm run dev` then open `http://127.0.0.1:9222` in Chrome. In dev, `F12` toggles DevTools.
+
+## Plugin changes don't show
+`fluxplugin dev` rebuilds the host and every plugin in `plugins/` on save; plugins reload in the running app. If you work in a plugin
+folder outside the app, run `fluxplugin dev` there. Host changes in `src/app/main` need an app restart.
+
+## Store problems
+* **"GitHub rate limit reached"** — anonymous search is limited to 60 requests/hour. Set `GITHUB_TOKEN` (any token) for the app/CLI.
+* **My published plugin isn't found** — GitHub topics can take a few minutes; check the repo has the topic `fluxplugin-plugin`, is **public**,
+  and the latest release contains both the `.tgz` and the `.fluxplugin.json` files (`fluxplugin publish` creates them).
+* **"version X is already published"** — bump `version` in `plugin.json`; releases are immutable.
+* **"downloaded package does not match the published checksum"** — the file changed after publishing; publish a new version.

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "fluxplugin",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Plugin architecture for Electron + React + TypeScript. Build apps that others can extend: routes, menus, commands, UI slots, IPC, hooks, permissions — with a CLI.",
   "license": "MIT",
-  "author": "Cellsflux",
   "keywords": [
     "electron",
     "react",