@pyreon/mcp 0.12.12 → 0.12.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/mcp",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "description": "MCP server for Pyreon — AI-powered framework assistance",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/mcp#readme",
   "bugs": {
@@ -46,9 +46,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@pyreon/compiler": "^0.12.12",
+    "@pyreon/compiler": "^0.12.14",
     "zod": "^4.3.6"
   },
+  "devDependencies": {
+    "@pyreon/manifest": "0.0.0"
+  },
   "peerDependencies": {
     "typescript": ">=5.0.0"
   }

package/src/api-reference.ts

@@ -747,9 +747,10 @@ await doc.toNotion()   // Notion blocks`,
   // @pyreon/flow
   // ═══════════════════════════════════════════════════════════════════════════
 
+  // <gen-docs:api-reference:start @pyreon/flow>
+
   'flow/createFlow': {
-    signature:
-      'createFlow<TData = Record<string, unknown>>(config: FlowConfig<TData>): FlowInstance<TData>',
+    signature: '<TData = Record<string, unknown>>(config: FlowConfig<TData>) => FlowInstance<TData>',
     example: `// Generic over node data shape — typed consumers get strong narrowing
 interface WorkflowData {
   kind: 'trigger' | 'filter' | 'transform' | 'notify'
@@ -768,13 +769,52 @@ const flow = createFlow<WorkflowData>({
 const trigger = flow.findNodes((n) => n.data.kind === 'trigger')
 
 flow.addNode({ id: '3', type: 'custom', position: { x: 100, y: 200 }, data: { kind: 'transform', label: 'New' } })
-await flow.layout('layered', { direction: 'RIGHT', nodeSpacing: 50, layerSpacing: 100 })  // auto-layout via lazy-loaded elkjs
-// LayoutOptions applicability: direction/layerSpacing/edgeRouting apply to layered/tree only;
+await flow.layout('layered', { direction: 'RIGHT', nodeSpacing: 50, layerSpacing: 100 })
+// LayoutOptions applicability: direction / layerSpacing / edgeRouting apply to layered/tree only;
 // force/stress/radial/box/rectpacking silently ignore them. nodeSpacing applies to all algorithms.
-const json = flow.toJSON(); flow.fromJSON(json)       // round-trip serialization
+const json = flow.toJSON(); flow.fromJSON(json)       // round-trip serialization`,
+    notes: 'Create a reactive flow instance. Generic over node data shape — `createFlow<MyData>(...)` returns `FlowInstance<MyData>` so `node.data.kind` narrows correctly without an `[key: string]: unknown` index signature on consumer types. Defaults to `Record<string, unknown>` when no generic is supplied. The returned instance owns signal-native nodes / edges and exposes CRUD, selection, viewport (zoom / pan / fitView), and auto-layout via lazy-loaded elkjs (first `.layout()` call fetches a ~1.4MB chunk). Pan / zoom uses pointer events + CSS transforms — no D3. See also: useFlow, FlowInstance, Flow.',
+    mistakes: `- Forgetting to declare \`@pyreon/runtime-dom\` in consumer app deps — flow's JSX emits \`_tpl()\` which needs runtime-dom imports
+- Reading \`NodeComponentProps.data\` / \`.selected\` / \`.dragging\` as plain values — all three are REACTIVE ACCESSORS: \`props.data()\`, \`props.selected()\`, \`props.dragging()\`
+- Calling \`props.data()\` OUTSIDE a reactive scope — captures the value once at component setup, defeating the per-node reactivity. Read it inside JSX expression thunks, \`effect\`, or \`computed\`
+- Adding \`[key: string]: unknown\` index signature to your node data interface — no longer needed now that \`createFlow\` is generic. Pass \`createFlow<MyData>(...)\` instead
+- Setting \`LayoutOptions.direction\` (or \`layerSpacing\`, or \`edgeRouting\`) on a force / stress / radial / box / rectpacking layout and expecting a directional result — these options are namespaced under ELK's layered / tree pipelines and silently ignored by the geometric algorithms. Dev-mode \`console.warn\` fires when this happens
+- Missing \`<Flow nodeTypes={{ key: Component }}>\` registration — \`node.type\` strings dispatch to that map, unregistered types fall through to the default renderer
+- Using \`createFlow\` inside a component body without \`onUnmount(() => flow.dispose())\` — prefer \`useFlow\` which auto-disposes
+- Using \`direction: 'row'\` on flow's containing Element layout — Pyreon \`Element\` accepts \`'inline'\` / \`'rows'\` / \`'reverseInline'\` / \`'reverseRows'\`, not CSS flex-direction values like \`'row'\` or \`'column'\``,
+  },
+
+  'flow/useFlow': {
+    signature: '<TData = Record<string, unknown>>(config: FlowConfig<TData>) => FlowInstance<TData>',
+    example: `// Component-scoped flow — auto-disposes when the component unmounts.
+// Identical shape to createFlow, plus an implicit onUnmount(() => flow.dispose()).
+const MyDiagram = () => {
+  const flow = useFlow<WorkflowData>({
+    nodes: [{ id: '1', position: { x: 0, y: 0 }, data: { kind: 'trigger', label: 'Start' } }],
+    edges: [],
+  })
+  return (
+    <Flow instance={flow}>
+      <Background />
+    </Flow>
+  )
+}`,
+    notes: `Component-scoped wrapper around \`createFlow\` — identical shape plus an implicit \`onUnmount(() => flow.dispose())\`. Prefer inside component bodies; use \`createFlow\` directly only for flows owned outside the component tree (app stores, singletons, SSR-shared state) where you'll dispose at the correct lifecycle point yourself. See also: createFlow.`,
+    mistakes: `- Using \`useFlow\` outside a component body — the \`onUnmount\` hook registration requires an active component setup context, same constraint as every \`useX\` hook
+- Using \`createFlow\` inside a component and forgetting \`onUnmount(() => flow.dispose())\` — that was the footgun \`useFlow\` exists to prevent
+- Storing the returned instance in a module-level variable — bypasses the auto-dispose guarantee; use \`createFlow\` for that pattern`,
+  },
+
+  'flow/Flow': {
+    signature: '(props: FlowComponentProps) => VNodeChild',
+    example: `<Flow instance={flow} nodeTypes={{ custom: MyNode }} edgeTypes={{ arrow: ArrowEdge }}>
+  <Background variant="dots" gap={20} />
+  <Controls position="bottom-left" />
+  <MiniMap nodeColor={(node) => '#6366f1'} />
+</Flow>
 
 // Custom node renderer — every prop except id is a REACTIVE ACCESSOR
-function CustomNode(props: NodeComponentProps<WorkflowData>) {
+function MyNode(props: NodeComponentProps<WorkflowData>) {
   return (
     <div
       class={() => (props.selected() ? 'selected' : '')}
@@ -783,23 +823,68 @@ function CustomNode(props: NodeComponentProps<WorkflowData>) {
       {() => props.data().label}
     </div>
   )
+}`,
+    notes: 'Main flow container. Accepts a `FlowInstance` via the `instance` prop plus optional `nodeTypes` / `edgeTypes` maps for custom renderers. Internally uses `<For>` keyed by `node.id` plus per-node reactive accessors that read live state from `instance.nodes()` — each node mounts EXACTLY ONCE across the lifetime of the graph regardless of drags, selection clicks, or `updateNode` mutations. A 60fps drag in a 1000-node graph stays O(1) per frame. JSX components are NOT generic at the call site (`<Flow<MyData> />` is invalid JSX); `FlowProps.instance` is typed as `FlowInstance<any>` so typed consumers can pass `FlowInstance<MyData>` without casting. See also: createFlow, Background, Controls, MiniMap, Handle.',
+    mistakes: `- \`<Flow<MyData> />\` is invalid JSX — the component is not generic at the call site; pass a typed \`FlowInstance<MyData>\` via \`instance\` prop
+- Missing \`nodeTypes\` entry for a \`node.type\` string — falls through to the default renderer
+- Mutating \`instance.nodes()\` return value directly — use \`instance.addNode\` / \`updateNode\` / \`removeNode\` so the internal signals fire`,
+  },
+
+  'flow/Background': {
+    signature: '(props: { variant?: "dots" | "lines"; gap?: number; color?: string }) => VNodeChild',
+    example: `<Flow instance={flow}>
+  <Background variant="dots" gap={24} color="#e5e7eb" />
+</Flow>`,
+    notes: 'Dot or line grid background inside a `<Flow>`. Place as a direct child. `variant` defaults to `"dots"`, `gap` controls pattern spacing, `color` sets the pattern color. Renders as an SVG pattern at the back of the z-order. See also: Flow, Controls, MiniMap.',
+  },
+
+  'flow/Controls': {
+    signature: '(props?: { position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" }) => VNodeChild',
+    example: `<Flow instance={flow}>
+  <Controls position="bottom-left" />
+</Flow>`,
+    notes: 'Zoom in / zoom out / fit-view button cluster. Renders absolutely inside the flow viewport at the configured corner (default `"bottom-right"`). Each button dispatches to the corresponding `FlowInstance` viewport method. See also: Flow, Background, MiniMap.',
+  },
+
+  'flow/MiniMap': {
+    signature: '(props?: { nodeColor?: (node: FlowNode) => string; maskColor?: string }) => VNodeChild',
+    example: `<Flow instance={flow}>
+  <MiniMap nodeColor={(node) => node.data.highlighted ? '#f59e0b' : '#6366f1'} />
+</Flow>`,
+    notes: 'Overview minimap of the full graph. `nodeColor` is a per-node color function (default grey), `maskColor` fills the area outside the current viewport (default semi-transparent black). Clicks on the minimap recenter the main viewport. See also: Flow, Background, Controls.',
+  },
+
+  'flow/Handle': {
+    signature: '(props: { type: "source" | "target"; position: Position; id?: string }) => VNodeChild',
+    example: `function CustomNode(props: NodeComponentProps<MyData>) {
+  return (
+    <div>
+      <Handle type="target" position={Position.Left} />
+      {() => props.data().label}
+      <Handle type="source" position={Position.Right} id="out-primary" />
+      <Handle type="source" position={Position.Bottom} id="out-fallback" />
+    </div>
+  )
 }
 
-<Flow instance={flow} nodeTypes={{ custom: CustomNode }}>
-  <Background variant="dots" />
-  <Controls />
-  <MiniMap />
+// Edge referencing a specific source handle by id
+flow.addEdge({ source: '1', sourceHandle: 'out-primary', target: '2' })`,
+    notes: 'Connection handle on a custom node — exposes a connectable point that edges attach to. `type` picks direction (`"source"` emits edges, `"target"` receives), `position` is a `Position` enum (`Top` / `Right` / `Bottom` / `Left`). Provide a distinct `id` when a node has multiple source or target handles so edges can reference the specific one via `edge.sourceHandle` / `edge.targetHandle`. See also: Flow, Position.',
+    mistakes: `- Multiple \`source\` / \`target\` handles on one node without distinct \`id\` values — edges cannot disambiguate which handle they connect to
+- Nesting a \`<Handle>\` inside a non-node component (a \`<Background>\` child, a \`<Panel>\`, etc.) — the connection machinery expects handles to live inside a node renderer`,
+  },
+
+  'flow/Panel': {
+    signature: '(props: { position?: "top-left" | "top-right" | "bottom-left" | "bottom-right"; children: VNodeChild }) => VNodeChild',
+    example: `<Flow instance={flow}>
+  <Panel position="top-right">
+    <button onClick={() => flow.fitView()}>Fit</button>
+    <button onClick={() => flow.toJSON()}>Export</button>
+  </Panel>
 </Flow>`,
-    notes:
-      "Signal-native nodes/edges. Generic over node data shape: createFlow<TData> returns FlowInstance<TData> so node.data.kind narrows correctly. Defaults to Record<string, unknown> if no generic supplied. NodeComponentProps has THREE reactive accessors — data: () => TData, selected: () => boolean, dragging: () => boolean — read inside reactive scopes so the node patches in place when ANY underlying state changes. Each node mounts EXACTLY ONCE across the lifetime of the graph regardless of how many drags, selection clicks, or updateNode mutations happen. Internally <Flow> uses <For> keyed by node.id plus per-node accessors that read live state from instance.nodes() — so a 60fps drag in a 1000-node graph is O(1) instead of O(N) per frame. Auto-layout via elkjs (lazy-loaded, ~1.4MB chunk only on first .layout() call). Pan/zoom via pointer events + CSS transforms. No D3. JSX components are NOT generic at the call site (<Flow<MyData> /> is invalid JSX) — FlowProps.instance is typed as FlowInstance<any> so typed consumers can pass FlowInstance<MyData> without casting.",
-    mistakes: `- Forgetting to declare @pyreon/runtime-dom in consumer app deps — flow's JSX emits _tpl() which needs runtime-dom imports
-- Reading props.data, props.selected, or props.dragging as plain values — they're ALL accessors, call them: props.data().kind, props.selected(), props.dragging()
-- Calling props.data() OUTSIDE a reactive scope — captures the value once at component setup, defeating reactivity. Read it inside JSX expression thunks, effect, or computed: {() => props.data().label}
-- Adding [key: string]: unknown index signature to your node data interface — no longer needed now that createFlow is generic. Just pass createFlow<MyData>(...)
-- Using direction: 'row' on flow's containing layout — Pyreon Element accepts 'inline'|'rows'|'reverseInline'|'reverseRows', not 'row'
-- Setting LayoutOptions.direction (or layerSpacing, or edgeRouting) on a force/stress/radial/box/rectpacking layout and expecting a directional result — these options are namespaced under ELK's layered/tree pipelines and silently ignored by the geometric algorithms. Switch the algorithm to 'layered' or 'tree' if you need a directional layout.
-- Missing the <Flow nodeTypes={{ key: Component }}> registration — node.type strings dispatch to that map`,
+    notes: 'Overlay panel positioned absolutely relative to the flow viewport. Use for toolbars, legend badges, or contextual action buttons. Pass any JSX as children — the panel is a plain positioned container, not a predefined chrome component. See also: Flow, Controls.',
   },
