@vsceasy/cli 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.
 ## [Unreleased]
 
 ### Added
+- **Reactivity — keep a webview in sync with data.** A visual element can now track a source and update the instant it changes, no manual refresh.
+  - ORM entities fire change events on every mutation; subscribe with `watchEntity(Todos, () => emit('todos:changed'))` from your generated `db.ts`.
+  - `defineStore(initial)` — a framework-agnostic observable value (`get`/`set`/`update`/`subscribe`) for non-ORM state. Scaffold one with **`vsceasy store add --name X --type number|string|boolean|json`**.
+  - `watch(source, effect)` (host) bridges a store/entity to an RPC emit; `listen(api, topic, cb)` (webview) runs a callback when the event arrives. Both return an unsubscribe.
+  - Panel/subpanel `rpc` factories receive a third arg, `emit`, for pushing events to their own webview. (Reuses the existing RPC event channel — no transport change.)
+  - See the [Reactivity guide](https://vsceasy.dev/guides/reactivity/) and tutorial step 8.
 - **`vsceasy create` post-scaffold setup** — after generating the project, `create` now offers to **initialize a git repository** (`git init`) and **install dependencies** (`bun`, falling back to `npm`). Both prompts default to yes in an interactive terminal. New `--git` / `--install` flags (and `--git=false` / `--install=false`) skip the prompts for scripting/CI. Non-interactive runs without the flags skip both, as before.
 - **`vsceasy job add`** — scaffold recurring / event-triggered jobs into `src/jobs/`. Schedules: `--every "60s"`, `--dailyAt "09:00"`, `--on startup|saveDocument|openDocument|changeActiveEditor|changeConfig`, `--onFile "**/*.md"`. Optional `--minIntervalMs` throttles re-runs via globalState. Runtime (`bootstrap`) auto-registers timers/listeners + cleanup on deactivate, catches errors so they don't crash the host.
 - **`command add --when <expr>`** — declare VS Code `when` clauses on commands. Auto-written to `contributes.commands[].enablement` and `contributes.menus.commandPalette` by `bun run gen`. Enables context-aware visibility (e.g. `editorTextFocus`, `resourceLangId == typescript`).

package/README.md

@@ -6,6 +6,8 @@
 
 <p align="center">Build VS Code extensions fast. React UI + typed RPC bridge between extension and webview + zero-config build.</p>
 
+<p align="center"><em>Pronounced <strong>"vee-see-easy"</strong> in English (<code>VSC</code> + <code>easy</code>) — or <strong>"visici"</strong> for Spanish speakers.</em></p>
+
 > Status: v0.1 — React UI. Typed RPC bridge + file-based registry + scaffolding for panels, commands, menus, tree views, subpanels, status bars.
 
 ## Install

package/dist/bin/cli.js

@@ -3826,7 +3826,7 @@ var init_scaffold = __esm(() => {
 });
 
 // src/lib/templatesData.ts
-var TEMPLATES_VERSION = "0.1.7", TEMPLATE_FILES;
+var TEMPLATES_VERSION = "0.1.8", TEMPLATE_FILES;
 var init_templatesData = __esm(() => {
   TEMPLATE_FILES = {
     "_generators/command/command.ts.tpl": `import { defineCommand } from '../shared/vsceasy';
@@ -4538,6 +4538,35 @@ export interface Repository<T> {
   clear(): Promise<void>;
 }
 
+// ── Change notifications (reactivity) ────────────────────────────────────────
+
+/**
+ * Per-entity change listeners. Any mutation (insert/upsert/update/delete/...) on
+ * an entity fires its listeners with the entity name. This is the host-side hook
+ * the \`watch()\` helper builds on to push updates to webviews.
+ */
+const entityListeners = new Map<string, Set<(entity: string) => void>>();
+
+function emitChange(entity: string): void {
+  entityListeners.get(entity)?.forEach((cb) => {
+    try { cb(entity); } catch { /* a bad listener must not break a write */ }
+  });
+}
+
+/**
+ * Subscribe to changes on an entity. Returns an unsubscribe function.
+ *
+ *   watchEntity(Todos, () => server.emit('todos:changed'));
+ *
+ * Prefer the higher-level \`watch()\` helper, which wires this to an RPC emit.
+ */
+export function watchEntity<T>(entity: Entity<T>, cb: (entity: string) => void): () => void {
+  let set = entityListeners.get(entity.name);
+  if (!set) entityListeners.set(entity.name, (set = new Set()));
+  set.add(cb);
+  return () => { set!.delete(cb); };
+}
+
 // ── Provider interface (future-proof for sqlite/etc.) ────────────────────────
 
 export interface Provider {
@@ -4708,6 +4737,7 @@ function makeDb(provider: Provider): Db {
         }
         rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async upsert(row) {
@@ -4715,6 +4745,7 @@ function makeDb(provider: Provider): Db {
         const i = rows.findIndex((r) => r[pk] === row[pk]);
         if (i >= 0) rows[i] = row; else rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async update(id, patch) {
@@ -4723,6 +4754,7 @@ function makeDb(provider: Provider): Db {
         if (i < 0) return null;
         rows[i] = { ...rows[i], ...patch };
         await save(rows);
+        emitChange(entity.name);
         return rows[i];
       },
       async delete(id) {
@@ -4731,17 +4763,19 @@ function makeDb(provider: Provider): Db {
         const next = rows.filter((r) => r[pk] !== id);
         if (next.length === before) return false;
         await save(next);
+        emitChange(entity.name);
         return true;
       },
       async deleteMany(where) {
         const rows = await load();
         const next = rows.filter((r) => !match(r, where));
         const removed = rows.length - next.length;
-        if (removed > 0) await save(next);
+        if (removed > 0) { await save(next); emitChange(entity.name); }
         return removed;
       },
       async clear() {
         await save([]);
+        emitChange(entity.name);
       },
     };
   };
@@ -5166,6 +5200,30 @@ export default defineStatusBar({
   alignment: '{{alignment}}',
   priority: {{priority}},{{commandLine}}{{panelLine}}
 });
+`,
+    "_generators/store/store.ts.tpl": `import { defineStore } from '../shared/vsceasy';
+
+/**
+ * Reactive store: a single observable value. Mutate it with \`.set()\` / \`.update()\`
+ * and anything subscribed reacts.
+ *
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   {{name}}.set({{example}});
+ *   {{name}}.update((v) => v);
+ *
+ * To push changes to a webview, watch it on the host and emit over RPC:
+ *
+ *   // inside a panel/subpanel rpc():
+ *   import { watch } from '../shared/vsceasy';
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   watch({{name}}, () => server.emit('{{name}}:changed', {{name}}.get()));
+ *
+ * Then listen in the webview:
+ *
+ *   import { listen } from '../shared/vsceasy/client';
+ *   listen(api, '{{name}}:changed', (v) => render(v));
+ */
+export const {{name}} = defineStore<{{type}}>({{initial}});
 `,
     "_generators/subpanel/App.tsx.tpl": `import React from 'react';
 {{apiBlock}}
@@ -6362,6 +6420,13 @@ function registerTreeView(
     vscode.commands.registerCommand(refreshCmd, () => provider.refresh()),
   );
 
+  // Keep the tree live: let the def subscribe to a data source and re-run
+  // getChildren on change. The unsubscribe is disposed on deactivate.
+  if (def.watch) {
+    const off = def.watch(() => provider.refresh(), vscode, context);
+    if (off) context.subscriptions.push({ dispose: off });
+  }
+
   const dispatchCmd = \`\${registry.prefix}._tree.\${def.id ?? id}.run\`;
   context.subscriptions.push(
     vscode.commands.registerCommand(dispatchCmd, async (node: TreeNode) => {
@@ -6438,9 +6503,11 @@ function registerSubpanel(
       const ui = def.ui ?? \`subpanels/\${def.id ?? id}\`;
       view.webview.html = renderHtml(view.webview, context, ui, def.title);
       if (def.rpc) {
-        const handlers = def.rpc(vscode, context);
-        const server = createRpcServer(webviewTransport(view.webview), handlers);
-        view.onDidDispose(() => server.dispose());
+        let server: ReturnType<typeof createRpcServer> | undefined;
+        const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+        const handlers = def.rpc(vscode, context, emit);
+        server = createRpcServer(webviewTransport(view.webview), handlers);
+        view.onDidDispose(() => server!.dispose());
       }
     },
   };
@@ -6676,9 +6743,13 @@ function openPanel(context: vscode.ExtensionContext, prefix: string, id: string,
   panel.webview.html = renderHtml(panel.webview, context, ui, def.title);
 
   if (def.rpc) {
-    const handlers = def.rpc(vscode, context);
-    const server = createRpcServer(webviewTransport(panel.webview), handlers);
-    panel.onDidDispose(() => server.dispose());
+    // \`emit\` is wired lazily: the rpc factory may call watch()/watchEntity()
+    // immediately, but the server (and thus the real emit) only exists after.
+    let server: ReturnType<typeof createRpcServer> | undefined;
+    const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+    const handlers = def.rpc(vscode, context, emit);
+    server = createRpcServer(webviewTransport(panel.webview), handlers);
+    panel.onDidDispose(() => server!.dispose());
   }
 
   openPanels.set(key, panel);
@@ -6796,6 +6867,33 @@ export {
   webviewState,
 } from './rpc';
 export type { RpcClient, Handlers, Transport, RpcClientOptions, WebviewApi } from './rpc';
+
+export { defineStore } from './store';
+export type { Store } from './store';
+
+import type { RpcClient, Handlers } from './rpc';
+
+/**
+ * Listen for a change pushed from the host over the RPC event channel, and run a
+ * callback when it arrives. This is the webview side of the reactivity model —
+ * the host emits with \`server.emit(topic, …)\` (usually wired via \`watch()\` /
+ * \`watchEntity()\`), and your visual element reacts here. Returns an unsubscribe
+ * function; call it on unmount.
+ *
+ *   const api = connectWebview<TodoStatsViewApi>();
+ *   // re-read + re-render whenever todos change on the host:
+ *   const off = listen(api, 'todos:changed', () => refresh());
+ *
+ * It's a thin, named wrapper over \`api.on(topic, handler)\` so the place you
+ * listen reads clearly in the UI code. The payload (if any) is passed through.
+ */
+export function listen<H extends Handlers>(
+  api: RpcClient<H>,
+  topic: string,
+  handler: (payload?: unknown) => void,
+): () => void {
+  return api.on(topic, handler);
+}
 `,
     "react/src/shared/vsceasy/codiconNames.ts": `/**
  * AUTO-GENERATED by scripts/genCodiconTypes.ts — do not edit.
@@ -6998,6 +7096,18 @@ export type CodiconName =
 import type { Handlers } from './rpc';
 import type { CodiconName } from './codiconNames';
 
+/**
+ * Push a change to this webview over the RPC event channel. The webview reacts
+ * with \`listen(api, topic, …)\`. Wire it to a data source with \`watch()\` /
+ * \`watchEntity()\` inside \`rpc()\`:
+ *
+ *   rpc: (vscode, ctx, emit) => {
+ *     watchEntity(Todos, () => emit('todos:changed'));
+ *     return { stats: () => … };
+ *   }
+ */
+export type RpcEmit = (topic: string, payload?: unknown) => void;
+
 export interface PanelDef<H extends Handlers = Handlers> {
   /** Stable id. Default: file basename. Used as command suffix and webview key. */
   id?: string;
@@ -7009,8 +7119,11 @@ export interface PanelDef<H extends Handlers = Handlers> {
   column?: 'active' | 'beside' | 'one' | 'two' | 'three';
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * \`emit\` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
   /** Optional command palette entry that opens this panel. Default: true. */
   command?:
     | boolean
@@ -7121,8 +7234,11 @@ export interface SubpanelDef<H extends Handlers = Handlers> {
   ui?: string;
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * \`emit\` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
 }
 
 export function defineSubpanel<H extends Handlers = Handlers>(def: SubpanelDef<H>): SubpanelDef<H> {
@@ -7224,6 +7340,18 @@ export interface TreeViewDef {
     vscode: typeof import('vscode'),
     ctx: vscode.ExtensionContext,
   ) => TreeNode[] | Promise<TreeNode[]>;
+  /**
+   * Keep the tree live. Receives \`refresh\` — call it (directly or as a callback)
+   * to re-run \`getChildren\`. Subscribe to a data source here so the tree updates
+   * itself; return an unsubscribe to clean up.
+   *
+   *   watch: (refresh) => watchEntity(Todos, refresh),
+   */
+  watch?: (
+    refresh: () => void,
+    vscode: typeof import('vscode'),
+    ctx: vscode.ExtensionContext,
+  ) => (() => void) | void;
 }
 
 export function defineTreeView(def: TreeViewDef): TreeViewDef {
@@ -7265,7 +7393,7 @@ export function defineJob(def: JobDef): JobDef {
 }
 `,
     "react/src/shared/vsceasy/index.ts": `export { definePanel, defineCommand, defineMenu, defineStatusBar, defineSubpanel, defineTreeView, defineJob } from './define';
-export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName } from './define';
+export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName, RpcEmit } from './define';
 export { bootstrap } from './bootstrap';
 export type { Registry, BootstrapOptions, ActivateHook } from './bootstrap';
 export {
@@ -7277,6 +7405,9 @@ export {
   webviewState,
 } from './rpc';
 export type { Transport, RpcClient, Handlers, RpcClientOptions, WebviewApi } from './rpc';
+export { defineStore, watch } from './store';
+export type { Store, Watchable } from './store';
+export { listen } from './client';
 `,
     "react/src/shared/vsceasy/rpc.ts": `// Typed RPC bridge — webview <-> extension.
 // Used by both sides. Transport-agnostic core + thin adapters.
@@ -7492,6 +7623,80 @@ export function webviewState<T>(defaults: T): {
     },
   };
 }
+`,
+    "react/src/shared/vsceasy/store.ts": `/**
+ * Reactive stores — a tiny, framework-agnostic observable value.
+ *
+ * A store holds one value and notifies subscribers when it changes. It's the
+ * non-ORM half of the reactivity model: use it for arbitrary state (a counter,
+ * a flag, a selection) that a visual element should track.
+ *
+ *   const counter = defineStore(0);
+ *   counter.subscribe((v) => console.log('now', v));
+ *   counter.set(1);          // logs: now 1
+ *   counter.update((n) => n + 1);
+ *
+ * Pair it with \`watch()\` on the host to push changes to a webview, and
+ * \`listen()\` on the webview to react — see those helpers below and in client.ts.
+ */
+export interface Store<T> {
+  /** Read the current value. */
+  get(): T;
+  /** Replace the value and notify subscribers (no-op if \`Object.is\`-equal). */
+  set(next: T): void;
+  /** Derive the next value from the current one, then \`set\` it. */
+  update(fn: (current: T) => T): void;
+  /** Subscribe to changes. Returns an unsubscribe function. */
+  subscribe(cb: (value: T) => void): () => void;
+}
+
+export function defineStore<T>(initial: T): Store<T> {
+  let value = initial;
+  const subs = new Set<(value: T) => void>();
+
+  return {
+    get: () => value,
+    set(next) {
+      if (Object.is(value, next)) return;
+      value = next;
+      subs.forEach((cb) => {
+        try { cb(value); } catch { /* a bad subscriber must not break a set */ }
+      });
+    },
+    update(fn) {
+      this.set(fn(value));
+    },
+    subscribe(cb) {
+      subs.add(cb);
+      return () => { subs.delete(cb); };
+    },
+  };
+}
+
+/**
+ * Anything that can be watched: it exposes a \`subscribe(cb)\` returning an
+ * unsubscribe function. Stores satisfy this directly. (ORM entities are watched
+ * with \`watchEntity\` from your generated \`db.ts\`, which has the same shape.)
+ */
+export interface Watchable {
+  subscribe(cb: (...args: any[]) => void): () => void;
+}
+
+/**
+ * Bridge a watchable source to a side-effect — typically an RPC emit that pushes
+ * the change to a subscribed webview. Runs \`effect\` on every change. Returns an
+ * unsubscribe function; register it on the panel's \`ctx.subscriptions\` (wrapped
+ * in \`{ dispose }\`) so it's cleaned up when the extension deactivates.
+ *
+ *   // host side, in a panel's rpc():
+ *   watch(badgeCount, () => server.emit('badge:changed'));
+ *
+ * For ORM entities, use \`watchEntity(Todos, () => server.emit('todos:changed'))\`
+ * from your generated db.ts — same idea, same return.
+ */
+export function watch(source: Watchable, effect: () => void): () => void {
+  return source.subscribe(() => effect());
+}
 `,
     "react/src/webview/panels/dashboard/App.tsx": `import React, { useEffect, useState } from 'react';
 import { connectWebview } from '../../../shared/vsceasy/client';
@@ -12853,6 +13058,122 @@ var init_add24 = __esm(() => {
   add_default12 = addComponentsCommand;
 });
 
+// src/lib/store/add.ts
+function addStore(opts) {
+  const name = assertId("store name", normalizeCamel9(opts.name));
+  const type = opts.type ?? "number";
+  const initial = opts.initial?.trim() || DEFAULT_INITIAL[type];
+  const storeTs = path44.join(opts.projectRoot, "src", "stores", `${name}.ts`);
+  assertNoOverwrite(opts.projectRoot, storeTs, "Store");
+  const tplPath = path44.join(opts.templatesRoot, "_generators", "store", "store.ts.tpl");
+  const body = substitute(fs29.readFileSync(tplPath, "utf8"), {
+    name,
+    type: TS_TYPE[type],
+    initial,
+    example: EXAMPLE[type]
+  });
+  fs29.mkdirSync(path44.dirname(storeTs), { recursive: true });
+  fs29.writeFileSync(storeTs, body);
+  return { created: [storeTs] };
+}
+function normalizeCamel9(s) {
+  const cleaned = s.trim().replace(/[^a-zA-Z0-9]+(.)/g, (_m, c) => c.toUpperCase()).replace(/[^a-zA-Z0-9]/g, "");
+  if (!cleaned)
+    return "";
+  return cleaned.charAt(0).toLowerCase() + cleaned.slice(1);
+}
+var fs29, path44, DEFAULT_INITIAL, TS_TYPE, EXAMPLE;
+var init_add25 = __esm(() => {
+  init_scaffold();
+  init_validate();
+  fs29 = __toESM(require("fs"));
+  path44 = __toESM(require("path"));
+  DEFAULT_INITIAL = {
+    number: "0",
+    string: "''",
+    boolean: "false",
+    json: "null"
+  };
+  TS_TYPE = {
+    number: "number",
+    string: "string",
+    boolean: "boolean",
+    json: "any"
+  };
+  EXAMPLE = {
+    number: "1",
+    string: "'hello'",
+    boolean: "true",
+    json: "{ open: true }"
+  };
+});
+
+// src/commands/store/add.ts
+var import_cli_maker20, path45, addStoreCommand, add_default13;
+var init_add26 = __esm(() => {
+  init_add25();
+  init_findProject();
+  import_cli_maker20 = __toESM(require_dist(), 1);
+  path45 = __toESM(require("path"));
+  addStoreCommand = {
+    name: "add",
+    description: "Add a reactive store (an observable value) under src/stores/. Watch it on the host and listen in a webview to keep UI in sync.",
+    params: [
+      { name: "name", description: "Store name (camelCase, e.g. badgeCount)", required: true, type: import_cli_maker20.ParamType.Text },
+      {
+        name: "type",
+        description: "Value type",
+        required: false,
+        type: import_cli_maker20.ParamType.List,
+        options: ["number", "string", "boolean", "json"]
+      },
+      {
+        name: "initial",
+        description: "Initial value expression (default per type: 0 / '' / false / null)",
+        required: false,
+        type: import_cli_maker20.ParamType.Text
+      }
+    ],
+    action: async (args) => {
+      try {
+        const projectRoot = findProjectRoot();
+        const templatesRoot = findTemplatesRoot();
+        const result = addStore({
+          name: String(args.name).trim(),
+          type: args.type ? String(args.type) : undefined,
+          initial: args.initial ? String(args.initial) : undefined,
+          projectRoot,
+          templatesRoot
+        });
+        const rel = (p) => path45.relative(projectRoot, p);
+        const name = String(args.name).trim();
+        console.log(`
+✓ Store "${name}" created.
+`);
+        for (const f of result.created)
+          console.log(`  + ${rel(f)}`);
+        console.log(`
+  Use it:
+    import { ${name} } from '../stores/${name}';
+    ${name}.set(...);  ${name}.update((v) => v);
+`);
+        console.log(`  Push changes to a webview — host side, in a panel rpc():
+    watch(${name}, () => server.emit('${name}:changed', ${name}.get()));
+`);
+        console.log(`  React in the webview:
+    listen(api, '${name}:changed', (v) => render(v));
+`);
+      } catch (err) {
+        console.error(`
+✗ ${err.message}
+`);
+        process.exitCode = 1;
+      }
+    }
+  };
+  add_default13 = addStoreCommand;
+});
+
 // src/commands/groups.ts
 function group(name, description, subcommands) {
   return {
@@ -12869,7 +13190,7 @@ Use one of: ${subcommands.map((s) => s.name).join(", ")}
     }
   };
 }
-var PanelGroup, MenuGroup, CommandGroup, RpcGroup, StatusBarGroup, SubpanelGroup, TreeViewGroup, TestGroup, PublishGroup, HelperGroup, JobGroup, DbGroup, ModelGroup, CrudGroup, ComponentsGroup;
+var PanelGroup, MenuGroup, CommandGroup, RpcGroup, StatusBarGroup, SubpanelGroup, TreeViewGroup, TestGroup, PublishGroup, HelperGroup, JobGroup, DbGroup, ModelGroup, CrudGroup, ComponentsGroup, StoreGroup;
 var init_groups = __esm(() => {
   init_add6();
   init_add8();
@@ -12887,6 +13208,7 @@ var init_groups = __esm(() => {
   init_add21();
   init_add23();
   init_add24();
+  init_add26();
   PanelGroup = group("panel", "Manage panels (webview + RPC bridge)", [add_default]);
   MenuGroup = group("menu", "Manage sidebar menus (activity bar tree views)", [add_default2, edit_default]);
   CommandGroup = group("command", "Manage palette commands", [add_default3]);
@@ -12902,6 +13224,7 @@ var init_groups = __esm(() => {
   ModelGroup = group("model", "Manage typed models (entities + repos) under src/models/", [add_default10]);
   CrudGroup = group("crud", "Scaffold full CRUD UI (service + list panel + form panel + RPC) for a model", [add_default11]);
   ComponentsGroup = group("components", "Generate a theme-aware React component library for webviews", [add_default12]);
+  StoreGroup = group("store", "Manage reactive stores (observable values) under src/stores/", [add_default13]);
 });
 
 // src/cli.ts
@@ -12909,17 +13232,17 @@ var exports_cli = {};
 __export(exports_cli, {
   cli: () => cli
 });
-var import_cli_maker20, cli;
+var import_cli_maker21, cli;
 var init_cli = __esm(() => {
   init_create();
   init_wizard();
   init_doctor2();
   init_upgrade2();
   init_groups();
-  import_cli_maker20 = __toESM(require_dist(), 1);
-  cli = new import_cli_maker20.CLI("vsceasy", "Build VS Code extensions fast — React UI + typed RPC bridge + zero-config build.", {
+  import_cli_maker21 = __toESM(require_dist(), 1);
+  cli = new import_cli_maker21.CLI("vsceasy", "Build VS Code extensions fast — React UI + typed RPC bridge + zero-config build.", {
     interactive: true,
-    version: "0.1.7",
+    version: "0.1.8",
     introAnimation: {
       enabled: true,
       preset: "retro-space",
@@ -12957,6 +13280,7 @@ var init_cli = __esm(() => {
   cli.command(ModelGroup);
   cli.command(CrudGroup);
   cli.command(ComponentsGroup);
+  cli.command(StoreGroup);
   cli.command(doctor_default);
   cli.command(upgrade_default);
   cli.parse(process.argv);

package/dist/commands/groups.d.ts

@@ -14,3 +14,4 @@ export declare const DbGroup: Command;
 export declare const ModelGroup: Command;
 export declare const CrudGroup: Command;
 export declare const ComponentsGroup: Command;
+export declare const StoreGroup: Command;

package/dist/commands/store/add.d.ts

@@ -0,0 +1,3 @@
+import { Command } from '@ideascol/cli-maker';
+declare const addStoreCommand: Command;
+export default addStoreCommand;

package/dist/index.js

@@ -2238,7 +2238,7 @@ var init_upgrade = __esm(() => {
 });
 
 // src/lib/templatesData.ts
-var TEMPLATES_VERSION = "0.1.7", TEMPLATE_FILES;
+var TEMPLATES_VERSION = "0.1.8", TEMPLATE_FILES;
 var init_templatesData = __esm(() => {
   TEMPLATE_FILES = {
     "_generators/command/command.ts.tpl": `import { defineCommand } from '../shared/vsceasy';
@@ -2950,6 +2950,35 @@ export interface Repository<T> {
   clear(): Promise<void>;
 }
 
+// ── Change notifications (reactivity) ────────────────────────────────────────
+
+/**
+ * Per-entity change listeners. Any mutation (insert/upsert/update/delete/...) on
+ * an entity fires its listeners with the entity name. This is the host-side hook
+ * the \`watch()\` helper builds on to push updates to webviews.
+ */
+const entityListeners = new Map<string, Set<(entity: string) => void>>();
+
+function emitChange(entity: string): void {
+  entityListeners.get(entity)?.forEach((cb) => {
+    try { cb(entity); } catch { /* a bad listener must not break a write */ }
+  });
+}
+
+/**
+ * Subscribe to changes on an entity. Returns an unsubscribe function.
+ *
+ *   watchEntity(Todos, () => server.emit('todos:changed'));
+ *
+ * Prefer the higher-level \`watch()\` helper, which wires this to an RPC emit.
+ */
+export function watchEntity<T>(entity: Entity<T>, cb: (entity: string) => void): () => void {
+  let set = entityListeners.get(entity.name);
+  if (!set) entityListeners.set(entity.name, (set = new Set()));
+  set.add(cb);
+  return () => { set!.delete(cb); };
+}
+
 // ── Provider interface (future-proof for sqlite/etc.) ────────────────────────
 
 export interface Provider {
@@ -3120,6 +3149,7 @@ function makeDb(provider: Provider): Db {
         }
         rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async upsert(row) {
@@ -3127,6 +3157,7 @@ function makeDb(provider: Provider): Db {
         const i = rows.findIndex((r) => r[pk] === row[pk]);
         if (i >= 0) rows[i] = row; else rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async update(id, patch) {
@@ -3135,6 +3166,7 @@ function makeDb(provider: Provider): Db {
         if (i < 0) return null;
         rows[i] = { ...rows[i], ...patch };
         await save(rows);
+        emitChange(entity.name);
         return rows[i];
       },
       async delete(id) {
@@ -3143,17 +3175,19 @@ function makeDb(provider: Provider): Db {
         const next = rows.filter((r) => r[pk] !== id);
         if (next.length === before) return false;
         await save(next);
+        emitChange(entity.name);
         return true;
       },
       async deleteMany(where) {
         const rows = await load();
         const next = rows.filter((r) => !match(r, where));
         const removed = rows.length - next.length;
-        if (removed > 0) await save(next);
+        if (removed > 0) { await save(next); emitChange(entity.name); }
         return removed;
       },
       async clear() {
         await save([]);
+        emitChange(entity.name);
       },
     };
   };
@@ -3578,6 +3612,30 @@ export default defineStatusBar({
   alignment: '{{alignment}}',
   priority: {{priority}},{{commandLine}}{{panelLine}}
 });
+`,
+    "_generators/store/store.ts.tpl": `import { defineStore } from '../shared/vsceasy';
+
+/**
+ * Reactive store: a single observable value. Mutate it with \`.set()\` / \`.update()\`
+ * and anything subscribed reacts.
+ *
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   {{name}}.set({{example}});
+ *   {{name}}.update((v) => v);
+ *
+ * To push changes to a webview, watch it on the host and emit over RPC:
+ *
+ *   // inside a panel/subpanel rpc():
+ *   import { watch } from '../shared/vsceasy';
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   watch({{name}}, () => server.emit('{{name}}:changed', {{name}}.get()));
+ *
+ * Then listen in the webview:
+ *
+ *   import { listen } from '../shared/vsceasy/client';
+ *   listen(api, '{{name}}:changed', (v) => render(v));
+ */
+export const {{name}} = defineStore<{{type}}>({{initial}});
 `,
     "_generators/subpanel/App.tsx.tpl": `import React from 'react';
 {{apiBlock}}
@@ -4774,6 +4832,13 @@ function registerTreeView(
     vscode.commands.registerCommand(refreshCmd, () => provider.refresh()),
   );
 
+  // Keep the tree live: let the def subscribe to a data source and re-run
+  // getChildren on change. The unsubscribe is disposed on deactivate.
+  if (def.watch) {
+    const off = def.watch(() => provider.refresh(), vscode, context);
+    if (off) context.subscriptions.push({ dispose: off });
+  }
+
   const dispatchCmd = \`\${registry.prefix}._tree.\${def.id ?? id}.run\`;
   context.subscriptions.push(
     vscode.commands.registerCommand(dispatchCmd, async (node: TreeNode) => {
@@ -4850,9 +4915,11 @@ function registerSubpanel(
       const ui = def.ui ?? \`subpanels/\${def.id ?? id}\`;
       view.webview.html = renderHtml(view.webview, context, ui, def.title);
       if (def.rpc) {
-        const handlers = def.rpc(vscode, context);
-        const server = createRpcServer(webviewTransport(view.webview), handlers);
-        view.onDidDispose(() => server.dispose());
+        let server: ReturnType<typeof createRpcServer> | undefined;
+        const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+        const handlers = def.rpc(vscode, context, emit);
+        server = createRpcServer(webviewTransport(view.webview), handlers);
+        view.onDidDispose(() => server!.dispose());
       }
     },
   };
@@ -5088,9 +5155,13 @@ function openPanel(context: vscode.ExtensionContext, prefix: string, id: string,
   panel.webview.html = renderHtml(panel.webview, context, ui, def.title);
 
   if (def.rpc) {
-    const handlers = def.rpc(vscode, context);
-    const server = createRpcServer(webviewTransport(panel.webview), handlers);
-    panel.onDidDispose(() => server.dispose());
+    // \`emit\` is wired lazily: the rpc factory may call watch()/watchEntity()
+    // immediately, but the server (and thus the real emit) only exists after.
+    let server: ReturnType<typeof createRpcServer> | undefined;
+    const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+    const handlers = def.rpc(vscode, context, emit);
+    server = createRpcServer(webviewTransport(panel.webview), handlers);
+    panel.onDidDispose(() => server!.dispose());
   }
 
   openPanels.set(key, panel);
@@ -5208,6 +5279,33 @@ export {
   webviewState,
 } from './rpc';
 export type { RpcClient, Handlers, Transport, RpcClientOptions, WebviewApi } from './rpc';
+
+export { defineStore } from './store';
+export type { Store } from './store';
+
+import type { RpcClient, Handlers } from './rpc';
+
+/**
+ * Listen for a change pushed from the host over the RPC event channel, and run a
+ * callback when it arrives. This is the webview side of the reactivity model —
+ * the host emits with \`server.emit(topic, …)\` (usually wired via \`watch()\` /
+ * \`watchEntity()\`), and your visual element reacts here. Returns an unsubscribe
+ * function; call it on unmount.
+ *
+ *   const api = connectWebview<TodoStatsViewApi>();
+ *   // re-read + re-render whenever todos change on the host:
+ *   const off = listen(api, 'todos:changed', () => refresh());
+ *
+ * It's a thin, named wrapper over \`api.on(topic, handler)\` so the place you
+ * listen reads clearly in the UI code. The payload (if any) is passed through.
+ */
+export function listen<H extends Handlers>(
+  api: RpcClient<H>,
+  topic: string,
+  handler: (payload?: unknown) => void,
+): () => void {
+  return api.on(topic, handler);
+}
 `,
     "react/src/shared/vsceasy/codiconNames.ts": `/**
  * AUTO-GENERATED by scripts/genCodiconTypes.ts — do not edit.
@@ -5410,6 +5508,18 @@ export type CodiconName =
 import type { Handlers } from './rpc';
 import type { CodiconName } from './codiconNames';
 
+/**
+ * Push a change to this webview over the RPC event channel. The webview reacts
+ * with \`listen(api, topic, …)\`. Wire it to a data source with \`watch()\` /
+ * \`watchEntity()\` inside \`rpc()\`:
+ *
+ *   rpc: (vscode, ctx, emit) => {
+ *     watchEntity(Todos, () => emit('todos:changed'));
+ *     return { stats: () => … };
+ *   }
+ */
+export type RpcEmit = (topic: string, payload?: unknown) => void;
+
 export interface PanelDef<H extends Handlers = Handlers> {
   /** Stable id. Default: file basename. Used as command suffix and webview key. */
   id?: string;
@@ -5421,8 +5531,11 @@ export interface PanelDef<H extends Handlers = Handlers> {
   column?: 'active' | 'beside' | 'one' | 'two' | 'three';
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * \`emit\` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
   /** Optional command palette entry that opens this panel. Default: true. */
   command?:
     | boolean
@@ -5533,8 +5646,11 @@ export interface SubpanelDef<H extends Handlers = Handlers> {
   ui?: string;
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * \`emit\` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
 }
 
 export function defineSubpanel<H extends Handlers = Handlers>(def: SubpanelDef<H>): SubpanelDef<H> {
@@ -5636,6 +5752,18 @@ export interface TreeViewDef {
     vscode: typeof import('vscode'),
     ctx: vscode.ExtensionContext,
   ) => TreeNode[] | Promise<TreeNode[]>;
+  /**
+   * Keep the tree live. Receives \`refresh\` — call it (directly or as a callback)
+   * to re-run \`getChildren\`. Subscribe to a data source here so the tree updates
+   * itself; return an unsubscribe to clean up.
+   *
+   *   watch: (refresh) => watchEntity(Todos, refresh),
+   */
+  watch?: (
+    refresh: () => void,
+    vscode: typeof import('vscode'),
+    ctx: vscode.ExtensionContext,
+  ) => (() => void) | void;
 }
 
 export function defineTreeView(def: TreeViewDef): TreeViewDef {
@@ -5677,7 +5805,7 @@ export function defineJob(def: JobDef): JobDef {
 }
 `,
     "react/src/shared/vsceasy/index.ts": `export { definePanel, defineCommand, defineMenu, defineStatusBar, defineSubpanel, defineTreeView, defineJob } from './define';
-export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName } from './define';
+export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName, RpcEmit } from './define';
 export { bootstrap } from './bootstrap';
 export type { Registry, BootstrapOptions, ActivateHook } from './bootstrap';
 export {
@@ -5689,6 +5817,9 @@ export {
   webviewState,
 } from './rpc';
 export type { Transport, RpcClient, Handlers, RpcClientOptions, WebviewApi } from './rpc';
+export { defineStore, watch } from './store';
+export type { Store, Watchable } from './store';
+export { listen } from './client';
 `,
     "react/src/shared/vsceasy/rpc.ts": `// Typed RPC bridge — webview <-> extension.
 // Used by both sides. Transport-agnostic core + thin adapters.
@@ -5904,6 +6035,80 @@ export function webviewState<T>(defaults: T): {
     },
   };
 }
+`,
+    "react/src/shared/vsceasy/store.ts": `/**
+ * Reactive stores — a tiny, framework-agnostic observable value.
+ *
+ * A store holds one value and notifies subscribers when it changes. It's the
+ * non-ORM half of the reactivity model: use it for arbitrary state (a counter,
+ * a flag, a selection) that a visual element should track.
+ *
+ *   const counter = defineStore(0);
+ *   counter.subscribe((v) => console.log('now', v));
+ *   counter.set(1);          // logs: now 1
+ *   counter.update((n) => n + 1);
+ *
+ * Pair it with \`watch()\` on the host to push changes to a webview, and
+ * \`listen()\` on the webview to react — see those helpers below and in client.ts.
+ */
+export interface Store<T> {
+  /** Read the current value. */
+  get(): T;
+  /** Replace the value and notify subscribers (no-op if \`Object.is\`-equal). */
+  set(next: T): void;
+  /** Derive the next value from the current one, then \`set\` it. */
+  update(fn: (current: T) => T): void;
+  /** Subscribe to changes. Returns an unsubscribe function. */
+  subscribe(cb: (value: T) => void): () => void;
+}
+
+export function defineStore<T>(initial: T): Store<T> {
+  let value = initial;
+  const subs = new Set<(value: T) => void>();
+
+  return {
+    get: () => value,
+    set(next) {
+      if (Object.is(value, next)) return;
+      value = next;
+      subs.forEach((cb) => {
+        try { cb(value); } catch { /* a bad subscriber must not break a set */ }
+      });
+    },
+    update(fn) {
+      this.set(fn(value));
+    },
+    subscribe(cb) {
+      subs.add(cb);
+      return () => { subs.delete(cb); };
+    },
+  };
+}
+
+/**
+ * Anything that can be watched: it exposes a \`subscribe(cb)\` returning an
+ * unsubscribe function. Stores satisfy this directly. (ORM entities are watched
+ * with \`watchEntity\` from your generated \`db.ts\`, which has the same shape.)
+ */
+export interface Watchable {
+  subscribe(cb: (...args: any[]) => void): () => void;
+}
+
+/**
+ * Bridge a watchable source to a side-effect — typically an RPC emit that pushes
+ * the change to a subscribed webview. Runs \`effect\` on every change. Returns an
+ * unsubscribe function; register it on the panel's \`ctx.subscriptions\` (wrapped
+ * in \`{ dispose }\`) so it's cleaned up when the extension deactivates.
+ *
+ *   // host side, in a panel's rpc():
+ *   watch(badgeCount, () => server.emit('badge:changed'));
+ *
+ * For ORM entities, use \`watchEntity(Todos, () => server.emit('todos:changed'))\`
+ * from your generated db.ts — same idea, same return.
+ */
+export function watch(source: Watchable, effect: () => void): () => void {
+  return source.subscribe(() => effect());
+}
 `,
     "react/src/webview/panels/dashboard/App.tsx": `import React, { useEffect, useState } from 'react';
 import { connectWebview } from '../../../shared/vsceasy/client';

package/dist/lib/store/add.d.ts

@@ -0,0 +1,14 @@
+export type StoreType = 'number' | 'string' | 'boolean' | 'json';
+export interface AddStoreOptions {
+    name: string;
+    /** Value type. Default: 'number'. */
+    type?: StoreType;
+    /** Raw initial value expression. Defaults per type (0 / '' / false / null). */
+    initial?: string;
+    projectRoot: string;
+    templatesRoot: string;
+}
+export interface AddStoreResult {
+    created: string[];
+}
+export declare function addStore(opts: AddStoreOptions): AddStoreResult;

package/dist/lib/templatesData.d.ts

@@ -1,2 +1,2 @@
-export declare const TEMPLATES_VERSION = "0.1.7";
+export declare const TEMPLATES_VERSION = "0.1.8";
 export declare const TEMPLATE_FILES: Record<string, string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsceasy/cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Build VS Code extensions fast — React UI + typed RPC bridge between extension and webview + file-based routing for panels, commands, menus, tree views, and subpanels.",
   "main": "dist/index.js",
   "scripts": {

package/templates/_generators/helper/db.ts.tpl

@@ -64,6 +64,35 @@ export interface Repository<T> {
   clear(): Promise<void>;
 }
 
+// ── Change notifications (reactivity) ────────────────────────────────────────
+
+/**
+ * Per-entity change listeners. Any mutation (insert/upsert/update/delete/...) on
+ * an entity fires its listeners with the entity name. This is the host-side hook
+ * the `watch()` helper builds on to push updates to webviews.
+ */
+const entityListeners = new Map<string, Set<(entity: string) => void>>();
+
+function emitChange(entity: string): void {
+  entityListeners.get(entity)?.forEach((cb) => {
+    try { cb(entity); } catch { /* a bad listener must not break a write */ }
+  });
+}
+
+/**
+ * Subscribe to changes on an entity. Returns an unsubscribe function.
+ *
+ *   watchEntity(Todos, () => server.emit('todos:changed'));
+ *
+ * Prefer the higher-level `watch()` helper, which wires this to an RPC emit.
+ */
+export function watchEntity<T>(entity: Entity<T>, cb: (entity: string) => void): () => void {
+  let set = entityListeners.get(entity.name);
+  if (!set) entityListeners.set(entity.name, (set = new Set()));
+  set.add(cb);
+  return () => { set!.delete(cb); };
+}
+
 // ── Provider interface (future-proof for sqlite/etc.) ────────────────────────
 
 export interface Provider {
@@ -234,6 +263,7 @@ function makeDb(provider: Provider): Db {
         }
         rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async upsert(row) {
@@ -241,6 +271,7 @@ function makeDb(provider: Provider): Db {
         const i = rows.findIndex((r) => r[pk] === row[pk]);
         if (i >= 0) rows[i] = row; else rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async update(id, patch) {
@@ -249,6 +280,7 @@ function makeDb(provider: Provider): Db {
         if (i < 0) return null;
         rows[i] = { ...rows[i], ...patch };
         await save(rows);
+        emitChange(entity.name);
         return rows[i];
       },
       async delete(id) {
@@ -257,17 +289,19 @@ function makeDb(provider: Provider): Db {
         const next = rows.filter((r) => r[pk] !== id);
         if (next.length === before) return false;
         await save(next);
+        emitChange(entity.name);
         return true;
       },
       async deleteMany(where) {
         const rows = await load();
         const next = rows.filter((r) => !match(r, where));
         const removed = rows.length - next.length;
-        if (removed > 0) await save(next);
+        if (removed > 0) { await save(next); emitChange(entity.name); }
         return removed;
       },
       async clear() {
         await save([]);
+        emitChange(entity.name);
       },
     };
   };

package/templates/_generators/store/store.ts.tpl

@@ -0,0 +1,23 @@
+import { defineStore } from '../shared/vsceasy';
+
+/**
+ * Reactive store: a single observable value. Mutate it with `.set()` / `.update()`
+ * and anything subscribed reacts.
+ *
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   {{name}}.set({{example}});
+ *   {{name}}.update((v) => v);
+ *
+ * To push changes to a webview, watch it on the host and emit over RPC:
+ *
+ *   // inside a panel/subpanel rpc():
+ *   import { watch } from '../shared/vsceasy';
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   watch({{name}}, () => server.emit('{{name}}:changed', {{name}}.get()));
+ *
+ * Then listen in the webview:
+ *
+ *   import { listen } from '../shared/vsceasy/client';
+ *   listen(api, '{{name}}:changed', (v) => render(v));
+ */
+export const {{name}} = defineStore<{{type}}>({{initial}});

package/templates/react/src/shared/vsceasy/bootstrap.ts

@@ -230,6 +230,13 @@ function registerTreeView(
     vscode.commands.registerCommand(refreshCmd, () => provider.refresh()),
   );
 
+  // Keep the tree live: let the def subscribe to a data source and re-run
+  // getChildren on change. The unsubscribe is disposed on deactivate.
+  if (def.watch) {
+    const off = def.watch(() => provider.refresh(), vscode, context);
+    if (off) context.subscriptions.push({ dispose: off });
+  }
+
   const dispatchCmd = `${registry.prefix}._tree.${def.id ?? id}.run`;
   context.subscriptions.push(
     vscode.commands.registerCommand(dispatchCmd, async (node: TreeNode) => {
@@ -306,9 +313,11 @@ function registerSubpanel(
       const ui = def.ui ?? `subpanels/${def.id ?? id}`;
       view.webview.html = renderHtml(view.webview, context, ui, def.title);
       if (def.rpc) {
-        const handlers = def.rpc(vscode, context);
-        const server = createRpcServer(webviewTransport(view.webview), handlers);
-        view.onDidDispose(() => server.dispose());
+        let server: ReturnType<typeof createRpcServer> | undefined;
+        const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+        const handlers = def.rpc(vscode, context, emit);
+        server = createRpcServer(webviewTransport(view.webview), handlers);
+        view.onDidDispose(() => server!.dispose());
       }
     },
   };
@@ -544,9 +553,13 @@ function openPanel(context: vscode.ExtensionContext, prefix: string, id: string,
   panel.webview.html = renderHtml(panel.webview, context, ui, def.title);
 
   if (def.rpc) {
-    const handlers = def.rpc(vscode, context);
-    const server = createRpcServer(webviewTransport(panel.webview), handlers);
-    panel.onDidDispose(() => server.dispose());
+    // `emit` is wired lazily: the rpc factory may call watch()/watchEntity()
+    // immediately, but the server (and thus the real emit) only exists after.
+    let server: ReturnType<typeof createRpcServer> | undefined;
+    const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+    const handlers = def.rpc(vscode, context, emit);
+    server = createRpcServer(webviewTransport(panel.webview), handlers);
+    panel.onDidDispose(() => server!.dispose());
   }
 
   openPanels.set(key, panel);

package/templates/react/src/shared/vsceasy/client.ts

@@ -6,3 +6,30 @@ export {
   webviewState,
 } from './rpc';
 export type { RpcClient, Handlers, Transport, RpcClientOptions, WebviewApi } from './rpc';
+
+export { defineStore } from './store';
+export type { Store } from './store';
+
+import type { RpcClient, Handlers } from './rpc';
+
+/**
+ * Listen for a change pushed from the host over the RPC event channel, and run a
+ * callback when it arrives. This is the webview side of the reactivity model —
+ * the host emits with `server.emit(topic, …)` (usually wired via `watch()` /
+ * `watchEntity()`), and your visual element reacts here. Returns an unsubscribe
+ * function; call it on unmount.
+ *
+ *   const api = connectWebview<TodoStatsViewApi>();
+ *   // re-read + re-render whenever todos change on the host:
+ *   const off = listen(api, 'todos:changed', () => refresh());
+ *
+ * It's a thin, named wrapper over `api.on(topic, handler)` so the place you
+ * listen reads clearly in the UI code. The payload (if any) is passed through.
+ */
+export function listen<H extends Handlers>(
+  api: RpcClient<H>,
+  topic: string,
+  handler: (payload?: unknown) => void,
+): () => void {
+  return api.on(topic, handler);
+}

package/templates/react/src/shared/vsceasy/define.ts

@@ -2,6 +2,18 @@ import type * as vscode from 'vscode';
 import type { Handlers } from './rpc';
 import type { CodiconName } from './codiconNames';
 
+/**
+ * Push a change to this webview over the RPC event channel. The webview reacts
+ * with `listen(api, topic, …)`. Wire it to a data source with `watch()` /
+ * `watchEntity()` inside `rpc()`:
+ *
+ *   rpc: (vscode, ctx, emit) => {
+ *     watchEntity(Todos, () => emit('todos:changed'));
+ *     return { stats: () => … };
+ *   }
+ */
+export type RpcEmit = (topic: string, payload?: unknown) => void;
+
 export interface PanelDef<H extends Handlers = Handlers> {
   /** Stable id. Default: file basename. Used as command suffix and webview key. */
   id?: string;
@@ -13,8 +25,11 @@ export interface PanelDef<H extends Handlers = Handlers> {
   column?: 'active' | 'beside' | 'one' | 'two' | 'three';
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * `emit` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
   /** Optional command palette entry that opens this panel. Default: true. */
   command?:
     | boolean
@@ -125,8 +140,11 @@ export interface SubpanelDef<H extends Handlers = Handlers> {
   ui?: string;
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * `emit` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
 }
 
 export function defineSubpanel<H extends Handlers = Handlers>(def: SubpanelDef<H>): SubpanelDef<H> {
@@ -228,6 +246,18 @@ export interface TreeViewDef {
     vscode: typeof import('vscode'),
     ctx: vscode.ExtensionContext,
   ) => TreeNode[] | Promise<TreeNode[]>;
+  /**
+   * Keep the tree live. Receives `refresh` — call it (directly or as a callback)
+   * to re-run `getChildren`. Subscribe to a data source here so the tree updates
+   * itself; return an unsubscribe to clean up.
+   *
+   *   watch: (refresh) => watchEntity(Todos, refresh),
+   */
+  watch?: (
+    refresh: () => void,
+    vscode: typeof import('vscode'),
+    ctx: vscode.ExtensionContext,
+  ) => (() => void) | void;
 }
 
 export function defineTreeView(def: TreeViewDef): TreeViewDef {

package/templates/react/src/shared/vsceasy/index.ts

@@ -1,5 +1,5 @@
 export { definePanel, defineCommand, defineMenu, defineStatusBar, defineSubpanel, defineTreeView, defineJob } from './define';
-export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName } from './define';
+export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName, RpcEmit } from './define';
 export { bootstrap } from './bootstrap';
 export type { Registry, BootstrapOptions, ActivateHook } from './bootstrap';
 export {
@@ -11,3 +11,6 @@ export {
   webviewState,
 } from './rpc';
 export type { Transport, RpcClient, Handlers, RpcClientOptions, WebviewApi } from './rpc';
+export { defineStore, watch } from './store';
+export type { Store, Watchable } from './store';
+export { listen } from './client';

package/templates/react/src/shared/vsceasy/store.ts

@@ -0,0 +1,73 @@
+/**
+ * Reactive stores — a tiny, framework-agnostic observable value.
+ *
+ * A store holds one value and notifies subscribers when it changes. It's the
+ * non-ORM half of the reactivity model: use it for arbitrary state (a counter,
+ * a flag, a selection) that a visual element should track.
+ *
+ *   const counter = defineStore(0);
+ *   counter.subscribe((v) => console.log('now', v));
+ *   counter.set(1);          // logs: now 1
+ *   counter.update((n) => n + 1);
+ *
+ * Pair it with `watch()` on the host to push changes to a webview, and
+ * `listen()` on the webview to react — see those helpers below and in client.ts.
+ */
+export interface Store<T> {
+  /** Read the current value. */
+  get(): T;
+  /** Replace the value and notify subscribers (no-op if `Object.is`-equal). */
+  set(next: T): void;
+  /** Derive the next value from the current one, then `set` it. */
+  update(fn: (current: T) => T): void;
+  /** Subscribe to changes. Returns an unsubscribe function. */
+  subscribe(cb: (value: T) => void): () => void;
+}
+
+export function defineStore<T>(initial: T): Store<T> {
+  let value = initial;
+  const subs = new Set<(value: T) => void>();
+
+  return {
+    get: () => value,
+    set(next) {
+      if (Object.is(value, next)) return;
+      value = next;
+      subs.forEach((cb) => {
+        try { cb(value); } catch { /* a bad subscriber must not break a set */ }
+      });
+    },
+    update(fn) {
+      this.set(fn(value));
+    },
+    subscribe(cb) {
+      subs.add(cb);
+      return () => { subs.delete(cb); };
+    },
+  };
+}
+
+/**
+ * Anything that can be watched: it exposes a `subscribe(cb)` returning an
+ * unsubscribe function. Stores satisfy this directly. (ORM entities are watched
+ * with `watchEntity` from your generated `db.ts`, which has the same shape.)
+ */
+export interface Watchable {
+  subscribe(cb: (...args: any[]) => void): () => void;
+}
+
+/**
+ * Bridge a watchable source to a side-effect — typically an RPC emit that pushes
+ * the change to a subscribed webview. Runs `effect` on every change. Returns an
+ * unsubscribe function; register it on the panel's `ctx.subscriptions` (wrapped
+ * in `{ dispose }`) so it's cleaned up when the extension deactivates.
+ *
+ *   // host side, in a panel's rpc():
+ *   watch(badgeCount, () => server.emit('badge:changed'));
+ *
+ * For ORM entities, use `watchEntity(Todos, () => server.emit('todos:changed'))`
+ * from your generated db.ts — same idea, same return.
+ */
+export function watch(source: Watchable, effect: () => void): () => void {
+  return source.subscribe(() => effect());
+}