@pyreon/mcp 0.12.10 → 0.12.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/mcp",
-  "version": "0.12.10",
+  "version": "0.12.12",
   "description": "MCP server for Pyreon — AI-powered framework assistance",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/mcp#readme",
   "bugs": {
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@pyreon/compiler": "^0.12.10",
+    "@pyreon/compiler": "^0.12.12",
     "zod": "^4.3.6"
   },
   "peerDependencies": {

package/src/api-reference.ts

@@ -698,7 +698,10 @@ theme.remove()    // delete from storage`,
   'i18n/createI18n': {
     signature:
       'createI18n(options: { locale: string, messages: Record<string, Record<string, string>>, loader?, fallbackLocale?, pluralRules? }): I18nInstance',
-    example: `const i18n = createI18n({
+    example: `// Full entry — includes JSX components (Trans, I18nProvider, useI18n)
+import { createI18n, useI18n } from '@pyreon/i18n'
+
+const i18n = createI18n({
   locale: 'en',
   messages: { en: { greeting: 'Hello, {{name}}!' } },
   loader: (locale, ns) => import(\`./locales/\${locale}/\${ns}.json\`),
@@ -706,9 +709,19 @@ theme.remove()    // delete from storage`,
 
 const { t, locale } = useI18n()
 t('greeting', { name: 'World' }) // "Hello, World!"
-locale.set('fr')                  // switch reactively`,
+locale.set('fr')                  // switch reactively
+
+// Backend / non-JSX entry — @pyreon/i18n/core
+// Zero JSX dependencies, transitively only @pyreon/reactivity.
+// Use this on backends, edge workers, non-Pyreon frontends.
+import { createI18n } from '@pyreon/i18n/core'
+const backendI18n = createI18n({ locale: 'en', messages: { en: { hello: 'Hi' } } })
+backendI18n.t('hello')`,
     notes:
-      'Interpolation with {{name}}, pluralization with _one/_other suffixes. Namespace lazy loading. <Trans> component for rich JSX interpolation.',
+      'Interpolation with {{name}}, pluralization with _one/_other suffixes. Namespace lazy loading. <Trans> component for rich JSX interpolation. TWO ENTRY POINTS: `@pyreon/i18n` (full, with JSX components) vs `@pyreon/i18n/core` (framework-agnostic, zero JSX deps — use for backends and non-Pyreon consumers). Both return identical I18nInstance objects.',
+    mistakes: `- Using \`@pyreon/i18n\` (the main entry) on a backend without a JSX-aware tsconfig — the bun condition resolves to source which transitively includes the Trans JSX component. Use \`@pyreon/i18n/core\` instead.
+- Reading the README example and importing from \`@pyreon/i18n\` in a non-Pyreon project — that path works for Pyreon UIs but the README now documents \`/core\` as the backend recommendation.
+- Trying to use \`<Trans>\` from \`@pyreon/i18n/core\` — it's intentionally not exported there. Import it from the main \`@pyreon/i18n\` entry instead.`,
   },
 
   // ═══════════════════════════════════════════════════════════════════════════
@@ -735,21 +748,57 @@ await doc.toNotion()   // Notion blocks`,
   // ═══════════════════════════════════════════════════════════════════════════
 
   'flow/createFlow': {
-    signature: 'createFlow(config: { nodes: FlowNode[], edges: FlowEdge[], ... }): FlowInstance',
-    example: `const flow = createFlow({
+    signature:
+      'createFlow<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'
+  label: string
+}
+
+const flow = createFlow<WorkflowData>({
   nodes: [
-    { id: '1', position: { x: 0, y: 0 }, data: { label: 'Start' } },
-    { id: '2', position: { x: 200, y: 100 }, data: { label: 'End' } },
+    { id: '1', type: 'custom', position: { x: 0, y: 0 }, data: { kind: 'trigger', label: 'Start' } },
+    { id: '2', type: 'custom', position: { x: 200, y: 100 }, data: { kind: 'notify', label: 'End' } },
   ],
-  edges: [{ id: 'e1', source: '1', target: '2' }],
+  edges: [{ id: 'e1', source: '1', target: '2', animated: true }],
 })
 
-flow.addNode({ id: '3', position: { x: 100, y: 200 }, data: { label: 'New' } })
-await flow.layout('layered')  // auto-layout via elkjs
+// node.data.kind narrows to the typed union, not unknown
+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;
+// force/stress/radial/box/rectpacking silently ignore them. nodeSpacing applies to all algorithms.
+const json = flow.toJSON(); flow.fromJSON(json)       // round-trip serialization
 
-<Flow instance={flow}><Background /><Controls /><MiniMap /></Flow>`,
+// Custom node renderer — every prop except id is a REACTIVE ACCESSOR
+function CustomNode(props: NodeComponentProps<WorkflowData>) {
+  return (
+    <div
+      class={() => (props.selected() ? 'selected' : '')}
+      style={() => \`cursor: \${props.dragging() ? 'grabbing' : 'grab'}\`}
+    >
+      {() => props.data().label}
+    </div>
+  )
+}
+
+<Flow instance={flow} nodeTypes={{ custom: CustomNode }}>
+  <Background variant="dots" />
+  <Controls />
+  <MiniMap />
+</Flow>`,
     notes:
-      'Signal-native nodes/edges. Auto-layout via elkjs (lazy-loaded). Pan/zoom via pointer events + CSS transforms. No D3.',
+      "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`,
   },
 
   // ═══════════════════════════════════════════════════════════════════════════
@@ -758,22 +807,66 @@ await flow.layout('layered')  // auto-layout via elkjs
 
   'code/createEditor': {
     signature:
-      'createEditor(config: { value?: string, language?: string, theme?: string, minimap?: boolean, ... }): EditorInstance',
+      'createEditor(config: { value?: string, language?: EditorLanguage, theme?: EditorTheme, onChange?: (val: string) => void, minimap?: boolean, lineNumbers?: boolean, ... }): EditorInstance',
     example: `const editor = createEditor({
   value: '// hello',
   language: 'typescript',
   theme: 'dark',
   minimap: true,
+  onChange: (next) => console.log('user edit:', next),
 })
 
-editor.value()       // reactive Signal<string>
+editor.value()              // reactive Signal<string>, read inside JSX/effects
+editor.value.set('new')     // write back into CodeMirror
+editor.cursor()             // computed { line, col }
+editor.lineCount()          // computed
 editor.goToLine(42)
 editor.insert('new code')
+editor.setDiagnostics([{ from: 0, to: 5, severity: 'error', message: '...' }])
 
-<CodeEditor instance={editor} />
-<DiffEditor original="old" modified="new" />`,
+<CodeEditor instance={editor} style="height: 400px" />
+<DiffEditor original="old" modified="new" language="typescript" />`,
     notes:
-      "Built on CodeMirror 6 (~250KB vs Monaco's ~2.5MB). loadLanguage() for lazy grammars. TabbedEditor for multi-file.",
+      "Built on CodeMirror 6 (~250KB vs Monaco's ~2.5MB). 19 languages via lazy-loaded grammars (declared as optionalDependencies). Two-way binding: editor.value is a writable Signal — pass onChange for editor → external, set editor.value for external → editor. For external↔editor binding with built-in loop prevention, use the higher-level `bindEditorToSignal({ editor, signal, serialize, parse })` helper instead of hand-rolling the flag pattern. <CodeEditor> auto-mounts and cleans up on unmount.",
+    mistakes: `- Forgetting to declare @pyreon/runtime-dom in consumer app deps — <CodeEditor> JSX emits _tpl() which needs runtime-dom imports
+- Hand-rolling the applyingFromExternal/applyingFromEditor flag pattern for two-way binding — use the bindEditorToSignal helper instead, it handles the loop prevention correctly and is tested
+- Calling editor methods before mount — they no-op safely but changes don't persist
+- Setting both vim: true and emacs: true — emacs wins`,
+  },
+
+  'code/bindEditorToSignal': {
+    signature:
+      'bindEditorToSignal<T>(options: { editor: EditorInstance, signal: SignalLike<T>, serialize: (val: T) => string, parse: (text: string) => T | null, onParseError?: (err: Error) => void }): { dispose: () => void }',
+    example: `import { bindEditorToSignal, createEditor } from '@pyreon/code'
+import { signal } from '@pyreon/reactivity'
+
+interface Doc { name: string; count: number }
+const data = signal<Doc>({ name: 'Alice', count: 1 })
+
+const editor = createEditor({
+  value: JSON.stringify(data(), null, 2),
+  language: 'json',
+})
+
+const binding = bindEditorToSignal({
+  editor,
+  signal: data,                              // accepts Signal<T> or any SignalLike<T>
+  serialize: (val) => JSON.stringify(val, null, 2),
+  parse: (text) => {
+    try { return JSON.parse(text) } catch { return null }
+  },
+  onParseError: (err) => console.warn(err.message),
+})
+
+// Later, on unmount:
+binding.dispose()`,
+    notes:
+      "Replaces the recurring loop-prevention flag-pair boilerplate (applyingFromExternal / applyingFromEditor) that consumers had to hand-roll for two-way external↔editor binding. The helper manages both directions, breaks the format-on-input race via internal flags, catches parse errors, and returns a disposable. Accepts any SignalLike<T> (Pyreon Signal, custom store wrapper, etc.). The editor itself ALSO has internal CM↔signal loop guards — this helper adds the SECOND layer for the external↔editor boundary.",
+    mistakes: `- Forgetting to call binding.dispose() on unmount — leaks both effects until the editor instance is GC'd
+- Non-deterministic serialize() — if serialize(parse(text)) returns a string structurally different from the input text, the helper dispatches redundant editor writes that fight the user's typing. JSON.stringify with consistent indentation is fine; pretty-printing that varies on every call is not
+- Throwing in parse() without an onParseError handler — the helper catches and silently no-ops if no handler is provided. Pass onParseError to surface parse errors in your UI
+- Returning a non-null value from parse() for malformed input — the helper writes whatever you return, including partial / corrupted state. Return null on parse failure, or throw with an error message
+- Using bindEditorToSignal AND a manual editor.value.set() loop in the same component — defeats the loop prevention. Pick one binding strategy per editor instance`,
   },
 
   // ═══════════════════════════════════════════════════════════════════════════
@@ -869,7 +962,7 @@ console.log(result.totalErrors, result.totalWarnings)
 // With config file auto-loading + rule overrides
 lint({ paths: ["."], ruleOverrides: { "pyreon/no-classname": "off" } })`,
     notes:
-      'Programmatic API. 55 rules across 12 categories. Auto-loads .pyreonlintrc.json. Presets: recommended, strict, app, lib. Uses oxc-parser with AST caching.',
+      'Programmatic API. 58 rules across 12 categories. Auto-loads .pyreonlintrc.json. Presets: recommended, strict, app, lib. Uses oxc-parser with AST caching.',
   },
 
   'lint/lintFile': {
@@ -889,12 +982,30 @@ const result = lintFile("app.tsx", source, allRules, config, cache)`,
     example: `pyreon-lint --preset strict --quiet    # CI mode
 pyreon-lint --fix                       # auto-fix
 pyreon-lint --watch src/                # watch mode
-pyreon-lint --list                      # list all 55 rules
+pyreon-lint --list                      # list all 58 rules
 pyreon-lint --format json               # machine-readable`,
     notes:
       "CLI entry. Config: .pyreonlintrc.json, package.json 'pyreonlint' field. Ignore: .pyreonlintignore + .gitignore. Watch: fs.watch recursive with 100ms debounce.",
   },
 
+  'lint/no-process-dev-gate': {
+    signature: 'rule: pyreon/no-process-dev-gate (architecture, error, auto-fixable)',
+    example: `// ❌ Wrong — dead code in real Vite browser bundles
+const __DEV__ = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'
+if (__DEV__) console.warn('hello')
+
+// ✅ Correct — Vite literal-replaces import.meta.env.DEV at build time
+// @ts-ignore — provided by Vite/Rolldown at build time
+const __DEV__ = import.meta.env?.DEV === true
+if (__DEV__) console.warn('hello')`,
+    notes:
+      "The `typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'` pattern works in vitest (Node, `process` is defined) but is silently dead code in real Vite browser bundles because Vite does NOT polyfill `process` for the client. Every `console.warn` gated on the broken constant never fires for real users in dev mode — unit tests pass while users get nothing. Use `import.meta.env.DEV` instead — Vite/Rolldown literal-replace it at build time, prod tree-shakes the warning to zero bytes, and vitest sets it to `true` automatically. Server-only packages (`zero`, `core/server`, `core/runtime-server`, `vite-plugin`, `cli`, `lint`, `mcp`, `storybook`, `typescript`) and test files are exempt. Reference implementation: `packages/fundamentals/flow/src/layout.ts:warnIgnoredOptions`. The rule has an auto-fix that replaces the broken expression with `import.meta.env?.DEV === true`.",
+    mistakes: `- Copying the \`typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'\` pattern from existing codebases — it works in Node but is dead in browser bundles
+- Trying to test with \`delete globalThis.process\` — vitest's own \`import.meta.env\` depends on \`process\`, so deleting it breaks the FIXED gate too (not because the gate is wrong, but because vitest can't resolve it)
+- Adding \`process: { env: { ... } }\` polyfills to vite.config.ts as a workaround — fix the source instead
+- Using the rule for server-only packages — they're correctly exempt because Node always has \`process\``,
+  },
+
   // ═══════════════════════════════════════════════════════════════════════════
   // @pyreon/ui-core
   // ═══════════════════════════════════════════════════════════════════════════
@@ -1145,4 +1256,65 @@ export const Primary: StoryObj<typeof meta> = {
     notes:
       'Storybook renderer for Pyreon components. Re-exports h, Fragment, signal, computed, effect, mount for story convenience.',
   },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/document-primitives
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  'document-primitives/extractDocNode': {
+    signature: 'extractDocNode(templateFn: () => VNode, options?: ExtractOptions): DocNode',
+    example: `import {
+  DocDocument, DocPage, DocHeading, DocText,
+  extractDocNode,
+} from '@pyreon/document-primitives'
+import { download } from '@pyreon/document'
+
+interface Resume { name: string; headline: string }
+
+function ResumeTemplate(props: { resume: () => Resume }) {
+  return (
+    // title and author accept reactive accessors — extractDocNode
+    // resolves them at extraction time, so each export click reads
+    // the LIVE value from the underlying signal
+    <DocDocument
+      title={() => \`\${props.resume().name} — Resume\`}
+      author={() => props.resume().name}
+    >
+      <DocPage>
+        <DocHeading level="h1">{() => props.resume().name}</DocHeading>
+        <DocText>{() => props.resume().headline}</DocText>
+      </DocPage>
+    </DocDocument>
+  )
+}
+
+// One-step extraction. The two-step createDocumentExport(...).getDocNode()
+// form is still exported for callers that want to pass the helper
+// object around, but extractDocNode is the recommended form.
+const tree = extractDocNode(() => <ResumeTemplate resume={store.resume} />)
+await download(tree, 'resume.pdf')
+await download(tree, 'resume.docx')
+await download(tree, 'resume.html')
+await download(tree, 'resume.md')`,
+    notes:
+      "18 primitives: DocDocument, DocPage, DocSection, DocRow, DocColumn, DocHeading, DocText, DocLink, DocImage, DocTable, DocList, DocListItem, DocCode, DocDivider, DocSpacer, DocButton, DocQuote, DocPageBreak. Same component tree renders in browser AND exports — primitives carry _documentType statics that extractDocumentTree (from @pyreon/connector-document) walks to produce a DocNode for @pyreon/document's render() to consume. DocDocument's title/author/subject accept either a string OR a `() => string` accessor; function values are stored in _documentProps and resolved at extraction time so reactive metadata works without `const initial = get()` workarounds. PR #197 also fixed a latent bug in extractDocumentTree: it now CALLS rocketstyle component functions to read post-attrs _documentProps, where before it only looked at the JSX vnode's props directly — every primitive's metadata was silently dropped during export until that fix landed.",
+    mistakes: `- Calling props.title() at the top of a template body to "fix" reactivity — components run ONCE at mount, so this captures the initial value forever. Pass the accessor through to DocDocument as-is: <DocDocument title={() => get().name}>
+- DocRow direction: layout props (direction, gap) go in .attrs() not .theme(). Element accepts 'inline' | 'rows' | 'reverseInline' | 'reverseRows' — 'row' is NOT valid
+- For text children reactivity, pass a signal accessor and read inside body: <DocText>{() => store.field()}</DocText>
+- Don't declare runtime-filled fields (tag, _documentProps) in the rocketstyle .attrs<P>() generic — they leak as required JSX props
+- Using createDocumentExport(...).getDocNode() in new code — prefer extractDocNode(fn) which is one call instead of two. createDocumentExport is kept for backward compat`,
+  },
+
+  'document-primitives/createDocumentExport': {
+    signature:
+      'createDocumentExport(templateFn: () => VNode): { getDocNode(): DocNode }',
+    example: `// Two-step form (kept for backward compat). New code should
+// prefer the one-step extractDocNode helper.
+import { createDocumentExport } from '@pyreon/document-primitives'
+
+const helper = createDocumentExport(() => <Resume name="Aisha" />)
+const tree = helper.getDocNode()`,
+    notes:
+      "Wrapper around extractDocNode. The wrapper-object form is kept for callers that want to pass the helper around (e.g. to wrapper components that take a DocumentExport instance). New code should use extractDocNode(templateFn) which is one call instead of two.",
+  },
 }