+  // <gen-docs:api-reference:end @pyreon/flow>
 
   // ═══════════════════════════════════════════════════════════════════════════
   // @pyreon/code
@@ -958,34 +1043,45 @@ Posts.useTable()   // TanStack Table config`,
 
 const result = lint({ paths: ["src/"], preset: "recommended" })
 console.log(result.totalErrors, result.totalWarnings)
+// Config-level diagnostics (malformed rule options, etc.)
+for (const d of result.configDiagnostics) console.log(d.ruleId, d.message)
 
-// With config file auto-loading + rule overrides
-lint({ paths: ["."], ruleOverrides: { "pyreon/no-classname": "off" } })`,
+// Severity overrides + per-rule options overrides
+lint({
+  paths: ["."],
+  ruleOverrides: { "pyreon/no-classname": "off" },
+  ruleOptionsOverrides: {
+    "pyreon/no-window-in-ssr": { exemptPaths: ["src/foundation/"] },
+  },
+})`,
     notes:
-      'Programmatic API. 58 rules across 12 categories. Auto-loads .pyreonlintrc.json. Presets: recommended, strict, app, lib. Uses oxc-parser with AST caching.',
+      'Programmatic API. 59 rules across 12 categories. Auto-loads .pyreonlintrc.json. Presets: recommended, strict, app, lib. Per-rule options via tuple form in config (`["error", { exemptPaths: [...] }]`) or `ruleOptionsOverrides`. Wrong-typed options surface on `result.configDiagnostics`. Uses oxc-parser with AST caching.',
   },
 
   'lint/lintFile': {
     signature:
-      'lintFile(filePath: string, sourceText: string, rules: Rule[], config: LintConfig, cache?: AstCache): LintFileResult',
+      'lintFile(filePath: string, sourceText: string, rules: Rule[], config: LintConfig, cache?: AstCache, configDiagnosticsSink?: ConfigDiagnostic[]): LintFileResult',
     example: `import { lintFile, allRules, getPreset, AstCache } from "@pyreon/lint"
 
 const cache = new AstCache()
 const config = getPreset("recommended")
-const result = lintFile("app.tsx", source, allRules, config, cache)`,
-    notes: 'Low-level single-file API. Optional AstCache for repeat runs (FNV-1a hash keyed).',
+const configSink: ConfigDiagnostic[] = []
+const result = lintFile("app.tsx", source, allRules, config, cache, configSink)`,
+    notes:
+      'Low-level single-file API. Optional AstCache for repeat runs (FNV-1a hash keyed). Optional `configDiagnosticsSink` collects malformed-option diagnostics; without it they print to stderr.',
   },
 
   'lint/cli': {
     signature:
-      'pyreon-lint [--preset name] [--fix] [--format text|json|compact] [--quiet] [--watch] [--list] [--config path] [--ignore path] [--rule id=severity] [path...]',
+      'pyreon-lint [--preset name] [--fix] [--format text|json|compact] [--quiet] [--watch] [--list] [--config path] [--ignore path] [--rule id=severity] [--rule-options id=\'{json}\'] [path...]',
     example: `pyreon-lint --preset strict --quiet    # CI mode
 pyreon-lint --fix                       # auto-fix
 pyreon-lint --watch src/                # watch mode
-pyreon-lint --list                      # list all 58 rules
-pyreon-lint --format json               # machine-readable`,
+pyreon-lint --list                      # list all 59 rules
+pyreon-lint --format json               # machine-readable
+pyreon-lint --rule-options 'pyreon/no-window-in-ssr={"exemptPaths":["src/foundation/"]}' src/`,
     notes:
-      "CLI entry. Config: .pyreonlintrc.json, package.json 'pyreonlint' field. Ignore: .pyreonlintignore + .gitignore. Watch: fs.watch recursive with 100ms debounce.",
+      "CLI entry. Config: .pyreonlintrc.json (reference schema/pyreonlintrc.schema.json for IDE autocomplete), package.json 'pyreonlint' field. Ignore: .pyreonlintignore + .gitignore. Watch: fs.watch recursive with 100ms debounce. `--rule-options id='{json}'` passes per-rule options on a single run.",
   },
 
   'lint/no-process-dev-gate': {
@@ -1006,6 +1102,39 @@ if (__DEV__) console.warn('hello')`,
 - Using the rule for server-only packages — they're correctly exempt because Node always has \`process\``,
   },
 
