@vsceasy/cli 0.1.3 → 0.1.5

package/dist/index.js

@@ -2237,6 +2237,3796 @@ var init_upgrade = __esm(() => {
   ];
 });
 
+// src/lib/templatesData.ts
+var TEMPLATES_VERSION = "0.1.5", TEMPLATE_FILES;
+var init_templatesData = __esm(() => {
+  TEMPLATE_FILES = {
+    "_generators/command/command.ts.tpl": `import { defineCommand } from '../shared/vsceasy';
+
+export default defineCommand({
+  title: '{{title}}',{{categoryLine}}{{keybindingLine}}{{whenLine}}
+  run: (vscode) => {
+    vscode.window.showInformationMessage('{{title}} ran');
+  },
+});
+`,
+    "_generators/components/Button.tsx.tpl": `import React from 'react';
+
+type Variant = 'primary' | 'secondary';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: Variant;
+}
+
+/** Theme-aware button using VS Code button tokens. */
+export function Button({ variant = 'primary', className = '', ...rest }: ButtonProps) {
+  return <button className={\`vx-btn vx-btn--\${variant} \${className}\`.trim()} {...rest} />;
+}
+`,
+    "_generators/components/Card.tsx.tpl": `import React from 'react';
+
+export interface CardProps {
+  title?: string;
+  actions?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+/** Bordered surface for grouping content, with an optional title + actions row. */
+export function Card({ title, actions, children }: CardProps) {
+  return (
+    <section className="vx-card">
+      {(title || actions) && (
+        <header className="vx-card__head">
+          {title ? <h2 className="vx-card__title">{title}</h2> : <span />}
+          {actions ? <div className="vx-card__actions">{actions}</div> : null}
+        </header>
+      )}
+      <div className="vx-card__body">{children}</div>
+    </section>
+  );
+}
+`,
+    "_generators/components/Field.tsx.tpl": `import React from 'react';
+
+export interface FieldProps {
+  label: string;
+  htmlFor?: string;
+  hint?: string;
+  error?: string;
+  children: React.ReactNode;
+}
+
+/** Labeled form field wrapper with optional hint / error text. */
+export function Field({ label, htmlFor, hint, error, children }: FieldProps) {
+  return (
+    <div className="vx-field">
+      <label className="vx-field__label" htmlFor={htmlFor}>{label}</label>
+      {children}
+      {error ? <span className="vx-field__error">{error}</span> : hint ? <span className="vx-field__hint">{hint}</span> : null}
+    </div>
+  );
+}
+`,
+    "_generators/components/Input.tsx.tpl": `import React from 'react';
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+/** Theme-aware text input using VS Code input tokens. */
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  function Input({ className = '', ...rest }, ref) {
+    return <input ref={ref} className={\`vx-input \${className}\`.trim()} {...rest} />;
+  },
+);
+`,
+    "_generators/components/List.tsx.tpl": `import React from 'react';
+
+export interface ListProps<T> {
+  items: T[];
+  getKey: (item: T, index: number) => string | number;
+  renderItem: (item: T, index: number) => React.ReactNode;
+  onSelect?: (item: T, index: number) => void;
+  empty?: React.ReactNode;
+}
+
+/** Selectable, theme-aware list. Rows highlight on hover and on selection. */
+export function List<T>({ items, getKey, renderItem, onSelect, empty }: ListProps<T>) {
+  if (items.length === 0) {
+    return <div className="vx-list__empty">{empty ?? 'Nothing here yet.'}</div>;
+  }
+  return (
+    <ul className="vx-list" role="list">
+      {items.map((item, i) => (
+        <li
+          key={getKey(item, i)}
+          className={\`vx-list__row\${onSelect ? ' vx-list__row--clickable' : ''}\`}
+          onClick={onSelect ? () => onSelect(item, i) : undefined}
+        >
+          {renderItem(item, i)}
+        </li>
+      ))}
+    </ul>
+  );
+}
+`,
+    "_generators/components/components.css.tpl": `.vx-btn {
+  font: inherit;
+  padding: 0.35rem 0.85rem;
+  border-radius: 2px;
+  border: 1px solid transparent;
+  cursor: pointer;
+}
+.vx-btn:focus-visible { outline: 1px solid var(--vscode-focusBorder); outline-offset: 2px; }
+.vx-btn:disabled { opacity: 0.5; cursor: default; }
+.vx-btn--primary {
+  color: var(--vscode-button-foreground);
+  background: var(--vscode-button-background);
+}
+.vx-btn--primary:hover:not(:disabled) { background: var(--vscode-button-hoverBackground); }
+.vx-btn--secondary {
+  color: var(--vscode-button-secondaryForeground, var(--vscode-foreground));
+  background: var(--vscode-button-secondaryBackground, transparent);
+  border-color: var(--vscode-button-border, var(--vscode-input-border, #555));
+}
+.vx-btn--secondary:hover:not(:disabled) { background: var(--vscode-button-secondaryHoverBackground, var(--vscode-list-hoverBackground)); }
+
+.vx-input {
+  font: inherit;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 0.35rem 0.5rem;
+  border-radius: 2px;
+  color: var(--vscode-input-foreground);
+  background: var(--vscode-input-background);
+  border: 1px solid var(--vscode-input-border, #555);
+}
+.vx-input:focus-visible { outline: 1px solid var(--vscode-focusBorder); outline-offset: -1px; }
+.vx-input::placeholder { color: var(--vscode-input-placeholderForeground); }
+
+.vx-field { display: flex; flex-direction: column; gap: 0.25rem; margin-bottom: 0.75rem; }
+.vx-field__label { font-size: 0.85em; color: var(--vscode-foreground); }
+.vx-field__hint { font-size: 0.8em; color: var(--vscode-descriptionForeground); }
+.vx-field__error { font-size: 0.8em; color: var(--vscode-errorForeground); }
+
+.vx-card {
+  border: 1px solid var(--vscode-panel-border, var(--vscode-input-border, #555));
+  border-radius: 4px;
+  margin-bottom: 0.75rem;
+  background: var(--vscode-editorWidget-background, transparent);
+}
+.vx-card__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--vscode-panel-border, var(--vscode-input-border, #555));
+}
+.vx-card__title { font-size: 1em; font-weight: 600; margin: 0; }
+.vx-card__actions { display: flex; gap: 0.5rem; }
+.vx-card__body { padding: 0.75rem; }
+
+.vx-list { list-style: none; margin: 0; padding: 0; }
+.vx-list__row {
+  padding: 0.4rem 0.6rem;
+  border-radius: 2px;
+  line-height: 1.5;
+}
+.vx-list__row--clickable { cursor: pointer; }
+.vx-list__row--clickable:hover { background: var(--vscode-list-hoverBackground); }
+.vx-list__empty { color: var(--vscode-descriptionForeground); padding: 0.6rem; }
+`,
+    "_generators/components/index.ts.tpl": `export { Button } from './Button';
+export type { ButtonProps } from './Button';
+export { Input } from './Input';
+export type { InputProps } from './Input';
+export { Field } from './Field';
+export type { FieldProps } from './Field';
+export { Card } from './Card';
+export type { CardProps } from './Card';
+export { List } from './List';
+export type { ListProps } from './List';
+`,
+    "_generators/crud/formApp.tsx.tpl": `import { useCallback, useEffect, useState } from 'react';
+import { connectWebview } from '../../../shared/vsceasy/client';
+import type { {{Name}}FormApi } from '../../../shared/api';
+import type { {{Name}} } from '../../../models/{{Name}}';
+
+const api = connectWebview<{{Name}}FormApi>();
+
+type FormState = Partial<{{Name}}>;
+
+const emptyForm: FormState = {{emptyFormLiteral}};
+
+export function App() {
+  const [form, setForm] = useState<FormState>(emptyForm);
+  const [editingId, setEditingId] = useState<{{Name}}['{{primaryKey}}'] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  const load = useCallback(async () => {
+    // The list stashes the row id before revealing this panel. Pull it (the host
+    // clears it after handing it over) and pre-fill the form for editing.
+    const id = await api.pendingId();
+    if (id == null || id === '') {
+      setForm(emptyForm);
+      setEditingId(null);
+      return;
+    }
+    const row = await api.get(id);
+    if (row) {
+      setForm(row);
+      setEditingId(row.{{primaryKey}});
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+    // Webviews retain state when hidden, so re-load whenever the panel is
+    // revealed — the list may have asked to edit a different row.
+    const onFocus = () => { void load(); };
+    const onVisible = () => { if (document.visibilityState === 'visible') void load(); };
+    window.addEventListener('focus', onFocus);
+    document.addEventListener('visibilitychange', onVisible);
+    return () => {
+      window.removeEventListener('focus', onFocus);
+      document.removeEventListener('visibilitychange', onVisible);
+    };
+  }, [load]);
+
+  const onChange = <K extends keyof FormState>(k: K, v: FormState[K]) => {
+    setForm((f) => ({ ...f, [k]: v }));
+  };
+
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSaving(true);
+    setError(null);
+    try {
+      const wasNew = editingId == null;
+      await api.save(form as {{Name}});
+      // After creating a new row, reset for the next entry. After an edit, keep
+      // the row loaded so further tweaks are possible.
+      if (wasNew) {
+        setForm(emptyForm);
+        setEditingId(null);
+      }
+    } catch (err: any) {
+      setError(String(err?.message ?? err));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <form onSubmit={onSubmit} style={{ padding: 16, display: 'grid', gap: 12, color: 'var(--vscode-foreground)' }}>
+      <h2 style={{ margin: 0 }}>{editingId ? 'Edit {{title}}' : 'New {{title}}'}</h2>
+{{formFieldInputs}}
+      {error && <div style={{ color: 'var(--vscode-errorForeground)' }}>{error}</div>}
+      <div style={{ display: 'flex', gap: 8 }}>
+        <button type="submit" disabled={saving}>{saving ? 'Saving…' : 'Save'}</button>
+        <button type="button" onClick={() => { setForm(emptyForm); setEditingId(null); }}>Reset</button>
+      </div>
+    </form>
+  );
+}
+`,
+    "_generators/crud/formNav.ts.tpl": `/**
+ * In-memory hand-off for "open the {{Name}} form to edit row X". The list panel
+ * sets the pending id before revealing the form; the form reads (and clears) it
+ * on mount. Lives in the extension host, shared across the two panel modules.
+ */
+type {{Name}}Id = unknown;
+
+let pendingId: {{Name}}Id | null = null;
+
+export function setPending{{Name}}Id(id: {{Name}}Id | null): void {
+  pendingId = id ?? null;
+}
+
+/** Returns the pending id once, then clears it. */
+export function takePending{{Name}}Id(): {{Name}}Id | null {
+  const v = pendingId;
+  pendingId = null;
+  return v;
+}
+`,
+    "_generators/crud/formPanel.ts.tpl": `import { definePanel } from '../shared/vsceasy';
+import { {{Name}}Service } from '../services/{{Name}}Service';
+import { takePending{{Name}}Id } from '../services/{{name}}FormNav';
+import type { {{Name}}FormApi } from '../shared/api';
+import type { {{Name}} } from '../models/{{Name}}';
+
+export default definePanel<{{Name}}FormApi>({
+  title: '{{title}}',
+  column: 'beside',
+  command: { title: '{{title}}: New / Edit' },
+  rpc: (vscode) => ({
+    async pendingId() {
+      // Consumed once by the webview on mount to decide edit vs new.
+      return (takePending{{Name}}Id() as {{Name}}['{{primaryKey}}'] | null) ?? null;
+    },
+    async get(id) {
+      if (!id) return null;
+      return {{Name}}Service.get(id as {{Name}}['{{primaryKey}}']);
+    },
+    async save(row) {
+      const saved = await {{Name}}Service.save(row);
+      void vscode.window.showInformationMessage(\`{{title}} saved (\${String(saved.{{primaryKey}})})\`);
+      // Reveal the list so the new/edited row shows. Revealing fires the list
+      // webview's focus/visibility listener, which reloads it.
+      void vscode.commands.executeCommand('{{prefix}}.open{{Plural}}List');
+      return saved;
+    },
+    async cancel() {
+      // No-op — webview closes itself.
+    },
+  }),
+});
+`,
+    "_generators/crud/listApp.tsx.tpl": `import { useEffect, useState, useCallback } from 'react';
+import { connectWebview } from '../../../shared/vsceasy/client';
+import type { {{Plural}}ListApi } from '../../../shared/api';
+import type { {{Name}} } from '../../../models/{{Name}}';
+
+const api = connectWebview<{{Plural}}ListApi>();
+
+export function App() {
+  const [rows, setRows] = useState<{{Name}}[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const reload = useCallback(async () => {
+    setLoading(true);
+    try {
+      setRows(await api.list());
+      setError(null);
+    } catch (e: any) {
+      setError(String(e?.message ?? e));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void reload();
+    // Webviews keep their state when hidden (retainContextWhenHidden), so the
+    // mount effect won't re-run when the panel is revealed again. Reload when the
+    // webview regains focus/visibility so edits made in another panel show up.
+    const onFocus = () => { void reload(); };
+    const onVisible = () => { if (document.visibilityState === 'visible') void reload(); };
+    window.addEventListener('focus', onFocus);
+    document.addEventListener('visibilitychange', onVisible);
+    return () => {
+      window.removeEventListener('focus', onFocus);
+      document.removeEventListener('visibilitychange', onVisible);
+    };
+  }, [reload]);
+
+  const onDelete = async (id: {{Name}}['{{primaryKey}}']) => {
+    // \`confirm()\` is disabled inside VS Code webviews — confirmation happens in
+    // the host (the \`delete\` RPC handler shows a modal). Just call + reload.
+    await api.delete(id);
+    await reload();
+  };
+
+  return (
+    <div style={{ padding: 16, color: 'var(--vscode-foreground)' }}>
+      <header style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 12 }}>
+        <h2 style={{ margin: 0 }}>{{title}}</h2>
+        <div style={{ display: 'flex', gap: 8 }}>
+          <button onClick={() => void reload()} disabled={loading}>{loading ? 'Loading…' : 'Refresh'}</button>
+          <button onClick={() => api.openForm()}>+ New</button>
+        </div>
+      </header>
+
+      {error && <div style={{ color: 'var(--vscode-errorForeground)', marginBottom: 8 }}>{error}</div>}
+      {loading ? <div>Loading…</div> : (
+        <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+          <thead>
+            <tr style={{ textAlign: 'left', borderBottom: '1px solid var(--vscode-panel-border)' }}>
+{{listHeaderCells}}
+              <th style={{ padding: '6px 8px' }}></th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.length === 0 && (
+              <tr><td colSpan={{{listColCount}}} style={{ padding: 16, opacity: 0.6 }}>No rows yet.</td></tr>
+            )}
+            {rows.map((r) => (
+              <tr key={String(r.{{primaryKey}})} style={{ borderBottom: '1px solid var(--vscode-panel-border)' }}>
+{{listBodyCells}}
+                <td style={{ padding: '6px 8px', whiteSpace: 'nowrap' }}>
+                  <button onClick={() => api.openForm(r.{{primaryKey}})}>Edit</button>{' '}
+                  <button onClick={() => onDelete(r.{{primaryKey}})}>Delete</button>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </div>
+  );
+}
+`,
+    "_generators/crud/listPanel.ts.tpl": `import { definePanel } from '../shared/vsceasy';
+import { {{Name}}Service } from '../services/{{Name}}Service';
+import { setPending{{Name}}Id } from '../services/{{name}}FormNav';
+import type { {{Plural}}ListApi } from '../shared/api';
+
+export default definePanel<{{Plural}}ListApi>({
+  title: '{{title}}',
+  column: 'active',
+  command: { title: '{{title}}: List' },
+  rpc: (vscode) => ({
+    async list() {
+      return {{Name}}Service.list();
+    },
+    async delete(id) {
+      // Confirm in the host — browser confirm() is disabled in webviews.
+      const pick = await vscode.window.showWarningMessage(
+        \`Delete {{title}} "\${String(id)}"?\`,
+        { modal: true },
+        'Delete',
+      );
+      if (pick !== 'Delete') return false;
+      return {{Name}}Service.delete(id);
+    },
+    async openForm(id) {
+      // Stash the id so the form can pre-load it on mount, then reveal the form.
+      setPending{{Name}}Id(id ?? null);
+      await vscode.commands.executeCommand('{{prefix}}.open{{Name}}Form', id ?? null);
+    },
+  }),
+});
+`,
+    "_generators/crud/main.tsx.tpl": `import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import '../../styles.css';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`,
+    "_generators/crud/service.ts.tpl": `import { {{Plural}}Repo } from '../models/{{Name}}';
+import type { {{Name}} } from '../models/{{Name}}';
+
+/**
+ * {{Name}} service — business logic between RPC handlers and the repo.
+ * Put validation, derivations (e.g. timestamps), and cross-entity work here.
+ */
+export const {{Name}}Service = {
+  async list(): Promise<{{Name}}[]> {
+    return {{Plural}}Repo().findMany({ orderBy: '{{primaryKey}}:desc' });
+  },
+
+  async get(id: {{Name}}['{{primaryKey}}']): Promise<{{Name}} | null> {
+    return {{Plural}}Repo().findById(id);
+  },
+
+  async save(row: {{Name}}): Promise<{{Name}}> {
+    if (!row.{{primaryKey}}) {
+      throw new Error('{{Name}}: {{primaryKey}} is required');
+    }
+    return {{Plural}}Repo().upsert(row);
+  },
+
+  async delete(id: {{Name}}['{{primaryKey}}']): Promise<boolean> {
+    return {{Plural}}Repo().delete(id);
+  },
+};
+`,
+    "_generators/helper/cache.ts.tpl": `/**
+ * In-memory TTL + LRU cache. Pair with the ORM for cheap reads:
+ *
+ *   const cache = createCache<User>({ ttlMs: 60_000, max: 200 });
+ *   const u = await cache.wrap(\`user:\${id}\`, () => orm(User).findById(id));
+ *
+ * Survives only while the extension host is running (cleared on reload).
+ * For persistent caches, write through to the ORM or \`globalState\`.
+ */
+
+export interface CacheOptions {
+  /** Time-to-live in ms. 0 = never expire. Default: 60000. */
+  ttlMs?: number;
+  /** Max entries. LRU eviction once exceeded. 0 = unlimited. Default: 500. */
+  max?: number;
+}
+
+export interface Cache<V> {
+  get(key: string): V | undefined;
+  set(key: string, value: V, ttlMsOverride?: number): void;
+  delete(key: string): boolean;
+  has(key: string): boolean;
+  clear(): void;
+  /** Memoize a loader. Returns cached value if fresh, else runs \`fn\` and stores. */
+  wrap(key: string, fn: () => Promise<V>, ttlMsOverride?: number): Promise<V>;
+  /** Force-refresh: invalidate then wrap. */
+  refresh(key: string, fn: () => Promise<V>, ttlMsOverride?: number): Promise<V>;
+  readonly size: number;
+}
+
+interface Entry<V> {
+  value: V;
+  expiresAt: number; // 0 = no expiry
+}
+
+export function createCache<V = unknown>(opts: CacheOptions = {}): Cache<V> {
+  const ttl = opts.ttlMs ?? 60_000;
+  const max = opts.max ?? 500;
+  // Map preserves insertion order — re-insert on access for LRU behavior.
+  const store = new Map<string, Entry<V>>();
+  // De-dupe concurrent loads for the same key.
+  const inflight = new Map<string, Promise<V>>();
+
+  const isFresh = (e: Entry<V>) => e.expiresAt === 0 || e.expiresAt > Date.now();
+
+  const evictIfNeeded = () => {
+    if (max <= 0) return;
+    while (store.size > max) {
+      const oldest = store.keys().next().value;
+      if (oldest === undefined) break;
+      store.delete(oldest);
+    }
+  };
+
+  const cache: Cache<V> = {
+    get(key) {
+      const e = store.get(key);
+      if (!e) return undefined;
+      if (!isFresh(e)) {
+        store.delete(key);
+        return undefined;
+      }
+      // LRU touch
+      store.delete(key);
+      store.set(key, e);
+      return e.value;
+    },
+    set(key, value, ttlMsOverride) {
+      const t = ttlMsOverride ?? ttl;
+      store.delete(key); // re-insert for LRU order
+      store.set(key, { value, expiresAt: t > 0 ? Date.now() + t : 0 });
+      evictIfNeeded();
+    },
+    delete(key) {
+      return store.delete(key);
+    },
+    has(key) {
+      const e = store.get(key);
+      if (!e) return false;
+      if (!isFresh(e)) {
+        store.delete(key);
+        return false;
+      }
+      return true;
+    },
+    clear() {
+      store.clear();
+      inflight.clear();
+    },
+    async wrap(key, fn, ttlMsOverride) {
+      const cached = cache.get(key);
+      if (cached !== undefined) return cached;
+      const pending = inflight.get(key);
+      if (pending) return pending;
+      const p = (async () => {
+        try {
+          const v = await fn();
+          cache.set(key, v, ttlMsOverride);
+          return v;
+        } finally {
+          inflight.delete(key);
+        }
+      })();
+      inflight.set(key, p);
+      return p;
+    },
+    async refresh(key, fn, ttlMsOverride) {
+      cache.delete(key);
+      return cache.wrap(key, fn, ttlMsOverride);
+    },
+    get size() {
+      return store.size;
+    },
+  };
+
+  return cache;
+}
+`,
+    "_generators/helper/config.ts.tpl": `import * as vscode from 'vscode';
+
+/**
+ * Typed wrapper over \`vscode.workspace.getConfiguration('{{commandPrefix}}')\`.
+ * Reads settings declared under \`contributes.configuration\` in package.json.
+ *
+ * Example package.json snippet:
+ *   "contributes": {
+ *     "configuration": {
+ *       "title": "{{displayName}}",
+ *       "properties": {
+ *         "{{commandPrefix}}.apiUrl": { "type": "string", "default": "" }
+ *       }
+ *     }
+ *   }
+ *
+ * Usage:
+ *   const url = config.get<string>('apiUrl');
+ *   await config.set('apiUrl', 'https://...');
+ */
+const SECTION = '{{commandPrefix}}';
+
+export const config = {
+  get<T>(key: string, fallback?: T): T {
+    const v = vscode.workspace.getConfiguration(SECTION).get<T>(key);
+    return (v === undefined ? (fallback as T) : v) as T;
+  },
+  set(key: string, value: unknown, target: vscode.ConfigurationTarget = vscode.ConfigurationTarget.Global): Thenable<void> {
+    return vscode.workspace.getConfiguration(SECTION).update(key, value, target);
+  },
+  onChange(listener: (key: string) => void): vscode.Disposable {
+    return vscode.workspace.onDidChangeConfiguration((e) => {
+      if (e.affectsConfiguration(SECTION)) listener(SECTION);
+    });
+  },
+};
+`,
+    "_generators/helper/db.ts.tpl": `import * as vscode from 'vscode';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Mini-ORM with pluggable providers. Ships with a filesystem JSON provider that
+ * writes each entity to a single file under the extension's storage dir. Future
+ * providers (sqlite, etc.) implement the same \`Provider\` interface — entity
+ * definitions and call sites don't change.
+ *
+ * Usage:
+ *   const User = defineEntity<{ id: string; name: string }>('users', { primaryKey: 'id' });
+ *   const orm = createDb(context, { provider: 'storage' });
+ *   await orm(User).insert({ id: 'u1', name: 'Jairo' });
+ *   const u = await orm(User).findById('u1');
+ */
+
+// ── Entity definition ────────────────────────────────────────────────────────
+
+export interface EntityOptions<T> {
+  /** Field used as the unique key. */
+  primaryKey: keyof T & string;
+  /** Optional indexes — speeds up \`findOne({ [k]: v })\` for these fields. */
+  indexes?: (keyof T & string)[];
+}
+
+export interface Entity<T> {
+  readonly name: string;
+  readonly primaryKey: keyof T & string;
+  readonly indexes: (keyof T & string)[];
+  /** Phantom type carrier so \`orm(E)\` infers \`T\`. Never read. */
+  readonly __t?: T;
+}
+
+export function defineEntity<T extends object>(
+  name: string,
+  opts: EntityOptions<T>,
+): Entity<T> {
+  return { name, primaryKey: opts.primaryKey, indexes: opts.indexes ?? [] };
+}
+
+// ── Query types ──────────────────────────────────────────────────────────────
+
+export type Where<T> = Partial<{ [K in keyof T]: T[K] | { in: T[K][] } | { neq: T[K] } }>;
+
+export interface FindOptions<T> {
+  where?: Where<T>;
+  limit?: number;
+  offset?: number;
+  /** \`'field:asc'\` | \`'field:desc'\`. Default asc when only field given. */
+  orderBy?: \`\${keyof T & string}:\${'asc' | 'desc'}\` | (keyof T & string);
+}
+
+export interface Repository<T> {
+  findById(id: T[keyof T]): Promise<T | null>;
+  findOne(where: Where<T>): Promise<T | null>;
+  findMany(opts?: FindOptions<T>): Promise<T[]>;
+  count(opts?: { where?: Where<T> }): Promise<number>;
+  insert(row: T): Promise<T>;
+  upsert(row: T): Promise<T>;
+  update(id: T[keyof T], patch: Partial<T>): Promise<T | null>;
+  delete(id: T[keyof T]): Promise<boolean>;
+  deleteMany(where: Where<T>): Promise<number>;
+  clear(): Promise<void>;
+}
+
+// ── Provider interface (future-proof for sqlite/etc.) ────────────────────────
+
+export interface Provider {
+  load(entity: string): Promise<Record<string, unknown>[]>;
+  save(entity: string, rows: Record<string, unknown>[]): Promise<void>;
+  /** Atomic batch. Implementations may optimize. */
+  transaction(work: (snapshot: Map<string, Record<string, unknown>[]>) => Promise<void> | void): Promise<void>;
+}
+
+// ── Storage provider (filesystem JSON) ───────────────────────────────────────
+
+class StorageProvider implements Provider {
+  private cache = new Map<string, Record<string, unknown>[]>();
+
+  constructor(private readonly root: string) {
+    fs.mkdirSync(root, { recursive: true });
+  }
+
+  private fileFor(entity: string): string {
+    return path.join(this.root, \`\${entity}.json\`);
+  }
+
+  async load(entity: string): Promise<Record<string, unknown>[]> {
+    if (this.cache.has(entity)) return this.cache.get(entity)!;
+    const f = this.fileFor(entity);
+    if (!fs.existsSync(f)) {
+      this.cache.set(entity, []);
+      return [];
+    }
+    try {
+      const rows = JSON.parse(fs.readFileSync(f, 'utf8'));
+      this.cache.set(entity, rows);
+      return rows;
+    } catch {
+      this.cache.set(entity, []);
+      return [];
+    }
+  }
+
+  async save(entity: string, rows: Record<string, unknown>[]): Promise<void> {
+    this.cache.set(entity, rows);
+    const f = this.fileFor(entity);
+    const tmp = \`\${f}.tmp\`;
+    fs.writeFileSync(tmp, JSON.stringify(rows));
+    fs.renameSync(tmp, f); // atomic on same filesystem
+  }
+
+  async transaction(
+    work: (snapshot: Map<string, Record<string, unknown>[]>) => Promise<void> | void,
+  ): Promise<void> {
+    // Snapshot pre-tx state for rollback. Working copy is what \`work\` mutates.
+    const backup = new Map<string, Record<string, unknown>[]>();
+    for (const [k, v] of this.cache) backup.set(k, structuredClone(v));
+    const working = new Map<string, Record<string, unknown>[]>();
+    for (const [k, v] of this.cache) working.set(k, structuredClone(v));
+    try {
+      await work(working);
+      for (const [entity, rows] of working) await this.save(entity, rows);
+    } catch (err) {
+      // Roll back in-memory cache to the pre-tx snapshot.
+      for (const [k, v] of backup) this.cache.set(k, v);
+      throw err;
+    }
+  }
+}
+
+// ── Public DB type ───────────────────────────────────────────────────────────
+
+export interface Db {
+  <T extends object>(entity: Entity<T>): Repository<T>;
+  transaction(work: (tx: Db) => Promise<void> | void): Promise<void>;
+  /** Wipe a single entity. */
+  drop(entity: Entity<unknown>): Promise<void>;
+  /** Underlying provider — escape hatch for advanced use. */
+  readonly provider: Provider;
+}
+
+export interface CreateDbOptions {
+  /** \`'storage'\` writes under \`context.storageUri/<subdir>/\`. \`'global'\` uses \`globalStorageUri\`. */
+  provider: 'storage' | 'global';
+  /** Override sub-directory under the chosen storage root. Default: \`db\`. */
+  subdir?: string;
+}
+
+export function createDb(ctx: vscode.ExtensionContext, opts: CreateDbOptions): Db {
+  // \`storageUri\` is only defined when a workspace/folder is open. \`globalStorageUri\`
+  // is always available — fall back to it so the extension still activates with no
+  // folder open (e.g. the Extension Development Host on first launch).
+  const baseUri =
+    opts.provider === 'global'
+      ? ctx.globalStorageUri
+      : (ctx.storageUri ?? ctx.globalStorageUri);
+  if (!baseUri) {
+    throw new Error('createDb: no storage URI available from the extension context.');
+  }
+  const root = path.join(baseUri.fsPath, opts.subdir ?? 'db');
+  const provider = new StorageProvider(root);
+  ctx.subscriptions.push({ dispose: () => {} }); // future hook
+  return makeDb(provider);
+}
+
+// ── Singleton accessor — \`import { db } from './db'; await db()(Users).insert(...)\` ──
+
+let _db: Db | undefined;
+
+/**
+ * Default options used by \`initDb\` when called as a bootstrap hook (one-arg).
+ * Override via the 2-arg form: \`initDb(context, { provider: 'global' })\`.
+ */
+export const dbOptions: CreateDbOptions = { provider: '{{provider}}' };
+
+/**
+ * Initialize the shared db. Call once on activate. Idempotent.
+ *
+ * As a bootstrap hook (recommended — \`bootstrap(registry, { onActivate: [initDb] })\`):
+ *   initDb(context)
+ *
+ * Direct call with custom options:
+ *   initDb(context, { provider: 'global' })
+ */
+export function initDb(ctx: vscode.ExtensionContext, opts?: CreateDbOptions): Db {
+  if (_db) return _db;
+  _db = createDb(ctx, opts ?? dbOptions);
+  return _db;
+}
+
+/** Access the shared db. Throws if \`initDb()\` wasn't called yet. */
+export function db(): Db {
+  if (!_db) throw new Error('db not initialized — call initDb(context) on activate.');
+  return _db;
+}
+
+function makeDb(provider: Provider): Db {
+  const repoFor = <T extends object>(entity: Entity<T>): Repository<T> => {
+    const pk = entity.primaryKey;
+    const load = () => provider.load(entity.name) as Promise<T[]>;
+    const save = (rows: T[]) => provider.save(entity.name, rows as Record<string, unknown>[]);
+
+    return {
+      async findById(id) {
+        const rows = await load();
+        return rows.find((r) => r[pk] === id) ?? null;
+      },
+      async findOne(where) {
+        const rows = await load();
+        return rows.find((r) => match(r, where)) ?? null;
+      },
+      async findMany(opts = {}) {
+        let rows = await load();
+        if (opts.where) rows = rows.filter((r) => match(r, opts.where!));
+        if (opts.orderBy) {
+          const [field, dir] = String(opts.orderBy).split(':');
+          const sign = dir === 'desc' ? -1 : 1;
+          rows = [...rows].sort((a, b) => compare(a[field as keyof T], b[field as keyof T]) * sign);
+        }
+        if (opts.offset) rows = rows.slice(opts.offset);
+        if (opts.limit !== undefined) rows = rows.slice(0, opts.limit);
+        return rows;
+      },
+      async count(opts = {}) {
+        const rows = await load();
+        return opts.where ? rows.filter((r) => match(r, opts.where!)).length : rows.length;
+      },
+      async insert(row) {
+        const rows = await load();
+        if (rows.some((r) => r[pk] === row[pk])) {
+          throw new Error(\`\${entity.name}: duplicate \${pk}=\${String(row[pk])}\`);
+        }
+        rows.push(row);
+        await save(rows);
+        return row;
+      },
+      async upsert(row) {
+        const rows = await load();
+        const i = rows.findIndex((r) => r[pk] === row[pk]);
+        if (i >= 0) rows[i] = row; else rows.push(row);
+        await save(rows);
+        return row;
+      },
+      async update(id, patch) {
+        const rows = await load();
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i < 0) return null;
+        rows[i] = { ...rows[i], ...patch };
+        await save(rows);
+        return rows[i];
+      },
+      async delete(id) {
+        const rows = await load();
+        const before = rows.length;
+        const next = rows.filter((r) => r[pk] !== id);
+        if (next.length === before) return false;
+        await save(next);
+        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);
+        return removed;
+      },
+      async clear() {
+        await save([]);
+      },
+    };
+  };
+
+  const db: Db = Object.assign(repoFor as any, {
+    provider,
+    async drop(entity: Entity<unknown>) {
+      await provider.save(entity.name, []);
+    },
+    async transaction(work: (tx: Db) => Promise<void> | void) {
+      await provider.transaction(async (snapshot) => {
+        // Build a tx-scoped Db that reads/writes the snapshot map.
+        const txProvider: Provider = {
+          async load(name) { return snapshot.get(name) ?? []; },
+          async save(name, rows) { snapshot.set(name, rows); },
+          async transaction() { throw new Error('Nested transactions are not supported'); },
+        };
+        await work(makeDb(txProvider));
+      });
+    },
+  });
+
+  return db;
+}
+
+// ── matcher ──────────────────────────────────────────────────────────────────
+
+function match<T extends object>(row: T, where: Where<T>): boolean {
+  for (const key of Object.keys(where) as (keyof T)[]) {
+    const expected = where[key] as unknown;
+    const actual = row[key];
+    if (expected && typeof expected === 'object' && !Array.isArray(expected)) {
+      if ('in' in expected) {
+        if (!(expected as { in: unknown[] }).in.includes(actual)) return false;
+        continue;
+      }
+      if ('neq' in expected) {
+        if (actual === (expected as { neq: unknown }).neq) return false;
+        continue;
+      }
+    }
+    if (actual !== expected) return false;
+  }
+  return true;
+}
+
+function compare(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  if (a === null || a === undefined) return -1;
+  if (b === null || b === undefined) return 1;
+  return a < b ? -1 : 1;
+}
+`,
+    "_generators/helper/notifications.ts.tpl": `import * as vscode from 'vscode';
+
+/**
+ * Concise wrappers over \`vscode.window.show*Message\`. Each accepts an optional
+ * list of action labels and resolves to the selected label (or undefined).
+ *
+ * Usage:
+ *   notify.info('Saved');
+ *   const pick = await notify.warn('Discard?', 'Discard', 'Keep');
+ *   if (pick === 'Discard') ...
+ *
+ * For long-running tasks use \`withProgress\`:
+ *   await withProgress('Indexing…', async (report) => {
+ *     for (let i = 0; i <= 100; i += 10) {
+ *       report({ increment: 10, message: \`\${i}%\` });
+ *       await new Promise(r => setTimeout(r, 100));
+ *     }
+ *   });
+ */
+export const notify = {
+  info(message: string, ...actions: string[]) {
+    return vscode.window.showInformationMessage(message, ...actions);
+  },
+  warn(message: string, ...actions: string[]) {
+    return vscode.window.showWarningMessage(message, ...actions);
+  },
+  error(message: string, ...actions: string[]) {
+    return vscode.window.showErrorMessage(message, ...actions);
+  },
+  confirm(message: string, yesLabel = 'Yes', noLabel = 'No'): Thenable<boolean> {
+    return vscode.window
+      .showInformationMessage(message, { modal: true }, yesLabel, noLabel)
+      .then((pick) => pick === yesLabel);
+  },
+};
+
+export function withProgress<T>(
+  title: string,
+  task: (report: (p: { message?: string; increment?: number }) => void) => Thenable<T> | T,
+  location: vscode.ProgressLocation = vscode.ProgressLocation.Notification,
+): Thenable<T> {
+  return vscode.window.withProgress({ location, title, cancellable: false }, (progress) =>
+    Promise.resolve(task((p) => progress.report(p))),
+  );
+}
+`,
+    "_generators/helper/secrets.ts.tpl": `import * as vscode from 'vscode';
+
+/**
+ * Typed wrapper over \`context.secrets\` (SecretStorage backed by OS keychain).
+ * Inject the extension context once on activate (bootstrap does this if you
+ * import this module from your extension entry).
+ *
+ * Usage:
+ *   await secrets.set('githubToken', 'ghp_xxx');
+ *   const token = await secrets.get('githubToken');
+ */
+let _ctx: vscode.ExtensionContext | undefined;
+
+export function initSecrets(ctx: vscode.ExtensionContext) {
+  _ctx = ctx;
+}
+
+function ctx(): vscode.ExtensionContext {
+  if (!_ctx) throw new Error('Secrets helper not initialized — call initSecrets(context) on activate.');
+  return _ctx;
+}
+
+export const secrets = {
+  get(key: string): Thenable<string | undefined> {
+    return ctx().secrets.get(key);
+  },
+  set(key: string, value: string): Thenable<void> {
+    return ctx().secrets.store(key, value);
+  },
+  delete(key: string): Thenable<void> {
+    return ctx().secrets.delete(key);
+  },
+  onChange(listener: (key: string) => void): vscode.Disposable {
+    return ctx().secrets.onDidChange((e) => listener(e.key));
+  },
+};
+`,
+    "_generators/helper/state.ts.tpl": `import * as vscode from 'vscode';
+
+/**
+ * Typed wrapper over \`context.{workspaceState, globalState}\`.
+ * - workspace: scoped to the current workspace (per-project preferences)
+ * - global: shared across all workspaces (user-wide settings, last-opened file)
+ *
+ * Usage:
+ *   await state.workspace.set('lastQuery', 'foo');
+ *   const q = state.workspace.get<string>('lastQuery');
+ */
+let _ctx: vscode.ExtensionContext | undefined;
+
+export function initState(ctx: vscode.ExtensionContext) {
+  _ctx = ctx;
+}
+
+function ctx(): vscode.ExtensionContext {
+  if (!_ctx) throw new Error('State helper not initialized — call initState(context) on activate.');
+  return _ctx;
+}
+
+function wrap(memento: () => vscode.Memento) {
+  return {
+    get<T>(key: string, fallback?: T): T | undefined {
+      const v = memento().get<T>(key);
+      return v === undefined ? fallback : v;
+    },
+    set(key: string, value: unknown): Thenable<void> {
+      return memento().update(key, value);
+    },
+    delete(key: string): Thenable<void> {
+      return memento().update(key, undefined);
+    },
+    keys(): readonly string[] {
+      return memento().keys();
+    },
+  };
+}
+
+export const state = {
+  workspace: wrap(() => ctx().workspaceState),
+  global: wrap(() => ctx().globalState),
+};
+`,
+    "_generators/job/job.ts.tpl": `import { defineJob } from '../shared/vsceasy';
+
+export default defineJob({
+  title: '{{title}}',
+  schedule: {{schedule}},{{minIntervalLine}}
+  run: async (vscode, ctx) => {
+    // TODO: implement {{name}} work
+    console.log('[{{name}}] tick', new Date().toISOString());
+  },
+});
+`,
+    "_generators/menu/menu.ts.tpl": `import { defineMenu } from '../shared/vsceasy';
+
+export default defineMenu({
+  title: '{{title}}',
+  icon: '{{icon}}',
+  items: [
+    {
+      label: 'Panels',
+      children: [
+        // { label: 'Dashboard', panel: 'dashboard' },
+      ],
+    },
+    {
+      label: 'Actions',
+      children: [
+        // { label: 'Hello', command: 'hello', icon: 'play' },
+        // { label: 'Docs', url: 'https://example.com', icon: 'book' },
+      ],
+    },
+  ],
+});
+`,
+    "_generators/model/model.ts.tpl": `import { defineEntity, db } from '../helpers/db';
+
+export interface {{Name}} {
+{{fieldLines}}
+}
+
+export const {{Plural}} = defineEntity<{{Name}}>('{{collection}}', {
+  primaryKey: '{{primaryKey}}',{{indexesLine}}
+});
+
+/**
+ * Typed repo accessor. Lazy — assumes \`initDb(context)\` ran on activate.
+ *
+ *   import { {{Plural}}Repo } from '../models/{{Name}}';
+ *   await {{Plural}}Repo().insert({ ... });
+ */
+export const {{Plural}}Repo = () => db()({{Plural}});
+`,
+    "_generators/panel/App.tsx.tpl": `import React from 'react';
+{{apiBlock}}
+export function App() {
+  return (
+    <div className="app">
+      <h1>{{title}}</h1>
+      <p>Edit <code>src/webview/panels/{{name}}/App.tsx</code> to start building.</p>
+    </div>
+  );
+}
+`,
+    "_generators/panel/main.tsx.tpl": `import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import '../../styles.css';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`,
+    "_generators/panel/panel.ts.tpl": `import { definePanel } from '../shared/vsceasy';
+{{apiImport}}
+export default definePanel{{apiGeneric}}({
+  title: '{{title}}',{{rpcBlock}}
+});
+`,
+    "_generators/panel/templates/dashboard/App.tsx.tpl": `import React, { useEffect, useState } from 'react';
+import { Button, Card } from '../../components';
+import '../../components/components.css';
+{{apiBlock}}
+interface Stats {
+  total: number;
+  active: number;
+  updatedAt: string;
+}
+
+export function App() {
+  const [stats, setStats] = useState<Stats | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  async function refresh() {
+    setLoading(true);
+    try {
+      {{statsCall}}
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  useEffect(() => {
+    void refresh();
+  }, []);
+
+  return (
+    <div className="app">
+      <h1>{{title}}</h1>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(8rem, 1fr))', gap: '0.75rem' }}>
+        <Card title="Total"><strong style={{ fontSize: '1.5rem' }}>{stats?.total ?? '—'}</strong></Card>
+        <Card title="Active"><strong style={{ fontSize: '1.5rem' }}>{stats?.active ?? '—'}</strong></Card>
+        <Card title="Updated"><span>{stats?.updatedAt ?? '—'}</span></Card>
+      </div>
+      <div style={{ marginTop: '0.75rem' }}>
+        <Button variant="secondary" onClick={refresh} disabled={loading}>{loading ? 'Loading…' : 'Refresh'}</Button>
+      </div>
+    </div>
+  );
+}
+`,
+    "_generators/panel/templates/form/App.tsx.tpl": `import React, { useState } from 'react';
+import { Button, Input, Field, Card } from '../../components';
+import '../../components/components.css';
+{{apiBlock}}
+export function App() {
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [status, setStatus] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setStatus(null);
+    try {
+      {{submitCall}}
+      setStatus('Saved.');
+      setName('');
+      setEmail('');
+    } catch (err) {
+      setStatus(err instanceof Error ? err.message : 'Failed.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="app">
+      <h1>{{title}}</h1>
+      <Card title="New entry">
+        <form onSubmit={onSubmit}>
+          <Field label="Name" htmlFor="name">
+            <Input id="name" value={name} onChange={(e) => setName(e.target.value)} placeholder="Jane Doe" required />
+          </Field>
+          <Field label="Email" htmlFor="email">
+            <Input id="email" type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="jane@acme.io" />
+          </Field>
+          <Button type="submit" disabled={busy}>{busy ? 'Saving…' : 'Save'}</Button>
+          {status ? <span style={{ marginLeft: '0.75rem' }}>{status}</span> : null}
+        </form>
+      </Card>
+    </div>
+  );
+}
+`,
+    "_generators/panel/templates/list/App.tsx.tpl": `import React, { useEffect, useState } from 'react';
+import { Button, List, Card } from '../../components';
+import '../../components/components.css';
+{{apiBlock}}
+interface Row {
+  id: string;
+  label: string;
+}
+
+export function App() {
+  const [rows, setRows] = useState<Row[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  async function refresh() {
+    setLoading(true);
+    try {
+      {{loadCall}}
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  useEffect(() => {
+    void refresh();
+  }, []);
+
+  return (
+    <div className="app">
+      <h1>{{title}}</h1>
+      <Card title="Items" actions={<Button variant="secondary" onClick={refresh} disabled={loading}>{loading ? 'Loading…' : 'Refresh'}</Button>}>
+        <List
+          items={rows}
+          getKey={(r) => r.id}
+          renderItem={(r) => r.label}
+          empty="No items yet."
+        />
+      </Card>
+    </div>
+  );
+}
+`,
+    "_generators/publish/CHANGELOG.md.tpl": `# Change Log
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+- Initial release.
+`,
+    "_generators/publish/README.md.tpl": `# {{displayName}}
+
+{{description}}
+
+## Features
+
+- (describe what this extension does)
+
+## Requirements
+
+VS Code ≥ 1.80
+
+## Extension Settings
+
+(list your \`contributes.configuration\` entries)
+
+## Known Issues
+
+—
+
+## Release Notes
+
+See [CHANGELOG.md](./CHANGELOG.md).
+`,
+    "_generators/statusBar/statusBar.ts.tpl": `import { defineStatusBar } from '../shared/vsceasy';
+
+export default defineStatusBar({
+  text: '{{text}}',{{iconLine}}{{tooltipLine}}
+  alignment: '{{alignment}}',
+  priority: {{priority}},{{commandLine}}{{panelLine}}
+});
+`,
+    "_generators/subpanel/App.tsx.tpl": `import React from 'react';
+{{apiBlock}}
+export function App() {
+  return (
+    <div className="sidebar-view">
+      <h2>{{title}}</h2>
+      <p>Edit <code>src/webview/subpanels/{{name}}/App.tsx</code> to start building.</p>
+    </div>
+  );
+}
+`,
+    "_generators/subpanel/main.tsx.tpl": `import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import '../../styles.css';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`,
+    "_generators/subpanel/subpanel.ts.tpl": `import { defineSubpanel } from '../shared/vsceasy';
+{{apiImport}}
+export default defineSubpanel{{apiGeneric}}({
+  title: '{{title}}',
+  menu: '{{menu}}',{{rpcBlock}}
+});
+`,
+    "_generators/test/_helpers.ts.tpl": `import { vi } from 'vitest';
+import { createRpcServer, createRpcClient } from '../shared/vsceasy/rpc';
+import type { Transport, Handlers, RpcClient } from '../shared/vsceasy/rpc';
+
+/**
+ * Minimal \`vscode\` namespace mock — covers the surface most extensions touch.
+ * Extend per test by spreading or assigning new spies onto the returned object.
+ *
+ *   const vscode = mockVscode();
+ *   vscode.window.showInformationMessage('hi');
+ *   expect(vscode.window.showInformationMessage).toHaveBeenCalledWith('hi');
+ */
+export function mockVscode() {
+  const subscriptions: { dispose(): void }[] = [];
+  return {
+    window: {
+      showInformationMessage: vi.fn(),
+      showWarningMessage: vi.fn(),
+      showErrorMessage: vi.fn(),
+      showInputBox: vi.fn(),
+      showQuickPick: vi.fn(),
+      withProgress: vi.fn(async (_opts: any, task: any) => task({ report: vi.fn() })),
+      createStatusBarItem: vi.fn(() => ({ show: vi.fn(), dispose: vi.fn(), text: '' })),
+      createTreeView: vi.fn(() => ({ dispose: vi.fn() })),
+      createWebviewPanel: vi.fn(),
+      activeTextEditor: undefined as any,
+    },
+    workspace: {
+      getConfiguration: vi.fn(() => ({ get: vi.fn(), update: vi.fn(async () => undefined) })),
+      onDidChangeConfiguration: vi.fn(() => ({ dispose: vi.fn() })),
+      findFiles: vi.fn(async () => [] as any[]),
+      workspaceFolders: [] as any[],
+    },
+    commands: {
+      registerCommand: vi.fn((_id: string, _fn: any) => ({ dispose: vi.fn() })),
+      executeCommand: vi.fn(async () => undefined),
+    },
+    env: {
+      openExternal: vi.fn(async () => true),
+    },
+    Uri: { parse: (s: string) => ({ toString: () => s }), file: (p: string) => ({ fsPath: p, toString: () => p }) },
+    ProgressLocation: { Notification: 15, SourceControl: 1, Window: 10 } as const,
+    ConfigurationTarget: { Global: 1, Workspace: 2, WorkspaceFolder: 3 } as const,
+    TreeItemCollapsibleState: { None: 0, Collapsed: 1, Expanded: 2 } as const,
+    StatusBarAlignment: { Left: 1, Right: 2 } as const,
+    EventEmitter: class {
+      private listeners: Array<(v: any) => void> = [];
+      event = (l: (v: any) => void) => {
+        this.listeners.push(l);
+        return { dispose: () => (this.listeners = this.listeners.filter((x) => x !== l)) };
+      };
+      fire(v: any) {
+        this.listeners.forEach((l) => l(v));
+      }
+      dispose() {
+        this.listeners = [];
+      }
+    },
+    Disposable: { from: (...d: any[]) => ({ dispose: () => d.forEach((x) => x.dispose?.()) }) },
+    subscriptions,
+  };
+}
+
+export type VscodeMock = ReturnType<typeof mockVscode>;
+
+/**
+ * Minimal \`ExtensionContext\` mock — backed by in-memory Maps for state/secrets.
+ */
+export function mockContext() {
+  const wm = new Map<string, unknown>();
+  const gm = new Map<string, unknown>();
+  const sm = new Map<string, string>();
+  const memento = (m: Map<string, unknown>) => ({
+    get: (k: string, d?: unknown) => (m.has(k) ? m.get(k) : d),
+    update: async (k: string, v: unknown) => void (v === undefined ? m.delete(k) : m.set(k, v)),
+    keys: () => Array.from(m.keys()),
+  });
+  return {
+    subscriptions: [] as { dispose(): void }[],
+    workspaceState: memento(wm),
+    globalState: memento(gm),
+    secrets: {
+      get: async (k: string) => sm.get(k),
+      store: async (k: string, v: string) => void sm.set(k, v),
+      delete: async (k: string) => void sm.delete(k),
+      onDidChange: () => ({ dispose: () => {} }),
+    },
+    extensionPath: '/mock',
+    extensionUri: { fsPath: '/mock' },
+  };
+}
+
+/**
+ * Build an in-memory RPC pair (server + typed client). No webview involved.
+ * Useful for testing your handlers end-to-end with the same types the UI sees.
+ *
+ *   const handlers = { greet: (n: string) => \`hi \${n}\` };
+ *   const api = mockRpcPair<typeof handlers>(handlers);
+ *   expect(await api.greet('Jairo')).toBe('hi Jairo');
+ */
+export function mockRpcPair<H extends Handlers>(handlers: H): RpcClient<H> {
+  const aListeners = new Set<(m: any) => void>();
+  const bListeners = new Set<(m: any) => void>();
+  const aToB: Transport = {
+    send: (m) => bListeners.forEach((l) => l(m)),
+    onMessage: (h) => {
+      aListeners.add(h);
+      return () => aListeners.delete(h);
+    },
+  };
+  const bToA: Transport = {
+    send: (m) => aListeners.forEach((l) => l(m)),
+    onMessage: (h) => {
+      bListeners.add(h);
+      return () => bListeners.delete(h);
+    },
+  };
+  createRpcServer<H>(bToA, handlers);
+  return createRpcClient<H>(aToB, { callTimeoutMs: 0 });
+}
+`,
+    "_generators/test/sample.test.ts.tpl": `import { describe, it, expect } from 'vitest';
+import { mockVscode, mockContext, mockRpcPair } from './_helpers';
+
+describe('vscode mock', () => {
+  it('captures notification calls', () => {
+    const vscode = mockVscode();
+    vscode.window.showInformationMessage('hello');
+    expect(vscode.window.showInformationMessage).toHaveBeenCalledWith('hello');
+  });
+
+  it('persists state via mock context', async () => {
+    const ctx = mockContext();
+    await ctx.workspaceState.update('key', 42);
+    expect(ctx.workspaceState.get('key')).toBe(42);
+  });
+});
+
+describe('RPC pair', () => {
+  it('round-trips a typed handler call', async () => {
+    const handlers = {
+      async greet(name: string) {
+        return \`hi \${name}\`;
+      },
+    };
+    const api = mockRpcPair<typeof handlers>(handlers);
+    expect(await api.greet('Jairo')).toBe('hi Jairo');
+  });
+
+  it('propagates handler errors', async () => {
+    const handlers = {
+      async boom() {
+        throw new Error('nope');
+      },
+    };
+    const api = mockRpcPair<typeof handlers>(handlers);
+    await expect(api.boom()).rejects.toThrow('nope');
+  });
+});
+`,
+    "_generators/test/vitest.config.ts.tpl": `import { defineConfig } from 'vitest/config';
+import * as path from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // \`vscode\` is only available inside the extension host. Tests stub it
+      // with an empty module so importing any file that does \`import * as vscode\`
+      // doesn't crash. Use \`mockVscode()\` from \`_helpers.ts\` for the surface
+      // you actually need to assert against.
+      vscode: path.resolve(__dirname, 'src/__tests__/__mocks__/vscode.ts'),
+    },
+  },
+  test: {
+    include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
+    environment: 'node',
+    globals: false,
+    coverage: {
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: ['src/extension/_registry.ts', 'src/webview/**', 'src/__tests__/**'],
+    },
+  },
+});
+`,
+    "_generators/test/vscode.stub.ts.tpl": `/**
+ * Auto-generated \`vscode\` module stub for vitest. Replaces the real \`vscode\`
+ * import inside tests (the real module only exists in the extension host).
+ *
+ * The stub exposes the enums and class shapes the runtime touches at module
+ * load time so files that do \`import * as vscode from 'vscode'\` don't crash
+ * during test collection.
+ *
+ * To assert behaviour against \`vscode.window.X\`, use \`mockVscode()\` from
+ * \`_helpers.ts\` and inject it into the code under test directly.
+ */
+export const TreeItemCollapsibleState = { None: 0, Collapsed: 1, Expanded: 2 } as const;
+export const StatusBarAlignment = { Left: 1, Right: 2 } as const;
+export const ConfigurationTarget = { Global: 1, Workspace: 2, WorkspaceFolder: 3 } as const;
+export const ProgressLocation = { SourceControl: 1, Window: 10, Notification: 15 } as const;
+export const ViewColumn = { Active: -1, Beside: -2, One: 1, Two: 2, Three: 3 } as const;
+export const ThemeIcon = class { constructor(public id: string) {} };
+export const ThemeColor = class { constructor(public id: string) {} };
+export const TreeItem = class { constructor(public label: string, public collapsibleState?: number) {} };
+export const MarkdownString = class {
+  value = '';
+  isTrusted = false;
+  supportHtml = false;
+  constructor(value = '') {
+    this.value = value;
+  }
+  appendMarkdown(v: string) {
+    this.value += v;
+    return this;
+  }
+};
+export const Uri = {
+  parse: (s: string) => ({ toString: () => s, fsPath: s }),
+  file: (p: string) => ({ fsPath: p, toString: () => p }),
+  joinPath: (base: { fsPath: string }, ...segs: string[]) => ({
+    fsPath: [base.fsPath, ...segs].join('/'),
+    toString: () => [base.fsPath, ...segs].join('/'),
+  }),
+};
+export const EventEmitter = class<T> {
+  private listeners: Array<(v: T) => void> = [];
+  event = (l: (v: T) => void) => {
+    this.listeners.push(l);
+    return { dispose: () => (this.listeners = this.listeners.filter((x) => x !== l)) };
+  };
+  fire(v: T) {
+    this.listeners.forEach((l) => l(v));
+  }
+  dispose() {
+    this.listeners = [];
+  }
+};
+export const Disposable = {
+  from: (...d: Array<{ dispose: () => void }>) => ({ dispose: () => d.forEach((x) => x.dispose()) }),
+};
+
+const noop = () => {};
+const noopDisposable = { dispose: noop };
+const noopAsync = async () => undefined;
+const noopReg = () => noopDisposable;
+
+export const window = {
+  showInformationMessage: noopAsync,
+  showWarningMessage: noopAsync,
+  showErrorMessage: noopAsync,
+  showInputBox: noopAsync,
+  showQuickPick: noopAsync,
+  withProgress: async (_o: unknown, task: (p: { report: () => void }) => unknown) =>
+    task({ report: noop }),
+  createStatusBarItem: () => ({ show: noop, hide: noop, dispose: noop, text: '' }),
+  createTreeView: () => ({ dispose: noop }),
+  createWebviewPanel: () => ({
+    webview: { html: '', onDidReceiveMessage: noopReg, postMessage: noop, asWebviewUri: (u: unknown) => u },
+    onDidDispose: noopReg,
+    dispose: noop,
+  }),
+  registerWebviewViewProvider: noopReg,
+  activeTextEditor: undefined as unknown,
+  onDidChangeActiveTextEditor: noopReg,
+};
+
+export const workspace = {
+  getConfiguration: () => ({ get: noop, update: noopAsync, has: () => false, inspect: () => undefined }),
+  onDidChangeConfiguration: noopReg,
+  findFiles: async () => [] as unknown[],
+  workspaceFolders: [] as unknown[],
+  asRelativePath: (p: string) => p,
+};
+
+export const commands = {
+  registerCommand: noopReg,
+  executeCommand: noopAsync,
+  getCommands: async () => [] as string[],
+};
+
+export const env = {
+  openExternal: async () => true,
+  clipboard: { writeText: noopAsync, readText: async () => '' },
+};
+
+export const extensions = {
+  getExtension: () => undefined,
+  all: [] as unknown[],
+};
+
+export const languages = {
+  registerHoverProvider: noopReg,
+  registerCompletionItemProvider: noopReg,
+};
+`,
+    "_generators/treeView/treeView.ts.tpl": `import { defineTreeView, TreeNode } from '../shared/vsceasy';
+
+export default defineTreeView({
+  title: '{{title}}',
+  menu: '{{menu}}',
+  getChildren: async (parent, vscode, ctx) => {
+    if (!parent) {
+      return [
+        { label: 'Item 1', icon: 'file', tooltip: 'Replace with real data' },
+        { label: 'Group', icon: 'folder', collapsed: 'collapsed', children: [] },
+      ] as TreeNode[];
+    }
+    // Lazy children — return based on parent.id / parent.contextValue.
+    return [];
+  },
+});
+`,
+    "react/.gitignore": `node_modules
+dist
+*.vsix
+.DS_Store
+`,
+    "react/.vscode/launch.json": `{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=\${workspaceFolder}"],
+      "outFiles": ["\${workspaceFolder}/dist/**/*.js"],
+      "sourceMaps": true,
+      "smartStep": true,
+      "preLaunchTask": "vsceasy: build"
+    },
+    {
+      "name": "Run Extension (watch / HMR)",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=\${workspaceFolder}"],
+      "outFiles": ["\${workspaceFolder}/dist/**/*.js"],
+      "sourceMaps": true,
+      "smartStep": true,
+      "preLaunchTask": "vsceasy: dev"
+    },
+    {
+      "name": "Attach to Extension Host",
+      "type": "node",
+      "request": "attach",
+      "port": 9229,
+      "skipFiles": ["<node_internals>/**"],
+      "sourceMaps": true,
+      "outFiles": ["\${workspaceFolder}/dist/**/*.js"]
+    }
+  ]
+}
+`,
+    "react/.vscode/tasks.json": `{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "vsceasy: build",
+      "type": "shell",
+      "command": "bun run build",
+      "presentation": { "reveal": "silent", "panel": "dedicated" },
+      "problemMatcher": []
+    },
+    {
+      "label": "vsceasy: dev",
+      "type": "shell",
+      "command": "bun run dev",
+      "isBackground": true,
+      "presentation": { "reveal": "always", "panel": "dedicated" },
+      "group": { "kind": "build", "isDefault": true },
+      "problemMatcher": {
+        "owner": "esbuild-watch",
+        "pattern": {
+          "regexp": "^\\\\s*✘\\\\s*\\\\[ERROR\\\\]\\\\s+(.*)$",
+          "message": 1
+        },
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": ".*build started.*|.*\\\\[watch\\\\] build started.*",
+          "endsPattern": ".*built in.*|.*\\\\[watch\\\\] build finished.*"
+        }
+      }
+    }
+  ]
+}
+`,
+    "react/.vscodeignore": `.vscode/**
+src/**
+scripts/**
+node_modules/**
+.gitignore
+tsconfig.json
+vite.config.ts
+*.map
+`,
+    "react/README.md": `# {{displayName}}
+
+Generated with [\`vsceasy\`](https://www.npmjs.com/package/vsceasy).
+
+## Develop
+
+Two ways to launch the Extension Development Host:
+
+### Option A — one-shot launch (recommended for first run)
+
+\`\`\`bash
+bun install
+bun run launch
+\`\`\`
+
+Builds extension + webview once, then opens a new VS Code window with the extension loaded.
+Then in the dev window: Command Palette → **{{displayName}}: Open Dashboard**.
+
+### Option B — watch mode + F5
+
+\`\`\`bash
+bun install
+bun run dev          # leave running — watches both extension + webview
+\`\`\`
+
+Then in VS Code (this folder open):
+- Press <kbd>F5</kbd> → picks **Run Extension** launch config → opens Extension Development Host.
+- Re-press <kbd>Ctrl/Cmd+R</kbd> inside the dev host after code changes to reload.
+
+> Note: \`bun run dev\` only builds — it does NOT launch VS Code. F5 (or \`bun run launch\`) does.
+
+## Commands
+
+- Command Palette → **{{displayName}}: Hello** → info toast
+- Command Palette → **{{displayName}}: Open Dashboard** → React webview
+
+## Structure
+
+- \`src/extension/extension.ts\` — entry, registers commands
+- \`src/extension/panels/DashboardPanel.ts\` — webview panel + RPC handlers
+- \`src/webview/App.tsx\` — React UI (typed RPC client)
+- \`src/shared/api.ts\` — RPC contract (types flow to both sides)
+- \`src/shared/rpc.ts\` — bridge implementation
+
+## Package as \`.vsix\`
+
+\`\`\`bash
+bun run build
+bun run package   # → {{name}}-0.0.1.vsix
+\`\`\`
+`,
+    "react/package.json": `{
+  "name": "{{name}}",
+  "displayName": "{{displayName}}",
+  "description": "{{description}}",
+  "version": "0.0.1",
+  "publisher": "{{publisher}}",
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "main": "./dist/extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "{{commandPrefix}}.hello",
+        "title": "{{displayName}}: Hello"
+      },
+      {
+        "command": "{{commandPrefix}}.openDashboard",
+        "title": "{{displayName}}: Open Dashboard"
+      }
+    ]
+  },
+  "activationEvents": [],
+  "scripts": {
+    "gen:scan": "bun scripts/gen.ts",
+    "gen": "bun run gen:scan && bun run build:ext",
+    "dev": "bun run gen:scan && concurrently -k -n ext,ui -c blue,magenta \\"bun run dev:ext\\" \\"bun run dev:ui\\"",
+    "dev:ext": "esbuild src/extension/extension.ts --bundle --platform=node --target=node18 --external:vscode --outfile=dist/extension.js --watch --sourcemap",
+    "dev:ui": "vite build --watch --mode development",
+    "launch": "bun run build && code --extensionDevelopmentPath=$PWD --new-window",
+    "build": "bun run gen:scan && bun run build:ext && bun run build:ui",
+    "build:ext": "esbuild src/extension/extension.ts --bundle --platform=node --target=node18 --external:vscode --outfile=dist/extension.js --sourcemap",
+    "build:ext:prod": "esbuild src/extension/extension.ts --bundle --platform=node --target=node18 --external:vscode --outfile=dist/extension.js --minify",
+    "build:ui": "vite build",
+    "build:prod": "bun run gen:scan && bun run build:ext:prod && bun run build:ui",
+    "package": "bun run build:prod && vsce package --no-dependencies"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@types/vscode": "^1.85.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "@vscode/vsce": "^2.24.0",
+    "concurrently": "^8.2.0",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}
+`,
+    "react/scripts/gen.ts": `#!/usr/bin/env bun
+// Scans src/panels, src/commands, and src/menus; writes src/extension/_registry.ts
+// and syncs package.json#contributes (commands, viewsContainers, views).
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ROOT = process.cwd();
+const SRC = path.join(ROOT, 'src');
+const PANELS_DIR = path.join(SRC, 'panels');
+const COMMANDS_DIR = path.join(SRC, 'commands');
+const MENUS_DIR = path.join(SRC, 'menus');
+const STATUS_BARS_DIR = path.join(SRC, 'statusBars');
+const SUBPANELS_DIR = path.join(SRC, 'subpanels');
+const TREE_VIEWS_DIR = path.join(SRC, 'treeViews');
+const JOBS_DIR = path.join(SRC, 'jobs');
+const OUT = path.join(SRC, 'extension', '_registry.ts');
+const PKG_PATH = path.join(ROOT, 'package.json');
+
+interface Discovered {
+  id: string;
+  importPath: string;
+}
+
+function scan(dir: string, registryDir: string): Discovered[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && /\\.(ts|tsx)$/.test(e.name) && !e.name.startsWith('_'))
+    .map((e) => {
+      const id = e.name.replace(/\\.(ts|tsx)$/, '');
+      const abs = path.join(dir, e.name);
+      const rel = path.relative(registryDir, abs).replace(/\\\\/g, '/').replace(/\\.(ts|tsx)$/, '');
+      const importPath = rel.startsWith('.') ? rel : \`./\${rel}\`;
+      return { id, importPath };
+    });
+}
+
+function writeRegistry(
+  panels: Discovered[],
+  commands: Discovered[],
+  menus: Discovered[],
+  statusBars: Discovered[],
+  subpanels: Discovered[],
+  treeViews: Discovered[],
+  jobs: Discovered[],
+  prefix: string,
+) {
+  const lines: string[] = [
+    '// AUTO-GENERATED — do not edit. Run \`bun run gen\`.',
+    \`import type { Registry } from '../shared/vsceasy';\`,
+    ...panels.map((p, i) => \`import panel\${i} from '\${p.importPath}';\`),
+    ...commands.map((c, i) => \`import command\${i} from '\${c.importPath}';\`),
+    ...menus.map((m, i) => \`import menu\${i} from '\${m.importPath}';\`),
+    ...statusBars.map((s, i) => \`import statusBar\${i} from '\${s.importPath}';\`),
+    ...subpanels.map((w, i) => \`import subpanel\${i} from '\${w.importPath}';\`),
+    ...treeViews.map((t, i) => \`import treeView\${i} from '\${t.importPath}';\`),
+    ...jobs.map((j, i) => \`import job\${i} from '\${j.importPath}';\`),
+    '',
+    'export const registry: Registry = {',
+    \`  prefix: \${JSON.stringify(prefix)},\`,
+    '  panels: {',
+    ...panels.map((p, i) => \`    \${JSON.stringify(p.id)}: panel\${i},\`),
+    '  },',
+    '  commands: {',
+    ...commands.map((c, i) => \`    \${JSON.stringify(c.id)}: command\${i},\`),
+    '  },',
+    '  menus: {',
+    ...menus.map((m, i) => \`    \${JSON.stringify(m.id)}: menu\${i},\`),
+    '  },',
+    '  statusBars: {',
+    ...statusBars.map((s, i) => \`    \${JSON.stringify(s.id)}: statusBar\${i},\`),
+    '  },',
+    '  subpanels: {',
+    ...subpanels.map((w, i) => \`    \${JSON.stringify(w.id)}: subpanel\${i},\`),
+    '  },',
+    '  treeViews: {',
+    ...treeViews.map((t, i) => \`    \${JSON.stringify(t.id)}: treeView\${i},\`),
+    '  },',
+    '  jobs: {',
+    ...jobs.map((j, i) => \`    \${JSON.stringify(j.id)}: job\${i},\`),
+    '  },',
+    '};',
+    '',
+  ];
+  fs.mkdirSync(path.dirname(OUT), { recursive: true });
+  fs.writeFileSync(OUT, lines.join('\\n'));
+}
+
+function syncPackageJson(
+  panels: Discovered[],
+  commands: Discovered[],
+  menus: Discovered[],
+  subpanels: Discovered[],
+  treeViews: Discovered[],
+  prefix: string,
+  displayName: string,
+) {
+  const pkg = JSON.parse(fs.readFileSync(PKG_PATH, 'utf8'));
+  const contributes = (pkg.contributes ??= {});
+  const cmds: Array<{ command: string; title: string; category?: string; enablement?: string }> = [];
+  const keybindings: Array<{ command: string; key: string; mac?: string; when?: string }> = [];
+  const palette: Array<{ command: string; when?: string }> = [];
+
+  for (const c of commands) {
+    const def = loadDef(path.join(COMMANDS_DIR, c.id + '.ts')) ?? loadDef(path.join(COMMANDS_DIR, c.id + '.tsx'));
+    const fullId = \`\${prefix}.\${def?.id ?? c.id}\`;
+    cmds.push({
+      command: fullId,
+      title: def?.title ?? c.id,
+      category: def?.category ?? displayName,
+      ...(def?.when ? { enablement: def.when } : {}),
+    });
+    if (def?.when) palette.push({ command: fullId, when: def.when });
+    if (def?.keybindings) {
+      for (const kb of def.keybindings) {
+        keybindings.push({
+          command: fullId,
+          key: kb.key,
+          ...(kb.mac ? { mac: kb.mac } : {}),
+          ...(kb.when ? { when: kb.when } : {}),
+        });
+      }
+    }
+  }
+  for (const p of panels) {
+    const def = loadDef(path.join(PANELS_DIR, p.id + '.ts')) ?? loadDef(path.join(PANELS_DIR, p.id + '.tsx'));
+    if (def?.command === false) continue;
+    const opts = typeof def?.command === 'object' ? def!.command : {};
+    cmds.push({
+      command: \`\${prefix}.open\${capitalize(def?.id ?? p.id)}\`,
+      title: (opts as any).title ?? \`Open \${def?.title ?? p.id}\`,
+      category: (opts as any).category ?? displayName,
+    });
+  }
+
+  contributes.commands = cmds;
+  if (keybindings.length) {
+    contributes.keybindings = keybindings;
+  } else {
+    delete contributes.keybindings;
+  }
+  if (palette.length) {
+    contributes.menus ??= {};
+    contributes.menus.commandPalette = palette;
+  } else if (contributes.menus) {
+    delete contributes.menus.commandPalette;
+    if (Object.keys(contributes.menus).length === 0) delete contributes.menus;
+  }
+
+  // Menus → viewsContainers.activitybar + views.<containerId>
+  const containers: Array<{ id: string; title: string; icon: string }> = [];
+  const views: Record<string, Array<{ id: string; name: string; type?: 'webview' }>> = {};
+
+  // Index subpanels by menu they belong to
+  const wvByMenu: Record<string, Array<{ id: string; name: string }>> = {};
+  for (const w of subpanels) {
+    const def = loadSubpanelDef(path.join(SUBPANELS_DIR, w.id + '.ts'))
+      ?? loadSubpanelDef(path.join(SUBPANELS_DIR, w.id + '.tsx'));
+    if (!def?.menu) continue;
+    const viewId = \`\${prefix}-\${def.menu}-\${def.id ?? w.id}\`;
+    const name = def.title ?? w.id;
+    (wvByMenu[def.menu] ??= []).push({ id: viewId, name });
+  }
+
+  // Index tree views by their menu container
+  const tvByMenu: Record<string, Array<{ id: string; name: string }>> = {};
+  for (const t of treeViews) {
+    const def = loadSubpanelDef(path.join(TREE_VIEWS_DIR, t.id + '.ts'))
+      ?? loadSubpanelDef(path.join(TREE_VIEWS_DIR, t.id + '.tsx'));
+    if (!def?.menu) continue;
+    const viewId = \`\${prefix}-\${def.menu}-\${def.id ?? t.id}\`;
+    const name = def.title ?? t.id;
+    (tvByMenu[def.menu] ??= []).push({ id: viewId, name });
+  }
+
+  for (const m of menus) {
+    const def = loadMenuDef(path.join(MENUS_DIR, m.id + '.ts')) ?? loadMenuDef(path.join(MENUS_DIR, m.id + '.tsx'));
+    // VS Code requires viewsContainer / view ids to match /^[A-Za-z0-9_-]+$/ — no dots.
+    const menuId = def?.id ?? m.id;
+    const containerId = \`\${prefix}-\${menuId}\`;
+    const title = def?.title ?? m.id;
+    const icon = resolveIconForPkg(def?.icon);
+    containers.push({ id: containerId, title, icon });
+    const containerViews: Array<{ id: string; name: string; type?: 'webview' }> = [
+      { id: containerId, name: title }, // primary tree view
+    ];
+    for (const v of wvByMenu[menuId] ?? []) {
+      containerViews.push({ id: v.id, name: v.name, type: 'webview' });
+    }
+    for (const t of tvByMenu[menuId] ?? []) {
+      containerViews.push({ id: t.id, name: t.name });
+    }
+    views[containerId] = containerViews;
+  }
+  if (containers.length) {
+    (contributes.viewsContainers ??= {}).activitybar = containers;
+    contributes.views = views;
+  } else {
+    delete contributes.viewsContainers?.activitybar;
+    if (contributes.viewsContainers && Object.keys(contributes.viewsContainers).length === 0) {
+      delete contributes.viewsContainers;
+    }
+    delete contributes.views;
+  }
+
+  fs.writeFileSync(PKG_PATH, JSON.stringify(pkg, null, 2) + '\\n');
+}
+
+function loadDef(file: string): {
+  id?: string;
+  title?: string;
+  category?: string;
+  command?: any;
+  when?: string;
+  keybindings?: Array<{ key: string; mac?: string; when?: string }>;
+} | null {
+  if (!fs.existsSync(file)) return null;
+  const src = fs.readFileSync(file, 'utf8');
+  const grab = (key: string) => {
+    const m = new RegExp(\`\\\\b\${key}\\\\s*:\\\\s*(['"\\\`])((?:\\\\\\\\.|(?!\\\\1).)*)\\\\1\`).exec(src);
+    return m?.[2];
+  };
+  const command =
+    /\\bcommand\\s*:\\s*false\\b/.test(src) ? false :
+    /\\bcommand\\s*:\\s*true\\b/.test(src) ? true :
+    undefined;
+  return {
+    id: grab('id'),
+    title: grab('title'),
+    category: grab('category'),
+    when: grab('when'),
+    command,
+    keybindings: parseKeybindings(src),
+  };
+}
+
+/** Extract keybinding(s) declared on a defineCommand call. Supports string, object, or array shorthand. */
+function parseKeybindings(src: string): Array<{ key: string; mac?: string; when?: string }> {
+  // 1) Plain string:  keybinding: 'ctrl+shift+h'
+  const stringMatch = /\\bkeybinding\\s*:\\s*(['"\`])([^'"\`]+)\\1\\s*,?/.exec(src);
+  if (stringMatch) return [{ key: stringMatch[2] }];
+
+  // 2) Single object:  keybinding: { key: '...', mac?: '...', when?: '...' }
+  const objMatch = /\\bkeybinding\\s*:\\s*\\{([^}]+)\\}/.exec(src);
+  if (objMatch) {
+    const obj = parseKbObject(objMatch[1]);
+    return obj ? [obj] : [];
+  }
+
+  // 3) Array shorthand: keybinding: [ 'ctrl+a', { key: 'ctrl+b', mac: 'cmd+b' } ]
+  const arrMatch = /\\bkeybinding\\s*:\\s*\\[([\\s\\S]*?)\\]/.exec(src);
+  if (arrMatch) {
+    const inner = arrMatch[1];
+    const out: Array<{ key: string; mac?: string; when?: string }> = [];
+    const strRe = /(['"\`])([^'"\`]+)\\1/g;
+    const objRe = /\\{([^}]+)\\}/g;
+    let sm: RegExpExecArray | null;
+    while ((sm = strRe.exec(inner))) out.push({ key: sm[2] });
+    let om: RegExpExecArray | null;
+    while ((om = objRe.exec(inner))) {
+      const o = parseKbObject(om[1]);
+      if (o) out.push(o);
+    }
+    return out;
+  }
+  return [];
+}
+
+function parseKbObject(body: string): { key: string; mac?: string; when?: string } | null {
+  const grab = (key: string) => {
+    const m = new RegExp(\`\\\\b\${key}\\\\s*:\\\\s*(['"\\\`])((?:\\\\\\\\.|(?!\\\\1).)*)\\\\1\`).exec(body);
+    return m?.[2];
+  };
+  const key = grab('key');
+  if (!key) return null;
+  const mac = grab('mac');
+  const when = grab('when');
+  return { key, ...(mac ? { mac } : {}), ...(when ? { when } : {}) };
+}
+
+interface MenuLoaded {
+  id?: string;
+  title?: string;
+  icon?: string | { path?: string; light?: string; dark?: string };
+}
+
+function loadMenuDef(file: string): MenuLoaded | null {
+  if (!fs.existsSync(file)) return null;
+  const src = fs.readFileSync(file, 'utf8');
+  const grab = (key: string) => {
+    const m = new RegExp(\`\\\\b\${key}\\\\s*:\\\\s*(['"\\\`])((?:\\\\\\\\.|(?!\\\\1).)*)\\\\1\`).exec(src);
+    return m?.[2];
+  };
+  let icon: MenuLoaded['icon'];
+  const iconString = grab('icon');
+  if (iconString !== undefined) {
+    icon = iconString;
+  } else {
+    // Try object form: icon: { path: '...' } OR { light: '...', dark: '...' }
+    const objMatch = /\\bicon\\s*:\\s*\\{([^}]+)\\}/.exec(src);
+    if (objMatch) {
+      const body = objMatch[1];
+      const p = /\\bpath\\s*:\\s*(['"\\\`])((?:\\\\.|(?!\\1).)*)\\1/.exec(body);
+      const l = /\\blight\\s*:\\s*(['"\\\`])((?:\\\\.|(?!\\1).)*)\\1/.exec(body);
+      const d = /\\bdark\\s*:\\s*(['"\\\`])((?:\\\\.|(?!\\1).)*)\\1/.exec(body);
+      if (p) icon = { path: p[2] };
+      else if (l && d) icon = { light: l[2], dark: d[2] };
+    }
+  }
+  return { id: grab('id'), title: grab('title'), icon };
+}
+
+interface SubpanelLoaded {
+  id?: string;
+  title?: string;
+  menu?: string;
+}
+
+function loadSubpanelDef(file: string): SubpanelLoaded | null {
+  if (!fs.existsSync(file)) return null;
+  const src = fs.readFileSync(file, 'utf8');
+  const grab = (key: string) => {
+    const m = new RegExp(\`\\\\b\${key}\\\\s*:\\\\s*(['"\\\`])((?:\\\\\\\\.|(?!\\\\1).)*)\\\\1\`).exec(src);
+    return m?.[2];
+  };
+  return { id: grab('id'), title: grab('title'), menu: grab('menu') };
+}
+
+function resolveIconForPkg(icon: MenuLoaded['icon']): string {
+  // VS Code's viewsContainers.activitybar.icon must be a string (path to SVG or codicon ref via "$(name)").
+  if (!icon) return '$(symbol-misc)';
+  if (typeof icon === 'string') return \`$(\${icon})\`;
+  if ('path' in icon && icon.path) return icon.path;
+  if ('light' in icon && icon.light) return icon.light;
+  return '$(symbol-misc)';
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function ensurePanelHtml(panels: Discovered[]) {
+  ensureBundleHtml(path.join(SRC, 'webview', 'panels'), panels);
+}
+
+function ensureSubpanelHtml(views: Discovered[]) {
+  ensureBundleHtml(path.join(SRC, 'webview', 'subpanels'), views);
+}
+
+function ensureBundleHtml(baseDir: string, entries: Discovered[]) {
+  for (const e of entries) {
+    const dir = path.join(baseDir, e.id);
+    if (!fs.existsSync(dir)) continue;
+    const htmlPath = path.join(dir, 'index.html');
+    if (fs.existsSync(htmlPath)) continue;
+    const mainCandidates = ['main.tsx', 'main.ts', 'index.tsx', 'index.ts'];
+    const main = mainCandidates.find((f) => fs.existsSync(path.join(dir, f))) ?? 'main.tsx';
+    fs.writeFileSync(
+      htmlPath,
+      \`<!DOCTYPE html>
+<html><head><meta charset="UTF-8" /></head>
+<body><div id="root"></div><script type="module" src="./\${main}"></script></body>
+</html>
+\`,
+    );
+  }
+}
+
+function main() {
+  const pkg = JSON.parse(fs.readFileSync(PKG_PATH, 'utf8'));
+  const prefix: string =
+    pkg.vsceasy?.commandPrefix ?? pkg.name.replace(/^@[^/]+\\//, '').replace(/[^a-zA-Z0-9]+/g, '');
+  const displayName: string = pkg.displayName ?? pkg.name;
+
+  const registryDir = path.dirname(OUT);
+  const panels = scan(PANELS_DIR, registryDir);
+  const commands = scan(COMMANDS_DIR, registryDir);
+  const menus = scan(MENUS_DIR, registryDir);
+  const statusBars = scan(STATUS_BARS_DIR, registryDir);
+  const subpanels = scan(SUBPANELS_DIR, registryDir);
+  const treeViews = scan(TREE_VIEWS_DIR, registryDir);
+  const jobs = scan(JOBS_DIR, registryDir);
+
+  writeRegistry(panels, commands, menus, statusBars, subpanels, treeViews, jobs, prefix);
+  syncPackageJson(panels, commands, menus, subpanels, treeViews, prefix, displayName);
+  ensurePanelHtml(panels);
+  ensureSubpanelHtml(subpanels);
+
+  console.log(
+    \`✓ vsceasy gen → \${panels.length} panel(s), \${commands.length} command(s), \${menus.length} menu(s), \${statusBars.length} statusBar(s), \${subpanels.length} subpanel(s), \${treeViews.length} treeView(s), \${jobs.length} job(s)\`,
+  );
+}
+
+main();
+`,
+    "react/src/commands/hello.ts": `import { defineCommand } from '../shared/vsceasy';
+
+export default defineCommand({
+  title: 'Hello',
+  run: (vscode) => vscode.window.showInformationMessage('Hello from {{displayName}}!'),
+});
+`,
+    "react/src/extension/extension.ts": `import { bootstrap } from '../shared/vsceasy';
+import { registry } from './_registry';
+
+export const activate = bootstrap(registry);
+export function deactivate() {}
+`,
+    "react/src/panels/dashboard.ts": `import { definePanel } from '../shared/vsceasy';
+import type { DashboardApi } from '../shared/api';
+
+export default definePanel<DashboardApi>({
+  title: '{{displayName}} Dashboard',
+  rpc: (vscode) => ({
+    async getInfo() {
+      return {
+        workspace: vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? null,
+        vscodeVersion: vscode.version,
+      };
+    },
+    async showMessage(text) {
+      await vscode.window.showInformationMessage(text);
+    },
+    async listFiles(pattern) {
+      const uris = await vscode.workspace.findFiles(pattern, '**/node_modules/**', 100);
+      return uris.map((u) => vscode.workspace.asRelativePath(u));
+    },
+  }),
+});
+`,
+    "react/src/shared/api.ts": `// RPC contracts — one interface per panel. Imported by both extension and webview.
+
+export interface DashboardApi {
+  getInfo(): Promise<{ workspace: string | null; vscodeVersion: string }>;
+  showMessage(text: string): Promise<void>;
+  listFiles(pattern: string): Promise<string[]>;
+}
+`,
+    "react/src/shared/vsceasy/bootstrap.ts": `import * as vscode from 'vscode';
+import type { PanelDef, CommandDef, MenuDef, MenuItem, StatusBarDef, StatusBarMenuItem, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule } from './define';
+import { createRpcServer, webviewTransport } from './rpc';
+
+export interface Registry {
+  panels: Record<string, PanelDef>;
+  commands: Record<string, CommandDef>;
+  menus?: Record<string, MenuDef>;
+  statusBars?: Record<string, StatusBarDef>;
+  subpanels?: Record<string, SubpanelDef>;
+  treeViews?: Record<string, TreeViewDef>;
+  jobs?: Record<string, JobDef>;
+  /** Command prefix from package.json (e.g. "myExt"). */
+  prefix: string;
+}
+
+const openPanels = new Map<string, vscode.WebviewPanel>();
+
+/**
+ * Hook fired with the \`ExtensionContext\`. Use to wire \`initDb(context)\`,
+ * \`initSecrets(context)\`, \`initState(context)\`, etc. Return value ignored;
+ * may be sync or async (awaited in order).
+ *
+ * Signature uses \`...rest: any[]\` so any 1- or 2-arg helper (including ones
+ * that declare a typed second parameter like \`initDb(ctx, opts?)\`) assigns
+ * cleanly. The bootstrap runtime always passes the \`vscode\` namespace as the
+ * second arg — helpers free to ignore it or declare their own type.
+ */
+export type ActivateHook = (
+  context: vscode.ExtensionContext,
+  ...rest: any[]
+) => unknown | Promise<unknown>;
+
+export interface BootstrapOptions {
+  /**
+   * Hooks that receive the \`ExtensionContext\` on activate, before any panel /
+   * command / job is registered. Use to wire \`initDb(context)\`, \`initSecrets(context)\`,
+   * \`initState(context)\`, telemetry, etc.
+   */
+  onActivate?: ActivateHook[];
+  /** Symmetric: runs in reverse on deactivate. */
+  onDeactivate?: ActivateHook[];
+}
+
+export function bootstrap(registry: Registry, options: BootstrapOptions = {}) {
+  return async function activate(context: vscode.ExtensionContext) {
+    for (const hook of options.onActivate ?? []) {
+      await hook(context, vscode);
+    }
+    for (const [id, def] of Object.entries(registry.commands)) {
+      const cmd = \`\${registry.prefix}.\${def.id ?? id}\`;
+      context.subscriptions.push(
+        vscode.commands.registerCommand(cmd, (...args) => def.run(vscode, context, ...args)),
+      );
+    }
+
+    for (const [id, def] of Object.entries(registry.panels)) {
+      if (def.command !== false) {
+        const cmd = \`\${registry.prefix}.open\${capitalize(def.id ?? id)}\`;
+        context.subscriptions.push(
+          vscode.commands.registerCommand(cmd, () => openPanel(context, registry.prefix, id, def)),
+        );
+      }
+    }
+
+    if (registry.menus) {
+      for (const [id, def] of Object.entries(registry.menus)) {
+        registerMenu(context, registry, id, def);
+      }
+    }
+
+    if (registry.statusBars) {
+      for (const [id, def] of Object.entries(registry.statusBars)) {
+        registerStatusBar(context, registry, id, def);
+      }
+    }
+
+    if (registry.subpanels) {
+      for (const [id, def] of Object.entries(registry.subpanels)) {
+        registerSubpanel(context, registry, id, def);
+      }
+    }
+
+    if (registry.treeViews) {
+      for (const [id, def] of Object.entries(registry.treeViews)) {
+        registerTreeView(context, registry, id, def);
+      }
+    }
+
+    if (registry.jobs) {
+      for (const [id, def] of Object.entries(registry.jobs)) {
+        registerJob(context, registry, id, def);
+      }
+    }
+
+    // Register deactivate hooks as disposables — fire in reverse order on shutdown.
+    for (const hook of [...(options.onDeactivate ?? [])].reverse()) {
+      context.subscriptions.push({
+        dispose: () => {
+          void hook(context, vscode);
+        },
+      });
+    }
+  };
+}
+
+// --- Jobs (recurring / event-triggered) ---
+
+function registerJob(
+  context: vscode.ExtensionContext,
+  registry: Registry,
+  id: string,
+  def: JobDef,
+) {
+  const jobId = def.id ?? id;
+  const lastRunKey = \`vsceasy.job.\${jobId}.lastRun\`;
+
+  const exec = async (reason: string) => {
+    if (def.minIntervalMs) {
+      const last = (context.globalState.get<number>(lastRunKey) ?? 0);
+      if (Date.now() - last < def.minIntervalMs) return;
+    }
+    try {
+      await def.run(vscode, context);
+      await context.globalState.update(lastRunKey, Date.now());
+    } catch (err) {
+      console.error(\`[vsceasy job:\${jobId}] (\${reason}) failed:\`, err);
+    }
+  };
+
+  const sched = def.schedule;
+  if ('every' in sched) {
+    const ms = parseDuration(sched.every);
+    if (ms <= 0) throw new Error(\`Job "\${jobId}": invalid every=\${sched.every}\`);
+    if (sched.runOnStart !== false) void exec('startup');
+    const handle = setInterval(() => void exec('interval'), ms);
+    context.subscriptions.push({ dispose: () => clearInterval(handle) });
+    return;
+  }
+  if ('dailyAt' in sched) {
+    const [hStr, mStr] = sched.dailyAt.split(':');
+    const h = Number(hStr);
+    const m = Number(mStr ?? '0');
+    if (!Number.isFinite(h) || !Number.isFinite(m)) {
+      throw new Error(\`Job "\${jobId}": invalid dailyAt=\${sched.dailyAt} (expected "HH:MM")\`);
+    }
+    let timer: NodeJS.Timeout | undefined;
+    const scheduleNext = () => {
+      const next = new Date();
+      next.setHours(h, m, 0, 0);
+      if (next.getTime() <= Date.now()) next.setDate(next.getDate() + 1);
+      timer = setTimeout(async () => {
+        await exec('dailyAt');
+        scheduleNext();
+      }, next.getTime() - Date.now());
+    };
+    scheduleNext();
+    context.subscriptions.push({ dispose: () => { if (timer) clearTimeout(timer); } });
+    return;
+  }
+  if ('on' in sched) {
+    let sub: vscode.Disposable;
+    switch (sched.on) {
+      case 'startup':
+        void exec('startup');
+        return;
+      case 'saveDocument':
+        sub = vscode.workspace.onDidSaveTextDocument(() => void exec('saveDocument'));
+        break;
+      case 'openDocument':
+        sub = vscode.workspace.onDidOpenTextDocument(() => void exec('openDocument'));
+        break;
+      case 'changeActiveEditor':
+        sub = vscode.window.onDidChangeActiveTextEditor(() => void exec('changeActiveEditor'));
+        break;
+      case 'changeConfig':
+        sub = vscode.workspace.onDidChangeConfiguration(() => void exec('changeConfig'));
+        break;
+      default:
+        throw new Error(\`Job "\${jobId}": unknown on=\${(sched as { on: string }).on}\`);
+    }
+    context.subscriptions.push(sub);
+    return;
+  }
+  if ('onFile' in sched) {
+    const watcher = vscode.workspace.createFileSystemWatcher(sched.onFile);
+    watcher.onDidChange(() => void exec('onFile:change'));
+    watcher.onDidCreate(() => void exec('onFile:create'));
+    watcher.onDidDelete(() => void exec('onFile:delete'));
+    context.subscriptions.push(watcher);
+    return;
+  }
+}
+
+const DURATION_RE = /^(\\d+)\\s*(ms|s|m|h|d)?$/;
+
+function parseDuration(input: string | number): number {
+  if (typeof input === 'number') return input;
+  const m = DURATION_RE.exec(input.trim());
+  if (!m) return -1;
+  const n = Number(m[1]);
+  switch (m[2] ?? 'ms') {
+    case 'ms': return n;
+    case 's': return n * 1000;
+    case 'm': return n * 60_000;
+    case 'h': return n * 3_600_000;
+    case 'd': return n * 86_400_000;
+    default: return -1;
+  }
+}
+
+// --- Tree Views (data-driven) ---
+
+function registerTreeView(
+  context: vscode.ExtensionContext,
+  registry: Registry,
+  id: string,
+  def: TreeViewDef,
+) {
+  const viewId = \`\${registry.prefix}-\${def.menu}-\${def.id ?? id}\`;
+  const provider = new DataTreeProvider(def, context);
+  const view = vscode.window.createTreeView(viewId, {
+    treeDataProvider: provider,
+    showCollapseAll: def.showCollapseAll !== false,
+  });
+  context.subscriptions.push(view);
+
+  const refreshCmd = \`\${registry.prefix}._tree.\${def.id ?? id}.refresh\`;
+  context.subscriptions.push(
+    vscode.commands.registerCommand(refreshCmd, () => provider.refresh()),
+  );
+
+  const dispatchCmd = \`\${registry.prefix}._tree.\${def.id ?? id}.run\`;
+  context.subscriptions.push(
+    vscode.commands.registerCommand(dispatchCmd, async (node: TreeNode) => {
+      if (node.run) return node.run(vscode, context);
+      if (node.panel) {
+        const p = registry.panels[node.panel];
+        if (p) return openPanel(context, registry.prefix, node.panel, p);
+      }
+      if (node.command) {
+        const c = registry.commands[node.command];
+        if (c) return c.run(vscode, context);
+      }
+    }),
+  );
+  provider.setDispatchCommand(dispatchCmd);
+}
+
+class DataTreeProvider implements vscode.TreeDataProvider<TreeNode> {
+  private _onDidChange = new vscode.EventEmitter<TreeNode | undefined>();
+  readonly onDidChangeTreeData = this._onDidChange.event;
+  private dispatchCmd = '';
+
+  constructor(private readonly def: TreeViewDef, private readonly context: vscode.ExtensionContext) {}
+
+  setDispatchCommand(cmd: string) {
+    this.dispatchCmd = cmd;
+  }
+
+  refresh() {
+    this._onDidChange.fire(undefined);
+  }
+
+  getTreeItem(node: TreeNode): vscode.TreeItem {
+    const hasChildren = !!node.children?.length;
+    const state = hasChildren || node.children === undefined
+      ? node.collapsed === 'expanded'
+        ? vscode.TreeItemCollapsibleState.Expanded
+        : vscode.TreeItemCollapsibleState.Collapsed
+      : vscode.TreeItemCollapsibleState.None;
+    const item = new vscode.TreeItem(node.label, state);
+    item.id = node.id;
+    item.tooltip = node.tooltip;
+    item.description = node.description;
+    item.contextValue = node.contextValue;
+    item.iconPath = resolveIcon(this.context, node.icon);
+    if (this.dispatchCmd && (node.run || node.panel || node.command)) {
+      item.command = { command: this.dispatchCmd, title: node.label, arguments: [node] };
+    }
+    return item;
+  }
+
+  async getChildren(node?: TreeNode): Promise<TreeNode[]> {
+    if (node?.children) return node.children;
+    return Promise.resolve(this.def.getChildren(node, vscode, this.context));
+  }
+}
+
+// --- Webview Views (sidebar inline) ---
+
+function registerSubpanel(
+  context: vscode.ExtensionContext,
+  registry: Registry,
+  id: string,
+  def: SubpanelDef,
+) {
+  // Must match the view id gen.ts writes into package.json#views.<container>.
+  const viewId = \`\${registry.prefix}-\${def.menu}-\${def.id ?? id}\`;
+  const provider: vscode.WebviewViewProvider = {
+    resolveWebviewView(view) {
+      view.webview.options = {
+        enableScripts: true,
+        localResourceRoots: [vscode.Uri.joinPath(context.extensionUri, 'dist', 'webview')],
+      };
+      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());
+      }
+    },
+  };
+  context.subscriptions.push(
+    vscode.window.registerWebviewViewProvider(viewId, provider, {
+      webviewOptions: { retainContextWhenHidden: def.retainContext ?? true },
+    }),
+  );
+}
+
+// --- Status bar items ---
+
+function registerStatusBar(
+  context: vscode.ExtensionContext,
+  registry: Registry,
+  id: string,
+  def: StatusBarDef,
+) {
+  const alignment = def.alignment === 'right'
+    ? vscode.StatusBarAlignment.Right
+    : vscode.StatusBarAlignment.Left;
+  const item = vscode.window.createStatusBarItem(alignment, def.priority ?? 100);
+  item.text = def.icon ? \`$(\${def.icon}) \${def.text}\` : def.text;
+
+  // Tooltip: markdown takes precedence over plain string
+  if (def.tooltipMarkdown) {
+    const md = new vscode.MarkdownString(def.tooltipMarkdown, true);
+    md.supportHtml = true;
+    md.isTrusted = true;
+    item.tooltip = md;
+  } else if (def.tooltip) {
+    item.tooltip = def.tooltip;
+  }
+
+  // Click behaviour priority: menu > panel > command
+  if (def.menu && def.menu.length > 0) {
+    const dispatchCmd = \`\${registry.prefix}._statusBar.\${id}.click\`;
+    context.subscriptions.push(
+      vscode.commands.registerCommand(dispatchCmd, () => openStatusBarMenu(context, registry, def.menu!)),
+    );
+    item.command = dispatchCmd;
+  } else if (def.panel) {
+    const panelDef = registry.panels[def.panel];
+    if (panelDef) {
+      const suffix = capitalize(panelDef.id ?? def.panel);
+      item.command = \`\${registry.prefix}.open\${suffix}\`;
+    } else {
+      console.warn(\`[vsceasy] statusBar "\${id}" references unknown panel "\${def.panel}"\`);
+    }
+  } else if (def.command) {
+    item.command = registry.commands[def.command]
+      ? \`\${registry.prefix}.\${registry.commands[def.command].id ?? def.command}\`
+      : def.command;
+  }
+
+  if (def.backgroundColor) {
+    item.backgroundColor = new vscode.ThemeColor(def.backgroundColor);
+  }
+  item.show();
+  context.subscriptions.push(item);
+}
+
+async function openStatusBarMenu(
+  context: vscode.ExtensionContext,
+  registry: Registry,
+  items: StatusBarMenuItem[],
+) {
+  type QP = vscode.QuickPickItem & { __item: StatusBarMenuItem };
+  const picks: QP[] = items.map((it) => ({
+    label: it.label,
+    description: it.description,
+    detail: it.detail,
+    __item: it,
+  }));
+  const selected = await vscode.window.showQuickPick(picks, { placeHolder: 'Choose action' });
+  if (!selected) return;
+  const it = selected.__item;
+  if (it.url) {
+    await vscode.env.openExternal(vscode.Uri.parse(it.url));
+    return;
+  }
+  if (it.panel) {
+    const panelDef = registry.panels[it.panel];
+    if (panelDef) {
+      const cmd = \`\${registry.prefix}.open\${capitalize(panelDef.id ?? it.panel)}\`;
+      await vscode.commands.executeCommand(cmd);
+    }
+    return;
+  }
+  if (it.command) {
+    const cmd = registry.commands[it.command]
+      ? \`\${registry.prefix}.\${registry.commands[it.command].id ?? it.command}\`
+      : it.command;
+    await vscode.commands.executeCommand(cmd);
+  }
+}
+
+// --- Menus ---
+
+function registerMenu(
+  context: vscode.ExtensionContext,
+  registry: Registry,
+  id: string,
+  def: MenuDef,
+) {
+  // Must match the id gen.ts writes into package.json#viewsContainers/views.
+  // VS Code disallows '.' in view ids, so we use '-' as separator.
+  const viewId = \`\${registry.prefix}-\${def.id ?? id}\`;
+  const provider = new MenuTreeDataProvider(def.items, context);
+  const view = vscode.window.createTreeView(viewId, {
+    treeDataProvider: provider,
+    showCollapseAll: true,
+  });
+  context.subscriptions.push(view);
+
+  // Single dispatch command per menu — passes the item through arguments[0] of contributes.commands.
+  const dispatchCmd = \`\${registry.prefix}._menu.\${def.id ?? id}.run\`;
+  context.subscriptions.push(
+    vscode.commands.registerCommand(dispatchCmd, (item: MenuItem) =>
+      dispatchMenuItem(context, registry, item),
+    ),
+  );
+
+  provider.setDispatchCommand(dispatchCmd);
+}
+
+async function dispatchMenuItem(
+  context: vscode.ExtensionContext,
+  registry: Registry,
+  item: MenuItem,
+) {
+  if (item.url) {
+    await vscode.env.openExternal(vscode.Uri.parse(item.url));
+    return;
+  }
+  if (item.panel) {
+    const panel = registry.panels[item.panel];
+    if (!panel) {
+      vscode.window.showErrorMessage(\`Menu item references unknown panel: \${item.panel}\`);
+      return;
+    }
+    openPanel(context, registry.prefix, item.panel, panel);
+    return;
+  }
+  if (item.command) {
+    const cmd = registry.commands[item.command];
+    if (!cmd) {
+      vscode.window.showErrorMessage(\`Menu item references unknown command: \${item.command}\`);
+      return;
+    }
+    await cmd.run(vscode, context);
+    return;
+  }
+  if (item.run) {
+    await item.run(vscode, context);
+    return;
+  }
+}
+
+class MenuTreeDataProvider implements vscode.TreeDataProvider<MenuItem> {
+  private _onDidChange = new vscode.EventEmitter<MenuItem | undefined>();
+  readonly onDidChangeTreeData = this._onDidChange.event;
+  private dispatchCmd = '';
+
+  constructor(private readonly items: MenuItem[], private readonly context: vscode.ExtensionContext) {}
+
+  setDispatchCommand(cmd: string) {
+    this.dispatchCmd = cmd;
+    this._onDidChange.fire(undefined);
+  }
+
+  getTreeItem(item: MenuItem): vscode.TreeItem {
+    const hasChildren = !!item.children?.length;
+    const collapsibleState = hasChildren
+      ? item.collapsed === 'collapsed'
+        ? vscode.TreeItemCollapsibleState.Collapsed
+        : vscode.TreeItemCollapsibleState.Expanded
+      : vscode.TreeItemCollapsibleState.None;
+    const node = new vscode.TreeItem(item.label, collapsibleState);
+    node.tooltip = item.description ?? item.label;
+    node.description = item.description;
+    node.iconPath = resolveIcon(this.context, item.icon);
+    if (!hasChildren && this.dispatchCmd) {
+      node.command = {
+        command: this.dispatchCmd,
+        title: item.label,
+        arguments: [item],
+      };
+    }
+    return node;
+  }
+
+  getChildren(item?: MenuItem): MenuItem[] {
+    if (!item) return this.items;
+    return item.children ?? [];
+  }
+}
+
+function resolveIcon(
+  context: vscode.ExtensionContext,
+  icon: MenuItem['icon'],
+): vscode.TreeItem['iconPath'] {
+  if (!icon) return undefined;
+  if (typeof icon === 'string') return new vscode.ThemeIcon(icon);
+  const path = require('path') as typeof import('path');
+  const toUri = (p: string) =>
+    path.isAbsolute(p) ? vscode.Uri.file(p) : vscode.Uri.joinPath(context.extensionUri, p);
+  if ('path' in icon) return toUri(icon.path);
+  return { light: toUri(icon.light), dark: toUri(icon.dark) };
+}
+
+function openPanel(context: vscode.ExtensionContext, prefix: string, id: string, def: PanelDef) {
+  const key = \`\${prefix}.\${def.id ?? id}\`;
+  const existing = openPanels.get(key);
+  const column = resolveColumn(def.column);
+  if (existing) {
+    existing.reveal(column);
+    return existing;
+  }
+
+  const panel = vscode.window.createWebviewPanel(
+    key,
+    def.title,
+    column,
+    {
+      enableScripts: true,
+      retainContextWhenHidden: def.retainContext ?? true,
+      localResourceRoots: [vscode.Uri.joinPath(context.extensionUri, 'dist', 'webview')],
+    },
+  );
+
+  const ui = def.ui ?? \`panels/\${def.id ?? id}\`;
+  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());
+  }
+
+  openPanels.set(key, panel);
+  panel.onDidDispose(() => openPanels.delete(key));
+  return panel;
+}
+
+interface ViteManifestEntry {
+  file: string;
+  css?: string[];
+  assets?: string[];
+  imports?: string[];
+}
+type ViteManifest = Record<string, ViteManifestEntry>;
+
+let cachedManifest: { mtime: number; data: ViteManifest } | null = null;
+
+function loadManifest(extensionUri: vscode.Uri): ViteManifest | null {
+  const fs = require('fs') as typeof import('fs');
+  const path = require('path') as typeof import('path');
+  // Vite manifest can land at either \`manifest.json\` (new) or \`.vite/manifest.json\` (default).
+  const webviewRoot = vscode.Uri.joinPath(extensionUri, 'dist', 'webview').fsPath;
+  for (const rel of ['manifest.json', '.vite/manifest.json']) {
+    const p = path.join(webviewRoot, rel);
+    if (!fs.existsSync(p)) continue;
+    const mtime = fs.statSync(p).mtimeMs;
+    if (cachedManifest?.mtime === mtime) return cachedManifest.data;
+    cachedManifest = { mtime, data: JSON.parse(fs.readFileSync(p, 'utf8')) };
+    return cachedManifest.data;
+  }
+  return null;
+}
+
+function resolveAssets(extensionUri: vscode.Uri, ui: string): { js: string[]; css: string[] } {
+  const manifest = loadManifest(extensionUri);
+  if (!manifest) {
+    // Fallback to convention: <ui>/index.js + <ui>/index.css
+    return { js: [\`\${ui}/index.js\`], css: [\`\${ui}/index.css\`] };
+  }
+  // Manifest keys for HTML entries look like \`<ui>/index.html\`.
+  const key = \`\${ui}/index.html\`;
+  const entry = manifest[key];
+  if (!entry) return { js: [\`\${ui}/index.js\`], css: [] };
+  const js = [entry.file];
+  const css = [...(entry.css ?? [])];
+  // Recursively pull CSS from imported chunks.
+  const seen = new Set<string>();
+  const walk = (imp: string) => {
+    if (seen.has(imp)) return;
+    seen.add(imp);
+    const e = manifest[imp];
+    if (!e) return;
+    if (e.css) css.push(...e.css);
+    e.imports?.forEach(walk);
+  };
+  entry.imports?.forEach(walk);
+  return { js, css };
+}
+
+function renderHtml(webview: vscode.Webview, context: vscode.ExtensionContext, ui: string, title: string): string {
+  const root = vscode.Uri.joinPath(context.extensionUri, 'dist', 'webview');
+  const { js, css } = resolveAssets(context.extensionUri, ui);
+  const toUri = (rel: string) =>
+    webview.asWebviewUri(vscode.Uri.joinPath(root, ...rel.split('/'))).toString();
+  const scriptTags = js
+    .map((f) => \`<script type="module" nonce="{{NONCE}}" src="\${toUri(f)}"></script>\`)
+    .join('\\n    ');
+  const styleTags = css.map((f) => \`<link rel="stylesheet" href="\${toUri(f)}" />\`).join('\\n    ');
+  const nonce = Array.from({ length: 16 }, () => Math.random().toString(36)[2]).join('');
+  const csp = [
+    \`default-src 'none'\`,
+    \`style-src \${webview.cspSource} 'unsafe-inline'\`,
+    \`script-src 'nonce-\${nonce}'\`,
+    \`img-src \${webview.cspSource} https: data:\`,
+    \`font-src \${webview.cspSource}\`,
+  ].join('; ');
+
+  return \`<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="Content-Security-Policy" content="\${csp}" />
+    \${styleTags}
+    <title>\${escapeHtml(title)}</title>
+  </head>
+  <body><div id="root"></div>
+    \${scriptTags.replace(/\\{\\{NONCE\\}\\}/g, nonce)}
+  </body>
+</html>\`;
+}
+
+function resolveColumn(c: PanelDef['column']): vscode.ViewColumn {
+  switch (c) {
+    case 'beside': return vscode.ViewColumn.Beside;
+    case 'one': return vscode.ViewColumn.One;
+    case 'two': return vscode.ViewColumn.Two;
+    case 'three': return vscode.ViewColumn.Three;
+    default: return vscode.window.activeTextEditor?.viewColumn ?? vscode.ViewColumn.One;
+  }
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!));
+}
+`,
+    "react/src/shared/vsceasy/client.ts": `// Webview-safe exports only — does NOT import 'vscode'.
+export {
+  createRpcClient,
+  vscodeApiTransport,
+  connectWebview,
+  webviewState,
+} from './rpc';
+export type { RpcClient, Handlers, Transport, RpcClientOptions, WebviewApi } from './rpc';
+`,
+    "react/src/shared/vsceasy/codiconNames.ts": `/**
+ * AUTO-GENERATED by scripts/genCodiconTypes.ts — do not edit.
+ *
+ * Curated subset of VS Code codicon names that the CLI's icon picker offers.
+ * Used by \`MenuIcon\` for editor autocomplete. Any string is still accepted at
+ * runtime via the \`(string & {})\` fallback in define.ts.
+ *
+ * Full list: https://microsoft.github.io/vscode-codicons/dist/codicon.html
+ */
+export type CodiconName =
+  | 'account'
+  | 'add'
+  | 'archive'
+  | 'beaker'
+  | 'bell'
+  | 'bell-dot'
+  | 'book'
+  | 'bookmark'
+  | 'broadcast'
+  | 'browser'
+  | 'bug'
+  | 'calendar'
+  | 'check'
+  | 'clock'
+  | 'close'
+  | 'cloud'
+  | 'cloud-download'
+  | 'cloud-upload'
+  | 'code'
+  | 'comment'
+  | 'comment-discussion'
+  | 'compass'
+  | 'console'
+  | 'dashboard'
+  | 'database'
+  | 'debug'
+  | 'debug-alt'
+  | 'debug-breakpoint'
+  | 'debug-console'
+  | 'debug-continue'
+  | 'debug-disconnect'
+  | 'debug-pause'
+  | 'debug-restart'
+  | 'debug-start'
+  | 'debug-step-into'
+  | 'debug-step-out'
+  | 'debug-step-over'
+  | 'debug-stop'
+  | 'desktop-download'
+  | 'edit'
+  | 'error'
+  | 'export'
+  | 'extensions'
+  | 'eye'
+  | 'eye-closed'
+  | 'file'
+  | 'file-binary'
+  | 'file-code'
+  | 'file-media'
+  | 'file-pdf'
+  | 'file-symlink-directory'
+  | 'file-symlink-file'
+  | 'file-text'
+  | 'file-zip'
+  | 'files'
+  | 'filter'
+  | 'flag'
+  | 'flame'
+  | 'folder'
+  | 'folder-active'
+  | 'folder-library'
+  | 'folder-opened'
+  | 'gear'
+  | 'git-branch'
+  | 'git-commit'
+  | 'git-compare'
+  | 'git-fork'
+  | 'git-merge'
+  | 'git-pull-request'
+  | 'github'
+  | 'github-alt'
+  | 'github-inverted'
+  | 'globe'
+  | 'graph'
+  | 'heart'
+  | 'history'
+  | 'home'
+  | 'image'
+  | 'inbox'
+  | 'info'
+  | 'json'
+  | 'key'
+  | 'layout'
+  | 'layout-panel'
+  | 'layout-sidebar-left'
+  | 'layout-sidebar-right'
+  | 'lightbulb'
+  | 'link'
+  | 'link-external'
+  | 'list-flat'
+  | 'list-ordered'
+  | 'list-selection'
+  | 'list-tree'
+  | 'list-unordered'
+  | 'location'
+  | 'lock'
+  | 'mail'
+  | 'markdown'
+  | 'megaphone'
+  | 'mortar-board'
+  | 'mute'
+  | 'new-file'
+  | 'new-folder'
+  | 'note'
+  | 'notebook'
+  | 'organization'
+  | 'output'
+  | 'package'
+  | 'pencil'
+  | 'person'
+  | 'pin'
+  | 'pinned'
+  | 'play'
+  | 'play-circle'
+  | 'plug'
+  | 'preferences'
+  | 'preview'
+  | 'pulse'
+  | 'question'
+  | 'record'
+  | 'refresh'
+  | 'remove'
+  | 'replace'
+  | 'repo'
+  | 'repo-clone'
+  | 'repo-forked'
+  | 'repo-pull'
+  | 'repo-push'
+  | 'rocket'
+  | 'save'
+  | 'save-all'
+  | 'search'
+  | 'server'
+  | 'server-environment'
+  | 'server-process'
+  | 'settings'
+  | 'settings-gear'
+  | 'shield'
+  | 'source-control'
+  | 'sparkle'
+  | 'split-horizontal'
+  | 'split-vertical'
+  | 'star'
+  | 'star-empty'
+  | 'star-full'
+  | 'stop'
+  | 'stop-circle'
+  | 'symbol-array'
+  | 'symbol-boolean'
+  | 'symbol-class'
+  | 'symbol-color'
+  | 'symbol-constant'
+  | 'symbol-enum'
+  | 'symbol-event'
+  | 'symbol-field'
+  | 'symbol-function'
+  | 'symbol-interface'
+  | 'symbol-key'
+  | 'symbol-method'
+  | 'symbol-misc'
+  | 'symbol-module'
+  | 'symbol-namespace'
+  | 'symbol-numeric'
+  | 'symbol-parameter'
+  | 'symbol-property'
+  | 'symbol-snippet'
+  | 'symbol-string'
+  | 'symbol-variable'
+  | 'sync'
+  | 'tag'
+  | 'terminal'
+  | 'terminal-bash'
+  | 'terminal-cmd'
+  | 'terminal-linux'
+  | 'terminal-powershell'
+  | 'tools'
+  | 'trash'
+  | 'unlock'
+  | 'unmute'
+  | 'verified'
+  | 'video'
+  | 'wand'
+  | 'warning'
+  | 'watch'
+  | 'window'
+  | 'zap';
+`,
+    "react/src/shared/vsceasy/define.ts": `import type * as vscode from 'vscode';
+import type { Handlers } from './rpc';
+import type { CodiconName } from './codiconNames';
+
+export interface PanelDef<H extends Handlers = Handlers> {
+  /** Stable id. Default: file basename. Used as command suffix and webview key. */
+  id?: string;
+  /** Tab title. */
+  title: string;
+  /** Webview bundle name under dist/webview/<ui>/. Default: same as id. */
+  ui?: string;
+  /** Where to open. Default: 'active'. */
+  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;
+  /** Optional command palette entry that opens this panel. Default: true. */
+  command?:
+    | boolean
+    | { title?: string; category?: string };
+}
+
+export interface CommandDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Command palette title. */
+  title: string;
+  /** Optional category prefix (default: extension displayName). */
+  category?: string;
+  /** Handler. Receives vscode + extension context. */
+  run: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, ...args: unknown[]) => unknown | Promise<unknown>;
+  /**
+   * Keyboard shortcut. String shorthand uses the same key on every platform.
+   * Object form supports \`mac\` override and a VS Code \`when\` clause.
+   * Written to package.json#contributes.keybindings by \`bun run gen\`.
+   */
+  keybinding?: string | KeybindingDef | (string | KeybindingDef)[];
+  /**
+   * VS Code \`when\` clause that controls visibility/enablement of this command
+   * in the command palette and auto-generated menu entries. Written to
+   * \`contributes.commands[].enablement\` and used as the default \`when\` on
+   * the palette menu entry by \`bun run gen\`.
+   *
+   * Examples: \`'editorTextFocus'\`, \`'resourceLangId == typescript'\`,
+   * \`'explorerResourceIsFolder && !virtualWorkspace'\`.
+   * Reference: https://code.visualstudio.com/api/references/when-clause-contexts
+   */
+  when?: string;
+}
+
+export interface KeybindingDef {
+  /** Default key combo (e.g. 'ctrl+shift+h'). */
+  key: string;
+  /** Override combo on macOS (e.g. 'cmd+shift+h'). */
+  mac?: string;
+  /** VS Code context \`when\` clause (e.g. 'editorTextFocus'). */
+  when?: string;
+}
+
+export function definePanel<H extends Handlers = Handlers>(def: PanelDef<H>): PanelDef<H> {
+  return def;
+}
+
+export function defineCommand(def: CommandDef): CommandDef {
+  return def;
+}
+
+// --- Menus (Activity Bar + Tree View) ---
+
+export type MenuIcon =
+  | CodiconName                                // known codicon (autocompletes)
+  | (string & {})                              // any codicon name (escape hatch, keeps autocomplete)
+  | { path: string }                           // single SVG path relative to project root
+  | { light: string; dark: string };           // theme-aware SVG paths
+
+export type { CodiconName };
+
+export interface MenuItem {
+  /** Display label. */
+  label: string;
+  /** Optional icon (codicon name or asset path). */
+  icon?: MenuIcon;
+  /** Optional tooltip / hover description. */
+  description?: string;
+  /** Open a panel by id (file basename in src/panels/). */
+  panel?: string;
+  /** Execute a command by id (file basename in src/commands/). */
+  command?: string;
+  /** Open an external URL in the user's browser. */
+  url?: string;
+  /** Run an arbitrary handler (full vscode access). */
+  run?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => unknown | Promise<unknown>;
+  /** Nested items — renders as a collapsible group. */
+  children?: MenuItem[];
+  /** Initial collapsed state for groups. Default: 'expanded'. */
+  collapsed?: 'expanded' | 'collapsed';
+}
+
+export interface MenuDef {
+  /** Stable id. Default: file basename. Becomes the view container id. */
+  id?: string;
+  /** Title shown at the top of the sidebar panel and as the activity bar tooltip. */
+  title: string;
+  /** Activity bar icon. Codicon string OR SVG path(s). */
+  icon: MenuIcon;
+  /** Items shown in the tree view. */
+  items: MenuItem[];
+}
+
+export function defineMenu(def: MenuDef): MenuDef {
+  return def;
+}
+
+// --- Webview Views (inline sidebar sections) ---
+
+export interface SubpanelDef<H extends Handlers = Handlers> {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Section header shown in the sidebar. */
+  title: string;
+  /** Menu (activity bar container) this view lives in — basename in src/menus/. */
+  menu: string;
+  /** Webview bundle name under dist/webview/<ui>/. Default: same as id. */
+  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;
+}
+
+export function defineSubpanel<H extends Handlers = Handlers>(def: SubpanelDef<H>): SubpanelDef<H> {
+  return def;
+}
+
+// --- Status Bar items ---
+
+export interface StatusBarDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Display text. May include \`$(codicon)\` syntax. */
+  text: string;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Optional codicon, prepended as \`$(icon) text\` when both present. */
+  icon?: CodiconName | (string & {});
+  /** Bar side. Default: 'left'. */
+  alignment?: 'left' | 'right';
+  /** Higher = leftmost on its side. Default: 100. */
+  priority?: number;
+  /** Command id to run on click (basename in src/commands/, or full vscode command id). */
+  command?: string;
+  /** Open a panel by id (basename in src/panels/). Takes precedence over \`command\` when set. */
+  panel?: string;
+  /** Background color theme key (e.g. 'statusBarItem.warningBackground'). */
+  backgroundColor?: string;
+  /**
+   * Rich markdown tooltip (overrides \`tooltip\`). Supports command links
+   * (\`[text](command:ext.foo)\`), codicons (\`$(rocket)\`), and HTML.
+   * Rendered on hover. Mimics Copilot/GitLens popup style.
+   */
+  tooltipMarkdown?: string;
+  /**
+   * Open a popup menu on click instead of running a single command/panel.
+   * Each item runs its \`command\`, opens its \`panel\`, or opens its \`url\`.
+   */
+  menu?: StatusBarMenuItem[];
+}
+
+export interface StatusBarMenuItem {
+  /** Display label. May include \`$(codicon)\`. */
+  label: string;
+  /** Inline secondary text. */
+  description?: string;
+  /** Detail line (smaller, below). */
+  detail?: string;
+  /** Command id (basename in src/commands/) or full vscode command id. */
+  command?: string;
+  /** Panel id (basename in src/panels/). */
+  panel?: string;
+  /** External URL. */
+  url?: string;
+}
+
+export function defineStatusBar(def: StatusBarDef): StatusBarDef {
+  return def;
+}
+
+// --- Tree Views (data-driven) ---
+
+export interface TreeNode {
+  /** Display label. */
+  label: string;
+  /** Stable id, defaults to label. Used for reveal/select. */
+  id?: string;
+  /** Optional icon. */
+  icon?: MenuIcon;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Right-aligned description text. */
+  description?: string;
+  /** Context value used by \`view/item/context\` menu entries. */
+  contextValue?: string;
+  /** Initial state when this node has children. Default: 'collapsed'. */
+  collapsed?: 'expanded' | 'collapsed';
+  /** Eagerly provided children. If omitted, getChildren(this) is called lazily. */
+  children?: TreeNode[];
+  /** Click handler — run an arbitrary callback when the node is selected. */
+  run?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => unknown | Promise<unknown>;
+  /** Click → open a panel by id. */
+  panel?: string;
+  /** Click → run a command by id. */
+  command?: string;
+}
+
+export interface TreeViewDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Sidebar section header. */
+  title: string;
+  /** Activity bar container id (menu basename in src/menus/). */
+  menu: string;
+  /** Show "Collapse All" button. Default: true. */
+  showCollapseAll?: boolean;
+  /** Initial / refreshed nodes. Called on mount and whenever the view is refreshed. */
+  getChildren: (
+    parent: TreeNode | undefined,
+    vscode: typeof import('vscode'),
+    ctx: vscode.ExtensionContext,
+  ) => TreeNode[] | Promise<TreeNode[]>;
+}
+
+export function defineTreeView(def: TreeViewDef): TreeViewDef {
+  return def;
+}
+
+// --- Jobs (recurring / event-triggered tasks) ---
+
+export type JobSchedule =
+  /** Run every <interval>. Accepts ms number or duration string: "30s", "5m", "2h", "1d". */
+  | { every: string | number; runOnStart?: boolean }
+  /** Run at HH:MM local time, every day. */
+  | { dailyAt: string }
+  /** Run on a VS Code lifecycle event. */
+  | { on: 'startup' | 'saveDocument' | 'openDocument' | 'changeActiveEditor' | 'changeConfig' }
+  /** Run on filesystem changes matching a glob (relative to workspace). */
+  | { onFile: string };
+
+export interface JobDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Display label (used in logs + opt. status bar). */
+  title: string;
+  /** When to run. */
+  schedule: JobSchedule;
+  /**
+   * Skip if last successful run was less than this many ms ago. Stored in
+   * \`context.globalState\` under \`vsceasy.job.<id>.lastRun\`. Useful for jobs
+   * that should at most run every N hours regardless of how often the
+   * trigger fires.
+   */
+  minIntervalMs?: number;
+  /** The actual work. Errors are caught and logged — they never crash the host. */
+  run: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => unknown | Promise<unknown>;
+}
+
+export function defineJob(def: JobDef): JobDef {
+  return def;
+}
+`,
+    "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 { bootstrap } from './bootstrap';
+export type { Registry, BootstrapOptions, ActivateHook } from './bootstrap';
+export {
+  createRpcClient,
+  createRpcServer,
+  webviewTransport,
+  vscodeApiTransport,
+  connectWebview,
+  webviewState,
+} from './rpc';
+export type { Transport, RpcClient, Handlers, RpcClientOptions, WebviewApi } from './rpc';
+`,
+    "react/src/shared/vsceasy/rpc.ts": `// Typed RPC bridge — webview <-> extension.
+// Used by both sides. Transport-agnostic core + thin adapters.
+
+export type RpcMessage =
+  | { id: string; kind: 'call'; method: string; args: unknown[] }
+  | { id: string; kind: 'result'; ok: true; value: unknown }
+  | { id: string; kind: 'result'; ok: false; error: { message: string; stack?: string } }
+  | { kind: 'event'; topic: string; payload: unknown };
+
+export interface Transport {
+  send(msg: RpcMessage): void;
+  onMessage(handler: (msg: RpcMessage) => void): () => void;
+}
+
+// --- Server (extension side) ---
+
+/**
+ * Loose constraint: an interface with method members. Using \`object\` (instead
+ * of a Record with index signature) lets user-declared interfaces satisfy the
+ * constraint without forcing them to declare \`[k: string]: any\`.
+ */
+export type Handlers = object;
+
+export function createRpcServer<H extends Handlers>(transport: Transport, handlers: H) {
+  const off = transport.onMessage(async (msg) => {
+    if (msg.kind !== 'call') return;
+    const fn = (handlers as Record<string, (...args: any[]) => any>)[msg.method];
+    if (!fn) {
+      transport.send({
+        id: msg.id,
+        kind: 'result',
+        ok: false,
+        error: { message: \`Unknown RPC method: \${msg.method}\` },
+      });
+      return;
+    }
+    try {
+      const value = await fn(...msg.args);
+      transport.send({ id: msg.id, kind: 'result', ok: true, value });
+    } catch (err: any) {
+      transport.send({
+        id: msg.id,
+        kind: 'result',
+        ok: false,
+        error: { message: String(err?.message ?? err), stack: err?.stack },
+      });
+    }
+  });
+
+  return {
+    emit(topic: string, payload: unknown) {
+      transport.send({ kind: 'event', topic, payload });
+    },
+    dispose: off,
+  };
+}
+
+// --- Client (webview side) ---
+
+export type RpcClient<H extends Handlers> = {
+  [K in keyof H]: H[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<Awaited<R>>
+    : never;
+} & {
+  on(topic: string, handler: (payload: any) => void): () => void;
+};
+
+export interface RpcClientOptions {
+  /**
+   * Max wait (ms) for a call's reply before rejecting with a timeout error.
+   * Prevents hangs when the extension host reloads mid-flight during \`bun run dev\`.
+   * Default: 15000. Set to 0 to disable.
+   */
+  callTimeoutMs?: number;
+}
+
+export function createRpcClient<H extends Handlers>(
+  transport: Transport,
+  opts: RpcClientOptions = {},
+): RpcClient<H> {
+  const callTimeoutMs = opts.callTimeoutMs ?? 15000;
+  const pending = new Map<string, { resolve: (v: any) => void; reject: (e: any) => void; timer?: ReturnType<typeof setTimeout> }>();
+  const listeners = new Map<string, Set<(p: any) => void>>();
+
+  transport.onMessage((msg) => {
+    if (msg.kind === 'result') {
+      const p = pending.get(msg.id);
+      if (!p) return;
+      pending.delete(msg.id);
+      if (p.timer) clearTimeout(p.timer);
+      if (msg.ok) p.resolve(msg.value);
+      else p.reject(Object.assign(new Error(msg.error.message), { stack: msg.error.stack }));
+    } else if (msg.kind === 'event') {
+      listeners.get(msg.topic)?.forEach((l) => l(msg.payload));
+    }
+  });
+
+  let counter = 0;
+  const newId = () => \`r\${++counter}_\${Date.now()}\`;
+
+  const proxy = new Proxy({} as any, {
+    get(_t, prop: string) {
+      if (prop === 'on') {
+        return (topic: string, handler: (p: any) => void) => {
+          let set = listeners.get(topic);
+          if (!set) listeners.set(topic, (set = new Set()));
+          set.add(handler);
+          return () => set!.delete(handler);
+        };
+      }
+      return (...args: unknown[]) =>
+        new Promise((resolve, reject) => {
+          const id = newId();
+          const entry: { resolve: (v: any) => void; reject: (e: any) => void; timer?: ReturnType<typeof setTimeout> } = { resolve, reject };
+          if (callTimeoutMs > 0) {
+            entry.timer = setTimeout(() => {
+              if (pending.delete(id)) {
+                reject(new Error(\`RPC \\\`\${prop}\\\` timed out after \${callTimeoutMs}ms (extension host reloaded?)\`));
+              }
+            }, callTimeoutMs);
+          }
+          pending.set(id, entry);
+          try {
+            transport.send({ id, kind: 'call', method: prop, args });
+          } catch (err) {
+            pending.delete(id);
+            if (entry.timer) clearTimeout(entry.timer);
+            reject(err);
+          }
+        });
+    },
+  });
+
+  return proxy as RpcClient<H>;
+}
+
+// --- Transports ---
+
+export function webviewTransport(webview: { postMessage(m: any): any; onDidReceiveMessage: any }): Transport {
+  return {
+    send: (m) => webview.postMessage(m),
+    onMessage: (h) => {
+      const sub = webview.onDidReceiveMessage((m: RpcMessage) => h(m));
+      return () => sub.dispose();
+    },
+  };
+}
+
+export function vscodeApiTransport(vscode: { postMessage(m: any): void }): Transport {
+  return {
+    send: (m) => vscode.postMessage(m),
+    onMessage: (h) => {
+      const listener = (e: MessageEvent) => h(e.data as RpcMessage);
+      window.addEventListener('message', listener);
+      return () => window.removeEventListener('message', listener);
+    },
+  };
+}
+
+declare global {
+  function acquireVsCodeApi(): WebviewApi;
+}
+
+export interface WebviewApi {
+  postMessage(m: any): void;
+  getState(): unknown;
+  setState<T>(s: T): T;
+}
+
+let _cachedVscode: WebviewApi | null = null;
+function vscodeApi(): WebviewApi {
+  // acquireVsCodeApi() may only be called once per webview lifetime.
+  if (_cachedVscode) return _cachedVscode;
+  return (_cachedVscode = acquireVsCodeApi());
+}
+
+/** One-liner for webview: returns a typed RPC client. */
+export function connectWebview<H extends Handlers>(opts?: RpcClientOptions): RpcClient<H> {
+  return createRpcClient<H>(vscodeApiTransport(vscodeApi()), opts);
+}
+
+/**
+ * Typed \`vscode.getState() / setState()\` wrapper for webviews. State survives
+ * panel hide/show, host reloads triggered by \`retainContextWhenHidden\`, and
+ * is the recommended way to persist scroll positions, form data, and selection.
+ *
+ * Usage:
+ *   const state = webviewState<{ query: string }>({ query: '' });
+ *   state.set({ query: 'foo' });
+ *   const { query } = state.get();
+ */
+export function webviewState<T>(defaults: T): {
+  get(): T;
+  set(next: T | ((prev: T) => T)): T;
+  patch(partial: Partial<T>): T;
+} {
+  const api = vscodeApi();
+  const init = (): T => ({ ...defaults, ...((api.getState() as T | undefined) ?? {}) });
+  return {
+    get: init,
+    set(next) {
+      const current = init();
+      const value = typeof next === 'function' ? (next as (p: T) => T)(current) : next;
+      api.setState(value);
+      return value;
+    },
+    patch(partial) {
+      const current = init();
+      const value = { ...current, ...partial };
+      api.setState(value);
+      return value;
+    },
+  };
+}
+`,
+    "react/src/webview/panels/dashboard/App.tsx": `import React, { useEffect, useState } from 'react';
+import { connectWebview } from '../../../shared/vsceasy/client';
+import type { DashboardApi } from '../../../shared/api';
+
+const api = connectWebview<DashboardApi>();
+
+export function App() {
+  const [info, setInfo] = useState<{ workspace: string | null; vscodeVersion: string } | null>(null);
+  const [files, setFiles] = useState<string[]>([]);
+  const [pattern, setPattern] = useState('**/*.ts');
+
+  useEffect(() => { api.getInfo().then(setInfo); }, []);
+
+  return (
+    <div className="app">
+      <h1>{{displayName}} Dashboard</h1>
+      {info && (
+        <section>
+          <p><strong>Workspace:</strong> {info.workspace ?? '(none)'}</p>
+          <p><strong>VS Code:</strong> {info.vscodeVersion}</p>
+        </section>
+      )}
+      <section>
+        <input value={pattern} onChange={(e) => setPattern(e.target.value)} />
+        <button onClick={async () => setFiles(await api.listFiles(pattern))}>Find files</button>
+        <button onClick={() => api.showMessage('Hello from the webview!')}>Toast</button>
+        <ul>{files.map((f) => <li key={f}>{f}</li>)}</ul>
+      </section>
+    </div>
+  );
+}
+`,
+    "react/src/webview/panels/dashboard/main.tsx": `import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import '../../styles.css';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`,
+    "react/src/webview/styles.css": `:root { color-scheme: light dark; }
+
+body {
+  margin: 0;
+  padding: 1rem;
+  font-family: var(--vscode-font-family);
+  font-size: var(--vscode-font-size);
+  color: var(--vscode-foreground);
+  background: var(--vscode-editor-background);
+}
+
+.app h1 { font-size: 1.25rem; margin: 0 0 1rem; }
+
+button, input {
+  font: inherit;
+  color: var(--vscode-button-foreground, inherit);
+  background: var(--vscode-button-background, transparent);
+  border: 1px solid var(--vscode-button-border, var(--vscode-input-border, #555));
+  padding: 0.35rem 0.75rem;
+  border-radius: 2px;
+  margin-right: 0.5rem;
+}
+
+input {
+  background: var(--vscode-input-background);
+  color: var(--vscode-input-foreground);
+  min-width: 16rem;
+}
+
+button:hover { background: var(--vscode-button-hoverBackground); }
+
+ul { padding-left: 1.25rem; }
+li { line-height: 1.6; }
+`,
+    "react/tsconfig.json": `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+`,
+    "react/vite.config.ts": `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const WEBVIEW_ROOT = path.resolve(__dirname, 'src/webview');
+
+function discoverHtmlEntries(subdir: string): Record<string, string> {
+  const dir = path.join(WEBVIEW_ROOT, subdir);
+  if (!fs.existsSync(dir)) return {};
+  const out: Record<string, string> = {};
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const html = path.join(dir, entry.name, 'index.html');
+    // Key includes subdir so panel \`dashboard\` and subpanel \`dashboard\` never collide.
+    if (fs.existsSync(html)) out[\`\${subdir}/\${entry.name}\`] = html;
+  }
+  return out;
+}
+
+const entries = {
+  ...discoverHtmlEntries('panels'),
+  ...discoverHtmlEntries('subpanels'),
+};
+
+export default defineConfig({
+  plugins: [react()],
+  root: WEBVIEW_ROOT,
+  build: {
+    outDir: path.resolve(__dirname, 'dist/webview'),
+    emptyOutDir: true,
+    manifest: 'manifest.json',
+    rollupOptions: {
+      input: entries,
+      output: {
+        entryFileNames: '[name]/index.js',
+        chunkFileNames: 'chunks/[name]-[hash].js',
+        assetFileNames: 'assets/[name]-[hash].[ext]',
+      },
+    },
+  },
+});
+`
+  };
+});
+
 // src/lib/findProject.ts
 function findProjectRoot(start = process.cwd()) {
   let dir = path14.resolve(start);
@@ -2258,20 +6048,59 @@ function findProjectRoot(start = process.cwd()) {
     dir = path14.dirname(dir);
   }
 }
-function findTemplatesRoot(fromFile = __dirname) {
-  const candidates = [
-    path14.resolve(fromFile, "..", "templates"),
-    path14.resolve(fromFile, "..", "..", "templates"),
-    path14.resolve(fromFile, "..", "..", "..", "templates")
-  ];
-  for (const c of candidates)
-    if (fs14.existsSync(c))
-      return c;
-  throw new Error(`templates/ directory not found near ${fromFile}`);
+function findTemplatesRoot(fromFile = process.argv[1] ?? __dirname) {
+  const onDisk = findTemplatesOnDisk(fromFile);
+  if (onDisk)
+    return onDisk;
+  return materializeEmbeddedTemplates();
+}
+function findTemplatesOnDisk(fromFile) {
+  let dir = path14.dirname(path14.resolve(fromFile));
+  const { root } = path14.parse(dir);
+  while (true) {
+    const candidate = path14.join(dir, "templates");
+    if (fs14.existsSync(candidate) && fs14.statSync(candidate).isDirectory()) {
+      try {
+        if (fs14.readdirSync(candidate).length > 0)
+          return candidate;
+      } catch {}
+    }
+    if (dir === root)
+      return;
+    dir = path14.dirname(dir);
+  }
 }
-var fs14, path14, __dirname = "/home/runner/work/vsceasy/vsceasy/src/lib";
+function materializeEmbeddedTemplates() {
+  if (materializedRoot)
+    return materializedRoot;
+  const keys = Object.keys(TEMPLATE_FILES);
+  if (keys.length === 0) {
+    throw new Error("No templates available: on-disk templates/ not found and no embedded " + "templates were bundled. This is a packaging bug — rebuild with " + "`bun run build` (runs scripts/embedTemplates.ts).");
+  }
+  const hash = crypto.createHash("sha1").update(`${TEMPLATES_VERSION}:${keys.length}:${keys.join("|")}`).digest("hex").slice(0, 12);
+  const dest = path14.join(os.tmpdir(), `vsceasy-templates-${TEMPLATES_VERSION}-${hash}`);
+  const sentinel = path14.join(dest, ".complete");
+  if (fs14.existsSync(sentinel)) {
+    materializedRoot = dest;
+    return dest;
+  }
+  fs14.rmSync(dest, { recursive: true, force: true });
+  fs14.mkdirSync(dest, { recursive: true });
+  for (const rel of keys) {
+    const abs = path14.join(dest, rel);
+    fs14.mkdirSync(path14.dirname(abs), { recursive: true });
+    fs14.writeFileSync(abs, TEMPLATE_FILES[rel]);
+  }
+  fs14.writeFileSync(sentinel, "");
+  materializedRoot = dest;
+  return dest;
+}
+var crypto, fs14, os, path14, __dirname = "/home/runner/work/vsceasy/vsceasy/src/lib", materializedRoot;
 var init_findProject = __esm(() => {
+  init_templatesData();
+  crypto = __toESM(require("crypto"));
   fs14 = __toESM(require("fs"));
+  os = __toESM(require("os"));
   path14 = __toESM(require("path"));
 });