fluxplugin 1.0.0 → 1.0.1

package/README.md

@@ -38,13 +38,25 @@ export default definePlugin({                      import { usePluginIPC } from
 ```
 More: [ARCHITECTURE](docs/ARCHITECTURE.md) · [SECURITY](docs/SECURITY.md) · [PLUGIN-AUTHORS](docs/PLUGIN-AUTHORS.md) · [RELEASE](docs/RELEASE.md)
 
+## What `fluxplugin init` generates
+All application code lives in `src/app`, in layers (`shared` → `main` / `preload` / `renderer`):
+```
+src/app/
+  shared/     constants.ts · types.ts            (depends on nothing)
+  main/       index.ts (Electron) · web.ts (browser) · framework.ts · operations.ts · window.ts · paths.ts
+  preload/    index.ts
+  renderer/   index.tsx · bootstrap.ts · extension-points.ts · routes.ts · App.tsx
+              providers/ · shell/ · pages/ · hooks/ · services/ · styles/
+plugins/      loaded at startup
+```
+
 ## Status — read this
-* **Verified:** 121 automated tests; typecheck strict; the packed tarball installed into a *freshly generated app*
-  (`init` → `npm install` → typecheck → `build` → run in browser mode); a Playwright E2E against that app with
-  3 plugins (menus, slots, extension points, hooks, validated IPC, push events, live enable/disable, palette, manager UI);
-  `plugin new` + `build` hot-loads into a running app.
-* **Not verified:** a real Electron binary (unavailable in the build sandbox). `main.ts`/`preload.ts` templates and
-  `attachElectron` follow the Electron API and are tested against fakes — expect small adjustments on first `npm run dev`.
-* **Not published:** the package is not on npm. Run the steps in `docs/RELEASE.md`; check the name is free first.
-* **Security:** plugin `main` code is not sandboxed (permissions are an API contract). Read `docs/SECURITY.md`.
-* **Not done:** per-plugin process isolation, hosted marketplace (only the `PluginRegistry` abstraction + local/HTTP), Tailwind wiring in the starter.
+* **Verified:** 121 tests; strict typecheck; the packed tarball installed into a freshly generated app
+  (`init` → `npm install` → typecheck → `build`); the generated app run **in real Electron 33** (under Xvfb, Linux) through
+  `fluxplugin dev`: window loads, preload bridge present, **no Node globals leak into the page**, plugin menus, hook-wrapped
+  host operation, live plugin disable — and in browser mode with a Playwright E2E (3 plugins).
+* **Not verified:** Windows and macOS (only Linux was available), packaging an installer (electron-builder/forge is not set up).
+* **Linux note:** if Electron's sandbox helper is not setuid-root (or you run as root) `fluxplugin dev` starts it with
+  `--no-sandbox` and tells you how to fix it. Extra flags: `FLUXPLUGIN_ELECTRON_ARGS="--remote-debugging-port=9222"`.
+* **Not published** on npm — see `docs/RELEASE.md`. **Security:** plugin `main` code is not sandboxed (see `docs/SECURITY.md`).
+* **Not done:** per-plugin process isolation, hosted marketplace (only `PluginRegistry` + local/HTTP), Tailwind wiring.

package/dist/cli.js

@@ -892,7 +892,7 @@ async function buildPlugin(root, watch = false, log2 = console.log) {
 
 // src/cli/host.ts
 import { spawn } from "node:child_process";
-import { promises as fs7 } from "node:fs";
+import { existsSync, promises as fs7, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import path8 from "node:path";
 import { build as build2, context as context2 } from "esbuild";
@@ -915,17 +915,25 @@ async function loadConfig(flags, cwd = process.cwd()) {
 // src/cli/host.ts
 var exists2 = (f) => fs7.access(f).then(() => true, () => false);
 async function isHostProject(cwd) {
-  return await exists2(path8.join(cwd, "fluxplugin.config.json")) || await exists2(path8.join(cwd, "src/renderer.tsx")) && await exists2(path8.join(cwd, "src/framework.ts"));
+  if (await exists2(path8.join(cwd, "fluxplugin.config.json"))) return true;
+  return await exists2(path8.join(cwd, "src/app/renderer/index.tsx")) || await exists2(path8.join(cwd, "src/renderer.tsx"));
 }
 var nodeBanner = { js: "import { createRequire as __r } from 'node:module'; const require = __r(import.meta.url);" };
+var pick = (cwd, ...rels) => {
+  for (const r of rels) if (existsSync(path8.join(cwd, r))) return path8.join(cwd, r);
+  return path8.join(cwd, rels[0]);
+};
 function hostBuilds(cwd, outDir, dev) {
   const common = { absWorkingDir: cwd, bundle: true, sourcemap: dev, logLevel: "warning", jsx: "automatic", define: { "process.env.NODE_ENV": JSON.stringify(dev ? "development" : "production") } };
-  const entry = (f) => path8.join(cwd, "src", f);
+  const renderer = pick(cwd, "src/app/renderer/index.tsx", "src/renderer.tsx");
+  const main = pick(cwd, "src/app/main/index.ts", "src/main.ts");
+  const preload = pick(cwd, "src/app/preload/index.ts", "src/preload.ts");
+  const web = pick(cwd, "src/app/main/web.ts", "src/web.ts");
   return [
-    { ...common, entryPoints: [entry("renderer.tsx")], outfile: path8.join(outDir, "renderer.js"), platform: "browser", format: "esm", target: "chrome120" },
-    { ...common, entryPoints: [entry("main.ts")], outfile: path8.join(outDir, "main.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
-    { ...common, entryPoints: [entry("preload.ts")], outfile: path8.join(outDir, "preload.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
-    { ...common, entryPoints: [entry("web.ts")], outfile: path8.join(outDir, "web.mjs"), platform: "node", format: "esm", target: "node20", external: ["electron"], banner: nodeBanner }
+    { ...common, entryPoints: [renderer], outfile: path8.join(outDir, "renderer.js"), platform: "browser", format: "esm", target: "chrome120" },
+    { ...common, entryPoints: [main], outfile: path8.join(outDir, "main.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
+    { ...common, entryPoints: [preload], outfile: path8.join(outDir, "preload.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
+    { ...common, entryPoints: [web], outfile: path8.join(outDir, "web.mjs"), platform: "node", format: "esm", target: "node20", external: ["electron"], banner: nodeBanner }
   ];
 }
 async function pluginDirs(cwd, pluginsDir) {
@@ -941,11 +949,12 @@ async function buildHost(cwd, opts = {}) {
   const cfg = await loadConfig({}, cwd);
   const outDir = path8.resolve(cwd, cfgFile.outDir ?? "dist");
   await fs7.mkdir(outDir, { recursive: true });
-  await fs7.copyFile(path8.join(cwd, "src/index.html"), path8.join(outDir, "index.html"));
+  await fs7.copyFile(pick(cwd, "src/app/renderer/index.html", "src/index.html"), path8.join(outDir, "index.html"));
   const disposers = [];
   const opts2 = hostBuilds(cwd, outDir, !!opts.watch);
   if (opts.watch) {
     const ctxs = await Promise.all(opts2.map((o) => context2(o)));
+    await Promise.all(ctxs.map((c) => c.rebuild()));
     await Promise.all(ctxs.map((c) => c.watch()));
     disposers.push(async () => void await Promise.all(ctxs.map((c) => c.dispose())));
   } else for (const o of opts2) await build2(o);
@@ -962,17 +971,115 @@ async function buildHost(cwd, opts = {}) {
 function electronBinary(cwd) {
   try {
     const p = createRequire(path8.join(cwd, "package.json"))("electron");
-    return typeof p === "string" ? p : void 0;
+    if (typeof p === "string" && existsSync(p)) return { bin: p };
+    return { error: "the Electron binary was not found" };
+  } catch (e) {
+    return { error: e.message.split("\n")[0] };
+  }
+}
+function needsNoSandbox(bin) {
+  if (process.platform !== "linux") return false;
+  if (process.getuid?.() === 0) return true;
+  try {
+    const st = statSync(path8.join(path8.dirname(bin), "chrome-sandbox"));
+    return !(st.uid === 0 && (st.mode & 2048) !== 0);
   } catch {
-    return void 0;
+    return false;
   }
 }
 function startApp(cwd, opts = {}) {
-  const bin = opts.web ? void 0 : electronBinary(cwd);
+  const log2 = opts.log ?? console.log;
   const env = { ...process.env, FLUXPLUGIN_PROJECT: cwd, ...opts.dev ? { FLUXPLUGIN_DEV: "1" } : {}, ...opts.port ? { PORT: String(opts.port) } : {} };
-  if (bin) return { child: spawn(bin, [path8.join(cwd, "dist/main.cjs")], { cwd, env, stdio: "inherit" }), mode: "electron" };
-  return { child: spawn(process.execPath, [path8.join(cwd, "dist/web.mjs")], { cwd, env, stdio: "inherit" }), mode: "web" };
+  if (opts.web) return { child: spawn(process.execPath, [path8.join(cwd, "dist/web.mjs")], { cwd, env, stdio: "inherit" }), mode: "web" };
+  const { bin, error } = electronBinary(cwd);
+  if (!bin) throw new Error(`cannot start Electron: ${error}.
+  Install it with:  npm install -D electron   (then re-run)
+  or run in a browser:  fluxplugin ${opts.dev ? "dev" : "start"} --web`);
+  const args = [...process.env["FLUXPLUGIN_ELECTRON_ARGS"]?.split(" ").filter(Boolean) ?? [], path8.join(cwd, "dist/main.cjs")];
+  if (needsNoSandbox(bin)) {
+    args.unshift("--no-sandbox");
+    log2("! Linux: Electron's sandbox helper is not configured (or you run as root) \u2192 starting with --no-sandbox.\n  To fix permanently: sudo chown root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox");
+  }
+  const started = Date.now();
+  const child = spawn(bin, args, { cwd, env, stdio: "inherit" });
+  child.on("exit", (code) => {
+    if (code && Date.now() - started < 5e3) log2(`Electron exited with code ${code} right after starting. Scroll up for its error, or try:  fluxplugin dev --web`);
+  });
+  return { child, mode: "electron" };
+}
+
+// src/cli/host-files.generated.ts
+var HOST_APP_FILES = {
+  "src/app/main/framework.ts": `import { MainFramework } from "fluxplugin/main";
+import { CHANNELS } from "../shared/constants";
+import { registerOperations } from "./operations";
+
+export interface FrameworkOptions {
+  pluginDirs: string[];
+  dataDir: string;
+  dev?: boolean;
+  assetUrl?: (id: string, rel: string) => string;
+}
+
+/** Creates the plugin framework. Shared by the Electron entry (index.ts) and the browser entry (web.ts). */
+export function createFramework(opts: FrameworkOptions): MainFramework {
+  const fw = new MainFramework({
+    pluginDirs: opts.pluginDirs,
+    dataDir: opts.dataDir,
+    hotReload: opts.dev,
+    assetUrl: opts.assetUrl,
+    requireApproval: false, // true \u2192 users must approve each plugin's permissions
+    allowedRendererChannels: [CHANNELS.createItem],
+  });
+  registerOperations(fw);
+  return fw;
+}
+`,
+  "src/app/main/index.ts": '// Electron entry (main process). Keep it thin: wiring only, logic lives in the other files of this folder.\nimport { app, ipcMain, protocol, webContents } from "electron";\nimport path from "node:path";\nimport { PLUGIN_SCHEME, attachElectron, registerPluginProtocol } from "fluxplugin/main";\nimport { createFramework } from "./framework";\nimport { pluginDirs, projectRoot } from "./paths";\nimport { createMainWindow } from "./window";\n\nprotocol.registerSchemesAsPrivileged([PLUGIN_SCHEME]); // must run before the app is ready\n\napp.whenReady().then(async () => {\n  const fw = createFramework({\n    pluginDirs: pluginDirs(projectRoot(__dirname), app.getPath("userData")),\n    dataDir: path.join(app.getPath("userData"), "plugins-data"),\n    dev: !!process.env["FLUXPLUGIN_DEV"],\n  });\n  registerPluginProtocol(fw, protocol);\n  attachElectron(fw, { ipcMain: ipcMain as never, webContents: webContents as never });\n  await fw.start();\n  createMainWindow(__dirname);\n  app.on("before-quit", () => void fw.stop());\n});\n\napp.on("window-all-closed", () => app.quit());\n',
+  "src/app/main/operations.ts": 'import { s } from "fluxplugin";\nimport type { MainFramework } from "fluxplugin/main";\nimport { CHANNELS, OPERATIONS } from "../shared/constants";\nimport type { Item } from "../shared/types";\n\n/**\n * Host operations. Each one runs through the hook pipeline, so plugins can validate, normalize or veto it\n * (before.item.create, transform.item.create, ...) without touching this file.\n */\nexport function registerOperations(fw: MainFramework): void {\n  fw.manager.ipc.handle(\n    CHANNELS.createItem,\n    (input: { name: string }) =>\n      fw.manager.hooks.run(OPERATIONS.createItem, input, (i) => {\n        const item: Item = { id: Math.random().toString(36).slice(2, 8), name: i.name };\n        fw.manager.events.emit("item.created", item, "host");\n        return item as unknown as Record<string, unknown>;\n      }),\n    "host",\n    { input: s.object({ name: s.string() }) },\n  );\n}\n',
+  "src/app/main/paths.ts": 'import path from "node:path";\n\n/** Project root: set by `fluxplugin dev|start`; falls back to the folder above dist/ (packaged app). */\nexport function projectRoot(distDir: string): string {\n  return process.env["FLUXPLUGIN_PROJECT"] ?? path.resolve(distDir, "..");\n}\n\n/** Plugins bundled with the app (read-only) and plugins installed by the user (writable). */\nexport function pluginDirs(root: string, userData: string): string[] {\n  return [path.join(root, "plugins"), path.join(userData, "plugins")];\n}\n',
+  "src/app/main/web.ts": '// Browser entry: `fluxplugin dev --web` (no Electron needed).\nimport path from "node:path";\nimport { serveWeb } from "fluxplugin/main";\nimport { APP_NAME } from "../shared/constants";\nimport { createFramework } from "./framework";\n\nconst root = process.env["FLUXPLUGIN_PROJECT"] ?? process.cwd();\nconst fw = createFramework({\n  pluginDirs: [path.join(root, "plugins")],\n  dataDir: path.join(root, ".flux-data"),\n  dev: true,\n  assetUrl: (id, rel) => "/@plugins/" + id + "/" + rel.replace("./", ""),\n});\nawait fw.start();\nconst srv = await serveWeb(fw, { distDir: path.join(root, "dist"), port: Number(process.env["PORT"] ?? 5173) });\nconsole.log(APP_NAME + " -> http://127.0.0.1:" + srv.port);\n',
+  "src/app/main/window.ts": 'import { BrowserWindow } from "electron";\nimport path from "node:path";\n\nexport function createMainWindow(distDir: string): BrowserWindow {\n  const win = new BrowserWindow({\n    width: 1100,\n    height: 760,\n    show: false,\n    webPreferences: {\n      preload: path.join(distDir, "preload.cjs"),\n      contextIsolation: true,\n      sandbox: true,\n      nodeIntegration: false,\n    },\n  });\n  win.once("ready-to-show", () => win.show());\n  // The app never navigates away and never opens new windows.\n  win.webContents.setWindowOpenHandler(() => ({ action: "deny" }));\n  win.webContents.on("will-navigate", (e) => e.preventDefault());\n  void win.loadFile(path.join(distDir, "index.html"));\n  return win;\n}\n',
+  "src/app/preload/index.ts": 'import { contextBridge, ipcRenderer } from "electron";\nimport { exposeFluxBridge } from "fluxplugin/preload";\n\n// The only thing renderer code receives from the preload: window.__fluxplugin\nexposeFluxBridge(contextBridge, ipcRenderer);\n',
+  "src/app/renderer/App.tsx": 'import type { FluxBridge } from "fluxplugin";\nimport type { RendererFramework } from "fluxplugin/react";\nimport { AppProviders } from "./providers/AppProviders";\nimport { AppShell } from "./shell/AppShell";\n\nexport function App({ framework, bridge }: { framework: RendererFramework; bridge: FluxBridge }) {\n  return (\n    <AppProviders framework={framework} bridge={bridge}>\n      <AppShell />\n    </AppProviders>\n  );\n}\n',
+  "src/app/renderer/bootstrap.ts": 'import React from "react";\nimport * as jsxRuntime from "react/jsx-runtime";\nimport * as ReactDOMClient from "react-dom/client";\nimport * as flux from "fluxplugin";\nimport * as fluxReact from "fluxplugin/react";\nimport type { FluxBridge } from "fluxplugin";\nimport { RendererFramework, createHttpBridge, installSharedModules } from "fluxplugin/react";\nimport { declareExtensionPoints } from "./extension-points";\nimport { registerHostRoutes } from "./routes";\n\n/**\n * Infrastructure layer: connects to the main process, shares singletons with plugin bundles,\n * declares what plugins may extend, registers the host\'s own routes, then starts the plugins.\n */\nexport async function bootstrap(): Promise<{ framework: RendererFramework; bridge: FluxBridge }> {\n  // One copy of React and of the runtime: plugin bundles import these from globalThis.\n  installSharedModules({\n    react: React,\n    "react/jsx-runtime": jsxRuntime,\n    "react/jsx-dev-runtime": jsxRuntime,\n    "react-dom/client": ReactDOMClient,\n    fluxplugin: flux,\n    "fluxplugin/react": fluxReact,\n  });\n\n  // Electron: the preload bridge. Browser mode: HTTP bridge to `fluxplugin dev --web`.\n  const bridge: FluxBridge = (window as unknown as { __fluxplugin?: FluxBridge }).__fluxplugin ?? createHttpBridge();\n  const framework = new RendererFramework({ bridge });\n\n  declareExtensionPoints(framework); // BEFORE plugins start\n  registerHostRoutes(framework);\n  await framework.start();\n  return { framework, bridge };\n}\n',
+  "src/app/renderer/extension-points.ts": 'import { s } from "fluxplugin";\nimport type { RendererFramework } from "fluxplugin/react";\nimport { EXTENSION_POINTS } from "../shared/constants";\n\n/** Declare what plugins may contribute. Contributions are validated against these schemas. */\nexport function declareExtensionPoints(framework: RendererFramework): void {\n  framework.manager.extensionPoints.declare({\n    name: EXTENSION_POINTS.dashboard,\n    contributions: {\n      toolbar: s.object({ id: s.string(), label: s.string(), command: s.string().optional() }),\n    },\n  });\n}\n',
+  "src/app/renderer/hooks/useCreateItem.ts": 'import { useState } from "react";\nimport { useBridge } from "../providers/AppProviders";\nimport { itemsApi } from "../services/items";\n\n/** Calls the host operation (which plugins may rewrite or veto through hooks) and exposes the outcome. */\nexport function useCreateItem() {\n  const bridge = useBridge();\n  const [result, setResult] = useState("");\n  const create = async (name: string) => {\n    try {\n      setResult(JSON.stringify(await itemsApi.create(bridge, name)));\n    } catch (e) {\n      setResult("blocked: " + (e as Error).message);\n    }\n  };\n  return { create, result };\n}\n',
+  "src/app/renderer/index.html": `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>__APP_NAME__</title>
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self' fluxplugin:; script-src 'self' fluxplugin:; style-src 'self' 'unsafe-inline' fluxplugin:; connect-src 'self'; img-src 'self' data:" />
+    <link rel="stylesheet" href="./renderer.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./renderer.js"></script>
+  </body>
+</html>
+`,
+  "src/app/renderer/index.tsx": '// Renderer entry. Order matters: styles \u2192 bootstrap (infrastructure) \u2192 mount (UI).\nimport "./styles/app.css";\nimport { createRoot } from "react-dom/client";\nimport { bootstrap } from "./bootstrap";\nimport { App } from "./App";\n\nconst { framework, bridge } = await bootstrap();\ncreateRoot(document.getElementById("root")!).render(<App framework={framework} bridge={bridge} />);\n',
+  "src/app/renderer/pages/DashboardPage.tsx": 'import { PluginSlot, useExtensionItems, usePluginFramework } from "fluxplugin/react";\nimport { EXTENSION_POINTS, SLOTS } from "../../shared/constants";\nimport type { ToolbarAction } from "../../shared/types";\nimport { useCreateItem } from "../hooks/useCreateItem";\n\nexport function DashboardPage() {\n  const framework = usePluginFramework();\n  const actions = useExtensionItems<ToolbarAction>(EXTENSION_POINTS.dashboard, "toolbar");\n  const { create, result } = useCreateItem();\n  return (\n    <div>\n      <h2>Dashboard</h2>\n      <PluginSlot name={SLOTS.dashboardBefore} />\n      <p className="hint">These buttons are contributed by plugins through a host-declared extension point.</p>\n      <div className="row" data-testid="toolbar">\n        {actions.map((a) => (\n          <button key={a.id} className="btn" onClick={() => a.command && void framework.manager.commands.execute(a.command)}>\n            {a.label}\n          </button>\n        ))}\n      </div>\n      <div className="row">\n        <button className="btn" onClick={() => void create("  Ada  ")}>Create item \u201C  Ada  \u201D (plugin hooks may rewrite it)</button>\n        <button className="btn" onClick={() => void create("   ")}>Create empty item (a plugin may veto)</button>\n      </div>\n      <pre data-testid="hook-result" className="hint">{result}</pre>\n      <PluginSlot name={SLOTS.dashboardAfter} />\n    </div>\n  );\n}\n',
+  "src/app/renderer/pages/PluginsPage.tsx": 'import { PluginManagerUI } from "fluxplugin/manager-ui";\n\n/** Ready-made plugin manager (enable/disable, permissions, settings, logs, install). Replace with your own UI if you like. */\nexport function PluginsPage() {\n  return <PluginManagerUI />;\n}\n',
+  "src/app/renderer/providers/AppProviders.tsx": 'import { createContext, useContext, type ReactNode } from "react";\nimport type { FluxBridge } from "fluxplugin";\nimport { PluginProvider, StyleHost, baseCss, type RendererFramework } from "fluxplugin/react";\n\nconst BridgeContext = createContext<FluxBridge | null>(null);\n\n/** Gives pages access to the main-process bridge without importing globals. */\nexport function useBridge(): FluxBridge {\n  const b = useContext(BridgeContext);\n  if (!b) throw new Error("useBridge must be used inside <AppProviders>");\n  return b;\n}\n\nexport function AppProviders({ framework, bridge, children }: { framework: RendererFramework; bridge: FluxBridge; children: ReactNode }) {\n  return (\n    <PluginProvider framework={framework}>\n      <BridgeContext.Provider value={bridge}>\n        <style>{baseCss}</style>\n        <StyleHost />\n        {children}\n      </BridgeContext.Provider>\n    </PluginProvider>\n  );\n}\n',
+  "src/app/renderer/routes.ts": `import type { RendererFramework } from "fluxplugin/react";
+import { DashboardPage } from "./pages/DashboardPage";
+import { PluginsPage } from "./pages/PluginsPage";
+
+/** The host's own pages (owner "host"). Plugins add theirs at runtime through the same registry. */
+export function registerHostRoutes(framework: RendererFramework): void {
+  framework.manager.routes.register({ path: "/", component: DashboardPage, meta: { title: "Dashboard" } }, "host");
+  framework.manager.routes.register({ path: "/plugins", component: PluginsPage, meta: { title: "Plugins", breadcrumb: "Plugins" } }, "host");
 }
+`,
+  "src/app/renderer/services/items.ts": 'import type { FluxBridge } from "fluxplugin";\nimport { CHANNELS } from "../../shared/constants";\nimport type { Item } from "../../shared/types";\n\n/** Service layer: the only place that knows the IPC channel names. UI code calls these functions. */\nexport const itemsApi = {\n  create: (bridge: FluxBridge, name: string) => bridge.invoke(CHANNELS.createItem, { name }) as Promise<Item>,\n};\n',
+  "src/app/renderer/shell/AppShell.tsx": 'import { Breadcrumbs, CommandPalette, PluginRoutes, useKeybindings } from "fluxplugin/react";\nimport { Sidebar } from "./Sidebar";\n\n/** Layout of the whole window: sidebar + routed content + command palette. */\nexport function AppShell() {\n  useKeybindings(); // runs commands bound to keyboard shortcuts (Mod+Shift+R, ...)\n  return (\n    <div className="app">\n      <Sidebar />\n      <main className="main">\n        <Breadcrumbs />\n        <PluginRoutes />\n      </main>\n      <CommandPalette />\n    </div>\n  );\n}\n',
+  "src/app/renderer/shell/Sidebar.tsx": 'import { Link, PluginSlot, useMenu } from "fluxplugin/react";\nimport { APP_NAME, SLOTS } from "../../shared/constants";\n\nexport function Sidebar() {\n  const { items, run } = useMenu("sidebar"); // entries added by plugins (routes with meta.menu, or menus.register)\n  return (\n    <aside className="side">\n      <h1>\n        {APP_NAME} <PluginSlot name={SLOTS.sidebarHeader} />\n      </h1>\n      <Link to="/">Dashboard</Link>\n      {items.map((i) => (\n        <a key={i.id} href={"#" + i.path} onClick={(e) => (e.preventDefault(), run(i))}>\n          {i.label}\n        </a>\n      ))}\n      <Link to="/plugins">Plugins</Link>\n      <p className="hint">Ctrl/Cmd+K: commands</p>\n    </aside>\n  );\n}\n',
+  "src/app/renderer/styles/app.css": "body { margin: 0; font: 14px system-ui; background: var(--flux-bg); color: var(--flux-fg); }\n.app { display: grid; grid-template-columns: 220px 1fr; min-height: 100vh; }\n.side { border-right: 1px solid var(--flux-border); padding: 16px; background: var(--flux-surface); }\n.side h1 { font-size: 16px; margin: 0 0 14px; }\n.side a { display: block; padding: 7px 10px; border-radius: 8px; color: inherit; text-decoration: none; margin: 2px 0; }\n.side a[data-active] { background: var(--flux-accent); color: #fff; }\n.main { padding: 24px; max-width: 860px; }\n.row { display: flex; gap: 8px; margin: 12px 0; flex-wrap: wrap; }\n.btn { border: 1px solid var(--flux-border); background: var(--flux-bg); color: inherit; border-radius: 8px; padding: 6px 12px; cursor: pointer; }\n.hint { color: var(--flux-muted); font-size: 12px; }\n",
+  "src/app/shared/constants.ts": '/** Names shared by the main process and the renderer. No imports here: this layer depends on nothing. */\nexport const APP_NAME = "__APP_NAME__";\n\n/** IPC channels the host exposes to the renderer (also allow-listed in main/framework.ts). */\nexport const CHANNELS = {\n  createItem: "host.item.create",\n} as const;\n\n/** Declarative extension points the host offers to plugins (see renderer/extension-points.ts). */\nexport const EXTENSION_POINTS = {\n  dashboard: "dashboard",\n} as const;\n\n/** UI slots where plugins can inject components (see <PluginSlot name=... />). */\nexport const SLOTS = {\n  sidebarHeader: "header.badges",\n  dashboardBefore: "dashboard.before",\n  dashboardAfter: "dashboard.after",\n} as const;\n\n/** Hook pipeline operations plugins can intercept: before./after./transform./validate.<operation>. */\nexport const OPERATIONS = {\n  createItem: "item.create",\n} as const;\n',
+  "src/app/shared/types.ts": 'export interface Item {\n  id: string;\n  name: string;\n}\n\n/** Shape of a contribution to the "dashboard" extension point (validated in renderer/extension-points.ts). */\nexport interface ToolbarAction {\n  id: string;\n  label: string;\n  command?: string;\n}\n'
+};
 
 // src/cli/templates.ts
 var pkg = (v) => JSON.stringify(
@@ -1201,113 +1308,9 @@ function hostFiles(v, withSample = true) {
       2
     ),
     ".gitignore": "node_modules\ndist\n.flux-data\n*.tgz\n",
-    "src/index.html": `<!doctype html>
-<html><head><meta charset="utf-8"><title>${v.name}</title>
-<meta http-equiv="Content-Security-Policy" content="default-src 'self' fluxplugin:; script-src 'self' fluxplugin:; style-src 'self' 'unsafe-inline' fluxplugin:; connect-src 'self'; img-src 'self' data:">
-<style>body{margin:0;font:14px system-ui}</style></head>
-<body><div id="root"></div><script type="module" src="./renderer.js"></script></body></html>
-`,
-    "src/framework.ts": `import { MainFramework } from "fluxplugin/main";
-import { s } from "fluxplugin";
-
-/** Shared by Electron (main.ts) and browser mode (web.ts). Put host-side setup here. */
-export function createFramework(opts: { pluginDirs: string[]; dataDir: string; dev?: boolean; assetUrl?: (id: string, rel: string) => string }) {
-  const fw = new MainFramework({
-    pluginDirs: opts.pluginDirs,
-    dataDir: opts.dataDir,
-    hotReload: opts.dev,
-    assetUrl: opts.assetUrl,
-    requireApproval: false, // set true to make users approve each plugin's permissions
-    allowedRendererChannels: ["host.item.create"],
-  });
-
-  // A host operation wrapped in the hook pipeline: plugins can validate, normalize or veto it
-  // (before./transform./after.item.create) without changing this file.
-  fw.manager.ipc.handle(
-    "host.item.create",
-    (input: { name: string }) =>
-      fw.manager.hooks.run("item.create", input, (i) => {
-        const item = { id: Math.random().toString(36).slice(2, 8), name: i.name };
-        fw.manager.events.emit("item.created", item, "host");
-        return item as Record<string, unknown>;
-      }),
-    "host",
-    { input: s.object({ name: s.string() }) },
-  );
-  return fw;
-}
-`,
-    "src/main.ts": `// Electron main process.
-import { app, BrowserWindow, ipcMain, protocol, webContents } from "electron";
-import path from "node:path";
-import { PLUGIN_SCHEME, attachElectron, registerPluginProtocol } from "fluxplugin/main";
-import { createFramework } from "./framework.js";
-
-protocol.registerSchemesAsPrivileged([PLUGIN_SCHEME]); // must run before app is ready
-
-app.whenReady().then(async () => {
-  const dev = !!process.env["FLUXPLUGIN_DEV"];
-  const root = process.env["FLUXPLUGIN_PROJECT"] ?? path.resolve(__dirname, "..");
-  const fw = createFramework({
-    pluginDirs: [path.join(root, "plugins"), path.join(app.getPath("userData"), "plugins")], // bundled + user-installed
-    dataDir: path.join(app.getPath("userData"), "plugins-data"),
-    dev,
-  });
-  registerPluginProtocol(fw, protocol);
-  attachElectron(fw, { ipcMain: ipcMain as never, webContents: webContents as never });
-  await fw.start();
-
-  const win = new BrowserWindow({
-    width: 1100,
-    height: 760,
-    webPreferences: { preload: path.join(__dirname, "preload.cjs"), contextIsolation: true, sandbox: true, nodeIntegration: false },
-  });
-  win.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
-  win.webContents.on("will-navigate", (e) => e.preventDefault());
-  await win.loadFile(path.join(__dirname, "index.html"));
-  app.on("before-quit", () => void fw.stop());
-});
-app.on("window-all-closed", () => app.quit());
-`,
-    "src/preload.ts": `import { contextBridge, ipcRenderer } from "electron";
-import { exposeFluxBridge } from "fluxplugin/preload";
-
-exposeFluxBridge(contextBridge, ipcRenderer); // the only thing renderer code receives: window.__fluxplugin
-`,
-    "src/web.ts": `// Browser mode (no Electron): \`fluxplugin dev --web\`.
-import path from "node:path";
-import { serveWeb } from "fluxplugin/main";
-import { createFramework } from "./framework.js";
-
-const root = process.env["FLUXPLUGIN_PROJECT"] ?? process.cwd();
-const fw = createFramework({
-  pluginDirs: [path.join(root, "plugins")],
-  dataDir: path.join(root, ".flux-data"),
-  dev: true,
-  assetUrl: (id, rel) => \`/@plugins/\${id}/\${rel.replace(/^\\.\\//, "")}\`,
-});
-await fw.start();
-const srv = await serveWeb(fw, { distDir: path.join(root, "dist"), port: Number(process.env["PORT"] ?? 5173) });
-console.log(\`${v.name} \u2192 http://127.0.0.1:\${srv.port}\`);
-`,
-    "src/renderer.tsx": renderer(v.name),
-    "README.md": `# ${v.name}
-
-Created with [fluxplugin](https://www.npmjs.com/package/fluxplugin).
-
-\`\`\`bash
-npm install
-npm run dev:web      # in a browser, no Electron needed
-npm run dev          # in Electron (hot reload for plugins)
-npm run build && npm start
-npm run plugin:new my-plugin -- -t backend    # scaffold a plugin in ./plugins
-\`\`\`
-
-* \`src/renderer.tsx\` \u2014 your React UI. \`<PluginSlot name="\u2026"/>\` and extension points are where plugins plug in.
-* \`src/framework.ts\` \u2014 host-side setup (permissions policy, host operations exposed to plugins, hooks).
-* \`plugins/\` \u2014 plugins loaded at startup; users can also install \`.tgz\` plugins from the Plugins page.
-`
+    "README.md": readme(v.name)
   };
+  for (const [rel, content] of Object.entries(HOST_APP_FILES)) files[rel] = content.split("__APP_NAME__").join(v.name);
   if (withSample) {
     const sample = TEMPLATES.dashboard(varsFromName("hello"));
     for (const [rel, content] of Object.entries(sample)) {
@@ -1317,97 +1320,35 @@ npm run plugin:new my-plugin -- -t backend    # scaffold a plugin in ./plugins
   }
   return files;
 }
-var renderer = (app) => `import React from "react";
-import { createRoot } from "react-dom/client";
-import * as jsxRuntime from "react/jsx-runtime";
-import * as ReactDOMClient from "react-dom/client";
-import * as flux from "fluxplugin";
-import * as fluxReact from "fluxplugin/react";
-import { s, type FluxBridge } from "fluxplugin";
-import {
-  Breadcrumbs, CommandPalette, Link, PluginProvider, PluginRoutes, PluginSlot, RendererFramework, StyleHost,
-  baseCss, createHttpBridge, installSharedModules, useExtensionItems, useKeybindings, useMenu,
-} from "fluxplugin/react";
-import { PluginManagerUI } from "fluxplugin/manager-ui";
-
-// One copy of React and of the runtime, shared with plugin bundles (they import these from globalThis).
-installSharedModules({
-  react: React, "react/jsx-runtime": jsxRuntime, "react/jsx-dev-runtime": jsxRuntime, "react-dom/client": ReactDOMClient,
-  fluxplugin: flux, "fluxplugin/react": fluxReact,
-});
-
-// Electron: the preload bridge. Browser mode: HTTP bridge to \`fluxplugin dev --web\`.
-const bridge: FluxBridge = (window as unknown as { __fluxplugin?: FluxBridge }).__fluxplugin ?? createHttpBridge();
-const framework = new RendererFramework({ bridge });
+var readme = (name) => `# ${name}
 
-// Declare extension points BEFORE plugins start. Plugins contribute validated data to them.
-framework.manager.extensionPoints.declare({
-  name: "dashboard",
-  contributions: { toolbar: s.object({ id: s.string(), label: s.string(), command: s.string().optional() }) },
-});
-
-const css = baseCss + \`
-body{background:var(--flux-bg);color:var(--flux-fg)}
-.app{display:grid;grid-template-columns:220px 1fr;min-height:100vh}
-.side{border-right:1px solid var(--flux-border);padding:16px;background:var(--flux-surface)}
-.side a{display:block;padding:7px 10px;border-radius:8px;color:inherit;text-decoration:none;margin:2px 0}
-.side a[data-active]{background:var(--flux-accent);color:#fff}.side h1{font-size:16px;margin:0 0 14px}
-.main{padding:24px;max-width:860px}.row{display:flex;gap:8px;margin:12px 0}
-.btn{border:1px solid var(--flux-border);background:var(--flux-bg);color:inherit;border-radius:8px;padding:6px 12px;cursor:pointer}
-.hint{color:var(--flux-muted);font-size:12px}\`;
-
-function Dashboard() {
-  const tools = useExtensionItems<{ id: string; label: string; command?: string }>("dashboard", "toolbar");
-  const [out, setOut] = React.useState("");
-  const create = async (name: string) => {
-    try { setOut(JSON.stringify(await bridge.invoke("host.item.create", { name }))); }
-    catch (e) { setOut("blocked: " + (e as Error).message); }
-  };
-  return (
-    <div>
-      <h2>Dashboard</h2>
-      <PluginSlot name="dashboard.before" />
-      <p className="hint">These buttons are contributed by plugins through a host-declared extension point.</p>
-      <div className="row" data-testid="toolbar">
-        {tools.map((t) => <button key={t.id} className="btn" onClick={() => t.command && void framework.manager.commands.execute(t.command)}>{t.label}</button>)}
-      </div>
-      <div className="row">
-        <button className="btn" onClick={() => void create("  Ada  ")}>Create item \u201C  Ada  \u201D (plugin hooks may rewrite it)</button>
-        <button className="btn" onClick={() => void create("   ")}>Create empty item (a plugin may veto)</button>
-      </div>
-      <pre data-testid="hook-result" className="hint">{out}</pre>
-      <PluginSlot name="dashboard.after" />
-    </div>
-  );
-}
+Created with [fluxplugin](https://www.npmjs.com/package/fluxplugin).
 
-function Shell() {
-  useKeybindings();
-  const { items, run } = useMenu("sidebar");
-  return (
-    <div className="app">
-      <aside className="side">
-        <h1>${"${APP}"} <PluginSlot name="header.badges" /></h1>
-        <Link to="/">Dashboard</Link>
-        {items.map((i) => <a key={i.id} href={"#" + i.path} onClick={(e) => { e.preventDefault(); run(i); }}>{i.label}</a>)}
-        <Link to="/plugins">Plugins</Link>
-        <p className="hint">Ctrl/Cmd+K: commands</p>
-      </aside>
-      <main className="main"><Breadcrumbs /><PluginRoutes /></main>
-      <CommandPalette />
-    </div>
-  );
-}
+\`\`\`bash
+npm install
+npm run dev:web      # in a browser, no Electron needed
+npm run dev          # in Electron (plugins hot-reload)
+npm run build && npm start
+npm run plugin:new my-plugin -- -t backend    # scaffold a plugin in ./plugins
+\`\`\`
 
-framework.manager.routes.register({ path: "/", component: Dashboard, meta: { title: "Dashboard" } }, "host");
-framework.manager.routes.register({ path: "/plugins", component: PluginManagerUI, meta: { title: "Plugins", breadcrumb: "Plugins" } }, "host");
+## Structure (everything lives in src/app)
 
-await framework.start();
-(window as unknown as Record<string, unknown>)["__framework"] = framework;
-createRoot(document.getElementById("root")!).render(
-  <PluginProvider framework={framework}><style>{css}</style><StyleHost /><Shell /></PluginProvider>,
-);
-`.replace("${APP}", app);
+\`\`\`
+src/app/
+  shared/      constants.ts, types.ts     names used by both processes (depends on nothing)
+  main/        index.ts (Electron entry) \xB7 web.ts (browser entry) \xB7 framework.ts \xB7 operations.ts \xB7 window.ts \xB7 paths.ts
+  preload/     index.ts                    exposes window.__fluxplugin
+  renderer/
+    index.tsx \xB7 index.html                 entry
+    bootstrap.ts                           bridge, shared modules, framework start   (infrastructure)
+    extension-points.ts \xB7 routes.ts        what plugins may extend / host pages
+    providers/  shell/  pages/             UI layers
+    hooks/  services/                      app logic (services know the IPC channels, hooks serve the UI)
+    styles/app.css
+plugins/       plugins loaded at startup (users can also install .tgz from the Plugins page)
+\`\`\`
+`;
 
 // src/cli/cli.ts
 var HELP = `fluxplugin <command>
@@ -1497,6 +1438,7 @@ Add a plugin:  npm run plugin:new my-plugin -- -t backend`);
         }
         const dispose = await buildHost(cwd, { watch: true });
         const { child, mode } = startApp(cwd, { web: f.web, dev: true, port: f.port ? Number(f.port) : void 0 });
+        child.on("error", (e) => console.error(`error: ${e.message}`));
         log(`running in ${mode} mode \u2014 edit a plugin and it reloads; Ctrl+C to stop`);
         const stop = () => {
           child.kill();

package/dist/node/cli-api.js

@@ -91,7 +91,7 @@ async function buildPlugin(root, watch = false, log2 = console.log) {
 
 // src/cli/host.ts
 import { spawn } from "node:child_process";
-import { promises as fs3 } from "node:fs";
+import { existsSync, promises as fs3, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import path4 from "node:path";
 import { build as build2, context as context2 } from "esbuild";
@@ -114,17 +114,25 @@ async function loadConfig(flags, cwd = process.cwd()) {
 // src/cli/host.ts
 var exists2 = (f) => fs3.access(f).then(() => true, () => false);
 async function isHostProject(cwd) {
-  return await exists2(path4.join(cwd, "fluxplugin.config.json")) || await exists2(path4.join(cwd, "src/renderer.tsx")) && await exists2(path4.join(cwd, "src/framework.ts"));
+  if (await exists2(path4.join(cwd, "fluxplugin.config.json"))) return true;
+  return await exists2(path4.join(cwd, "src/app/renderer/index.tsx")) || await exists2(path4.join(cwd, "src/renderer.tsx"));
 }
 var nodeBanner = { js: "import { createRequire as __r } from 'node:module'; const require = __r(import.meta.url);" };
+var pick = (cwd, ...rels) => {
+  for (const r of rels) if (existsSync(path4.join(cwd, r))) return path4.join(cwd, r);
+  return path4.join(cwd, rels[0]);
+};
 function hostBuilds(cwd, outDir, dev) {
   const common = { absWorkingDir: cwd, bundle: true, sourcemap: dev, logLevel: "warning", jsx: "automatic", define: { "process.env.NODE_ENV": JSON.stringify(dev ? "development" : "production") } };
-  const entry = (f) => path4.join(cwd, "src", f);
+  const renderer = pick(cwd, "src/app/renderer/index.tsx", "src/renderer.tsx");
+  const main = pick(cwd, "src/app/main/index.ts", "src/main.ts");
+  const preload = pick(cwd, "src/app/preload/index.ts", "src/preload.ts");
+  const web = pick(cwd, "src/app/main/web.ts", "src/web.ts");
   return [
-    { ...common, entryPoints: [entry("renderer.tsx")], outfile: path4.join(outDir, "renderer.js"), platform: "browser", format: "esm", target: "chrome120" },
-    { ...common, entryPoints: [entry("main.ts")], outfile: path4.join(outDir, "main.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
-    { ...common, entryPoints: [entry("preload.ts")], outfile: path4.join(outDir, "preload.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
-    { ...common, entryPoints: [entry("web.ts")], outfile: path4.join(outDir, "web.mjs"), platform: "node", format: "esm", target: "node20", external: ["electron"], banner: nodeBanner }
+    { ...common, entryPoints: [renderer], outfile: path4.join(outDir, "renderer.js"), platform: "browser", format: "esm", target: "chrome120" },
+    { ...common, entryPoints: [main], outfile: path4.join(outDir, "main.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
+    { ...common, entryPoints: [preload], outfile: path4.join(outDir, "preload.cjs"), platform: "node", format: "cjs", target: "node20", external: ["electron"] },
+    { ...common, entryPoints: [web], outfile: path4.join(outDir, "web.mjs"), platform: "node", format: "esm", target: "node20", external: ["electron"], banner: nodeBanner }
   ];
 }
 async function pluginDirs(cwd, pluginsDir) {
@@ -140,11 +148,12 @@ async function buildHost(cwd, opts = {}) {
   const cfg = await loadConfig({}, cwd);
   const outDir = path4.resolve(cwd, cfgFile.outDir ?? "dist");
   await fs3.mkdir(outDir, { recursive: true });
-  await fs3.copyFile(path4.join(cwd, "src/index.html"), path4.join(outDir, "index.html"));
+  await fs3.copyFile(pick(cwd, "src/app/renderer/index.html", "src/index.html"), path4.join(outDir, "index.html"));
   const disposers = [];
   const opts2 = hostBuilds(cwd, outDir, !!opts.watch);
   if (opts.watch) {
     const ctxs = await Promise.all(opts2.map((o) => context2(o)));
+    await Promise.all(ctxs.map((c) => c.rebuild()));
     await Promise.all(ctxs.map((c) => c.watch()));
     disposers.push(async () => void await Promise.all(ctxs.map((c) => c.dispose())));
   } else for (const o of opts2) await build2(o);
@@ -161,17 +170,115 @@ async function buildHost(cwd, opts = {}) {
 function electronBinary(cwd) {
   try {
     const p = createRequire(path4.join(cwd, "package.json"))("electron");
-    return typeof p === "string" ? p : void 0;
+    if (typeof p === "string" && existsSync(p)) return { bin: p };
+    return { error: "the Electron binary was not found" };
+  } catch (e) {
+    return { error: e.message.split("\n")[0] };
+  }
+}
+function needsNoSandbox(bin) {
+  if (process.platform !== "linux") return false;
+  if (process.getuid?.() === 0) return true;
+  try {
+    const st = statSync(path4.join(path4.dirname(bin), "chrome-sandbox"));
+    return !(st.uid === 0 && (st.mode & 2048) !== 0);
   } catch {
-    return void 0;
+    return false;
   }
 }
 function startApp(cwd, opts = {}) {
-  const bin = opts.web ? void 0 : electronBinary(cwd);
+  const log2 = opts.log ?? console.log;
   const env = { ...process.env, FLUXPLUGIN_PROJECT: cwd, ...opts.dev ? { FLUXPLUGIN_DEV: "1" } : {}, ...opts.port ? { PORT: String(opts.port) } : {} };
-  if (bin) return { child: spawn(bin, [path4.join(cwd, "dist/main.cjs")], { cwd, env, stdio: "inherit" }), mode: "electron" };
-  return { child: spawn(process.execPath, [path4.join(cwd, "dist/web.mjs")], { cwd, env, stdio: "inherit" }), mode: "web" };
+  if (opts.web) return { child: spawn(process.execPath, [path4.join(cwd, "dist/web.mjs")], { cwd, env, stdio: "inherit" }), mode: "web" };
+  const { bin, error } = electronBinary(cwd);
+  if (!bin) throw new Error(`cannot start Electron: ${error}.
+  Install it with:  npm install -D electron   (then re-run)
+  or run in a browser:  fluxplugin ${opts.dev ? "dev" : "start"} --web`);
+  const args = [...process.env["FLUXPLUGIN_ELECTRON_ARGS"]?.split(" ").filter(Boolean) ?? [], path4.join(cwd, "dist/main.cjs")];
+  if (needsNoSandbox(bin)) {
+    args.unshift("--no-sandbox");
+    log2("! Linux: Electron's sandbox helper is not configured (or you run as root) \u2192 starting with --no-sandbox.\n  To fix permanently: sudo chown root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox");
+  }
+  const started = Date.now();
+  const child = spawn(bin, args, { cwd, env, stdio: "inherit" });
+  child.on("exit", (code) => {
+    if (code && Date.now() - started < 5e3) log2(`Electron exited with code ${code} right after starting. Scroll up for its error, or try:  fluxplugin dev --web`);
+  });
+  return { child, mode: "electron" };
+}
+
+// src/cli/host-files.generated.ts
+var HOST_APP_FILES = {
+  "src/app/main/framework.ts": `import { MainFramework } from "fluxplugin/main";
+import { CHANNELS } from "../shared/constants";
+import { registerOperations } from "./operations";
+
+export interface FrameworkOptions {
+  pluginDirs: string[];
+  dataDir: string;
+  dev?: boolean;
+  assetUrl?: (id: string, rel: string) => string;
+}
+
+/** Creates the plugin framework. Shared by the Electron entry (index.ts) and the browser entry (web.ts). */
+export function createFramework(opts: FrameworkOptions): MainFramework {
+  const fw = new MainFramework({
+    pluginDirs: opts.pluginDirs,
+    dataDir: opts.dataDir,
+    hotReload: opts.dev,
+    assetUrl: opts.assetUrl,
+    requireApproval: false, // true \u2192 users must approve each plugin's permissions
+    allowedRendererChannels: [CHANNELS.createItem],
+  });
+  registerOperations(fw);
+  return fw;
+}
+`,
+  "src/app/main/index.ts": '// Electron entry (main process). Keep it thin: wiring only, logic lives in the other files of this folder.\nimport { app, ipcMain, protocol, webContents } from "electron";\nimport path from "node:path";\nimport { PLUGIN_SCHEME, attachElectron, registerPluginProtocol } from "fluxplugin/main";\nimport { createFramework } from "./framework";\nimport { pluginDirs, projectRoot } from "./paths";\nimport { createMainWindow } from "./window";\n\nprotocol.registerSchemesAsPrivileged([PLUGIN_SCHEME]); // must run before the app is ready\n\napp.whenReady().then(async () => {\n  const fw = createFramework({\n    pluginDirs: pluginDirs(projectRoot(__dirname), app.getPath("userData")),\n    dataDir: path.join(app.getPath("userData"), "plugins-data"),\n    dev: !!process.env["FLUXPLUGIN_DEV"],\n  });\n  registerPluginProtocol(fw, protocol);\n  attachElectron(fw, { ipcMain: ipcMain as never, webContents: webContents as never });\n  await fw.start();\n  createMainWindow(__dirname);\n  app.on("before-quit", () => void fw.stop());\n});\n\napp.on("window-all-closed", () => app.quit());\n',
+  "src/app/main/operations.ts": 'import { s } from "fluxplugin";\nimport type { MainFramework } from "fluxplugin/main";\nimport { CHANNELS, OPERATIONS } from "../shared/constants";\nimport type { Item } from "../shared/types";\n\n/**\n * Host operations. Each one runs through the hook pipeline, so plugins can validate, normalize or veto it\n * (before.item.create, transform.item.create, ...) without touching this file.\n */\nexport function registerOperations(fw: MainFramework): void {\n  fw.manager.ipc.handle(\n    CHANNELS.createItem,\n    (input: { name: string }) =>\n      fw.manager.hooks.run(OPERATIONS.createItem, input, (i) => {\n        const item: Item = { id: Math.random().toString(36).slice(2, 8), name: i.name };\n        fw.manager.events.emit("item.created", item, "host");\n        return item as unknown as Record<string, unknown>;\n      }),\n    "host",\n    { input: s.object({ name: s.string() }) },\n  );\n}\n',
+  "src/app/main/paths.ts": 'import path from "node:path";\n\n/** Project root: set by `fluxplugin dev|start`; falls back to the folder above dist/ (packaged app). */\nexport function projectRoot(distDir: string): string {\n  return process.env["FLUXPLUGIN_PROJECT"] ?? path.resolve(distDir, "..");\n}\n\n/** Plugins bundled with the app (read-only) and plugins installed by the user (writable). */\nexport function pluginDirs(root: string, userData: string): string[] {\n  return [path.join(root, "plugins"), path.join(userData, "plugins")];\n}\n',
+  "src/app/main/web.ts": '// Browser entry: `fluxplugin dev --web` (no Electron needed).\nimport path from "node:path";\nimport { serveWeb } from "fluxplugin/main";\nimport { APP_NAME } from "../shared/constants";\nimport { createFramework } from "./framework";\n\nconst root = process.env["FLUXPLUGIN_PROJECT"] ?? process.cwd();\nconst fw = createFramework({\n  pluginDirs: [path.join(root, "plugins")],\n  dataDir: path.join(root, ".flux-data"),\n  dev: true,\n  assetUrl: (id, rel) => "/@plugins/" + id + "/" + rel.replace("./", ""),\n});\nawait fw.start();\nconst srv = await serveWeb(fw, { distDir: path.join(root, "dist"), port: Number(process.env["PORT"] ?? 5173) });\nconsole.log(APP_NAME + " -> http://127.0.0.1:" + srv.port);\n',
+  "src/app/main/window.ts": 'import { BrowserWindow } from "electron";\nimport path from "node:path";\n\nexport function createMainWindow(distDir: string): BrowserWindow {\n  const win = new BrowserWindow({\n    width: 1100,\n    height: 760,\n    show: false,\n    webPreferences: {\n      preload: path.join(distDir, "preload.cjs"),\n      contextIsolation: true,\n      sandbox: true,\n      nodeIntegration: false,\n    },\n  });\n  win.once("ready-to-show", () => win.show());\n  // The app never navigates away and never opens new windows.\n  win.webContents.setWindowOpenHandler(() => ({ action: "deny" }));\n  win.webContents.on("will-navigate", (e) => e.preventDefault());\n  void win.loadFile(path.join(distDir, "index.html"));\n  return win;\n}\n',
+  "src/app/preload/index.ts": 'import { contextBridge, ipcRenderer } from "electron";\nimport { exposeFluxBridge } from "fluxplugin/preload";\n\n// The only thing renderer code receives from the preload: window.__fluxplugin\nexposeFluxBridge(contextBridge, ipcRenderer);\n',
+  "src/app/renderer/App.tsx": 'import type { FluxBridge } from "fluxplugin";\nimport type { RendererFramework } from "fluxplugin/react";\nimport { AppProviders } from "./providers/AppProviders";\nimport { AppShell } from "./shell/AppShell";\n\nexport function App({ framework, bridge }: { framework: RendererFramework; bridge: FluxBridge }) {\n  return (\n    <AppProviders framework={framework} bridge={bridge}>\n      <AppShell />\n    </AppProviders>\n  );\n}\n',
+  "src/app/renderer/bootstrap.ts": 'import React from "react";\nimport * as jsxRuntime from "react/jsx-runtime";\nimport * as ReactDOMClient from "react-dom/client";\nimport * as flux from "fluxplugin";\nimport * as fluxReact from "fluxplugin/react";\nimport type { FluxBridge } from "fluxplugin";\nimport { RendererFramework, createHttpBridge, installSharedModules } from "fluxplugin/react";\nimport { declareExtensionPoints } from "./extension-points";\nimport { registerHostRoutes } from "./routes";\n\n/**\n * Infrastructure layer: connects to the main process, shares singletons with plugin bundles,\n * declares what plugins may extend, registers the host\'s own routes, then starts the plugins.\n */\nexport async function bootstrap(): Promise<{ framework: RendererFramework; bridge: FluxBridge }> {\n  // One copy of React and of the runtime: plugin bundles import these from globalThis.\n  installSharedModules({\n    react: React,\n    "react/jsx-runtime": jsxRuntime,\n    "react/jsx-dev-runtime": jsxRuntime,\n    "react-dom/client": ReactDOMClient,\n    fluxplugin: flux,\n    "fluxplugin/react": fluxReact,\n  });\n\n  // Electron: the preload bridge. Browser mode: HTTP bridge to `fluxplugin dev --web`.\n  const bridge: FluxBridge = (window as unknown as { __fluxplugin?: FluxBridge }).__fluxplugin ?? createHttpBridge();\n  const framework = new RendererFramework({ bridge });\n\n  declareExtensionPoints(framework); // BEFORE plugins start\n  registerHostRoutes(framework);\n  await framework.start();\n  return { framework, bridge };\n}\n',
+  "src/app/renderer/extension-points.ts": 'import { s } from "fluxplugin";\nimport type { RendererFramework } from "fluxplugin/react";\nimport { EXTENSION_POINTS } from "../shared/constants";\n\n/** Declare what plugins may contribute. Contributions are validated against these schemas. */\nexport function declareExtensionPoints(framework: RendererFramework): void {\n  framework.manager.extensionPoints.declare({\n    name: EXTENSION_POINTS.dashboard,\n    contributions: {\n      toolbar: s.object({ id: s.string(), label: s.string(), command: s.string().optional() }),\n    },\n  });\n}\n',
+  "src/app/renderer/hooks/useCreateItem.ts": 'import { useState } from "react";\nimport { useBridge } from "../providers/AppProviders";\nimport { itemsApi } from "../services/items";\n\n/** Calls the host operation (which plugins may rewrite or veto through hooks) and exposes the outcome. */\nexport function useCreateItem() {\n  const bridge = useBridge();\n  const [result, setResult] = useState("");\n  const create = async (name: string) => {\n    try {\n      setResult(JSON.stringify(await itemsApi.create(bridge, name)));\n    } catch (e) {\n      setResult("blocked: " + (e as Error).message);\n    }\n  };\n  return { create, result };\n}\n',
+  "src/app/renderer/index.html": `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>__APP_NAME__</title>
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self' fluxplugin:; script-src 'self' fluxplugin:; style-src 'self' 'unsafe-inline' fluxplugin:; connect-src 'self'; img-src 'self' data:" />
+    <link rel="stylesheet" href="./renderer.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./renderer.js"></script>
+  </body>
+</html>
+`,
+  "src/app/renderer/index.tsx": '// Renderer entry. Order matters: styles \u2192 bootstrap (infrastructure) \u2192 mount (UI).\nimport "./styles/app.css";\nimport { createRoot } from "react-dom/client";\nimport { bootstrap } from "./bootstrap";\nimport { App } from "./App";\n\nconst { framework, bridge } = await bootstrap();\ncreateRoot(document.getElementById("root")!).render(<App framework={framework} bridge={bridge} />);\n',
+  "src/app/renderer/pages/DashboardPage.tsx": 'import { PluginSlot, useExtensionItems, usePluginFramework } from "fluxplugin/react";\nimport { EXTENSION_POINTS, SLOTS } from "../../shared/constants";\nimport type { ToolbarAction } from "../../shared/types";\nimport { useCreateItem } from "../hooks/useCreateItem";\n\nexport function DashboardPage() {\n  const framework = usePluginFramework();\n  const actions = useExtensionItems<ToolbarAction>(EXTENSION_POINTS.dashboard, "toolbar");\n  const { create, result } = useCreateItem();\n  return (\n    <div>\n      <h2>Dashboard</h2>\n      <PluginSlot name={SLOTS.dashboardBefore} />\n      <p className="hint">These buttons are contributed by plugins through a host-declared extension point.</p>\n      <div className="row" data-testid="toolbar">\n        {actions.map((a) => (\n          <button key={a.id} className="btn" onClick={() => a.command && void framework.manager.commands.execute(a.command)}>\n            {a.label}\n          </button>\n        ))}\n      </div>\n      <div className="row">\n        <button className="btn" onClick={() => void create("  Ada  ")}>Create item \u201C  Ada  \u201D (plugin hooks may rewrite it)</button>\n        <button className="btn" onClick={() => void create("   ")}>Create empty item (a plugin may veto)</button>\n      </div>\n      <pre data-testid="hook-result" className="hint">{result}</pre>\n      <PluginSlot name={SLOTS.dashboardAfter} />\n    </div>\n  );\n}\n',
+  "src/app/renderer/pages/PluginsPage.tsx": 'import { PluginManagerUI } from "fluxplugin/manager-ui";\n\n/** Ready-made plugin manager (enable/disable, permissions, settings, logs, install). Replace with your own UI if you like. */\nexport function PluginsPage() {\n  return <PluginManagerUI />;\n}\n',
+  "src/app/renderer/providers/AppProviders.tsx": 'import { createContext, useContext, type ReactNode } from "react";\nimport type { FluxBridge } from "fluxplugin";\nimport { PluginProvider, StyleHost, baseCss, type RendererFramework } from "fluxplugin/react";\n\nconst BridgeContext = createContext<FluxBridge | null>(null);\n\n/** Gives pages access to the main-process bridge without importing globals. */\nexport function useBridge(): FluxBridge {\n  const b = useContext(BridgeContext);\n  if (!b) throw new Error("useBridge must be used inside <AppProviders>");\n  return b;\n}\n\nexport function AppProviders({ framework, bridge, children }: { framework: RendererFramework; bridge: FluxBridge; children: ReactNode }) {\n  return (\n    <PluginProvider framework={framework}>\n      <BridgeContext.Provider value={bridge}>\n        <style>{baseCss}</style>\n        <StyleHost />\n        {children}\n      </BridgeContext.Provider>\n    </PluginProvider>\n  );\n}\n',
+  "src/app/renderer/routes.ts": `import type { RendererFramework } from "fluxplugin/react";
+import { DashboardPage } from "./pages/DashboardPage";
+import { PluginsPage } from "./pages/PluginsPage";
+
+/** The host's own pages (owner "host"). Plugins add theirs at runtime through the same registry. */
+export function registerHostRoutes(framework: RendererFramework): void {
+  framework.manager.routes.register({ path: "/", component: DashboardPage, meta: { title: "Dashboard" } }, "host");
+  framework.manager.routes.register({ path: "/plugins", component: PluginsPage, meta: { title: "Plugins", breadcrumb: "Plugins" } }, "host");
 }
+`,
+  "src/app/renderer/services/items.ts": 'import type { FluxBridge } from "fluxplugin";\nimport { CHANNELS } from "../../shared/constants";\nimport type { Item } from "../../shared/types";\n\n/** Service layer: the only place that knows the IPC channel names. UI code calls these functions. */\nexport const itemsApi = {\n  create: (bridge: FluxBridge, name: string) => bridge.invoke(CHANNELS.createItem, { name }) as Promise<Item>,\n};\n',
+  "src/app/renderer/shell/AppShell.tsx": 'import { Breadcrumbs, CommandPalette, PluginRoutes, useKeybindings } from "fluxplugin/react";\nimport { Sidebar } from "./Sidebar";\n\n/** Layout of the whole window: sidebar + routed content + command palette. */\nexport function AppShell() {\n  useKeybindings(); // runs commands bound to keyboard shortcuts (Mod+Shift+R, ...)\n  return (\n    <div className="app">\n      <Sidebar />\n      <main className="main">\n        <Breadcrumbs />\n        <PluginRoutes />\n      </main>\n      <CommandPalette />\n    </div>\n  );\n}\n',
+  "src/app/renderer/shell/Sidebar.tsx": 'import { Link, PluginSlot, useMenu } from "fluxplugin/react";\nimport { APP_NAME, SLOTS } from "../../shared/constants";\n\nexport function Sidebar() {\n  const { items, run } = useMenu("sidebar"); // entries added by plugins (routes with meta.menu, or menus.register)\n  return (\n    <aside className="side">\n      <h1>\n        {APP_NAME} <PluginSlot name={SLOTS.sidebarHeader} />\n      </h1>\n      <Link to="/">Dashboard</Link>\n      {items.map((i) => (\n        <a key={i.id} href={"#" + i.path} onClick={(e) => (e.preventDefault(), run(i))}>\n          {i.label}\n        </a>\n      ))}\n      <Link to="/plugins">Plugins</Link>\n      <p className="hint">Ctrl/Cmd+K: commands</p>\n    </aside>\n  );\n}\n',
+  "src/app/renderer/styles/app.css": "body { margin: 0; font: 14px system-ui; background: var(--flux-bg); color: var(--flux-fg); }\n.app { display: grid; grid-template-columns: 220px 1fr; min-height: 100vh; }\n.side { border-right: 1px solid var(--flux-border); padding: 16px; background: var(--flux-surface); }\n.side h1 { font-size: 16px; margin: 0 0 14px; }\n.side a { display: block; padding: 7px 10px; border-radius: 8px; color: inherit; text-decoration: none; margin: 2px 0; }\n.side a[data-active] { background: var(--flux-accent); color: #fff; }\n.main { padding: 24px; max-width: 860px; }\n.row { display: flex; gap: 8px; margin: 12px 0; flex-wrap: wrap; }\n.btn { border: 1px solid var(--flux-border); background: var(--flux-bg); color: inherit; border-radius: 8px; padding: 6px 12px; cursor: pointer; }\n.hint { color: var(--flux-muted); font-size: 12px; }\n",
+  "src/app/shared/constants.ts": '/** Names shared by the main process and the renderer. No imports here: this layer depends on nothing. */\nexport const APP_NAME = "__APP_NAME__";\n\n/** IPC channels the host exposes to the renderer (also allow-listed in main/framework.ts). */\nexport const CHANNELS = {\n  createItem: "host.item.create",\n} as const;\n\n/** Declarative extension points the host offers to plugins (see renderer/extension-points.ts). */\nexport const EXTENSION_POINTS = {\n  dashboard: "dashboard",\n} as const;\n\n/** UI slots where plugins can inject components (see <PluginSlot name=... />). */\nexport const SLOTS = {\n  sidebarHeader: "header.badges",\n  dashboardBefore: "dashboard.before",\n  dashboardAfter: "dashboard.after",\n} as const;\n\n/** Hook pipeline operations plugins can intercept: before./after./transform./validate.<operation>. */\nexport const OPERATIONS = {\n  createItem: "item.create",\n} as const;\n',
+  "src/app/shared/types.ts": 'export interface Item {\n  id: string;\n  name: string;\n}\n\n/** Shape of a contribution to the "dashboard" extension point (validated in renderer/extension-points.ts). */\nexport interface ToolbarAction {\n  id: string;\n  label: string;\n  command?: string;\n}\n'
+};
 
 // src/cli/templates.ts
 var pkg = (v) => JSON.stringify(
@@ -400,113 +507,9 @@ function hostFiles(v, withSample = true) {
       2
     ),
     ".gitignore": "node_modules\ndist\n.flux-data\n*.tgz\n",
-    "src/index.html": `<!doctype html>
-<html><head><meta charset="utf-8"><title>${v.name}</title>
-<meta http-equiv="Content-Security-Policy" content="default-src 'self' fluxplugin:; script-src 'self' fluxplugin:; style-src 'self' 'unsafe-inline' fluxplugin:; connect-src 'self'; img-src 'self' data:">
-<style>body{margin:0;font:14px system-ui}</style></head>
-<body><div id="root"></div><script type="module" src="./renderer.js"></script></body></html>
-`,
-    "src/framework.ts": `import { MainFramework } from "fluxplugin/main";
-import { s } from "fluxplugin";
-
-/** Shared by Electron (main.ts) and browser mode (web.ts). Put host-side setup here. */
-export function createFramework(opts: { pluginDirs: string[]; dataDir: string; dev?: boolean; assetUrl?: (id: string, rel: string) => string }) {
-  const fw = new MainFramework({
-    pluginDirs: opts.pluginDirs,
-    dataDir: opts.dataDir,
-    hotReload: opts.dev,
-    assetUrl: opts.assetUrl,
-    requireApproval: false, // set true to make users approve each plugin's permissions
-    allowedRendererChannels: ["host.item.create"],
-  });
-
-  // A host operation wrapped in the hook pipeline: plugins can validate, normalize or veto it
-  // (before./transform./after.item.create) without changing this file.
-  fw.manager.ipc.handle(
-    "host.item.create",
-    (input: { name: string }) =>
-      fw.manager.hooks.run("item.create", input, (i) => {
-        const item = { id: Math.random().toString(36).slice(2, 8), name: i.name };
-        fw.manager.events.emit("item.created", item, "host");
-        return item as Record<string, unknown>;
-      }),
-    "host",
-    { input: s.object({ name: s.string() }) },
-  );
-  return fw;
-}
-`,
-    "src/main.ts": `// Electron main process.
-import { app, BrowserWindow, ipcMain, protocol, webContents } from "electron";
-import path from "node:path";
-import { PLUGIN_SCHEME, attachElectron, registerPluginProtocol } from "fluxplugin/main";
-import { createFramework } from "./framework.js";
-
-protocol.registerSchemesAsPrivileged([PLUGIN_SCHEME]); // must run before app is ready
-
-app.whenReady().then(async () => {
-  const dev = !!process.env["FLUXPLUGIN_DEV"];
-  const root = process.env["FLUXPLUGIN_PROJECT"] ?? path.resolve(__dirname, "..");
-  const fw = createFramework({
-    pluginDirs: [path.join(root, "plugins"), path.join(app.getPath("userData"), "plugins")], // bundled + user-installed
-    dataDir: path.join(app.getPath("userData"), "plugins-data"),
-    dev,
-  });
-  registerPluginProtocol(fw, protocol);
-  attachElectron(fw, { ipcMain: ipcMain as never, webContents: webContents as never });
-  await fw.start();
-
-  const win = new BrowserWindow({
-    width: 1100,
-    height: 760,
-    webPreferences: { preload: path.join(__dirname, "preload.cjs"), contextIsolation: true, sandbox: true, nodeIntegration: false },
-  });
-  win.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
-  win.webContents.on("will-navigate", (e) => e.preventDefault());
-  await win.loadFile(path.join(__dirname, "index.html"));
-  app.on("before-quit", () => void fw.stop());
-});
-app.on("window-all-closed", () => app.quit());
-`,
-    "src/preload.ts": `import { contextBridge, ipcRenderer } from "electron";
-import { exposeFluxBridge } from "fluxplugin/preload";
-
-exposeFluxBridge(contextBridge, ipcRenderer); // the only thing renderer code receives: window.__fluxplugin
-`,
-    "src/web.ts": `// Browser mode (no Electron): \`fluxplugin dev --web\`.
-import path from "node:path";
-import { serveWeb } from "fluxplugin/main";
-import { createFramework } from "./framework.js";
-
-const root = process.env["FLUXPLUGIN_PROJECT"] ?? process.cwd();
-const fw = createFramework({
-  pluginDirs: [path.join(root, "plugins")],
-  dataDir: path.join(root, ".flux-data"),
-  dev: true,
-  assetUrl: (id, rel) => \`/@plugins/\${id}/\${rel.replace(/^\\.\\//, "")}\`,
-});
-await fw.start();
-const srv = await serveWeb(fw, { distDir: path.join(root, "dist"), port: Number(process.env["PORT"] ?? 5173) });
-console.log(\`${v.name} \u2192 http://127.0.0.1:\${srv.port}\`);
-`,
-    "src/renderer.tsx": renderer(v.name),
-    "README.md": `# ${v.name}
-
-Created with [fluxplugin](https://www.npmjs.com/package/fluxplugin).
-
-\`\`\`bash
-npm install
-npm run dev:web      # in a browser, no Electron needed
-npm run dev          # in Electron (hot reload for plugins)
-npm run build && npm start
-npm run plugin:new my-plugin -- -t backend    # scaffold a plugin in ./plugins
-\`\`\`
-
-* \`src/renderer.tsx\` \u2014 your React UI. \`<PluginSlot name="\u2026"/>\` and extension points are where plugins plug in.
-* \`src/framework.ts\` \u2014 host-side setup (permissions policy, host operations exposed to plugins, hooks).
-* \`plugins/\` \u2014 plugins loaded at startup; users can also install \`.tgz\` plugins from the Plugins page.
-`
+    "README.md": readme(v.name)
   };
+  for (const [rel, content] of Object.entries(HOST_APP_FILES)) files[rel] = content.split("__APP_NAME__").join(v.name);
   if (withSample) {
     const sample = TEMPLATES.dashboard(varsFromName("hello"));
     for (const [rel, content] of Object.entries(sample)) {
@@ -516,97 +519,35 @@ npm run plugin:new my-plugin -- -t backend    # scaffold a plugin in ./plugins
   }
   return files;
 }
-var renderer = (app) => `import React from "react";
-import { createRoot } from "react-dom/client";
-import * as jsxRuntime from "react/jsx-runtime";
-import * as ReactDOMClient from "react-dom/client";
-import * as flux from "fluxplugin";
-import * as fluxReact from "fluxplugin/react";
-import { s, type FluxBridge } from "fluxplugin";
-import {
-  Breadcrumbs, CommandPalette, Link, PluginProvider, PluginRoutes, PluginSlot, RendererFramework, StyleHost,
-  baseCss, createHttpBridge, installSharedModules, useExtensionItems, useKeybindings, useMenu,
-} from "fluxplugin/react";
-import { PluginManagerUI } from "fluxplugin/manager-ui";
-
-// One copy of React and of the runtime, shared with plugin bundles (they import these from globalThis).
-installSharedModules({
-  react: React, "react/jsx-runtime": jsxRuntime, "react/jsx-dev-runtime": jsxRuntime, "react-dom/client": ReactDOMClient,
-  fluxplugin: flux, "fluxplugin/react": fluxReact,
-});
-
-// Electron: the preload bridge. Browser mode: HTTP bridge to \`fluxplugin dev --web\`.
-const bridge: FluxBridge = (window as unknown as { __fluxplugin?: FluxBridge }).__fluxplugin ?? createHttpBridge();
-const framework = new RendererFramework({ bridge });
-
-// Declare extension points BEFORE plugins start. Plugins contribute validated data to them.
-framework.manager.extensionPoints.declare({
-  name: "dashboard",
-  contributions: { toolbar: s.object({ id: s.string(), label: s.string(), command: s.string().optional() }) },
-});
+var readme = (name) => `# ${name}
 
-const css = baseCss + \`
-body{background:var(--flux-bg);color:var(--flux-fg)}
-.app{display:grid;grid-template-columns:220px 1fr;min-height:100vh}
-.side{border-right:1px solid var(--flux-border);padding:16px;background:var(--flux-surface)}
-.side a{display:block;padding:7px 10px;border-radius:8px;color:inherit;text-decoration:none;margin:2px 0}
-.side a[data-active]{background:var(--flux-accent);color:#fff}.side h1{font-size:16px;margin:0 0 14px}
-.main{padding:24px;max-width:860px}.row{display:flex;gap:8px;margin:12px 0}
-.btn{border:1px solid var(--flux-border);background:var(--flux-bg);color:inherit;border-radius:8px;padding:6px 12px;cursor:pointer}
-.hint{color:var(--flux-muted);font-size:12px}\`;
-
-function Dashboard() {
-  const tools = useExtensionItems<{ id: string; label: string; command?: string }>("dashboard", "toolbar");
-  const [out, setOut] = React.useState("");
-  const create = async (name: string) => {
-    try { setOut(JSON.stringify(await bridge.invoke("host.item.create", { name }))); }
-    catch (e) { setOut("blocked: " + (e as Error).message); }
-  };
-  return (
-    <div>
-      <h2>Dashboard</h2>
-      <PluginSlot name="dashboard.before" />
-      <p className="hint">These buttons are contributed by plugins through a host-declared extension point.</p>
-      <div className="row" data-testid="toolbar">
-        {tools.map((t) => <button key={t.id} className="btn" onClick={() => t.command && void framework.manager.commands.execute(t.command)}>{t.label}</button>)}
-      </div>
-      <div className="row">
-        <button className="btn" onClick={() => void create("  Ada  ")}>Create item \u201C  Ada  \u201D (plugin hooks may rewrite it)</button>
-        <button className="btn" onClick={() => void create("   ")}>Create empty item (a plugin may veto)</button>
-      </div>
-      <pre data-testid="hook-result" className="hint">{out}</pre>
-      <PluginSlot name="dashboard.after" />
-    </div>
-  );
-}
+Created with [fluxplugin](https://www.npmjs.com/package/fluxplugin).
 
-function Shell() {
-  useKeybindings();
-  const { items, run } = useMenu("sidebar");
-  return (
-    <div className="app">
-      <aside className="side">
-        <h1>${"${APP}"} <PluginSlot name="header.badges" /></h1>
-        <Link to="/">Dashboard</Link>
-        {items.map((i) => <a key={i.id} href={"#" + i.path} onClick={(e) => { e.preventDefault(); run(i); }}>{i.label}</a>)}
-        <Link to="/plugins">Plugins</Link>
-        <p className="hint">Ctrl/Cmd+K: commands</p>
-      </aside>
-      <main className="main"><Breadcrumbs /><PluginRoutes /></main>
-      <CommandPalette />
-    </div>
-  );
-}
+\`\`\`bash
+npm install
+npm run dev:web      # in a browser, no Electron needed
+npm run dev          # in Electron (plugins hot-reload)
+npm run build && npm start
+npm run plugin:new my-plugin -- -t backend    # scaffold a plugin in ./plugins
+\`\`\`
 
-framework.manager.routes.register({ path: "/", component: Dashboard, meta: { title: "Dashboard" } }, "host");
-framework.manager.routes.register({ path: "/plugins", component: PluginManagerUI, meta: { title: "Plugins", breadcrumb: "Plugins" } }, "host");
+## Structure (everything lives in src/app)
 
-await framework.start();
-(window as unknown as Record<string, unknown>)["__framework"] = framework;
-createRoot(document.getElementById("root")!).render(
-  <PluginProvider framework={framework}><style>{css}</style><StyleHost /><Shell /></PluginProvider>,
-);
-`.replace("${APP}", app);
+\`\`\`
+src/app/
+  shared/      constants.ts, types.ts     names used by both processes (depends on nothing)
+  main/        index.ts (Electron entry) \xB7 web.ts (browser entry) \xB7 framework.ts \xB7 operations.ts \xB7 window.ts \xB7 paths.ts
+  preload/     index.ts                    exposes window.__fluxplugin
+  renderer/
+    index.tsx \xB7 index.html                 entry
+    bootstrap.ts                           bridge, shared modules, framework start   (infrastructure)
+    extension-points.ts \xB7 routes.ts        what plugins may extend / host pages
+    providers/  shell/  pages/             UI layers
+    hooks/  services/                      app logic (services know the IPC channels, hooks serve the UI)
+    styles/app.css
+plugins/       plugins loaded at startup (users can also install .tgz from the Plugins page)
+\`\`\`
+`;
 
 // src/cli/cli.ts
 var HELP = `fluxplugin <command>
@@ -696,6 +637,7 @@ Add a plugin:  npm run plugin:new my-plugin -- -t backend`);
         }
         const dispose = await buildHost(cwd, { watch: true });
         const { child, mode } = startApp(cwd, { web: f.web, dev: true, port: f.port ? Number(f.port) : void 0 });
+        child.on("error", (e) => console.error(`error: ${e.message}`));
         log(`running in ${mode} mode \u2014 edit a plugin and it reloads; Ctrl+C to stop`);
         const stop = () => {
           child.kill();

package/dist/types/cli/host-files.generated.d.ts

@@ -0,0 +1 @@
+export declare const HOST_APP_FILES: Record<string, string>;

package/dist/types/cli/host.d.ts

@@ -5,11 +5,12 @@ export declare function buildHost(cwd: string, opts?: {
     watch?: boolean;
     log?: (m: string) => void;
 }): Promise<() => Promise<void>>;
-/** Starts the app: Electron when available (unless `web`), otherwise browser mode. Resolves when it exits. */
+/** Starts the app: Electron by default, browser mode with `web`. Throws a readable error if Electron cannot run. */
 export declare function startApp(cwd: string, opts?: {
     web?: boolean;
     dev?: boolean;
     port?: number;
+    log?: (m: string) => void;
 }): {
     child: ChildProcess;
     mode: "electron" | "web";

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "fluxplugin",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",