+  'lint/require-browser-smoke-test': {
+    signature: 'rule: pyreon/require-browser-smoke-test (architecture, error in recommended/strict/lib, off in app)',
+    example: `// Per-package config (optional — defaults cover all known browser packages)
+{
+  "rules": {
+    "pyreon/require-browser-smoke-test": [
+      "error",
+      {
+        "additionalPackages": ["@my-org/my-browser-pkg"],
+        "exemptPaths": ["packages/experimental/"]
+      }
+    ]
+  }
+}`,
+    notes:
+      "Locks in the durability of the T1.1 browser smoke harness (PRs #224, #227, #229, #231). Every browser-categorized package MUST ship at least one \`*.browser.test.{ts,tsx}\` file under \`src/\`. Without this rule, new browser packages can quietly ship without smoke coverage and we drift back to the world before T1.1 — happy-dom silently masks environment-divergence bugs (PR #197 mock-vnode metadata drop, PR #200 \`typeof process\` dead code, multi-word event delegation bug). Default browser-package list mirrors \`.claude/rules/test-environment-parity.md\`. The rule fires once per package on its \`src/index.ts\`, walks the package directory looking for \`*.browser.test.*\`, and reports if none are found. Off in \`app\` preset because apps don't ship as packages with smoke obligations.",
+    mistakes: `- Adding a new browser-running package without a browser test — the rule will fail your PR
+- Hardcoding the browser-package list in the rule — the list lives in \`.claude/rules/browser-packages.json\` (single source of truth), not in the rule source
+- Disabling the rule globally — use \`exemptPaths\` to exempt specific packages still under construction
+- Shipping a \`sanity.browser.test.ts\` with \`expect(1).toBe(1)\` just to satisfy the rule — it passes but provides zero signal. The rule is a GATE, not a quality check; review actual contents on PR`,
+  },
+
+  'mcp/get_browser_smoke_status': {
+    signature: 'tool: get_browser_smoke_status — no args',
+    example: `// Ask the MCP server:
+//   "which Pyreon packages are missing browser smoke coverage?"
+// Tool walks packages/, matches against .claude/rules/browser-packages.json,
+// returns a coverage report.`,
+    notes:
+      "Companion to the `pyreon/require-browser-smoke-test` lint rule. Reports which browser-categorized Pyreon packages have at least one `*.browser.test.{ts,tsx}` file under `src/`. Uses the same `.claude/rules/browser-packages.json` single source of truth as the rule + the CI script. Lets an AI agent check coverage before writing a new browser package (so it adds a smoke test in the same PR) instead of discovering the failure when CI runs. Falls back with a clear message if the JSON isn't present (e.g. consumer apps that don't ship the Pyreon monorepo layout).",
+    mistakes: `- Using the tool's output as a substitute for running the CI script — this tool only checks file existence, not the self-expiring-exemption check that \`bun run lint:browser-smoke\` performs`,
+  },
+
   // ═══════════════════════════════════════════════════════════════════════════
   // @pyreon/ui-core
   // ═══════════════════════════════════════════════════════════════════════════

package/src/index.ts

@@ -6,12 +6,13 @@
  * to generate, validate, and migrate Pyreon code.
  *
  * Tools:
- *   get_api        — Look up any Pyreon API: signature, usage, common mistakes
- *   validate       — Check a code snippet for Pyreon anti-patterns
- *   migrate_react  — Convert React code to idiomatic Pyreon
- *   diagnose       — Parse an error message into structured fix information
- *   get_routes     — List all routes in the current project
- *   get_components — List all components with their props and signals
+ *   get_api                   — Look up any Pyreon API: signature, usage, common mistakes
+ *   validate                  — Check a code snippet for Pyreon anti-patterns
+ *   migrate_react             — Convert React code to idiomatic Pyreon
+ *   diagnose                  — Parse an error message into structured fix information
+ *   get_routes                — List all routes in the current project
+ *   get_components            — List all components with their props and signals
+ *   get_browser_smoke_status  — Report which browser-categorized packages have smoke coverage
  *
  * Usage:
  *   bunx @pyreon/mcp          # stdio transport (for IDE integration)
@@ -230,6 +231,168 @@ server.tool('get_components', {}, async () => {
   return textResult(`**Components (${ctx.components.length}):**\n\n${compList}`)
 })
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool: get_browser_smoke_status
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+  'get_browser_smoke_status',
+  {},
+  async () => {
+    // Walks the current project, reports which browser-categorized
+    // packages have at least one `*.browser.test.{ts,tsx}` file.
+    // Mirrors `pyreon/require-browser-smoke-test` / the CI script so an
+    // AI agent can check coverage before editing without running lint.
+    const fs = await import('node:fs')
+    const path = await import('node:path')
+
+    const cwd = process.cwd()
+
+    // Discover the browser-packages list by walking up from cwd.
+    let browserPackages: string[] = []
+    {
+      let dir = cwd
+      for (let i = 0; i < 30; i++) {
+        const candidate = path.join(dir, '.claude', 'rules', 'browser-packages.json')
+        if (fs.existsSync(candidate)) {
+          try {
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8')) as {
+              packages?: unknown
+            }
+            if (Array.isArray(parsed.packages)) {
+              browserPackages = parsed.packages.filter((p): p is string => typeof p === 'string')
+            }
+          } catch {
+            // fall through to empty list
+          }
+          break
+        }
+        const parent = path.dirname(dir)
+        if (parent === dir) break
+        dir = parent
+      }
+    }
+
+    if (browserPackages.length === 0) {
+      return textResult(
+        'No `.claude/rules/browser-packages.json` found in the current project. ' +
+          'This tool reports browser-smoke coverage for Pyreon monorepos that ship ' +
+          'the single-source-of-truth list. Consumer apps can still opt in via the ' +
+          "lint rule's `additionalPackages` option.",
+      )
+    }
+
+    function hasBrowserTest(dir: string): boolean {
+      let entries: string[]
+      try {
+        entries = fs.readdirSync(dir)
+      } catch {
+        return false
+      }
+      for (const name of entries) {
+        if (
+          name.startsWith('.') ||
+          name === 'node_modules' ||
+          name === 'lib' ||
+          name === 'dist'
+        ) {
+          continue
+        }
+        const full = path.join(dir, name)
+        let isDir = false
+        try {
+          isDir = fs.statSync(full).isDirectory()
+        } catch {
+          continue
+        }
+        if (isDir) {
+          if (hasBrowserTest(full)) return true
+          continue
+        }
+        if (/\.browser\.test\.(?:ts|tsx)$/.test(name)) return true
+      }
+      return false
+    }
+
+    // Find each browser-categorized package's directory by matching
+    // package.json `name` under packages/*.
+    const pkgDirs = new Map<string, string>() // name -> dir
+    function walkPkgs(dir: string, depth = 0): void {
+      if (depth > 4) return
+      let entries: string[]
+      try {
+        entries = fs.readdirSync(dir)
+      } catch {
+        return
+      }
+      for (const name of entries) {
+        if (name.startsWith('.') || name === 'node_modules') continue
+        const full = path.join(dir, name)
+        let isDir = false
+        try {
+          isDir = fs.statSync(full).isDirectory()
+        } catch {
+          continue
+        }
+        if (!isDir) continue
+        const pkgJsonPath = path.join(full, 'package.json')
+        if (fs.existsSync(pkgJsonPath)) {
+          try {
+            const parsed = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8')) as {
+              name?: unknown
+            }
+            if (typeof parsed.name === 'string') {
+              pkgDirs.set(parsed.name, full)
+            }
+          } catch {
+            // ignore malformed package.json
+          }
+        } else {
+          walkPkgs(full, depth + 1)
+        }
+      }
+    }
+    // Project root = cwd or the ancestor with browser-packages.json.
+    walkPkgs(path.join(cwd, 'packages'))
+
+    const covered: string[] = []
+    const missing: string[] = []
+    const unknown: string[] = []
+    for (const name of browserPackages) {
+      const dir = pkgDirs.get(name)
+      if (!dir) {
+        unknown.push(name)
+        continue
+      }
+      if (hasBrowserTest(dir)) covered.push(name)
+      else missing.push(name)
+    }
+
+    const parts: string[] = []
+    parts.push(`**Browser smoke coverage** (${covered.length} / ${browserPackages.length}):`)
+    parts.push('')
+    if (covered.length > 0) {
+      parts.push(`✓ Covered (${covered.length}):`)
+      for (const n of covered) parts.push(`  - ${n}`)
+      parts.push('')
+    }
+    if (missing.length > 0) {
+      parts.push(`✗ Missing \`*.browser.test.*\` (${missing.length}):`)
+      for (const n of missing) parts.push(`  - ${n}`)
+      parts.push('')
+      parts.push(
+        'Add a `*.browser.test.{ts,tsx}` file under `src/` in each missing package. ' +
+          'See `.claude/rules/test-environment-parity.md` for the setup recipe.',
+      )
+    }
+    if (unknown.length > 0) {
+      parts.push(`? Listed in browser-packages.json but not found in this repo (${unknown.length}):`)
+      for (const n of unknown) parts.push(`  - ${n}`)
+    }
+    return textResult(parts.join('\n'))
+  },
+)
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // Start server
 // ═══════════════════════════════════════════════════════════════════════════════

package/src/tests/api-reference.test.ts

@@ -1,4 +1,27 @@
-import { API_REFERENCE } from '../api-reference'
+import type { McpApiReferenceEntry } from '@pyreon/manifest'
+import { type ApiEntry, API_REFERENCE } from '../api-reference'
+
+// Compile-time assertion that `McpApiReferenceEntry` (declared in
+// `@pyreon/manifest`) stays structurally identical to the local
+// `ApiEntry` that `API_REFERENCE` is typed against. A drift in
+// either direction — e.g. MCP adds `deprecated?: string`, or the
+// manifest renderer starts emitting a new field — fails typecheck
+// here BEFORE the generated `api-reference.ts` is produced.
+//
+// Why symmetric assertions: a one-sided `extends` only catches drift
+// in one direction. `Equal<A, B>` is precise — fails if either side
+// adds a field the other lacks.
+type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false
+type Assert<T extends true> = T
+// If the types drift (MCP or manifest adds / removes / renames a
+// field), `Equal<...>` resolves to `false`, `Assert<false>` fails
+// the constraint `T extends true`, and `tsc --noEmit` errors on
+// this line. The `void` usage keeps the alias load-bearing at
+// runtime so tree-shaking / unused-symbol lints don't strip it.
+type _McpShapeInSync = Assert<Equal<McpApiReferenceEntry, ApiEntry>>
+const _assertion: _McpShapeInSync = true
+void _assertion
 
 describe('api-reference', () => {
   it('has entries', () => {
@@ -11,4 +34,71 @@ describe('api-reference', () => {
       expect(entry.example, `${key} missing example`).toBeTruthy()
     }
   })
+
+  // Coverage for the T2.5.1 flip: @pyreon/flow's region now
+  // regenerates from its manifest. These tests guard the observable
+  // surface that MCP consumers see via the `get_api` tool — if a
+  // future manifest refactor drops a key or accidentally renames
+  // one, the failure surfaces HERE in addition to the
+  // gen-docs --check drift check.
+  describe('@pyreon/flow — manifest-driven region', () => {
+    const EXPECTED_FLOW_KEYS = [
+      'flow/createFlow',
+      'flow/useFlow',
+      'flow/Flow',
+      'flow/Background',
+      'flow/Controls',
+      'flow/MiniMap',
+      'flow/Handle',
+      'flow/Panel',
+    ]
+
+    it.each(EXPECTED_FLOW_KEYS)('exposes %s with the full MCP shape', (key) => {
+      const entry = API_REFERENCE[key]
+      expect(entry, `${key} missing from API_REFERENCE`).toBeDefined()
+      // Signature + example are required by the manifest renderer
+      // (guaranteed non-empty by the manifest type). Notes come
+      // from `summary` (always present in the manifest); mistakes
+      // are optional per-entry.
+      expect(entry!.signature).toBeTruthy()
+      expect(entry!.example).toBeTruthy()
+      expect(entry!.notes).toBeTruthy()
+    })
+
+    it('createFlow carries the enriched foot-gun catalog including the `direction: row` mistake', () => {
+      // Regression guard for a hand-written mistake the first pass
+      // of T2.5.1 accidentally dropped. Ensures future manifest
+      // edits don't silently lose it again.
+      const createFlow = API_REFERENCE['flow/createFlow']
+      expect(createFlow?.mistakes).toContain("Using `direction: 'row'`")
+    })
+
+    it('createFlow notes carry the load-bearing architectural claims', () => {
+      // Spot-checks that MCP consumers see the signal-native /
+      // elkjs / no-D3 framing — the stuff that makes flow's API
+      // understandable without opening source. A regression here
+      // means the manifest summary lost density.
+      const createFlow = API_REFERENCE['flow/createFlow']
+      expect(createFlow?.notes).toContain('elkjs')
+      expect(createFlow?.notes).toContain('no D3')
+      expect(createFlow?.notes).toContain('signal-native')
+    })
+
+    it('Flow (container component) documents the mount-once invariant', () => {
+      // Flow is new in the T2.5.1 flip — previously the hand-
+      // written surface only covered `createFlow` + `useFlow`.
+      // Assert the component + its load-bearing contract are both
+      // reachable via MCP.
+      const flow = API_REFERENCE['flow/Flow']
+      expect(flow?.notes).toContain('mounts EXACTLY ONCE')
+    })
+
+    it('Handle (connection component) documents the distinct-id rule for multiple handles', () => {
+      // Another T2.5.1-new entry. The multiple-handle id contract
+      // is subtle; surface it for MCP consumers.
+      const handle = API_REFERENCE['flow/Handle']
+      expect(handle?.notes).toContain('multiple source or target handles')
+      expect(handle?.mistakes).toContain('distinct `id`')
+    })
+  })
 })