diff --git a/pages/index.md b/pages/index.md
index 602257e..d94b7db 100644
--- a/pages/index.md
+++ b/pages/index.md
@@ -11,7 +11,8 @@ If it runs Python and Node, it runs Pyxle.
 - [Quick start](https://pyxle.dev/docs/getting-started/quick-start.md) — build your first app
 - [.pyxl files](https://pyxle.dev/docs/core-concepts/pyxl-files.md) — the core format
 - [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) — the dashboard built into `pyxle dev`
-- [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md) — breakpoints in the loader and the component
+- [Debugging](https://pyxle.dev/docs/guides/debugging.md) — breakpoints in the loader and the component, in one file
+- [Editor setup](https://pyxle.dev/docs/guides/editor-setup.md) — the VS Code extension: `code --install-extension pyxle.pyxle-language-tools`
 - [Pyxle for AI coding agents](https://pyxle.dev/docs/guides/for-ai-agents.md)
 
 ## Explore
diff --git a/pages/index.pyxl b/pages/index.pyxl
index 666f0be..41cb653 100644
--- a/pages/index.pyxl
+++ b/pages/index.pyxl
@@ -214,7 +214,7 @@ function JustShipped() {
                     </p>
                     <span className="ml-auto flex items-center gap-4">
                         <Link href="/docs/guides/studio" className="focus-ring rounded font-mono text-[12px] text-acct underline decoration-1 underline-offset-4 transition-[text-decoration-thickness] hover:decoration-2">Studio</Link>
-                        <Link href="/docs/guides/debugging-pyxl" className="focus-ring rounded font-mono text-[12px] text-acct underline decoration-1 underline-offset-4 transition-[text-decoration-thickness] hover:decoration-2">Debugger</Link>
+                        <Link href="/docs/guides/debugging" className="focus-ring rounded font-mono text-[12px] text-acct underline decoration-1 underline-offset-4 transition-[text-decoration-thickness] hover:decoration-2">Debugger</Link>
                         <button
                             type="button"
                             onClick={dismiss}
@@ -466,7 +466,7 @@ const INDEX_ROWS = [
     ['Hot reload', 'Vite HMR, Python changes included'],
     ['Server actions', '@action replaces the API layer'],
     ['Studio', 'a dashboard for routes, loaders & actions', '/docs/guides/studio'],
-    ['The debugger', 'breakpoints in .pyxl — Python and React', '/docs/guides/debugging-pyxl'],
+    ['The debugger', 'breakpoints in .pyxl — Python and React', '/docs/guides/debugging'],
     ['Plugins', 'auth, database, and your own'],
     ['ASGI underneath', 'uvicorn today, any host tomorrow'],
 ];
@@ -579,13 +579,24 @@ function StudioAndDebugger() {
                         <p className="mt-3 font-mono text-[11px] leading-relaxed text-ink2">
                             routes · tester · request feed · latency · resolved config · pyxle check
                         </p>
-                        <p className="mt-4 font-mono text-[11px] leading-relaxed text-ink2">
-                            Already on Pyxle? <span className="text-ink">pip install --upgrade pyxle-framework</span>
+                    </div>
+                    <div data-reveal className="mt-5 border-t border-rule pt-5">
+                        <div className="flex items-center gap-3 font-mono text-[13px] text-ink">
+                            <span className="select-none text-acct">$</span>
+                            <span className="truncate">code --install-extension pyxle.pyxle-language-tools</span>
+                            <span className="ml-auto"><CopyButton text="code --install-extension pyxle.pyxle-language-tools" /></span>
+                        </div>
+                        <p className="mt-3 font-mono text-[11px] leading-relaxed text-ink2">
+                            F5 needs the extension · already on Pyxle?{' '}
+                            <span className="text-ink">pip install --upgrade pyxle-framework</span>
                         </p>
                     </div>
                     <p data-reveal className="mt-7 flex flex-wrap items-center gap-x-7 gap-y-3">
+                        <EditorialLink href="/docs/guides/debugging">Debug a .pyxl file →</EditorialLink>
                         <EditorialLink href="/docs/guides/studio">Studio, panel by panel →</EditorialLink>
-                        <EditorialLink href="/docs/guides/debugging-pyxl">Debug a .pyxl file →</EditorialLink>
+                        <EditorialLink href="https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools" external>
+                            Get the VS Code extension ↗
+                        </EditorialLink>
                     </p>
                 </div>
 
diff --git a/public/docs-data/changelog.json b/public/docs-data/changelog.json
index 98f2c60..3cc4f71 100644
--- a/public/docs-data/changelog.json
+++ b/public/docs-data/changelog.json
@@ -1 +1 @@
-{"title":"Changelog","description":"Release notes for Pyxle. While we're in beta (`0.x`), minor versions may include breaking changes — those are called out explicitly. To upgrade, run `pip install --upgrade pyxle-framework`.","html":"<p>Release notes for Pyxle. While we&#39;re in beta (<code>0.x</code>), minor versions may include breaking changes — those are called out explicitly. To upgrade, run <code>pip install --upgrade pyxle-framework</code>.</p>\n<h2 id=\"080\">0.8.0</h2><ul>\n<li><strong>Pyxle Studio — a dashboard built into <code>pyxle dev</code>.</strong> Served at <code>/__pyxle/studio</code>: every route with its loader, actions, cache posture, and boundaries; an interactive tester (loaders run in-process, actions go through their real endpoint — CSRF, validation, and auth hooks included); a live request feed; latency metrics; the effective config (secrets redacted); and in-browser <code>pyxle check</code>. Dev-only by construction, with a <code>Host</code>-header allowlist. <a href=\"/docs/guides/studio\">Pyxle Studio</a>.</li>\n<li><strong>New <code>pyxle studio</code> command.</strong> Runs the dev server and opens the browser on the dashboard, enabling it for that run even when the config opts out. <a href=\"/docs/reference/cli#pyxle-studio\">CLI</a>.</li>\n<li><strong>Breakpoint debugging directly in <code>.pyxl</code> files.</strong> Set a breakpoint on a line inside a <code>@server</code> loader <em>and</em> on a line inside the JSX below it — both bind. Compiled server modules are remapped to their <code>.pyxl</code> sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. <a href=\"/docs/guides/debugging-pyxl\">Debugging .pyxl files</a>.</li>\n<li><strong>One-key debugging from VS Code.</strong> Pyxle Language Tools 0.3.0 contributes a <code>pyxle</code> debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate &quot;Debug Pyxle app (React browser)&quot; configuration debugs the React side in a standalone browser session. Plus a &quot;Pyxle: Open Studio&quot; command. <a href=\"/docs/guides/debugging-pyxl#quick-start-vs-code\">Debugging .pyxl files</a>.</li>\n<li><strong><code>pyxle dev --inspect</code> for attach-style debugging.</strong> Hosts a debugpy server bound to <code>127.0.0.1</code> so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes <code>.pyxle-build/dev-server.json</code> (ports, debugpy endpoint) for editor tooling and removes it on shutdown. <a href=\"/docs/guides/debugging-pyxl\">Debugging .pyxl files</a>.</li>\n<li><strong>Dev tracebacks now point at <code>.pyxl</code> sources.</strong> A loader/action error names your <code>.pyxl</code> file and line instead of the compiled module under <code>.pyxle-build/</code>. <a href=\"/docs/guides/debugging\">Debugging</a>.</li>\n<li><strong>Breaking: <code>/__pyxle</code> is now a reserved URL namespace.</strong> The dev server&#39;s Vite asset proxy never forwards paths under it, so an app route under <code>/__pyxle</code> no longer resolves in <code>pyxle dev</code> (it still serves in production, where the namespace is unused). Move any such route before upgrading. <a href=\"/docs/guides/studio#the-reserved-__pyxle-namespace\">Pyxle Studio</a>.</li>\n<li><strong>Fixed on Windows: <code>NODE_PATH</code> is built with the platform delimiter.</strong> A project that already set <code>NODE_PATH</code> got a <code>:</code>-joined value, which Node cannot parse on Windows, so neither entry resolved.</li>\n<li><strong>Fixed on Windows: rebuild notifications report POSIX paths.</strong> The dev server&#39;s rebuild event carried host separators, so Studio and the error overlay showed <code>pages\\index.pyxl</code>.</li>\n</ul>\n<h2 id=\"075\">0.7.5</h2><ul>\n<li><strong><code>pyxle dev</code> now persists module-level state across requests, like <code>pyxle serve</code>.</strong> A <code>@server</code>/<code>@action</code> module is imported once and reused between rebuilds, so a module-level counter or in-memory cache no longer resets on every refresh in dev. Saving a file still re-imports it (resetting globals and applying your edits). State stays per-process — use a database or cache for anything shared or durable (<a href=\"/docs/core-concepts/data-loading#loaders-should-be-stateless\">Loaders should be stateless</a>).</li>\n<li><strong><code>pyxle init</code> now requires an explicit target.</strong> A bare <code>pyxle init</code> used to silently scaffold into the current directory; it now errors, pointing to <code>pyxle init my-app</code> (new directory) or <code>pyxle init .</code> (current directory).</li>\n</ul>\n<h2 id=\"074\">0.7.4</h2><ul>\n<li><strong>Fix: <code>pyxle dev</code> no longer hot-reloads in an endless loop on Linux.</strong> After a save, the rebuild&#39;s own file reads surfaced through <code>inotify</code> as events the watcher mistook for edits, re-triggering the rebuild forever (macOS <code>FSEvents</code> doesn&#39;t report reads, so it was Linux-only). The watcher now reacts only to genuine change events, not read-only opens.</li>\n</ul>\n<h2 id=\"073\">0.7.3</h2><ul>\n<li><strong>Docs: an <code>@action</code>&#39;s awaited result is the flat <code>{ ok, ...yourReturn }</code></strong> — read fields directly (<code>res.title</code>), never <code>res.data.title</code> (a successful result has no <code>.data</code>; <code>useAction().data</code> is a separate hook property). Clarified across the <a href=\"/docs/core-concepts/server-actions\">Server Actions guide</a>, the <a href=\"/docs/reference/client-api\">client API reference</a>, and the scaffold <code>AGENTS.md</code>.</li>\n</ul>\n<h2 id=\"072\">0.7.2</h2><ul>\n<li><strong>Fix: <code>pyxle init</code> scaffolds an installable <code>requirements.txt</code> again.</strong> The template&#39;s <code>starlette</code> pin conflicted with the framework&#39;s after 0.7.1&#39;s security bump; both now use <code>starlette&gt;=1.3.1,&lt;2.0</code>.</li>\n<li><strong>Config: a boolean <code>port</code> is now rejected instead of binding port 1.</strong> <code>bool</code> being an <code>int</code> subclass slipped past the validator; it now raises a clear <code>ConfigError</code>.</li>\n</ul>\n<h2 id=\"071\">0.7.1</h2><ul>\n<li><strong>Security: require Starlette ≥ 1.3.1</strong>, fixing a <code>Host</code>-header auth bypass (PYSEC-2026-161), form-parsing DoS (PYSEC-2026-249, -1943), and a Windows <code>StaticFiles</code> SSRF (CVE-2026-48818). Pyxle&#39;s own API is unchanged; a new <code>pip-audit</code> CI job guards dependencies.</li>\n<li><strong><code>pyxle serve</code> refuses to start in production without <code>PYXLE_SECRET_KEY</code></strong> — previously only a warning, leaving CSRF tokens and signed cookies forgeable. <a href=\"/docs/guides/security\">Security</a>, <a href=\"/docs/guides/deployment\">Deployment</a>.</li>\n<li><strong><code>pyxle dev</code>/<code>build</code> check the Node.js version up front</strong> — a clear &quot;Node.js 20.19+ required&quot; message instead of an opaque Vite crash. <a href=\"/docs/getting-started/installation#troubleshooting\">Installation → Troubleshooting</a>.</li>\n<li><strong>A real testing story: <code>pyxle.testing</code> helpers and a <a href=\"/docs/guides/testing\">Testing guide</a>.</strong> <code>load_loader(&quot;pages/index.pyxl&quot;)</code> / <code>load_page(...)</code> compile a page and hand back its loader/module for unit tests.</li>\n<li><strong>New <a href=\"/docs/guides/debugging\">Debugging guide</a> and Deployment fixes</strong> — Node 22 in the sample Dockerfile, the real metrics path (<code>/api/__pyxle/metrics</code>), a migrations section, and a blue-green CSRF gotcha.</li>\n<li><strong>Security docs now match what Pyxle sends</strong> — it already sets <code>X-Content-Type-Options</code>/<code>X-Frame-Options</code>/<code>Referrer-Policy</code>, so the guide covers only CSP and HSTS; a <a href=\"https://github.com/pyxle-dev/pyxle/blob/main/SECURITY.md\" target=\"_blank\" rel=\"noreferrer\">SECURITY.md</a> is published for every repo.</li>\n<li><strong>A fresh project now ships a human <code>README.md</code></strong> alongside the AI-oriented <code>AGENTS.md</code>.</li>\n<li><strong>The <a href=\"/docs/guides/comparison\">comparison guide</a> names current gaps</strong> — TSX authoring, a first-class test client, automatic image/font optimization, i18n — with how to bridge each today.</li>\n</ul>\n<h2 id=\"070\">0.7.0</h2><ul>\n<li><strong>Fix: <code>error.pyxl</code> renders even when an ancestor layout has a <code>@server</code> loader.</strong> Boundary renders now run ancestor layout loaders like a normal page instead of silently falling back to the built-in error document.</li>\n<li><strong>Pre-release fixes.</strong> <code>PYXLE_SSR_WORKER_CONCURRENCY</code> reaches the worker again, <code>SIGTERM</code> to <code>pyxle dev</code> tears down the whole child tree, a failed rebuild broadcasts to the overlay, and reverting to last-good content triggers the recovery rebuild.</li>\n<li><strong>Fix: CommonJS React libraries no longer crash SSR.</strong> The SSR bundler resolves dependencies ESM-first (like Vite), so packages without an <code>exports</code> map (e.g. <code>lucide-react</code>) link cleanly; a genuinely CJS-only package now fails with an actionable error. <a href=\"/docs/guides/third-party-packages#commonjs-packages-and-ssr\">Third-party packages</a>.</li>\n<li><strong>Docs: <a href=\"/docs/guides/fully-typed-pyxle\">the road to a fully-typed Pyxle</a></strong> — where the type story is heading (TSX authoring, Python types across the boundary), grounded in what works today.</li>\n<li><strong>Breaking: Node.js 20.19+ is now required</strong> (Vite 7&#39;s floor; Node 18 is EOL). <a href=\"/docs/getting-started/installation\">Installation</a>.</li>\n<li><strong>Modernized scaffold — React 19, Vite 7, and an interactive <code>pyxle init</code>.</strong> Arrow-key prompts for Tailwind, shadcn/ui, and the import alias, with <code>--yes</code>/explicit flags for non-interactive use. <a href=\"/docs/getting-started/quick-start\">Quick Start</a>.</li>\n<li><strong>Tailwind is now opt-in — Tailwind v4 wired into Vite when chosen.</strong> No config files or standalone watcher; decline it and plain CSS / CSS Modules work out of the box. <a href=\"/docs/guides/styling\">Styling</a>.</li>\n<li><strong>shadcn/ui support</strong> — choose it at <code>pyxle init</code> and <code>npx shadcn@latest add …</code> works with no <code>shadcn init</code>; the <code>@</code> alias resolves in the client build and SSR. <a href=\"/docs/guides/third-party-packages#shadcnui\">Third-party packages</a>.</li>\n<li><strong>Fix: streaming SSR no longer serializes across requests.</strong> An SSR worker now renders many requests concurrently (isolated per-request with <code>AsyncLocalStorage</code>), and <code>pyxle serve</code> auto-sizes its worker pool. <a href=\"/docs/guides/streaming#concurrent-streams-dont-queue\">Streaming</a>.</li>\n<li><strong><code>pyxle init</code> renders the framework pin from the running version</strong> instead of a stale <code>&gt;=0.4.1</code> that downgraded fresh projects.</li>\n<li><strong><code>pyxle typecheck</code> fails fast when TypeScript isn&#39;t installed</strong>, with an actionable message instead of npm&#39;s placeholder <code>tsc</code>. <a href=\"/docs/guides/typescript\">TypeScript</a>.</li>\n<li><strong>Scaffolded <code>AGENTS.md</code> corrected</strong> — <code>LoaderError</code> (like <code>server</code>/<code>action</code>/<code>ActionError</code>/…) is compiler-injected, not imported.</li>\n<li><strong><code>pyxle check</code> works out of the box — <code>pyxle-langkit</code> is now a default dependency</strong>, so JSX checking passes on a fresh scaffold with no extra step.</li>\n<li><strong>Fix: the CSRF cookie no longer collides between apps on one host.</strong> The default name is namespaced by bind port (<code>pyxle-csrf-8000</code>) and injected into the page shell. <a href=\"/docs/guides/security#csrf-protection\">Security → CSRF</a>.</li>\n<li><strong>Fix: multipart forms (file uploads) now pass CSRF with a <code>_csrf_token</code> field.</strong> The middleware stream-parses just far enough to read the token (capped at 1 MiB) and replays the body untouched. <a href=\"/docs/guides/security#form-bodies-and-uploads\">Security → Form bodies and uploads</a>.</li>\n<li><strong><code>pyxle dev</code> output is clean by default, <code>--verbose</code> for the firehose</strong> — a curated startup summary and one-line rebuild notices instead of Vite&#39;s raw stdout. <a href=\"/docs/reference/cli#pyxle-dev\">CLI</a>.</li>\n<li><strong>Server-side logs stream to the browser console in <code>pyxle dev</code></strong>, prefixed <code>[pyxle:server]</code>; dev-only and bounded. <a href=\"/docs/reference/cli#pyxle-dev\">CLI</a>.</li>\n<li><strong><code>public/</code> changes are picked up on refresh instead of triggering a rebuild (matching Next.js)</strong> — assets serve live from disk, and a newly added or removed file refreshes the static index. <a href=\"/docs/architecture/dev-server#the-watcher\">Architecture → the watcher</a>.</li>\n<li><strong>Watch extra directories with <code>dev.watch</code>, ignore paths with <code>dev.ignore</code>.</strong> A shared module outside <code>pages/</code> can now trigger hot reload; <code>dev.ignore</code> is additive to the built-in ignores. <a href=\"/docs/reference/configuration#development\">Configuration → Development</a>.</li>\n</ul>\n<h3 id=\"documentation\">Documentation</h3><ul>\n<li><strong>Fixed the flagship <a href=\"/docs/guides/websockets\">WebSockets</a> example</strong> — it derived the socket path from <code>window</code> during SSR and 500&#39;d; it now builds the path from loader data.</li>\n<li><strong>More doc fixes</strong> — a broken <code>@action</code> example in the <a href=\"/docs/plugins/pyxle-db\">pyxle-db docs</a> (<code>await request.json()</code>), documented CSRF on the pyxle-auth endpoints and where pyxle-auth accounts live, an honest <a href=\"/docs/reference/cli#pyxle-check\"><code>pyxle check</code></a> scope note, and prerequisites up front in the <a href=\"/docs/getting-started/introduction\">Introduction</a>.</li>\n<li><strong><code>Accept: text/markdown</code> negotiation now follows RFC 9110</strong> (q-values honoured, exact type match); new <code>markdown_is_acceptable(accept)</code> helper. <a href=\"/docs/guides/llms#negotiation-rules\">AI accessibility</a>.</li>\n<li><strong><code>/llms.txt</code> now emits absolute URLs and links <code>.md</code> only where Markdown actually resolves.</strong> <a href=\"/docs/guides/llms#the-llmstxt-index\">AI accessibility</a>.</li>\n<li><strong>Breaking: converted Markdown rewrites internal links to <code>.md</code></strong> — <code>html_to_markdown()</code> rewrites by default (<code>rewrite_links=False</code> for the old behavior). <a href=\"/docs/guides/llms#autoconvert-the-lossy-fallback\">AI accessibility</a>.</li>\n<li><strong>Fix: a burst of rapid saves can no longer kill the dev server</strong> — builds are serialized, <code>meta.json</code> writes atomically, and the Vite subprocess is supervised with bounded backoff.</li>\n<li><strong>Fix: reading an unprovided <code>request.state.&lt;name&gt;</code></strong> (e.g. <code>request.state.db</code> without pyxle-db) now gives a structured, guided error instead of a bare <code>AttributeError</code>.</li>\n<li><strong>Actionable SSR error when a component touches a browser global</strong> (<code>window</code>, <code>document</code>, …) — dev names your <code>.pyxl</code> file and the fix (<code>useEffect</code>/<code>&lt;ClientOnly&gt;</code>); production stays generic. <a href=\"/docs/guides/client-components\">Client Components</a>.</li>\n</ul>\n<h2 id=\"061\">0.6.1</h2><p>A sharper <code>pyxle check</code> — the edit → check → fix loop now catches classes of mistake it used to wave through.</p>\n<ul>\n<li><strong><code>pyxle check</code> gained a semantic layer</strong> — pyflakes over the Python section flags undefined names, unused imports, and redefinitions (compiler-injected names are recognized).</li>\n<li><strong>Duplicate <code>export default</code> is now caught at check time</strong>, at the real source line, instead of failing later in the build.</li>\n<li><strong>JSX error lines are now accurate</strong>, and Babel&#39;s misleading &quot;unterminated regex&quot; carries a plain-language hint about the real cause.</li>\n<li><strong><code>LoaderError</code> and <code>invalidate_routes</code> are now auto-injected</strong>, matching <code>ActionError</code>/<code>ValidationActionError</code>. <a href=\"/docs/reference/runtime-api\">Runtime API</a>.</li>\n<li><strong><code>pyxle install --break-system-packages</code></strong> for externally-managed (PEP 668) environments. <a href=\"/docs/reference/cli#pyxle-install\">CLI</a>.</li>\n</ul>\n<h2 id=\"060\">0.6.0</h2><ul>\n<li><strong>AI accessibility — serve your app as Markdown, plus <code>llms.txt</code>.</strong> Opt in with <code>&quot;llms&quot;: true</code> and every page gains a <code>.md</code> rendition (and <code>Accept: text/markdown</code> support), an <code>/llms.txt</code> index, and discovery headers; Markdown resolves from a co-located <code>&lt;page&gt;.md</code>, a <code>to_markdown</code> handler, or an ancestor <code>llms.py</code>, with an <code>autoConvert</code> HTML→Markdown fallback. Off by default, and adds nothing to the page hot path. <a href=\"/docs/guides/llms\">AI accessibility</a>.</li>\n</ul>\n<h2 id=\"050\">0.5.0</h2><p>The depth release: caching/SSG/ISR, streaming SSR, realtime (WebSockets + a cross-worker Redis broker), Pydantic-validated actions, observability, background work, image optimization, and multi-worker serving — built, documented, and dogfooded on pyxle.dev. The two behavior changes below are called out explicitly.</p>\n<ul>\n<li><strong>Cross-worker realtime — a Redis pub/sub broker.</strong> WebSocket channels span worker processes and machines with <code>PYXLE_REALTIME_BROKER=redis</code>; the in-process broker stays the default. No code change. <a href=\"/docs/guides/websockets#cross-worker-realtime-with-redis\">WebSockets</a>.</li>\n<li><strong>Fix: streaming SSR now survives production gzip.</strong> A streaming-aware <code>StreamingGZipMiddleware</code> flushes the compressor per chunk so the shell reaches the browser first. <a href=\"/docs/guides/streaming#streaming-survives-gzip-in-production\">Streaming</a>.</li>\n<li><strong>Fix: dynamic pages are no longer client-nav-cached with stale data.</strong> The navigation-cache TTL now mirrors server cacheability, so a dynamic page always refetches on back/forward. <a href=\"/docs/guides/caching#client-navigation-cache\">Caching</a>.</li>\n<li><strong>Fix: <code>pyxle build --static</code> pre-renders pages whose loaders use a plugin.</strong> The static builder stands up the same plugin context a request sees, so a DB-backed loader runs at build time. <a href=\"/docs/guides/caching#static-pre-rendering-pyxle-build-static\">Caching</a>.</li>\n<li><strong>Changed (behavior): stricter nested-config validation.</strong> The <code>cors</code>/<code>csrf</code>/<code>observability</code>/… blocks now reject unknown keys at boot, so a typo&#39;d security key fails loudly instead of silently no-opping. <a href=\"/docs/reference/configuration\">Configuration</a>.</li>\n<li><strong>Fix: <code>error.pyxl</code> no longer leaks internal error details in production</strong> — the boundary gets a generic message and sanitized type; author-raised <code>LoaderError</code>/<code>ActionError</code> messages still pass through. <a href=\"/docs/guides/error-handling\">Error Handling</a>.</li>\n<li><strong>Fix: <code>import.meta.env.PYXLE_PUBLIC_*</code> is now substituted during SSR</strong>, so a public env var no longer causes a hydration mismatch. <a href=\"/docs/guides/environment-variables\">Environment variables</a>.</li>\n<li><strong>Fix: scaffold <code>.gitignore</code> no longer ignores <code>.env</code></strong>, matching the env-vars doc.</li>\n<li><strong>Fix: <code>&lt;Image&gt;</code> emits a lowercase <code>fetchpriority</code> attribute</strong> (React 18.3.1 rejected the camelCase form).</li>\n<li><strong>Fix: production gzip no longer prints <code>I/O operation on closed file</code></strong> — the compressor closes deterministically on every path.</li>\n<li><strong>Fix: scaffolded <code>jsconfig.json</code> drops the deprecated <code>baseUrl</code></strong> in favor of tsconfig-relative <code>paths</code>.</li>\n<li><strong>Fix: <code>pyxle typecheck</code> works on current TypeScript</strong> — <code>&quot;bundler&quot;</code> resolution, no <code>baseUrl</code>.</li>\n<li><strong>Startup warning when a <code>BaseHTTPMiddleware</code> is paired with streaming routes</strong> (it buffers responses, breaking streaming SSR). <a href=\"/docs/guides/middleware\">Middleware</a>.</li>\n<li><strong>Clear compile-time error for TypeScript syntax in a client block</strong> (it&#39;s plain JSX), pointing at your <code>.pyxl</code> source line. <a href=\"/docs/guides/typescript\">TypeScript</a>.</li>\n<li><strong>New guides: <a href=\"/docs/guides/typescript\">TypeScript</a> and <a href=\"/docs/guides/migration-from-flask-django\">Migrating from Flask or Django</a>.</strong></li>\n<li><strong><code>error.pyxl</code> is now a client-side error boundary too</strong> — a render fault after hydration renders the nearest boundary instead of a blank screen, with the same <code>error</code> prop on both sides. <a href=\"/docs/guides/error-handling#client-side-errors\">Error Handling</a>.</li>\n<li><strong>Built-in rate limiting — <code>pyxle.middleware.RateLimitMiddleware</code>.</strong> A dependency-free token-bucket limiter configured from <code>pyxle.config.json</code>; per-process, so rate-limit at the proxy for one global cap. Off by default. <a href=\"/docs/guides/middleware#rate-limiting\">Middleware</a>.</li>\n<li><strong>Route policies now apply to <code>@action</code> endpoints</strong> via <code>routeMiddleware.actions</code>, closing a bypass where an auth policy wrapped pages but not actions. <a href=\"/docs/guides/middleware#route-level-hooks\">Middleware</a>.</li>\n<li><strong><code>pyxle serve --workers 0</code> auto-detects the core count.</strong> The <a href=\"/docs/guides/deployment#multi-core-worker-processes\">Deployment guide</a> adds a per-worker-state table and rolling-deploy guidance.</li>\n<li><strong>Build optimization: responsive <code>&lt;Image&gt;</code>, modulepreload hints, and <code>--analyze</code>.</strong> <code>&lt;Image&gt;</code> emits a responsive <code>srcset</code> via a <code>loader</code> and gains <code>fill</code>/<code>sizes</code>/<code>priority</code>; the SSR shell preloads entry chunks; <code>pyxle build --analyze</code> reports bundle sizes. <a href=\"/docs/guides/build-optimization\">Build Optimization</a>.</li>\n<li><strong>Background tasks &amp; deferred work.</strong> <code>request.state.background.add_task(...)</code> (or a <code>{&quot;background&quot;: [...]}</code> return) runs after the response; <code>pyxle.tasks.enqueue(...)</code> schedules fire-and-forget work on an in-process pool (per-process — hand off to Celery/ARQ/Dramatiq for durability). <a href=\"/docs/guides/background-tasks\">Background Tasks</a>.</li>\n<li><strong>OpenTelemetry tracing (opt-in).</strong> Request/SSR/loader/action spans via the <code>[observability-otel]</code> extra; fully off and zero-cost by default. <a href=\"/docs/guides/observability#opentelemetry-tracing\">Observability</a>.</li>\n<li><strong><code>pyxle dev --dashboard</code> — a live terminal observability panel</strong> (throughput, error rate, latency, cache hit ratio); dependency-free and dev-only. <a href=\"/docs/guides/observability#dev-dashboard\">Observability</a>.</li>\n<li><strong>Structured access logging</strong> — one line per request (<code>method</code>/<code>path</code>/<code>status</code>/<code>duration_ms</code>/correlation id) in console or JSON via <code>observability.accessLog</code>. <a href=\"/docs/guides/observability#structured-logging\">Observability</a>.</li>\n<li><strong>Observability: request IDs, timing, metrics, and richer health probes.</strong> Every request gets a correlation id (<code>X-Request-Id</code>) and timing; opt-in Prometheus metrics; <code>/readyz</code> runs dependency checks. Metrics are per-worker. <a href=\"/docs/guides/observability\">Observability</a>.</li>\n<li><strong>Typed <code>@action</code> request validation with Pydantic.</strong> Annotate a <code>body: Model</code> parameter and Pyxle validates before the action runs, returning <code>422</code> with a <code>fields</code> map on failure; <code>pyxle openapi</code> generates an OpenAPI 3.1 document from your models. Optional <code>[pydantic]</code> extra. <a href=\"/docs/core-concepts/server-actions#validating-request-bodies-with-pydantic\">Server Actions</a>.</li>\n<li><strong>Fix: a server module that fails to import is no longer cached as a broken empty module</strong> — the real error re-raises on each request.</li>\n<li><strong>WebSockets — page handlers, a client hook, and pub/sub.</strong> A page can export <code>async def websocket(ws)</code>; <code>pyxle.realtime</code> adds <code>channel</code>/<code>room.publish</code>, WS auth/origin helpers, and a <code>useWebSocket()</code> hook. The in-process broker is per-worker (a Redis broker drops in). <a href=\"/docs/guides/websockets\">WebSockets</a>.</li>\n<li><strong>Streaming SSR for <code>&lt;Suspense&gt;</code> pages.</strong> The shell flushes immediately and each boundary streams in as it resolves; opt-in, zero-config, dynamic pages only. <a href=\"/docs/guides/streaming\">Streaming</a>.</li>\n<li><strong><code>loading.pyxl</code> route-level loading states</strong> wrap a route in <code>&lt;Suspense&gt;</code>, streamed as the shell and applied identically on the client. <a href=\"/docs/guides/streaming#route-level-loading-states-with-loadingpyxl\">Streaming</a>.</li>\n<li><strong>Server-side page caching with incremental regeneration.</strong> Return <code>{&quot;data&quot;, &quot;revalidate&quot;: N}</code> (or a <code>CACHE</code> directive) to cache rendered HTML; <code>pyxle build --static</code> warms it; stale-while-revalidate, strong <code>ETag</code>, and <code>cache.invalidate(...)</code>. In-memory/disk/Redis backends. <a href=\"/docs/guides/caching\">Caching</a>.</li>\n</ul>\n<h2 id=\"045\">0.4.5</h2><ul>\n<li><strong>Signed cookies &amp; tokens — <code>sign_cookie</code> / <code>verify_cookie</code>.</strong> Stdlib-only helpers that attach a tamper-proof HMAC-SHA256 signature to any string (session id, unsubscribe link, reset token) and verify it in constant time; a <code>salt=</code> namespaces signatures, and signing without a secret fails closed. <a href=\"/docs/guides/security#signed-cookies-and-tokens\">Security</a>.</li>\n<li><strong>Fix: <code>PYXLE_PUBLIC_*</code> client env vars now work in <code>pyxle dev</code> and no longer break <code>pyxle build</code></strong> — values are emitted as quoted JS string literals, so a non-identifier value (API URL, Turnstile key) resolves in both. <a href=\"/docs/guides/environment-variables\">Environment variables</a>.</li>\n<li><strong>Fix: web fonts and other CSS <code>url()</code> assets no longer 404 in <code>pyxle dev</code></strong> — Pyxle sets Vite&#39;s <code>server.origin</code> so dev assets load from Vite directly.</li>\n</ul>\n<h2 id=\"044\">0.4.4</h2><ul>\n<li><strong>Fix: cross-page hash links scroll to their anchor.</strong> Client-side navigation to <code>/page#section</code> now jumps to the top and scrolls to the anchor once the next page commits, matching native behaviour.</li>\n</ul>\n<h2 id=\"043\">0.4.3</h2><ul>\n<li><strong>Security: hardened HEAD sanitisation (XSS).</strong> Dynamic <code>HEAD</code> values are now parsed and rebuilt from a strict tag allowlist with every attribute HTML-escaped, <code>on*</code> handlers dropped, dangerous URLs neutralised, and non-head tags rejected — closing an injection via the dynamic-meta-tags recipe. Inline <code>&lt;script&gt;</code>/<code>&lt;style&gt;</code> stays supported as trusted author code.</li>\n<li><strong>Security: <code>csrf.exemptPaths</code> match on segment boundaries</strong>, so exempting <code>/api/webhooks</code> no longer also exempts <code>/api/webhooks-admin</code>.</li>\n<li><strong>Security: oversized no-JS form POSTs fail loud</strong> with a <code>413</code> (asking for the token via header) instead of being silently truncated.</li>\n<li><strong>Fix: <code>&lt;Script&gt;</code>/<code>&lt;Image&gt;</code> boolean attributes written as strings</strong> (<code>defer=&quot;false&quot;</code>, <code>priority=&quot;0&quot;</code>) now coerce correctly instead of to <code>True</code>.</li>\n<li><strong>Fix: custom <code>csrf.cookieName</code>/<code>headerName</code> now reach the client runtime</strong> — non-default names are injected into the shell so <code>useAction</code>/<code>&lt;Form&gt;</code> stop <code>403</code>-ing.</li>\n<li><strong>Fix: no double loader run on hover-then-click navigation</strong> — the click reuses the in-flight prefetch, and a superseded prefetch is discarded.</li>\n<li><strong>Multi-core serving: <code>pyxle serve --workers N</code>.</strong> N independent server processes on one port, each with its own SSR pool — throughput scales with cores, no load balancer or shared state. <a href=\"/docs/guides/deployment#multi-core-worker-processes\">Deployment</a>.</li>\n<li><strong>Sync API endpoints.</strong> A plain <code>def endpoint(request)</code> (and sync <code>HTTPEndpoint</code> methods) now runs in Starlette&#39;s threadpool, so blocking drivers no longer need manual <code>asyncio.to_thread</code>. <a href=\"/docs/guides/api-routes#sync-endpoints-and-blocking-calls\">API Routes</a>.</li>\n<li><strong>In-memory static asset cache.</strong> Small static files (≤1 MB, 32 MB/process) are served from memory with no filesystem I/O; conditional requests and cache headers behave as before.</li>\n</ul>\n<h2 id=\"042\">0.4.2</h2><ul>\n<li><strong>Live dev-server reconciliation.</strong> Editing a <code>.pyxl</code> now applies route-shape changes without a restart — rename/add/remove a loader or action, add/delete a page, wrap a page in a layout — by hot-swapping the route table; editing <code>pyxle.config.json</code> prints a &quot;restart to apply&quot; warning.</li>\n<li><strong><code>pyxle check</code> works on a clean install</strong> — the JSX checker&#39;s parser dependencies are bundled (via <code>pyxle-langkit</code>), so <code>check</code> runs after <code>pip install &#39;pyxle-framework[langkit]&#39;</code> with no npm setup.</li>\n<li><strong>Locale-independent SSR</strong> — the Python↔Node transport pins UTF-8, so non-BMP characters no longer crash rendering under <code>LANG=C</code>.</li>\n<li><strong>Smoother first run</strong> — <code>pyxle init</code> writes a gitignored <code>.env.local</code> with a random dev secret, the scaffold <code>requirements.txt</code> declares <code>pyxle-framework</code>, and <code>pyxle install</code> gives PEP 668 guidance.</li>\n<li><strong>Docs:</strong> documented calling an <code>@action</code> endpoint directly for scripts and tests.</li>\n</ul>\n<h2 id=\"041\">0.4.1</h2><ul>\n<li><strong>No more double loader run on first load.</strong> The landing page is seeded into the client navigation cache from the server render, so its prefetch resolves from cache — the loader runs once, not twice (also making back/forward instant).</li>\n<li><strong>Per-route navigation-cache TTL.</strong> A route&#39;s <a href=\"/docs/reference/configuration#edge-caching\"><code>cache</code></a> TTL now also governs client navigation-cache freshness; routes without one default to 2 minutes, tunable via <a href=\"/docs/reference/configuration#navigation\"><code>navigation.defaultPrefetchTtl</code></a>.</li>\n</ul>\n<h2 id=\"040\">0.4.0</h2><ul>\n<li><strong>Edge caching.</strong> Declare cacheable routes in <a href=\"/docs/reference/configuration#edge-caching\"><code>pyxle.config.json::cache</code></a> and pages serve <code>Cache-Control: public, s-maxage=N</code> (+ <code>stale-while-revalidate</code>) so a CDN absorbs traffic; the per-user CSRF cookie is omitted from cacheable responses. <a href=\"/docs/guides/deployment#cdn-and-edge-caching\">Deployment</a>.</li>\n<li><strong>Hardened production errors.</strong> SSR render failures (including the SPA-navigation JSON path) are sanitized in the response and logged in full for operators.</li>\n<li><strong>Faster static serving.</strong> The static-asset middleware indexes paths up front, skipping a per-request <code>stat</code> on every dynamic request.</li>\n<li><strong>Layout &amp; template loaders.</strong> A <code>layout.pyxl</code>/<code>template.pyxl</code> can declare its own <code>@server</code> loader, so shared UI loads once per request without repeating the loader in every page. <a href=\"/docs/core-concepts/layouts#layout-data-loaders\">Layouts</a>.</li>\n</ul>\n<h2 id=\"030\">0.3.0</h2><ul>\n<li><strong>First-class plugin system.</strong> Compose apps via <code>pyxle.config.json::plugins</code> (Django-style <code>INSTALLED_APPS</code>). <a href=\"/docs/guides/plugins\">Plugins guide</a>, <a href=\"/docs/reference/plugins-api\">Plugins API</a>.</li>\n<li><strong>Django-style service access.</strong> Resolve any plugin service with <code>plugin(&quot;auth.service&quot;)</code> or a typed shortcut (e.g. <code>from pyxle_auth import get_auth_service</code>).</li>\n<li><strong>First-party plugins.</strong> <a href=\"/docs/plugins/pyxle-db\"><code>pyxle-db</code></a> (SQLite-first with migrations) and <a href=\"/docs/plugins/pyxle-auth\"><code>pyxle-auth</code></a> (email+password sessions, argon2id, rate limits).</li>\n<li><strong>WebSocket endpoints</strong> — <code>pages/api/*.py</code> can export <code>async def websocket(ws)</code>. <a href=\"/docs/guides/api-routes#websocket-endpoints\">API Routes</a>.</li>\n<li><strong>Client navigation cache with TTL + invalidation.</strong> Loader payloads are cached (30s default) for instant back/forward; call <a href=\"/docs/reference/client-api#invalidateurl\"><code>invalidate(url)</code></a> or return <a href=\"/docs/reference/runtime-api#invalidate_routesresponse-urls\"><code>invalidate_routes(...)</code></a> from an action to keep lists fresh.</li>\n<li><strong><code>ActionError</code> is auto-imported</strong> for any <code>.pyxl</code> with an <code>@action</code>.</li>\n<li><strong><code>&lt;Head&gt;</code> coerces multi-part <code>&lt;title&gt;</code> children</strong> into a single string, silencing React&#39;s array-title warning.</li>\n<li><strong>SSR worker pins <code>LANG=en-US.UTF-8</code></strong> (override with <code>PYXLE_SSR_LOCALE</code>) to stop <code>Intl</code> hydration mismatches.</li>\n<li><strong>Vite resolver prefers pinned versions</strong> — <code>pyxle build</code> runs <code>npm install</code> before falling back to <code>npx --yes vite</code>.</li>\n</ul>\n","toc":[{"depth":2,"text":"0.8.0","slug":"080"},{"depth":2,"text":"0.7.5","slug":"075"},{"depth":2,"text":"0.7.4","slug":"074"},{"depth":2,"text":"0.7.3","slug":"073"},{"depth":2,"text":"0.7.2","slug":"072"},{"depth":2,"text":"0.7.1","slug":"071"},{"depth":2,"text":"0.7.0","slug":"070"},{"depth":3,"text":"Documentation","slug":"documentation"},{"depth":2,"text":"0.6.1","slug":"061"},{"depth":2,"text":"0.6.0","slug":"060"},{"depth":2,"text":"0.5.0","slug":"050"},{"depth":2,"text":"0.4.5","slug":"045"},{"depth":2,"text":"0.4.4","slug":"044"},{"depth":2,"text":"0.4.3","slug":"043"},{"depth":2,"text":"0.4.2","slug":"042"},{"depth":2,"text":"0.4.1","slug":"041"},{"depth":2,"text":"0.4.0","slug":"040"},{"depth":2,"text":"0.3.0","slug":"030"}],"path":"changelog","markdown":"# Changelog\n\nRelease notes for Pyxle. While we're in beta (`0.x`), minor versions may include breaking changes — those are called out explicitly. To upgrade, run `pip install --upgrade pyxle-framework`.\n\n## 0.8.0\n\n- **Pyxle Studio — a dashboard built into `pyxle dev`.** Served at `/__pyxle/studio`: every route with its loader, actions, cache posture, and boundaries; an interactive tester (loaders run in-process, actions go through their real endpoint — CSRF, validation, and auth hooks included); a live request feed; latency metrics; the effective config (secrets redacted); and in-browser `pyxle check`. Dev-only by construction, with a `Host`-header allowlist. [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md).\n- **New `pyxle studio` command.** Runs the dev server and opens the browser on the dashboard, enabling it for that run even when the config opts out. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-studio).\n- **Breakpoint debugging directly in `.pyxl` files.** Set a breakpoint on a line inside a `@server` loader *and* on a line inside the JSX below it — both bind. Compiled server modules are remapped to their `.pyxl` sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md).\n- **One-key debugging from VS Code.** Pyxle Language Tools 0.3.0 contributes a `pyxle` debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate \"Debug Pyxle app (React browser)\" configuration debugs the React side in a standalone browser session. Plus a \"Pyxle: Open Studio\" command. [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md#quick-start-vs-code).\n- **`pyxle dev --inspect` for attach-style debugging.** Hosts a debugpy server bound to `127.0.0.1` so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes `.pyxle-build/dev-server.json` (ports, debugpy endpoint) for editor tooling and removes it on shutdown. [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md).\n- **Dev tracebacks now point at `.pyxl` sources.** A loader/action error names your `.pyxl` file and line instead of the compiled module under `.pyxle-build/`. [Debugging](https://pyxle.dev/docs/guides/debugging.md).\n- **Breaking: `/__pyxle` is now a reserved URL namespace.** The dev server's Vite asset proxy never forwards paths under it, so an app route under `/__pyxle` no longer resolves in `pyxle dev` (it still serves in production, where the namespace is unused). Move any such route before upgrading. [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md#the-reserved-__pyxle-namespace).\n- **Fixed on Windows: `NODE_PATH` is built with the platform delimiter.** A project that already set `NODE_PATH` got a `:`-joined value, which Node cannot parse on Windows, so neither entry resolved.\n- **Fixed on Windows: rebuild notifications report POSIX paths.** The dev server's rebuild event carried host separators, so Studio and the error overlay showed `pages\\index.pyxl`.\n\n## 0.7.5\n\n- **`pyxle dev` now persists module-level state across requests, like `pyxle serve`.** A `@server`/`@action` module is imported once and reused between rebuilds, so a module-level counter or in-memory cache no longer resets on every refresh in dev. Saving a file still re-imports it (resetting globals and applying your edits). State stays per-process — use a database or cache for anything shared or durable ([Loaders should be stateless](https://pyxle.dev/docs/core-concepts/data-loading.md#loaders-should-be-stateless)).\n- **`pyxle init` now requires an explicit target.** A bare `pyxle init` used to silently scaffold into the current directory; it now errors, pointing to `pyxle init my-app` (new directory) or `pyxle init .` (current directory).\n\n## 0.7.4\n\n- **Fix: `pyxle dev` no longer hot-reloads in an endless loop on Linux.** After a save, the rebuild's own file reads surfaced through `inotify` as events the watcher mistook for edits, re-triggering the rebuild forever (macOS `FSEvents` doesn't report reads, so it was Linux-only). The watcher now reacts only to genuine change events, not read-only opens.\n\n## 0.7.3\n\n- **Docs: an `@action`'s awaited result is the flat `{ ok, ...yourReturn }`** — read fields directly (`res.title`), never `res.data.title` (a successful result has no `.data`; `useAction().data` is a separate hook property). Clarified across the [Server Actions guide](https://pyxle.dev/docs/core-concepts/server-actions.md), the [client API reference](https://pyxle.dev/docs/reference/client-api.md), and the scaffold `AGENTS.md`.\n\n## 0.7.2\n\n- **Fix: `pyxle init` scaffolds an installable `requirements.txt` again.** The template's `starlette` pin conflicted with the framework's after 0.7.1's security bump; both now use `starlette>=1.3.1,<2.0`.\n- **Config: a boolean `port` is now rejected instead of binding port 1.** `bool` being an `int` subclass slipped past the validator; it now raises a clear `ConfigError`.\n\n## 0.7.1\n\n- **Security: require Starlette ≥ 1.3.1**, fixing a `Host`-header auth bypass (PYSEC-2026-161), form-parsing DoS (PYSEC-2026-249, -1943), and a Windows `StaticFiles` SSRF (CVE-2026-48818). Pyxle's own API is unchanged; a new `pip-audit` CI job guards dependencies.\n- **`pyxle serve` refuses to start in production without `PYXLE_SECRET_KEY`** — previously only a warning, leaving CSRF tokens and signed cookies forgeable. [Security](https://pyxle.dev/docs/guides/security.md), [Deployment](https://pyxle.dev/docs/guides/deployment.md).\n- **`pyxle dev`/`build` check the Node.js version up front** — a clear \"Node.js 20.19+ required\" message instead of an opaque Vite crash. [Installation → Troubleshooting](https://pyxle.dev/docs/getting-started/installation.md#troubleshooting).\n- **A real testing story: `pyxle.testing` helpers and a [Testing guide](https://pyxle.dev/docs/guides/testing.md).** `load_loader(\"pages/index.pyxl\")` / `load_page(...)` compile a page and hand back its loader/module for unit tests.\n- **New [Debugging guide](https://pyxle.dev/docs/guides/debugging.md) and Deployment fixes** — Node 22 in the sample Dockerfile, the real metrics path (`/api/__pyxle/metrics`), a migrations section, and a blue-green CSRF gotcha.\n- **Security docs now match what Pyxle sends** — it already sets `X-Content-Type-Options`/`X-Frame-Options`/`Referrer-Policy`, so the guide covers only CSP and HSTS; a [SECURITY.md](https://github.com/pyxle-dev/pyxle/blob/main/SECURITY.md) is published for every repo.\n- **A fresh project now ships a human `README.md`** alongside the AI-oriented `AGENTS.md`.\n- **The [comparison guide](https://pyxle.dev/docs/guides/comparison.md) names current gaps** — TSX authoring, a first-class test client, automatic image/font optimization, i18n — with how to bridge each today.\n\n## 0.7.0\n\n- **Fix: `error.pyxl` renders even when an ancestor layout has a `@server` loader.** Boundary renders now run ancestor layout loaders like a normal page instead of silently falling back to the built-in error document.\n- **Pre-release fixes.** `PYXLE_SSR_WORKER_CONCURRENCY` reaches the worker again, `SIGTERM` to `pyxle dev` tears down the whole child tree, a failed rebuild broadcasts to the overlay, and reverting to last-good content triggers the recovery rebuild.\n- **Fix: CommonJS React libraries no longer crash SSR.** The SSR bundler resolves dependencies ESM-first (like Vite), so packages without an `exports` map (e.g. `lucide-react`) link cleanly; a genuinely CJS-only package now fails with an actionable error. [Third-party packages](https://pyxle.dev/docs/guides/third-party-packages.md#commonjs-packages-and-ssr).\n- **Docs: [the road to a fully-typed Pyxle](https://pyxle.dev/docs/guides/fully-typed-pyxle.md)** — where the type story is heading (TSX authoring, Python types across the boundary), grounded in what works today.\n- **Breaking: Node.js 20.19+ is now required** (Vite 7's floor; Node 18 is EOL). [Installation](https://pyxle.dev/docs/getting-started/installation.md).\n- **Modernized scaffold — React 19, Vite 7, and an interactive `pyxle init`.** Arrow-key prompts for Tailwind, shadcn/ui, and the import alias, with `--yes`/explicit flags for non-interactive use. [Quick Start](https://pyxle.dev/docs/getting-started/quick-start.md).\n- **Tailwind is now opt-in — Tailwind v4 wired into Vite when chosen.** No config files or standalone watcher; decline it and plain CSS / CSS Modules work out of the box. [Styling](https://pyxle.dev/docs/guides/styling.md).\n- **shadcn/ui support** — choose it at `pyxle init` and `npx shadcn@latest add …` works with no `shadcn init`; the `@` alias resolves in the client build and SSR. [Third-party packages](https://pyxle.dev/docs/guides/third-party-packages.md#shadcnui).\n- **Fix: streaming SSR no longer serializes across requests.** An SSR worker now renders many requests concurrently (isolated per-request with `AsyncLocalStorage`), and `pyxle serve` auto-sizes its worker pool. [Streaming](https://pyxle.dev/docs/guides/streaming.md#concurrent-streams-dont-queue).\n- **`pyxle init` renders the framework pin from the running version** instead of a stale `>=0.4.1` that downgraded fresh projects.\n- **`pyxle typecheck` fails fast when TypeScript isn't installed**, with an actionable message instead of npm's placeholder `tsc`. [TypeScript](https://pyxle.dev/docs/guides/typescript.md).\n- **Scaffolded `AGENTS.md` corrected** — `LoaderError` (like `server`/`action`/`ActionError`/…) is compiler-injected, not imported.\n- **`pyxle check` works out of the box — `pyxle-langkit` is now a default dependency**, so JSX checking passes on a fresh scaffold with no extra step.\n- **Fix: the CSRF cookie no longer collides between apps on one host.** The default name is namespaced by bind port (`pyxle-csrf-8000`) and injected into the page shell. [Security → CSRF](https://pyxle.dev/docs/guides/security.md#csrf-protection).\n- **Fix: multipart forms (file uploads) now pass CSRF with a `_csrf_token` field.** The middleware stream-parses just far enough to read the token (capped at 1 MiB) and replays the body untouched. [Security → Form bodies and uploads](https://pyxle.dev/docs/guides/security.md#form-bodies-and-uploads).\n- **`pyxle dev` output is clean by default, `--verbose` for the firehose** — a curated startup summary and one-line rebuild notices instead of Vite's raw stdout. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-dev).\n- **Server-side logs stream to the browser console in `pyxle dev`**, prefixed `[pyxle:server]`; dev-only and bounded. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-dev).\n- **`public/` changes are picked up on refresh instead of triggering a rebuild (matching Next.js)** — assets serve live from disk, and a newly added or removed file refreshes the static index. [Architecture → the watcher](https://pyxle.dev/docs/architecture/dev-server.md#the-watcher).\n- **Watch extra directories with `dev.watch`, ignore paths with `dev.ignore`.** A shared module outside `pages/` can now trigger hot reload; `dev.ignore` is additive to the built-in ignores. [Configuration → Development](https://pyxle.dev/docs/reference/configuration.md#development).\n\n### Documentation\n\n- **Fixed the flagship [WebSockets](https://pyxle.dev/docs/guides/websockets.md) example** — it derived the socket path from `window` during SSR and 500'd; it now builds the path from loader data.\n- **More doc fixes** — a broken `@action` example in the [pyxle-db docs](https://pyxle.dev/docs/plugins/pyxle-db.md) (`await request.json()`), documented CSRF on the pyxle-auth endpoints and where pyxle-auth accounts live, an honest [`pyxle check`](https://pyxle.dev/docs/reference/cli.md#pyxle-check) scope note, and prerequisites up front in the [Introduction](https://pyxle.dev/docs/getting-started/introduction.md).\n- **`Accept: text/markdown` negotiation now follows RFC 9110** (q-values honoured, exact type match); new `markdown_is_acceptable(accept)` helper. [AI accessibility](https://pyxle.dev/docs/guides/llms.md#negotiation-rules).\n- **`/llms.txt` now emits absolute URLs and links `.md` only where Markdown actually resolves.** [AI accessibility](https://pyxle.dev/docs/guides/llms.md#the-llmstxt-index).\n- **Breaking: converted Markdown rewrites internal links to `.md`** — `html_to_markdown()` rewrites by default (`rewrite_links=False` for the old behavior). [AI accessibility](https://pyxle.dev/docs/guides/llms.md#autoconvert-the-lossy-fallback).\n- **Fix: a burst of rapid saves can no longer kill the dev server** — builds are serialized, `meta.json` writes atomically, and the Vite subprocess is supervised with bounded backoff.\n- **Fix: reading an unprovided `request.state.<name>`** (e.g. `request.state.db` without pyxle-db) now gives a structured, guided error instead of a bare `AttributeError`.\n- **Actionable SSR error when a component touches a browser global** (`window`, `document`, …) — dev names your `.pyxl` file and the fix (`useEffect`/`<ClientOnly>`); production stays generic. [Client Components](https://pyxle.dev/docs/guides/client-components.md).\n\n## 0.6.1\n\nA sharper `pyxle check` — the edit → check → fix loop now catches classes of mistake it used to wave through.\n\n- **`pyxle check` gained a semantic layer** — pyflakes over the Python section flags undefined names, unused imports, and redefinitions (compiler-injected names are recognized).\n- **Duplicate `export default` is now caught at check time**, at the real source line, instead of failing later in the build.\n- **JSX error lines are now accurate**, and Babel's misleading \"unterminated regex\" carries a plain-language hint about the real cause.\n- **`LoaderError` and `invalidate_routes` are now auto-injected**, matching `ActionError`/`ValidationActionError`. [Runtime API](https://pyxle.dev/docs/reference/runtime-api.md).\n- **`pyxle install --break-system-packages`** for externally-managed (PEP 668) environments. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-install).\n\n## 0.6.0\n\n- **AI accessibility — serve your app as Markdown, plus `llms.txt`.** Opt in with `\"llms\": true` and every page gains a `.md` rendition (and `Accept: text/markdown` support), an `/llms.txt` index, and discovery headers; Markdown resolves from a co-located `<page>.md`, a `to_markdown` handler, or an ancestor `llms.py`, with an `autoConvert` HTML→Markdown fallback. Off by default, and adds nothing to the page hot path. [AI accessibility](https://pyxle.dev/docs/guides/llms.md).\n\n## 0.5.0\n\nThe depth release: caching/SSG/ISR, streaming SSR, realtime (WebSockets + a cross-worker Redis broker), Pydantic-validated actions, observability, background work, image optimization, and multi-worker serving — built, documented, and dogfooded on pyxle.dev. The two behavior changes below are called out explicitly.\n\n- **Cross-worker realtime — a Redis pub/sub broker.** WebSocket channels span worker processes and machines with `PYXLE_REALTIME_BROKER=redis`; the in-process broker stays the default. No code change. [WebSockets](https://pyxle.dev/docs/guides/websockets.md#cross-worker-realtime-with-redis).\n- **Fix: streaming SSR now survives production gzip.** A streaming-aware `StreamingGZipMiddleware` flushes the compressor per chunk so the shell reaches the browser first. [Streaming](https://pyxle.dev/docs/guides/streaming.md#streaming-survives-gzip-in-production).\n- **Fix: dynamic pages are no longer client-nav-cached with stale data.** The navigation-cache TTL now mirrors server cacheability, so a dynamic page always refetches on back/forward. [Caching](https://pyxle.dev/docs/guides/caching.md#client-navigation-cache).\n- **Fix: `pyxle build --static` pre-renders pages whose loaders use a plugin.** The static builder stands up the same plugin context a request sees, so a DB-backed loader runs at build time. [Caching](https://pyxle.dev/docs/guides/caching.md#static-pre-rendering-pyxle-build-static).\n- **Changed (behavior): stricter nested-config validation.** The `cors`/`csrf`/`observability`/… blocks now reject unknown keys at boot, so a typo'd security key fails loudly instead of silently no-opping. [Configuration](https://pyxle.dev/docs/reference/configuration.md).\n- **Fix: `error.pyxl` no longer leaks internal error details in production** — the boundary gets a generic message and sanitized type; author-raised `LoaderError`/`ActionError` messages still pass through. [Error Handling](https://pyxle.dev/docs/guides/error-handling.md).\n- **Fix: `import.meta.env.PYXLE_PUBLIC_*` is now substituted during SSR**, so a public env var no longer causes a hydration mismatch. [Environment variables](https://pyxle.dev/docs/guides/environment-variables.md).\n- **Fix: scaffold `.gitignore` no longer ignores `.env`**, matching the env-vars doc.\n- **Fix: `<Image>` emits a lowercase `fetchpriority` attribute** (React 18.3.1 rejected the camelCase form).\n- **Fix: production gzip no longer prints `I/O operation on closed file`** — the compressor closes deterministically on every path.\n- **Fix: scaffolded `jsconfig.json` drops the deprecated `baseUrl`** in favor of tsconfig-relative `paths`.\n- **Fix: `pyxle typecheck` works on current TypeScript** — `\"bundler\"` resolution, no `baseUrl`.\n- **Startup warning when a `BaseHTTPMiddleware` is paired with streaming routes** (it buffers responses, breaking streaming SSR). [Middleware](https://pyxle.dev/docs/guides/middleware.md).\n- **Clear compile-time error for TypeScript syntax in a client block** (it's plain JSX), pointing at your `.pyxl` source line. [TypeScript](https://pyxle.dev/docs/guides/typescript.md).\n- **New guides: [TypeScript](https://pyxle.dev/docs/guides/typescript.md) and [Migrating from Flask or Django](https://pyxle.dev/docs/guides/migration-from-flask-django.md).**\n- **`error.pyxl` is now a client-side error boundary too** — a render fault after hydration renders the nearest boundary instead of a blank screen, with the same `error` prop on both sides. [Error Handling](https://pyxle.dev/docs/guides/error-handling.md#client-side-errors).\n- **Built-in rate limiting — `pyxle.middleware.RateLimitMiddleware`.** A dependency-free token-bucket limiter configured from `pyxle.config.json`; per-process, so rate-limit at the proxy for one global cap. Off by default. [Middleware](https://pyxle.dev/docs/guides/middleware.md#rate-limiting).\n- **Route policies now apply to `@action` endpoints** via `routeMiddleware.actions`, closing a bypass where an auth policy wrapped pages but not actions. [Middleware](https://pyxle.dev/docs/guides/middleware.md#route-level-hooks).\n- **`pyxle serve --workers 0` auto-detects the core count.** The [Deployment guide](https://pyxle.dev/docs/guides/deployment.md#multi-core-worker-processes) adds a per-worker-state table and rolling-deploy guidance.\n- **Build optimization: responsive `<Image>`, modulepreload hints, and `--analyze`.** `<Image>` emits a responsive `srcset` via a `loader` and gains `fill`/`sizes`/`priority`; the SSR shell preloads entry chunks; `pyxle build --analyze` reports bundle sizes. [Build Optimization](https://pyxle.dev/docs/guides/build-optimization.md).\n- **Background tasks & deferred work.** `request.state.background.add_task(...)` (or a `{\"background\": [...]}` return) runs after the response; `pyxle.tasks.enqueue(...)` schedules fire-and-forget work on an in-process pool (per-process — hand off to Celery/ARQ/Dramatiq for durability). [Background Tasks](https://pyxle.dev/docs/guides/background-tasks.md).\n- **OpenTelemetry tracing (opt-in).** Request/SSR/loader/action spans via the `[observability-otel]` extra; fully off and zero-cost by default. [Observability](https://pyxle.dev/docs/guides/observability.md#opentelemetry-tracing).\n- **`pyxle dev --dashboard` — a live terminal observability panel** (throughput, error rate, latency, cache hit ratio); dependency-free and dev-only. [Observability](https://pyxle.dev/docs/guides/observability.md#dev-dashboard).\n- **Structured access logging** — one line per request (`method`/`path`/`status`/`duration_ms`/correlation id) in console or JSON via `observability.accessLog`. [Observability](https://pyxle.dev/docs/guides/observability.md#structured-logging).\n- **Observability: request IDs, timing, metrics, and richer health probes.** Every request gets a correlation id (`X-Request-Id`) and timing; opt-in Prometheus metrics; `/readyz` runs dependency checks. Metrics are per-worker. [Observability](https://pyxle.dev/docs/guides/observability.md).\n- **Typed `@action` request validation with Pydantic.** Annotate a `body: Model` parameter and Pyxle validates before the action runs, returning `422` with a `fields` map on failure; `pyxle openapi` generates an OpenAPI 3.1 document from your models. Optional `[pydantic]` extra. [Server Actions](https://pyxle.dev/docs/core-concepts/server-actions.md#validating-request-bodies-with-pydantic).\n- **Fix: a server module that fails to import is no longer cached as a broken empty module** — the real error re-raises on each request.\n- **WebSockets — page handlers, a client hook, and pub/sub.** A page can export `async def websocket(ws)`; `pyxle.realtime` adds `channel`/`room.publish`, WS auth/origin helpers, and a `useWebSocket()` hook. The in-process broker is per-worker (a Redis broker drops in). [WebSockets](https://pyxle.dev/docs/guides/websockets.md).\n- **Streaming SSR for `<Suspense>` pages.** The shell flushes immediately and each boundary streams in as it resolves; opt-in, zero-config, dynamic pages only. [Streaming](https://pyxle.dev/docs/guides/streaming.md).\n- **`loading.pyxl` route-level loading states** wrap a route in `<Suspense>`, streamed as the shell and applied identically on the client. [Streaming](https://pyxle.dev/docs/guides/streaming.md#route-level-loading-states-with-loadingpyxl).\n- **Server-side page caching with incremental regeneration.** Return `{\"data\", \"revalidate\": N}` (or a `CACHE` directive) to cache rendered HTML; `pyxle build --static` warms it; stale-while-revalidate, strong `ETag`, and `cache.invalidate(...)`. In-memory/disk/Redis backends. [Caching](https://pyxle.dev/docs/guides/caching.md).\n\n## 0.4.5\n\n- **Signed cookies & tokens — `sign_cookie` / `verify_cookie`.** Stdlib-only helpers that attach a tamper-proof HMAC-SHA256 signature to any string (session id, unsubscribe link, reset token) and verify it in constant time; a `salt=` namespaces signatures, and signing without a secret fails closed. [Security](https://pyxle.dev/docs/guides/security.md#signed-cookies-and-tokens).\n- **Fix: `PYXLE_PUBLIC_*` client env vars now work in `pyxle dev` and no longer break `pyxle build`** — values are emitted as quoted JS string literals, so a non-identifier value (API URL, Turnstile key) resolves in both. [Environment variables](https://pyxle.dev/docs/guides/environment-variables.md).\n- **Fix: web fonts and other CSS `url()` assets no longer 404 in `pyxle dev`** — Pyxle sets Vite's `server.origin` so dev assets load from Vite directly.\n\n## 0.4.4\n\n- **Fix: cross-page hash links scroll to their anchor.** Client-side navigation to `/page#section` now jumps to the top and scrolls to the anchor once the next page commits, matching native behaviour.\n\n## 0.4.3\n\n- **Security: hardened HEAD sanitisation (XSS).** Dynamic `HEAD` values are now parsed and rebuilt from a strict tag allowlist with every attribute HTML-escaped, `on*` handlers dropped, dangerous URLs neutralised, and non-head tags rejected — closing an injection via the dynamic-meta-tags recipe. Inline `<script>`/`<style>` stays supported as trusted author code.\n- **Security: `csrf.exemptPaths` match on segment boundaries**, so exempting `/api/webhooks` no longer also exempts `/api/webhooks-admin`.\n- **Security: oversized no-JS form POSTs fail loud** with a `413` (asking for the token via header) instead of being silently truncated.\n- **Fix: `<Script>`/`<Image>` boolean attributes written as strings** (`defer=\"false\"`, `priority=\"0\"`) now coerce correctly instead of to `True`.\n- **Fix: custom `csrf.cookieName`/`headerName` now reach the client runtime** — non-default names are injected into the shell so `useAction`/`<Form>` stop `403`-ing.\n- **Fix: no double loader run on hover-then-click navigation** — the click reuses the in-flight prefetch, and a superseded prefetch is discarded.\n- **Multi-core serving: `pyxle serve --workers N`.** N independent server processes on one port, each with its own SSR pool — throughput scales with cores, no load balancer or shared state. [Deployment](https://pyxle.dev/docs/guides/deployment.md#multi-core-worker-processes).\n- **Sync API endpoints.** A plain `def endpoint(request)` (and sync `HTTPEndpoint` methods) now runs in Starlette's threadpool, so blocking drivers no longer need manual `asyncio.to_thread`. [API Routes](https://pyxle.dev/docs/guides/api-routes.md#sync-endpoints-and-blocking-calls).\n- **In-memory static asset cache.** Small static files (≤1 MB, 32 MB/process) are served from memory with no filesystem I/O; conditional requests and cache headers behave as before.\n\n## 0.4.2\n\n- **Live dev-server reconciliation.** Editing a `.pyxl` now applies route-shape changes without a restart — rename/add/remove a loader or action, add/delete a page, wrap a page in a layout — by hot-swapping the route table; editing `pyxle.config.json` prints a \"restart to apply\" warning.\n- **`pyxle check` works on a clean install** — the JSX checker's parser dependencies are bundled (via `pyxle-langkit`), so `check` runs after `pip install 'pyxle-framework[langkit]'` with no npm setup.\n- **Locale-independent SSR** — the Python↔Node transport pins UTF-8, so non-BMP characters no longer crash rendering under `LANG=C`.\n- **Smoother first run** — `pyxle init` writes a gitignored `.env.local` with a random dev secret, the scaffold `requirements.txt` declares `pyxle-framework`, and `pyxle install` gives PEP 668 guidance.\n- **Docs:** documented calling an `@action` endpoint directly for scripts and tests.\n\n## 0.4.1\n\n- **No more double loader run on first load.** The landing page is seeded into the client navigation cache from the server render, so its prefetch resolves from cache — the loader runs once, not twice (also making back/forward instant).\n- **Per-route navigation-cache TTL.** A route's [`cache`](https://pyxle.dev/docs/reference/configuration.md#edge-caching) TTL now also governs client navigation-cache freshness; routes without one default to 2 minutes, tunable via [`navigation.defaultPrefetchTtl`](https://pyxle.dev/docs/reference/configuration.md#navigation).\n\n## 0.4.0\n\n- **Edge caching.** Declare cacheable routes in [`pyxle.config.json::cache`](https://pyxle.dev/docs/reference/configuration.md#edge-caching) and pages serve `Cache-Control: public, s-maxage=N` (+ `stale-while-revalidate`) so a CDN absorbs traffic; the per-user CSRF cookie is omitted from cacheable responses. [Deployment](https://pyxle.dev/docs/guides/deployment.md#cdn-and-edge-caching).\n- **Hardened production errors.** SSR render failures (including the SPA-navigation JSON path) are sanitized in the response and logged in full for operators.\n- **Faster static serving.** The static-asset middleware indexes paths up front, skipping a per-request `stat` on every dynamic request.\n- **Layout & template loaders.** A `layout.pyxl`/`template.pyxl` can declare its own `@server` loader, so shared UI loads once per request without repeating the loader in every page. [Layouts](https://pyxle.dev/docs/core-concepts/layouts.md#layout-data-loaders).\n\n## 0.3.0\n\n- **First-class plugin system.** Compose apps via `pyxle.config.json::plugins` (Django-style `INSTALLED_APPS`). [Plugins guide](https://pyxle.dev/docs/guides/plugins.md), [Plugins API](https://pyxle.dev/docs/reference/plugins-api.md).\n- **Django-style service access.** Resolve any plugin service with `plugin(\"auth.service\")` or a typed shortcut (e.g. `from pyxle_auth import get_auth_service`).\n- **First-party plugins.** [`pyxle-db`](https://pyxle.dev/docs/plugins/pyxle-db.md) (SQLite-first with migrations) and [`pyxle-auth`](https://pyxle.dev/docs/plugins/pyxle-auth.md) (email+password sessions, argon2id, rate limits).\n- **WebSocket endpoints** — `pages/api/*.py` can export `async def websocket(ws)`. [API Routes](https://pyxle.dev/docs/guides/api-routes.md#websocket-endpoints).\n- **Client navigation cache with TTL + invalidation.** Loader payloads are cached (30s default) for instant back/forward; call [`invalidate(url)`](https://pyxle.dev/docs/reference/client-api.md#invalidateurl) or return [`invalidate_routes(...)`](https://pyxle.dev/docs/reference/runtime-api.md#invalidate_routesresponse-urls) from an action to keep lists fresh.\n- **`ActionError` is auto-imported** for any `.pyxl` with an `@action`.\n- **`<Head>` coerces multi-part `<title>` children** into a single string, silencing React's array-title warning.\n- **SSR worker pins `LANG=en-US.UTF-8`** (override with `PYXLE_SSR_LOCALE`) to stop `Intl` hydration mismatches.\n- **Vite resolver prefers pinned versions** — `pyxle build` runs `npm install` before falling back to `npx --yes vite`.\n","prev":{"title":"Frequently Asked Questions","path":"faq"}}
\ No newline at end of file
+{"title":"Changelog","description":"Release notes for Pyxle. While we're in beta (`0.x`), minor versions may include breaking changes — those are called out explicitly. To upgrade, run `pip install --upgrade pyxle-framework`.","html":"<p>Release notes for Pyxle. While we&#39;re in beta (<code>0.x</code>), minor versions may include breaking changes — those are called out explicitly. To upgrade, run <code>pip install --upgrade pyxle-framework</code>.</p>\n<h2 id=\"080\">0.8.0</h2><ul>\n<li><strong>Pyxle Studio — a dashboard built into <code>pyxle dev</code>.</strong> Served at <code>/__pyxle/studio</code>: every route with its loader, actions, cache posture, and boundaries; an interactive tester (loaders run in-process, actions go through their real endpoint — CSRF, validation, and auth hooks included); a live request feed; latency metrics; the effective config (secrets redacted); and in-browser <code>pyxle check</code>. Dev-only by construction, with a <code>Host</code>-header allowlist. <a href=\"/docs/guides/studio\">Pyxle Studio</a>.</li>\n<li><strong>New <code>pyxle studio</code> command.</strong> Runs the dev server and opens the browser on the dashboard, enabling it for that run even when the config opts out. <a href=\"/docs/reference/cli#pyxle-studio\">CLI</a>.</li>\n<li><strong>Breakpoint debugging directly in <code>.pyxl</code> files.</strong> Set a breakpoint on a line inside a <code>@server</code> loader <em>and</em> on a line inside the JSX below it — both bind. Compiled server modules are remapped to their <code>.pyxl</code> sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. <a href=\"/docs/guides/debugging\">Debugging</a>.</li>\n<li><strong>One-key debugging from VS Code.</strong> Pyxle Language Tools 0.3.0 contributes a <code>pyxle</code> debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate &quot;Debug Pyxle app (React browser)&quot; configuration debugs the React side in a standalone browser session. Plus a &quot;Pyxle: Open Studio&quot; command. Install it with <code>code --install-extension pyxle.pyxle-language-tools</code>. <a href=\"/docs/guides/debugging#quick-start-breakpoints-in-a-pyxl-file\">Debugging</a>.</li>\n<li><strong><code>pyxle dev --inspect</code> for attach-style debugging.</strong> Hosts a debugpy server bound to <code>127.0.0.1</code> so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes <code>.pyxle-build/dev-server.json</code> (ports, debugpy endpoint) for editor tooling and removes it on shutdown. <a href=\"/docs/guides/debugging\">Debugging</a>.</li>\n<li><strong>Dev tracebacks now point at <code>.pyxl</code> sources.</strong> A loader/action error names your <code>.pyxl</code> file and line instead of the compiled module under <code>.pyxle-build/</code>. <a href=\"/docs/guides/debugging\">Debugging</a>.</li>\n<li><strong>Breaking: <code>/__pyxle</code> is now a reserved URL namespace.</strong> The dev server&#39;s Vite asset proxy never forwards paths under it, so an app route under <code>/__pyxle</code> no longer resolves in <code>pyxle dev</code> (it still serves in production, where the namespace is unused). Move any such route before upgrading. <a href=\"/docs/guides/studio#the-reserved-__pyxle-namespace\">Pyxle Studio</a>.</li>\n<li><strong>Fixed on Windows: <code>NODE_PATH</code> is built with the platform delimiter.</strong> A project that already set <code>NODE_PATH</code> got a <code>:</code>-joined value, which Node cannot parse on Windows, so neither entry resolved.</li>\n<li><strong>Fixed on Windows: rebuild notifications report POSIX paths.</strong> The dev server&#39;s rebuild event carried host separators, so Studio and the error overlay showed <code>pages\\index.pyxl</code>.</li>\n</ul>\n<h2 id=\"075\">0.7.5</h2><ul>\n<li><strong><code>pyxle dev</code> now persists module-level state across requests, like <code>pyxle serve</code>.</strong> A <code>@server</code>/<code>@action</code> module is imported once and reused between rebuilds, so a module-level counter or in-memory cache no longer resets on every refresh in dev. Saving a file still re-imports it (resetting globals and applying your edits). State stays per-process — use a database or cache for anything shared or durable (<a href=\"/docs/core-concepts/data-loading#loaders-should-be-stateless\">Loaders should be stateless</a>).</li>\n<li><strong><code>pyxle init</code> now requires an explicit target.</strong> A bare <code>pyxle init</code> used to silently scaffold into the current directory; it now errors, pointing to <code>pyxle init my-app</code> (new directory) or <code>pyxle init .</code> (current directory).</li>\n</ul>\n<h2 id=\"074\">0.7.4</h2><ul>\n<li><strong>Fix: <code>pyxle dev</code> no longer hot-reloads in an endless loop on Linux.</strong> After a save, the rebuild&#39;s own file reads surfaced through <code>inotify</code> as events the watcher mistook for edits, re-triggering the rebuild forever (macOS <code>FSEvents</code> doesn&#39;t report reads, so it was Linux-only). The watcher now reacts only to genuine change events, not read-only opens.</li>\n</ul>\n<h2 id=\"073\">0.7.3</h2><ul>\n<li><strong>Docs: an <code>@action</code>&#39;s awaited result is the flat <code>{ ok, ...yourReturn }</code></strong> — read fields directly (<code>res.title</code>), never <code>res.data.title</code> (a successful result has no <code>.data</code>; <code>useAction().data</code> is a separate hook property). Clarified across the <a href=\"/docs/core-concepts/server-actions\">Server Actions guide</a>, the <a href=\"/docs/reference/client-api\">client API reference</a>, and the scaffold <code>AGENTS.md</code>.</li>\n</ul>\n<h2 id=\"072\">0.7.2</h2><ul>\n<li><strong>Fix: <code>pyxle init</code> scaffolds an installable <code>requirements.txt</code> again.</strong> The template&#39;s <code>starlette</code> pin conflicted with the framework&#39;s after 0.7.1&#39;s security bump; both now use <code>starlette&gt;=1.3.1,&lt;2.0</code>.</li>\n<li><strong>Config: a boolean <code>port</code> is now rejected instead of binding port 1.</strong> <code>bool</code> being an <code>int</code> subclass slipped past the validator; it now raises a clear <code>ConfigError</code>.</li>\n</ul>\n<h2 id=\"071\">0.7.1</h2><ul>\n<li><strong>Security: require Starlette ≥ 1.3.1</strong>, fixing a <code>Host</code>-header auth bypass (PYSEC-2026-161), form-parsing DoS (PYSEC-2026-249, -1943), and a Windows <code>StaticFiles</code> SSRF (CVE-2026-48818). Pyxle&#39;s own API is unchanged; a new <code>pip-audit</code> CI job guards dependencies.</li>\n<li><strong><code>pyxle serve</code> refuses to start in production without <code>PYXLE_SECRET_KEY</code></strong> — previously only a warning, leaving CSRF tokens and signed cookies forgeable. <a href=\"/docs/guides/security\">Security</a>, <a href=\"/docs/guides/deployment\">Deployment</a>.</li>\n<li><strong><code>pyxle dev</code>/<code>build</code> check the Node.js version up front</strong> — a clear &quot;Node.js 20.19+ required&quot; message instead of an opaque Vite crash. <a href=\"/docs/getting-started/installation#troubleshooting\">Installation → Troubleshooting</a>.</li>\n<li><strong>A real testing story: <code>pyxle.testing</code> helpers and a <a href=\"/docs/guides/testing\">Testing guide</a>.</strong> <code>load_loader(&quot;pages/index.pyxl&quot;)</code> / <code>load_page(...)</code> compile a page and hand back its loader/module for unit tests.</li>\n<li><strong>New <a href=\"/docs/guides/debugging\">Debugging guide</a> and Deployment fixes</strong> — Node 22 in the sample Dockerfile, the real metrics path (<code>/api/__pyxle/metrics</code>), a migrations section, and a blue-green CSRF gotcha.</li>\n<li><strong>Security docs now match what Pyxle sends</strong> — it already sets <code>X-Content-Type-Options</code>/<code>X-Frame-Options</code>/<code>Referrer-Policy</code>, so the guide covers only CSP and HSTS; a <a href=\"https://github.com/pyxle-dev/pyxle/blob/main/SECURITY.md\" target=\"_blank\" rel=\"noreferrer\">SECURITY.md</a> is published for every repo.</li>\n<li><strong>A fresh project now ships a human <code>README.md</code></strong> alongside the AI-oriented <code>AGENTS.md</code>.</li>\n<li><strong>The <a href=\"/docs/guides/comparison\">comparison guide</a> names current gaps</strong> — TSX authoring, a first-class test client, automatic image/font optimization, i18n — with how to bridge each today.</li>\n</ul>\n<h2 id=\"070\">0.7.0</h2><ul>\n<li><strong>Fix: <code>error.pyxl</code> renders even when an ancestor layout has a <code>@server</code> loader.</strong> Boundary renders now run ancestor layout loaders like a normal page instead of silently falling back to the built-in error document.</li>\n<li><strong>Pre-release fixes.</strong> <code>PYXLE_SSR_WORKER_CONCURRENCY</code> reaches the worker again, <code>SIGTERM</code> to <code>pyxle dev</code> tears down the whole child tree, a failed rebuild broadcasts to the overlay, and reverting to last-good content triggers the recovery rebuild.</li>\n<li><strong>Fix: CommonJS React libraries no longer crash SSR.</strong> The SSR bundler resolves dependencies ESM-first (like Vite), so packages without an <code>exports</code> map (e.g. <code>lucide-react</code>) link cleanly; a genuinely CJS-only package now fails with an actionable error. <a href=\"/docs/guides/third-party-packages#commonjs-packages-and-ssr\">Third-party packages</a>.</li>\n<li><strong>Docs: <a href=\"/docs/guides/fully-typed-pyxle\">the road to a fully-typed Pyxle</a></strong> — where the type story is heading (TSX authoring, Python types across the boundary), grounded in what works today.</li>\n<li><strong>Breaking: Node.js 20.19+ is now required</strong> (Vite 7&#39;s floor; Node 18 is EOL). <a href=\"/docs/getting-started/installation\">Installation</a>.</li>\n<li><strong>Modernized scaffold — React 19, Vite 7, and an interactive <code>pyxle init</code>.</strong> Arrow-key prompts for Tailwind, shadcn/ui, and the import alias, with <code>--yes</code>/explicit flags for non-interactive use. <a href=\"/docs/getting-started/quick-start\">Quick Start</a>.</li>\n<li><strong>Tailwind is now opt-in — Tailwind v4 wired into Vite when chosen.</strong> No config files or standalone watcher; decline it and plain CSS / CSS Modules work out of the box. <a href=\"/docs/guides/styling\">Styling</a>.</li>\n<li><strong>shadcn/ui support</strong> — choose it at <code>pyxle init</code> and <code>npx shadcn@latest add …</code> works with no <code>shadcn init</code>; the <code>@</code> alias resolves in the client build and SSR. <a href=\"/docs/guides/third-party-packages#shadcnui\">Third-party packages</a>.</li>\n<li><strong>Fix: streaming SSR no longer serializes across requests.</strong> An SSR worker now renders many requests concurrently (isolated per-request with <code>AsyncLocalStorage</code>), and <code>pyxle serve</code> auto-sizes its worker pool. <a href=\"/docs/guides/streaming#concurrent-streams-dont-queue\">Streaming</a>.</li>\n<li><strong><code>pyxle init</code> renders the framework pin from the running version</strong> instead of a stale <code>&gt;=0.4.1</code> that downgraded fresh projects.</li>\n<li><strong><code>pyxle typecheck</code> fails fast when TypeScript isn&#39;t installed</strong>, with an actionable message instead of npm&#39;s placeholder <code>tsc</code>. <a href=\"/docs/guides/typescript\">TypeScript</a>.</li>\n<li><strong>Scaffolded <code>AGENTS.md</code> corrected</strong> — <code>LoaderError</code> (like <code>server</code>/<code>action</code>/<code>ActionError</code>/…) is compiler-injected, not imported.</li>\n<li><strong><code>pyxle check</code> works out of the box — <code>pyxle-langkit</code> is now a default dependency</strong>, so JSX checking passes on a fresh scaffold with no extra step.</li>\n<li><strong>Fix: the CSRF cookie no longer collides between apps on one host.</strong> The default name is namespaced by bind port (<code>pyxle-csrf-8000</code>) and injected into the page shell. <a href=\"/docs/guides/security#csrf-protection\">Security → CSRF</a>.</li>\n<li><strong>Fix: multipart forms (file uploads) now pass CSRF with a <code>_csrf_token</code> field.</strong> The middleware stream-parses just far enough to read the token (capped at 1 MiB) and replays the body untouched. <a href=\"/docs/guides/security#form-bodies-and-uploads\">Security → Form bodies and uploads</a>.</li>\n<li><strong><code>pyxle dev</code> output is clean by default, <code>--verbose</code> for the firehose</strong> — a curated startup summary and one-line rebuild notices instead of Vite&#39;s raw stdout. <a href=\"/docs/reference/cli#pyxle-dev\">CLI</a>.</li>\n<li><strong>Server-side logs stream to the browser console in <code>pyxle dev</code></strong>, prefixed <code>[pyxle:server]</code>; dev-only and bounded. <a href=\"/docs/reference/cli#pyxle-dev\">CLI</a>.</li>\n<li><strong><code>public/</code> changes are picked up on refresh instead of triggering a rebuild (matching Next.js)</strong> — assets serve live from disk, and a newly added or removed file refreshes the static index. <a href=\"/docs/architecture/dev-server#the-watcher\">Architecture → the watcher</a>.</li>\n<li><strong>Watch extra directories with <code>dev.watch</code>, ignore paths with <code>dev.ignore</code>.</strong> A shared module outside <code>pages/</code> can now trigger hot reload; <code>dev.ignore</code> is additive to the built-in ignores. <a href=\"/docs/reference/configuration#development\">Configuration → Development</a>.</li>\n</ul>\n<h3 id=\"documentation\">Documentation</h3><ul>\n<li><strong>Fixed the flagship <a href=\"/docs/guides/websockets\">WebSockets</a> example</strong> — it derived the socket path from <code>window</code> during SSR and 500&#39;d; it now builds the path from loader data.</li>\n<li><strong>More doc fixes</strong> — a broken <code>@action</code> example in the <a href=\"/docs/plugins/pyxle-db\">pyxle-db docs</a> (<code>await request.json()</code>), documented CSRF on the pyxle-auth endpoints and where pyxle-auth accounts live, an honest <a href=\"/docs/reference/cli#pyxle-check\"><code>pyxle check</code></a> scope note, and prerequisites up front in the <a href=\"/docs/getting-started/introduction\">Introduction</a>.</li>\n<li><strong><code>Accept: text/markdown</code> negotiation now follows RFC 9110</strong> (q-values honoured, exact type match); new <code>markdown_is_acceptable(accept)</code> helper. <a href=\"/docs/guides/llms#negotiation-rules\">AI accessibility</a>.</li>\n<li><strong><code>/llms.txt</code> now emits absolute URLs and links <code>.md</code> only where Markdown actually resolves.</strong> <a href=\"/docs/guides/llms#the-llmstxt-index\">AI accessibility</a>.</li>\n<li><strong>Breaking: converted Markdown rewrites internal links to <code>.md</code></strong> — <code>html_to_markdown()</code> rewrites by default (<code>rewrite_links=False</code> for the old behavior). <a href=\"/docs/guides/llms#autoconvert-the-lossy-fallback\">AI accessibility</a>.</li>\n<li><strong>Fix: a burst of rapid saves can no longer kill the dev server</strong> — builds are serialized, <code>meta.json</code> writes atomically, and the Vite subprocess is supervised with bounded backoff.</li>\n<li><strong>Fix: reading an unprovided <code>request.state.&lt;name&gt;</code></strong> (e.g. <code>request.state.db</code> without pyxle-db) now gives a structured, guided error instead of a bare <code>AttributeError</code>.</li>\n<li><strong>Actionable SSR error when a component touches a browser global</strong> (<code>window</code>, <code>document</code>, …) — dev names your <code>.pyxl</code> file and the fix (<code>useEffect</code>/<code>&lt;ClientOnly&gt;</code>); production stays generic. <a href=\"/docs/guides/client-components\">Client Components</a>.</li>\n</ul>\n<h2 id=\"061\">0.6.1</h2><p>A sharper <code>pyxle check</code> — the edit → check → fix loop now catches classes of mistake it used to wave through.</p>\n<ul>\n<li><strong><code>pyxle check</code> gained a semantic layer</strong> — pyflakes over the Python section flags undefined names, unused imports, and redefinitions (compiler-injected names are recognized).</li>\n<li><strong>Duplicate <code>export default</code> is now caught at check time</strong>, at the real source line, instead of failing later in the build.</li>\n<li><strong>JSX error lines are now accurate</strong>, and Babel&#39;s misleading &quot;unterminated regex&quot; carries a plain-language hint about the real cause.</li>\n<li><strong><code>LoaderError</code> and <code>invalidate_routes</code> are now auto-injected</strong>, matching <code>ActionError</code>/<code>ValidationActionError</code>. <a href=\"/docs/reference/runtime-api\">Runtime API</a>.</li>\n<li><strong><code>pyxle install --break-system-packages</code></strong> for externally-managed (PEP 668) environments. <a href=\"/docs/reference/cli#pyxle-install\">CLI</a>.</li>\n</ul>\n<h2 id=\"060\">0.6.0</h2><ul>\n<li><strong>AI accessibility — serve your app as Markdown, plus <code>llms.txt</code>.</strong> Opt in with <code>&quot;llms&quot;: true</code> and every page gains a <code>.md</code> rendition (and <code>Accept: text/markdown</code> support), an <code>/llms.txt</code> index, and discovery headers; Markdown resolves from a co-located <code>&lt;page&gt;.md</code>, a <code>to_markdown</code> handler, or an ancestor <code>llms.py</code>, with an <code>autoConvert</code> HTML→Markdown fallback. Off by default, and adds nothing to the page hot path. <a href=\"/docs/guides/llms\">AI accessibility</a>.</li>\n</ul>\n<h2 id=\"050\">0.5.0</h2><p>The depth release: caching/SSG/ISR, streaming SSR, realtime (WebSockets + a cross-worker Redis broker), Pydantic-validated actions, observability, background work, image optimization, and multi-worker serving — built, documented, and dogfooded on pyxle.dev. The two behavior changes below are called out explicitly.</p>\n<ul>\n<li><strong>Cross-worker realtime — a Redis pub/sub broker.</strong> WebSocket channels span worker processes and machines with <code>PYXLE_REALTIME_BROKER=redis</code>; the in-process broker stays the default. No code change. <a href=\"/docs/guides/websockets#cross-worker-realtime-with-redis\">WebSockets</a>.</li>\n<li><strong>Fix: streaming SSR now survives production gzip.</strong> A streaming-aware <code>StreamingGZipMiddleware</code> flushes the compressor per chunk so the shell reaches the browser first. <a href=\"/docs/guides/streaming#streaming-survives-gzip-in-production\">Streaming</a>.</li>\n<li><strong>Fix: dynamic pages are no longer client-nav-cached with stale data.</strong> The navigation-cache TTL now mirrors server cacheability, so a dynamic page always refetches on back/forward. <a href=\"/docs/guides/caching#client-navigation-cache\">Caching</a>.</li>\n<li><strong>Fix: <code>pyxle build --static</code> pre-renders pages whose loaders use a plugin.</strong> The static builder stands up the same plugin context a request sees, so a DB-backed loader runs at build time. <a href=\"/docs/guides/caching#static-pre-rendering-pyxle-build-static\">Caching</a>.</li>\n<li><strong>Changed (behavior): stricter nested-config validation.</strong> The <code>cors</code>/<code>csrf</code>/<code>observability</code>/… blocks now reject unknown keys at boot, so a typo&#39;d security key fails loudly instead of silently no-opping. <a href=\"/docs/reference/configuration\">Configuration</a>.</li>\n<li><strong>Fix: <code>error.pyxl</code> no longer leaks internal error details in production</strong> — the boundary gets a generic message and sanitized type; author-raised <code>LoaderError</code>/<code>ActionError</code> messages still pass through. <a href=\"/docs/guides/error-handling\">Error Handling</a>.</li>\n<li><strong>Fix: <code>import.meta.env.PYXLE_PUBLIC_*</code> is now substituted during SSR</strong>, so a public env var no longer causes a hydration mismatch. <a href=\"/docs/guides/environment-variables\">Environment variables</a>.</li>\n<li><strong>Fix: scaffold <code>.gitignore</code> no longer ignores <code>.env</code></strong>, matching the env-vars doc.</li>\n<li><strong>Fix: <code>&lt;Image&gt;</code> emits a lowercase <code>fetchpriority</code> attribute</strong> (React 18.3.1 rejected the camelCase form).</li>\n<li><strong>Fix: production gzip no longer prints <code>I/O operation on closed file</code></strong> — the compressor closes deterministically on every path.</li>\n<li><strong>Fix: scaffolded <code>jsconfig.json</code> drops the deprecated <code>baseUrl</code></strong> in favor of tsconfig-relative <code>paths</code>.</li>\n<li><strong>Fix: <code>pyxle typecheck</code> works on current TypeScript</strong> — <code>&quot;bundler&quot;</code> resolution, no <code>baseUrl</code>.</li>\n<li><strong>Startup warning when a <code>BaseHTTPMiddleware</code> is paired with streaming routes</strong> (it buffers responses, breaking streaming SSR). <a href=\"/docs/guides/middleware\">Middleware</a>.</li>\n<li><strong>Clear compile-time error for TypeScript syntax in a client block</strong> (it&#39;s plain JSX), pointing at your <code>.pyxl</code> source line. <a href=\"/docs/guides/typescript\">TypeScript</a>.</li>\n<li><strong>New guides: <a href=\"/docs/guides/typescript\">TypeScript</a> and <a href=\"/docs/guides/migration-from-flask-django\">Migrating from Flask or Django</a>.</strong></li>\n<li><strong><code>error.pyxl</code> is now a client-side error boundary too</strong> — a render fault after hydration renders the nearest boundary instead of a blank screen, with the same <code>error</code> prop on both sides. <a href=\"/docs/guides/error-handling#client-side-errors\">Error Handling</a>.</li>\n<li><strong>Built-in rate limiting — <code>pyxle.middleware.RateLimitMiddleware</code>.</strong> A dependency-free token-bucket limiter configured from <code>pyxle.config.json</code>; per-process, so rate-limit at the proxy for one global cap. Off by default. <a href=\"/docs/guides/middleware#rate-limiting\">Middleware</a>.</li>\n<li><strong>Route policies now apply to <code>@action</code> endpoints</strong> via <code>routeMiddleware.actions</code>, closing a bypass where an auth policy wrapped pages but not actions. <a href=\"/docs/guides/middleware#route-level-hooks\">Middleware</a>.</li>\n<li><strong><code>pyxle serve --workers 0</code> auto-detects the core count.</strong> The <a href=\"/docs/guides/deployment#multi-core-worker-processes\">Deployment guide</a> adds a per-worker-state table and rolling-deploy guidance.</li>\n<li><strong>Build optimization: responsive <code>&lt;Image&gt;</code>, modulepreload hints, and <code>--analyze</code>.</strong> <code>&lt;Image&gt;</code> emits a responsive <code>srcset</code> via a <code>loader</code> and gains <code>fill</code>/<code>sizes</code>/<code>priority</code>; the SSR shell preloads entry chunks; <code>pyxle build --analyze</code> reports bundle sizes. <a href=\"/docs/guides/build-optimization\">Build Optimization</a>.</li>\n<li><strong>Background tasks &amp; deferred work.</strong> <code>request.state.background.add_task(...)</code> (or a <code>{&quot;background&quot;: [...]}</code> return) runs after the response; <code>pyxle.tasks.enqueue(...)</code> schedules fire-and-forget work on an in-process pool (per-process — hand off to Celery/ARQ/Dramatiq for durability). <a href=\"/docs/guides/background-tasks\">Background Tasks</a>.</li>\n<li><strong>OpenTelemetry tracing (opt-in).</strong> Request/SSR/loader/action spans via the <code>[observability-otel]</code> extra; fully off and zero-cost by default. <a href=\"/docs/guides/observability#opentelemetry-tracing\">Observability</a>.</li>\n<li><strong><code>pyxle dev --dashboard</code> — a live terminal observability panel</strong> (throughput, error rate, latency, cache hit ratio); dependency-free and dev-only. <a href=\"/docs/guides/observability#dev-dashboard\">Observability</a>.</li>\n<li><strong>Structured access logging</strong> — one line per request (<code>method</code>/<code>path</code>/<code>status</code>/<code>duration_ms</code>/correlation id) in console or JSON via <code>observability.accessLog</code>. <a href=\"/docs/guides/observability#structured-logging\">Observability</a>.</li>\n<li><strong>Observability: request IDs, timing, metrics, and richer health probes.</strong> Every request gets a correlation id (<code>X-Request-Id</code>) and timing; opt-in Prometheus metrics; <code>/readyz</code> runs dependency checks. Metrics are per-worker. <a href=\"/docs/guides/observability\">Observability</a>.</li>\n<li><strong>Typed <code>@action</code> request validation with Pydantic.</strong> Annotate a <code>body: Model</code> parameter and Pyxle validates before the action runs, returning <code>422</code> with a <code>fields</code> map on failure; <code>pyxle openapi</code> generates an OpenAPI 3.1 document from your models. Optional <code>[pydantic]</code> extra. <a href=\"/docs/core-concepts/server-actions#validating-request-bodies-with-pydantic\">Server Actions</a>.</li>\n<li><strong>Fix: a server module that fails to import is no longer cached as a broken empty module</strong> — the real error re-raises on each request.</li>\n<li><strong>WebSockets — page handlers, a client hook, and pub/sub.</strong> A page can export <code>async def websocket(ws)</code>; <code>pyxle.realtime</code> adds <code>channel</code>/<code>room.publish</code>, WS auth/origin helpers, and a <code>useWebSocket()</code> hook. The in-process broker is per-worker (a Redis broker drops in). <a href=\"/docs/guides/websockets\">WebSockets</a>.</li>\n<li><strong>Streaming SSR for <code>&lt;Suspense&gt;</code> pages.</strong> The shell flushes immediately and each boundary streams in as it resolves; opt-in, zero-config, dynamic pages only. <a href=\"/docs/guides/streaming\">Streaming</a>.</li>\n<li><strong><code>loading.pyxl</code> route-level loading states</strong> wrap a route in <code>&lt;Suspense&gt;</code>, streamed as the shell and applied identically on the client. <a href=\"/docs/guides/streaming#route-level-loading-states-with-loadingpyxl\">Streaming</a>.</li>\n<li><strong>Server-side page caching with incremental regeneration.</strong> Return <code>{&quot;data&quot;, &quot;revalidate&quot;: N}</code> (or a <code>CACHE</code> directive) to cache rendered HTML; <code>pyxle build --static</code> warms it; stale-while-revalidate, strong <code>ETag</code>, and <code>cache.invalidate(...)</code>. In-memory/disk/Redis backends. <a href=\"/docs/guides/caching\">Caching</a>.</li>\n</ul>\n<h2 id=\"045\">0.4.5</h2><ul>\n<li><strong>Signed cookies &amp; tokens — <code>sign_cookie</code> / <code>verify_cookie</code>.</strong> Stdlib-only helpers that attach a tamper-proof HMAC-SHA256 signature to any string (session id, unsubscribe link, reset token) and verify it in constant time; a <code>salt=</code> namespaces signatures, and signing without a secret fails closed. <a href=\"/docs/guides/security#signed-cookies-and-tokens\">Security</a>.</li>\n<li><strong>Fix: <code>PYXLE_PUBLIC_*</code> client env vars now work in <code>pyxle dev</code> and no longer break <code>pyxle build</code></strong> — values are emitted as quoted JS string literals, so a non-identifier value (API URL, Turnstile key) resolves in both. <a href=\"/docs/guides/environment-variables\">Environment variables</a>.</li>\n<li><strong>Fix: web fonts and other CSS <code>url()</code> assets no longer 404 in <code>pyxle dev</code></strong> — Pyxle sets Vite&#39;s <code>server.origin</code> so dev assets load from Vite directly.</li>\n</ul>\n<h2 id=\"044\">0.4.4</h2><ul>\n<li><strong>Fix: cross-page hash links scroll to their anchor.</strong> Client-side navigation to <code>/page#section</code> now jumps to the top and scrolls to the anchor once the next page commits, matching native behaviour.</li>\n</ul>\n<h2 id=\"043\">0.4.3</h2><ul>\n<li><strong>Security: hardened HEAD sanitisation (XSS).</strong> Dynamic <code>HEAD</code> values are now parsed and rebuilt from a strict tag allowlist with every attribute HTML-escaped, <code>on*</code> handlers dropped, dangerous URLs neutralised, and non-head tags rejected — closing an injection via the dynamic-meta-tags recipe. Inline <code>&lt;script&gt;</code>/<code>&lt;style&gt;</code> stays supported as trusted author code.</li>\n<li><strong>Security: <code>csrf.exemptPaths</code> match on segment boundaries</strong>, so exempting <code>/api/webhooks</code> no longer also exempts <code>/api/webhooks-admin</code>.</li>\n<li><strong>Security: oversized no-JS form POSTs fail loud</strong> with a <code>413</code> (asking for the token via header) instead of being silently truncated.</li>\n<li><strong>Fix: <code>&lt;Script&gt;</code>/<code>&lt;Image&gt;</code> boolean attributes written as strings</strong> (<code>defer=&quot;false&quot;</code>, <code>priority=&quot;0&quot;</code>) now coerce correctly instead of to <code>True</code>.</li>\n<li><strong>Fix: custom <code>csrf.cookieName</code>/<code>headerName</code> now reach the client runtime</strong> — non-default names are injected into the shell so <code>useAction</code>/<code>&lt;Form&gt;</code> stop <code>403</code>-ing.</li>\n<li><strong>Fix: no double loader run on hover-then-click navigation</strong> — the click reuses the in-flight prefetch, and a superseded prefetch is discarded.</li>\n<li><strong>Multi-core serving: <code>pyxle serve --workers N</code>.</strong> N independent server processes on one port, each with its own SSR pool — throughput scales with cores, no load balancer or shared state. <a href=\"/docs/guides/deployment#multi-core-worker-processes\">Deployment</a>.</li>\n<li><strong>Sync API endpoints.</strong> A plain <code>def endpoint(request)</code> (and sync <code>HTTPEndpoint</code> methods) now runs in Starlette&#39;s threadpool, so blocking drivers no longer need manual <code>asyncio.to_thread</code>. <a href=\"/docs/guides/api-routes#sync-endpoints-and-blocking-calls\">API Routes</a>.</li>\n<li><strong>In-memory static asset cache.</strong> Small static files (≤1 MB, 32 MB/process) are served from memory with no filesystem I/O; conditional requests and cache headers behave as before.</li>\n</ul>\n<h2 id=\"042\">0.4.2</h2><ul>\n<li><strong>Live dev-server reconciliation.</strong> Editing a <code>.pyxl</code> now applies route-shape changes without a restart — rename/add/remove a loader or action, add/delete a page, wrap a page in a layout — by hot-swapping the route table; editing <code>pyxle.config.json</code> prints a &quot;restart to apply&quot; warning.</li>\n<li><strong><code>pyxle check</code> works on a clean install</strong> — the JSX checker&#39;s parser dependencies are bundled (via <code>pyxle-langkit</code>), so <code>check</code> runs after <code>pip install &#39;pyxle-framework[langkit]&#39;</code> with no npm setup.</li>\n<li><strong>Locale-independent SSR</strong> — the Python↔Node transport pins UTF-8, so non-BMP characters no longer crash rendering under <code>LANG=C</code>.</li>\n<li><strong>Smoother first run</strong> — <code>pyxle init</code> writes a gitignored <code>.env.local</code> with a random dev secret, the scaffold <code>requirements.txt</code> declares <code>pyxle-framework</code>, and <code>pyxle install</code> gives PEP 668 guidance.</li>\n<li><strong>Docs:</strong> documented calling an <code>@action</code> endpoint directly for scripts and tests.</li>\n</ul>\n<h2 id=\"041\">0.4.1</h2><ul>\n<li><strong>No more double loader run on first load.</strong> The landing page is seeded into the client navigation cache from the server render, so its prefetch resolves from cache — the loader runs once, not twice (also making back/forward instant).</li>\n<li><strong>Per-route navigation-cache TTL.</strong> A route&#39;s <a href=\"/docs/reference/configuration#edge-caching\"><code>cache</code></a> TTL now also governs client navigation-cache freshness; routes without one default to 2 minutes, tunable via <a href=\"/docs/reference/configuration#navigation\"><code>navigation.defaultPrefetchTtl</code></a>.</li>\n</ul>\n<h2 id=\"040\">0.4.0</h2><ul>\n<li><strong>Edge caching.</strong> Declare cacheable routes in <a href=\"/docs/reference/configuration#edge-caching\"><code>pyxle.config.json::cache</code></a> and pages serve <code>Cache-Control: public, s-maxage=N</code> (+ <code>stale-while-revalidate</code>) so a CDN absorbs traffic; the per-user CSRF cookie is omitted from cacheable responses. <a href=\"/docs/guides/deployment#cdn-and-edge-caching\">Deployment</a>.</li>\n<li><strong>Hardened production errors.</strong> SSR render failures (including the SPA-navigation JSON path) are sanitized in the response and logged in full for operators.</li>\n<li><strong>Faster static serving.</strong> The static-asset middleware indexes paths up front, skipping a per-request <code>stat</code> on every dynamic request.</li>\n<li><strong>Layout &amp; template loaders.</strong> A <code>layout.pyxl</code>/<code>template.pyxl</code> can declare its own <code>@server</code> loader, so shared UI loads once per request without repeating the loader in every page. <a href=\"/docs/core-concepts/layouts#layout-data-loaders\">Layouts</a>.</li>\n</ul>\n<h2 id=\"030\">0.3.0</h2><ul>\n<li><strong>First-class plugin system.</strong> Compose apps via <code>pyxle.config.json::plugins</code> (Django-style <code>INSTALLED_APPS</code>). <a href=\"/docs/guides/plugins\">Plugins guide</a>, <a href=\"/docs/reference/plugins-api\">Plugins API</a>.</li>\n<li><strong>Django-style service access.</strong> Resolve any plugin service with <code>plugin(&quot;auth.service&quot;)</code> or a typed shortcut (e.g. <code>from pyxle_auth import get_auth_service</code>).</li>\n<li><strong>First-party plugins.</strong> <a href=\"/docs/plugins/pyxle-db\"><code>pyxle-db</code></a> (SQLite-first with migrations) and <a href=\"/docs/plugins/pyxle-auth\"><code>pyxle-auth</code></a> (email+password sessions, argon2id, rate limits).</li>\n<li><strong>WebSocket endpoints</strong> — <code>pages/api/*.py</code> can export <code>async def websocket(ws)</code>. <a href=\"/docs/guides/api-routes#websocket-endpoints\">API Routes</a>.</li>\n<li><strong>Client navigation cache with TTL + invalidation.</strong> Loader payloads are cached (30s default) for instant back/forward; call <a href=\"/docs/reference/client-api#invalidateurl\"><code>invalidate(url)</code></a> or return <a href=\"/docs/reference/runtime-api#invalidate_routesresponse-urls\"><code>invalidate_routes(...)</code></a> from an action to keep lists fresh.</li>\n<li><strong><code>ActionError</code> is auto-imported</strong> for any <code>.pyxl</code> with an <code>@action</code>.</li>\n<li><strong><code>&lt;Head&gt;</code> coerces multi-part <code>&lt;title&gt;</code> children</strong> into a single string, silencing React&#39;s array-title warning.</li>\n<li><strong>SSR worker pins <code>LANG=en-US.UTF-8</code></strong> (override with <code>PYXLE_SSR_LOCALE</code>) to stop <code>Intl</code> hydration mismatches.</li>\n<li><strong>Vite resolver prefers pinned versions</strong> — <code>pyxle build</code> runs <code>npm install</code> before falling back to <code>npx --yes vite</code>.</li>\n</ul>\n","toc":[{"depth":2,"text":"0.8.0","slug":"080"},{"depth":2,"text":"0.7.5","slug":"075"},{"depth":2,"text":"0.7.4","slug":"074"},{"depth":2,"text":"0.7.3","slug":"073"},{"depth":2,"text":"0.7.2","slug":"072"},{"depth":2,"text":"0.7.1","slug":"071"},{"depth":2,"text":"0.7.0","slug":"070"},{"depth":3,"text":"Documentation","slug":"documentation"},{"depth":2,"text":"0.6.1","slug":"061"},{"depth":2,"text":"0.6.0","slug":"060"},{"depth":2,"text":"0.5.0","slug":"050"},{"depth":2,"text":"0.4.5","slug":"045"},{"depth":2,"text":"0.4.4","slug":"044"},{"depth":2,"text":"0.4.3","slug":"043"},{"depth":2,"text":"0.4.2","slug":"042"},{"depth":2,"text":"0.4.1","slug":"041"},{"depth":2,"text":"0.4.0","slug":"040"},{"depth":2,"text":"0.3.0","slug":"030"}],"path":"changelog","markdown":"# Changelog\n\nRelease notes for Pyxle. While we're in beta (`0.x`), minor versions may include breaking changes — those are called out explicitly. To upgrade, run `pip install --upgrade pyxle-framework`.\n\n## 0.8.0\n\n- **Pyxle Studio — a dashboard built into `pyxle dev`.** Served at `/__pyxle/studio`: every route with its loader, actions, cache posture, and boundaries; an interactive tester (loaders run in-process, actions go through their real endpoint — CSRF, validation, and auth hooks included); a live request feed; latency metrics; the effective config (secrets redacted); and in-browser `pyxle check`. Dev-only by construction, with a `Host`-header allowlist. [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md).\n- **New `pyxle studio` command.** Runs the dev server and opens the browser on the dashboard, enabling it for that run even when the config opts out. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-studio).\n- **Breakpoint debugging directly in `.pyxl` files.** Set a breakpoint on a line inside a `@server` loader *and* on a line inside the JSX below it — both bind. Compiled server modules are remapped to their `.pyxl` sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. [Debugging](https://pyxle.dev/docs/guides/debugging.md).\n- **One-key debugging from VS Code.** Pyxle Language Tools 0.3.0 contributes a `pyxle` debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate \"Debug Pyxle app (React browser)\" configuration debugs the React side in a standalone browser session. Plus a \"Pyxle: Open Studio\" command. Install it with `code --install-extension pyxle.pyxle-language-tools`. [Debugging](https://pyxle.dev/docs/guides/debugging.md#quick-start-breakpoints-in-a-pyxl-file).\n- **`pyxle dev --inspect` for attach-style debugging.** Hosts a debugpy server bound to `127.0.0.1` so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes `.pyxle-build/dev-server.json` (ports, debugpy endpoint) for editor tooling and removes it on shutdown. [Debugging](https://pyxle.dev/docs/guides/debugging.md).\n- **Dev tracebacks now point at `.pyxl` sources.** A loader/action error names your `.pyxl` file and line instead of the compiled module under `.pyxle-build/`. [Debugging](https://pyxle.dev/docs/guides/debugging.md).\n- **Breaking: `/__pyxle` is now a reserved URL namespace.** The dev server's Vite asset proxy never forwards paths under it, so an app route under `/__pyxle` no longer resolves in `pyxle dev` (it still serves in production, where the namespace is unused). Move any such route before upgrading. [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md#the-reserved-__pyxle-namespace).\n- **Fixed on Windows: `NODE_PATH` is built with the platform delimiter.** A project that already set `NODE_PATH` got a `:`-joined value, which Node cannot parse on Windows, so neither entry resolved.\n- **Fixed on Windows: rebuild notifications report POSIX paths.** The dev server's rebuild event carried host separators, so Studio and the error overlay showed `pages\\index.pyxl`.\n\n## 0.7.5\n\n- **`pyxle dev` now persists module-level state across requests, like `pyxle serve`.** A `@server`/`@action` module is imported once and reused between rebuilds, so a module-level counter or in-memory cache no longer resets on every refresh in dev. Saving a file still re-imports it (resetting globals and applying your edits). State stays per-process — use a database or cache for anything shared or durable ([Loaders should be stateless](https://pyxle.dev/docs/core-concepts/data-loading.md#loaders-should-be-stateless)).\n- **`pyxle init` now requires an explicit target.** A bare `pyxle init` used to silently scaffold into the current directory; it now errors, pointing to `pyxle init my-app` (new directory) or `pyxle init .` (current directory).\n\n## 0.7.4\n\n- **Fix: `pyxle dev` no longer hot-reloads in an endless loop on Linux.** After a save, the rebuild's own file reads surfaced through `inotify` as events the watcher mistook for edits, re-triggering the rebuild forever (macOS `FSEvents` doesn't report reads, so it was Linux-only). The watcher now reacts only to genuine change events, not read-only opens.\n\n## 0.7.3\n\n- **Docs: an `@action`'s awaited result is the flat `{ ok, ...yourReturn }`** — read fields directly (`res.title`), never `res.data.title` (a successful result has no `.data`; `useAction().data` is a separate hook property). Clarified across the [Server Actions guide](https://pyxle.dev/docs/core-concepts/server-actions.md), the [client API reference](https://pyxle.dev/docs/reference/client-api.md), and the scaffold `AGENTS.md`.\n\n## 0.7.2\n\n- **Fix: `pyxle init` scaffolds an installable `requirements.txt` again.** The template's `starlette` pin conflicted with the framework's after 0.7.1's security bump; both now use `starlette>=1.3.1,<2.0`.\n- **Config: a boolean `port` is now rejected instead of binding port 1.** `bool` being an `int` subclass slipped past the validator; it now raises a clear `ConfigError`.\n\n## 0.7.1\n\n- **Security: require Starlette ≥ 1.3.1**, fixing a `Host`-header auth bypass (PYSEC-2026-161), form-parsing DoS (PYSEC-2026-249, -1943), and a Windows `StaticFiles` SSRF (CVE-2026-48818). Pyxle's own API is unchanged; a new `pip-audit` CI job guards dependencies.\n- **`pyxle serve` refuses to start in production without `PYXLE_SECRET_KEY`** — previously only a warning, leaving CSRF tokens and signed cookies forgeable. [Security](https://pyxle.dev/docs/guides/security.md), [Deployment](https://pyxle.dev/docs/guides/deployment.md).\n- **`pyxle dev`/`build` check the Node.js version up front** — a clear \"Node.js 20.19+ required\" message instead of an opaque Vite crash. [Installation → Troubleshooting](https://pyxle.dev/docs/getting-started/installation.md#troubleshooting).\n- **A real testing story: `pyxle.testing` helpers and a [Testing guide](https://pyxle.dev/docs/guides/testing.md).** `load_loader(\"pages/index.pyxl\")` / `load_page(...)` compile a page and hand back its loader/module for unit tests.\n- **New [Debugging guide](https://pyxle.dev/docs/guides/debugging.md) and Deployment fixes** — Node 22 in the sample Dockerfile, the real metrics path (`/api/__pyxle/metrics`), a migrations section, and a blue-green CSRF gotcha.\n- **Security docs now match what Pyxle sends** — it already sets `X-Content-Type-Options`/`X-Frame-Options`/`Referrer-Policy`, so the guide covers only CSP and HSTS; a [SECURITY.md](https://github.com/pyxle-dev/pyxle/blob/main/SECURITY.md) is published for every repo.\n- **A fresh project now ships a human `README.md`** alongside the AI-oriented `AGENTS.md`.\n- **The [comparison guide](https://pyxle.dev/docs/guides/comparison.md) names current gaps** — TSX authoring, a first-class test client, automatic image/font optimization, i18n — with how to bridge each today.\n\n## 0.7.0\n\n- **Fix: `error.pyxl` renders even when an ancestor layout has a `@server` loader.** Boundary renders now run ancestor layout loaders like a normal page instead of silently falling back to the built-in error document.\n- **Pre-release fixes.** `PYXLE_SSR_WORKER_CONCURRENCY` reaches the worker again, `SIGTERM` to `pyxle dev` tears down the whole child tree, a failed rebuild broadcasts to the overlay, and reverting to last-good content triggers the recovery rebuild.\n- **Fix: CommonJS React libraries no longer crash SSR.** The SSR bundler resolves dependencies ESM-first (like Vite), so packages without an `exports` map (e.g. `lucide-react`) link cleanly; a genuinely CJS-only package now fails with an actionable error. [Third-party packages](https://pyxle.dev/docs/guides/third-party-packages.md#commonjs-packages-and-ssr).\n- **Docs: [the road to a fully-typed Pyxle](https://pyxle.dev/docs/guides/fully-typed-pyxle.md)** — where the type story is heading (TSX authoring, Python types across the boundary), grounded in what works today.\n- **Breaking: Node.js 20.19+ is now required** (Vite 7's floor; Node 18 is EOL). [Installation](https://pyxle.dev/docs/getting-started/installation.md).\n- **Modernized scaffold — React 19, Vite 7, and an interactive `pyxle init`.** Arrow-key prompts for Tailwind, shadcn/ui, and the import alias, with `--yes`/explicit flags for non-interactive use. [Quick Start](https://pyxle.dev/docs/getting-started/quick-start.md).\n- **Tailwind is now opt-in — Tailwind v4 wired into Vite when chosen.** No config files or standalone watcher; decline it and plain CSS / CSS Modules work out of the box. [Styling](https://pyxle.dev/docs/guides/styling.md).\n- **shadcn/ui support** — choose it at `pyxle init` and `npx shadcn@latest add …` works with no `shadcn init`; the `@` alias resolves in the client build and SSR. [Third-party packages](https://pyxle.dev/docs/guides/third-party-packages.md#shadcnui).\n- **Fix: streaming SSR no longer serializes across requests.** An SSR worker now renders many requests concurrently (isolated per-request with `AsyncLocalStorage`), and `pyxle serve` auto-sizes its worker pool. [Streaming](https://pyxle.dev/docs/guides/streaming.md#concurrent-streams-dont-queue).\n- **`pyxle init` renders the framework pin from the running version** instead of a stale `>=0.4.1` that downgraded fresh projects.\n- **`pyxle typecheck` fails fast when TypeScript isn't installed**, with an actionable message instead of npm's placeholder `tsc`. [TypeScript](https://pyxle.dev/docs/guides/typescript.md).\n- **Scaffolded `AGENTS.md` corrected** — `LoaderError` (like `server`/`action`/`ActionError`/…) is compiler-injected, not imported.\n- **`pyxle check` works out of the box — `pyxle-langkit` is now a default dependency**, so JSX checking passes on a fresh scaffold with no extra step.\n- **Fix: the CSRF cookie no longer collides between apps on one host.** The default name is namespaced by bind port (`pyxle-csrf-8000`) and injected into the page shell. [Security → CSRF](https://pyxle.dev/docs/guides/security.md#csrf-protection).\n- **Fix: multipart forms (file uploads) now pass CSRF with a `_csrf_token` field.** The middleware stream-parses just far enough to read the token (capped at 1 MiB) and replays the body untouched. [Security → Form bodies and uploads](https://pyxle.dev/docs/guides/security.md#form-bodies-and-uploads).\n- **`pyxle dev` output is clean by default, `--verbose` for the firehose** — a curated startup summary and one-line rebuild notices instead of Vite's raw stdout. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-dev).\n- **Server-side logs stream to the browser console in `pyxle dev`**, prefixed `[pyxle:server]`; dev-only and bounded. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-dev).\n- **`public/` changes are picked up on refresh instead of triggering a rebuild (matching Next.js)** — assets serve live from disk, and a newly added or removed file refreshes the static index. [Architecture → the watcher](https://pyxle.dev/docs/architecture/dev-server.md#the-watcher).\n- **Watch extra directories with `dev.watch`, ignore paths with `dev.ignore`.** A shared module outside `pages/` can now trigger hot reload; `dev.ignore` is additive to the built-in ignores. [Configuration → Development](https://pyxle.dev/docs/reference/configuration.md#development).\n\n### Documentation\n\n- **Fixed the flagship [WebSockets](https://pyxle.dev/docs/guides/websockets.md) example** — it derived the socket path from `window` during SSR and 500'd; it now builds the path from loader data.\n- **More doc fixes** — a broken `@action` example in the [pyxle-db docs](https://pyxle.dev/docs/plugins/pyxle-db.md) (`await request.json()`), documented CSRF on the pyxle-auth endpoints and where pyxle-auth accounts live, an honest [`pyxle check`](https://pyxle.dev/docs/reference/cli.md#pyxle-check) scope note, and prerequisites up front in the [Introduction](https://pyxle.dev/docs/getting-started/introduction.md).\n- **`Accept: text/markdown` negotiation now follows RFC 9110** (q-values honoured, exact type match); new `markdown_is_acceptable(accept)` helper. [AI accessibility](https://pyxle.dev/docs/guides/llms.md#negotiation-rules).\n- **`/llms.txt` now emits absolute URLs and links `.md` only where Markdown actually resolves.** [AI accessibility](https://pyxle.dev/docs/guides/llms.md#the-llmstxt-index).\n- **Breaking: converted Markdown rewrites internal links to `.md`** — `html_to_markdown()` rewrites by default (`rewrite_links=False` for the old behavior). [AI accessibility](https://pyxle.dev/docs/guides/llms.md#autoconvert-the-lossy-fallback).\n- **Fix: a burst of rapid saves can no longer kill the dev server** — builds are serialized, `meta.json` writes atomically, and the Vite subprocess is supervised with bounded backoff.\n- **Fix: reading an unprovided `request.state.<name>`** (e.g. `request.state.db` without pyxle-db) now gives a structured, guided error instead of a bare `AttributeError`.\n- **Actionable SSR error when a component touches a browser global** (`window`, `document`, …) — dev names your `.pyxl` file and the fix (`useEffect`/`<ClientOnly>`); production stays generic. [Client Components](https://pyxle.dev/docs/guides/client-components.md).\n\n## 0.6.1\n\nA sharper `pyxle check` — the edit → check → fix loop now catches classes of mistake it used to wave through.\n\n- **`pyxle check` gained a semantic layer** — pyflakes over the Python section flags undefined names, unused imports, and redefinitions (compiler-injected names are recognized).\n- **Duplicate `export default` is now caught at check time**, at the real source line, instead of failing later in the build.\n- **JSX error lines are now accurate**, and Babel's misleading \"unterminated regex\" carries a plain-language hint about the real cause.\n- **`LoaderError` and `invalidate_routes` are now auto-injected**, matching `ActionError`/`ValidationActionError`. [Runtime API](https://pyxle.dev/docs/reference/runtime-api.md).\n- **`pyxle install --break-system-packages`** for externally-managed (PEP 668) environments. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-install).\n\n## 0.6.0\n\n- **AI accessibility — serve your app as Markdown, plus `llms.txt`.** Opt in with `\"llms\": true` and every page gains a `.md` rendition (and `Accept: text/markdown` support), an `/llms.txt` index, and discovery headers; Markdown resolves from a co-located `<page>.md`, a `to_markdown` handler, or an ancestor `llms.py`, with an `autoConvert` HTML→Markdown fallback. Off by default, and adds nothing to the page hot path. [AI accessibility](https://pyxle.dev/docs/guides/llms.md).\n\n## 0.5.0\n\nThe depth release: caching/SSG/ISR, streaming SSR, realtime (WebSockets + a cross-worker Redis broker), Pydantic-validated actions, observability, background work, image optimization, and multi-worker serving — built, documented, and dogfooded on pyxle.dev. The two behavior changes below are called out explicitly.\n\n- **Cross-worker realtime — a Redis pub/sub broker.** WebSocket channels span worker processes and machines with `PYXLE_REALTIME_BROKER=redis`; the in-process broker stays the default. No code change. [WebSockets](https://pyxle.dev/docs/guides/websockets.md#cross-worker-realtime-with-redis).\n- **Fix: streaming SSR now survives production gzip.** A streaming-aware `StreamingGZipMiddleware` flushes the compressor per chunk so the shell reaches the browser first. [Streaming](https://pyxle.dev/docs/guides/streaming.md#streaming-survives-gzip-in-production).\n- **Fix: dynamic pages are no longer client-nav-cached with stale data.** The navigation-cache TTL now mirrors server cacheability, so a dynamic page always refetches on back/forward. [Caching](https://pyxle.dev/docs/guides/caching.md#client-navigation-cache).\n- **Fix: `pyxle build --static` pre-renders pages whose loaders use a plugin.** The static builder stands up the same plugin context a request sees, so a DB-backed loader runs at build time. [Caching](https://pyxle.dev/docs/guides/caching.md#static-pre-rendering-pyxle-build-static).\n- **Changed (behavior): stricter nested-config validation.** The `cors`/`csrf`/`observability`/… blocks now reject unknown keys at boot, so a typo'd security key fails loudly instead of silently no-opping. [Configuration](https://pyxle.dev/docs/reference/configuration.md).\n- **Fix: `error.pyxl` no longer leaks internal error details in production** — the boundary gets a generic message and sanitized type; author-raised `LoaderError`/`ActionError` messages still pass through. [Error Handling](https://pyxle.dev/docs/guides/error-handling.md).\n- **Fix: `import.meta.env.PYXLE_PUBLIC_*` is now substituted during SSR**, so a public env var no longer causes a hydration mismatch. [Environment variables](https://pyxle.dev/docs/guides/environment-variables.md).\n- **Fix: scaffold `.gitignore` no longer ignores `.env`**, matching the env-vars doc.\n- **Fix: `<Image>` emits a lowercase `fetchpriority` attribute** (React 18.3.1 rejected the camelCase form).\n- **Fix: production gzip no longer prints `I/O operation on closed file`** — the compressor closes deterministically on every path.\n- **Fix: scaffolded `jsconfig.json` drops the deprecated `baseUrl`** in favor of tsconfig-relative `paths`.\n- **Fix: `pyxle typecheck` works on current TypeScript** — `\"bundler\"` resolution, no `baseUrl`.\n- **Startup warning when a `BaseHTTPMiddleware` is paired with streaming routes** (it buffers responses, breaking streaming SSR). [Middleware](https://pyxle.dev/docs/guides/middleware.md).\n- **Clear compile-time error for TypeScript syntax in a client block** (it's plain JSX), pointing at your `.pyxl` source line. [TypeScript](https://pyxle.dev/docs/guides/typescript.md).\n- **New guides: [TypeScript](https://pyxle.dev/docs/guides/typescript.md) and [Migrating from Flask or Django](https://pyxle.dev/docs/guides/migration-from-flask-django.md).**\n- **`error.pyxl` is now a client-side error boundary too** — a render fault after hydration renders the nearest boundary instead of a blank screen, with the same `error` prop on both sides. [Error Handling](https://pyxle.dev/docs/guides/error-handling.md#client-side-errors).\n- **Built-in rate limiting — `pyxle.middleware.RateLimitMiddleware`.** A dependency-free token-bucket limiter configured from `pyxle.config.json`; per-process, so rate-limit at the proxy for one global cap. Off by default. [Middleware](https://pyxle.dev/docs/guides/middleware.md#rate-limiting).\n- **Route policies now apply to `@action` endpoints** via `routeMiddleware.actions`, closing a bypass where an auth policy wrapped pages but not actions. [Middleware](https://pyxle.dev/docs/guides/middleware.md#route-level-hooks).\n- **`pyxle serve --workers 0` auto-detects the core count.** The [Deployment guide](https://pyxle.dev/docs/guides/deployment.md#multi-core-worker-processes) adds a per-worker-state table and rolling-deploy guidance.\n- **Build optimization: responsive `<Image>`, modulepreload hints, and `--analyze`.** `<Image>` emits a responsive `srcset` via a `loader` and gains `fill`/`sizes`/`priority`; the SSR shell preloads entry chunks; `pyxle build --analyze` reports bundle sizes. [Build Optimization](https://pyxle.dev/docs/guides/build-optimization.md).\n- **Background tasks & deferred work.** `request.state.background.add_task(...)` (or a `{\"background\": [...]}` return) runs after the response; `pyxle.tasks.enqueue(...)` schedules fire-and-forget work on an in-process pool (per-process — hand off to Celery/ARQ/Dramatiq for durability). [Background Tasks](https://pyxle.dev/docs/guides/background-tasks.md).\n- **OpenTelemetry tracing (opt-in).** Request/SSR/loader/action spans via the `[observability-otel]` extra; fully off and zero-cost by default. [Observability](https://pyxle.dev/docs/guides/observability.md#opentelemetry-tracing).\n- **`pyxle dev --dashboard` — a live terminal observability panel** (throughput, error rate, latency, cache hit ratio); dependency-free and dev-only. [Observability](https://pyxle.dev/docs/guides/observability.md#dev-dashboard).\n- **Structured access logging** — one line per request (`method`/`path`/`status`/`duration_ms`/correlation id) in console or JSON via `observability.accessLog`. [Observability](https://pyxle.dev/docs/guides/observability.md#structured-logging).\n- **Observability: request IDs, timing, metrics, and richer health probes.** Every request gets a correlation id (`X-Request-Id`) and timing; opt-in Prometheus metrics; `/readyz` runs dependency checks. Metrics are per-worker. [Observability](https://pyxle.dev/docs/guides/observability.md).\n- **Typed `@action` request validation with Pydantic.** Annotate a `body: Model` parameter and Pyxle validates before the action runs, returning `422` with a `fields` map on failure; `pyxle openapi` generates an OpenAPI 3.1 document from your models. Optional `[pydantic]` extra. [Server Actions](https://pyxle.dev/docs/core-concepts/server-actions.md#validating-request-bodies-with-pydantic).\n- **Fix: a server module that fails to import is no longer cached as a broken empty module** — the real error re-raises on each request.\n- **WebSockets — page handlers, a client hook, and pub/sub.** A page can export `async def websocket(ws)`; `pyxle.realtime` adds `channel`/`room.publish`, WS auth/origin helpers, and a `useWebSocket()` hook. The in-process broker is per-worker (a Redis broker drops in). [WebSockets](https://pyxle.dev/docs/guides/websockets.md).\n- **Streaming SSR for `<Suspense>` pages.** The shell flushes immediately and each boundary streams in as it resolves; opt-in, zero-config, dynamic pages only. [Streaming](https://pyxle.dev/docs/guides/streaming.md).\n- **`loading.pyxl` route-level loading states** wrap a route in `<Suspense>`, streamed as the shell and applied identically on the client. [Streaming](https://pyxle.dev/docs/guides/streaming.md#route-level-loading-states-with-loadingpyxl).\n- **Server-side page caching with incremental regeneration.** Return `{\"data\", \"revalidate\": N}` (or a `CACHE` directive) to cache rendered HTML; `pyxle build --static` warms it; stale-while-revalidate, strong `ETag`, and `cache.invalidate(...)`. In-memory/disk/Redis backends. [Caching](https://pyxle.dev/docs/guides/caching.md).\n\n## 0.4.5\n\n- **Signed cookies & tokens — `sign_cookie` / `verify_cookie`.** Stdlib-only helpers that attach a tamper-proof HMAC-SHA256 signature to any string (session id, unsubscribe link, reset token) and verify it in constant time; a `salt=` namespaces signatures, and signing without a secret fails closed. [Security](https://pyxle.dev/docs/guides/security.md#signed-cookies-and-tokens).\n- **Fix: `PYXLE_PUBLIC_*` client env vars now work in `pyxle dev` and no longer break `pyxle build`** — values are emitted as quoted JS string literals, so a non-identifier value (API URL, Turnstile key) resolves in both. [Environment variables](https://pyxle.dev/docs/guides/environment-variables.md).\n- **Fix: web fonts and other CSS `url()` assets no longer 404 in `pyxle dev`** — Pyxle sets Vite's `server.origin` so dev assets load from Vite directly.\n\n## 0.4.4\n\n- **Fix: cross-page hash links scroll to their anchor.** Client-side navigation to `/page#section` now jumps to the top and scrolls to the anchor once the next page commits, matching native behaviour.\n\n## 0.4.3\n\n- **Security: hardened HEAD sanitisation (XSS).** Dynamic `HEAD` values are now parsed and rebuilt from a strict tag allowlist with every attribute HTML-escaped, `on*` handlers dropped, dangerous URLs neutralised, and non-head tags rejected — closing an injection via the dynamic-meta-tags recipe. Inline `<script>`/`<style>` stays supported as trusted author code.\n- **Security: `csrf.exemptPaths` match on segment boundaries**, so exempting `/api/webhooks` no longer also exempts `/api/webhooks-admin`.\n- **Security: oversized no-JS form POSTs fail loud** with a `413` (asking for the token via header) instead of being silently truncated.\n- **Fix: `<Script>`/`<Image>` boolean attributes written as strings** (`defer=\"false\"`, `priority=\"0\"`) now coerce correctly instead of to `True`.\n- **Fix: custom `csrf.cookieName`/`headerName` now reach the client runtime** — non-default names are injected into the shell so `useAction`/`<Form>` stop `403`-ing.\n- **Fix: no double loader run on hover-then-click navigation** — the click reuses the in-flight prefetch, and a superseded prefetch is discarded.\n- **Multi-core serving: `pyxle serve --workers N`.** N independent server processes on one port, each with its own SSR pool — throughput scales with cores, no load balancer or shared state. [Deployment](https://pyxle.dev/docs/guides/deployment.md#multi-core-worker-processes).\n- **Sync API endpoints.** A plain `def endpoint(request)` (and sync `HTTPEndpoint` methods) now runs in Starlette's threadpool, so blocking drivers no longer need manual `asyncio.to_thread`. [API Routes](https://pyxle.dev/docs/guides/api-routes.md#sync-endpoints-and-blocking-calls).\n- **In-memory static asset cache.** Small static files (≤1 MB, 32 MB/process) are served from memory with no filesystem I/O; conditional requests and cache headers behave as before.\n\n## 0.4.2\n\n- **Live dev-server reconciliation.** Editing a `.pyxl` now applies route-shape changes without a restart — rename/add/remove a loader or action, add/delete a page, wrap a page in a layout — by hot-swapping the route table; editing `pyxle.config.json` prints a \"restart to apply\" warning.\n- **`pyxle check` works on a clean install** — the JSX checker's parser dependencies are bundled (via `pyxle-langkit`), so `check` runs after `pip install 'pyxle-framework[langkit]'` with no npm setup.\n- **Locale-independent SSR** — the Python↔Node transport pins UTF-8, so non-BMP characters no longer crash rendering under `LANG=C`.\n- **Smoother first run** — `pyxle init` writes a gitignored `.env.local` with a random dev secret, the scaffold `requirements.txt` declares `pyxle-framework`, and `pyxle install` gives PEP 668 guidance.\n- **Docs:** documented calling an `@action` endpoint directly for scripts and tests.\n\n## 0.4.1\n\n- **No more double loader run on first load.** The landing page is seeded into the client navigation cache from the server render, so its prefetch resolves from cache — the loader runs once, not twice (also making back/forward instant).\n- **Per-route navigation-cache TTL.** A route's [`cache`](https://pyxle.dev/docs/reference/configuration.md#edge-caching) TTL now also governs client navigation-cache freshness; routes without one default to 2 minutes, tunable via [`navigation.defaultPrefetchTtl`](https://pyxle.dev/docs/reference/configuration.md#navigation).\n\n## 0.4.0\n\n- **Edge caching.** Declare cacheable routes in [`pyxle.config.json::cache`](https://pyxle.dev/docs/reference/configuration.md#edge-caching) and pages serve `Cache-Control: public, s-maxage=N` (+ `stale-while-revalidate`) so a CDN absorbs traffic; the per-user CSRF cookie is omitted from cacheable responses. [Deployment](https://pyxle.dev/docs/guides/deployment.md#cdn-and-edge-caching).\n- **Hardened production errors.** SSR render failures (including the SPA-navigation JSON path) are sanitized in the response and logged in full for operators.\n- **Faster static serving.** The static-asset middleware indexes paths up front, skipping a per-request `stat` on every dynamic request.\n- **Layout & template loaders.** A `layout.pyxl`/`template.pyxl` can declare its own `@server` loader, so shared UI loads once per request without repeating the loader in every page. [Layouts](https://pyxle.dev/docs/core-concepts/layouts.md#layout-data-loaders).\n\n## 0.3.0\n\n- **First-class plugin system.** Compose apps via `pyxle.config.json::plugins` (Django-style `INSTALLED_APPS`). [Plugins guide](https://pyxle.dev/docs/guides/plugins.md), [Plugins API](https://pyxle.dev/docs/reference/plugins-api.md).\n- **Django-style service access.** Resolve any plugin service with `plugin(\"auth.service\")` or a typed shortcut (e.g. `from pyxle_auth import get_auth_service`).\n- **First-party plugins.** [`pyxle-db`](https://pyxle.dev/docs/plugins/pyxle-db.md) (SQLite-first with migrations) and [`pyxle-auth`](https://pyxle.dev/docs/plugins/pyxle-auth.md) (email+password sessions, argon2id, rate limits).\n- **WebSocket endpoints** — `pages/api/*.py` can export `async def websocket(ws)`. [API Routes](https://pyxle.dev/docs/guides/api-routes.md#websocket-endpoints).\n- **Client navigation cache with TTL + invalidation.** Loader payloads are cached (30s default) for instant back/forward; call [`invalidate(url)`](https://pyxle.dev/docs/reference/client-api.md#invalidateurl) or return [`invalidate_routes(...)`](https://pyxle.dev/docs/reference/runtime-api.md#invalidate_routesresponse-urls) from an action to keep lists fresh.\n- **`ActionError` is auto-imported** for any `.pyxl` with an `@action`.\n- **`<Head>` coerces multi-part `<title>` children** into a single string, silencing React's array-title warning.\n- **SSR worker pins `LANG=en-US.UTF-8`** (override with `PYXLE_SSR_LOCALE`) to stop `Intl` hydration mismatches.\n- **Vite resolver prefers pinned versions** — `pyxle build` runs `npm install` before falling back to `npx --yes vite`.\n","prev":{"title":"Frequently Asked Questions","path":"faq"}}
\ No newline at end of file
diff --git a/public/docs-data/guides/debugging-pyxl.json b/public/docs-data/guides/debugging-pyxl.json
deleted file mode 100644
index 0e8efee..0000000
--- a/public/docs-data/guides/debugging-pyxl.json
+++ /dev/null
@@ -1 +0,0 @@
-{"title":"Debugging .pyxl files","description":"Set a breakpoint directly in your `.pyxl` source — on a line inside a `@server` loader *and* on a line inside the JSX below it — and both bind. `pyxle dev --inspect` exposes the Python half to any deb","html":"<p>Set a breakpoint directly in your <code>.pyxl</code> source — on a line inside a <code>@server</code> loader <em>and</em> on a line inside the JSX below it — and both bind. <code>pyxle dev --inspect</code> exposes the Python half to any debugger, dev source maps expose the React half to the browser, and the VS Code extension turns each into one launch: <strong>F5</strong> for the Python side, a second configuration for the React side. No custom debugger, no compiled-file archaeology.</p>\n<hr>\n<h2 id=\"quick-start-vs-code\">Quick start (VS Code)</h2><ol>\n<li>Install the <strong>Pyxle Language Tools</strong> extension (0.3.0 or later). For Python-side breakpoints, also install the <strong>Python</strong> extension (<code>ms-python.python</code>) — the debugger prompts you if it&#39;s missing and still debugs the React side without it.</li>\n<li>Make sure your project uses <strong>pyxle-framework 0.8.0 or newer</strong> (the debugger relies on line mapping shipped in 0.8.0). Nothing else to install: debugpy ships with the framework.</li>\n<li>Open a <code>.pyxl</code> file and press <strong>F5</strong>. With no <code>launch.json</code> yet, Pyxle asks which half to debug — <strong>Backend — Python</strong> or <strong>Frontend — React</strong>. Pick one, or commit the configurations to skip the prompt:</li>\n</ol>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app\" },\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app (React browser)\", \"server\": false }\n  ]\n}</code></pre></div><p>Choosing <strong>Backend</strong> runs your dev server under the Python debugger — one clean debug session that VS Code owns. A breakpoint in a loader or action pauses the request in VS Code with the <code>.pyxl</code> frame in the stack. Once the server is ready, your app opens in the browser. <strong>Stop</strong>, <strong>Restart</strong>, and <strong>Pause</strong> all act on that single session — Stop tears the whole server (Vite, SSR workers) down with it. It needs the <strong>Python</strong> extension (<code>ms-python.python</code>); the debugger offers to install it if it&#39;s missing.</p>\n<p><strong>To debug the React half too</strong>, run the <strong>&quot;Debug Pyxle app (React browser)&quot;</strong> configuration (it&#39;s just <code>&quot;server&quot;: false</code>) — a standalone Chrome session pointed at the running dev server. A breakpoint you set in the component pauses there, in the same <code>.pyxl</code> file you set the loader breakpoint in. It&#39;s a <em>separate</em> session on purpose: keeping the browser out of the Python session&#39;s toolbar means each side has clean, unambiguous Stop / Restart / Pause.</p>\n<p>If the Frontend session had to start its own <code>pyxle dev</code> (nothing was running), <strong>stopping it offers to stop that server too</strong> — a one-click &quot;Stop server&quot;. Restarting the Frontend session keeps the server up (no prompt). If instead it attached to a server something else started (Backend, or a <code>pyxle dev</code> you ran yourself), stopping Frontend leaves that server running untouched — you stop it where you started it.</p>\n<p>To debug <strong>both</strong> halves, start <strong>Backend</strong> first — it runs the dev server — then start <strong>Frontend</strong>, which attaches its browser to that same server. That way Stop on either side does the right thing: stopping Frontend leaves the server (Backend owns it), stopping Backend tears it down. Frontend on its own works standalone too; just don&#39;t start Backend on top of a Frontend-started server, or they&#39;ll race for the port (the second one fails to bind with an &quot;address already in use&quot; error — stop the first, then start the other).</p>\n<p>The launch configuration accepts a few knobs:</p>\n<table>\n<thead>\n<tr>\n<th>Property</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>cwd</code></td>\n<td><code>${workspaceFolder}</code></td>\n<td>Pyxle project root (contains <code>pages/</code> and <code>pyxle.config.json</code>).</td>\n</tr>\n<tr>\n<td><code>server</code></td>\n<td><code>true</code></td>\n<td>Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set <code>false</code> to debug <strong>only</strong> the React side in a standalone Chrome session.</td>\n</tr>\n<tr>\n<td><code>browser</code></td>\n<td><code>true</code></td>\n<td>When debugging Python, open the app in your browser once the server is ready.</td>\n</tr>\n<tr>\n<td><code>url</code></td>\n<td>dev server root</td>\n<td>Page to open.</td>\n</tr>\n<tr>\n<td><code>args</code></td>\n<td><code>[]</code></td>\n<td>Extra arguments passed to <code>pyxle dev</code> (e.g. <code>[&quot;--port&quot;, &quot;3000&quot;]</code>).</td>\n</tr>\n<tr>\n<td><code>justMyCode</code></td>\n<td><code>true</code></td>\n<td>Keep stepping inside your own code. Set <code>false</code> to step into framework internals.</td>\n</tr>\n</tbody></table>\n<p>To attach to an already-running server instead of launching one, use <code>&quot;request&quot;: &quot;attach&quot;</code> (see <a href=\"#attaching-from-any-dap-client\">Attaching from any DAP client</a>).</p>\n<p>The extension also contributes a <strong>&quot;Pyxle: Open Studio&quot;</strong> command, which opens the running server&#39;s <a href=\"/docs/guides/studio\">Studio dashboard</a> from the command palette.</p>\n<hr>\n<h2 id=\"how-it-works\">How it works</h2><p>There is no bespoke Pyxle debugger — the feature is two stock debuggers plus line mapping, which is why it works so broadly:</p>\n<ul>\n<li><strong>The Python half</strong> (<code>@server</code> loaders, <code>@action</code> handlers). The compiler embeds a line map in every generated server module, and in development the server imports those modules with <code>co_filename</code> and line numbers remapped to the original <code>.pyxl</code> source. To <a href=\"https://github.com/microsoft/debugpy\" target=\"_blank\" rel=\"noreferrer\">debugpy</a> the running code simply <em>is</em> your <code>.pyxl</code> file, so breakpoints set there bind natively. The default launch runs the dev server under debugpy directly; <code>--inspect</code> instead hosts a debugpy server for clients to attach to.</li>\n<li><strong>The React half</strong> (the JSX in the same file). The compiler writes a source-map sidecar for each generated <code>.jsx</code> module, and the dev Vite config includes a small dev-only plugin that attaches those maps pointing back at the real <code>.pyxl</code> file on disk. VS Code&#39;s built-in js-debug resolves that file and binds breakpoints in it; browser devtools map every position the same way.</li>\n</ul>\n<p>Both mappings exist only in development. A production build ships neither.</p>\n<hr>\n<h2 id=\"cli-reference\">CLI reference</h2><p>The debugger flags live on <code>pyxle dev</code> (and <code>pyxle studio</code>, which accepts <code>--inspect</code> and <code>--inspect-port</code>):</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle dev --inspect</code></pre></div><table>\n<thead>\n<tr>\n<th>Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--inspect</code> / <code>--no-inspect</code></td>\n<td><code>false</code></td>\n<td>Host a debugpy debug server inside the dev-server process, bound to <code>127.0.0.1</code>. debugpy ships with the framework.</td>\n</tr>\n<tr>\n<td><code>--inspect-port</code></td>\n<td><code>5678</code></td>\n<td>Port for the debug server. When it&#39;s busy, Pyxle falls back to an ephemeral port and records the actual endpoint in the discovery file, so editor attach flows keep working.</td>\n</tr>\n<tr>\n<td><code>--inspect-wait</code> / <code>--no-inspect-wait</code></td>\n<td><code>false</code></td>\n<td>With <code>--inspect</code>: block startup until a debugger attaches — for breakpoints in code that runs during boot.</td>\n</tr>\n</tbody></table>\n<p>Only the dev-server process is debugged: the debugger environment is never injected into subprocesses (Vite, SSR workers, or anything a loader shells out to).</p>\n<hr>\n<h2 id=\"attaching-from-any-dap-client\">Attaching from any DAP client</h2><p>debugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a requirement. From neovim (<code>nvim-dap</code>), Emacs (<code>dape</code>), or any other DAP client, attach to the endpoint <code>--inspect</code> printed — the equivalent of:</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"type\": \"debugpy\",\n  \"request\": \"attach\",\n  \"connect\": { \"host\": \"127.0.0.1\", \"port\": 5678 }\n}</code></pre></div><p>Set breakpoints in <code>.pyxl</code> files by their real path. Because the server&#39;s code objects already carry <code>.pyxl</code> filenames, no path mappings or source translations are needed — stack frames, stepping, and <code>evaluate</code> in a paused loader all just work.</p>\n<hr>\n<h2 id=\"tracebacks-point-at-pyxl-now\">Tracebacks point at .pyxl now</h2><p>The same line mapping improves life with no debugger attached at all: in development, a Python traceback from a loader or action names your <code>.pyxl</code> file and line — not a compiled module under <code>.pyxle-build/</code>. The terminal, the browser error overlay, and your logs all agree on where the error actually is.</p>\n<hr>\n<h2 id=\"the-discovery-file\">The discovery file</h2><p>While running, the dev server writes <code>.pyxle-build/dev-server.json</code> describing itself, and removes it on shutdown. This is what editor tooling (like the VS Code extension&#39;s F5 flow and &quot;Open Studio&quot;) reads instead of guessing ports:</p>\n<table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Type</th>\n<th>Meaning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>pid</code></td>\n<td><code>integer</code></td>\n<td>Dev-server process id.</td>\n</tr>\n<tr>\n<td><code>version</code></td>\n<td><code>string</code></td>\n<td>Pyxle version.</td>\n</tr>\n<tr>\n<td><code>startedAt</code></td>\n<td><code>number</code></td>\n<td>Unix timestamp of server start.</td>\n</tr>\n<tr>\n<td><code>projectRoot</code></td>\n<td><code>string</code></td>\n<td>Absolute path of the project.</td>\n</tr>\n<tr>\n<td><code>server</code></td>\n<td><code>object</code></td>\n<td><code>{ &quot;host&quot;, &quot;port&quot; }</code> of the Starlette server.</td>\n</tr>\n<tr>\n<td><code>vite</code></td>\n<td><code>object</code></td>\n<td><code>{ &quot;host&quot;, &quot;port&quot; }</code> of the Vite dev server.</td>\n</tr>\n<tr>\n<td><code>url</code></td>\n<td><code>string</code></td>\n<td>Browser-reachable base URL.</td>\n</tr>\n<tr>\n<td><code>studio</code></td>\n<td><code>string</code> | <code>null</code></td>\n<td>Studio dashboard URL (<code>null</code> when Studio is disabled).</td>\n</tr>\n<tr>\n<td><code>debugpy</code></td>\n<td><code>object</code> | <code>null</code></td>\n<td><code>{ &quot;host&quot;, &quot;port&quot; }</code> of the debug server (<code>null</code> without <code>--inspect</code>).</td>\n</tr>\n</tbody></table>\n<p>The file is written atomically, and a failed write never takes down the server.</p>\n<hr>\n<h2 id=\"caveats\">Caveats</h2><p>Worth knowing before you rely on it:</p>\n<ul>\n<li><strong>A paused breakpoint pauses the whole server.</strong> <code>pyxle dev</code> is a single process, so while you sit at a breakpoint every in-flight request waits. That&#39;s the right trade-off for development — and one reason production never hosts a debugger.</li>\n<li><strong><code>justMyCode</code> defaults to <code>true</code>.</strong> Stepping stays inside your own code; set it to <code>false</code> in the launch configuration to step into Pyxle&#39;s internals.</li>\n<li><strong>React debugging happens in the browser, not the SSR worker.</strong> Your component renders first in the Node SSR process, but the debugger doesn&#39;t attach there — it&#39;s the same code with the same source maps in the browser, which is where you debug it. (Server-render <code>console.log</code> output still prints to the <code>pyxle dev</code> terminal — see <a href=\"/docs/guides/debugging#debugging-rendering-the-nodessr-side\">Debugging</a>.)</li>\n<li><strong>Production is untouched.</strong> <code>pyxle serve</code> never remaps line numbers and never hosts debugpy, regardless of flags or config.</li>\n<li><strong>debugpy ships with the framework</strong> — <code>--inspect</code> works on a default install, no extra needed.</li>\n</ul>\n<hr>\n<h2 id=\"troubleshooting\">Troubleshooting</h2><p><strong>&quot;No module named pyxle&quot; when you press F5.</strong> VS Code has a Python interpreter selected that doesn&#39;t have pyxle installed — a common split when pyxle lives in one environment (a virtualenv, pyenv, or system Python) while VS Code points at another. The launch runs <code>python -m pyxle dev</code> under the <em>selected</em> interpreter, so it has to be the one where <code>pyxle</code> is installed. The extension checks this before launching and, when it doesn&#39;t match, offers a <strong>Select Interpreter</strong> button; you can also run <strong>Python: Select Interpreter</strong> from the command palette and pick the environment your terminal&#39;s <code>pyxle</code> command uses (<code>which pyxle</code> / <code>where pyxle</code> shows it). This is the same interpreter selection every Python project needs — nothing pyxle-specific.</p>\n<hr>\n<h2 id=\"see-also\">See also</h2><ul>\n<li><a href=\"/docs/guides/debugging\">Debugging</a> — the wider guide: reading errors, <code>pdb</code>, the SSR side, common symptoms</li>\n<li><a href=\"/docs/guides/studio\">Pyxle Studio</a> — the dev dashboard; <code>pyxle studio --inspect</code> runs both</li>\n<li><a href=\"/docs/reference/cli#pyxle-dev\">CLI reference → <code>pyxle dev</code></a> — every dev-server flag</li>\n<li><a href=\"/docs/guides/editor-setup\">Editor setup</a> — installing the VS Code extension and language server</li>\n</ul>\n","toc":[{"depth":2,"text":"Quick start (VS Code)","slug":"quick-start-vs-code"},{"depth":2,"text":"How it works","slug":"how-it-works"},{"depth":2,"text":"CLI reference","slug":"cli-reference"},{"depth":2,"text":"Attaching from any DAP client","slug":"attaching-from-any-dap-client"},{"depth":2,"text":"Tracebacks point at .pyxl now","slug":"tracebacks-point-at-pyxl-now"},{"depth":2,"text":"The discovery file","slug":"the-discovery-file"},{"depth":2,"text":"Caveats","slug":"caveats"},{"depth":2,"text":"Troubleshooting","slug":"troubleshooting"},{"depth":2,"text":"See also","slug":"see-also"}],"path":"guides/debugging-pyxl","markdown":"# Debugging .pyxl files\n\nSet a breakpoint directly in your `.pyxl` source — on a line inside a `@server` loader *and* on a line inside the JSX below it — and both bind. `pyxle dev --inspect` exposes the Python half to any debugger, dev source maps expose the React half to the browser, and the VS Code extension turns each into one launch: **F5** for the Python side, a second configuration for the React side. No custom debugger, no compiled-file archaeology.\n\n---\n\n## Quick start (VS Code)\n\n1. Install the **Pyxle Language Tools** extension (0.3.0 or later). For Python-side breakpoints, also install the **Python** extension (`ms-python.python`) — the debugger prompts you if it's missing and still debugs the React side without it.\n2. Make sure your project uses **pyxle-framework 0.8.0 or newer** (the debugger relies on line mapping shipped in 0.8.0). Nothing else to install: debugpy ships with the framework.\n3. Open a `.pyxl` file and press **F5**. With no `launch.json` yet, Pyxle asks which half to debug — **Backend — Python** or **Frontend — React**. Pick one, or commit the configurations to skip the prompt:\n\n```json\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app\" },\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app (React browser)\", \"server\": false }\n  ]\n}\n```\n\nChoosing **Backend** runs your dev server under the Python debugger — one clean debug session that VS Code owns. A breakpoint in a loader or action pauses the request in VS Code with the `.pyxl` frame in the stack. Once the server is ready, your app opens in the browser. **Stop**, **Restart**, and **Pause** all act on that single session — Stop tears the whole server (Vite, SSR workers) down with it. It needs the **Python** extension (`ms-python.python`); the debugger offers to install it if it's missing.\n\n**To debug the React half too**, run the **\"Debug Pyxle app (React browser)\"** configuration (it's just `\"server\": false`) — a standalone Chrome session pointed at the running dev server. A breakpoint you set in the component pauses there, in the same `.pyxl` file you set the loader breakpoint in. It's a *separate* session on purpose: keeping the browser out of the Python session's toolbar means each side has clean, unambiguous Stop / Restart / Pause.\n\nIf the Frontend session had to start its own `pyxle dev` (nothing was running), **stopping it offers to stop that server too** — a one-click \"Stop server\". Restarting the Frontend session keeps the server up (no prompt). If instead it attached to a server something else started (Backend, or a `pyxle dev` you ran yourself), stopping Frontend leaves that server running untouched — you stop it where you started it.\n\nTo debug **both** halves, start **Backend** first — it runs the dev server — then start **Frontend**, which attaches its browser to that same server. That way Stop on either side does the right thing: stopping Frontend leaves the server (Backend owns it), stopping Backend tears it down. Frontend on its own works standalone too; just don't start Backend on top of a Frontend-started server, or they'll race for the port (the second one fails to bind with an \"address already in use\" error — stop the first, then start the other).\n\nThe launch configuration accepts a few knobs:\n\n| Property | Default | Description |\n|----------|---------|-------------|\n| `cwd` | `${workspaceFolder}` | Pyxle project root (contains `pages/` and `pyxle.config.json`). |\n| `server` | `true` | Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set `false` to debug **only** the React side in a standalone Chrome session. |\n| `browser` | `true` | When debugging Python, open the app in your browser once the server is ready. |\n| `url` | dev server root | Page to open. |\n| `args` | `[]` | Extra arguments passed to `pyxle dev` (e.g. `[\"--port\", \"3000\"]`). |\n| `justMyCode` | `true` | Keep stepping inside your own code. Set `false` to step into framework internals. |\n\nTo attach to an already-running server instead of launching one, use `\"request\": \"attach\"` (see [Attaching from any DAP client](#attaching-from-any-dap-client)).\n\nThe extension also contributes a **\"Pyxle: Open Studio\"** command, which opens the running server's [Studio dashboard](https://pyxle.dev/docs/guides/studio.md) from the command palette.\n\n---\n\n## How it works\n\nThere is no bespoke Pyxle debugger — the feature is two stock debuggers plus line mapping, which is why it works so broadly:\n\n- **The Python half** (`@server` loaders, `@action` handlers). The compiler embeds a line map in every generated server module, and in development the server imports those modules with `co_filename` and line numbers remapped to the original `.pyxl` source. To [debugpy](https://github.com/microsoft/debugpy) the running code simply *is* your `.pyxl` file, so breakpoints set there bind natively. The default launch runs the dev server under debugpy directly; `--inspect` instead hosts a debugpy server for clients to attach to.\n- **The React half** (the JSX in the same file). The compiler writes a source-map sidecar for each generated `.jsx` module, and the dev Vite config includes a small dev-only plugin that attaches those maps pointing back at the real `.pyxl` file on disk. VS Code's built-in js-debug resolves that file and binds breakpoints in it; browser devtools map every position the same way.\n\nBoth mappings exist only in development. A production build ships neither.\n\n---\n\n## CLI reference\n\nThe debugger flags live on `pyxle dev` (and `pyxle studio`, which accepts `--inspect` and `--inspect-port`):\n\n```bash\npyxle dev --inspect\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server inside the dev-server process, bound to `127.0.0.1`. debugpy ships with the framework. |\n| `--inspect-port` | `5678` | Port for the debug server. When it's busy, Pyxle falls back to an ephemeral port and records the actual endpoint in the discovery file, so editor attach flows keep working. |\n| `--inspect-wait` / `--no-inspect-wait` | `false` | With `--inspect`: block startup until a debugger attaches — for breakpoints in code that runs during boot. |\n\nOnly the dev-server process is debugged: the debugger environment is never injected into subprocesses (Vite, SSR workers, or anything a loader shells out to).\n\n---\n\n## Attaching from any DAP client\n\ndebugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a requirement. From neovim (`nvim-dap`), Emacs (`dape`), or any other DAP client, attach to the endpoint `--inspect` printed — the equivalent of:\n\n```json\n{\n  \"type\": \"debugpy\",\n  \"request\": \"attach\",\n  \"connect\": { \"host\": \"127.0.0.1\", \"port\": 5678 }\n}\n```\n\nSet breakpoints in `.pyxl` files by their real path. Because the server's code objects already carry `.pyxl` filenames, no path mappings or source translations are needed — stack frames, stepping, and `evaluate` in a paused loader all just work.\n\n---\n\n## Tracebacks point at .pyxl now\n\nThe same line mapping improves life with no debugger attached at all: in development, a Python traceback from a loader or action names your `.pyxl` file and line — not a compiled module under `.pyxle-build/`. The terminal, the browser error overlay, and your logs all agree on where the error actually is.\n\n---\n\n## The discovery file\n\nWhile running, the dev server writes `.pyxle-build/dev-server.json` describing itself, and removes it on shutdown. This is what editor tooling (like the VS Code extension's F5 flow and \"Open Studio\") reads instead of guessing ports:\n\n| Key | Type | Meaning |\n|-----|------|---------|\n| `pid` | `integer` | Dev-server process id. |\n| `version` | `string` | Pyxle version. |\n| `startedAt` | `number` | Unix timestamp of server start. |\n| `projectRoot` | `string` | Absolute path of the project. |\n| `server` | `object` | `{ \"host\", \"port\" }` of the Starlette server. |\n| `vite` | `object` | `{ \"host\", \"port\" }` of the Vite dev server. |\n| `url` | `string` | Browser-reachable base URL. |\n| `studio` | `string` \\| `null` | Studio dashboard URL (`null` when Studio is disabled). |\n| `debugpy` | `object` \\| `null` | `{ \"host\", \"port\" }` of the debug server (`null` without `--inspect`). |\n\nThe file is written atomically, and a failed write never takes down the server.\n\n---\n\n## Caveats\n\nWorth knowing before you rely on it:\n\n- **A paused breakpoint pauses the whole server.** `pyxle dev` is a single process, so while you sit at a breakpoint every in-flight request waits. That's the right trade-off for development — and one reason production never hosts a debugger.\n- **`justMyCode` defaults to `true`.** Stepping stays inside your own code; set it to `false` in the launch configuration to step into Pyxle's internals.\n- **React debugging happens in the browser, not the SSR worker.** Your component renders first in the Node SSR process, but the debugger doesn't attach there — it's the same code with the same source maps in the browser, which is where you debug it. (Server-render `console.log` output still prints to the `pyxle dev` terminal — see [Debugging](https://pyxle.dev/docs/guides/debugging.md#debugging-rendering-the-nodessr-side).)\n- **Production is untouched.** `pyxle serve` never remaps line numbers and never hosts debugpy, regardless of flags or config.\n- **debugpy ships with the framework** — `--inspect` works on a default install, no extra needed.\n\n---\n\n## Troubleshooting\n\n**\"No module named pyxle\" when you press F5.** VS Code has a Python interpreter selected that doesn't have pyxle installed — a common split when pyxle lives in one environment (a virtualenv, pyenv, or system Python) while VS Code points at another. The launch runs `python -m pyxle dev` under the *selected* interpreter, so it has to be the one where `pyxle` is installed. The extension checks this before launching and, when it doesn't match, offers a **Select Interpreter** button; you can also run **Python: Select Interpreter** from the command palette and pick the environment your terminal's `pyxle` command uses (`which pyxle` / `where pyxle` shows it). This is the same interpreter selection every Python project needs — nothing pyxle-specific.\n\n---\n\n## See also\n\n- [Debugging](https://pyxle.dev/docs/guides/debugging.md) — the wider guide: reading errors, `pdb`, the SSR side, common symptoms\n- [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) — the dev dashboard; `pyxle studio --inspect` runs both\n- [CLI reference → `pyxle dev`](https://pyxle.dev/docs/reference/cli.md#pyxle-dev) — every dev-server flag\n- [Editor setup](https://pyxle.dev/docs/guides/editor-setup.md) — installing the VS Code extension and language server\n","prev":{"title":"Debugging","path":"guides/debugging"},"next":{"title":"Pyxle Studio","path":"guides/studio"}}
\ No newline at end of file
diff --git a/public/docs-data/guides/debugging.json b/public/docs-data/guides/debugging.json
index 8ec8a74..def8742 100644
--- a/public/docs-data/guides/debugging.json
+++ b/public/docs-data/guides/debugging.json
@@ -1 +1 @@
-{"title":"Debugging","description":"A Pyxle app has two runtimes: **Python** (your `@server` loaders, `@action` handlers, and the request pipeline) and **Node.js** (the SSR worker that renders your React components to HTML). Knowing whi","html":"<p>A Pyxle app has two runtimes: <strong>Python</strong> (your <code>@server</code> loaders, <code>@action</code>\nhandlers, and the request pipeline) and <strong>Node.js</strong> (the SSR worker that renders\nyour React components to HTML). Knowing which side an error comes from tells you\nwhere to look. This guide covers both.</p>\n<h2 id=\"read-the-error-first\">Read the error first</h2><p>In development, Pyxle surfaces errors in three places at once:</p>\n<ul>\n<li><strong>The browser error overlay</strong> — a full-screen panel with the message, the file\nand line, and a breadcrumb of what the framework was doing (loading, rendering,\nhead evaluation). This is the fastest signal for a broken page.</li>\n<li><strong>The terminal</strong> running <code>pyxle dev</code> — the same error, plus the Python\ntraceback for loader/action failures.</li>\n<li><strong>The browser devtools console</strong> — your server-side <code>logging</code> output is\nforwarded here during <code>pyxle dev</code>, prefixed <code>[pyxle:server]</code>, so you can watch\nserver logs without leaving the page. <code>pyxle -v dev</code> also forwards <code>DEBUG</code>\nrecords and framework-internal logs.</li>\n</ul>\n<p>In production (<code>debug=false</code>) error responses are intentionally generic — no\nstack traces or file paths in the body. The full detail goes to the <strong>server\nlog</strong> instead. Check your process manager&#39;s logs (e.g. <code>journalctl -u myapp</code>).</p>\n<h2 id=\"breakpoints-in-pyxl-files\">Breakpoints in .pyxl files</h2><p>Beyond <code>pdb</code>, Pyxle has a full breakpoint-debugging story: <code>pyxle dev --inspect</code>\nhosts a debug server so VS Code (or any DAP client) can pause a request at a\nbreakpoint set <strong>directly in a <code>.pyxl</code> file</strong> — Python loaders/actions on the\nserver side, and the React half through the browser. That workflow has its own\nguide: <a href=\"/docs/guides/debugging-pyxl\">Debugging <code>.pyxl</code> files</a>.</p>\n<h2 id=\"debugging-a-loader-or-action-the-python-side\">Debugging a loader or action (the Python side)</h2><p><code>@server</code> and <code>@action</code> functions are plain <code>async</code> functions — debug them like\nany Python. Drop a breakpoint:</p>\n<div class=\"code-block\" data-lang=\"python\"><pre><code class=\"language-python\">@server\nasync def load_dashboard(request):\n    breakpoint()          # or: import pdb; pdb.set_trace()\n    data = await fetch_stats(request.state.db)\n    return {\"stats\": data}</code></pre></div><p>Run <code>pyxle dev</code> <strong>in a terminal you can type into</strong> (not detached) and the <code>pdb</code>\nprompt appears there when the loader runs. Or add logging — it shows in the\nterminal <em>and</em> the browser console in dev:</p>\n<div class=\"code-block\" data-lang=\"python\"><pre><code class=\"language-python\">import logging\nlog = logging.getLogger(__name__)\n\n@server\nasync def load_dashboard(request):\n    log.info(\"loading dashboard for %s\", request.url.path)\n    ...</code></pre></div><p>To unit-test a loader/action in isolation (no server, no browser), use the\n<a href=\"/docs/guides/testing\"><code>pyxle.testing</code> helpers</a>.</p>\n<p>Two common Python-side errors have targeted messages:</p>\n<ul>\n<li><strong><code>request.state.&lt;name&gt;</code> is missing</strong> (e.g. <code>request.state.db</code> without the\n<code>pyxle-db</code> plugin) — the error names the attribute and the plugin that provides\nit. Add the plugin to <code>pyxle.config.json</code>.</li>\n<li><strong>A loader raising <code>LoaderError</code></strong> triggers the nearest <code>error.pyxl</code> boundary;\nsee <a href=\"/docs/guides/error-handling\">Error Handling</a>.</li>\n</ul>\n<h2 id=\"debugging-rendering-the-nodessr-side\">Debugging rendering (the Node/SSR side)</h2><p>Your React component runs <strong>on the server</strong> during SSR before it ever runs in the\nbrowser. Errors that mention rendering come from the Node worker:</p>\n<ul>\n<li><strong><code>window is not defined</code></strong> (or <code>document</code>, <code>localStorage</code>, …) — the component\ntouched a browser global at render scope. These don&#39;t exist during SSR. Move\nthe code into a <code>useEffect</code> or an event handler, or wrap the subtree in\n<code>&lt;ClientOnly&gt;</code>. The dev error names your <code>.pyxl</code> file and the remedy — see\n<a href=\"/docs/guides/client-components\">Client Components</a>.</li>\n<li><strong><code>Dynamic require of &quot;react&quot; is not supported</code></strong> — a dependency resolved to a\nCommonJS-only build. Pyxle resolves dependencies ESM-first; a package that is\ngenuinely CommonJS-only reports an actionable error naming the module. See\n<a href=\"/docs/guides/third-party-packages#commonjs-packages-and-ssr\">Third-party packages → CommonJS packages and SSR</a>.</li>\n</ul>\n<p><code>console.log</code> inside a component prints to the <strong><code>pyxle dev</code> terminal</strong> during the\nserver render (and to the browser console after hydration) — so a value that logs\ntwice is telling you it ran on both the server and the client.</p>\n<p>To step through the SSR worker itself, run it under the Node inspector by setting\n<code>NODE_OPTIONS</code>:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">NODE_OPTIONS=\"--inspect\" pyxle dev</code></pre></div><p>then open <code>chrome://inspect</code>. This is rarely needed for app code — it&#39;s for\ndiagnosing the render transport itself.</p>\n<h2 id=\"reading-the-compiled-output\">Reading the compiled output</h2><p>Pyxle compiles each <code>.pyxl</code> into a Python module and a JavaScript module under\nthe build directory (<code>.pyxle-build/</code> in dev, <code>dist/</code> for a production build).\nReading them demystifies &quot;where did my code go&quot;:</p>\n<ul>\n<li><code>.pyxle-build/server/pages/…​.py</code> — the <strong>Python</strong> half: your <code>@server</code> /\n<code>@action</code> functions with the runtime imports the compiler injected at the top\n(<code>from pyxle.runtime import server</code>, etc.).</li>\n<li><code>.pyxle-build/client/…​</code> — the <strong>JavaScript</strong> half: your component, ready for\nVite.</li>\n</ul>\n<p>In development, Python tracebacks already point at your <code>.pyxl</code> file and line\n(see <a href=\"/docs/guides/debugging-pyxl\">Debugging <code>.pyxl</code> files</a>). A traceback from a\n<strong>production build</strong> points at the compiled <code>.py</code>; the compiler preserves your\ncode verbatim below the injected header, so mapping back to your <code>.pyxl</code> is a\nsmall, constant offset. The build directory is disposable — delete it and the\nnext <code>pyxle dev</code>/<code>build</code> regenerates it.</p>\n<h2 id=\"static-checks\">Static checks</h2><p>Two commands catch problems before you run the page:</p>\n<ul>\n<li><strong><code>pyxle check</code></strong> — validates <code>.pyxl</code> syntax, Python semantics, and JSX. Note\nthat a green check does not prove a page <em>renders</em>: a component reading a loader\nkey that doesn&#39;t exist is a runtime error, not a static one.</li>\n<li><strong><code>pyxle typecheck</code></strong> — runs TypeScript over your compiled JSX when you&#39;ve opted\ninto TypeScript (see the <a href=\"/docs/guides/typescript\">TypeScript guide</a>).</li>\n</ul>\n<h2 id=\"common-symptoms\">Common symptoms</h2><table>\n<thead>\n<tr>\n<th>Symptom</th>\n<th>Likely cause</th>\n<th>Where to look</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Blank page, overlay shows a Python traceback</td>\n<td>Loader/action raised</td>\n<td><code>pyxle dev</code> terminal; add a <code>breakpoint()</code></td>\n</tr>\n<tr>\n<td><code>window is not defined</code></td>\n<td>Browser global at render scope</td>\n<td>The named <code>.pyxl</code>; use <code>useEffect</code>/<code>&lt;ClientOnly&gt;</code></td>\n</tr>\n<tr>\n<td><code>&#39;State&#39; object has no attribute &#39;db&#39;</code></td>\n<td>Missing plugin</td>\n<td><code>plugins</code> in <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td>Component data is <code>undefined</code></td>\n<td>Loader key ≠ component prop</td>\n<td>Compare the loader&#39;s return dict to the component&#39;s <code>data</code> usage</td>\n</tr>\n<tr>\n<td>Change didn&#39;t take effect</td>\n<td>Editing built output, or a stale build</td>\n<td>Edit the <code>.pyxl</code> source, not <code>.pyxle-build/</code></td>\n</tr>\n<tr>\n<td>Works in dev, fails in prod</td>\n<td>Debug-only behavior / missing env</td>\n<td>Server log (prod hides detail from the response)</td>\n</tr>\n</tbody></table>\n<h2 id=\"next-steps\">Next steps</h2><ul>\n<li><a href=\"/docs/guides/debugging-pyxl\">Debugging <code>.pyxl</code> files</a> — breakpoints in <code>.pyxl</code> source with VS Code or any DAP client</li>\n<li><a href=\"/docs/guides/error-handling\">Error Handling</a> — <code>LoaderError</code>, error boundaries, 404s</li>\n<li><a href=\"/docs/guides/testing\">Testing</a> — unit-test loaders and actions</li>\n<li><a href=\"/docs/guides/client-components\">Client Components</a> — browser-only code and <code>&lt;ClientOnly&gt;</code></li>\n</ul>\n","toc":[{"depth":2,"text":"Read the error first","slug":"read-the-error-first"},{"depth":2,"text":"Breakpoints in .pyxl files","slug":"breakpoints-in-pyxl-files"},{"depth":2,"text":"Debugging a loader or action (the Python side)","slug":"debugging-a-loader-or-action-the-python-side"},{"depth":2,"text":"Debugging rendering (the Node/SSR side)","slug":"debugging-rendering-the-nodessr-side"},{"depth":2,"text":"Reading the compiled output","slug":"reading-the-compiled-output"},{"depth":2,"text":"Static checks","slug":"static-checks"},{"depth":2,"text":"Common symptoms","slug":"common-symptoms"},{"depth":2,"text":"Next steps","slug":"next-steps"}],"path":"guides/debugging","markdown":"# Debugging\n\nA Pyxle app has two runtimes: **Python** (your `@server` loaders, `@action`\nhandlers, and the request pipeline) and **Node.js** (the SSR worker that renders\nyour React components to HTML). Knowing which side an error comes from tells you\nwhere to look. This guide covers both.\n\n## Read the error first\n\nIn development, Pyxle surfaces errors in three places at once:\n\n- **The browser error overlay** — a full-screen panel with the message, the file\n  and line, and a breadcrumb of what the framework was doing (loading, rendering,\n  head evaluation). This is the fastest signal for a broken page.\n- **The terminal** running `pyxle dev` — the same error, plus the Python\n  traceback for loader/action failures.\n- **The browser devtools console** — your server-side `logging` output is\n  forwarded here during `pyxle dev`, prefixed `[pyxle:server]`, so you can watch\n  server logs without leaving the page. `pyxle -v dev` also forwards `DEBUG`\n  records and framework-internal logs.\n\nIn production (`debug=false`) error responses are intentionally generic — no\nstack traces or file paths in the body. The full detail goes to the **server\nlog** instead. Check your process manager's logs (e.g. `journalctl -u myapp`).\n\n## Breakpoints in .pyxl files\n\nBeyond `pdb`, Pyxle has a full breakpoint-debugging story: `pyxle dev --inspect`\nhosts a debug server so VS Code (or any DAP client) can pause a request at a\nbreakpoint set **directly in a `.pyxl` file** — Python loaders/actions on the\nserver side, and the React half through the browser. That workflow has its own\nguide: [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md).\n\n## Debugging a loader or action (the Python side)\n\n`@server` and `@action` functions are plain `async` functions — debug them like\nany Python. Drop a breakpoint:\n\n```python\n@server\nasync def load_dashboard(request):\n    breakpoint()          # or: import pdb; pdb.set_trace()\n    data = await fetch_stats(request.state.db)\n    return {\"stats\": data}\n```\n\nRun `pyxle dev` **in a terminal you can type into** (not detached) and the `pdb`\nprompt appears there when the loader runs. Or add logging — it shows in the\nterminal *and* the browser console in dev:\n\n```python\nimport logging\nlog = logging.getLogger(__name__)\n\n@server\nasync def load_dashboard(request):\n    log.info(\"loading dashboard for %s\", request.url.path)\n    ...\n```\n\nTo unit-test a loader/action in isolation (no server, no browser), use the\n[`pyxle.testing` helpers](https://pyxle.dev/docs/guides/testing.md).\n\nTwo common Python-side errors have targeted messages:\n\n- **`request.state.<name>` is missing** (e.g. `request.state.db` without the\n  `pyxle-db` plugin) — the error names the attribute and the plugin that provides\n  it. Add the plugin to `pyxle.config.json`.\n- **A loader raising `LoaderError`** triggers the nearest `error.pyxl` boundary;\n  see [Error Handling](https://pyxle.dev/docs/guides/error-handling.md).\n\n## Debugging rendering (the Node/SSR side)\n\nYour React component runs **on the server** during SSR before it ever runs in the\nbrowser. Errors that mention rendering come from the Node worker:\n\n- **`window is not defined`** (or `document`, `localStorage`, …) — the component\n  touched a browser global at render scope. These don't exist during SSR. Move\n  the code into a `useEffect` or an event handler, or wrap the subtree in\n  `<ClientOnly>`. The dev error names your `.pyxl` file and the remedy — see\n  [Client Components](https://pyxle.dev/docs/guides/client-components.md).\n- **`Dynamic require of \"react\" is not supported`** — a dependency resolved to a\n  CommonJS-only build. Pyxle resolves dependencies ESM-first; a package that is\n  genuinely CommonJS-only reports an actionable error naming the module. See\n  [Third-party packages → CommonJS packages and SSR](https://pyxle.dev/docs/guides/third-party-packages.md#commonjs-packages-and-ssr).\n\n`console.log` inside a component prints to the **`pyxle dev` terminal** during the\nserver render (and to the browser console after hydration) — so a value that logs\ntwice is telling you it ran on both the server and the client.\n\nTo step through the SSR worker itself, run it under the Node inspector by setting\n`NODE_OPTIONS`:\n\n```bash\nNODE_OPTIONS=\"--inspect\" pyxle dev\n```\n\nthen open `chrome://inspect`. This is rarely needed for app code — it's for\ndiagnosing the render transport itself.\n\n## Reading the compiled output\n\nPyxle compiles each `.pyxl` into a Python module and a JavaScript module under\nthe build directory (`.pyxle-build/` in dev, `dist/` for a production build).\nReading them demystifies \"where did my code go\":\n\n- `.pyxle-build/server/pages/…​.py` — the **Python** half: your `@server` /\n  `@action` functions with the runtime imports the compiler injected at the top\n  (`from pyxle.runtime import server`, etc.).\n- `.pyxle-build/client/…​` — the **JavaScript** half: your component, ready for\n  Vite.\n\nIn development, Python tracebacks already point at your `.pyxl` file and line\n(see [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md)). A traceback from a\n**production build** points at the compiled `.py`; the compiler preserves your\ncode verbatim below the injected header, so mapping back to your `.pyxl` is a\nsmall, constant offset. The build directory is disposable — delete it and the\nnext `pyxle dev`/`build` regenerates it.\n\n## Static checks\n\nTwo commands catch problems before you run the page:\n\n- **`pyxle check`** — validates `.pyxl` syntax, Python semantics, and JSX. Note\n  that a green check does not prove a page *renders*: a component reading a loader\n  key that doesn't exist is a runtime error, not a static one.\n- **`pyxle typecheck`** — runs TypeScript over your compiled JSX when you've opted\n  into TypeScript (see the [TypeScript guide](https://pyxle.dev/docs/guides/typescript.md)).\n\n## Common symptoms\n\n| Symptom | Likely cause | Where to look |\n|---------|--------------|---------------|\n| Blank page, overlay shows a Python traceback | Loader/action raised | `pyxle dev` terminal; add a `breakpoint()` |\n| `window is not defined` | Browser global at render scope | The named `.pyxl`; use `useEffect`/`<ClientOnly>` |\n| `'State' object has no attribute 'db'` | Missing plugin | `plugins` in `pyxle.config.json` |\n| Component data is `undefined` | Loader key ≠ component prop | Compare the loader's return dict to the component's `data` usage |\n| Change didn't take effect | Editing built output, or a stale build | Edit the `.pyxl` source, not `.pyxle-build/` |\n| Works in dev, fails in prod | Debug-only behavior / missing env | Server log (prod hides detail from the response) |\n\n## Next steps\n\n- [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md) — breakpoints in `.pyxl` source with VS Code or any DAP client\n- [Error Handling](https://pyxle.dev/docs/guides/error-handling.md) — `LoaderError`, error boundaries, 404s\n- [Testing](https://pyxle.dev/docs/guides/testing.md) — unit-test loaders and actions\n- [Client Components](https://pyxle.dev/docs/guides/client-components.md) — browser-only code and `<ClientOnly>`\n","prev":{"title":"Testing","path":"guides/testing"},"next":{"title":"Debugging .pyxl files","path":"guides/debugging-pyxl"}}
\ No newline at end of file
+{"title":"Debugging","description":"A Pyxle app has two runtimes: **Python** (your `@server` loaders, `@action` handlers, and the request pipeline) and **Node.js** (the SSR worker that renders your React components to HTML). Knowing whi","html":"<p>A Pyxle app has two runtimes: <strong>Python</strong> (your <code>@server</code> loaders, <code>@action</code>\nhandlers, and the request pipeline) and <strong>Node.js</strong> (the SSR worker that renders\nyour React components to HTML). Knowing which side an error comes from tells you\nwhere to look. This guide covers both — including how to set a breakpoint\ndirectly in a <code>.pyxl</code> file, on a line inside a <code>@server</code> loader <em>and</em> on a line\ninside the JSX below it, and have both bind.</p>\n<p>There is no bespoke Pyxle debugger: <code>pyxle dev --inspect</code> exposes the Python half\nto any debugger, dev source maps expose the React half to the browser, and the\nVS Code extension turns each into one launch.</p>\n<hr>\n<h2 id=\"install-the-vs-code-extension\">Install the VS Code extension</h2><p>Breakpoint debugging from the editor needs <strong><a href=\"https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools\" target=\"_blank\" rel=\"noreferrer\">Pyxle Language Tools</a></strong>\n(0.3.0 or newer). Install it from the command line:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">code --install-extension pyxle.pyxle-language-tools</code></pre></div><p>…or search for <strong>Pyxle Language Tools</strong> in the Extensions view (<code>Ctrl+Shift+X</code> /\n<code>Cmd+Shift+X</code>), or install it from the <a href=\"https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools\" target=\"_blank\" rel=\"noreferrer\">VS Code Marketplace</a> in a browser.</p>\n<p>Two more requirements, both one-time:</p>\n<ul>\n<li><strong>pyxle-framework 0.8.0 or newer</strong> in the environment VS Code has selected. The\ndebugger relies on line mapping added in 0.8.0 and launches the dev server as\n<code>python -m pyxle</code>, which earlier versions don&#39;t provide. Upgrade with\n<code>pip install --upgrade pyxle-framework</code>.</li>\n<li><strong>The Python extension</strong> (<code>ms-python.python</code>) for Python-side breakpoints. The\ndebugger prompts you if it&#39;s missing, and still debugs the React side without it.</li>\n</ul>\n<p>Nothing else to install — debugpy ships with the framework.</p>\n<p>The extension also gives you syntax highlighting, diagnostics, completions,\nhover, go-to-definition and formatting for <code>.pyxl</code> files; see\n<a href=\"/docs/guides/editor-setup\">Editor setup</a> for the full feature list and the language-server\ndetails.</p>\n<hr>\n<h2 id=\"quick-start-breakpoints-in-a-pyxl-file\">Quick start: breakpoints in a .pyxl file</h2><p>Open a <code>.pyxl</code> file and press <strong>F5</strong>. With no <code>launch.json</code> yet, Pyxle asks which\nhalf to debug — <strong>Backend — Python</strong> or <strong>Frontend — React</strong>. Pick one, or commit\nthe configurations to skip the prompt:</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app\" },\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app (React browser)\", \"server\": false }\n  ]\n}</code></pre></div><p>Choosing <strong>Backend</strong> runs your dev server under the Python debugger — one clean\ndebug session that VS Code owns. A breakpoint in a loader or action pauses the\nrequest with the <code>.pyxl</code> frame in the stack. Once the server is ready, your app\nopens in the browser. <strong>Stop</strong>, <strong>Restart</strong>, and <strong>Pause</strong> all act on that single\nsession — Stop tears the whole server (Vite, SSR workers) down with it.</p>\n<p><strong>To debug the React half too</strong>, run the <strong>&quot;Debug Pyxle app (React browser)&quot;</strong>\nconfiguration (it&#39;s just <code>&quot;server&quot;: false</code>) — a standalone browser session pointed\nat the running dev server. A breakpoint you set in the component pauses there, in\nthe same <code>.pyxl</code> file you set the loader breakpoint in. It&#39;s a <em>separate</em> session\non purpose: keeping the browser out of the Python session&#39;s toolbar means each\nside has clean, unambiguous Stop / Restart / Pause.</p>\n<p>If the Frontend session had to start its own <code>pyxle dev</code> (nothing was running),\n<strong>stopping it offers to stop that server too</strong> — a one-click &quot;Stop server&quot;.\nRestarting the Frontend session keeps the server up. If instead it attached to a\nserver something else started (Backend, or a <code>pyxle dev</code> you ran yourself),\nstopping Frontend leaves that server running untouched.</p>\n<p>To debug <strong>both</strong> halves, start <strong>Backend</strong> first — it runs the dev server — then\nstart <strong>Frontend</strong>, which attaches its browser to that same server. Stop on either\nside then does the right thing: stopping Frontend leaves the server (Backend owns\nit), stopping Backend tears it down. Frontend on its own works standalone too;\njust don&#39;t start Backend on top of a Frontend-started server, or they&#39;ll race for\nthe port (the second fails to bind with &quot;address already in use&quot; — stop the first,\nthen start the other).</p>\n<p>The launch configuration accepts a few knobs:</p>\n<table>\n<thead>\n<tr>\n<th>Property</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>cwd</code></td>\n<td><code>${workspaceFolder}</code></td>\n<td>Pyxle project root (contains <code>pages/</code> and <code>pyxle.config.json</code>).</td>\n</tr>\n<tr>\n<td><code>server</code></td>\n<td><code>true</code></td>\n<td>Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set <code>false</code> to debug <strong>only</strong> the React side in a standalone browser session.</td>\n</tr>\n<tr>\n<td><code>browser</code></td>\n<td><code>true</code></td>\n<td>When debugging Python, open the app in your browser once the server is ready.</td>\n</tr>\n<tr>\n<td><code>url</code></td>\n<td>dev server root</td>\n<td>Page to open.</td>\n</tr>\n<tr>\n<td><code>args</code></td>\n<td><code>[]</code></td>\n<td>Extra arguments passed to <code>pyxle dev</code> (e.g. <code>[&quot;--port&quot;, &quot;3000&quot;]</code>).</td>\n</tr>\n<tr>\n<td><code>justMyCode</code></td>\n<td><code>true</code></td>\n<td>Keep stepping inside your own code. Set <code>false</code> to step into framework internals.</td>\n</tr>\n</tbody></table>\n<p>To attach to an already-running server instead of launching one, use\n<code>&quot;request&quot;: &quot;attach&quot;</code> (see <a href=\"#attaching-from-any-dap-client\">Attaching from any DAP client</a>).</p>\n<p>The extension also contributes a <strong>&quot;Pyxle: Open Studio&quot;</strong> command, which opens the\nrunning server&#39;s <a href=\"/docs/guides/studio\">Studio dashboard</a> from the command palette.</p>\n<hr>\n<h2 id=\"read-the-error-first\">Read the error first</h2><p>In development, Pyxle surfaces errors in three places at once:</p>\n<ul>\n<li><strong>The browser error overlay</strong> — a full-screen panel with the message, the file\nand line, and a breadcrumb of what the framework was doing (loading, rendering,\nhead evaluation). This is the fastest signal for a broken page.</li>\n<li><strong>The terminal</strong> running <code>pyxle dev</code> — the same error, plus the Python\ntraceback for loader/action failures.</li>\n<li><strong>The browser devtools console</strong> — your server-side <code>logging</code> output is\nforwarded here during <code>pyxle dev</code>, prefixed <code>[pyxle:server]</code>, so you can watch\nserver logs without leaving the page. <code>pyxle -v dev</code> also forwards <code>DEBUG</code>\nrecords and framework-internal logs.</li>\n</ul>\n<p>In production (<code>debug=false</code>) error responses are intentionally generic — no\nstack traces or file paths in the body. The full detail goes to the <strong>server\nlog</strong> instead. Check your process manager&#39;s logs (e.g. <code>journalctl -u myapp</code>).</p>\n<hr>\n<h2 id=\"debugging-a-loader-or-action-the-python-side\">Debugging a loader or action (the Python side)</h2><p><code>@server</code> and <code>@action</code> functions are plain <code>async</code> functions — debug them like\nany Python. Set a breakpoint in the editor as above, or drop one in code:</p>\n<div class=\"code-block\" data-lang=\"python\"><pre><code class=\"language-python\">@server\nasync def load_dashboard(request):\n    breakpoint()          # or: import pdb; pdb.set_trace()\n    data = await fetch_stats(request.state.db)\n    return {\"stats\": data}</code></pre></div><p>For <code>pdb</code>, run <code>pyxle dev</code> <strong>in a terminal you can type into</strong> (not detached) and\nthe prompt appears there when the loader runs. Or add logging — it shows in the\nterminal <em>and</em> the browser console in dev:</p>\n<div class=\"code-block\" data-lang=\"python\"><pre><code class=\"language-python\">import logging\nlog = logging.getLogger(__name__)\n\n@server\nasync def load_dashboard(request):\n    log.info(\"loading dashboard for %s\", request.url.path)\n    ...</code></pre></div><p>To unit-test a loader/action in isolation (no server, no browser), use the\n<a href=\"/docs/guides/testing\"><code>pyxle.testing</code> helpers</a>.</p>\n<p>Two common Python-side errors have targeted messages:</p>\n<ul>\n<li><strong><code>request.state.&lt;name&gt;</code> is missing</strong> (e.g. <code>request.state.db</code> without the\n<code>pyxle-db</code> plugin) — the error names the attribute and the plugin that provides\nit. Add the plugin to <code>pyxle.config.json</code>.</li>\n<li><strong>A loader raising <code>LoaderError</code></strong> triggers the nearest <code>error.pyxl</code> boundary;\nsee <a href=\"/docs/guides/error-handling\">Error Handling</a>.</li>\n</ul>\n<hr>\n<h2 id=\"debugging-rendering-the-nodessr-side\">Debugging rendering (the Node/SSR side)</h2><p>Your React component runs <strong>on the server</strong> during SSR before it ever runs in the\nbrowser. Errors that mention rendering come from the Node worker:</p>\n<ul>\n<li><strong><code>window is not defined</code></strong> (or <code>document</code>, <code>localStorage</code>, …) — the component\ntouched a browser global at render scope. These don&#39;t exist during SSR. Move\nthe code into a <code>useEffect</code> or an event handler, or wrap the subtree in\n<code>&lt;ClientOnly&gt;</code>. The dev error names your <code>.pyxl</code> file and the remedy — see\n<a href=\"/docs/guides/client-components\">Client Components</a>.</li>\n<li><strong><code>Dynamic require of &quot;react&quot; is not supported</code></strong> — a dependency resolved to a\nCommonJS-only build. Pyxle resolves dependencies ESM-first; a package that is\ngenuinely CommonJS-only reports an actionable error naming the module. See\n<a href=\"/docs/guides/third-party-packages#commonjs-packages-and-ssr\">Third-party packages → CommonJS packages and SSR</a>.</li>\n</ul>\n<p><code>console.log</code> inside a component prints to the <strong><code>pyxle dev</code> terminal</strong> during the\nserver render (and to the browser console after hydration) — so a value that logs\ntwice is telling you it ran on both the server and the client.</p>\n<p>To step through the SSR worker itself, run it under the Node inspector by setting\n<code>NODE_OPTIONS</code>:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">NODE_OPTIONS=\"--inspect\" pyxle dev</code></pre></div><p>then open <code>chrome://inspect</code>. This is rarely needed for app code — it&#39;s for\ndiagnosing the render transport itself.</p>\n<hr>\n<h2 id=\"how-the-breakpoint-mapping-works\">How the breakpoint mapping works</h2><p>The feature is two stock debuggers plus line mapping, which is why it works so\nbroadly:</p>\n<ul>\n<li><strong>The Python half</strong> (<code>@server</code> loaders, <code>@action</code> handlers). The compiler embeds\na line map in every generated server module, and in development the server\nimports those modules with <code>co_filename</code> and line numbers remapped to the\noriginal <code>.pyxl</code> source. To <a href=\"https://github.com/microsoft/debugpy\" target=\"_blank\" rel=\"noreferrer\">debugpy</a> the\nrunning code simply <em>is</em> your <code>.pyxl</code> file, so breakpoints set there bind\nnatively. The default launch runs the dev server under debugpy directly;\n<code>--inspect</code> instead hosts a debugpy server for clients to attach to.</li>\n<li><strong>The React half</strong> (the JSX in the same file). The compiler writes a source-map\nsidecar for each generated <code>.jsx</code> module, and the dev Vite config includes a\nsmall dev-only plugin that attaches those maps pointing back at the real <code>.pyxl</code>\nfile on disk. VS Code&#39;s built-in js-debug resolves that file and binds\nbreakpoints in it; browser devtools map every position the same way. The map is\nfetched by the browser, so it carries only the JSX lines — the <code>@server</code> and\n<code>@action</code> Python in the same file is never sent to a client.</li>\n</ul>\n<p>Both mappings exist only in development. A production build ships neither.</p>\n<hr>\n<h2 id=\"cli-reference\">CLI reference</h2><p>The debugger flags live on <code>pyxle dev</code> (and <code>pyxle studio</code>, which accepts\n<code>--inspect</code> and <code>--inspect-port</code>):</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle dev --inspect</code></pre></div><table>\n<thead>\n<tr>\n<th>Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--inspect</code> / <code>--no-inspect</code></td>\n<td><code>false</code></td>\n<td>Host a debugpy debug server inside the dev-server process, bound to <code>127.0.0.1</code>. debugpy ships with the framework.</td>\n</tr>\n<tr>\n<td><code>--inspect-port</code></td>\n<td><code>5678</code></td>\n<td>Port for the debug server. When it&#39;s busy, Pyxle falls back to an ephemeral port and records the actual endpoint in the discovery file, so editor attach flows keep working.</td>\n</tr>\n<tr>\n<td><code>--inspect-wait</code> / <code>--no-inspect-wait</code></td>\n<td><code>false</code></td>\n<td>With <code>--inspect</code>: block startup until a debugger attaches — for breakpoints in code that runs during boot.</td>\n</tr>\n</tbody></table>\n<p>Only the dev-server process is debugged: the debugger environment is never\ninjected into subprocesses (Vite, SSR workers, or anything a loader shells out to).</p>\n<hr>\n<h2 id=\"attaching-from-any-dap-client\">Attaching from any DAP client</h2><p>debugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a\nrequirement. From neovim (<code>nvim-dap</code>), Emacs (<code>dape</code>), or any other DAP client,\nattach to the endpoint <code>--inspect</code> printed — the equivalent of:</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"type\": \"debugpy\",\n  \"request\": \"attach\",\n  \"connect\": { \"host\": \"127.0.0.1\", \"port\": 5678 }\n}</code></pre></div><p>Set breakpoints in <code>.pyxl</code> files by their real path. Because the server&#39;s code\nobjects already carry <code>.pyxl</code> filenames, no path mappings or source translations\nare needed — stack frames, stepping, and <code>evaluate</code> in a paused loader all just\nwork.</p>\n<hr>\n<h2 id=\"tracebacks-point-at-pyxl\">Tracebacks point at .pyxl</h2><p>The same line mapping improves life with no debugger attached at all: in\ndevelopment, a Python traceback from a loader or action names your <code>.pyxl</code> file\nand line — not a compiled module under <code>.pyxle-build/</code>. The terminal, the browser\nerror overlay, and your logs all agree on where the error actually is.</p>\n<hr>\n<h2 id=\"the-discovery-file\">The discovery file</h2><p>While running, the dev server writes <code>.pyxle-build/dev-server.json</code> describing\nitself, and removes it on shutdown. This is what editor tooling (the extension&#39;s\nF5 flow and &quot;Open Studio&quot;) reads instead of guessing ports:</p>\n<table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Type</th>\n<th>Meaning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>pid</code></td>\n<td><code>integer</code></td>\n<td>Dev-server process id.</td>\n</tr>\n<tr>\n<td><code>version</code></td>\n<td><code>string</code></td>\n<td>Pyxle version.</td>\n</tr>\n<tr>\n<td><code>startedAt</code></td>\n<td><code>number</code></td>\n<td>Unix timestamp of server start.</td>\n</tr>\n<tr>\n<td><code>projectRoot</code></td>\n<td><code>string</code></td>\n<td>Absolute path of the project.</td>\n</tr>\n<tr>\n<td><code>server</code></td>\n<td><code>object</code></td>\n<td><code>{ &quot;host&quot;, &quot;port&quot; }</code> of the Starlette server.</td>\n</tr>\n<tr>\n<td><code>vite</code></td>\n<td><code>object</code></td>\n<td><code>{ &quot;host&quot;, &quot;port&quot; }</code> of the Vite dev server.</td>\n</tr>\n<tr>\n<td><code>url</code></td>\n<td><code>string</code></td>\n<td>Browser-reachable base URL.</td>\n</tr>\n<tr>\n<td><code>studio</code></td>\n<td><code>string</code> | <code>null</code></td>\n<td>Studio dashboard URL (<code>null</code> when Studio is disabled).</td>\n</tr>\n<tr>\n<td><code>debugpy</code></td>\n<td><code>object</code> | <code>null</code></td>\n<td><code>{ &quot;host&quot;, &quot;port&quot; }</code> of the debug server (<code>null</code> without <code>--inspect</code>).</td>\n</tr>\n</tbody></table>\n<p>The file is written atomically, and a failed write never takes down the server.</p>\n<hr>\n<h2 id=\"reading-the-compiled-output\">Reading the compiled output</h2><p>Pyxle compiles each <code>.pyxl</code> into a Python module and a JavaScript module under\nthe build directory (<code>.pyxle-build/</code> in dev, <code>dist/</code> for a production build).\nReading them demystifies &quot;where did my code go&quot;:</p>\n<ul>\n<li><code>.pyxle-build/server/pages/…​.py</code> — the <strong>Python</strong> half: your <code>@server</code> /\n<code>@action</code> functions with the runtime imports the compiler injected at the top\n(<code>from pyxle.runtime import server</code>, etc.).</li>\n<li><code>.pyxle-build/client/…​</code> — the <strong>JavaScript</strong> half: your component, ready for\nVite.</li>\n</ul>\n<p>In development you rarely need this, because tracebacks and breakpoints already\npoint at your <code>.pyxl</code>. A traceback from a <strong>production build</strong> points at the\ncompiled <code>.py</code>; the compiler preserves your code verbatim below the injected\nheader, so mapping back to your <code>.pyxl</code> is a small, constant offset. The build\ndirectory is disposable — delete it and the next <code>pyxle dev</code>/<code>build</code> regenerates it.</p>\n<hr>\n<h2 id=\"static-checks\">Static checks</h2><p>Two commands catch problems before you run the page:</p>\n<ul>\n<li><strong><code>pyxle check</code></strong> — validates <code>.pyxl</code> syntax, Python semantics, and JSX. Note\nthat a green check does not prove a page <em>renders</em>: a component reading a loader\nkey that doesn&#39;t exist is a runtime error, not a static one.</li>\n<li><strong><code>pyxle typecheck</code></strong> — runs TypeScript over your compiled JSX when you&#39;ve opted\ninto TypeScript (see the <a href=\"/docs/guides/typescript\">TypeScript guide</a>).</li>\n</ul>\n<hr>\n<h2 id=\"caveats\">Caveats</h2><p>Worth knowing before you rely on breakpoint debugging:</p>\n<ul>\n<li><strong>A paused breakpoint pauses the whole server.</strong> <code>pyxle dev</code> is a single\nprocess, so while you sit at a breakpoint every in-flight request waits. That&#39;s\nthe right trade-off for development — and one reason production never hosts a\ndebugger.</li>\n<li><strong><code>justMyCode</code> defaults to <code>true</code>.</strong> Stepping stays inside your own code; set it\nto <code>false</code> in the launch configuration to step into Pyxle&#39;s internals.</li>\n<li><strong>React debugging happens in the browser, not the SSR worker.</strong> Your component\nrenders first in the Node SSR process, but the debugger doesn&#39;t attach there —\nit&#39;s the same code with the same source maps in the browser, which is where you\ndebug it. Server-render <code>console.log</code> output still prints to the <code>pyxle dev</code>\nterminal (see <a href=\"#debugging-rendering-the-nodessr-side\">the SSR side</a>).</li>\n<li><strong>Production is untouched.</strong> <code>pyxle serve</code> never remaps line numbers and never\nhosts debugpy, regardless of flags or config.</li>\n</ul>\n<hr>\n<h2 id=\"troubleshooting\">Troubleshooting</h2><p><strong>&quot;No module named pyxle&quot; when you press F5.</strong> VS Code has a Python interpreter\nselected that doesn&#39;t have pyxle installed — a common split when pyxle lives in\none environment (a virtualenv, pyenv, or system Python) while VS Code points at\nanother. The launch runs <code>python -m pyxle dev</code> under the <em>selected</em> interpreter,\nso it has to be the one where <code>pyxle</code> is installed. The extension checks this\nbefore launching and offers a <strong>Select Interpreter</strong> button; you can also run\n<strong>Python: Select Interpreter</strong> from the command palette and pick the environment\nyour terminal&#39;s <code>pyxle</code> command uses (<code>which pyxle</code> / <code>where pyxle</code> shows it).</p>\n<p><strong>&quot;No module named pyxle.__main__&quot;, or the debugger says to upgrade.</strong> The\nselected interpreter has pyxle, but a version older than 0.8.0. Run\n<code>pip install --upgrade pyxle-framework</code> in that environment.</p>\n<hr>\n<h2 id=\"common-symptoms\">Common symptoms</h2><table>\n<thead>\n<tr>\n<th>Symptom</th>\n<th>Likely cause</th>\n<th>Where to look</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Blank page, overlay shows a Python traceback</td>\n<td>Loader/action raised</td>\n<td><code>pyxle dev</code> terminal; set a breakpoint in the loader</td>\n</tr>\n<tr>\n<td><code>window is not defined</code></td>\n<td>Browser global at render scope</td>\n<td>The named <code>.pyxl</code>; use <code>useEffect</code>/<code>&lt;ClientOnly&gt;</code></td>\n</tr>\n<tr>\n<td><code>&#39;State&#39; object has no attribute &#39;db&#39;</code></td>\n<td>Missing plugin</td>\n<td><code>plugins</code> in <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td>Component data is <code>undefined</code></td>\n<td>Loader key ≠ component prop</td>\n<td>Compare the loader&#39;s return dict to the component&#39;s <code>data</code> usage</td>\n</tr>\n<tr>\n<td>Change didn&#39;t take effect</td>\n<td>Editing built output, or a stale build</td>\n<td>Edit the <code>.pyxl</code> source, not <code>.pyxle-build/</code></td>\n</tr>\n<tr>\n<td>Works in dev, fails in prod</td>\n<td>Debug-only behavior / missing env</td>\n<td>Server log (prod hides detail from the response)</td>\n</tr>\n<tr>\n<td>Breakpoint never binds</td>\n<td>Wrong interpreter, or framework older than 0.8.0</td>\n<td>See <a href=\"#troubleshooting\">Troubleshooting</a></td>\n</tr>\n</tbody></table>\n<hr>\n<h2 id=\"next-steps\">Next steps</h2><ul>\n<li><a href=\"/docs/guides/editor-setup\">Editor setup</a> — installing the extension and language server, and everything else it does</li>\n<li><a href=\"/docs/guides/studio\">Pyxle Studio</a> — the dev dashboard; <code>pyxle studio --inspect</code> runs both</li>\n<li><a href=\"/docs/guides/error-handling\">Error Handling</a> — <code>LoaderError</code>, error boundaries, 404s</li>\n<li><a href=\"/docs/guides/testing\">Testing</a> — unit-test loaders and actions</li>\n<li><a href=\"/docs/guides/client-components\">Client Components</a> — browser-only code and <code>&lt;ClientOnly&gt;</code></li>\n<li><a href=\"/docs/reference/cli#pyxle-dev\">CLI reference → <code>pyxle dev</code></a> — every dev-server flag</li>\n</ul>\n","toc":[{"depth":2,"text":"Install the VS Code extension","slug":"install-the-vs-code-extension"},{"depth":2,"text":"Quick start: breakpoints in a .pyxl file","slug":"quick-start-breakpoints-in-a-pyxl-file"},{"depth":2,"text":"Read the error first","slug":"read-the-error-first"},{"depth":2,"text":"Debugging a loader or action (the Python side)","slug":"debugging-a-loader-or-action-the-python-side"},{"depth":2,"text":"Debugging rendering (the Node/SSR side)","slug":"debugging-rendering-the-nodessr-side"},{"depth":2,"text":"How the breakpoint mapping works","slug":"how-the-breakpoint-mapping-works"},{"depth":2,"text":"CLI reference","slug":"cli-reference"},{"depth":2,"text":"Attaching from any DAP client","slug":"attaching-from-any-dap-client"},{"depth":2,"text":"Tracebacks point at .pyxl","slug":"tracebacks-point-at-pyxl"},{"depth":2,"text":"The discovery file","slug":"the-discovery-file"},{"depth":2,"text":"Reading the compiled output","slug":"reading-the-compiled-output"},{"depth":2,"text":"Static checks","slug":"static-checks"},{"depth":2,"text":"Caveats","slug":"caveats"},{"depth":2,"text":"Troubleshooting","slug":"troubleshooting"},{"depth":2,"text":"Common symptoms","slug":"common-symptoms"},{"depth":2,"text":"Next steps","slug":"next-steps"}],"path":"guides/debugging","markdown":"# Debugging\n\nA Pyxle app has two runtimes: **Python** (your `@server` loaders, `@action`\nhandlers, and the request pipeline) and **Node.js** (the SSR worker that renders\nyour React components to HTML). Knowing which side an error comes from tells you\nwhere to look. This guide covers both — including how to set a breakpoint\ndirectly in a `.pyxl` file, on a line inside a `@server` loader *and* on a line\ninside the JSX below it, and have both bind.\n\nThere is no bespoke Pyxle debugger: `pyxle dev --inspect` exposes the Python half\nto any debugger, dev source maps expose the React half to the browser, and the\nVS Code extension turns each into one launch.\n\n---\n\n## Install the VS Code extension\n\nBreakpoint debugging from the editor needs **[Pyxle Language Tools][ext]**\n(0.3.0 or newer). Install it from the command line:\n\n```bash\ncode --install-extension pyxle.pyxle-language-tools\n```\n\n…or search for **Pyxle Language Tools** in the Extensions view (`Ctrl+Shift+X` /\n`Cmd+Shift+X`), or install it from the [VS Code Marketplace][ext] in a browser.\n\nTwo more requirements, both one-time:\n\n- **pyxle-framework 0.8.0 or newer** in the environment VS Code has selected. The\n  debugger relies on line mapping added in 0.8.0 and launches the dev server as\n  `python -m pyxle`, which earlier versions don't provide. Upgrade with\n  `pip install --upgrade pyxle-framework`.\n- **The Python extension** (`ms-python.python`) for Python-side breakpoints. The\n  debugger prompts you if it's missing, and still debugs the React side without it.\n\nNothing else to install — debugpy ships with the framework.\n\nThe extension also gives you syntax highlighting, diagnostics, completions,\nhover, go-to-definition and formatting for `.pyxl` files; see\n[Editor setup](https://pyxle.dev/docs/guides/editor-setup.md) for the full feature list and the language-server\ndetails.\n\n[ext]: https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools\n\n---\n\n## Quick start: breakpoints in a .pyxl file\n\nOpen a `.pyxl` file and press **F5**. With no `launch.json` yet, Pyxle asks which\nhalf to debug — **Backend — Python** or **Frontend — React**. Pick one, or commit\nthe configurations to skip the prompt:\n\n```json\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app\" },\n    { \"type\": \"pyxle\", \"request\": \"launch\", \"name\": \"Debug Pyxle app (React browser)\", \"server\": false }\n  ]\n}\n```\n\nChoosing **Backend** runs your dev server under the Python debugger — one clean\ndebug session that VS Code owns. A breakpoint in a loader or action pauses the\nrequest with the `.pyxl` frame in the stack. Once the server is ready, your app\nopens in the browser. **Stop**, **Restart**, and **Pause** all act on that single\nsession — Stop tears the whole server (Vite, SSR workers) down with it.\n\n**To debug the React half too**, run the **\"Debug Pyxle app (React browser)\"**\nconfiguration (it's just `\"server\": false`) — a standalone browser session pointed\nat the running dev server. A breakpoint you set in the component pauses there, in\nthe same `.pyxl` file you set the loader breakpoint in. It's a *separate* session\non purpose: keeping the browser out of the Python session's toolbar means each\nside has clean, unambiguous Stop / Restart / Pause.\n\nIf the Frontend session had to start its own `pyxle dev` (nothing was running),\n**stopping it offers to stop that server too** — a one-click \"Stop server\".\nRestarting the Frontend session keeps the server up. If instead it attached to a\nserver something else started (Backend, or a `pyxle dev` you ran yourself),\nstopping Frontend leaves that server running untouched.\n\nTo debug **both** halves, start **Backend** first — it runs the dev server — then\nstart **Frontend**, which attaches its browser to that same server. Stop on either\nside then does the right thing: stopping Frontend leaves the server (Backend owns\nit), stopping Backend tears it down. Frontend on its own works standalone too;\njust don't start Backend on top of a Frontend-started server, or they'll race for\nthe port (the second fails to bind with \"address already in use\" — stop the first,\nthen start the other).\n\nThe launch configuration accepts a few knobs:\n\n| Property | Default | Description |\n|----------|---------|-------------|\n| `cwd` | `${workspaceFolder}` | Pyxle project root (contains `pages/` and `pyxle.config.json`). |\n| `server` | `true` | Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set `false` to debug **only** the React side in a standalone browser session. |\n| `browser` | `true` | When debugging Python, open the app in your browser once the server is ready. |\n| `url` | dev server root | Page to open. |\n| `args` | `[]` | Extra arguments passed to `pyxle dev` (e.g. `[\"--port\", \"3000\"]`). |\n| `justMyCode` | `true` | Keep stepping inside your own code. Set `false` to step into framework internals. |\n\nTo attach to an already-running server instead of launching one, use\n`\"request\": \"attach\"` (see [Attaching from any DAP client](#attaching-from-any-dap-client)).\n\nThe extension also contributes a **\"Pyxle: Open Studio\"** command, which opens the\nrunning server's [Studio dashboard](https://pyxle.dev/docs/guides/studio.md) from the command palette.\n\n---\n\n## Read the error first\n\nIn development, Pyxle surfaces errors in three places at once:\n\n- **The browser error overlay** — a full-screen panel with the message, the file\n  and line, and a breadcrumb of what the framework was doing (loading, rendering,\n  head evaluation). This is the fastest signal for a broken page.\n- **The terminal** running `pyxle dev` — the same error, plus the Python\n  traceback for loader/action failures.\n- **The browser devtools console** — your server-side `logging` output is\n  forwarded here during `pyxle dev`, prefixed `[pyxle:server]`, so you can watch\n  server logs without leaving the page. `pyxle -v dev` also forwards `DEBUG`\n  records and framework-internal logs.\n\nIn production (`debug=false`) error responses are intentionally generic — no\nstack traces or file paths in the body. The full detail goes to the **server\nlog** instead. Check your process manager's logs (e.g. `journalctl -u myapp`).\n\n---\n\n## Debugging a loader or action (the Python side)\n\n`@server` and `@action` functions are plain `async` functions — debug them like\nany Python. Set a breakpoint in the editor as above, or drop one in code:\n\n```python\n@server\nasync def load_dashboard(request):\n    breakpoint()          # or: import pdb; pdb.set_trace()\n    data = await fetch_stats(request.state.db)\n    return {\"stats\": data}\n```\n\nFor `pdb`, run `pyxle dev` **in a terminal you can type into** (not detached) and\nthe prompt appears there when the loader runs. Or add logging — it shows in the\nterminal *and* the browser console in dev:\n\n```python\nimport logging\nlog = logging.getLogger(__name__)\n\n@server\nasync def load_dashboard(request):\n    log.info(\"loading dashboard for %s\", request.url.path)\n    ...\n```\n\nTo unit-test a loader/action in isolation (no server, no browser), use the\n[`pyxle.testing` helpers](https://pyxle.dev/docs/guides/testing.md).\n\nTwo common Python-side errors have targeted messages:\n\n- **`request.state.<name>` is missing** (e.g. `request.state.db` without the\n  `pyxle-db` plugin) — the error names the attribute and the plugin that provides\n  it. Add the plugin to `pyxle.config.json`.\n- **A loader raising `LoaderError`** triggers the nearest `error.pyxl` boundary;\n  see [Error Handling](https://pyxle.dev/docs/guides/error-handling.md).\n\n---\n\n## Debugging rendering (the Node/SSR side)\n\nYour React component runs **on the server** during SSR before it ever runs in the\nbrowser. Errors that mention rendering come from the Node worker:\n\n- **`window is not defined`** (or `document`, `localStorage`, …) — the component\n  touched a browser global at render scope. These don't exist during SSR. Move\n  the code into a `useEffect` or an event handler, or wrap the subtree in\n  `<ClientOnly>`. The dev error names your `.pyxl` file and the remedy — see\n  [Client Components](https://pyxle.dev/docs/guides/client-components.md).\n- **`Dynamic require of \"react\" is not supported`** — a dependency resolved to a\n  CommonJS-only build. Pyxle resolves dependencies ESM-first; a package that is\n  genuinely CommonJS-only reports an actionable error naming the module. See\n  [Third-party packages → CommonJS packages and SSR](https://pyxle.dev/docs/guides/third-party-packages.md#commonjs-packages-and-ssr).\n\n`console.log` inside a component prints to the **`pyxle dev` terminal** during the\nserver render (and to the browser console after hydration) — so a value that logs\ntwice is telling you it ran on both the server and the client.\n\nTo step through the SSR worker itself, run it under the Node inspector by setting\n`NODE_OPTIONS`:\n\n```bash\nNODE_OPTIONS=\"--inspect\" pyxle dev\n```\n\nthen open `chrome://inspect`. This is rarely needed for app code — it's for\ndiagnosing the render transport itself.\n\n---\n\n## How the breakpoint mapping works\n\nThe feature is two stock debuggers plus line mapping, which is why it works so\nbroadly:\n\n- **The Python half** (`@server` loaders, `@action` handlers). The compiler embeds\n  a line map in every generated server module, and in development the server\n  imports those modules with `co_filename` and line numbers remapped to the\n  original `.pyxl` source. To [debugpy](https://github.com/microsoft/debugpy) the\n  running code simply *is* your `.pyxl` file, so breakpoints set there bind\n  natively. The default launch runs the dev server under debugpy directly;\n  `--inspect` instead hosts a debugpy server for clients to attach to.\n- **The React half** (the JSX in the same file). The compiler writes a source-map\n  sidecar for each generated `.jsx` module, and the dev Vite config includes a\n  small dev-only plugin that attaches those maps pointing back at the real `.pyxl`\n  file on disk. VS Code's built-in js-debug resolves that file and binds\n  breakpoints in it; browser devtools map every position the same way. The map is\n  fetched by the browser, so it carries only the JSX lines — the `@server` and\n  `@action` Python in the same file is never sent to a client.\n\nBoth mappings exist only in development. A production build ships neither.\n\n---\n\n## CLI reference\n\nThe debugger flags live on `pyxle dev` (and `pyxle studio`, which accepts\n`--inspect` and `--inspect-port`):\n\n```bash\npyxle dev --inspect\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server inside the dev-server process, bound to `127.0.0.1`. debugpy ships with the framework. |\n| `--inspect-port` | `5678` | Port for the debug server. When it's busy, Pyxle falls back to an ephemeral port and records the actual endpoint in the discovery file, so editor attach flows keep working. |\n| `--inspect-wait` / `--no-inspect-wait` | `false` | With `--inspect`: block startup until a debugger attaches — for breakpoints in code that runs during boot. |\n\nOnly the dev-server process is debugged: the debugger environment is never\ninjected into subprocesses (Vite, SSR workers, or anything a loader shells out to).\n\n---\n\n## Attaching from any DAP client\n\ndebugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a\nrequirement. From neovim (`nvim-dap`), Emacs (`dape`), or any other DAP client,\nattach to the endpoint `--inspect` printed — the equivalent of:\n\n```json\n{\n  \"type\": \"debugpy\",\n  \"request\": \"attach\",\n  \"connect\": { \"host\": \"127.0.0.1\", \"port\": 5678 }\n}\n```\n\nSet breakpoints in `.pyxl` files by their real path. Because the server's code\nobjects already carry `.pyxl` filenames, no path mappings or source translations\nare needed — stack frames, stepping, and `evaluate` in a paused loader all just\nwork.\n\n---\n\n## Tracebacks point at .pyxl\n\nThe same line mapping improves life with no debugger attached at all: in\ndevelopment, a Python traceback from a loader or action names your `.pyxl` file\nand line — not a compiled module under `.pyxle-build/`. The terminal, the browser\nerror overlay, and your logs all agree on where the error actually is.\n\n---\n\n## The discovery file\n\nWhile running, the dev server writes `.pyxle-build/dev-server.json` describing\nitself, and removes it on shutdown. This is what editor tooling (the extension's\nF5 flow and \"Open Studio\") reads instead of guessing ports:\n\n| Key | Type | Meaning |\n|-----|------|---------|\n| `pid` | `integer` | Dev-server process id. |\n| `version` | `string` | Pyxle version. |\n| `startedAt` | `number` | Unix timestamp of server start. |\n| `projectRoot` | `string` | Absolute path of the project. |\n| `server` | `object` | `{ \"host\", \"port\" }` of the Starlette server. |\n| `vite` | `object` | `{ \"host\", \"port\" }` of the Vite dev server. |\n| `url` | `string` | Browser-reachable base URL. |\n| `studio` | `string` \\| `null` | Studio dashboard URL (`null` when Studio is disabled). |\n| `debugpy` | `object` \\| `null` | `{ \"host\", \"port\" }` of the debug server (`null` without `--inspect`). |\n\nThe file is written atomically, and a failed write never takes down the server.\n\n---\n\n## Reading the compiled output\n\nPyxle compiles each `.pyxl` into a Python module and a JavaScript module under\nthe build directory (`.pyxle-build/` in dev, `dist/` for a production build).\nReading them demystifies \"where did my code go\":\n\n- `.pyxle-build/server/pages/…​.py` — the **Python** half: your `@server` /\n  `@action` functions with the runtime imports the compiler injected at the top\n  (`from pyxle.runtime import server`, etc.).\n- `.pyxle-build/client/…​` — the **JavaScript** half: your component, ready for\n  Vite.\n\nIn development you rarely need this, because tracebacks and breakpoints already\npoint at your `.pyxl`. A traceback from a **production build** points at the\ncompiled `.py`; the compiler preserves your code verbatim below the injected\nheader, so mapping back to your `.pyxl` is a small, constant offset. The build\ndirectory is disposable — delete it and the next `pyxle dev`/`build` regenerates it.\n\n---\n\n## Static checks\n\nTwo commands catch problems before you run the page:\n\n- **`pyxle check`** — validates `.pyxl` syntax, Python semantics, and JSX. Note\n  that a green check does not prove a page *renders*: a component reading a loader\n  key that doesn't exist is a runtime error, not a static one.\n- **`pyxle typecheck`** — runs TypeScript over your compiled JSX when you've opted\n  into TypeScript (see the [TypeScript guide](https://pyxle.dev/docs/guides/typescript.md)).\n\n---\n\n## Caveats\n\nWorth knowing before you rely on breakpoint debugging:\n\n- **A paused breakpoint pauses the whole server.** `pyxle dev` is a single\n  process, so while you sit at a breakpoint every in-flight request waits. That's\n  the right trade-off for development — and one reason production never hosts a\n  debugger.\n- **`justMyCode` defaults to `true`.** Stepping stays inside your own code; set it\n  to `false` in the launch configuration to step into Pyxle's internals.\n- **React debugging happens in the browser, not the SSR worker.** Your component\n  renders first in the Node SSR process, but the debugger doesn't attach there —\n  it's the same code with the same source maps in the browser, which is where you\n  debug it. Server-render `console.log` output still prints to the `pyxle dev`\n  terminal (see [the SSR side](#debugging-rendering-the-nodessr-side)).\n- **Production is untouched.** `pyxle serve` never remaps line numbers and never\n  hosts debugpy, regardless of flags or config.\n\n---\n\n## Troubleshooting\n\n**\"No module named pyxle\" when you press F5.** VS Code has a Python interpreter\nselected that doesn't have pyxle installed — a common split when pyxle lives in\none environment (a virtualenv, pyenv, or system Python) while VS Code points at\nanother. The launch runs `python -m pyxle dev` under the *selected* interpreter,\nso it has to be the one where `pyxle` is installed. The extension checks this\nbefore launching and offers a **Select Interpreter** button; you can also run\n**Python: Select Interpreter** from the command palette and pick the environment\nyour terminal's `pyxle` command uses (`which pyxle` / `where pyxle` shows it).\n\n**\"No module named pyxle.\\_\\_main\\_\\_\", or the debugger says to upgrade.** The\nselected interpreter has pyxle, but a version older than 0.8.0. Run\n`pip install --upgrade pyxle-framework` in that environment.\n\n---\n\n## Common symptoms\n\n| Symptom | Likely cause | Where to look |\n|---------|--------------|---------------|\n| Blank page, overlay shows a Python traceback | Loader/action raised | `pyxle dev` terminal; set a breakpoint in the loader |\n| `window is not defined` | Browser global at render scope | The named `.pyxl`; use `useEffect`/`<ClientOnly>` |\n| `'State' object has no attribute 'db'` | Missing plugin | `plugins` in `pyxle.config.json` |\n| Component data is `undefined` | Loader key ≠ component prop | Compare the loader's return dict to the component's `data` usage |\n| Change didn't take effect | Editing built output, or a stale build | Edit the `.pyxl` source, not `.pyxle-build/` |\n| Works in dev, fails in prod | Debug-only behavior / missing env | Server log (prod hides detail from the response) |\n| Breakpoint never binds | Wrong interpreter, or framework older than 0.8.0 | See [Troubleshooting](#troubleshooting) |\n\n---\n\n## Next steps\n\n- [Editor setup](https://pyxle.dev/docs/guides/editor-setup.md) — installing the extension and language server, and everything else it does\n- [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) — the dev dashboard; `pyxle studio --inspect` runs both\n- [Error Handling](https://pyxle.dev/docs/guides/error-handling.md) — `LoaderError`, error boundaries, 404s\n- [Testing](https://pyxle.dev/docs/guides/testing.md) — unit-test loaders and actions\n- [Client Components](https://pyxle.dev/docs/guides/client-components.md) — browser-only code and `<ClientOnly>`\n- [CLI reference → `pyxle dev`](https://pyxle.dev/docs/reference/cli.md#pyxle-dev) — every dev-server flag\n","prev":{"title":"Testing","path":"guides/testing"},"next":{"title":"Pyxle Studio","path":"guides/studio"}}
\ No newline at end of file
diff --git a/public/docs-data/guides/editor-setup.json b/public/docs-data/guides/editor-setup.json
index ea8ac0c..d286558 100644
--- a/public/docs-data/guides/editor-setup.json
+++ b/public/docs-data/guides/editor-setup.json
@@ -1 +1 @@
-{"title":"Editor setup","description":"Pyxle Language Tools brings first-class IDE support to `.pyxl` files — syntax highlighting, diagnostics, completions, hover documentation, go-to-definition, formatting, and breakpoint debugging, plus ","html":"<p>Pyxle Language Tools brings first-class IDE support to <code>.pyxl</code> files — syntax\nhighlighting, diagnostics, completions, hover documentation, go-to-definition,\nformatting, and breakpoint debugging, plus a <strong>Pyxle: Open Studio</strong> command.\nEverything works out of the box with a single install.</p>\n<blockquote>\n<p><strong>Beta release.</strong> The language toolkit is production-usable but still\nevolving. <a href=\"https://github.com/pyxle-dev/pyxle-langkit/issues\" target=\"_blank\" rel=\"noreferrer\">Report issues on GitHub.</a></p>\n</blockquote>\n<hr>\n<h2 id=\"vs-code-recommended\">VS Code (recommended)</h2><h3 id=\"1-install-the-extension\">1. Install the extension</h3><p>Search for <strong>&quot;Pyxle&quot;</strong> in the VS Code Extensions panel, or install from\nthe terminal:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">code --install-extension pyxle.pyxle-language-tools</code></pre></div><p>The extension is also available on the\n<a href=\"https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools\" target=\"_blank\" rel=\"noreferrer\">VS Code Marketplace</a>.</p>\n<h3 id=\"2-install-the-language-server\">2. Install the language server</h3><p>The VS Code extension is a thin client — the actual intelligence comes from\nthe <code>pyxle-langserver</code> process. As of 0.7.0 it ships with the framework itself —\nif you&#39;ve run <code>pip install pyxle-framework</code>, <code>pyxle-langserver</code> is already in\nyour environment. (On older framework versions, <code>pip install pyxle-langkit</code>\ninstalls it separately.)</p>\n<p>That&#39;s it. Open any <code>.pyxl</code> file and you&#39;ll see the <strong>✓ Pyxle</strong> indicator\nin the status bar when the language server connects.</p>\n<hr>\n<h2 id=\"features\">Features</h2><h3 id=\"syntax-highlighting\">Syntax highlighting</h3><p><code>.pyxl</code> files get dual-language highlighting — Python sections are\nhighlighted as Python, JSX sections as JavaScript/React. The grammar\ncorrectly handles template literals, so code snippets inside backtick\nstrings won&#39;t confuse the highlighter.</p>\n<h3 id=\"diagnostics\">Diagnostics</h3><p>Errors and warnings appear inline as you type:</p>\n<ul>\n<li><strong>Python analysis</strong> — powered by <a href=\"https://pypi.org/project/pyflakes/\" target=\"_blank\" rel=\"noreferrer\">pyflakes</a>\nwith 40+ rules. Catches undefined names, unused imports, syntax errors,\nunreachable code, and more.</li>\n<li><strong>JSX analysis</strong> — powered by <a href=\"https://babeljs.io/\" target=\"_blank\" rel=\"noreferrer\">Babel</a>. Catches\nsyntax errors in your JSX code.</li>\n<li><strong>Pyxle-specific rules</strong> — validates <code>@server</code> loaders (async, request\nparameter, return statement), <code>@action</code> functions, <code>&lt;Script&gt;</code> and\n<code>&lt;Image&gt;</code> component props, <code>HEAD</code> element format, and default export\nrequirements.</li>\n</ul>\n<h3 id=\"completions\">Completions</h3><p>Intelligent autocompletion for both sections:</p>\n<ul>\n<li><strong>Python</strong> — powered by <a href=\"https://jedi.readthedocs.io/\" target=\"_blank\" rel=\"noreferrer\">Jedi</a>. Full\nmodule completions, function signatures, attribute access, import\nsuggestions.</li>\n<li><strong>JSX</strong> — powered by TypeScript&#39;s language service. React component\nprops, DOM attributes, imported symbols, and local variables.</li>\n<li><strong>Pyxle-specific</strong> — <code>@server</code> and <code>@action</code> decorator snippets,\n<code>HEAD</code> boilerplate, Pyxle component names (<code>&lt;Link&gt;</code>, <code>&lt;Script&gt;</code>,\n<code>&lt;Image&gt;</code>, <code>&lt;Head&gt;</code>, <code>&lt;Slot&gt;</code>, <code>&lt;ClientOnly&gt;</code>, <code>&lt;Form&gt;</code>), and\n<code>data.</code> property completions inferred from your loader&#39;s return\nstatement.</li>\n</ul>\n<h3 id=\"hover-documentation\">Hover documentation</h3><p>Hover over any symbol to see its type and documentation:</p>\n<ul>\n<li><strong>Python symbols</strong> — function signatures, docstrings, and type info\nfrom Jedi.</li>\n<li><strong>JSX symbols</strong> — type information from TypeScript.</li>\n<li><strong>Pyxle decorators</strong> — hover <code>@server</code> or <code>@action</code> for a quick\nreference of the decorator contract.</li>\n<li><strong>Pyxle components</strong> — hover <code>Link</code>, <code>Script</code>, <code>Image</code>, etc. for\nprop documentation.</li>\n</ul>\n<h3 id=\"go-to-definition\">Go-to-definition</h3><p><strong>Cmd+Click</strong> (macOS) or <strong>Ctrl+Click</strong> (Windows/Linux) to jump to\ndefinitions:</p>\n<ul>\n<li><strong>Python symbols</strong> — jump to function definitions, class declarations,\nand imported modules via Jedi.</li>\n<li><strong>JSX symbols</strong> — jump to component definitions, imported functions,\nand type declarations via TypeScript.</li>\n<li><strong>Cross-section</strong> — click <code>data.title</code> in JSX to jump to the\n<code>&quot;title&quot;</code> key in your <code>@server</code> loader&#39;s return statement.</li>\n</ul>\n<h3 id=\"document-symbols\">Document symbols</h3><p>Open the <strong>Outline</strong> panel (Cmd+Shift+O) to see all symbols in the\ncurrent file: loaders, actions, functions, classes, and JSX exports.</p>\n<h3 id=\"formatting\">Formatting</h3><p>Format <code>.pyxl</code> files with section-aware formatting:</p>\n<ul>\n<li><strong>Python sections</strong> — formatted with <a href=\"https://docs.astral.sh/ruff/\" target=\"_blank\" rel=\"noreferrer\">ruff</a>\n(or optionally <a href=\"https://black.readthedocs.io/\" target=\"_blank\" rel=\"noreferrer\">black</a>).</li>\n<li><strong>JSX sections</strong> — formatted with <a href=\"https://prettier.io/\" target=\"_blank\" rel=\"noreferrer\">prettier</a>.</li>\n</ul>\n<p>Each section is formatted independently, preserving the file structure.</p>\n<h3 id=\"semantic-highlighting\">Semantic highlighting</h3><p>Enhanced syntax coloring beyond the TextMate grammar — decorators,\nfunction parameters, built-in calls, and constants get distinct colors\nbased on AST analysis.</p>\n<h3 id=\"debugging\">Debugging</h3><p>Set a breakpoint directly in a <code>.pyxl</code> file — on a line inside a\n<code>@server</code> loader <em>and</em> on a line inside the JSX below it — and press\n<strong>F5</strong>. The extension contributes a <code>pyxle</code> debug type with two launch\nconfigurations: one runs your dev server under the Python debugger, the\nother debugs the React half in a standalone browser session.</p>\n<p>Debugging ships in extension version <strong>0.3.0</strong> and needs\n<strong>pyxle-framework 0.8.0 or newer</strong> — the launch runs <code>python -m pyxle</code>,\nwhich earlier framework versions don&#39;t provide. Python-side breakpoints\nalso require the Python extension (<code>ms-python.python</code>); the debugger\noffers to install it if it&#39;s missing.</p>\n<p>Full walkthrough: <a href=\"/docs/guides/debugging-pyxl\">Debugging .pyxl files</a>.</p>\n<h3 id=\"open-studio\">Open Studio</h3><p>The <strong>Pyxle: Open Studio</strong> command (from the command palette) opens the\nrunning dev server&#39;s <a href=\"/docs/guides/studio\">Pyxle Studio</a> dashboard — routes, an\ninteractive loader/action tester, live requests, metrics, and config. It\nreads the server&#39;s discovery file, so it finds the right port without\nasking.</p>\n<hr>\n<h2 id=\"configuration\">Configuration</h2><p>The extension exposes these settings (VS Code Settings → search &quot;Pyxle&quot;):</p>\n<table>\n<thead>\n<tr>\n<th>Setting</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>pyxle.langserver.command</code></td>\n<td><code>pyxle-langserver</code></td>\n<td>Command to launch the language server</td>\n</tr>\n<tr>\n<td><code>pyxle.langserver.args</code></td>\n<td><code>[&quot;--stdio&quot;]</code></td>\n<td>Arguments for the language server</td>\n</tr>\n<tr>\n<td><code>pyxle.formatting.python</code></td>\n<td><code>ruff</code></td>\n<td>Python formatter (<code>ruff</code>, <code>black</code>, or <code>none</code>)</td>\n</tr>\n<tr>\n<td><code>pyxle.formatting.jsx</code></td>\n<td><code>prettier</code></td>\n<td>JSX formatter (<code>prettier</code> or <code>none</code>)</td>\n</tr>\n<tr>\n<td><code>pyxle.diagnostics.pyflakes</code></td>\n<td><code>true</code></td>\n<td>Enable pyflakes diagnostics</td>\n</tr>\n<tr>\n<td><code>pyxle.diagnostics.react</code></td>\n<td><code>true</code></td>\n<td>Enable Babel-based JSX analysis</td>\n</tr>\n</tbody></table>\n<h3 id=\"using-a-virtual-environment\">Using a virtual environment</h3><p>If <code>pyxle-langserver</code> is installed in a virtual environment, point the\nextension to the full path:</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"pyxle.langserver.command\": \"/path/to/venv/bin/pyxle-langserver\"\n}</code></pre></div><hr>\n<h2 id=\"cli-tools\">CLI tools</h2><p>The language toolkit also provides command-line tools for CI pipelines\nand scripting:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\"># Parse a .pyxl file and output its structure as JSON\npyxle-langkit parse pages/index.pyxl\n\n# Lint a .pyxl file (exit code 1 on errors)\npyxle-langkit lint pages/index.pyxl\n\n# Show the symbol outline\npyxle-langkit outline pages/index.pyxl\n\n# Format a .pyxl file\npyxle-langkit format pages/index.pyxl\n\n# Check if a file needs formatting (without modifying it)\npyxle-langkit format pages/index.pyxl --check</code></pre></div><h3 id=\"lint-in-ci\">Lint in CI</h3><p>Add to your CI pipeline to catch issues before merge:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pip install pyxle-framework  # pyxle-langkit ships with it\npyxle-langkit lint pages/*.pyxl</code></pre></div><hr>\n<h2 id=\"other-editors\">Other editors</h2><p>The language server speaks the standard\n<a href=\"https://microsoft.github.io/language-server-protocol/\" target=\"_blank\" rel=\"noreferrer\">Language Server Protocol</a>\nand works with any LSP-compatible editor.</p>\n<h3 id=\"neovim\">Neovim</h3><p>Using <a href=\"https://github.com/neovim/nvim-lspconfig\" target=\"_blank\" rel=\"noreferrer\">nvim-lspconfig</a>:</p>\n<div class=\"code-block\" data-lang=\"lua\"><pre><code class=\"language-lua\">vim.api.nvim_create_autocmd(\"FileType\", {\n  pattern = \"pyxle\",\n  callback = function()\n    vim.lsp.start({\n      name = \"pyxle-langserver\",\n      cmd = { \"pyxle-langserver\", \"--stdio\" },\n      root_dir = vim.fs.dirname(\n        vim.fs.find({ \"pyxle.config.json\", \"pyproject.toml\" }, { upward = true })[1]\n      ),\n    })\n  end,\n})</code></pre></div><p>You&#39;ll also need to register the <code>.pyxl</code> filetype:</p>\n<div class=\"code-block\" data-lang=\"lua\"><pre><code class=\"language-lua\">vim.filetype.add({ extension = { pyxl = \"pyxle\" } })</code></pre></div><h3 id=\"sublime-text\">Sublime Text</h3><p>Using <a href=\"https://github.com/sublimelsp/LSP\" target=\"_blank\" rel=\"noreferrer\">LSP</a>:</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"clients\": {\n    \"pyxle\": {\n      \"enabled\": true,\n      \"command\": [\"pyxle-langserver\", \"--stdio\"],\n      \"selector\": \"source.pyxle\"\n    }\n  }\n}</code></pre></div><h3 id=\"jetbrains-ides\">JetBrains IDEs</h3><p>JetBrains IDEs have limited LSP support. A dedicated plugin is planned\nfor a future release.</p>\n<hr>\n<h2 id=\"troubleshooting\">Troubleshooting</h2><h3 id=\"pyxle-langserver-command-not-found\">\"pyxle-langserver: command not found\"</h3><p>The language server isn&#39;t on your PATH. Either:</p>\n<ul>\n<li>Install it (ships with the framework): <code>pip install pyxle-framework</code> — or standalone: <code>pip install pyxle-langkit</code></li>\n<li>Or set the full path in VS Code settings:\n<code>&quot;pyxle.langserver.command&quot;: &quot;/path/to/venv/bin/pyxle-langserver&quot;</code></li>\n</ul>\n<h3 id=\"no-jsx-completions\">No JSX completions</h3><p>JSX completions require <strong>Node.js</strong> and <strong>TypeScript</strong> installed in your\nproject&#39;s <code>node_modules</code>. The language server spawns a TypeScript\nlanguage service worker for JSX intelligence.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">npm install typescript</code></pre></div><h3 id=\"no-python-completions\">No Python completions</h3><p>Python completions are powered by Jedi, which is installed automatically\nwith <code>pyxle-langkit</code>. If completions are missing, verify the install:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">python -c \"import jedi; print(jedi.__version__)\"</code></pre></div><h3 id=\"status-bar-shows-pyxle\">Status bar shows \"✗ Pyxle\"</h3><p>The language server failed to start. Check the <strong>Output</strong> panel in\nVS Code (View → Output → select &quot;Pyxle Language Server&quot;) for error\ndetails.</p>\n<h3 id=\"formatting-doesnt-change-anything\">Formatting doesn't change anything</h3><p>Formatting requires the formatter binaries to be on your PATH:</p>\n<ul>\n<li>Python: <code>pip install ruff</code> (or <code>pip install black</code>)</li>\n<li>JSX: <code>npm install -g prettier</code> (or install in your project)</li>\n</ul>\n<hr>\n<h2 id=\"architecture\">Architecture</h2><p>The language toolkit has a server-driven architecture — all intelligence\nlives in the Python LSP server:</p>\n<ul>\n<li><strong>Python analysis</strong> — <a href=\"https://jedi.readthedocs.io/\" target=\"_blank\" rel=\"noreferrer\">Jedi</a> runs\nin-process for completions, hover, and go-to-definition.</li>\n<li><strong>JSX analysis</strong> — An embedded TypeScript language service runs as a\nNode.js subprocess, communicating via NDJSON over stdin/stdout.</li>\n<li><strong>Diagnostics</strong> — <a href=\"https://pypi.org/project/pyflakes/\" target=\"_blank\" rel=\"noreferrer\">pyflakes</a> for\nPython static analysis, <a href=\"https://babeljs.io/\" target=\"_blank\" rel=\"noreferrer\">Babel</a> for JSX\nvalidation, plus Pyxle-specific rules.</li>\n<li><strong>No virtual files</strong> — unlike some language tools that write temporary\nfiles to disk, Pyxle&#39;s language server keeps everything in memory.</li>\n</ul>\n<p>The VS Code extension is a thin LSP client (~100 lines of TypeScript)\nthat connects to the server and manages the status bar. All the\nintelligence is in the server, making it easy to support other editors.</p>\n<p>Source code: <a href=\"https://github.com/pyxle-dev/pyxle-langkit\" target=\"_blank\" rel=\"noreferrer\">github.com/pyxle-dev/pyxle-langkit</a></p>\n","toc":[{"depth":2,"text":"VS Code (recommended)","slug":"vs-code-recommended"},{"depth":3,"text":"1. Install the extension","slug":"1-install-the-extension"},{"depth":3,"text":"2. Install the language server","slug":"2-install-the-language-server"},{"depth":2,"text":"Features","slug":"features"},{"depth":3,"text":"Syntax highlighting","slug":"syntax-highlighting"},{"depth":3,"text":"Diagnostics","slug":"diagnostics"},{"depth":3,"text":"Completions","slug":"completions"},{"depth":3,"text":"Hover documentation","slug":"hover-documentation"},{"depth":3,"text":"Go-to-definition","slug":"go-to-definition"},{"depth":3,"text":"Document symbols","slug":"document-symbols"},{"depth":3,"text":"Formatting","slug":"formatting"},{"depth":3,"text":"Semantic highlighting","slug":"semantic-highlighting"},{"depth":3,"text":"Debugging","slug":"debugging"},{"depth":3,"text":"Open Studio","slug":"open-studio"},{"depth":2,"text":"Configuration","slug":"configuration"},{"depth":3,"text":"Using a virtual environment","slug":"using-a-virtual-environment"},{"depth":2,"text":"CLI tools","slug":"cli-tools"},{"depth":3,"text":"Lint in CI","slug":"lint-in-ci"},{"depth":2,"text":"Other editors","slug":"other-editors"},{"depth":3,"text":"Neovim","slug":"neovim"},{"depth":3,"text":"Sublime Text","slug":"sublime-text"},{"depth":3,"text":"JetBrains IDEs","slug":"jetbrains-ides"},{"depth":2,"text":"Troubleshooting","slug":"troubleshooting"},{"depth":3,"text":"\"pyxle-langserver: command not found\"","slug":"pyxle-langserver-command-not-found"},{"depth":3,"text":"No JSX completions","slug":"no-jsx-completions"},{"depth":3,"text":"No Python completions","slug":"no-python-completions"},{"depth":3,"text":"Status bar shows \"✗ Pyxle\"","slug":"status-bar-shows-pyxle"},{"depth":3,"text":"Formatting doesn't change anything","slug":"formatting-doesnt-change-anything"},{"depth":2,"text":"Architecture","slug":"architecture"}],"path":"guides/editor-setup","markdown":"# Editor setup\n\nPyxle Language Tools brings first-class IDE support to `.pyxl` files — syntax\nhighlighting, diagnostics, completions, hover documentation, go-to-definition,\nformatting, and breakpoint debugging, plus a **Pyxle: Open Studio** command.\nEverything works out of the box with a single install.\n\n> **Beta release.** The language toolkit is production-usable but still\n> evolving. [Report issues on GitHub.](https://github.com/pyxle-dev/pyxle-langkit/issues)\n\n---\n\n## VS Code (recommended)\n\n### 1. Install the extension\n\nSearch for **\"Pyxle\"** in the VS Code Extensions panel, or install from\nthe terminal:\n\n```bash\ncode --install-extension pyxle.pyxle-language-tools\n```\n\nThe extension is also available on the\n[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools).\n\n### 2. Install the language server\n\nThe VS Code extension is a thin client — the actual intelligence comes from\nthe `pyxle-langserver` process. As of 0.7.0 it ships with the framework itself —\nif you've run `pip install pyxle-framework`, `pyxle-langserver` is already in\nyour environment. (On older framework versions, `pip install pyxle-langkit`\ninstalls it separately.)\n\nThat's it. Open any `.pyxl` file and you'll see the **✓ Pyxle** indicator\nin the status bar when the language server connects.\n\n---\n\n## Features\n\n### Syntax highlighting\n\n`.pyxl` files get dual-language highlighting — Python sections are\nhighlighted as Python, JSX sections as JavaScript/React. The grammar\ncorrectly handles template literals, so code snippets inside backtick\nstrings won't confuse the highlighter.\n\n### Diagnostics\n\nErrors and warnings appear inline as you type:\n\n- **Python analysis** — powered by [pyflakes](https://pypi.org/project/pyflakes/)\n  with 40+ rules. Catches undefined names, unused imports, syntax errors,\n  unreachable code, and more.\n- **JSX analysis** — powered by [Babel](https://babeljs.io/). Catches\n  syntax errors in your JSX code.\n- **Pyxle-specific rules** — validates `@server` loaders (async, request\n  parameter, return statement), `@action` functions, `<Script>` and\n  `<Image>` component props, `HEAD` element format, and default export\n  requirements.\n\n### Completions\n\nIntelligent autocompletion for both sections:\n\n- **Python** — powered by [Jedi](https://jedi.readthedocs.io/). Full\n  module completions, function signatures, attribute access, import\n  suggestions.\n- **JSX** — powered by TypeScript's language service. React component\n  props, DOM attributes, imported symbols, and local variables.\n- **Pyxle-specific** — `@server` and `@action` decorator snippets,\n  `HEAD` boilerplate, Pyxle component names (`<Link>`, `<Script>`,\n  `<Image>`, `<Head>`, `<Slot>`, `<ClientOnly>`, `<Form>`), and\n  `data.` property completions inferred from your loader's return\n  statement.\n\n### Hover documentation\n\nHover over any symbol to see its type and documentation:\n\n- **Python symbols** — function signatures, docstrings, and type info\n  from Jedi.\n- **JSX symbols** — type information from TypeScript.\n- **Pyxle decorators** — hover `@server` or `@action` for a quick\n  reference of the decorator contract.\n- **Pyxle components** — hover `Link`, `Script`, `Image`, etc. for\n  prop documentation.\n\n### Go-to-definition\n\n**Cmd+Click** (macOS) or **Ctrl+Click** (Windows/Linux) to jump to\ndefinitions:\n\n- **Python symbols** — jump to function definitions, class declarations,\n  and imported modules via Jedi.\n- **JSX symbols** — jump to component definitions, imported functions,\n  and type declarations via TypeScript.\n- **Cross-section** — click `data.title` in JSX to jump to the\n  `\"title\"` key in your `@server` loader's return statement.\n\n### Document symbols\n\nOpen the **Outline** panel (Cmd+Shift+O) to see all symbols in the\ncurrent file: loaders, actions, functions, classes, and JSX exports.\n\n### Formatting\n\nFormat `.pyxl` files with section-aware formatting:\n\n- **Python sections** — formatted with [ruff](https://docs.astral.sh/ruff/)\n  (or optionally [black](https://black.readthedocs.io/)).\n- **JSX sections** — formatted with [prettier](https://prettier.io/).\n\nEach section is formatted independently, preserving the file structure.\n\n### Semantic highlighting\n\nEnhanced syntax coloring beyond the TextMate grammar — decorators,\nfunction parameters, built-in calls, and constants get distinct colors\nbased on AST analysis.\n\n### Debugging\n\nSet a breakpoint directly in a `.pyxl` file — on a line inside a\n`@server` loader *and* on a line inside the JSX below it — and press\n**F5**. The extension contributes a `pyxle` debug type with two launch\nconfigurations: one runs your dev server under the Python debugger, the\nother debugs the React half in a standalone browser session.\n\nDebugging ships in extension version **0.3.0** and needs\n**pyxle-framework 0.8.0 or newer** — the launch runs `python -m pyxle`,\nwhich earlier framework versions don't provide. Python-side breakpoints\nalso require the Python extension (`ms-python.python`); the debugger\noffers to install it if it's missing.\n\nFull walkthrough: [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md).\n\n### Open Studio\n\nThe **Pyxle: Open Studio** command (from the command palette) opens the\nrunning dev server's [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) dashboard — routes, an\ninteractive loader/action tester, live requests, metrics, and config. It\nreads the server's discovery file, so it finds the right port without\nasking.\n\n---\n\n## Configuration\n\nThe extension exposes these settings (VS Code Settings → search \"Pyxle\"):\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `pyxle.langserver.command` | `pyxle-langserver` | Command to launch the language server |\n| `pyxle.langserver.args` | `[\"--stdio\"]` | Arguments for the language server |\n| `pyxle.formatting.python` | `ruff` | Python formatter (`ruff`, `black`, or `none`) |\n| `pyxle.formatting.jsx` | `prettier` | JSX formatter (`prettier` or `none`) |\n| `pyxle.diagnostics.pyflakes` | `true` | Enable pyflakes diagnostics |\n| `pyxle.diagnostics.react` | `true` | Enable Babel-based JSX analysis |\n\n### Using a virtual environment\n\nIf `pyxle-langserver` is installed in a virtual environment, point the\nextension to the full path:\n\n```json\n{\n  \"pyxle.langserver.command\": \"/path/to/venv/bin/pyxle-langserver\"\n}\n```\n\n---\n\n## CLI tools\n\nThe language toolkit also provides command-line tools for CI pipelines\nand scripting:\n\n```bash\n# Parse a .pyxl file and output its structure as JSON\npyxle-langkit parse pages/index.pyxl\n\n# Lint a .pyxl file (exit code 1 on errors)\npyxle-langkit lint pages/index.pyxl\n\n# Show the symbol outline\npyxle-langkit outline pages/index.pyxl\n\n# Format a .pyxl file\npyxle-langkit format pages/index.pyxl\n\n# Check if a file needs formatting (without modifying it)\npyxle-langkit format pages/index.pyxl --check\n```\n\n### Lint in CI\n\nAdd to your CI pipeline to catch issues before merge:\n\n```bash\npip install pyxle-framework  # pyxle-langkit ships with it\npyxle-langkit lint pages/*.pyxl\n```\n\n---\n\n## Other editors\n\nThe language server speaks the standard\n[Language Server Protocol](https://microsoft.github.io/language-server-protocol/)\nand works with any LSP-compatible editor.\n\n### Neovim\n\nUsing [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig):\n\n```lua\nvim.api.nvim_create_autocmd(\"FileType\", {\n  pattern = \"pyxle\",\n  callback = function()\n    vim.lsp.start({\n      name = \"pyxle-langserver\",\n      cmd = { \"pyxle-langserver\", \"--stdio\" },\n      root_dir = vim.fs.dirname(\n        vim.fs.find({ \"pyxle.config.json\", \"pyproject.toml\" }, { upward = true })[1]\n      ),\n    })\n  end,\n})\n```\n\nYou'll also need to register the `.pyxl` filetype:\n\n```lua\nvim.filetype.add({ extension = { pyxl = \"pyxle\" } })\n```\n\n### Sublime Text\n\nUsing [LSP](https://github.com/sublimelsp/LSP):\n\n```json\n{\n  \"clients\": {\n    \"pyxle\": {\n      \"enabled\": true,\n      \"command\": [\"pyxle-langserver\", \"--stdio\"],\n      \"selector\": \"source.pyxle\"\n    }\n  }\n}\n```\n\n### JetBrains IDEs\n\nJetBrains IDEs have limited LSP support. A dedicated plugin is planned\nfor a future release.\n\n---\n\n## Troubleshooting\n\n### \"pyxle-langserver: command not found\"\n\nThe language server isn't on your PATH. Either:\n- Install it (ships with the framework): `pip install pyxle-framework` — or standalone: `pip install pyxle-langkit`\n- Or set the full path in VS Code settings:\n  `\"pyxle.langserver.command\": \"/path/to/venv/bin/pyxle-langserver\"`\n\n### No JSX completions\n\nJSX completions require **Node.js** and **TypeScript** installed in your\nproject's `node_modules`. The language server spawns a TypeScript\nlanguage service worker for JSX intelligence.\n\n```bash\nnpm install typescript\n```\n\n### No Python completions\n\nPython completions are powered by Jedi, which is installed automatically\nwith `pyxle-langkit`. If completions are missing, verify the install:\n\n```bash\npython -c \"import jedi; print(jedi.__version__)\"\n```\n\n### Status bar shows \"✗ Pyxle\"\n\nThe language server failed to start. Check the **Output** panel in\nVS Code (View → Output → select \"Pyxle Language Server\") for error\ndetails.\n\n### Formatting doesn't change anything\n\nFormatting requires the formatter binaries to be on your PATH:\n- Python: `pip install ruff` (or `pip install black`)\n- JSX: `npm install -g prettier` (or install in your project)\n\n---\n\n## Architecture\n\nThe language toolkit has a server-driven architecture — all intelligence\nlives in the Python LSP server:\n\n- **Python analysis** — [Jedi](https://jedi.readthedocs.io/) runs\n  in-process for completions, hover, and go-to-definition.\n- **JSX analysis** — An embedded TypeScript language service runs as a\n  Node.js subprocess, communicating via NDJSON over stdin/stdout.\n- **Diagnostics** — [pyflakes](https://pypi.org/project/pyflakes/) for\n  Python static analysis, [Babel](https://babeljs.io/) for JSX\n  validation, plus Pyxle-specific rules.\n- **No virtual files** — unlike some language tools that write temporary\n  files to disk, Pyxle's language server keeps everything in memory.\n\nThe VS Code extension is a thin LSP client (~100 lines of TypeScript)\nthat connects to the server and manages the status bar. All the\nintelligence is in the server, making it easy to support other editors.\n\nSource code: [github.com/pyxle-dev/pyxle-langkit](https://github.com/pyxle-dev/pyxle-langkit)\n","prev":{"title":"Deployment","path":"guides/deployment"},"next":{"title":"TypeScript","path":"guides/typescript"}}
\ No newline at end of file
+{"title":"Editor setup","description":"Pyxle Language Tools brings first-class IDE support to `.pyxl` files — syntax highlighting, diagnostics, completions, hover documentation, go-to-definition, formatting, and breakpoint debugging, plus ","html":"<p>Pyxle Language Tools brings first-class IDE support to <code>.pyxl</code> files — syntax\nhighlighting, diagnostics, completions, hover documentation, go-to-definition,\nformatting, and breakpoint debugging, plus a <strong>Pyxle: Open Studio</strong> command.\nEverything works out of the box with a single install.</p>\n<blockquote>\n<p><strong>Beta release.</strong> The language toolkit is production-usable but still\nevolving. <a href=\"https://github.com/pyxle-dev/pyxle-langkit/issues\" target=\"_blank\" rel=\"noreferrer\">Report issues on GitHub.</a></p>\n</blockquote>\n<hr>\n<h2 id=\"vs-code-recommended\">VS Code (recommended)</h2><h3 id=\"1-install-the-extension\">1. Install the extension</h3><p>Search for <strong>&quot;Pyxle&quot;</strong> in the VS Code Extensions panel, or install from\nthe terminal:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">code --install-extension pyxle.pyxle-language-tools</code></pre></div><p>The extension is also available on the\n<a href=\"https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools\" target=\"_blank\" rel=\"noreferrer\">VS Code Marketplace</a>.</p>\n<h3 id=\"2-install-the-language-server\">2. Install the language server</h3><p>The VS Code extension is a thin client — the actual intelligence comes from\nthe <code>pyxle-langserver</code> process. As of 0.7.0 it ships with the framework itself —\nif you&#39;ve run <code>pip install pyxle-framework</code>, <code>pyxle-langserver</code> is already in\nyour environment. (On older framework versions, <code>pip install pyxle-langkit</code>\ninstalls it separately.)</p>\n<p>That&#39;s it. Open any <code>.pyxl</code> file and you&#39;ll see the <strong>✓ Pyxle</strong> indicator\nin the status bar when the language server connects.</p>\n<hr>\n<h2 id=\"features\">Features</h2><h3 id=\"syntax-highlighting\">Syntax highlighting</h3><p><code>.pyxl</code> files get dual-language highlighting — Python sections are\nhighlighted as Python, JSX sections as JavaScript/React. The grammar\ncorrectly handles template literals, so code snippets inside backtick\nstrings won&#39;t confuse the highlighter.</p>\n<h3 id=\"diagnostics\">Diagnostics</h3><p>Errors and warnings appear inline as you type:</p>\n<ul>\n<li><strong>Python analysis</strong> — powered by <a href=\"https://pypi.org/project/pyflakes/\" target=\"_blank\" rel=\"noreferrer\">pyflakes</a>\nwith 40+ rules. Catches undefined names, unused imports, syntax errors,\nunreachable code, and more.</li>\n<li><strong>JSX analysis</strong> — powered by <a href=\"https://babeljs.io/\" target=\"_blank\" rel=\"noreferrer\">Babel</a>. Catches\nsyntax errors in your JSX code.</li>\n<li><strong>Pyxle-specific rules</strong> — validates <code>@server</code> loaders (async, request\nparameter, return statement), <code>@action</code> functions, <code>&lt;Script&gt;</code> and\n<code>&lt;Image&gt;</code> component props, <code>HEAD</code> element format, and default export\nrequirements.</li>\n</ul>\n<h3 id=\"completions\">Completions</h3><p>Intelligent autocompletion for both sections:</p>\n<ul>\n<li><strong>Python</strong> — powered by <a href=\"https://jedi.readthedocs.io/\" target=\"_blank\" rel=\"noreferrer\">Jedi</a>. Full\nmodule completions, function signatures, attribute access, import\nsuggestions.</li>\n<li><strong>JSX</strong> — powered by TypeScript&#39;s language service. React component\nprops, DOM attributes, imported symbols, and local variables.</li>\n<li><strong>Pyxle-specific</strong> — <code>@server</code> and <code>@action</code> decorator snippets,\n<code>HEAD</code> boilerplate, Pyxle component names (<code>&lt;Link&gt;</code>, <code>&lt;Script&gt;</code>,\n<code>&lt;Image&gt;</code>, <code>&lt;Head&gt;</code>, <code>&lt;Slot&gt;</code>, <code>&lt;ClientOnly&gt;</code>, <code>&lt;Form&gt;</code>), and\n<code>data.</code> property completions inferred from your loader&#39;s return\nstatement.</li>\n</ul>\n<h3 id=\"hover-documentation\">Hover documentation</h3><p>Hover over any symbol to see its type and documentation:</p>\n<ul>\n<li><strong>Python symbols</strong> — function signatures, docstrings, and type info\nfrom Jedi.</li>\n<li><strong>JSX symbols</strong> — type information from TypeScript.</li>\n<li><strong>Pyxle decorators</strong> — hover <code>@server</code> or <code>@action</code> for a quick\nreference of the decorator contract.</li>\n<li><strong>Pyxle components</strong> — hover <code>Link</code>, <code>Script</code>, <code>Image</code>, etc. for\nprop documentation.</li>\n</ul>\n<h3 id=\"go-to-definition\">Go-to-definition</h3><p><strong>Cmd+Click</strong> (macOS) or <strong>Ctrl+Click</strong> (Windows/Linux) to jump to\ndefinitions:</p>\n<ul>\n<li><strong>Python symbols</strong> — jump to function definitions, class declarations,\nand imported modules via Jedi.</li>\n<li><strong>JSX symbols</strong> — jump to component definitions, imported functions,\nand type declarations via TypeScript.</li>\n<li><strong>Cross-section</strong> — click <code>data.title</code> in JSX to jump to the\n<code>&quot;title&quot;</code> key in your <code>@server</code> loader&#39;s return statement.</li>\n</ul>\n<h3 id=\"document-symbols\">Document symbols</h3><p>Open the <strong>Outline</strong> panel (Cmd+Shift+O) to see all symbols in the\ncurrent file: loaders, actions, functions, classes, and JSX exports.</p>\n<h3 id=\"formatting\">Formatting</h3><p>Format <code>.pyxl</code> files with section-aware formatting:</p>\n<ul>\n<li><strong>Python sections</strong> — formatted with <a href=\"https://docs.astral.sh/ruff/\" target=\"_blank\" rel=\"noreferrer\">ruff</a>\n(or optionally <a href=\"https://black.readthedocs.io/\" target=\"_blank\" rel=\"noreferrer\">black</a>).</li>\n<li><strong>JSX sections</strong> — formatted with <a href=\"https://prettier.io/\" target=\"_blank\" rel=\"noreferrer\">prettier</a>.</li>\n</ul>\n<p>Each section is formatted independently, preserving the file structure.</p>\n<h3 id=\"semantic-highlighting\">Semantic highlighting</h3><p>Enhanced syntax coloring beyond the TextMate grammar — decorators,\nfunction parameters, built-in calls, and constants get distinct colors\nbased on AST analysis.</p>\n<h3 id=\"debugging\">Debugging</h3><p>Set a breakpoint directly in a <code>.pyxl</code> file — on a line inside a\n<code>@server</code> loader <em>and</em> on a line inside the JSX below it — and press\n<strong>F5</strong>. The extension contributes a <code>pyxle</code> debug type with two launch\nconfigurations: one runs your dev server under the Python debugger, the\nother debugs the React half in a standalone browser session.</p>\n<p>Debugging ships in extension version <strong>0.3.0</strong> and needs\n<strong>pyxle-framework 0.8.0 or newer</strong> — the launch runs <code>python -m pyxle</code>,\nwhich earlier framework versions don&#39;t provide. Python-side breakpoints\nalso require the Python extension (<code>ms-python.python</code>); the debugger\noffers to install it if it&#39;s missing.</p>\n<p>Full walkthrough: <a href=\"/docs/guides/debugging\">Debugging .pyxl files</a>.</p>\n<h3 id=\"open-studio\">Open Studio</h3><p>The <strong>Pyxle: Open Studio</strong> command (from the command palette) opens the\nrunning dev server&#39;s <a href=\"/docs/guides/studio\">Pyxle Studio</a> dashboard — routes, an\ninteractive loader/action tester, live requests, metrics, and config. It\nreads the server&#39;s discovery file, so it finds the right port without\nasking.</p>\n<hr>\n<h2 id=\"configuration\">Configuration</h2><p>The extension exposes these settings (VS Code Settings → search &quot;Pyxle&quot;):</p>\n<table>\n<thead>\n<tr>\n<th>Setting</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>pyxle.langserver.command</code></td>\n<td><code>pyxle-langserver</code></td>\n<td>Command to launch the language server</td>\n</tr>\n<tr>\n<td><code>pyxle.langserver.args</code></td>\n<td><code>[&quot;--stdio&quot;]</code></td>\n<td>Arguments for the language server</td>\n</tr>\n<tr>\n<td><code>pyxle.formatting.python</code></td>\n<td><code>ruff</code></td>\n<td>Python formatter (<code>ruff</code>, <code>black</code>, or <code>none</code>)</td>\n</tr>\n<tr>\n<td><code>pyxle.formatting.jsx</code></td>\n<td><code>prettier</code></td>\n<td>JSX formatter (<code>prettier</code> or <code>none</code>)</td>\n</tr>\n<tr>\n<td><code>pyxle.diagnostics.pyflakes</code></td>\n<td><code>true</code></td>\n<td>Enable pyflakes diagnostics</td>\n</tr>\n<tr>\n<td><code>pyxle.diagnostics.react</code></td>\n<td><code>true</code></td>\n<td>Enable Babel-based JSX analysis</td>\n</tr>\n</tbody></table>\n<h3 id=\"using-a-virtual-environment\">Using a virtual environment</h3><p>If <code>pyxle-langserver</code> is installed in a virtual environment, point the\nextension to the full path:</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"pyxle.langserver.command\": \"/path/to/venv/bin/pyxle-langserver\"\n}</code></pre></div><hr>\n<h2 id=\"cli-tools\">CLI tools</h2><p>The language toolkit also provides command-line tools for CI pipelines\nand scripting:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\"># Parse a .pyxl file and output its structure as JSON\npyxle-langkit parse pages/index.pyxl\n\n# Lint a .pyxl file (exit code 1 on errors)\npyxle-langkit lint pages/index.pyxl\n\n# Show the symbol outline\npyxle-langkit outline pages/index.pyxl\n\n# Format a .pyxl file\npyxle-langkit format pages/index.pyxl\n\n# Check if a file needs formatting (without modifying it)\npyxle-langkit format pages/index.pyxl --check</code></pre></div><h3 id=\"lint-in-ci\">Lint in CI</h3><p>Add to your CI pipeline to catch issues before merge:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pip install pyxle-framework  # pyxle-langkit ships with it\npyxle-langkit lint pages/*.pyxl</code></pre></div><hr>\n<h2 id=\"other-editors\">Other editors</h2><p>The language server speaks the standard\n<a href=\"https://microsoft.github.io/language-server-protocol/\" target=\"_blank\" rel=\"noreferrer\">Language Server Protocol</a>\nand works with any LSP-compatible editor.</p>\n<h3 id=\"neovim\">Neovim</h3><p>Using <a href=\"https://github.com/neovim/nvim-lspconfig\" target=\"_blank\" rel=\"noreferrer\">nvim-lspconfig</a>:</p>\n<div class=\"code-block\" data-lang=\"lua\"><pre><code class=\"language-lua\">vim.api.nvim_create_autocmd(\"FileType\", {\n  pattern = \"pyxle\",\n  callback = function()\n    vim.lsp.start({\n      name = \"pyxle-langserver\",\n      cmd = { \"pyxle-langserver\", \"--stdio\" },\n      root_dir = vim.fs.dirname(\n        vim.fs.find({ \"pyxle.config.json\", \"pyproject.toml\" }, { upward = true })[1]\n      ),\n    })\n  end,\n})</code></pre></div><p>You&#39;ll also need to register the <code>.pyxl</code> filetype:</p>\n<div class=\"code-block\" data-lang=\"lua\"><pre><code class=\"language-lua\">vim.filetype.add({ extension = { pyxl = \"pyxle\" } })</code></pre></div><h3 id=\"sublime-text\">Sublime Text</h3><p>Using <a href=\"https://github.com/sublimelsp/LSP\" target=\"_blank\" rel=\"noreferrer\">LSP</a>:</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"clients\": {\n    \"pyxle\": {\n      \"enabled\": true,\n      \"command\": [\"pyxle-langserver\", \"--stdio\"],\n      \"selector\": \"source.pyxle\"\n    }\n  }\n}</code></pre></div><h3 id=\"jetbrains-ides\">JetBrains IDEs</h3><p>JetBrains IDEs have limited LSP support. A dedicated plugin is planned\nfor a future release.</p>\n<hr>\n<h2 id=\"troubleshooting\">Troubleshooting</h2><h3 id=\"pyxle-langserver-command-not-found\">\"pyxle-langserver: command not found\"</h3><p>The language server isn&#39;t on your PATH. Either:</p>\n<ul>\n<li>Install it (ships with the framework): <code>pip install pyxle-framework</code> — or standalone: <code>pip install pyxle-langkit</code></li>\n<li>Or set the full path in VS Code settings:\n<code>&quot;pyxle.langserver.command&quot;: &quot;/path/to/venv/bin/pyxle-langserver&quot;</code></li>\n</ul>\n<h3 id=\"no-jsx-completions\">No JSX completions</h3><p>JSX completions require <strong>Node.js</strong> and <strong>TypeScript</strong> installed in your\nproject&#39;s <code>node_modules</code>. The language server spawns a TypeScript\nlanguage service worker for JSX intelligence.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">npm install typescript</code></pre></div><h3 id=\"no-python-completions\">No Python completions</h3><p>Python completions are powered by Jedi, which is installed automatically\nwith <code>pyxle-langkit</code>. If completions are missing, verify the install:</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">python -c \"import jedi; print(jedi.__version__)\"</code></pre></div><h3 id=\"status-bar-shows-pyxle\">Status bar shows \"✗ Pyxle\"</h3><p>The language server failed to start. Check the <strong>Output</strong> panel in\nVS Code (View → Output → select &quot;Pyxle Language Server&quot;) for error\ndetails.</p>\n<h3 id=\"formatting-doesnt-change-anything\">Formatting doesn't change anything</h3><p>Formatting requires the formatter binaries to be on your PATH:</p>\n<ul>\n<li>Python: <code>pip install ruff</code> (or <code>pip install black</code>)</li>\n<li>JSX: <code>npm install -g prettier</code> (or install in your project)</li>\n</ul>\n<hr>\n<h2 id=\"architecture\">Architecture</h2><p>The language toolkit has a server-driven architecture — all intelligence\nlives in the Python LSP server:</p>\n<ul>\n<li><strong>Python analysis</strong> — <a href=\"https://jedi.readthedocs.io/\" target=\"_blank\" rel=\"noreferrer\">Jedi</a> runs\nin-process for completions, hover, and go-to-definition.</li>\n<li><strong>JSX analysis</strong> — An embedded TypeScript language service runs as a\nNode.js subprocess, communicating via NDJSON over stdin/stdout.</li>\n<li><strong>Diagnostics</strong> — <a href=\"https://pypi.org/project/pyflakes/\" target=\"_blank\" rel=\"noreferrer\">pyflakes</a> for\nPython static analysis, <a href=\"https://babeljs.io/\" target=\"_blank\" rel=\"noreferrer\">Babel</a> for JSX\nvalidation, plus Pyxle-specific rules.</li>\n<li><strong>No virtual files</strong> — unlike some language tools that write temporary\nfiles to disk, Pyxle&#39;s language server keeps everything in memory.</li>\n</ul>\n<p>The VS Code extension is a thin LSP client (~100 lines of TypeScript)\nthat connects to the server and manages the status bar. All the\nintelligence is in the server, making it easy to support other editors.</p>\n<p>Source code: <a href=\"https://github.com/pyxle-dev/pyxle-langkit\" target=\"_blank\" rel=\"noreferrer\">github.com/pyxle-dev/pyxle-langkit</a></p>\n","toc":[{"depth":2,"text":"VS Code (recommended)","slug":"vs-code-recommended"},{"depth":3,"text":"1. Install the extension","slug":"1-install-the-extension"},{"depth":3,"text":"2. Install the language server","slug":"2-install-the-language-server"},{"depth":2,"text":"Features","slug":"features"},{"depth":3,"text":"Syntax highlighting","slug":"syntax-highlighting"},{"depth":3,"text":"Diagnostics","slug":"diagnostics"},{"depth":3,"text":"Completions","slug":"completions"},{"depth":3,"text":"Hover documentation","slug":"hover-documentation"},{"depth":3,"text":"Go-to-definition","slug":"go-to-definition"},{"depth":3,"text":"Document symbols","slug":"document-symbols"},{"depth":3,"text":"Formatting","slug":"formatting"},{"depth":3,"text":"Semantic highlighting","slug":"semantic-highlighting"},{"depth":3,"text":"Debugging","slug":"debugging"},{"depth":3,"text":"Open Studio","slug":"open-studio"},{"depth":2,"text":"Configuration","slug":"configuration"},{"depth":3,"text":"Using a virtual environment","slug":"using-a-virtual-environment"},{"depth":2,"text":"CLI tools","slug":"cli-tools"},{"depth":3,"text":"Lint in CI","slug":"lint-in-ci"},{"depth":2,"text":"Other editors","slug":"other-editors"},{"depth":3,"text":"Neovim","slug":"neovim"},{"depth":3,"text":"Sublime Text","slug":"sublime-text"},{"depth":3,"text":"JetBrains IDEs","slug":"jetbrains-ides"},{"depth":2,"text":"Troubleshooting","slug":"troubleshooting"},{"depth":3,"text":"\"pyxle-langserver: command not found\"","slug":"pyxle-langserver-command-not-found"},{"depth":3,"text":"No JSX completions","slug":"no-jsx-completions"},{"depth":3,"text":"No Python completions","slug":"no-python-completions"},{"depth":3,"text":"Status bar shows \"✗ Pyxle\"","slug":"status-bar-shows-pyxle"},{"depth":3,"text":"Formatting doesn't change anything","slug":"formatting-doesnt-change-anything"},{"depth":2,"text":"Architecture","slug":"architecture"}],"path":"guides/editor-setup","markdown":"# Editor setup\n\nPyxle Language Tools brings first-class IDE support to `.pyxl` files — syntax\nhighlighting, diagnostics, completions, hover documentation, go-to-definition,\nformatting, and breakpoint debugging, plus a **Pyxle: Open Studio** command.\nEverything works out of the box with a single install.\n\n> **Beta release.** The language toolkit is production-usable but still\n> evolving. [Report issues on GitHub.](https://github.com/pyxle-dev/pyxle-langkit/issues)\n\n---\n\n## VS Code (recommended)\n\n### 1. Install the extension\n\nSearch for **\"Pyxle\"** in the VS Code Extensions panel, or install from\nthe terminal:\n\n```bash\ncode --install-extension pyxle.pyxle-language-tools\n```\n\nThe extension is also available on the\n[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools).\n\n### 2. Install the language server\n\nThe VS Code extension is a thin client — the actual intelligence comes from\nthe `pyxle-langserver` process. As of 0.7.0 it ships with the framework itself —\nif you've run `pip install pyxle-framework`, `pyxle-langserver` is already in\nyour environment. (On older framework versions, `pip install pyxle-langkit`\ninstalls it separately.)\n\nThat's it. Open any `.pyxl` file and you'll see the **✓ Pyxle** indicator\nin the status bar when the language server connects.\n\n---\n\n## Features\n\n### Syntax highlighting\n\n`.pyxl` files get dual-language highlighting — Python sections are\nhighlighted as Python, JSX sections as JavaScript/React. The grammar\ncorrectly handles template literals, so code snippets inside backtick\nstrings won't confuse the highlighter.\n\n### Diagnostics\n\nErrors and warnings appear inline as you type:\n\n- **Python analysis** — powered by [pyflakes](https://pypi.org/project/pyflakes/)\n  with 40+ rules. Catches undefined names, unused imports, syntax errors,\n  unreachable code, and more.\n- **JSX analysis** — powered by [Babel](https://babeljs.io/). Catches\n  syntax errors in your JSX code.\n- **Pyxle-specific rules** — validates `@server` loaders (async, request\n  parameter, return statement), `@action` functions, `<Script>` and\n  `<Image>` component props, `HEAD` element format, and default export\n  requirements.\n\n### Completions\n\nIntelligent autocompletion for both sections:\n\n- **Python** — powered by [Jedi](https://jedi.readthedocs.io/). Full\n  module completions, function signatures, attribute access, import\n  suggestions.\n- **JSX** — powered by TypeScript's language service. React component\n  props, DOM attributes, imported symbols, and local variables.\n- **Pyxle-specific** — `@server` and `@action` decorator snippets,\n  `HEAD` boilerplate, Pyxle component names (`<Link>`, `<Script>`,\n  `<Image>`, `<Head>`, `<Slot>`, `<ClientOnly>`, `<Form>`), and\n  `data.` property completions inferred from your loader's return\n  statement.\n\n### Hover documentation\n\nHover over any symbol to see its type and documentation:\n\n- **Python symbols** — function signatures, docstrings, and type info\n  from Jedi.\n- **JSX symbols** — type information from TypeScript.\n- **Pyxle decorators** — hover `@server` or `@action` for a quick\n  reference of the decorator contract.\n- **Pyxle components** — hover `Link`, `Script`, `Image`, etc. for\n  prop documentation.\n\n### Go-to-definition\n\n**Cmd+Click** (macOS) or **Ctrl+Click** (Windows/Linux) to jump to\ndefinitions:\n\n- **Python symbols** — jump to function definitions, class declarations,\n  and imported modules via Jedi.\n- **JSX symbols** — jump to component definitions, imported functions,\n  and type declarations via TypeScript.\n- **Cross-section** — click `data.title` in JSX to jump to the\n  `\"title\"` key in your `@server` loader's return statement.\n\n### Document symbols\n\nOpen the **Outline** panel (Cmd+Shift+O) to see all symbols in the\ncurrent file: loaders, actions, functions, classes, and JSX exports.\n\n### Formatting\n\nFormat `.pyxl` files with section-aware formatting:\n\n- **Python sections** — formatted with [ruff](https://docs.astral.sh/ruff/)\n  (or optionally [black](https://black.readthedocs.io/)).\n- **JSX sections** — formatted with [prettier](https://prettier.io/).\n\nEach section is formatted independently, preserving the file structure.\n\n### Semantic highlighting\n\nEnhanced syntax coloring beyond the TextMate grammar — decorators,\nfunction parameters, built-in calls, and constants get distinct colors\nbased on AST analysis.\n\n### Debugging\n\nSet a breakpoint directly in a `.pyxl` file — on a line inside a\n`@server` loader *and* on a line inside the JSX below it — and press\n**F5**. The extension contributes a `pyxle` debug type with two launch\nconfigurations: one runs your dev server under the Python debugger, the\nother debugs the React half in a standalone browser session.\n\nDebugging ships in extension version **0.3.0** and needs\n**pyxle-framework 0.8.0 or newer** — the launch runs `python -m pyxle`,\nwhich earlier framework versions don't provide. Python-side breakpoints\nalso require the Python extension (`ms-python.python`); the debugger\noffers to install it if it's missing.\n\nFull walkthrough: [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging.md).\n\n### Open Studio\n\nThe **Pyxle: Open Studio** command (from the command palette) opens the\nrunning dev server's [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) dashboard — routes, an\ninteractive loader/action tester, live requests, metrics, and config. It\nreads the server's discovery file, so it finds the right port without\nasking.\n\n---\n\n## Configuration\n\nThe extension exposes these settings (VS Code Settings → search \"Pyxle\"):\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `pyxle.langserver.command` | `pyxle-langserver` | Command to launch the language server |\n| `pyxle.langserver.args` | `[\"--stdio\"]` | Arguments for the language server |\n| `pyxle.formatting.python` | `ruff` | Python formatter (`ruff`, `black`, or `none`) |\n| `pyxle.formatting.jsx` | `prettier` | JSX formatter (`prettier` or `none`) |\n| `pyxle.diagnostics.pyflakes` | `true` | Enable pyflakes diagnostics |\n| `pyxle.diagnostics.react` | `true` | Enable Babel-based JSX analysis |\n\n### Using a virtual environment\n\nIf `pyxle-langserver` is installed in a virtual environment, point the\nextension to the full path:\n\n```json\n{\n  \"pyxle.langserver.command\": \"/path/to/venv/bin/pyxle-langserver\"\n}\n```\n\n---\n\n## CLI tools\n\nThe language toolkit also provides command-line tools for CI pipelines\nand scripting:\n\n```bash\n# Parse a .pyxl file and output its structure as JSON\npyxle-langkit parse pages/index.pyxl\n\n# Lint a .pyxl file (exit code 1 on errors)\npyxle-langkit lint pages/index.pyxl\n\n# Show the symbol outline\npyxle-langkit outline pages/index.pyxl\n\n# Format a .pyxl file\npyxle-langkit format pages/index.pyxl\n\n# Check if a file needs formatting (without modifying it)\npyxle-langkit format pages/index.pyxl --check\n```\n\n### Lint in CI\n\nAdd to your CI pipeline to catch issues before merge:\n\n```bash\npip install pyxle-framework  # pyxle-langkit ships with it\npyxle-langkit lint pages/*.pyxl\n```\n\n---\n\n## Other editors\n\nThe language server speaks the standard\n[Language Server Protocol](https://microsoft.github.io/language-server-protocol/)\nand works with any LSP-compatible editor.\n\n### Neovim\n\nUsing [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig):\n\n```lua\nvim.api.nvim_create_autocmd(\"FileType\", {\n  pattern = \"pyxle\",\n  callback = function()\n    vim.lsp.start({\n      name = \"pyxle-langserver\",\n      cmd = { \"pyxle-langserver\", \"--stdio\" },\n      root_dir = vim.fs.dirname(\n        vim.fs.find({ \"pyxle.config.json\", \"pyproject.toml\" }, { upward = true })[1]\n      ),\n    })\n  end,\n})\n```\n\nYou'll also need to register the `.pyxl` filetype:\n\n```lua\nvim.filetype.add({ extension = { pyxl = \"pyxle\" } })\n```\n\n### Sublime Text\n\nUsing [LSP](https://github.com/sublimelsp/LSP):\n\n```json\n{\n  \"clients\": {\n    \"pyxle\": {\n      \"enabled\": true,\n      \"command\": [\"pyxle-langserver\", \"--stdio\"],\n      \"selector\": \"source.pyxle\"\n    }\n  }\n}\n```\n\n### JetBrains IDEs\n\nJetBrains IDEs have limited LSP support. A dedicated plugin is planned\nfor a future release.\n\n---\n\n## Troubleshooting\n\n### \"pyxle-langserver: command not found\"\n\nThe language server isn't on your PATH. Either:\n- Install it (ships with the framework): `pip install pyxle-framework` — or standalone: `pip install pyxle-langkit`\n- Or set the full path in VS Code settings:\n  `\"pyxle.langserver.command\": \"/path/to/venv/bin/pyxle-langserver\"`\n\n### No JSX completions\n\nJSX completions require **Node.js** and **TypeScript** installed in your\nproject's `node_modules`. The language server spawns a TypeScript\nlanguage service worker for JSX intelligence.\n\n```bash\nnpm install typescript\n```\n\n### No Python completions\n\nPython completions are powered by Jedi, which is installed automatically\nwith `pyxle-langkit`. If completions are missing, verify the install:\n\n```bash\npython -c \"import jedi; print(jedi.__version__)\"\n```\n\n### Status bar shows \"✗ Pyxle\"\n\nThe language server failed to start. Check the **Output** panel in\nVS Code (View → Output → select \"Pyxle Language Server\") for error\ndetails.\n\n### Formatting doesn't change anything\n\nFormatting requires the formatter binaries to be on your PATH:\n- Python: `pip install ruff` (or `pip install black`)\n- JSX: `npm install -g prettier` (or install in your project)\n\n---\n\n## Architecture\n\nThe language toolkit has a server-driven architecture — all intelligence\nlives in the Python LSP server:\n\n- **Python analysis** — [Jedi](https://jedi.readthedocs.io/) runs\n  in-process for completions, hover, and go-to-definition.\n- **JSX analysis** — An embedded TypeScript language service runs as a\n  Node.js subprocess, communicating via NDJSON over stdin/stdout.\n- **Diagnostics** — [pyflakes](https://pypi.org/project/pyflakes/) for\n  Python static analysis, [Babel](https://babeljs.io/) for JSX\n  validation, plus Pyxle-specific rules.\n- **No virtual files** — unlike some language tools that write temporary\n  files to disk, Pyxle's language server keeps everything in memory.\n\nThe VS Code extension is a thin LSP client (~100 lines of TypeScript)\nthat connects to the server and manages the status bar. All the\nintelligence is in the server, making it easy to support other editors.\n\nSource code: [github.com/pyxle-dev/pyxle-langkit](https://github.com/pyxle-dev/pyxle-langkit)\n","prev":{"title":"Deployment","path":"guides/deployment"},"next":{"title":"TypeScript","path":"guides/typescript"}}
\ No newline at end of file
diff --git a/public/docs-data/guides/studio.json b/public/docs-data/guides/studio.json
index 2a333fd..c048ccf 100644
--- a/public/docs-data/guides/studio.json
+++ b/public/docs-data/guides/studio.json
@@ -1 +1 @@
-{"title":"Pyxle Studio","description":"Pyxle Studio is the dashboard built into `pyxle dev` — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester ","html":"<p>Pyxle Studio is the dashboard built into <code>pyxle dev</code> — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester that runs them with real inputs, a live request feed, latency metrics, the effective configuration, and <code>pyxle check</code> diagnostics. Nothing to install, nothing to configure, and <strong>dev-only by construction</strong> — a production <code>pyxle serve</code> process doesn&#39;t contain it.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle studio</code></pre></div><hr>\n<h2 id=\"opening-studio\">Opening Studio</h2><p>Two ways in:</p>\n<ul>\n<li><strong><code>pyxle studio [directory]</code></strong> — runs the same development server as <code>pyxle dev</code> and opens your browser on the dashboard once it&#39;s ready. It takes the server flags (<code>--host</code>, <code>--port</code>, <code>--vite-host</code>, <code>--vite-port</code>, <code>--ssr-workers</code>, <code>--tailwind/--no-tailwind</code>, <code>--config</code>, <code>--verbose</code>), the debugger flags <code>--inspect</code> and <code>--inspect-port</code>, and <code>--open/--no-open</code>. The command also enables the dashboard for that run even when the config turns it off. Full flag list: <a href=\"/docs/reference/cli#pyxle-studio\">CLI reference</a>.</li>\n<li><strong>Any running <code>pyxle dev</code></strong> already serves it — visit <code>http://localhost:8000/__pyxle/studio</code>.</li>\n</ul>\n<p>Studio updates itself live: the request feed streams over Server-Sent Events, and a hot rebuild refreshes the route data, so you can keep it open in a second window while you work.</p>\n<hr>\n<h2 id=\"the-panels\">The panels</h2><h3 id=\"routes\">Routes</h3><p>The route table as the server actually resolved it. For every page: its URL pattern and source file, the <code>@server</code> loader (name and line), each <code>@action</code> with the <strong>real endpoint URL</strong> it&#39;s served at, any <code>websocket</code> handler, the cache posture (the loader&#39;s <code>revalidate</code> and the route&#39;s edge TTL from the <a href=\"/docs/reference/configuration#edge-caching\"><code>cache</code></a> block), the layout loaders that run above the page, and its <code>loading.pyxl</code>/<code>error.pyxl</code> boundaries. API routes are listed below the pages.</p>\n<p>Every source reference is a click-to-open link into your editor — <code>vscode://</code> deep links by default, with Cursor or copy-the-path selectable from the header.</p>\n<h3 id=\"tester\">Tester</h3><p>Run any loader or action against the live server without writing a scratch page. The two halves are deliberately different in how faithful they are:</p>\n<ul>\n<li><strong>Loaders run in-process.</strong> Pick a page, fill in its path params and query string, and Studio calls the <code>@server</code> function directly, timed. Every result shape renders as it would resolve — a plain data dict, a cache-shaped <code>{&quot;data&quot;: ..., &quot;revalidate&quot;: N}</code> return, a raised <code>LoaderError</code> (status and message), or a timeout. The synthesized request is deliberately minimal — no cookies, no session, no caller headers — the tester exercises the <em>loader</em>, not a login flow.</li>\n<li><strong>Actions go through their real HTTP endpoint</strong>, exactly like a browser would. Studio generates an input form from the action&#39;s <a href=\"/docs/core-concepts/server-actions#validating-request-bodies-with-pydantic\">Pydantic body model</a>&#39;s JSON schema (a free-form JSON editor when there isn&#39;t one) and POSTs to the action&#39;s URL — so the CSRF token, Pydantic validation, and any <a href=\"/docs/guides/middleware#route-level-hooks\"><code>routeMiddleware.actions</code></a> auth hooks are all exercised. A <code>401</code> from your auth hook or a <code>422</code> field map in the tester is precisely what a client would get. The response view also surfaces the <code>x-pyxle-invalidate</code> header, so you can confirm an action&#39;s <code>invalidate_routes(...)</code> is telling the client cache what you meant.</li>\n</ul>\n<h3 id=\"requests\">Requests</h3><p>A live feed of the requests your dev server is handling — method, path, status, duration, the route target that handled it, and the request&#39;s correlation id — streamed as they happen. It&#39;s a bounded window (the most recent 200), not a log store. Studio&#39;s own traffic is excluded from both the feed <strong>and</strong> the metrics, so the dashboard never counts itself.</p>\n<h3 id=\"metrics\">Metrics</h3><p>A view over the same in-process <a href=\"/docs/guides/observability#metrics\">metrics registry</a> the observability stack records into: request, SSR-render, loader, and action latency histograms, request totals, and server uptime. No exporter or Prometheus setup needed in dev — this is the zero-config way to see where a slow page spends its time.</p>\n<h3 id=\"config\">Config</h3><p>The effective merged settings and every config block (<code>cors</code>, <code>csrf</code>, <code>cache</code>, <code>observability</code>, …) as the server is actually running them — the fastest answer to &quot;did my config change take effect?&quot;. Secret-shaped values (keys matching <code>secret</code>, <code>token</code>, <code>password</code>, <code>apiKey</code>, …) are redacted before they reach the browser.</p>\n<h3 id=\"check\">Check</h3><p>The same three-level diagnostics as <a href=\"/docs/reference/cli#pyxle-check\"><code>pyxle check</code></a> — Python syntax and structure, Python semantics, JSX — run on demand from the browser, with each finding linking straight to the offending file and line in your editor.</p>\n<hr>\n<h2 id=\"configuration\">Configuration</h2><p>Studio is configured under the <code>&quot;studio&quot;</code> block in <code>pyxle.config.json</code>. It&#39;s on by default in development; a bare boolean is accepted as shorthand (<code>&quot;studio&quot;: false</code> turns it off).</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"studio\": {\n    \"enabled\": true,\n    \"allowedHosts\": [\"my-machine.local\"]\n  }\n}</code></pre></div><table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Type</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>studio</code></td>\n<td><code>object</code> | <code>boolean</code></td>\n<td><code>{}</code></td>\n<td>Studio settings. <code>false</code> disables the dashboard; <code>true</code> (or omitting the block) enables it.</td>\n</tr>\n<tr>\n<td><code>studio.enabled</code></td>\n<td><code>boolean</code></td>\n<td><code>true</code></td>\n<td>Serve the dashboard at <code>/__pyxle/studio</code> under <code>pyxle dev</code>. The <code>pyxle studio</code> command re-enables it for that run even when this is <code>false</code>.</td>\n</tr>\n<tr>\n<td><code>studio.allowedHosts</code></td>\n<td><code>string[]</code></td>\n<td><code>[]</code></td>\n<td>Extra hostnames allowed to reach Studio, extending the built-in <code>Host</code>-header allowlist (loopback names and the configured server host are always allowed).</td>\n</tr>\n</tbody></table>\n<hr>\n<h2 id=\"security-model\">Security model</h2><p>Studio displays your app&#39;s internals, so even as a local tool it is hardened:</p>\n<ul>\n<li><strong>Dev-only by construction.</strong> The code that mounts Studio only exists in the debug-mode dev server. <code>pyxle serve</code> never constructs it, so no configuration mistake can expose the dashboard in production.</li>\n<li><strong>A <code>Host</code>-header allowlist on every Studio endpoint</strong> — the standard defence against DNS rebinding, where an attacker&#39;s domain resolves to <code>127.0.0.1</code> so their page can read your local server. Only loopback names (<code>localhost</code>, <code>127.0.0.1</code>, <code>[::1]</code>) and the configured server host are accepted; add <code>allowedHosts</code> entries when you genuinely reach the dev server through another name (a LAN IP while testing on a phone, a <code>*.local</code> alias).</li>\n<li><strong>Mutating endpoints are <code>POST</code> and require <code>Content-Type: application/json</code></strong>, so a cross-site form or no-CORS fetch can&#39;t invoke the tester — and with <a href=\"/docs/guides/security#csrf-protection\">CSRF protection</a> enabled (the default), they ride the app&#39;s double-submit token too.</li>\n<li><strong>Secrets are redacted</strong> in the config view, and every Studio response is served <code>Cache-Control: no-store</code>.</li>\n</ul>\n<hr>\n<h2 id=\"the-reserved-__pyxle-namespace\">The reserved <code>__pyxle</code> namespace</h2><p>The <code>/__pyxle</code> URL prefix is reserved for framework endpoints — Studio lives under it, and the dev server&#39;s Vite asset proxy never forwards paths beneath it to Vite. Don&#39;t create pages or API routes that map into it.</p>\n<hr>\n<h2 id=\"see-also\">See also</h2><ul>\n<li><a href=\"/docs/guides/debugging-pyxl\">Debugging <code>.pyxl</code> files</a> — breakpoints in <code>.pyxl</code> source; <code>pyxle studio --inspect</code> combines both tools</li>\n<li><a href=\"/docs/guides/observability\">Observability</a> — the metrics registry Studio reads, and production-grade exporters</li>\n<li><a href=\"/docs/reference/cli#pyxle-studio\">CLI reference → <code>pyxle studio</code></a> — every flag</li>\n<li><a href=\"/docs/reference/configuration#studio\">Configuration reference → Studio</a> — the config block</li>\n</ul>\n","toc":[{"depth":2,"text":"Opening Studio","slug":"opening-studio"},{"depth":2,"text":"The panels","slug":"the-panels"},{"depth":3,"text":"Routes","slug":"routes"},{"depth":3,"text":"Tester","slug":"tester"},{"depth":3,"text":"Requests","slug":"requests"},{"depth":3,"text":"Metrics","slug":"metrics"},{"depth":3,"text":"Config","slug":"config"},{"depth":3,"text":"Check","slug":"check"},{"depth":2,"text":"Configuration","slug":"configuration"},{"depth":2,"text":"Security model","slug":"security-model"},{"depth":2,"text":"The reserved __pyxle namespace","slug":"the-reserved-__pyxle-namespace"},{"depth":2,"text":"See also","slug":"see-also"}],"path":"guides/studio","markdown":"# Pyxle Studio\n\nPyxle Studio is the dashboard built into `pyxle dev` — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester that runs them with real inputs, a live request feed, latency metrics, the effective configuration, and `pyxle check` diagnostics. Nothing to install, nothing to configure, and **dev-only by construction** — a production `pyxle serve` process doesn't contain it.\n\n```bash\npyxle studio\n```\n\n---\n\n## Opening Studio\n\nTwo ways in:\n\n- **`pyxle studio [directory]`** — runs the same development server as `pyxle dev` and opens your browser on the dashboard once it's ready. It takes the server flags (`--host`, `--port`, `--vite-host`, `--vite-port`, `--ssr-workers`, `--tailwind/--no-tailwind`, `--config`, `--verbose`), the debugger flags `--inspect` and `--inspect-port`, and `--open/--no-open`. The command also enables the dashboard for that run even when the config turns it off. Full flag list: [CLI reference](https://pyxle.dev/docs/reference/cli.md#pyxle-studio).\n- **Any running `pyxle dev`** already serves it — visit `http://localhost:8000/__pyxle/studio`.\n\nStudio updates itself live: the request feed streams over Server-Sent Events, and a hot rebuild refreshes the route data, so you can keep it open in a second window while you work.\n\n---\n\n## The panels\n\n### Routes\n\nThe route table as the server actually resolved it. For every page: its URL pattern and source file, the `@server` loader (name and line), each `@action` with the **real endpoint URL** it's served at, any `websocket` handler, the cache posture (the loader's `revalidate` and the route's edge TTL from the [`cache`](https://pyxle.dev/docs/reference/configuration.md#edge-caching) block), the layout loaders that run above the page, and its `loading.pyxl`/`error.pyxl` boundaries. API routes are listed below the pages.\n\nEvery source reference is a click-to-open link into your editor — `vscode://` deep links by default, with Cursor or copy-the-path selectable from the header.\n\n### Tester\n\nRun any loader or action against the live server without writing a scratch page. The two halves are deliberately different in how faithful they are:\n\n- **Loaders run in-process.** Pick a page, fill in its path params and query string, and Studio calls the `@server` function directly, timed. Every result shape renders as it would resolve — a plain data dict, a cache-shaped `{\"data\": ..., \"revalidate\": N}` return, a raised `LoaderError` (status and message), or a timeout. The synthesized request is deliberately minimal — no cookies, no session, no caller headers — the tester exercises the *loader*, not a login flow.\n- **Actions go through their real HTTP endpoint**, exactly like a browser would. Studio generates an input form from the action's [Pydantic body model](https://pyxle.dev/docs/core-concepts/server-actions.md#validating-request-bodies-with-pydantic)'s JSON schema (a free-form JSON editor when there isn't one) and POSTs to the action's URL — so the CSRF token, Pydantic validation, and any [`routeMiddleware.actions`](https://pyxle.dev/docs/guides/middleware.md#route-level-hooks) auth hooks are all exercised. A `401` from your auth hook or a `422` field map in the tester is precisely what a client would get. The response view also surfaces the `x-pyxle-invalidate` header, so you can confirm an action's `invalidate_routes(...)` is telling the client cache what you meant.\n\n### Requests\n\nA live feed of the requests your dev server is handling — method, path, status, duration, the route target that handled it, and the request's correlation id — streamed as they happen. It's a bounded window (the most recent 200), not a log store. Studio's own traffic is excluded from both the feed **and** the metrics, so the dashboard never counts itself.\n\n### Metrics\n\nA view over the same in-process [metrics registry](https://pyxle.dev/docs/guides/observability.md#metrics) the observability stack records into: request, SSR-render, loader, and action latency histograms, request totals, and server uptime. No exporter or Prometheus setup needed in dev — this is the zero-config way to see where a slow page spends its time.\n\n### Config\n\nThe effective merged settings and every config block (`cors`, `csrf`, `cache`, `observability`, …) as the server is actually running them — the fastest answer to \"did my config change take effect?\". Secret-shaped values (keys matching `secret`, `token`, `password`, `apiKey`, …) are redacted before they reach the browser.\n\n### Check\n\nThe same three-level diagnostics as [`pyxle check`](https://pyxle.dev/docs/reference/cli.md#pyxle-check) — Python syntax and structure, Python semantics, JSX — run on demand from the browser, with each finding linking straight to the offending file and line in your editor.\n\n---\n\n## Configuration\n\nStudio is configured under the `\"studio\"` block in `pyxle.config.json`. It's on by default in development; a bare boolean is accepted as shorthand (`\"studio\": false` turns it off).\n\n```json\n{\n  \"studio\": {\n    \"enabled\": true,\n    \"allowedHosts\": [\"my-machine.local\"]\n  }\n}\n```\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `studio` | `object` \\| `boolean` | `{}` | Studio settings. `false` disables the dashboard; `true` (or omitting the block) enables it. |\n| `studio.enabled` | `boolean` | `true` | Serve the dashboard at `/__pyxle/studio` under `pyxle dev`. The `pyxle studio` command re-enables it for that run even when this is `false`. |\n| `studio.allowedHosts` | `string[]` | `[]` | Extra hostnames allowed to reach Studio, extending the built-in `Host`-header allowlist (loopback names and the configured server host are always allowed). |\n\n---\n\n## Security model\n\nStudio displays your app's internals, so even as a local tool it is hardened:\n\n- **Dev-only by construction.** The code that mounts Studio only exists in the debug-mode dev server. `pyxle serve` never constructs it, so no configuration mistake can expose the dashboard in production.\n- **A `Host`-header allowlist on every Studio endpoint** — the standard defence against DNS rebinding, where an attacker's domain resolves to `127.0.0.1` so their page can read your local server. Only loopback names (`localhost`, `127.0.0.1`, `[::1]`) and the configured server host are accepted; add `allowedHosts` entries when you genuinely reach the dev server through another name (a LAN IP while testing on a phone, a `*.local` alias).\n- **Mutating endpoints are `POST` and require `Content-Type: application/json`**, so a cross-site form or no-CORS fetch can't invoke the tester — and with [CSRF protection](https://pyxle.dev/docs/guides/security.md#csrf-protection) enabled (the default), they ride the app's double-submit token too.\n- **Secrets are redacted** in the config view, and every Studio response is served `Cache-Control: no-store`.\n\n---\n\n## The reserved `__pyxle` namespace\n\nThe `/__pyxle` URL prefix is reserved for framework endpoints — Studio lives under it, and the dev server's Vite asset proxy never forwards paths beneath it to Vite. Don't create pages or API routes that map into it.\n\n---\n\n## See also\n\n- [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md) — breakpoints in `.pyxl` source; `pyxle studio --inspect` combines both tools\n- [Observability](https://pyxle.dev/docs/guides/observability.md) — the metrics registry Studio reads, and production-grade exporters\n- [CLI reference → `pyxle studio`](https://pyxle.dev/docs/reference/cli.md#pyxle-studio) — every flag\n- [Configuration reference → Studio](https://pyxle.dev/docs/reference/configuration.md#studio) — the config block\n","prev":{"title":"Debugging .pyxl files","path":"guides/debugging-pyxl"},"next":{"title":"Client Components","path":"guides/client-components"}}
\ No newline at end of file
+{"title":"Pyxle Studio","description":"Pyxle Studio is the dashboard built into `pyxle dev` — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester ","html":"<p>Pyxle Studio is the dashboard built into <code>pyxle dev</code> — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester that runs them with real inputs, a live request feed, latency metrics, the effective configuration, and <code>pyxle check</code> diagnostics. Nothing to install, nothing to configure, and <strong>dev-only by construction</strong> — a production <code>pyxle serve</code> process doesn&#39;t contain it.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle studio</code></pre></div><hr>\n<h2 id=\"opening-studio\">Opening Studio</h2><p>Two ways in:</p>\n<ul>\n<li><strong><code>pyxle studio [directory]</code></strong> — runs the same development server as <code>pyxle dev</code> and opens your browser on the dashboard once it&#39;s ready. It takes the server flags (<code>--host</code>, <code>--port</code>, <code>--vite-host</code>, <code>--vite-port</code>, <code>--ssr-workers</code>, <code>--tailwind/--no-tailwind</code>, <code>--config</code>, <code>--verbose</code>), the debugger flags <code>--inspect</code> and <code>--inspect-port</code>, and <code>--open/--no-open</code>. The command also enables the dashboard for that run even when the config turns it off. Full flag list: <a href=\"/docs/reference/cli#pyxle-studio\">CLI reference</a>.</li>\n<li><strong>Any running <code>pyxle dev</code></strong> already serves it — visit <code>http://localhost:8000/__pyxle/studio</code>.</li>\n</ul>\n<p>Studio updates itself live: the request feed streams over Server-Sent Events, and a hot rebuild refreshes the route data, so you can keep it open in a second window while you work.</p>\n<hr>\n<h2 id=\"the-panels\">The panels</h2><h3 id=\"routes\">Routes</h3><p>The route table as the server actually resolved it. For every page: its URL pattern and source file, the <code>@server</code> loader (name and line), each <code>@action</code> with the <strong>real endpoint URL</strong> it&#39;s served at, any <code>websocket</code> handler, the cache posture (the loader&#39;s <code>revalidate</code> and the route&#39;s edge TTL from the <a href=\"/docs/reference/configuration#edge-caching\"><code>cache</code></a> block), the layout loaders that run above the page, and its <code>loading.pyxl</code>/<code>error.pyxl</code> boundaries. API routes are listed below the pages.</p>\n<p>Every source reference is a click-to-open link into your editor — <code>vscode://</code> deep links by default, with Cursor or copy-the-path selectable from the header.</p>\n<h3 id=\"tester\">Tester</h3><p>Run any loader or action against the live server without writing a scratch page. The two halves are deliberately different in how faithful they are:</p>\n<ul>\n<li><strong>Loaders run in-process.</strong> Pick a page, fill in its path params and query string, and Studio calls the <code>@server</code> function directly, timed. Every result shape renders as it would resolve — a plain data dict, a cache-shaped <code>{&quot;data&quot;: ..., &quot;revalidate&quot;: N}</code> return, a raised <code>LoaderError</code> (status and message), or a timeout. The synthesized request is deliberately minimal — no cookies, no session, no caller headers — the tester exercises the <em>loader</em>, not a login flow.</li>\n<li><strong>Actions go through their real HTTP endpoint</strong>, exactly like a browser would. Studio generates an input form from the action&#39;s <a href=\"/docs/core-concepts/server-actions#validating-request-bodies-with-pydantic\">Pydantic body model</a>&#39;s JSON schema (a free-form JSON editor when there isn&#39;t one) and POSTs to the action&#39;s URL — so the CSRF token, Pydantic validation, and any <a href=\"/docs/guides/middleware#route-level-hooks\"><code>routeMiddleware.actions</code></a> auth hooks are all exercised. A <code>401</code> from your auth hook or a <code>422</code> field map in the tester is precisely what a client would get. The response view also surfaces the <code>x-pyxle-invalidate</code> header, so you can confirm an action&#39;s <code>invalidate_routes(...)</code> is telling the client cache what you meant.</li>\n</ul>\n<h3 id=\"requests\">Requests</h3><p>A live feed of the requests your dev server is handling — method, path, status, duration, the route target that handled it, and the request&#39;s correlation id — streamed as they happen. It&#39;s a bounded window (the most recent 200), not a log store. Studio&#39;s own traffic is excluded from both the feed <strong>and</strong> the metrics, so the dashboard never counts itself.</p>\n<h3 id=\"metrics\">Metrics</h3><p>A view over the same in-process <a href=\"/docs/guides/observability#metrics\">metrics registry</a> the observability stack records into: request, SSR-render, loader, and action latency histograms, request totals, and server uptime. No exporter or Prometheus setup needed in dev — this is the zero-config way to see where a slow page spends its time.</p>\n<h3 id=\"config\">Config</h3><p>The effective merged settings and every config block (<code>cors</code>, <code>csrf</code>, <code>cache</code>, <code>observability</code>, …) as the server is actually running them — the fastest answer to &quot;did my config change take effect?&quot;. Secret-shaped values (keys matching <code>secret</code>, <code>token</code>, <code>password</code>, <code>apiKey</code>, …) are redacted before they reach the browser.</p>\n<h3 id=\"check\">Check</h3><p>The same three-level diagnostics as <a href=\"/docs/reference/cli#pyxle-check\"><code>pyxle check</code></a> — Python syntax and structure, Python semantics, JSX — run on demand from the browser, with each finding linking straight to the offending file and line in your editor.</p>\n<hr>\n<h2 id=\"configuration\">Configuration</h2><p>Studio is configured under the <code>&quot;studio&quot;</code> block in <code>pyxle.config.json</code>. It&#39;s on by default in development; a bare boolean is accepted as shorthand (<code>&quot;studio&quot;: false</code> turns it off).</p>\n<div class=\"code-block\" data-lang=\"json\"><pre><code class=\"language-json\">{\n  \"studio\": {\n    \"enabled\": true,\n    \"allowedHosts\": [\"my-machine.local\"]\n  }\n}</code></pre></div><table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Type</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>studio</code></td>\n<td><code>object</code> | <code>boolean</code></td>\n<td><code>{}</code></td>\n<td>Studio settings. <code>false</code> disables the dashboard; <code>true</code> (or omitting the block) enables it.</td>\n</tr>\n<tr>\n<td><code>studio.enabled</code></td>\n<td><code>boolean</code></td>\n<td><code>true</code></td>\n<td>Serve the dashboard at <code>/__pyxle/studio</code> under <code>pyxle dev</code>. The <code>pyxle studio</code> command re-enables it for that run even when this is <code>false</code>.</td>\n</tr>\n<tr>\n<td><code>studio.allowedHosts</code></td>\n<td><code>string[]</code></td>\n<td><code>[]</code></td>\n<td>Extra hostnames allowed to reach Studio, extending the built-in <code>Host</code>-header allowlist (loopback names and the configured server host are always allowed).</td>\n</tr>\n</tbody></table>\n<hr>\n<h2 id=\"security-model\">Security model</h2><p>Studio displays your app&#39;s internals, so even as a local tool it is hardened:</p>\n<ul>\n<li><strong>Dev-only by construction.</strong> The code that mounts Studio only exists in the debug-mode dev server. <code>pyxle serve</code> never constructs it, so no configuration mistake can expose the dashboard in production.</li>\n<li><strong>A <code>Host</code>-header allowlist on every Studio endpoint</strong> — the standard defence against DNS rebinding, where an attacker&#39;s domain resolves to <code>127.0.0.1</code> so their page can read your local server. Only loopback names (<code>localhost</code>, <code>127.0.0.1</code>, <code>[::1]</code>) and the configured server host are accepted; add <code>allowedHosts</code> entries when you genuinely reach the dev server through another name (a LAN IP while testing on a phone, a <code>*.local</code> alias).</li>\n<li><strong>Mutating endpoints are <code>POST</code> and require <code>Content-Type: application/json</code></strong>, so a cross-site form or no-CORS fetch can&#39;t invoke the tester — and with <a href=\"/docs/guides/security#csrf-protection\">CSRF protection</a> enabled (the default), they ride the app&#39;s double-submit token too.</li>\n<li><strong>Secrets are redacted</strong> in the config view, and every Studio response is served <code>Cache-Control: no-store</code>.</li>\n</ul>\n<hr>\n<h2 id=\"the-reserved-__pyxle-namespace\">The reserved <code>__pyxle</code> namespace</h2><p>The <code>/__pyxle</code> URL prefix is reserved for framework endpoints — Studio lives under it, and the dev server&#39;s Vite asset proxy never forwards paths beneath it to Vite. Don&#39;t create pages or API routes that map into it.</p>\n<hr>\n<h2 id=\"see-also\">See also</h2><ul>\n<li><a href=\"/docs/guides/debugging\">Debugging</a> — breakpoints in <code>.pyxl</code> source; <code>pyxle studio --inspect</code> combines both tools</li>\n<li><a href=\"/docs/guides/observability\">Observability</a> — the metrics registry Studio reads, and production-grade exporters</li>\n<li><a href=\"/docs/reference/cli#pyxle-studio\">CLI reference → <code>pyxle studio</code></a> — every flag</li>\n<li><a href=\"/docs/reference/configuration#studio\">Configuration reference → Studio</a> — the config block</li>\n</ul>\n","toc":[{"depth":2,"text":"Opening Studio","slug":"opening-studio"},{"depth":2,"text":"The panels","slug":"the-panels"},{"depth":3,"text":"Routes","slug":"routes"},{"depth":3,"text":"Tester","slug":"tester"},{"depth":3,"text":"Requests","slug":"requests"},{"depth":3,"text":"Metrics","slug":"metrics"},{"depth":3,"text":"Config","slug":"config"},{"depth":3,"text":"Check","slug":"check"},{"depth":2,"text":"Configuration","slug":"configuration"},{"depth":2,"text":"Security model","slug":"security-model"},{"depth":2,"text":"The reserved __pyxle namespace","slug":"the-reserved-__pyxle-namespace"},{"depth":2,"text":"See also","slug":"see-also"}],"path":"guides/studio","markdown":"# Pyxle Studio\n\nPyxle Studio is the dashboard built into `pyxle dev` — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester that runs them with real inputs, a live request feed, latency metrics, the effective configuration, and `pyxle check` diagnostics. Nothing to install, nothing to configure, and **dev-only by construction** — a production `pyxle serve` process doesn't contain it.\n\n```bash\npyxle studio\n```\n\n---\n\n## Opening Studio\n\nTwo ways in:\n\n- **`pyxle studio [directory]`** — runs the same development server as `pyxle dev` and opens your browser on the dashboard once it's ready. It takes the server flags (`--host`, `--port`, `--vite-host`, `--vite-port`, `--ssr-workers`, `--tailwind/--no-tailwind`, `--config`, `--verbose`), the debugger flags `--inspect` and `--inspect-port`, and `--open/--no-open`. The command also enables the dashboard for that run even when the config turns it off. Full flag list: [CLI reference](https://pyxle.dev/docs/reference/cli.md#pyxle-studio).\n- **Any running `pyxle dev`** already serves it — visit `http://localhost:8000/__pyxle/studio`.\n\nStudio updates itself live: the request feed streams over Server-Sent Events, and a hot rebuild refreshes the route data, so you can keep it open in a second window while you work.\n\n---\n\n## The panels\n\n### Routes\n\nThe route table as the server actually resolved it. For every page: its URL pattern and source file, the `@server` loader (name and line), each `@action` with the **real endpoint URL** it's served at, any `websocket` handler, the cache posture (the loader's `revalidate` and the route's edge TTL from the [`cache`](https://pyxle.dev/docs/reference/configuration.md#edge-caching) block), the layout loaders that run above the page, and its `loading.pyxl`/`error.pyxl` boundaries. API routes are listed below the pages.\n\nEvery source reference is a click-to-open link into your editor — `vscode://` deep links by default, with Cursor or copy-the-path selectable from the header.\n\n### Tester\n\nRun any loader or action against the live server without writing a scratch page. The two halves are deliberately different in how faithful they are:\n\n- **Loaders run in-process.** Pick a page, fill in its path params and query string, and Studio calls the `@server` function directly, timed. Every result shape renders as it would resolve — a plain data dict, a cache-shaped `{\"data\": ..., \"revalidate\": N}` return, a raised `LoaderError` (status and message), or a timeout. The synthesized request is deliberately minimal — no cookies, no session, no caller headers — the tester exercises the *loader*, not a login flow.\n- **Actions go through their real HTTP endpoint**, exactly like a browser would. Studio generates an input form from the action's [Pydantic body model](https://pyxle.dev/docs/core-concepts/server-actions.md#validating-request-bodies-with-pydantic)'s JSON schema (a free-form JSON editor when there isn't one) and POSTs to the action's URL — so the CSRF token, Pydantic validation, and any [`routeMiddleware.actions`](https://pyxle.dev/docs/guides/middleware.md#route-level-hooks) auth hooks are all exercised. A `401` from your auth hook or a `422` field map in the tester is precisely what a client would get. The response view also surfaces the `x-pyxle-invalidate` header, so you can confirm an action's `invalidate_routes(...)` is telling the client cache what you meant.\n\n### Requests\n\nA live feed of the requests your dev server is handling — method, path, status, duration, the route target that handled it, and the request's correlation id — streamed as they happen. It's a bounded window (the most recent 200), not a log store. Studio's own traffic is excluded from both the feed **and** the metrics, so the dashboard never counts itself.\n\n### Metrics\n\nA view over the same in-process [metrics registry](https://pyxle.dev/docs/guides/observability.md#metrics) the observability stack records into: request, SSR-render, loader, and action latency histograms, request totals, and server uptime. No exporter or Prometheus setup needed in dev — this is the zero-config way to see where a slow page spends its time.\n\n### Config\n\nThe effective merged settings and every config block (`cors`, `csrf`, `cache`, `observability`, …) as the server is actually running them — the fastest answer to \"did my config change take effect?\". Secret-shaped values (keys matching `secret`, `token`, `password`, `apiKey`, …) are redacted before they reach the browser.\n\n### Check\n\nThe same three-level diagnostics as [`pyxle check`](https://pyxle.dev/docs/reference/cli.md#pyxle-check) — Python syntax and structure, Python semantics, JSX — run on demand from the browser, with each finding linking straight to the offending file and line in your editor.\n\n---\n\n## Configuration\n\nStudio is configured under the `\"studio\"` block in `pyxle.config.json`. It's on by default in development; a bare boolean is accepted as shorthand (`\"studio\": false` turns it off).\n\n```json\n{\n  \"studio\": {\n    \"enabled\": true,\n    \"allowedHosts\": [\"my-machine.local\"]\n  }\n}\n```\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `studio` | `object` \\| `boolean` | `{}` | Studio settings. `false` disables the dashboard; `true` (or omitting the block) enables it. |\n| `studio.enabled` | `boolean` | `true` | Serve the dashboard at `/__pyxle/studio` under `pyxle dev`. The `pyxle studio` command re-enables it for that run even when this is `false`. |\n| `studio.allowedHosts` | `string[]` | `[]` | Extra hostnames allowed to reach Studio, extending the built-in `Host`-header allowlist (loopback names and the configured server host are always allowed). |\n\n---\n\n## Security model\n\nStudio displays your app's internals, so even as a local tool it is hardened:\n\n- **Dev-only by construction.** The code that mounts Studio only exists in the debug-mode dev server. `pyxle serve` never constructs it, so no configuration mistake can expose the dashboard in production.\n- **A `Host`-header allowlist on every Studio endpoint** — the standard defence against DNS rebinding, where an attacker's domain resolves to `127.0.0.1` so their page can read your local server. Only loopback names (`localhost`, `127.0.0.1`, `[::1]`) and the configured server host are accepted; add `allowedHosts` entries when you genuinely reach the dev server through another name (a LAN IP while testing on a phone, a `*.local` alias).\n- **Mutating endpoints are `POST` and require `Content-Type: application/json`**, so a cross-site form or no-CORS fetch can't invoke the tester — and with [CSRF protection](https://pyxle.dev/docs/guides/security.md#csrf-protection) enabled (the default), they ride the app's double-submit token too.\n- **Secrets are redacted** in the config view, and every Studio response is served `Cache-Control: no-store`.\n\n---\n\n## The reserved `__pyxle` namespace\n\nThe `/__pyxle` URL prefix is reserved for framework endpoints — Studio lives under it, and the dev server's Vite asset proxy never forwards paths beneath it to Vite. Don't create pages or API routes that map into it.\n\n---\n\n## See also\n\n- [Debugging](https://pyxle.dev/docs/guides/debugging.md) — breakpoints in `.pyxl` source; `pyxle studio --inspect` combines both tools\n- [Observability](https://pyxle.dev/docs/guides/observability.md) — the metrics registry Studio reads, and production-grade exporters\n- [CLI reference → `pyxle studio`](https://pyxle.dev/docs/reference/cli.md#pyxle-studio) — every flag\n- [Configuration reference → Studio](https://pyxle.dev/docs/reference/configuration.md#studio) — the config block\n","prev":{"title":"Debugging","path":"guides/debugging"},"next":{"title":"Client Components","path":"guides/client-components"}}
\ No newline at end of file
diff --git a/public/docs-data/manifest.json b/public/docs-data/manifest.json
index 75c4737..1dc2ca9 100644
--- a/public/docs-data/manifest.json
+++ b/public/docs-data/manifest.json
@@ -146,11 +146,6 @@
           "slug": "debugging",
           "path": "guides/debugging"
         },
-        {
-          "title": "Debugging .pyxl files",
-          "slug": "debugging-pyxl",
-          "path": "guides/debugging-pyxl"
-        },
         {
           "title": "Pyxle Studio",
           "slug": "studio",
@@ -1156,73 +1151,60 @@
       "path": "guides/debugging",
       "category": "Guides",
       "description": "A Pyxle app has two runtimes: **Python** (your `@server` loaders, `@action` handlers, and the request pipeline) and **Node.js** (the SSR worker that renders your React components to HTML). Knowing whi",
-      "searchText": "Debugging A Pyxle app has two runtimes: Python (your loaders, handlers, and the request pipeline) and Node.js (the SSR worker that renders your React components to HTML). Knowing which side an error comes from tells you where to look. This guide covers both. Read the error first In development, Pyxle surfaces errors in three places at once: The browser error overlay — a fullscreen panel with the message, the file and line, and a breadcrumb of what the framework was doing (loading, rendering, head evaluation). This is the fastest signal for a broken page. The terminal running — the same error, plus the Python traceback for loader/action failures. The browser devtools console — your serverside output is forwarded here during , prefixed , so you can watch server logs without leaving the page. also forwards records and frameworkinternal logs. In production () error responses are intentionally generic — no stack traces or file paths in the body. The full detail goes to the server log instead. Check your process manager's logs (e.g. ). Breakpoints in .pyxl files Beyond , Pyxle has a full breakpointdebugging story: hosts a debug server so VS Code (or any DAP client) can pause a request at a breakpoint set directly in a file — Python loaders/actions on the server side, and the React half through the browser. That workflow has its own guide: Debugging files. Debugging a loader or action (the Python side) and functions are plain functions — debug them like any Python. Drop a breakpoint: Run in a terminal you can type into (not detached) and the prompt appears there when the loader runs. Or add logging — it shows in the terminal and the browser console in dev: To unittest a loader/action in isolation (no server, no browser), use the helpers. Two common Pythonside errors have targeted messages: is missing (e.g. without the plugin) — the error names the attribute and the plugin that provides it. Add the plugin to . A loader raising triggers the nearest boundary; see Error Handling. Debugging rendering (the Node/SSR side) Your React component runs on the server during SSR before it ever runs in the browser. Errors that mention rendering come from the Node worker: (or , , …) — the component touched a browser global at render scope. These don't exist during SSR. Move the code into a or an event handler, or wrap the subtree in . The dev error names your file and the remedy — see Client Components. — a dependency resolved to a CommonJSonly build. Pyxle resolves dependencies ESMfirst; a package that is genuinely CommonJSonly reports an actionable error naming the module. See Thirdparty packages → CommonJS packages and SSR. inside a component prints to the terminal during the server render (and to the browser console after hydration) — so a value that logs twice is telling you it ran on both the server and the client. To step through the SSR worker itself, run it under the Node inspector by setting : then open . This is rarely needed for app code — it's for diagnosing the render transport itself. Reading the compiled output Pyxle compiles each into a Python module and a JavaScript module under the build directory ( in dev, for a production build). Reading them demystifies \"where did my code go\": — the Python half: your / functions with the runtime imports the compiler injected at the top (, etc.). — the JavaScript half: your component, ready for Vite. In development, Python tracebacks already point at your file and line (see Debugging files). A traceback from a production build points at the compiled ; the compiler preserves your code verbatim below the injected header, so mapping back to your is a small, constant offset. The build directory is disposable — delete it and the next / regenerates it. Static checks Two commands catch problems before you run the page: — validates syntax, Python semantics, and JSX. Note that a green check does not prove a page renders: a component reading a loader key that doesn't exist is a runtime error, not a static one. — runs TypeScript over your compiled JSX when you've opted into TypeScript (see the TypeScript guide). Common symptoms Symptom Likely cause Where to look Blank page, overlay shows a Python traceback Loader/action raised terminal; add a Browser global at render scope The named ; use / Missing plugin in Component data is Loader key ≠ component prop Compare the loader's return dict to the component's usage Change didn't take effect Editing built output, or a stale build Edit the source, not Works in dev, fails in prod Debugonly behavior / missing env Server log (prod hides detail from the response) Next steps Debugging files — breakpoints in source with VS Code or any DAP client Error Handling — , error boundaries, 404s Testing — unittest loaders and actions Client Components — browseronly code and",
+      "searchText": "Debugging A Pyxle app has two runtimes: Python (your loaders, handlers, and the request pipeline) and Node.js (the SSR worker that renders your React components to HTML). Knowing which side an error comes from tells you where to look. This guide covers both — including how to set a breakpoint directly in a file, on a line inside a loader and on a line inside the JSX below it, and have both bind. There is no bespoke Pyxle debugger: exposes the Python half to any debugger, dev source maps expose the React half to the browser, and the VS Code extension turns each into one launch. Install the VS Code extension Breakpoint debugging from the editor needs [Pyxle Language Tools][ext] (0.3.0 or newer). Install it from the command line: …or search for Pyxle Language Tools in the Extensions view ( / ), or install it from the [VS Code Marketplace][ext] in a browser. Two more requirements, both onetime: pyxleframework 0.8.0 or newer in the environment VS Code has selected. The debugger relies on line mapping added in 0.8.0 and launches the dev server as , which earlier versions don't provide. Upgrade with . The Python extension () for Pythonside breakpoints. The debugger prompts you if it's missing, and still debugs the React side without it. Nothing else to install — debugpy ships with the framework. The extension also gives you syntax highlighting, diagnostics, completions, hover, gotodefinition and formatting for files; see Editor setup for the full feature list and the languageserver details. [ext]: https://marketplace.visualstudio.com/items?itemName=pyxle.pyxlelanguagetools Quick start: breakpoints in a .pyxl file Open a file and press F5. With no yet, Pyxle asks which half to debug — Backend — Python or Frontend — React. Pick one, or commit the configurations to skip the prompt: Choosing Backend runs your dev server under the Python debugger — one clean debug session that VS Code owns. A breakpoint in a loader or action pauses the request with the frame in the stack. Once the server is ready, your app opens in the browser. Stop, Restart, and Pause all act on that single session — Stop tears the whole server (Vite, SSR workers) down with it. To debug the React half too, run the \"Debug Pyxle app (React browser)\" configuration (it's just ) — a standalone browser session pointed at the running dev server. A breakpoint you set in the component pauses there, in the same file you set the loader breakpoint in. It's a separate session on purpose: keeping the browser out of the Python session's toolbar means each side has clean, unambiguous Stop / Restart / Pause. If the Frontend session had to start its own (nothing was running), stopping it offers to stop that server too — a oneclick \"Stop server\". Restarting the Frontend session keeps the server up. If instead it attached to a server something else started (Backend, or a you ran yourself), stopping Frontend leaves that server running untouched. To debug both halves, start Backend first — it runs the dev server — then start Frontend, which attaches its browser to that same server. Stop on either side then does the right thing: stopping Frontend leaves the server (Backend owns it), stopping Backend tears it down. Frontend on its own works standalone too; just don't start Backend on top of a Frontendstarted server, or they'll race for the port (the second fails to bind with \"address already in use\" — stop the first, then start the other). The launch configuration accepts a few knobs: Property Default Description Pyxle project root (contains and ). Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set to debug only the React side in a standalone browser session. When debugging Python, open the app in your browser once the server is ready. dev server root Page to open. Extra arguments passed to (e.g. ). Keep stepping inside your own code. Set to step into framework internals. To attach to an alreadyrunning server instead of launching one, use (see Attaching from any DAP client). The extension also contributes a \"Pyxle: Open Studio\" command, which opens the running server's Studio dashboard from the command palette. Read the error first In development, Pyxle surfaces errors in three places at once: The browser error overlay — a fullscreen panel with the message, the file and line, and a breadcrumb of what the framework was doing (loading, rendering, head evaluation). This is the fastest signal for a broken page. The terminal running — the same error, plus the Python traceback for loader/action failures. The browser devtools console — your serverside output is forwarded here during , prefixed , so you can watch server logs without leaving the page. also forwards records and frameworkinternal logs. In production () error responses are intentionally generic — no stack traces or file paths in the body. The full detail goes to the server log instead. Check your process manager's logs (e.g. ). Debugging a loader or action (the Python side) and functions are plain functions — debug them like any Python. Set a breakpoint in the editor as above, or drop one in code: For , run in a terminal you can type into (not detached) and the prompt appears there when the loader runs. Or add logging — it shows in the terminal and the browser console in dev: To unittest a loader/action in isolation (no server, no browser), use the helpers. Two common Pythonside errors have targeted messages: is missing (e.g. without the plugin) — the error names the attribute and the plugin that provides it. Add the plugin to . A loader raising triggers the nearest boundary; see Error Handling. Debugging rendering (the Node/SSR side) Your React component runs on the server during SSR before it ever runs in the browser. Errors that mention rendering come from the Node worker: (or , , …) — the component touched a browser global at render scope. These don't exist during SSR. Move the code into a or an event handler, or wrap the subtree in . The dev error names your file and the remedy — see Client Components. — a dependency resolved to a CommonJSonly build. Pyxle resolves dependencies ESMfirst; a package that is genuinely CommonJSonly reports an actionable error naming the module. See Thirdparty packages → CommonJS packages and SSR. inside a component prints to the terminal during the server render (and to the browser console after hydration) — so a value that logs twice is telling you it ran on both the server and the client. To step through the SSR worker itself, run it under the Node inspector by setting : then open . This is rarely needed for app code — it's for diagnosing the render transport itself. How the breakpoint mapping works The feature is two stock debuggers plus line mapping, which is why it works so broadly: The Python half ( loaders, handlers). The compiler embeds a line map in every generated server module, and in development the server imports those modules with and line numbers remapped to the original source. To debugpy the running code simply is your file, so breakpoints set there bind natively. The default launch runs the dev server under debugpy directly; instead hosts a debugpy server for clients to attach to. The React half (the JSX in the same file). The compiler writes a sourcemap sidecar for each generated module, and the dev Vite config includes a small devonly plugin that attaches those maps pointing back at the real file on disk. VS Code's builtin jsdebug resolves that file and binds breakpoints in it; browser devtools map every position the same way. The map is fetched by the browser, so it carries only the JSX lines — the and Python in the same file is never sent to a client. Both mappings exist only in development. A production build ships neither. CLI reference The debugger flags live on (and , which accepts and ): Flag Default Description / Host a debugpy debug server inside the devserver process, bound to . debugpy ships with the framework. Port for the debug server. When it's busy, P",
       "headings": [
+        "Install the VS Code extension",
+        "Quick start: breakpoints in a .pyxl file",
         "Read the error first",
-        "Breakpoints in .pyxl files",
         "Debugging a loader or action (the Python side)",
         "Debugging rendering (the Node/SSR side)",
+        "How the breakpoint mapping works",
+        "CLI reference",
+        "Attaching from any DAP client",
+        "Tracebacks point at .pyxl",
+        "The discovery file",
         "Reading the compiled output",
         "Static checks",
+        "Caveats",
+        "Troubleshooting",
         "Common symptoms",
         "Next steps"
       ],
       "keywords": [
         "debug",
         "debugging",
+        "debugger",
         "pdb",
         "breakpoint",
+        "breakpoints",
+        "debugpy",
         "traceback",
         "error overlay",
         "server logs",
         "console.log",
         "inspect",
+        "--inspect",
         "node inspector",
         "ssr error",
         "compiled output",
         ".pyxle-build",
         "window is not defined",
         "stack trace",
-        "logging"
-      ]
-    },
-    {
-      "title": "Debugging .pyxl files",
-      "path": "guides/debugging-pyxl",
-      "category": "Guides",
-      "description": "Set a breakpoint directly in your `.pyxl` source — on a line inside a `@server` loader *and* on a line inside the JSX below it — and both bind. `pyxle dev --inspect` exposes the Python half to any deb",
-      "searchText": "Debugging .pyxl files Set a breakpoint directly in your source — on a line inside a loader and on a line inside the JSX below it — and both bind. exposes the Python half to any debugger, dev source maps expose the React half to the browser, and the VS Code extension turns each into one launch: F5 for the Python side, a second configuration for the React side. No custom debugger, no compiledfile archaeology. Quick start (VS Code) 1. Install the Pyxle Language Tools extension (0.3.0 or later). For Pythonside breakpoints, also install the Python extension () — the debugger prompts you if it's missing and still debugs the React side without it. 2. Make sure your project uses pyxleframework 0.8.0 or newer (the debugger relies on line mapping shipped in 0.8.0). Nothing else to install: debugpy ships with the framework. 3. Open a file and press F5. With no yet, Pyxle asks which half to debug — Backend — Python or Frontend — React. Pick one, or commit the configurations to skip the prompt: Choosing Backend runs your dev server under the Python debugger — one clean debug session that VS Code owns. A breakpoint in a loader or action pauses the request in VS Code with the frame in the stack. Once the server is ready, your app opens in the browser. Stop, Restart, and Pause all act on that single session — Stop tears the whole server (Vite, SSR workers) down with it. It needs the Python extension (); the debugger offers to install it if it's missing. To debug the React half too, run the \"Debug Pyxle app (React browser)\" configuration (it's just ) — a standalone Chrome session pointed at the running dev server. A breakpoint you set in the component pauses there, in the same file you set the loader breakpoint in. It's a separate session on purpose: keeping the browser out of the Python session's toolbar means each side has clean, unambiguous Stop / Restart / Pause. If the Frontend session had to start its own (nothing was running), stopping it offers to stop that server too — a oneclick \"Stop server\". Restarting the Frontend session keeps the server up (no prompt). If instead it attached to a server something else started (Backend, or a you ran yourself), stopping Frontend leaves that server running untouched — you stop it where you started it. To debug both halves, start Backend first — it runs the dev server — then start Frontend, which attaches its browser to that same server. That way Stop on either side does the right thing: stopping Frontend leaves the server (Backend owns it), stopping Backend tears it down. Frontend on its own works standalone too; just don't start Backend on top of a Frontendstarted server, or they'll race for the port (the second one fails to bind with an \"address already in use\" error — stop the first, then start the other). The launch configuration accepts a few knobs: Property Default Description Pyxle project root (contains and ). Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set to debug only the React side in a standalone Chrome session. When debugging Python, open the app in your browser once the server is ready. dev server root Page to open. Extra arguments passed to (e.g. ). Keep stepping inside your own code. Set to step into framework internals. To attach to an alreadyrunning server instead of launching one, use (see Attaching from any DAP client). The extension also contributes a \"Pyxle: Open Studio\" command, which opens the running server's Studio dashboard from the command palette. How it works There is no bespoke Pyxle debugger — the feature is two stock debuggers plus line mapping, which is why it works so broadly: The Python half ( loaders, handlers). The compiler embeds a line map in every generated server module, and in development the server imports those modules with and line numbers remapped to the original source. To debugpy the running code simply is your file, so breakpoints set there bind natively. The default launch runs the dev server under debugpy directly; instead hosts a debugpy server for clients to attach to. The React half (the JSX in the same file). The compiler writes a sourcemap sidecar for each generated module, and the dev Vite config includes a small devonly plugin that attaches those maps pointing back at the real file on disk. VS Code's builtin jsdebug resolves that file and binds breakpoints in it; browser devtools map every position the same way. Both mappings exist only in development. A production build ships neither. CLI reference The debugger flags live on (and , which accepts and ): Flag Default Description / Host a debugpy debug server inside the devserver process, bound to . debugpy ships with the framework. Port for the debug server. When it's busy, Pyxle falls back to an ephemeral port and records the actual endpoint in the discovery file, so editor attach flows keep working. / With : block startup until a debugger attaches — for breakpoints in code that runs during boot. Only the devserver process is debugged: the debugger environment is never injected into subprocesses (Vite, SSR workers, or anything a loader shells out to). Attaching from any DAP client debugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a requirement. From neovim (), Emacs (), or any other DAP client, attach to the endpoint printed — the equivalent of: Set breakpoints in files by their real path. Because the server's code objects already carry filenames, no path mappings or source translations are needed — stack frames, stepping, and in a paused loader all just work. Tracebacks point at .pyxl now The same line mapping improves life with no debugger attached at all: in development, a Python traceback from a loader or action names your file and line — not a compiled module under . The terminal, the browser error overlay, and your logs all agree on where the error actually is. The discovery file While running, the dev server writes describing itself, and removes it on shutdown. This is what editor tooling (like the VS Code extension's F5 flow and \"Open Studio\") reads instead of guessing ports: Key Type Meaning Devserver process id. Pyxle version. Unix timestamp of server start. Absolute path of the project. of the Starlette server. of the Vite dev server. Browserreachable base URL. \\ Studio dashboard URL ( when Studio is disabled). \\ of the debug server ( without ). The file is written atomically, and a failed write never takes down the server. Caveats Worth knowing before you rely on it: A paused breakpoint pauses the whole server. is a single process, so while you sit at a breakpoint every inflight request waits. That's the right tradeoff for development — and one reason production never hosts a debugger. defaults to . Stepping stays inside your own code; set it to in the launch configuration to step into Pyxle's internals. React debugging happens in the browser, not the SSR worker. Your component renders first in the Node SSR process, but the debugger doesn't attach there — it's the same code with the same source maps in the browser, which is where you debug it. (Serverrender output still prints to the terminal — see Debugging.) Production is untouched. never remaps line numbers and never hosts debugpy, regardless of flags or config. debugpy ships with the framework — works on a default install, no extra needed. Troubleshooting \"No module named pyxle\" when you press F5. VS Code has a Python interpreter selected that doesn't have pyxle installed — a common split when pyxle lives in one environment (a virtualenv, pyenv, or system Python) while VS Code points at another. The launch runs under the selected interpreter, so it has to be the one where is installed. The extension checks this before launching and, when it doesn't match, offers a Select Interpreter button; you can also run Python: Select Interpreter from the command palette and pick the environment your terminal's command uses ( / shows it). This is the same interpreter selection every Pytho",
-      "headings": [
-        "Quick start (VS Code)",
-        "How it works",
-        "CLI reference",
-        "Attaching from any DAP client",
-        "Tracebacks point at .pyxl now",
-        "The discovery file",
-        "Caveats",
-        "Troubleshooting",
-        "See also"
-      ],
-      "keywords": [
-        "debugger",
-        "breakpoints",
-        "breakpoint",
-        "debugpy",
+        "logging",
         "vs code",
         "vscode",
+        "extension",
+        "install extension",
         "step through",
         "step debugging",
         "dap",
-        "--inspect",
-        "inspect",
         "f5",
         "attach",
         "launch.json",
         "source maps",
         "js-debug",
         "dev-server.json",
-        "pause",
-        "debug extra"
+        "pause"
       ]
     },
     {
@@ -1230,7 +1212,7 @@
       "path": "guides/studio",
       "category": "Guides",
       "description": "Pyxle Studio is the dashboard built into `pyxle dev` — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester ",
-      "searchText": "Pyxle Studio Pyxle Studio is the dashboard built into — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester that runs them with real inputs, a live request feed, latency metrics, the effective configuration, and diagnostics. Nothing to install, nothing to configure, and devonly by construction — a production process doesn't contain it. Opening Studio Two ways in: — runs the same development server as and opens your browser on the dashboard once it's ready. It takes the server flags (, , , , , , , ), the debugger flags and , and . The command also enables the dashboard for that run even when the config turns it off. Full flag list: CLI reference. Any running already serves it — visit . Studio updates itself live: the request feed streams over ServerSent Events, and a hot rebuild refreshes the route data, so you can keep it open in a second window while you work. The panels Routes The route table as the server actually resolved it. For every page: its URL pattern and source file, the loader (name and line), each with the real endpoint URL it's served at, any handler, the cache posture (the loader's and the route's edge TTL from the [](../reference/configuration.md#edgecaching) block), the layout loaders that run above the page, and its / boundaries. API routes are listed below the pages. Every source reference is a clicktoopen link into your editor — deep links by default, with Cursor or copythepath selectable from the header. Tester Run any loader or action against the live server without writing a scratch page. The two halves are deliberately different in how faithful they are: Loaders run inprocess. Pick a page, fill in its path params and query string, and Studio calls the function directly, timed. Every result shape renders as it would resolve — a plain data dict, a cacheshaped return, a raised (status and message), or a timeout. The synthesized request is deliberately minimal — no cookies, no session, no caller headers — the tester exercises the loader, not a login flow. Actions go through their real HTTP endpoint, exactly like a browser would. Studio generates an input form from the action's Pydantic body model's JSON schema (a freeform JSON editor when there isn't one) and POSTs to the action's URL — so the CSRF token, Pydantic validation, and any [](middleware.md#routelevelhooks) auth hooks are all exercised. A from your auth hook or a field map in the tester is precisely what a client would get. The response view also surfaces the header, so you can confirm an action's is telling the client cache what you meant. Requests A live feed of the requests your dev server is handling — method, path, status, duration, the route target that handled it, and the request's correlation id — streamed as they happen. It's a bounded window (the most recent 200), not a log store. Studio's own traffic is excluded from both the feed and the metrics, so the dashboard never counts itself. Metrics A view over the same inprocess metrics registry the observability stack records into: request, SSRrender, loader, and action latency histograms, request totals, and server uptime. No exporter or Prometheus setup needed in dev — this is the zeroconfig way to see where a slow page spends its time. Config The effective merged settings and every config block (, , , , …) as the server is actually running them — the fastest answer to \"did my config change take effect?\". Secretshaped values (keys matching , , , , …) are redacted before they reach the browser. Check The same threelevel diagnostics as [](../reference/cli.md#pyxlecheck) — Python syntax and structure, Python semantics, JSX — run on demand from the browser, with each finding linking straight to the offending file and line in your editor. Configuration Studio is configured under the block in . It's on by default in development; a bare boolean is accepted as shorthand ( turns it off). Key Type Default Description \\ Studio settings. disables the dashboard; (or omitting the block) enables it. Serve the dashboard at under . The command reenables it for that run even when this is . Extra hostnames allowed to reach Studio, extending the builtin header allowlist (loopback names and the configured server host are always allowed). Security model Studio displays your app's internals, so even as a local tool it is hardened: Devonly by construction. The code that mounts Studio only exists in the debugmode dev server. never constructs it, so no configuration mistake can expose the dashboard in production. A header allowlist on every Studio endpoint — the standard defence against DNS rebinding, where an attacker's domain resolves to so their page can read your local server. Only loopback names (, , ) and the configured server host are accepted; add entries when you genuinely reach the dev server through another name (a LAN IP while testing on a phone, a alias). Mutating endpoints are and require , so a crosssite form or noCORS fetch can't invoke the tester — and with CSRF protection enabled (the default), they ride the app's doublesubmit token too. Secrets are redacted in the config view, and every Studio response is served . The reserved namespace The URL prefix is reserved for framework endpoints — Studio lives under it, and the dev server's Vite asset proxy never forwards paths beneath it to Vite. Don't create pages or API routes that map into it. See also Debugging files — breakpoints in source; combines both tools Observability — the metrics registry Studio reads, and productiongrade exporters CLI reference → — every flag Configuration reference → Studio — the config block",
+      "searchText": "Pyxle Studio Pyxle Studio is the dashboard built into — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester that runs them with real inputs, a live request feed, latency metrics, the effective configuration, and diagnostics. Nothing to install, nothing to configure, and devonly by construction — a production process doesn't contain it. Opening Studio Two ways in: — runs the same development server as and opens your browser on the dashboard once it's ready. It takes the server flags (, , , , , , , ), the debugger flags and , and . The command also enables the dashboard for that run even when the config turns it off. Full flag list: CLI reference. Any running already serves it — visit . Studio updates itself live: the request feed streams over ServerSent Events, and a hot rebuild refreshes the route data, so you can keep it open in a second window while you work. The panels Routes The route table as the server actually resolved it. For every page: its URL pattern and source file, the loader (name and line), each with the real endpoint URL it's served at, any handler, the cache posture (the loader's and the route's edge TTL from the [](../reference/configuration.md#edgecaching) block), the layout loaders that run above the page, and its / boundaries. API routes are listed below the pages. Every source reference is a clicktoopen link into your editor — deep links by default, with Cursor or copythepath selectable from the header. Tester Run any loader or action against the live server without writing a scratch page. The two halves are deliberately different in how faithful they are: Loaders run inprocess. Pick a page, fill in its path params and query string, and Studio calls the function directly, timed. Every result shape renders as it would resolve — a plain data dict, a cacheshaped return, a raised (status and message), or a timeout. The synthesized request is deliberately minimal — no cookies, no session, no caller headers — the tester exercises the loader, not a login flow. Actions go through their real HTTP endpoint, exactly like a browser would. Studio generates an input form from the action's Pydantic body model's JSON schema (a freeform JSON editor when there isn't one) and POSTs to the action's URL — so the CSRF token, Pydantic validation, and any [](middleware.md#routelevelhooks) auth hooks are all exercised. A from your auth hook or a field map in the tester is precisely what a client would get. The response view also surfaces the header, so you can confirm an action's is telling the client cache what you meant. Requests A live feed of the requests your dev server is handling — method, path, status, duration, the route target that handled it, and the request's correlation id — streamed as they happen. It's a bounded window (the most recent 200), not a log store. Studio's own traffic is excluded from both the feed and the metrics, so the dashboard never counts itself. Metrics A view over the same inprocess metrics registry the observability stack records into: request, SSRrender, loader, and action latency histograms, request totals, and server uptime. No exporter or Prometheus setup needed in dev — this is the zeroconfig way to see where a slow page spends its time. Config The effective merged settings and every config block (, , , , …) as the server is actually running them — the fastest answer to \"did my config change take effect?\". Secretshaped values (keys matching , , , , …) are redacted before they reach the browser. Check The same threelevel diagnostics as [](../reference/cli.md#pyxlecheck) — Python syntax and structure, Python semantics, JSX — run on demand from the browser, with each finding linking straight to the offending file and line in your editor. Configuration Studio is configured under the block in . It's on by default in development; a bare boolean is accepted as shorthand ( turns it off). Key Type Default Description \\ Studio settings. disables the dashboard; (or omitting the block) enables it. Serve the dashboard at under . The command reenables it for that run even when this is . Extra hostnames allowed to reach Studio, extending the builtin header allowlist (loopback names and the configured server host are always allowed). Security model Studio displays your app's internals, so even as a local tool it is hardened: Devonly by construction. The code that mounts Studio only exists in the debugmode dev server. never constructs it, so no configuration mistake can expose the dashboard in production. A header allowlist on every Studio endpoint — the standard defence against DNS rebinding, where an attacker's domain resolves to so their page can read your local server. Only loopback names (, , ) and the configured server host are accepted; add entries when you genuinely reach the dev server through another name (a LAN IP while testing on a phone, a alias). Mutating endpoints are and require , so a crosssite form or noCORS fetch can't invoke the tester — and with CSRF protection enabled (the default), they ride the app's doublesubmit token too. Secrets are redacted in the config view, and every Studio response is served . The reserved namespace The URL prefix is reserved for framework endpoints — Studio lives under it, and the dev server's Vite asset proxy never forwards paths beneath it to Vite. Don't create pages or API routes that map into it. See also Debugging — breakpoints in source; combines both tools Observability — the metrics registry Studio reads, and productiongrade exporters CLI reference → — every flag Configuration reference → Studio — the config block",
       "headings": [
         "Opening Studio",
         "The panels",
@@ -1631,7 +1613,7 @@
       "path": "reference/cli",
       "category": "Reference",
       "description": "The `pyxle` CLI manages Pyxle projects from scaffolding to production.",
-      "searchText": "CLI Reference The CLI manages Pyxle projects from scaffolding to production. Global options Flag Description Show Pyxle version and exit Output format (default: ) / Show debuglevel output / Suppress informational output; show only warnings and errors Install shell completion for the current shell Print shell completion (to copy or customize) Create a new Pyxle project. is interactive: when stdin is a terminal and no flag pins the choice, it walks you through arrowkey selections — Tailwind CSS, shadcn/ui (only if Tailwind is enabled), and whether to customize the default import alias (; the value input appears only if you say yes). When stdin is not a terminal (CI, pipes), it never prompts — it uses the flags and defaults below. Argument / Flag Default Description (required) Project directory to create. A name like creates a new directory; scaffolds into the current directory (deriving the name from it). Running with no argument is an error. / Overwrite an existing directory (or scaffold into a nonempty current directory). / Project template. Only is supported today (other values error). / prompt → off Set up Tailwind CSS v4 (wired into Vite). / prompt → off Set up shadcn/ui (implies ). Import alias for project modules (e.g. ). / Accept all defaults without prompting (no Tailwind, no shadcn, default alias). / Run and after scaffolding. Examples: Install Python and Node.js dependencies. Argument / Flag Default Description Project directory / Install Python deps via / Install Node deps via Pass to , for externallymanaged (PEP 668) environments without a virtualenv. Use with care. Examples: Outside a virtualenv, warns about PEP 668 (\"externallymanagedenvironment\") and recommends creating a venv first; pass to install anyway. Start the development server with hot reload. Argument / Flag Default Description Project directory Starlette server bind address Starlette server port Vite dev server bind address Vite dev server port / Enable debug mode Number of persistent SSR worker processes ( = perrequest subprocess mode) Path to / Print merged configuration before starting / Autostart the legacy standalone Tailwind v3 CLI watcher when a handwritten is present. Tailwind v4 projects (the scaffold default when you opt into Tailwind) run through the plugin and ignore this flag. / Periodically print a live observability panel (request/SSR metrics) to the terminal / Host a debugpy debug server (bound to ) so VS Code or any DAP client can set breakpoints directly in files — see Debugging .pyxl files. debugpy ships with the framework. Port for the debug server (with ). Falls back to an ephemeral port when busy; the actual endpoint is recorded in . / With : wait for a debugger to attach before starting the server — for breakpoints in code that runs during boot. / Restore full output: the raw Vite log firehose, debuglevel internals, and server logs in the browser console. Equivalent to the global . Examples: What it does: 1. Loads configuration from + environment variables + CLI flags 2. Compiles files into Python and JSX modules 3. Starts the Vite dev server for React hot reload (Tailwind v4 compiles here via the plugin) 4. Starts the legacy Tailwind v3 watcher only if a handwritten is detected 5. Starts the Starlette ASGI server 6. Watches for file changes and recompiles automatically Console output. By default prints a clean, curated console — a startup summary (the local URL, the Vite URL, the route count, and the total \"ready in X ms\"), a concise oneline notice per incremental rebuild (), and any warnings or errors. The raw linebyline Vite firehose and debuglevel internals are hidden. Pass (or , or the global ) to restore the full output when troubleshooting. Genuine signal — errors, warnings, the URLs, and rebuild success/failure — is always shown, at every verbosity. Server logs in the browser console (dev only). While is running, your serverside output (from loaders, actions, and your own modules) is forwarded to the browser devtools console, prefixed and mapped to the matching method ( → , → , → ). This lets you follow server logs without leaving the browser. By default only and above from your own loggers are forwarded; additionally forwards records and the framework's own internal loggers. This is strictly a development feature — it never runs under and never appears in the production bundle. Run the dev server and open the Pyxle Studio dashboard. runs the same development server as — Studio is part of it, served at — and opens your browser on the dashboard once the server is ready. Debug mode is forced on (Studio is devonly), and the dashboard is enabled for this run even when the config sets . Argument / Flag Default Description Project directory Starlette server bind address Starlette server port Vite dev server bind address Vite dev server port Number of persistent SSR worker processes ( = perrequest subprocess mode) Path to / Autostart the legacy Tailwind v3 watcher when a handwritten is present (same behavior as ) / Open the Studio dashboard in the system browser once the server is ready / Host a debugpy debug server for breakpoint debugging — see Debugging .pyxl files Port for the debug server (with ; falls back to an ephemeral port when busy) / Restore full output (raw Vite logs, debug internals). Equivalent to . Examples: Build productionready assets. Argument / Flag Default Description Project directory Path to Output directory for build artifacts / Reuse cached artifacts / Prerender loaderless, nondynamic pages to HTML at build time (SSG) — see Caching / Print a JS/CSS bundlesize report (raw + gzip, largest first) after the build — see Build Optimization Examples: Serve a production build (without Vite). Argument / Flag Default Description Project directory Bind address Port number Directory with production artifacts / Skip running build first Path to / Serve static assets directly from Pyxle Number of persistent SSR worker processes, per server worker ( = autosize to CPU cores, capped at 4) / Number of server worker processes (one per CPU core); enables multicore serving; autodetects from CPU cores Examples: With (N 1), Pyxle serves the build across uvicorn worker processes. Each is an independent server with its own SSR pool, so applies per worker (total render processes = ). See the deployment guide for sizing guidance. Validate files, configuration, and dependencies without starting the server. Each file is checked at three levels: Python syntax (via ) and Pyxle structural rules (loader/action shape, , …). Python semantics (via pyflakes): undefined names — e.g. a symbol you but never imported — unused imports, redefinitions. Compilerinjected runtime names (, , , , …) are recognized, so the idiomatic patterns never read as undefined. JSX syntax (via Babel): unclosed tags/expressions, mismatched braces, TypeScript in a client block, and duplicate (which Babel accepts but the build rejects). As of 0.7.0 the JSX level works out of the box — , which provides the Babelbased checker, ships with the framework. On earlier versions it required the extra (); without it, the JSX check reported itself unavailable. What a green check proves — and what it doesn't. is a static gate: it validates syntax, Python semantics, and JSX syntax. It does not render your pages, so a mistake that only exists at runtime — a component reading when the loader returns , a loader whose query fails against the real database — surfaces when the page renders, not here. Treat a clean check as \"this compiles\"; loading the page under (or a test that requests it) remains the runtime proof. Argument / Flag Default Description Project directory Path to Example output: Errors are reported per file as , with the file path on the next line (every file is checked, so one broken file never aborts the scan): Exit code is when clean, when any error is found. Run TypeScript typechecking on compiled JSX output. Requires in your . Runs against the compiled JSX in . Argument / Flag Default Desc",
+      "searchText": "CLI Reference The CLI manages Pyxle projects from scaffolding to production. Global options Flag Description Show Pyxle version and exit Output format (default: ) / Show debuglevel output / Suppress informational output; show only warnings and errors Install shell completion for the current shell Print shell completion (to copy or customize) Create a new Pyxle project. is interactive: when stdin is a terminal and no flag pins the choice, it walks you through arrowkey selections — Tailwind CSS, shadcn/ui (only if Tailwind is enabled), and whether to customize the default import alias (; the value input appears only if you say yes). When stdin is not a terminal (CI, pipes), it never prompts — it uses the flags and defaults below. Argument / Flag Default Description (required) Project directory to create. A name like creates a new directory; scaffolds into the current directory (deriving the name from it). Running with no argument is an error. / Overwrite an existing directory (or scaffold into a nonempty current directory). / Project template. Only is supported today (other values error). / prompt → off Set up Tailwind CSS v4 (wired into Vite). / prompt → off Set up shadcn/ui (implies ). Import alias for project modules (e.g. ). / Accept all defaults without prompting (no Tailwind, no shadcn, default alias). / Run and after scaffolding. Examples: Install Python and Node.js dependencies. Argument / Flag Default Description Project directory / Install Python deps via / Install Node deps via Pass to , for externallymanaged (PEP 668) environments without a virtualenv. Use with care. Examples: Outside a virtualenv, warns about PEP 668 (\"externallymanagedenvironment\") and recommends creating a venv first; pass to install anyway. Start the development server with hot reload. Argument / Flag Default Description Project directory Starlette server bind address Starlette server port Vite dev server bind address Vite dev server port / Enable debug mode Number of persistent SSR worker processes ( = perrequest subprocess mode) Path to / Print merged configuration before starting / Autostart the legacy standalone Tailwind v3 CLI watcher when a handwritten is present. Tailwind v4 projects (the scaffold default when you opt into Tailwind) run through the plugin and ignore this flag. / Periodically print a live observability panel (request/SSR metrics) to the terminal / Host a debugpy debug server (bound to ) so VS Code or any DAP client can set breakpoints directly in files — see Debugging. debugpy ships with the framework. Port for the debug server (with ). Falls back to an ephemeral port when busy; the actual endpoint is recorded in . / With : wait for a debugger to attach before starting the server — for breakpoints in code that runs during boot. / Restore full output: the raw Vite log firehose, debuglevel internals, and server logs in the browser console. Equivalent to the global . Examples: What it does: 1. Loads configuration from + environment variables + CLI flags 2. Compiles files into Python and JSX modules 3. Starts the Vite dev server for React hot reload (Tailwind v4 compiles here via the plugin) 4. Starts the legacy Tailwind v3 watcher only if a handwritten is detected 5. Starts the Starlette ASGI server 6. Watches for file changes and recompiles automatically Console output. By default prints a clean, curated console — a startup summary (the local URL, the Vite URL, the route count, and the total \"ready in X ms\"), a concise oneline notice per incremental rebuild (), and any warnings or errors. The raw linebyline Vite firehose and debuglevel internals are hidden. Pass (or , or the global ) to restore the full output when troubleshooting. Genuine signal — errors, warnings, the URLs, and rebuild success/failure — is always shown, at every verbosity. Server logs in the browser console (dev only). While is running, your serverside output (from loaders, actions, and your own modules) is forwarded to the browser devtools console, prefixed and mapped to the matching method ( → , → , → ). This lets you follow server logs without leaving the browser. By default only and above from your own loggers are forwarded; additionally forwards records and the framework's own internal loggers. This is strictly a development feature — it never runs under and never appears in the production bundle. Run the dev server and open the Pyxle Studio dashboard. runs the same development server as — Studio is part of it, served at — and opens your browser on the dashboard once the server is ready. Debug mode is forced on (Studio is devonly), and the dashboard is enabled for this run even when the config sets . Argument / Flag Default Description Project directory Starlette server bind address Starlette server port Vite dev server bind address Vite dev server port Number of persistent SSR worker processes ( = perrequest subprocess mode) Path to / Autostart the legacy Tailwind v3 watcher when a handwritten is present (same behavior as ) / Open the Studio dashboard in the system browser once the server is ready / Host a debugpy debug server for breakpoint debugging — see Debugging Port for the debug server (with ; falls back to an ephemeral port when busy) / Restore full output (raw Vite logs, debug internals). Equivalent to . Examples: Build productionready assets. Argument / Flag Default Description Project directory Path to Output directory for build artifacts / Reuse cached artifacts / Prerender loaderless, nondynamic pages to HTML at build time (SSG) — see Caching / Print a JS/CSS bundlesize report (raw + gzip, largest first) after the build — see Build Optimization Examples: Serve a production build (without Vite). Argument / Flag Default Description Project directory Bind address Port number Directory with production artifacts / Skip running build first Path to / Serve static assets directly from Pyxle Number of persistent SSR worker processes, per server worker ( = autosize to CPU cores, capped at 4) / Number of server worker processes (one per CPU core); enables multicore serving; autodetects from CPU cores Examples: With (N 1), Pyxle serves the build across uvicorn worker processes. Each is an independent server with its own SSR pool, so applies per worker (total render processes = ). See the deployment guide for sizing guidance. Validate files, configuration, and dependencies without starting the server. Each file is checked at three levels: Python syntax (via ) and Pyxle structural rules (loader/action shape, , …). Python semantics (via pyflakes): undefined names — e.g. a symbol you but never imported — unused imports, redefinitions. Compilerinjected runtime names (, , , , …) are recognized, so the idiomatic patterns never read as undefined. JSX syntax (via Babel): unclosed tags/expressions, mismatched braces, TypeScript in a client block, and duplicate (which Babel accepts but the build rejects). As of 0.7.0 the JSX level works out of the box — , which provides the Babelbased checker, ships with the framework. On earlier versions it required the extra (); without it, the JSX check reported itself unavailable. What a green check proves — and what it doesn't. is a static gate: it validates syntax, Python semantics, and JSX syntax. It does not render your pages, so a mistake that only exists at runtime — a component reading when the loader returns , a loader whose query fails against the real database — surfaces when the page renders, not here. Treat a clean check as \"this compiles\"; loading the page under (or a test that requests it) remains the runtime proof. Argument / Flag Default Description Project directory Path to Example output: Errors are reported per file as , with the file path on the next line (every file is checked, so one broken file never aborts the scan): Exit code is when clean, when any error is found. Run TypeScript typechecking on compiled JSX output. Requires in your . Runs against the compiled JSX in . Argument / Flag Default Description Project director",
       "headings": [
         "Global options",
         "pyxle init",
@@ -2416,7 +2398,7 @@
       "path": "changelog",
       "category": "Changelog",
       "description": "Release notes for Pyxle. While we're in beta (`0.x`), minor versions may include breaking changes — those are called out explicitly. To upgrade, run `pip install --upgrade pyxle-framework`.",
-      "searchText": "Changelog Release notes for Pyxle. While we're in beta (), minor versions may include breaking changes — those are called out explicitly. To upgrade, run . 0.8.0 Pyxle Studio — a dashboard built into . Served at : every route with its loader, actions, cache posture, and boundaries; an interactive tester (loaders run inprocess, actions go through their real endpoint — CSRF, validation, and auth hooks included); a live request feed; latency metrics; the effective config (secrets redacted); and inbrowser . Devonly by construction, with a header allowlist. Pyxle Studio. New command. Runs the dev server and opens the browser on the dashboard, enabling it for that run even when the config opts out. CLI. Breakpoint debugging directly in files. Set a breakpoint on a line inside a loader and on a line inside the JSX below it — both bind. Compiled server modules are remapped to their sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. Debugging .pyxl files. Onekey debugging from VS Code. Pyxle Language Tools 0.3.0 contributes a debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate \"Debug Pyxle app (React browser)\" configuration debugs the React side in a standalone browser session. Plus a \"Pyxle: Open Studio\" command. Debugging .pyxl files. for attachstyle debugging. Hosts a debugpy server bound to so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes (ports, debugpy endpoint) for editor tooling and removes it on shutdown. Debugging .pyxl files. Dev tracebacks now point at sources. A loader/action error names your file and line instead of the compiled module under . Debugging. Breaking: is now a reserved URL namespace. The dev server's Vite asset proxy never forwards paths under it, so an app route under no longer resolves in (it still serves in production, where the namespace is unused). Move any such route before upgrading. Pyxle Studio. Fixed on Windows: is built with the platform delimiter. A project that already set got a joined value, which Node cannot parse on Windows, so neither entry resolved. Fixed on Windows: rebuild notifications report POSIX paths. The dev server's rebuild event carried host separators, so Studio and the error overlay showed . 0.7.5 now persists modulelevel state across requests, like . A / module is imported once and reused between rebuilds, so a modulelevel counter or inmemory cache no longer resets on every refresh in dev. Saving a file still reimports it (resetting globals and applying your edits). State stays perprocess — use a database or cache for anything shared or durable (Loaders should be stateless). now requires an explicit target. A bare used to silently scaffold into the current directory; it now errors, pointing to (new directory) or (current directory). 0.7.4 Fix: no longer hotreloads in an endless loop on Linux. After a save, the rebuild's own file reads surfaced through as events the watcher mistook for edits, retriggering the rebuild forever (macOS doesn't report reads, so it was Linuxonly). The watcher now reacts only to genuine change events, not readonly opens. 0.7.3 Docs: an 's awaited result is the flat — read fields directly (), never (a successful result has no ; is a separate hook property). Clarified across the Server Actions guide, the client API reference, and the scaffold . 0.7.2 Fix: scaffolds an installable again. The template's pin conflicted with the framework's after 0.7.1's security bump; both now use . Config: a boolean is now rejected instead of binding port 1. being an subclass slipped past the validator; it now raises a clear . 0.7.1 Security: require Starlette ≥ 1.3.1, fixing a header auth bypass (PYSEC2026161), formparsing DoS (PYSEC2026249, 1943), and a Windows SSRF (CVE202648818). Pyxle's own API is unchanged; a new CI job guards dependencies. refuses to start in production without — previously only a warning, leaving CSRF tokens and signed cookies forgeable. Security, Deployment. / check the Node.js version up front — a clear \"Node.js 20.19+ required\" message instead of an opaque Vite crash. Installation → Troubleshooting. A real testing story: helpers and a Testing guide. / compile a page and hand back its loader/module for unit tests. New Debugging guide and Deployment fixes — Node 22 in the sample Dockerfile, the real metrics path (), a migrations section, and a bluegreen CSRF gotcha. Security docs now match what Pyxle sends — it already sets //, so the guide covers only CSP and HSTS; a SECURITY.md is published for every repo. A fresh project now ships a human alongside the AIoriented . The comparison guide names current gaps — TSX authoring, a firstclass test client, automatic image/font optimization, i18n — with how to bridge each today. 0.7.0 Fix: renders even when an ancestor layout has a loader. Boundary renders now run ancestor layout loaders like a normal page instead of silently falling back to the builtin error document. Prerelease fixes. reaches the worker again, to tears down the whole child tree, a failed rebuild broadcasts to the overlay, and reverting to lastgood content triggers the recovery rebuild. Fix: CommonJS React libraries no longer crash SSR. The SSR bundler resolves dependencies ESMfirst (like Vite), so packages without an map (e.g. ) link cleanly; a genuinely CJSonly package now fails with an actionable error. Thirdparty packages. Docs: the road to a fullytyped Pyxle — where the type story is heading (TSX authoring, Python types across the boundary), grounded in what works today. Breaking: Node.js 20.19+ is now required (Vite 7's floor; Node 18 is EOL). Installation. Modernized scaffold — React 19, Vite 7, and an interactive . Arrowkey prompts for Tailwind, shadcn/ui, and the import alias, with /explicit flags for noninteractive use. Quick Start. Tailwind is now optin — Tailwind v4 wired into Vite when chosen. No config files or standalone watcher; decline it and plain CSS / CSS Modules work out of the box. Styling. shadcn/ui support — choose it at and works with no ; the alias resolves in the client build and SSR. Thirdparty packages. Fix: streaming SSR no longer serializes across requests. An SSR worker now renders many requests concurrently (isolated perrequest with ), and autosizes its worker pool. Streaming. renders the framework pin from the running version instead of a stale that downgraded fresh projects. fails fast when TypeScript isn't installed, with an actionable message instead of npm's placeholder . TypeScript. Scaffolded corrected — (like ///…) is compilerinjected, not imported. works out of the box — is now a default dependency, so JSX checking passes on a fresh scaffold with no extra step. Fix: the CSRF cookie no longer collides between apps on one host. The default name is namespaced by bind port () and injected into the page shell. Security → CSRF. Fix: multipart forms (file uploads) now pass CSRF with a field. The middleware streamparses just far enough to read the token (capped at 1 MiB) and replays the body untouched. Security → Form bodies and uploads. output is clean by default, for the firehose — a curated startup summary and oneline rebuild notices instead of Vite's raw stdout. CLI. Serverside logs stream to the browser console in , prefixed ; devonly and bounded. CLI. changes are picked up on refresh instead of triggering a rebuild (matching Next.js) — assets serve live from disk, and a newly added or removed file refreshes the static index. Architecture → the watcher. Watch extra directories with , ignore paths with . A shared module outside can now trigger hot reload; is additive to the builtin ignores. Configuration → Development. Documentation Fixed the flagship WebSockets example — it derived the socket path from during SSR and 500'd; it ",
+      "searchText": "Changelog Release notes for Pyxle. While we're in beta (), minor versions may include breaking changes — those are called out explicitly. To upgrade, run . 0.8.0 Pyxle Studio — a dashboard built into . Served at : every route with its loader, actions, cache posture, and boundaries; an interactive tester (loaders run inprocess, actions go through their real endpoint — CSRF, validation, and auth hooks included); a live request feed; latency metrics; the effective config (secrets redacted); and inbrowser . Devonly by construction, with a header allowlist. Pyxle Studio. New command. Runs the dev server and opens the browser on the dashboard, enabling it for that run even when the config opts out. CLI. Breakpoint debugging directly in files. Set a breakpoint on a line inside a loader and on a line inside the JSX below it — both bind. Compiled server modules are remapped to their sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. Debugging. Onekey debugging from VS Code. Pyxle Language Tools 0.3.0 contributes a debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate \"Debug Pyxle app (React browser)\" configuration debugs the React side in a standalone browser session. Plus a \"Pyxle: Open Studio\" command. Install it with . Debugging. for attachstyle debugging. Hosts a debugpy server bound to so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes (ports, debugpy endpoint) for editor tooling and removes it on shutdown. Debugging. Dev tracebacks now point at sources. A loader/action error names your file and line instead of the compiled module under . Debugging. Breaking: is now a reserved URL namespace. The dev server's Vite asset proxy never forwards paths under it, so an app route under no longer resolves in (it still serves in production, where the namespace is unused). Move any such route before upgrading. Pyxle Studio. Fixed on Windows: is built with the platform delimiter. A project that already set got a joined value, which Node cannot parse on Windows, so neither entry resolved. Fixed on Windows: rebuild notifications report POSIX paths. The dev server's rebuild event carried host separators, so Studio and the error overlay showed . 0.7.5 now persists modulelevel state across requests, like . A / module is imported once and reused between rebuilds, so a modulelevel counter or inmemory cache no longer resets on every refresh in dev. Saving a file still reimports it (resetting globals and applying your edits). State stays perprocess — use a database or cache for anything shared or durable (Loaders should be stateless). now requires an explicit target. A bare used to silently scaffold into the current directory; it now errors, pointing to (new directory) or (current directory). 0.7.4 Fix: no longer hotreloads in an endless loop on Linux. After a save, the rebuild's own file reads surfaced through as events the watcher mistook for edits, retriggering the rebuild forever (macOS doesn't report reads, so it was Linuxonly). The watcher now reacts only to genuine change events, not readonly opens. 0.7.3 Docs: an 's awaited result is the flat — read fields directly (), never (a successful result has no ; is a separate hook property). Clarified across the Server Actions guide, the client API reference, and the scaffold . 0.7.2 Fix: scaffolds an installable again. The template's pin conflicted with the framework's after 0.7.1's security bump; both now use . Config: a boolean is now rejected instead of binding port 1. being an subclass slipped past the validator; it now raises a clear . 0.7.1 Security: require Starlette ≥ 1.3.1, fixing a header auth bypass (PYSEC2026161), formparsing DoS (PYSEC2026249, 1943), and a Windows SSRF (CVE202648818). Pyxle's own API is unchanged; a new CI job guards dependencies. refuses to start in production without — previously only a warning, leaving CSRF tokens and signed cookies forgeable. Security, Deployment. / check the Node.js version up front — a clear \"Node.js 20.19+ required\" message instead of an opaque Vite crash. Installation → Troubleshooting. A real testing story: helpers and a Testing guide. / compile a page and hand back its loader/module for unit tests. New Debugging guide and Deployment fixes — Node 22 in the sample Dockerfile, the real metrics path (), a migrations section, and a bluegreen CSRF gotcha. Security docs now match what Pyxle sends — it already sets //, so the guide covers only CSP and HSTS; a SECURITY.md is published for every repo. A fresh project now ships a human alongside the AIoriented . The comparison guide names current gaps — TSX authoring, a firstclass test client, automatic image/font optimization, i18n — with how to bridge each today. 0.7.0 Fix: renders even when an ancestor layout has a loader. Boundary renders now run ancestor layout loaders like a normal page instead of silently falling back to the builtin error document. Prerelease fixes. reaches the worker again, to tears down the whole child tree, a failed rebuild broadcasts to the overlay, and reverting to lastgood content triggers the recovery rebuild. Fix: CommonJS React libraries no longer crash SSR. The SSR bundler resolves dependencies ESMfirst (like Vite), so packages without an map (e.g. ) link cleanly; a genuinely CJSonly package now fails with an actionable error. Thirdparty packages. Docs: the road to a fullytyped Pyxle — where the type story is heading (TSX authoring, Python types across the boundary), grounded in what works today. Breaking: Node.js 20.19+ is now required (Vite 7's floor; Node 18 is EOL). Installation. Modernized scaffold — React 19, Vite 7, and an interactive . Arrowkey prompts for Tailwind, shadcn/ui, and the import alias, with /explicit flags for noninteractive use. Quick Start. Tailwind is now optin — Tailwind v4 wired into Vite when chosen. No config files or standalone watcher; decline it and plain CSS / CSS Modules work out of the box. Styling. shadcn/ui support — choose it at and works with no ; the alias resolves in the client build and SSR. Thirdparty packages. Fix: streaming SSR no longer serializes across requests. An SSR worker now renders many requests concurrently (isolated perrequest with ), and autosizes its worker pool. Streaming. renders the framework pin from the running version instead of a stale that downgraded fresh projects. fails fast when TypeScript isn't installed, with an actionable message instead of npm's placeholder . TypeScript. Scaffolded corrected — (like ///…) is compilerinjected, not imported. works out of the box — is now a default dependency, so JSX checking passes on a fresh scaffold with no extra step. Fix: the CSRF cookie no longer collides between apps on one host. The default name is namespaced by bind port () and injected into the page shell. Security → CSRF. Fix: multipart forms (file uploads) now pass CSRF with a field. The middleware streamparses just far enough to read the token (capped at 1 MiB) and replays the body untouched. Security → Form bodies and uploads. output is clean by default, for the firehose — a curated startup summary and oneline rebuild notices instead of Vite's raw stdout. CLI. Serverside logs stream to the browser console in , prefixed ; devonly and bounded. CLI. changes are picked up on refresh instead of triggering a rebuild (matching Next.js) — assets serve live from disk, and a newly added or removed file refreshes the static index. Architecture → the watcher. Watch extra directories with , ignore paths with . A shared module outside can now trigger hot reload; is additive to the builtin ignores. Configuration → Development. Documentation Fixed the flagship WebSockets example — it derived the socket path from during SSR and 500'd; it now builds the pat",
       "headings": [
         "0.8.0",
         "0.7.5",
@@ -2553,10 +2535,6 @@
       "title": "Debugging",
       "category": "Guides"
     },
-    "guides/debugging-pyxl": {
-      "title": "Debugging .pyxl files",
-      "category": "Guides"
-    },
     "guides/studio": {
       "title": "Pyxle Studio",
       "category": "Guides"
diff --git a/public/docs-data/reference/cli.json b/public/docs-data/reference/cli.json
index ae7e258..35f21cd 100644
--- a/public/docs-data/reference/cli.json
+++ b/public/docs-data/reference/cli.json
@@ -1 +1 @@
-{"title":"CLI Reference","description":"The `pyxle` CLI manages Pyxle projects from scaffolding to production.","html":"<p>The <code>pyxle</code> CLI manages Pyxle projects from scaffolding to production.</p>\n<h2 id=\"global-options\">Global options</h2><table>\n<thead>\n<tr>\n<th>Flag</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--version</code></td>\n<td>Show Pyxle version and exit</td>\n</tr>\n<tr>\n<td><code>--log-format [console|json]</code></td>\n<td>Output format (default: <code>console</code>)</td>\n</tr>\n<tr>\n<td><code>--verbose</code> / <code>-v</code></td>\n<td>Show debug-level output</td>\n</tr>\n<tr>\n<td><code>--quiet</code> / <code>-q</code></td>\n<td>Suppress informational output; show only warnings and errors</td>\n</tr>\n<tr>\n<td><code>--install-completion</code></td>\n<td>Install shell completion for the current shell</td>\n</tr>\n<tr>\n<td><code>--show-completion</code></td>\n<td>Print shell completion (to copy or customize)</td>\n</tr>\n</tbody></table>\n<h2 id=\"pyxle-init\"><code>pyxle init</code></h2><p>Create a new Pyxle project.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle init &lt;name&gt; [options]</code></pre></div><p><code>pyxle init</code> is <strong>interactive</strong>: when stdin is a terminal and no flag pins the\nchoice, it walks you through arrow-key selections — Tailwind CSS, shadcn/ui\n(only if Tailwind is enabled), and whether to customize the default import\nalias (<code>@/*</code>; the value input appears only if you say yes). When stdin is\n<strong>not</strong> a terminal (CI, pipes), it never prompts — it uses the flags and\ndefaults below.</p>\n<table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>name</code></td>\n<td><em>(required)</em></td>\n<td>Project directory to create. A name like <code>my-app</code> creates a new directory; <code>.</code> scaffolds into the current directory (deriving the name from it). Running <code>pyxle init</code> with no argument is an error.</td>\n</tr>\n<tr>\n<td><code>--force</code> / <code>-f</code></td>\n<td><code>false</code></td>\n<td>Overwrite an existing directory (or scaffold into a non-empty current directory).</td>\n</tr>\n<tr>\n<td><code>--template</code> / <code>-t</code></td>\n<td><code>default</code></td>\n<td>Project template. Only <code>&quot;default&quot;</code> is supported today (other values error).</td>\n</tr>\n<tr>\n<td><code>--tailwind</code> / <code>--no-tailwind</code></td>\n<td>prompt → off</td>\n<td>Set up Tailwind CSS v4 (wired into Vite).</td>\n</tr>\n<tr>\n<td><code>--shadcn</code> / <code>--no-shadcn</code></td>\n<td>prompt → off</td>\n<td>Set up shadcn/ui (implies <code>--tailwind</code>).</td>\n</tr>\n<tr>\n<td><code>--import-alias</code></td>\n<td><code>@/*</code></td>\n<td>Import alias for project modules (e.g. <code>~/*</code>).</td>\n</tr>\n<tr>\n<td><code>--yes</code> / <code>-y</code></td>\n<td><code>false</code></td>\n<td>Accept all defaults without prompting (no Tailwind, no shadcn, default alias).</td>\n</tr>\n<tr>\n<td><code>--install</code> / <code>--no-install</code></td>\n<td><code>false</code></td>\n<td>Run <code>pip install</code> and <code>npm install</code> after scaffolding.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle init my-app                          # interactive prompts\npyxle init my-app --yes                     # accept defaults (no Tailwind)\npyxle init my-app --tailwind --no-shadcn    # Tailwind only, no prompts\npyxle init my-app --shadcn                  # shadcn/ui (implies Tailwind)\npyxle init .                                # scaffold into an empty current dir\npyxle init my-app --force --install</code></pre></div><h2 id=\"pyxle-install\"><code>pyxle install</code></h2><p>Install Python and Node.js dependencies.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle install [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--python</code> / <code>--no-python</code></td>\n<td><code>true</code></td>\n<td>Install Python deps via <code>pip</code></td>\n</tr>\n<tr>\n<td><code>--node</code> / <code>--no-node</code></td>\n<td><code>true</code></td>\n<td>Install Node deps via <code>npm</code></td>\n</tr>\n<tr>\n<td><code>--break-system-packages</code></td>\n<td><code>false</code></td>\n<td>Pass <code>--break-system-packages</code> to <code>pip</code>, for externally-managed (PEP 668) environments without a virtualenv. Use with care.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle install\npyxle install --no-python    # Node only\npyxle install ./my-app\npyxle install --break-system-packages   # PEP 668 system Python, no venv</code></pre></div><p>Outside a virtualenv, <code>pyxle install</code> warns about PEP 668 (&quot;externally-managed-environment&quot;) and recommends creating a venv first; pass <code>--break-system-packages</code> to install anyway.</p>\n<h2 id=\"pyxle-dev\"><code>pyxle dev</code></h2><p>Start the development server with hot reload.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle dev [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Starlette server bind address</td>\n</tr>\n<tr>\n<td><code>--port</code></td>\n<td><code>8000</code></td>\n<td>Starlette server port</td>\n</tr>\n<tr>\n<td><code>--vite-host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Vite dev server bind address</td>\n</tr>\n<tr>\n<td><code>--vite-port</code></td>\n<td><code>5173</code></td>\n<td>Vite dev server port</td>\n</tr>\n<tr>\n<td><code>--debug</code> / <code>--no-debug</code></td>\n<td><code>true</code></td>\n<td>Enable debug mode</td>\n</tr>\n<tr>\n<td><code>--ssr-workers</code></td>\n<td><code>1</code></td>\n<td>Number of persistent SSR worker processes (<code>0</code> = per-request subprocess mode)</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--print-config</code> / <code>--no-print-config</code></td>\n<td><code>false</code></td>\n<td>Print merged configuration before starting</td>\n</tr>\n<tr>\n<td><code>--tailwind</code> / <code>--no-tailwind</code></td>\n<td><code>true</code></td>\n<td>Auto-start the <strong>legacy</strong> standalone Tailwind v3 CLI watcher when a hand-written <code>tailwind.config.*</code> is present. Tailwind <strong>v4</strong> projects (the scaffold default when you opt into Tailwind) run through the <code>@tailwindcss/vite</code> plugin and ignore this flag.</td>\n</tr>\n<tr>\n<td><code>--dashboard</code> / <code>--no-dashboard</code></td>\n<td><code>false</code></td>\n<td>Periodically print a live <a href=\"/docs/guides/observability#dev-dashboard\">observability</a> panel (request/SSR metrics) to the terminal</td>\n</tr>\n<tr>\n<td><code>--inspect</code> / <code>--no-inspect</code></td>\n<td><code>false</code></td>\n<td>Host a debugpy debug server (bound to <code>127.0.0.1</code>) so VS Code or any DAP client can set breakpoints directly in <code>.pyxl</code> files — see <a href=\"/docs/guides/debugging-pyxl\">Debugging .pyxl files</a>. debugpy ships with the framework.</td>\n</tr>\n<tr>\n<td><code>--inspect-port</code></td>\n<td><code>5678</code></td>\n<td>Port for the debug server (with <code>--inspect</code>). Falls back to an ephemeral port when busy; the actual endpoint is recorded in <code>.pyxle-build/dev-server.json</code>.</td>\n</tr>\n<tr>\n<td><code>--inspect-wait</code> / <code>--no-inspect-wait</code></td>\n<td><code>false</code></td>\n<td>With <code>--inspect</code>: wait for a debugger to attach before starting the server — for breakpoints in code that runs during boot.</td>\n</tr>\n<tr>\n<td><code>--verbose</code> / <code>-v</code></td>\n<td><code>false</code></td>\n<td>Restore full output: the raw Vite log firehose, debug-level internals, and <code>DEBUG</code> server logs in the browser console. Equivalent to the global <code>pyxle -v dev</code>.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle dev\npyxle dev --host 0.0.0.0 --port 3000\npyxle dev --no-tailwind --ssr-workers 4\npyxle dev ./my-app --print-config\npyxle dev --verbose             # troubleshoot: full Vite + debug output</code></pre></div><p><strong>What it does:</strong></p>\n<ol>\n<li>Loads configuration from <code>pyxle.config.json</code> + environment variables + CLI flags</li>\n<li>Compiles <code>.pyxl</code> files into Python and JSX modules</li>\n<li>Starts the Vite dev server for React hot reload (Tailwind v4 compiles here via the <code>@tailwindcss/vite</code> plugin)</li>\n<li>Starts the legacy Tailwind v3 watcher only if a hand-written <code>tailwind.config.*</code> is detected</li>\n<li>Starts the Starlette ASGI server</li>\n<li>Watches for file changes and recompiles automatically</li>\n</ol>\n<p><strong>Console output.</strong> By default <code>pyxle dev</code> prints a clean, curated console — a\nstartup summary (the local URL, the Vite URL, the route count, and the total\n&quot;ready in X ms&quot;), a concise one-line notice per incremental rebuild\n(<code>Rebuilt … in X ms</code>), and any warnings or errors. The raw line-by-line Vite\nfirehose and debug-level internals are hidden. Pass <code>--verbose</code> (or <code>-v</code>, or the\nglobal <code>pyxle -v dev</code>) to restore the full output when troubleshooting. Genuine\nsignal — errors, warnings, the URLs, and rebuild success/failure — is always\nshown, at every verbosity.</p>\n<p><strong>Server logs in the browser console (dev only).</strong> While <code>pyxle dev</code> is running,\nyour server-side <code>logging</code> output (from loaders, actions, and your own modules)\nis forwarded to the browser devtools console, prefixed <code>[pyxle:server]</code> and\nmapped to the matching <code>console</code> method (<code>info</code> → <code>console.info</code>, <code>warning</code> →\n<code>console.warn</code>, <code>error</code> → <code>console.error</code>). This lets you follow server logs\nwithout leaving the browser. By default only <code>INFO</code> and above from your own\nloggers are forwarded; <code>--verbose</code> additionally forwards <code>DEBUG</code> records and the\nframework&#39;s own internal loggers. This is strictly a development feature — it\nnever runs under <code>pyxle serve</code> and never appears in the production bundle.</p>\n<h2 id=\"pyxle-studio\"><code>pyxle studio</code></h2><p>Run the dev server and open the <a href=\"/docs/guides/studio\">Pyxle Studio</a> dashboard.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle studio [directory] [options]</code></pre></div><p><code>pyxle studio</code> runs the same development server as <code>pyxle dev</code> — Studio is part of it, served at <code>/__pyxle/studio</code> — and opens your browser on the dashboard once the server is ready. Debug mode is forced on (Studio is dev-only), and the dashboard is enabled for this run even when the config sets <code>&quot;studio&quot;: false</code>.</p>\n<table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Starlette server bind address</td>\n</tr>\n<tr>\n<td><code>--port</code></td>\n<td><code>8000</code></td>\n<td>Starlette server port</td>\n</tr>\n<tr>\n<td><code>--vite-host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Vite dev server bind address</td>\n</tr>\n<tr>\n<td><code>--vite-port</code></td>\n<td><code>5173</code></td>\n<td>Vite dev server port</td>\n</tr>\n<tr>\n<td><code>--ssr-workers</code></td>\n<td><code>1</code></td>\n<td>Number of persistent SSR worker processes (<code>0</code> = per-request subprocess mode)</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--tailwind</code> / <code>--no-tailwind</code></td>\n<td><code>true</code></td>\n<td>Auto-start the legacy Tailwind v3 watcher when a hand-written <code>tailwind.config.*</code> is present (same behavior as <code>pyxle dev</code>)</td>\n</tr>\n<tr>\n<td><code>--open</code> / <code>--no-open</code></td>\n<td><code>true</code></td>\n<td>Open the Studio dashboard in the system browser once the server is ready</td>\n</tr>\n<tr>\n<td><code>--inspect</code> / <code>--no-inspect</code></td>\n<td><code>false</code></td>\n<td>Host a debugpy debug server for <code>.pyxl</code> breakpoint debugging — see <a href=\"/docs/guides/debugging-pyxl\">Debugging .pyxl files</a></td>\n</tr>\n<tr>\n<td><code>--inspect-port</code></td>\n<td><code>5678</code></td>\n<td>Port for the debug server (with <code>--inspect</code>; falls back to an ephemeral port when busy)</td>\n</tr>\n<tr>\n<td><code>--verbose</code> / <code>-v</code></td>\n<td><code>false</code></td>\n<td>Restore full output (raw Vite logs, debug internals). Equivalent to <code>pyxle -v studio</code>.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle studio                     # dev server + dashboard in the browser\npyxle studio --no-open           # dashboard enabled, but don't launch a browser\npyxle studio --inspect           # dashboard + debugger in one command\npyxle studio ./my-app --port 3000</code></pre></div><h2 id=\"pyxle-build\"><code>pyxle build</code></h2><p>Build production-ready assets.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle build [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--out-dir</code></td>\n<td><code>dist/</code></td>\n<td>Output directory for build artifacts</td>\n</tr>\n<tr>\n<td><code>--incremental</code> / <code>--no-incremental</code></td>\n<td><code>false</code></td>\n<td>Reuse cached artifacts</td>\n</tr>\n<tr>\n<td><code>--static</code> / <code>--no-static</code></td>\n<td><code>false</code></td>\n<td>Pre-render loader-less, non-dynamic pages to HTML at build time (SSG) — see <a href=\"/docs/guides/caching#static-pre-rendering-pyxle-build-static\">Caching</a></td>\n</tr>\n<tr>\n<td><code>--analyze</code> / <code>--no-analyze</code></td>\n<td><code>false</code></td>\n<td>Print a JS/CSS bundle-size report (raw + gzip, largest first) after the build — see <a href=\"/docs/guides/build-optimization#inspecting-the-bundle-pyxle-build-analyze\">Build Optimization</a></td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle build\npyxle build --analyze\npyxle build --out-dir ./output --incremental\npyxle build --static</code></pre></div><h2 id=\"pyxle-serve\"><code>pyxle serve</code></h2><p>Serve a production build (without Vite).</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle serve [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Bind address</td>\n</tr>\n<tr>\n<td><code>--port</code></td>\n<td><code>8000</code></td>\n<td>Port number</td>\n</tr>\n<tr>\n<td><code>--dist-dir</code></td>\n<td><code>dist/</code></td>\n<td>Directory with production artifacts</td>\n</tr>\n<tr>\n<td><code>--skip-build</code> / <code>--no-skip-build</code></td>\n<td><code>false</code></td>\n<td>Skip running build first</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--serve-static</code> / <code>--no-serve-static</code></td>\n<td><code>true</code></td>\n<td>Serve static assets directly from Pyxle</td>\n</tr>\n<tr>\n<td><code>--ssr-workers</code></td>\n<td><code>1</code></td>\n<td>Number of persistent SSR worker processes, per server worker (<code>0</code> = auto-size to CPU cores, capped at 4)</td>\n</tr>\n<tr>\n<td><code>--workers</code> / <code>-w</code></td>\n<td><code>1</code></td>\n<td>Number of server worker processes (one per CPU core); <code>&gt;1</code> enables multi-core serving; <code>0</code> auto-detects from CPU cores</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle serve\npyxle serve --host 0.0.0.0 --port 8000 --skip-build\npyxle serve --ssr-workers 4\npyxle serve --workers $(nproc)   # one server process per CPU core</code></pre></div><p>With <code>--workers N</code> (N &gt; 1), Pyxle serves the build across <code>N</code> uvicorn worker\nprocesses. Each is an independent server with its own SSR pool, so <code>--ssr-workers</code>\napplies per worker (total render processes = <code>workers × ssr-workers</code>). See the\n<a href=\"/docs/guides/deployment#multi-core-worker-processes\">deployment guide</a> for\nsizing guidance.</p>\n<h2 id=\"pyxle-check\"><code>pyxle check</code></h2><p>Validate <code>.pyxl</code> files, configuration, and dependencies without starting the server. Each <code>.pyxl</code> file is checked at three levels:</p>\n<ul>\n<li><strong>Python syntax</strong> (via <code>ast</code>) and Pyxle structural rules (loader/action shape, <code>HEAD</code>, …).</li>\n<li><strong>Python semantics</strong> (via pyflakes): undefined names — e.g. a symbol you <code>raise</code> but never imported — unused imports, redefinitions. Compiler-injected runtime names (<code>server</code>, <code>action</code>, <code>LoaderError</code>, <code>ActionError</code>, …) are recognized, so the idiomatic patterns never read as undefined.</li>\n<li><strong>JSX syntax</strong> (via Babel): unclosed tags/expressions, mismatched braces, TypeScript in a client block, and <strong>duplicate <code>export default</code></strong> (which Babel accepts but the build rejects).</li>\n</ul>\n<p>As of 0.7.0 the JSX level works out of the box — <code>pyxle-langkit</code>, which provides the Babel-based checker, ships with the framework. On earlier versions it required the <code>[langkit]</code> extra (<code>pip install &#39;pyxle-framework[langkit]&#39;</code>); without it, the JSX check reported itself unavailable.</p>\n<blockquote>\n<p><strong>What a green check proves — and what it doesn&#39;t.</strong> <code>pyxle check</code> is a\nstatic gate: it validates <code>.pyxl</code> syntax, Python semantics, and JSX syntax.\nIt does <strong>not</strong> render your pages, so a mistake that only exists at runtime —\na component reading <code>data.posts</code> when the loader returns <code>{&quot;items&quot;: ...}</code>, a\nloader whose query fails against the real database — surfaces when the page\nrenders, not here. Treat a clean check as &quot;this compiles&quot;; loading the page\nunder <code>pyxle dev</code> (or a test that requests it) remains the runtime proof.</p>\n</blockquote>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle check [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n</tbody></table>\n<p><strong>Example output:</strong></p>\n<div class=\"code-block\" data-lang=\"\"><pre><code>ℹ️  Checked 12 .pyxl file(s) in my-app/\n✅ All checks passed</code></pre></div><p>Errors are reported per file as <code>[section] line N: message</code>, with the file path on the next line (every file is checked, so one broken file never aborts the scan):</p>\n<div class=\"code-block\" data-lang=\"\"><pre><code>ℹ️  Checked 12 .pyxl file(s) in my-app/\n  error: [python] line 15: @server function must be async\n    --&gt; pages/index.pyxl\n  error: [jsx] line 8:10: Unterminated JSX contents\n    --&gt; pages/settings.pyxl\n❌ Check failed with 2 error(s)</code></pre></div><p>Exit code is <code>0</code> when clean, <code>1</code> when any error is found.</p>\n<h2 id=\"pyxle-typecheck\"><code>pyxle typecheck</code></h2><p>Run TypeScript type-checking on compiled JSX output.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle typecheck [directory] [options]</code></pre></div><p>Requires <code>typescript</code> in your <code>devDependencies</code>. Runs <code>tsc --noEmit</code> against the compiled JSX in <code>.pyxle-build/client/</code>.</p>\n<table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n</tbody></table>\n<h2 id=\"pyxle-routes\"><code>pyxle routes</code></h2><p>Display the route table for your project.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle routes [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--json</code></td>\n<td><code>false</code></td>\n<td>Output as JSON</td>\n</tr>\n</tbody></table>\n<p><strong>Example output:</strong></p>\n<div class=\"code-block\" data-lang=\"\"><pre><code>ℹ️  Routes for my-app/\n\n  Pages:\n  ▶️  /  — pages/index.pyxl  [loader=load_home]\n  ▶️  /about  — pages/about.pyxl\n  ▶️  /blog/{slug}  — pages/blog/[slug].pyxl  [loader=load_post]\n\n  API Routes:\n  ▶️  /api/pulse  — pages/api/pulse.py</code></pre></div><p>Use <code>--json</code> for machine-readable output.</p>\n<h2 id=\"pyxle-openapi\"><code>pyxle openapi</code></h2><p>Generate an <a href=\"https://spec.openapis.org/oas/v3.1.0\" target=\"_blank\" rel=\"noreferrer\">OpenAPI 3.1</a> document from your <code>@action</code> request models. For every action that declares a <a href=\"/docs/core-concepts/server-actions#validating-request-bodies-with-pydantic\">Pydantic body parameter</a>, Pyxle emits a <code>POST</code> operation with the model&#39;s JSON Schema as the request body and a structured <code>422</code> validation response; actions without a model get a permissive object body.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle openapi [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--out</code> / <code>-o</code></td>\n<td>--</td>\n<td>Write the schema to this file (default: stdout)</td>\n</tr>\n<tr>\n<td><code>--title</code></td>\n<td><code>Pyxle API</code></td>\n<td>OpenAPI <code>info.title</code></td>\n</tr>\n<tr>\n<td><code>--api-version</code></td>\n<td><code>0.1.0</code></td>\n<td>OpenAPI <code>info.version</code></td>\n</tr>\n</tbody></table>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\"># Print to stdout\npyxle openapi\n\n# Write a file with custom metadata\npyxle openapi --out openapi.json --title \"Acme API\" --api-version 2.0.0</code></pre></div><p>The schema is derived from runtime introspection of the compiled action modules, so it always matches what the dispatcher actually validates. Requires the <code>[pydantic]</code> extra (<code>pip install &quot;pyxle-framework[pydantic]&quot;</code>); the command exits with an error if Pydantic isn&#39;t installed or a page module can&#39;t be imported.</p>\n","toc":[{"depth":2,"text":"Global options","slug":"global-options"},{"depth":2,"text":"pyxle init","slug":"pyxle-init"},{"depth":2,"text":"pyxle install","slug":"pyxle-install"},{"depth":2,"text":"pyxle dev","slug":"pyxle-dev"},{"depth":2,"text":"pyxle studio","slug":"pyxle-studio"},{"depth":2,"text":"pyxle build","slug":"pyxle-build"},{"depth":2,"text":"pyxle serve","slug":"pyxle-serve"},{"depth":2,"text":"pyxle check","slug":"pyxle-check"},{"depth":2,"text":"pyxle typecheck","slug":"pyxle-typecheck"},{"depth":2,"text":"pyxle routes","slug":"pyxle-routes"},{"depth":2,"text":"pyxle openapi","slug":"pyxle-openapi"}],"path":"reference/cli","markdown":"# CLI Reference\n\nThe `pyxle` CLI manages Pyxle projects from scaffolding to production.\n\n## Global options\n\n| Flag | Description |\n|------|-------------|\n| `--version` | Show Pyxle version and exit |\n| `--log-format [console\\|json]` | Output format (default: `console`) |\n| `--verbose` / `-v` | Show debug-level output |\n| `--quiet` / `-q` | Suppress informational output; show only warnings and errors |\n| `--install-completion` | Install shell completion for the current shell |\n| `--show-completion` | Print shell completion (to copy or customize) |\n\n## `pyxle init`\n\nCreate a new Pyxle project.\n\n```bash\npyxle init <name> [options]\n```\n\n`pyxle init` is **interactive**: when stdin is a terminal and no flag pins the\nchoice, it walks you through arrow-key selections — Tailwind CSS, shadcn/ui\n(only if Tailwind is enabled), and whether to customize the default import\nalias (`@/*`; the value input appears only if you say yes). When stdin is\n**not** a terminal (CI, pipes), it never prompts — it uses the flags and\ndefaults below.\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `name` | *(required)* | Project directory to create. A name like `my-app` creates a new directory; `.` scaffolds into the current directory (deriving the name from it). Running `pyxle init` with no argument is an error. |\n| `--force` / `-f` | `false` | Overwrite an existing directory (or scaffold into a non-empty current directory). |\n| `--template` / `-t` | `default` | Project template. Only `\"default\"` is supported today (other values error). |\n| `--tailwind` / `--no-tailwind` | prompt → off | Set up Tailwind CSS v4 (wired into Vite). |\n| `--shadcn` / `--no-shadcn` | prompt → off | Set up shadcn/ui (implies `--tailwind`). |\n| `--import-alias` | `@/*` | Import alias for project modules (e.g. `~/*`). |\n| `--yes` / `-y` | `false` | Accept all defaults without prompting (no Tailwind, no shadcn, default alias). |\n| `--install` / `--no-install` | `false` | Run `pip install` and `npm install` after scaffolding. |\n\n**Examples:**\n\n```bash\npyxle init my-app                          # interactive prompts\npyxle init my-app --yes                     # accept defaults (no Tailwind)\npyxle init my-app --tailwind --no-shadcn    # Tailwind only, no prompts\npyxle init my-app --shadcn                  # shadcn/ui (implies Tailwind)\npyxle init .                                # scaffold into an empty current dir\npyxle init my-app --force --install\n```\n\n## `pyxle install`\n\nInstall Python and Node.js dependencies.\n\n```bash\npyxle install [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--python` / `--no-python` | `true` | Install Python deps via `pip` |\n| `--node` / `--no-node` | `true` | Install Node deps via `npm` |\n| `--break-system-packages` | `false` | Pass `--break-system-packages` to `pip`, for externally-managed (PEP 668) environments without a virtualenv. Use with care. |\n\n**Examples:**\n\n```bash\npyxle install\npyxle install --no-python    # Node only\npyxle install ./my-app\npyxle install --break-system-packages   # PEP 668 system Python, no venv\n```\n\nOutside a virtualenv, `pyxle install` warns about PEP 668 (\"externally-managed-environment\") and recommends creating a venv first; pass `--break-system-packages` to install anyway.\n\n## `pyxle dev`\n\nStart the development server with hot reload.\n\n```bash\npyxle dev [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--host` | `127.0.0.1` | Starlette server bind address |\n| `--port` | `8000` | Starlette server port |\n| `--vite-host` | `127.0.0.1` | Vite dev server bind address |\n| `--vite-port` | `5173` | Vite dev server port |\n| `--debug` / `--no-debug` | `true` | Enable debug mode |\n| `--ssr-workers` | `1` | Number of persistent SSR worker processes (`0` = per-request subprocess mode) |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--print-config` / `--no-print-config` | `false` | Print merged configuration before starting |\n| `--tailwind` / `--no-tailwind` | `true` | Auto-start the **legacy** standalone Tailwind v3 CLI watcher when a hand-written `tailwind.config.*` is present. Tailwind **v4** projects (the scaffold default when you opt into Tailwind) run through the `@tailwindcss/vite` plugin and ignore this flag. |\n| `--dashboard` / `--no-dashboard` | `false` | Periodically print a live [observability](https://pyxle.dev/docs/guides/observability.md#dev-dashboard) panel (request/SSR metrics) to the terminal |\n| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server (bound to `127.0.0.1`) so VS Code or any DAP client can set breakpoints directly in `.pyxl` files — see [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md). debugpy ships with the framework. |\n| `--inspect-port` | `5678` | Port for the debug server (with `--inspect`). Falls back to an ephemeral port when busy; the actual endpoint is recorded in `.pyxle-build/dev-server.json`. |\n| `--inspect-wait` / `--no-inspect-wait` | `false` | With `--inspect`: wait for a debugger to attach before starting the server — for breakpoints in code that runs during boot. |\n| `--verbose` / `-v` | `false` | Restore full output: the raw Vite log firehose, debug-level internals, and `DEBUG` server logs in the browser console. Equivalent to the global `pyxle -v dev`. |\n\n**Examples:**\n\n```bash\npyxle dev\npyxle dev --host 0.0.0.0 --port 3000\npyxle dev --no-tailwind --ssr-workers 4\npyxle dev ./my-app --print-config\npyxle dev --verbose             # troubleshoot: full Vite + debug output\n```\n\n**What it does:**\n\n1. Loads configuration from `pyxle.config.json` + environment variables + CLI flags\n2. Compiles `.pyxl` files into Python and JSX modules\n3. Starts the Vite dev server for React hot reload (Tailwind v4 compiles here via the `@tailwindcss/vite` plugin)\n4. Starts the legacy Tailwind v3 watcher only if a hand-written `tailwind.config.*` is detected\n5. Starts the Starlette ASGI server\n6. Watches for file changes and recompiles automatically\n\n**Console output.** By default `pyxle dev` prints a clean, curated console — a\nstartup summary (the local URL, the Vite URL, the route count, and the total\n\"ready in X ms\"), a concise one-line notice per incremental rebuild\n(`Rebuilt … in X ms`), and any warnings or errors. The raw line-by-line Vite\nfirehose and debug-level internals are hidden. Pass `--verbose` (or `-v`, or the\nglobal `pyxle -v dev`) to restore the full output when troubleshooting. Genuine\nsignal — errors, warnings, the URLs, and rebuild success/failure — is always\nshown, at every verbosity.\n\n**Server logs in the browser console (dev only).** While `pyxle dev` is running,\nyour server-side `logging` output (from loaders, actions, and your own modules)\nis forwarded to the browser devtools console, prefixed `[pyxle:server]` and\nmapped to the matching `console` method (`info` → `console.info`, `warning` →\n`console.warn`, `error` → `console.error`). This lets you follow server logs\nwithout leaving the browser. By default only `INFO` and above from your own\nloggers are forwarded; `--verbose` additionally forwards `DEBUG` records and the\nframework's own internal loggers. This is strictly a development feature — it\nnever runs under `pyxle serve` and never appears in the production bundle.\n\n## `pyxle studio`\n\nRun the dev server and open the [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) dashboard.\n\n```bash\npyxle studio [directory] [options]\n```\n\n`pyxle studio` runs the same development server as `pyxle dev` — Studio is part of it, served at `/__pyxle/studio` — and opens your browser on the dashboard once the server is ready. Debug mode is forced on (Studio is dev-only), and the dashboard is enabled for this run even when the config sets `\"studio\": false`.\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--host` | `127.0.0.1` | Starlette server bind address |\n| `--port` | `8000` | Starlette server port |\n| `--vite-host` | `127.0.0.1` | Vite dev server bind address |\n| `--vite-port` | `5173` | Vite dev server port |\n| `--ssr-workers` | `1` | Number of persistent SSR worker processes (`0` = per-request subprocess mode) |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--tailwind` / `--no-tailwind` | `true` | Auto-start the legacy Tailwind v3 watcher when a hand-written `tailwind.config.*` is present (same behavior as `pyxle dev`) |\n| `--open` / `--no-open` | `true` | Open the Studio dashboard in the system browser once the server is ready |\n| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server for `.pyxl` breakpoint debugging — see [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md) |\n| `--inspect-port` | `5678` | Port for the debug server (with `--inspect`; falls back to an ephemeral port when busy) |\n| `--verbose` / `-v` | `false` | Restore full output (raw Vite logs, debug internals). Equivalent to `pyxle -v studio`. |\n\n**Examples:**\n\n```bash\npyxle studio                     # dev server + dashboard in the browser\npyxle studio --no-open           # dashboard enabled, but don't launch a browser\npyxle studio --inspect           # dashboard + debugger in one command\npyxle studio ./my-app --port 3000\n```\n\n## `pyxle build`\n\nBuild production-ready assets.\n\n```bash\npyxle build [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--out-dir` | `dist/` | Output directory for build artifacts |\n| `--incremental` / `--no-incremental` | `false` | Reuse cached artifacts |\n| `--static` / `--no-static` | `false` | Pre-render loader-less, non-dynamic pages to HTML at build time (SSG) — see [Caching](https://pyxle.dev/docs/guides/caching.md#static-pre-rendering-pyxle-build-static) |\n| `--analyze` / `--no-analyze` | `false` | Print a JS/CSS bundle-size report (raw + gzip, largest first) after the build — see [Build Optimization](https://pyxle.dev/docs/guides/build-optimization.md#inspecting-the-bundle-pyxle-build-analyze) |\n\n**Examples:**\n\n```bash\npyxle build\npyxle build --analyze\npyxle build --out-dir ./output --incremental\npyxle build --static\n```\n\n## `pyxle serve`\n\nServe a production build (without Vite).\n\n```bash\npyxle serve [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--host` | `127.0.0.1` | Bind address |\n| `--port` | `8000` | Port number |\n| `--dist-dir` | `dist/` | Directory with production artifacts |\n| `--skip-build` / `--no-skip-build` | `false` | Skip running build first |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--serve-static` / `--no-serve-static` | `true` | Serve static assets directly from Pyxle |\n| `--ssr-workers` | `1` | Number of persistent SSR worker processes, per server worker (`0` = auto-size to CPU cores, capped at 4) |\n| `--workers` / `-w` | `1` | Number of server worker processes (one per CPU core); `>1` enables multi-core serving; `0` auto-detects from CPU cores |\n\n**Examples:**\n\n```bash\npyxle serve\npyxle serve --host 0.0.0.0 --port 8000 --skip-build\npyxle serve --ssr-workers 4\npyxle serve --workers $(nproc)   # one server process per CPU core\n```\n\nWith `--workers N` (N > 1), Pyxle serves the build across `N` uvicorn worker\nprocesses. Each is an independent server with its own SSR pool, so `--ssr-workers`\napplies per worker (total render processes = `workers × ssr-workers`). See the\n[deployment guide](https://pyxle.dev/docs/guides/deployment.md#multi-core-worker-processes) for\nsizing guidance.\n\n## `pyxle check`\n\nValidate `.pyxl` files, configuration, and dependencies without starting the server. Each `.pyxl` file is checked at three levels:\n\n- **Python syntax** (via `ast`) and Pyxle structural rules (loader/action shape, `HEAD`, …).\n- **Python semantics** (via pyflakes): undefined names — e.g. a symbol you `raise` but never imported — unused imports, redefinitions. Compiler-injected runtime names (`server`, `action`, `LoaderError`, `ActionError`, …) are recognized, so the idiomatic patterns never read as undefined.\n- **JSX syntax** (via Babel): unclosed tags/expressions, mismatched braces, TypeScript in a client block, and **duplicate `export default`** (which Babel accepts but the build rejects).\n\nAs of 0.7.0 the JSX level works out of the box — `pyxle-langkit`, which provides the Babel-based checker, ships with the framework. On earlier versions it required the `[langkit]` extra (`pip install 'pyxle-framework[langkit]'`); without it, the JSX check reported itself unavailable.\n\n> **What a green check proves — and what it doesn't.** `pyxle check` is a\n> static gate: it validates `.pyxl` syntax, Python semantics, and JSX syntax.\n> It does **not** render your pages, so a mistake that only exists at runtime —\n> a component reading `data.posts` when the loader returns `{\"items\": ...}`, a\n> loader whose query fails against the real database — surfaces when the page\n> renders, not here. Treat a clean check as \"this compiles\"; loading the page\n> under `pyxle dev` (or a test that requests it) remains the runtime proof.\n\n```bash\npyxle check [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n\n**Example output:**\n\n```\nℹ️  Checked 12 .pyxl file(s) in my-app/\n✅ All checks passed\n```\n\nErrors are reported per file as `[section] line N: message`, with the file path on the next line (every file is checked, so one broken file never aborts the scan):\n\n```\nℹ️  Checked 12 .pyxl file(s) in my-app/\n  error: [python] line 15: @server function must be async\n    --> pages/index.pyxl\n  error: [jsx] line 8:10: Unterminated JSX contents\n    --> pages/settings.pyxl\n❌ Check failed with 2 error(s)\n```\n\nExit code is `0` when clean, `1` when any error is found.\n\n## `pyxle typecheck`\n\nRun TypeScript type-checking on compiled JSX output.\n\n```bash\npyxle typecheck [directory] [options]\n```\n\nRequires `typescript` in your `devDependencies`. Runs `tsc --noEmit` against the compiled JSX in `.pyxle-build/client/`.\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n\n## `pyxle routes`\n\nDisplay the route table for your project.\n\n```bash\npyxle routes [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--json` | `false` | Output as JSON |\n\n**Example output:**\n\n```\nℹ️  Routes for my-app/\n\n  Pages:\n  ▶️  /  — pages/index.pyxl  [loader=load_home]\n  ▶️  /about  — pages/about.pyxl\n  ▶️  /blog/{slug}  — pages/blog/[slug].pyxl  [loader=load_post]\n\n  API Routes:\n  ▶️  /api/pulse  — pages/api/pulse.py\n```\n\nUse `--json` for machine-readable output.\n\n## `pyxle openapi`\n\nGenerate an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) document from your `@action` request models. For every action that declares a [Pydantic body parameter](https://pyxle.dev/docs/core-concepts/server-actions.md#validating-request-bodies-with-pydantic), Pyxle emits a `POST` operation with the model's JSON Schema as the request body and a structured `422` validation response; actions without a model get a permissive object body.\n\n```bash\npyxle openapi [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--out` / `-o` | -- | Write the schema to this file (default: stdout) |\n| `--title` | `Pyxle API` | OpenAPI `info.title` |\n| `--api-version` | `0.1.0` | OpenAPI `info.version` |\n\n```bash\n# Print to stdout\npyxle openapi\n\n# Write a file with custom metadata\npyxle openapi --out openapi.json --title \"Acme API\" --api-version 2.0.0\n```\n\nThe schema is derived from runtime introspection of the compiled action modules, so it always matches what the dispatcher actually validates. Requires the `[pydantic]` extra (`pip install \"pyxle-framework[pydantic]\"`); the command exits with an error if Pydantic isn't installed or a page module can't be imported.\n","prev":{"title":"Migrating from .pyx to .pyxl","path":"guides/migration-pyx-to-pyxl"},"next":{"title":"Configuration Reference","path":"reference/configuration"}}
\ No newline at end of file
+{"title":"CLI Reference","description":"The `pyxle` CLI manages Pyxle projects from scaffolding to production.","html":"<p>The <code>pyxle</code> CLI manages Pyxle projects from scaffolding to production.</p>\n<h2 id=\"global-options\">Global options</h2><table>\n<thead>\n<tr>\n<th>Flag</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--version</code></td>\n<td>Show Pyxle version and exit</td>\n</tr>\n<tr>\n<td><code>--log-format [console|json]</code></td>\n<td>Output format (default: <code>console</code>)</td>\n</tr>\n<tr>\n<td><code>--verbose</code> / <code>-v</code></td>\n<td>Show debug-level output</td>\n</tr>\n<tr>\n<td><code>--quiet</code> / <code>-q</code></td>\n<td>Suppress informational output; show only warnings and errors</td>\n</tr>\n<tr>\n<td><code>--install-completion</code></td>\n<td>Install shell completion for the current shell</td>\n</tr>\n<tr>\n<td><code>--show-completion</code></td>\n<td>Print shell completion (to copy or customize)</td>\n</tr>\n</tbody></table>\n<h2 id=\"pyxle-init\"><code>pyxle init</code></h2><p>Create a new Pyxle project.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle init &lt;name&gt; [options]</code></pre></div><p><code>pyxle init</code> is <strong>interactive</strong>: when stdin is a terminal and no flag pins the\nchoice, it walks you through arrow-key selections — Tailwind CSS, shadcn/ui\n(only if Tailwind is enabled), and whether to customize the default import\nalias (<code>@/*</code>; the value input appears only if you say yes). When stdin is\n<strong>not</strong> a terminal (CI, pipes), it never prompts — it uses the flags and\ndefaults below.</p>\n<table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>name</code></td>\n<td><em>(required)</em></td>\n<td>Project directory to create. A name like <code>my-app</code> creates a new directory; <code>.</code> scaffolds into the current directory (deriving the name from it). Running <code>pyxle init</code> with no argument is an error.</td>\n</tr>\n<tr>\n<td><code>--force</code> / <code>-f</code></td>\n<td><code>false</code></td>\n<td>Overwrite an existing directory (or scaffold into a non-empty current directory).</td>\n</tr>\n<tr>\n<td><code>--template</code> / <code>-t</code></td>\n<td><code>default</code></td>\n<td>Project template. Only <code>&quot;default&quot;</code> is supported today (other values error).</td>\n</tr>\n<tr>\n<td><code>--tailwind</code> / <code>--no-tailwind</code></td>\n<td>prompt → off</td>\n<td>Set up Tailwind CSS v4 (wired into Vite).</td>\n</tr>\n<tr>\n<td><code>--shadcn</code> / <code>--no-shadcn</code></td>\n<td>prompt → off</td>\n<td>Set up shadcn/ui (implies <code>--tailwind</code>).</td>\n</tr>\n<tr>\n<td><code>--import-alias</code></td>\n<td><code>@/*</code></td>\n<td>Import alias for project modules (e.g. <code>~/*</code>).</td>\n</tr>\n<tr>\n<td><code>--yes</code> / <code>-y</code></td>\n<td><code>false</code></td>\n<td>Accept all defaults without prompting (no Tailwind, no shadcn, default alias).</td>\n</tr>\n<tr>\n<td><code>--install</code> / <code>--no-install</code></td>\n<td><code>false</code></td>\n<td>Run <code>pip install</code> and <code>npm install</code> after scaffolding.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle init my-app                          # interactive prompts\npyxle init my-app --yes                     # accept defaults (no Tailwind)\npyxle init my-app --tailwind --no-shadcn    # Tailwind only, no prompts\npyxle init my-app --shadcn                  # shadcn/ui (implies Tailwind)\npyxle init .                                # scaffold into an empty current dir\npyxle init my-app --force --install</code></pre></div><h2 id=\"pyxle-install\"><code>pyxle install</code></h2><p>Install Python and Node.js dependencies.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle install [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--python</code> / <code>--no-python</code></td>\n<td><code>true</code></td>\n<td>Install Python deps via <code>pip</code></td>\n</tr>\n<tr>\n<td><code>--node</code> / <code>--no-node</code></td>\n<td><code>true</code></td>\n<td>Install Node deps via <code>npm</code></td>\n</tr>\n<tr>\n<td><code>--break-system-packages</code></td>\n<td><code>false</code></td>\n<td>Pass <code>--break-system-packages</code> to <code>pip</code>, for externally-managed (PEP 668) environments without a virtualenv. Use with care.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle install\npyxle install --no-python    # Node only\npyxle install ./my-app\npyxle install --break-system-packages   # PEP 668 system Python, no venv</code></pre></div><p>Outside a virtualenv, <code>pyxle install</code> warns about PEP 668 (&quot;externally-managed-environment&quot;) and recommends creating a venv first; pass <code>--break-system-packages</code> to install anyway.</p>\n<h2 id=\"pyxle-dev\"><code>pyxle dev</code></h2><p>Start the development server with hot reload.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle dev [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Starlette server bind address</td>\n</tr>\n<tr>\n<td><code>--port</code></td>\n<td><code>8000</code></td>\n<td>Starlette server port</td>\n</tr>\n<tr>\n<td><code>--vite-host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Vite dev server bind address</td>\n</tr>\n<tr>\n<td><code>--vite-port</code></td>\n<td><code>5173</code></td>\n<td>Vite dev server port</td>\n</tr>\n<tr>\n<td><code>--debug</code> / <code>--no-debug</code></td>\n<td><code>true</code></td>\n<td>Enable debug mode</td>\n</tr>\n<tr>\n<td><code>--ssr-workers</code></td>\n<td><code>1</code></td>\n<td>Number of persistent SSR worker processes (<code>0</code> = per-request subprocess mode)</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--print-config</code> / <code>--no-print-config</code></td>\n<td><code>false</code></td>\n<td>Print merged configuration before starting</td>\n</tr>\n<tr>\n<td><code>--tailwind</code> / <code>--no-tailwind</code></td>\n<td><code>true</code></td>\n<td>Auto-start the <strong>legacy</strong> standalone Tailwind v3 CLI watcher when a hand-written <code>tailwind.config.*</code> is present. Tailwind <strong>v4</strong> projects (the scaffold default when you opt into Tailwind) run through the <code>@tailwindcss/vite</code> plugin and ignore this flag.</td>\n</tr>\n<tr>\n<td><code>--dashboard</code> / <code>--no-dashboard</code></td>\n<td><code>false</code></td>\n<td>Periodically print a live <a href=\"/docs/guides/observability#dev-dashboard\">observability</a> panel (request/SSR metrics) to the terminal</td>\n</tr>\n<tr>\n<td><code>--inspect</code> / <code>--no-inspect</code></td>\n<td><code>false</code></td>\n<td>Host a debugpy debug server (bound to <code>127.0.0.1</code>) so VS Code or any DAP client can set breakpoints directly in <code>.pyxl</code> files — see <a href=\"/docs/guides/debugging\">Debugging</a>. debugpy ships with the framework.</td>\n</tr>\n<tr>\n<td><code>--inspect-port</code></td>\n<td><code>5678</code></td>\n<td>Port for the debug server (with <code>--inspect</code>). Falls back to an ephemeral port when busy; the actual endpoint is recorded in <code>.pyxle-build/dev-server.json</code>.</td>\n</tr>\n<tr>\n<td><code>--inspect-wait</code> / <code>--no-inspect-wait</code></td>\n<td><code>false</code></td>\n<td>With <code>--inspect</code>: wait for a debugger to attach before starting the server — for breakpoints in code that runs during boot.</td>\n</tr>\n<tr>\n<td><code>--verbose</code> / <code>-v</code></td>\n<td><code>false</code></td>\n<td>Restore full output: the raw Vite log firehose, debug-level internals, and <code>DEBUG</code> server logs in the browser console. Equivalent to the global <code>pyxle -v dev</code>.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle dev\npyxle dev --host 0.0.0.0 --port 3000\npyxle dev --no-tailwind --ssr-workers 4\npyxle dev ./my-app --print-config\npyxle dev --verbose             # troubleshoot: full Vite + debug output</code></pre></div><p><strong>What it does:</strong></p>\n<ol>\n<li>Loads configuration from <code>pyxle.config.json</code> + environment variables + CLI flags</li>\n<li>Compiles <code>.pyxl</code> files into Python and JSX modules</li>\n<li>Starts the Vite dev server for React hot reload (Tailwind v4 compiles here via the <code>@tailwindcss/vite</code> plugin)</li>\n<li>Starts the legacy Tailwind v3 watcher only if a hand-written <code>tailwind.config.*</code> is detected</li>\n<li>Starts the Starlette ASGI server</li>\n<li>Watches for file changes and recompiles automatically</li>\n</ol>\n<p><strong>Console output.</strong> By default <code>pyxle dev</code> prints a clean, curated console — a\nstartup summary (the local URL, the Vite URL, the route count, and the total\n&quot;ready in X ms&quot;), a concise one-line notice per incremental rebuild\n(<code>Rebuilt … in X ms</code>), and any warnings or errors. The raw line-by-line Vite\nfirehose and debug-level internals are hidden. Pass <code>--verbose</code> (or <code>-v</code>, or the\nglobal <code>pyxle -v dev</code>) to restore the full output when troubleshooting. Genuine\nsignal — errors, warnings, the URLs, and rebuild success/failure — is always\nshown, at every verbosity.</p>\n<p><strong>Server logs in the browser console (dev only).</strong> While <code>pyxle dev</code> is running,\nyour server-side <code>logging</code> output (from loaders, actions, and your own modules)\nis forwarded to the browser devtools console, prefixed <code>[pyxle:server]</code> and\nmapped to the matching <code>console</code> method (<code>info</code> → <code>console.info</code>, <code>warning</code> →\n<code>console.warn</code>, <code>error</code> → <code>console.error</code>). This lets you follow server logs\nwithout leaving the browser. By default only <code>INFO</code> and above from your own\nloggers are forwarded; <code>--verbose</code> additionally forwards <code>DEBUG</code> records and the\nframework&#39;s own internal loggers. This is strictly a development feature — it\nnever runs under <code>pyxle serve</code> and never appears in the production bundle.</p>\n<h2 id=\"pyxle-studio\"><code>pyxle studio</code></h2><p>Run the dev server and open the <a href=\"/docs/guides/studio\">Pyxle Studio</a> dashboard.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle studio [directory] [options]</code></pre></div><p><code>pyxle studio</code> runs the same development server as <code>pyxle dev</code> — Studio is part of it, served at <code>/__pyxle/studio</code> — and opens your browser on the dashboard once the server is ready. Debug mode is forced on (Studio is dev-only), and the dashboard is enabled for this run even when the config sets <code>&quot;studio&quot;: false</code>.</p>\n<table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Starlette server bind address</td>\n</tr>\n<tr>\n<td><code>--port</code></td>\n<td><code>8000</code></td>\n<td>Starlette server port</td>\n</tr>\n<tr>\n<td><code>--vite-host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Vite dev server bind address</td>\n</tr>\n<tr>\n<td><code>--vite-port</code></td>\n<td><code>5173</code></td>\n<td>Vite dev server port</td>\n</tr>\n<tr>\n<td><code>--ssr-workers</code></td>\n<td><code>1</code></td>\n<td>Number of persistent SSR worker processes (<code>0</code> = per-request subprocess mode)</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--tailwind</code> / <code>--no-tailwind</code></td>\n<td><code>true</code></td>\n<td>Auto-start the legacy Tailwind v3 watcher when a hand-written <code>tailwind.config.*</code> is present (same behavior as <code>pyxle dev</code>)</td>\n</tr>\n<tr>\n<td><code>--open</code> / <code>--no-open</code></td>\n<td><code>true</code></td>\n<td>Open the Studio dashboard in the system browser once the server is ready</td>\n</tr>\n<tr>\n<td><code>--inspect</code> / <code>--no-inspect</code></td>\n<td><code>false</code></td>\n<td>Host a debugpy debug server for <code>.pyxl</code> breakpoint debugging — see <a href=\"/docs/guides/debugging\">Debugging</a></td>\n</tr>\n<tr>\n<td><code>--inspect-port</code></td>\n<td><code>5678</code></td>\n<td>Port for the debug server (with <code>--inspect</code>; falls back to an ephemeral port when busy)</td>\n</tr>\n<tr>\n<td><code>--verbose</code> / <code>-v</code></td>\n<td><code>false</code></td>\n<td>Restore full output (raw Vite logs, debug internals). Equivalent to <code>pyxle -v studio</code>.</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle studio                     # dev server + dashboard in the browser\npyxle studio --no-open           # dashboard enabled, but don't launch a browser\npyxle studio --inspect           # dashboard + debugger in one command\npyxle studio ./my-app --port 3000</code></pre></div><h2 id=\"pyxle-build\"><code>pyxle build</code></h2><p>Build production-ready assets.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle build [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--out-dir</code></td>\n<td><code>dist/</code></td>\n<td>Output directory for build artifacts</td>\n</tr>\n<tr>\n<td><code>--incremental</code> / <code>--no-incremental</code></td>\n<td><code>false</code></td>\n<td>Reuse cached artifacts</td>\n</tr>\n<tr>\n<td><code>--static</code> / <code>--no-static</code></td>\n<td><code>false</code></td>\n<td>Pre-render loader-less, non-dynamic pages to HTML at build time (SSG) — see <a href=\"/docs/guides/caching#static-pre-rendering-pyxle-build-static\">Caching</a></td>\n</tr>\n<tr>\n<td><code>--analyze</code> / <code>--no-analyze</code></td>\n<td><code>false</code></td>\n<td>Print a JS/CSS bundle-size report (raw + gzip, largest first) after the build — see <a href=\"/docs/guides/build-optimization#inspecting-the-bundle-pyxle-build-analyze\">Build Optimization</a></td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle build\npyxle build --analyze\npyxle build --out-dir ./output --incremental\npyxle build --static</code></pre></div><h2 id=\"pyxle-serve\"><code>pyxle serve</code></h2><p>Serve a production build (without Vite).</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle serve [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--host</code></td>\n<td><code>127.0.0.1</code></td>\n<td>Bind address</td>\n</tr>\n<tr>\n<td><code>--port</code></td>\n<td><code>8000</code></td>\n<td>Port number</td>\n</tr>\n<tr>\n<td><code>--dist-dir</code></td>\n<td><code>dist/</code></td>\n<td>Directory with production artifacts</td>\n</tr>\n<tr>\n<td><code>--skip-build</code> / <code>--no-skip-build</code></td>\n<td><code>false</code></td>\n<td>Skip running build first</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--serve-static</code> / <code>--no-serve-static</code></td>\n<td><code>true</code></td>\n<td>Serve static assets directly from Pyxle</td>\n</tr>\n<tr>\n<td><code>--ssr-workers</code></td>\n<td><code>1</code></td>\n<td>Number of persistent SSR worker processes, per server worker (<code>0</code> = auto-size to CPU cores, capped at 4)</td>\n</tr>\n<tr>\n<td><code>--workers</code> / <code>-w</code></td>\n<td><code>1</code></td>\n<td>Number of server worker processes (one per CPU core); <code>&gt;1</code> enables multi-core serving; <code>0</code> auto-detects from CPU cores</td>\n</tr>\n</tbody></table>\n<p><strong>Examples:</strong></p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle serve\npyxle serve --host 0.0.0.0 --port 8000 --skip-build\npyxle serve --ssr-workers 4\npyxle serve --workers $(nproc)   # one server process per CPU core</code></pre></div><p>With <code>--workers N</code> (N &gt; 1), Pyxle serves the build across <code>N</code> uvicorn worker\nprocesses. Each is an independent server with its own SSR pool, so <code>--ssr-workers</code>\napplies per worker (total render processes = <code>workers × ssr-workers</code>). See the\n<a href=\"/docs/guides/deployment#multi-core-worker-processes\">deployment guide</a> for\nsizing guidance.</p>\n<h2 id=\"pyxle-check\"><code>pyxle check</code></h2><p>Validate <code>.pyxl</code> files, configuration, and dependencies without starting the server. Each <code>.pyxl</code> file is checked at three levels:</p>\n<ul>\n<li><strong>Python syntax</strong> (via <code>ast</code>) and Pyxle structural rules (loader/action shape, <code>HEAD</code>, …).</li>\n<li><strong>Python semantics</strong> (via pyflakes): undefined names — e.g. a symbol you <code>raise</code> but never imported — unused imports, redefinitions. Compiler-injected runtime names (<code>server</code>, <code>action</code>, <code>LoaderError</code>, <code>ActionError</code>, …) are recognized, so the idiomatic patterns never read as undefined.</li>\n<li><strong>JSX syntax</strong> (via Babel): unclosed tags/expressions, mismatched braces, TypeScript in a client block, and <strong>duplicate <code>export default</code></strong> (which Babel accepts but the build rejects).</li>\n</ul>\n<p>As of 0.7.0 the JSX level works out of the box — <code>pyxle-langkit</code>, which provides the Babel-based checker, ships with the framework. On earlier versions it required the <code>[langkit]</code> extra (<code>pip install &#39;pyxle-framework[langkit]&#39;</code>); without it, the JSX check reported itself unavailable.</p>\n<blockquote>\n<p><strong>What a green check proves — and what it doesn&#39;t.</strong> <code>pyxle check</code> is a\nstatic gate: it validates <code>.pyxl</code> syntax, Python semantics, and JSX syntax.\nIt does <strong>not</strong> render your pages, so a mistake that only exists at runtime —\na component reading <code>data.posts</code> when the loader returns <code>{&quot;items&quot;: ...}</code>, a\nloader whose query fails against the real database — surfaces when the page\nrenders, not here. Treat a clean check as &quot;this compiles&quot;; loading the page\nunder <code>pyxle dev</code> (or a test that requests it) remains the runtime proof.</p>\n</blockquote>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle check [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n</tbody></table>\n<p><strong>Example output:</strong></p>\n<div class=\"code-block\" data-lang=\"\"><pre><code>ℹ️  Checked 12 .pyxl file(s) in my-app/\n✅ All checks passed</code></pre></div><p>Errors are reported per file as <code>[section] line N: message</code>, with the file path on the next line (every file is checked, so one broken file never aborts the scan):</p>\n<div class=\"code-block\" data-lang=\"\"><pre><code>ℹ️  Checked 12 .pyxl file(s) in my-app/\n  error: [python] line 15: @server function must be async\n    --&gt; pages/index.pyxl\n  error: [jsx] line 8:10: Unterminated JSX contents\n    --&gt; pages/settings.pyxl\n❌ Check failed with 2 error(s)</code></pre></div><p>Exit code is <code>0</code> when clean, <code>1</code> when any error is found.</p>\n<h2 id=\"pyxle-typecheck\"><code>pyxle typecheck</code></h2><p>Run TypeScript type-checking on compiled JSX output.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle typecheck [directory] [options]</code></pre></div><p>Requires <code>typescript</code> in your <code>devDependencies</code>. Runs <code>tsc --noEmit</code> against the compiled JSX in <code>.pyxle-build/client/</code>.</p>\n<table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n</tbody></table>\n<h2 id=\"pyxle-routes\"><code>pyxle routes</code></h2><p>Display the route table for your project.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle routes [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--json</code></td>\n<td><code>false</code></td>\n<td>Output as JSON</td>\n</tr>\n</tbody></table>\n<p><strong>Example output:</strong></p>\n<div class=\"code-block\" data-lang=\"\"><pre><code>ℹ️  Routes for my-app/\n\n  Pages:\n  ▶️  /  — pages/index.pyxl  [loader=load_home]\n  ▶️  /about  — pages/about.pyxl\n  ▶️  /blog/{slug}  — pages/blog/[slug].pyxl  [loader=load_post]\n\n  API Routes:\n  ▶️  /api/pulse  — pages/api/pulse.py</code></pre></div><p>Use <code>--json</code> for machine-readable output.</p>\n<h2 id=\"pyxle-openapi\"><code>pyxle openapi</code></h2><p>Generate an <a href=\"https://spec.openapis.org/oas/v3.1.0\" target=\"_blank\" rel=\"noreferrer\">OpenAPI 3.1</a> document from your <code>@action</code> request models. For every action that declares a <a href=\"/docs/core-concepts/server-actions#validating-request-bodies-with-pydantic\">Pydantic body parameter</a>, Pyxle emits a <code>POST</code> operation with the model&#39;s JSON Schema as the request body and a structured <code>422</code> validation response; actions without a model get a permissive object body.</p>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\">pyxle openapi [directory] [options]</code></pre></div><table>\n<thead>\n<tr>\n<th>Argument / Flag</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>directory</code></td>\n<td><code>.</code></td>\n<td>Project directory</td>\n</tr>\n<tr>\n<td><code>--config</code></td>\n<td>--</td>\n<td>Path to <code>pyxle.config.json</code></td>\n</tr>\n<tr>\n<td><code>--out</code> / <code>-o</code></td>\n<td>--</td>\n<td>Write the schema to this file (default: stdout)</td>\n</tr>\n<tr>\n<td><code>--title</code></td>\n<td><code>Pyxle API</code></td>\n<td>OpenAPI <code>info.title</code></td>\n</tr>\n<tr>\n<td><code>--api-version</code></td>\n<td><code>0.1.0</code></td>\n<td>OpenAPI <code>info.version</code></td>\n</tr>\n</tbody></table>\n<div class=\"code-block\" data-lang=\"bash\"><pre><code class=\"language-bash\"># Print to stdout\npyxle openapi\n\n# Write a file with custom metadata\npyxle openapi --out openapi.json --title \"Acme API\" --api-version 2.0.0</code></pre></div><p>The schema is derived from runtime introspection of the compiled action modules, so it always matches what the dispatcher actually validates. Requires the <code>[pydantic]</code> extra (<code>pip install &quot;pyxle-framework[pydantic]&quot;</code>); the command exits with an error if Pydantic isn&#39;t installed or a page module can&#39;t be imported.</p>\n","toc":[{"depth":2,"text":"Global options","slug":"global-options"},{"depth":2,"text":"pyxle init","slug":"pyxle-init"},{"depth":2,"text":"pyxle install","slug":"pyxle-install"},{"depth":2,"text":"pyxle dev","slug":"pyxle-dev"},{"depth":2,"text":"pyxle studio","slug":"pyxle-studio"},{"depth":2,"text":"pyxle build","slug":"pyxle-build"},{"depth":2,"text":"pyxle serve","slug":"pyxle-serve"},{"depth":2,"text":"pyxle check","slug":"pyxle-check"},{"depth":2,"text":"pyxle typecheck","slug":"pyxle-typecheck"},{"depth":2,"text":"pyxle routes","slug":"pyxle-routes"},{"depth":2,"text":"pyxle openapi","slug":"pyxle-openapi"}],"path":"reference/cli","markdown":"# CLI Reference\n\nThe `pyxle` CLI manages Pyxle projects from scaffolding to production.\n\n## Global options\n\n| Flag | Description |\n|------|-------------|\n| `--version` | Show Pyxle version and exit |\n| `--log-format [console\\|json]` | Output format (default: `console`) |\n| `--verbose` / `-v` | Show debug-level output |\n| `--quiet` / `-q` | Suppress informational output; show only warnings and errors |\n| `--install-completion` | Install shell completion for the current shell |\n| `--show-completion` | Print shell completion (to copy or customize) |\n\n## `pyxle init`\n\nCreate a new Pyxle project.\n\n```bash\npyxle init <name> [options]\n```\n\n`pyxle init` is **interactive**: when stdin is a terminal and no flag pins the\nchoice, it walks you through arrow-key selections — Tailwind CSS, shadcn/ui\n(only if Tailwind is enabled), and whether to customize the default import\nalias (`@/*`; the value input appears only if you say yes). When stdin is\n**not** a terminal (CI, pipes), it never prompts — it uses the flags and\ndefaults below.\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `name` | *(required)* | Project directory to create. A name like `my-app` creates a new directory; `.` scaffolds into the current directory (deriving the name from it). Running `pyxle init` with no argument is an error. |\n| `--force` / `-f` | `false` | Overwrite an existing directory (or scaffold into a non-empty current directory). |\n| `--template` / `-t` | `default` | Project template. Only `\"default\"` is supported today (other values error). |\n| `--tailwind` / `--no-tailwind` | prompt → off | Set up Tailwind CSS v4 (wired into Vite). |\n| `--shadcn` / `--no-shadcn` | prompt → off | Set up shadcn/ui (implies `--tailwind`). |\n| `--import-alias` | `@/*` | Import alias for project modules (e.g. `~/*`). |\n| `--yes` / `-y` | `false` | Accept all defaults without prompting (no Tailwind, no shadcn, default alias). |\n| `--install` / `--no-install` | `false` | Run `pip install` and `npm install` after scaffolding. |\n\n**Examples:**\n\n```bash\npyxle init my-app                          # interactive prompts\npyxle init my-app --yes                     # accept defaults (no Tailwind)\npyxle init my-app --tailwind --no-shadcn    # Tailwind only, no prompts\npyxle init my-app --shadcn                  # shadcn/ui (implies Tailwind)\npyxle init .                                # scaffold into an empty current dir\npyxle init my-app --force --install\n```\n\n## `pyxle install`\n\nInstall Python and Node.js dependencies.\n\n```bash\npyxle install [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--python` / `--no-python` | `true` | Install Python deps via `pip` |\n| `--node` / `--no-node` | `true` | Install Node deps via `npm` |\n| `--break-system-packages` | `false` | Pass `--break-system-packages` to `pip`, for externally-managed (PEP 668) environments without a virtualenv. Use with care. |\n\n**Examples:**\n\n```bash\npyxle install\npyxle install --no-python    # Node only\npyxle install ./my-app\npyxle install --break-system-packages   # PEP 668 system Python, no venv\n```\n\nOutside a virtualenv, `pyxle install` warns about PEP 668 (\"externally-managed-environment\") and recommends creating a venv first; pass `--break-system-packages` to install anyway.\n\n## `pyxle dev`\n\nStart the development server with hot reload.\n\n```bash\npyxle dev [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--host` | `127.0.0.1` | Starlette server bind address |\n| `--port` | `8000` | Starlette server port |\n| `--vite-host` | `127.0.0.1` | Vite dev server bind address |\n| `--vite-port` | `5173` | Vite dev server port |\n| `--debug` / `--no-debug` | `true` | Enable debug mode |\n| `--ssr-workers` | `1` | Number of persistent SSR worker processes (`0` = per-request subprocess mode) |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--print-config` / `--no-print-config` | `false` | Print merged configuration before starting |\n| `--tailwind` / `--no-tailwind` | `true` | Auto-start the **legacy** standalone Tailwind v3 CLI watcher when a hand-written `tailwind.config.*` is present. Tailwind **v4** projects (the scaffold default when you opt into Tailwind) run through the `@tailwindcss/vite` plugin and ignore this flag. |\n| `--dashboard` / `--no-dashboard` | `false` | Periodically print a live [observability](https://pyxle.dev/docs/guides/observability.md#dev-dashboard) panel (request/SSR metrics) to the terminal |\n| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server (bound to `127.0.0.1`) so VS Code or any DAP client can set breakpoints directly in `.pyxl` files — see [Debugging](https://pyxle.dev/docs/guides/debugging.md). debugpy ships with the framework. |\n| `--inspect-port` | `5678` | Port for the debug server (with `--inspect`). Falls back to an ephemeral port when busy; the actual endpoint is recorded in `.pyxle-build/dev-server.json`. |\n| `--inspect-wait` / `--no-inspect-wait` | `false` | With `--inspect`: wait for a debugger to attach before starting the server — for breakpoints in code that runs during boot. |\n| `--verbose` / `-v` | `false` | Restore full output: the raw Vite log firehose, debug-level internals, and `DEBUG` server logs in the browser console. Equivalent to the global `pyxle -v dev`. |\n\n**Examples:**\n\n```bash\npyxle dev\npyxle dev --host 0.0.0.0 --port 3000\npyxle dev --no-tailwind --ssr-workers 4\npyxle dev ./my-app --print-config\npyxle dev --verbose             # troubleshoot: full Vite + debug output\n```\n\n**What it does:**\n\n1. Loads configuration from `pyxle.config.json` + environment variables + CLI flags\n2. Compiles `.pyxl` files into Python and JSX modules\n3. Starts the Vite dev server for React hot reload (Tailwind v4 compiles here via the `@tailwindcss/vite` plugin)\n4. Starts the legacy Tailwind v3 watcher only if a hand-written `tailwind.config.*` is detected\n5. Starts the Starlette ASGI server\n6. Watches for file changes and recompiles automatically\n\n**Console output.** By default `pyxle dev` prints a clean, curated console — a\nstartup summary (the local URL, the Vite URL, the route count, and the total\n\"ready in X ms\"), a concise one-line notice per incremental rebuild\n(`Rebuilt … in X ms`), and any warnings or errors. The raw line-by-line Vite\nfirehose and debug-level internals are hidden. Pass `--verbose` (or `-v`, or the\nglobal `pyxle -v dev`) to restore the full output when troubleshooting. Genuine\nsignal — errors, warnings, the URLs, and rebuild success/failure — is always\nshown, at every verbosity.\n\n**Server logs in the browser console (dev only).** While `pyxle dev` is running,\nyour server-side `logging` output (from loaders, actions, and your own modules)\nis forwarded to the browser devtools console, prefixed `[pyxle:server]` and\nmapped to the matching `console` method (`info` → `console.info`, `warning` →\n`console.warn`, `error` → `console.error`). This lets you follow server logs\nwithout leaving the browser. By default only `INFO` and above from your own\nloggers are forwarded; `--verbose` additionally forwards `DEBUG` records and the\nframework's own internal loggers. This is strictly a development feature — it\nnever runs under `pyxle serve` and never appears in the production bundle.\n\n## `pyxle studio`\n\nRun the dev server and open the [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) dashboard.\n\n```bash\npyxle studio [directory] [options]\n```\n\n`pyxle studio` runs the same development server as `pyxle dev` — Studio is part of it, served at `/__pyxle/studio` — and opens your browser on the dashboard once the server is ready. Debug mode is forced on (Studio is dev-only), and the dashboard is enabled for this run even when the config sets `\"studio\": false`.\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--host` | `127.0.0.1` | Starlette server bind address |\n| `--port` | `8000` | Starlette server port |\n| `--vite-host` | `127.0.0.1` | Vite dev server bind address |\n| `--vite-port` | `5173` | Vite dev server port |\n| `--ssr-workers` | `1` | Number of persistent SSR worker processes (`0` = per-request subprocess mode) |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--tailwind` / `--no-tailwind` | `true` | Auto-start the legacy Tailwind v3 watcher when a hand-written `tailwind.config.*` is present (same behavior as `pyxle dev`) |\n| `--open` / `--no-open` | `true` | Open the Studio dashboard in the system browser once the server is ready |\n| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server for `.pyxl` breakpoint debugging — see [Debugging](https://pyxle.dev/docs/guides/debugging.md) |\n| `--inspect-port` | `5678` | Port for the debug server (with `--inspect`; falls back to an ephemeral port when busy) |\n| `--verbose` / `-v` | `false` | Restore full output (raw Vite logs, debug internals). Equivalent to `pyxle -v studio`. |\n\n**Examples:**\n\n```bash\npyxle studio                     # dev server + dashboard in the browser\npyxle studio --no-open           # dashboard enabled, but don't launch a browser\npyxle studio --inspect           # dashboard + debugger in one command\npyxle studio ./my-app --port 3000\n```\n\n## `pyxle build`\n\nBuild production-ready assets.\n\n```bash\npyxle build [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--out-dir` | `dist/` | Output directory for build artifacts |\n| `--incremental` / `--no-incremental` | `false` | Reuse cached artifacts |\n| `--static` / `--no-static` | `false` | Pre-render loader-less, non-dynamic pages to HTML at build time (SSG) — see [Caching](https://pyxle.dev/docs/guides/caching.md#static-pre-rendering-pyxle-build-static) |\n| `--analyze` / `--no-analyze` | `false` | Print a JS/CSS bundle-size report (raw + gzip, largest first) after the build — see [Build Optimization](https://pyxle.dev/docs/guides/build-optimization.md#inspecting-the-bundle-pyxle-build-analyze) |\n\n**Examples:**\n\n```bash\npyxle build\npyxle build --analyze\npyxle build --out-dir ./output --incremental\npyxle build --static\n```\n\n## `pyxle serve`\n\nServe a production build (without Vite).\n\n```bash\npyxle serve [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--host` | `127.0.0.1` | Bind address |\n| `--port` | `8000` | Port number |\n| `--dist-dir` | `dist/` | Directory with production artifacts |\n| `--skip-build` / `--no-skip-build` | `false` | Skip running build first |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--serve-static` / `--no-serve-static` | `true` | Serve static assets directly from Pyxle |\n| `--ssr-workers` | `1` | Number of persistent SSR worker processes, per server worker (`0` = auto-size to CPU cores, capped at 4) |\n| `--workers` / `-w` | `1` | Number of server worker processes (one per CPU core); `>1` enables multi-core serving; `0` auto-detects from CPU cores |\n\n**Examples:**\n\n```bash\npyxle serve\npyxle serve --host 0.0.0.0 --port 8000 --skip-build\npyxle serve --ssr-workers 4\npyxle serve --workers $(nproc)   # one server process per CPU core\n```\n\nWith `--workers N` (N > 1), Pyxle serves the build across `N` uvicorn worker\nprocesses. Each is an independent server with its own SSR pool, so `--ssr-workers`\napplies per worker (total render processes = `workers × ssr-workers`). See the\n[deployment guide](https://pyxle.dev/docs/guides/deployment.md#multi-core-worker-processes) for\nsizing guidance.\n\n## `pyxle check`\n\nValidate `.pyxl` files, configuration, and dependencies without starting the server. Each `.pyxl` file is checked at three levels:\n\n- **Python syntax** (via `ast`) and Pyxle structural rules (loader/action shape, `HEAD`, …).\n- **Python semantics** (via pyflakes): undefined names — e.g. a symbol you `raise` but never imported — unused imports, redefinitions. Compiler-injected runtime names (`server`, `action`, `LoaderError`, `ActionError`, …) are recognized, so the idiomatic patterns never read as undefined.\n- **JSX syntax** (via Babel): unclosed tags/expressions, mismatched braces, TypeScript in a client block, and **duplicate `export default`** (which Babel accepts but the build rejects).\n\nAs of 0.7.0 the JSX level works out of the box — `pyxle-langkit`, which provides the Babel-based checker, ships with the framework. On earlier versions it required the `[langkit]` extra (`pip install 'pyxle-framework[langkit]'`); without it, the JSX check reported itself unavailable.\n\n> **What a green check proves — and what it doesn't.** `pyxle check` is a\n> static gate: it validates `.pyxl` syntax, Python semantics, and JSX syntax.\n> It does **not** render your pages, so a mistake that only exists at runtime —\n> a component reading `data.posts` when the loader returns `{\"items\": ...}`, a\n> loader whose query fails against the real database — surfaces when the page\n> renders, not here. Treat a clean check as \"this compiles\"; loading the page\n> under `pyxle dev` (or a test that requests it) remains the runtime proof.\n\n```bash\npyxle check [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n\n**Example output:**\n\n```\nℹ️  Checked 12 .pyxl file(s) in my-app/\n✅ All checks passed\n```\n\nErrors are reported per file as `[section] line N: message`, with the file path on the next line (every file is checked, so one broken file never aborts the scan):\n\n```\nℹ️  Checked 12 .pyxl file(s) in my-app/\n  error: [python] line 15: @server function must be async\n    --> pages/index.pyxl\n  error: [jsx] line 8:10: Unterminated JSX contents\n    --> pages/settings.pyxl\n❌ Check failed with 2 error(s)\n```\n\nExit code is `0` when clean, `1` when any error is found.\n\n## `pyxle typecheck`\n\nRun TypeScript type-checking on compiled JSX output.\n\n```bash\npyxle typecheck [directory] [options]\n```\n\nRequires `typescript` in your `devDependencies`. Runs `tsc --noEmit` against the compiled JSX in `.pyxle-build/client/`.\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n\n## `pyxle routes`\n\nDisplay the route table for your project.\n\n```bash\npyxle routes [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--json` | `false` | Output as JSON |\n\n**Example output:**\n\n```\nℹ️  Routes for my-app/\n\n  Pages:\n  ▶️  /  — pages/index.pyxl  [loader=load_home]\n  ▶️  /about  — pages/about.pyxl\n  ▶️  /blog/{slug}  — pages/blog/[slug].pyxl  [loader=load_post]\n\n  API Routes:\n  ▶️  /api/pulse  — pages/api/pulse.py\n```\n\nUse `--json` for machine-readable output.\n\n## `pyxle openapi`\n\nGenerate an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) document from your `@action` request models. For every action that declares a [Pydantic body parameter](https://pyxle.dev/docs/core-concepts/server-actions.md#validating-request-bodies-with-pydantic), Pyxle emits a `POST` operation with the model's JSON Schema as the request body and a structured `422` validation response; actions without a model get a permissive object body.\n\n```bash\npyxle openapi [directory] [options]\n```\n\n| Argument / Flag | Default | Description |\n|----------------|---------|-------------|\n| `directory` | `.` | Project directory |\n| `--config` | -- | Path to `pyxle.config.json` |\n| `--out` / `-o` | -- | Write the schema to this file (default: stdout) |\n| `--title` | `Pyxle API` | OpenAPI `info.title` |\n| `--api-version` | `0.1.0` | OpenAPI `info.version` |\n\n```bash\n# Print to stdout\npyxle openapi\n\n# Write a file with custom metadata\npyxle openapi --out openapi.json --title \"Acme API\" --api-version 2.0.0\n```\n\nThe schema is derived from runtime introspection of the compiled action modules, so it always matches what the dispatcher actually validates. Requires the `[pydantic]` extra (`pip install \"pyxle-framework[pydantic]\"`); the command exits with an error if Pydantic isn't installed or a page module can't be imported.\n","prev":{"title":"Migrating from .pyx to .pyxl","path":"guides/migration-pyx-to-pyxl"},"next":{"title":"Configuration Reference","path":"reference/configuration"}}
\ No newline at end of file
diff --git a/public/llms-full.txt b/public/llms-full.txt
index cfd2ddb..999be31 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -4993,7 +4993,109 @@ Source: https://pyxle.dev/docs/guides/debugging.md
 A Pyxle app has two runtimes: **Python** (your `@server` loaders, `@action`
 handlers, and the request pipeline) and **Node.js** (the SSR worker that renders
 your React components to HTML). Knowing which side an error comes from tells you
-where to look. This guide covers both.
+where to look. This guide covers both — including how to set a breakpoint
+directly in a `.pyxl` file, on a line inside a `@server` loader *and* on a line
+inside the JSX below it, and have both bind.
+
+There is no bespoke Pyxle debugger: `pyxle dev --inspect` exposes the Python half
+to any debugger, dev source maps expose the React half to the browser, and the
+VS Code extension turns each into one launch.
+
+---
+
+## Install the VS Code extension
+
+Breakpoint debugging from the editor needs **[Pyxle Language Tools][ext]**
+(0.3.0 or newer). Install it from the command line:
+
+```bash
+code --install-extension pyxle.pyxle-language-tools
+```
+
+…or search for **Pyxle Language Tools** in the Extensions view (`Ctrl+Shift+X` /
+`Cmd+Shift+X`), or install it from the [VS Code Marketplace][ext] in a browser.
+
+Two more requirements, both one-time:
+
+- **pyxle-framework 0.8.0 or newer** in the environment VS Code has selected. The
+  debugger relies on line mapping added in 0.8.0 and launches the dev server as
+  `python -m pyxle`, which earlier versions don't provide. Upgrade with
+  `pip install --upgrade pyxle-framework`.
+- **The Python extension** (`ms-python.python`) for Python-side breakpoints. The
+  debugger prompts you if it's missing, and still debugs the React side without it.
+
+Nothing else to install — debugpy ships with the framework.
+
+The extension also gives you syntax highlighting, diagnostics, completions,
+hover, go-to-definition and formatting for `.pyxl` files; see
+[Editor setup](https://pyxle.dev/docs/guides/editor-setup.md) for the full feature list and the language-server
+details.
+
+[ext]: https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools
+
+---
+
+## Quick start: breakpoints in a .pyxl file
+
+Open a `.pyxl` file and press **F5**. With no `launch.json` yet, Pyxle asks which
+half to debug — **Backend — Python** or **Frontend — React**. Pick one, or commit
+the configurations to skip the prompt:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    { "type": "pyxle", "request": "launch", "name": "Debug Pyxle app" },
+    { "type": "pyxle", "request": "launch", "name": "Debug Pyxle app (React browser)", "server": false }
+  ]
+}
+```
+
+Choosing **Backend** runs your dev server under the Python debugger — one clean
+debug session that VS Code owns. A breakpoint in a loader or action pauses the
+request with the `.pyxl` frame in the stack. Once the server is ready, your app
+opens in the browser. **Stop**, **Restart**, and **Pause** all act on that single
+session — Stop tears the whole server (Vite, SSR workers) down with it.
+
+**To debug the React half too**, run the **"Debug Pyxle app (React browser)"**
+configuration (it's just `"server": false`) — a standalone browser session pointed
+at the running dev server. A breakpoint you set in the component pauses there, in
+the same `.pyxl` file you set the loader breakpoint in. It's a *separate* session
+on purpose: keeping the browser out of the Python session's toolbar means each
+side has clean, unambiguous Stop / Restart / Pause.
+
+If the Frontend session had to start its own `pyxle dev` (nothing was running),
+**stopping it offers to stop that server too** — a one-click "Stop server".
+Restarting the Frontend session keeps the server up. If instead it attached to a
+server something else started (Backend, or a `pyxle dev` you ran yourself),
+stopping Frontend leaves that server running untouched.
+
+To debug **both** halves, start **Backend** first — it runs the dev server — then
+start **Frontend**, which attaches its browser to that same server. Stop on either
+side then does the right thing: stopping Frontend leaves the server (Backend owns
+it), stopping Backend tears it down. Frontend on its own works standalone too;
+just don't start Backend on top of a Frontend-started server, or they'll race for
+the port (the second fails to bind with "address already in use" — stop the first,
+then start the other).
+
+The launch configuration accepts a few knobs:
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `cwd` | `${workspaceFolder}` | Pyxle project root (contains `pages/` and `pyxle.config.json`). |
+| `server` | `true` | Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set `false` to debug **only** the React side in a standalone browser session. |
+| `browser` | `true` | When debugging Python, open the app in your browser once the server is ready. |
+| `url` | dev server root | Page to open. |
+| `args` | `[]` | Extra arguments passed to `pyxle dev` (e.g. `["--port", "3000"]`). |
+| `justMyCode` | `true` | Keep stepping inside your own code. Set `false` to step into framework internals. |
+
+To attach to an already-running server instead of launching one, use
+`"request": "attach"` (see [Attaching from any DAP client](#attaching-from-any-dap-client)).
+
+The extension also contributes a **"Pyxle: Open Studio"** command, which opens the
+running server's [Studio dashboard](https://pyxle.dev/docs/guides/studio.md) from the command palette.
+
+---
 
 ## Read the error first
 
@@ -5013,18 +5115,12 @@ In production (`debug=false`) error responses are intentionally generic — no
 stack traces or file paths in the body. The full detail goes to the **server
 log** instead. Check your process manager's logs (e.g. `journalctl -u myapp`).
 
-## Breakpoints in .pyxl files
-
-Beyond `pdb`, Pyxle has a full breakpoint-debugging story: `pyxle dev --inspect`
-hosts a debug server so VS Code (or any DAP client) can pause a request at a
-breakpoint set **directly in a `.pyxl` file** — Python loaders/actions on the
-server side, and the React half through the browser. That workflow has its own
-guide: [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md).
+---
 
 ## Debugging a loader or action (the Python side)
 
 `@server` and `@action` functions are plain `async` functions — debug them like
-any Python. Drop a breakpoint:
+any Python. Set a breakpoint in the editor as above, or drop one in code:
 
 ```python
 @server
@@ -5034,8 +5130,8 @@ async def load_dashboard(request):
     return {"stats": data}
 ```
 
-Run `pyxle dev` **in a terminal you can type into** (not detached) and the `pdb`
-prompt appears there when the loader runs. Or add logging — it shows in the
+For `pdb`, run `pyxle dev` **in a terminal you can type into** (not detached) and
+the prompt appears there when the loader runs. Or add logging — it shows in the
 terminal *and* the browser console in dev:
 
 ```python
@@ -5059,6 +5155,8 @@ Two common Python-side errors have targeted messages:
 - **A loader raising `LoaderError`** triggers the nearest `error.pyxl` boundary;
   see [Error Handling](https://pyxle.dev/docs/guides/error-handling.md).
 
+---
+
 ## Debugging rendering (the Node/SSR side)
 
 Your React component runs **on the server** during SSR before it ever runs in the
@@ -5088,110 +5186,27 @@ NODE_OPTIONS="--inspect" pyxle dev
 then open `chrome://inspect`. This is rarely needed for app code — it's for
 diagnosing the render transport itself.
 
-## Reading the compiled output
-
-Pyxle compiles each `.pyxl` into a Python module and a JavaScript module under
-the build directory (`.pyxle-build/` in dev, `dist/` for a production build).
-Reading them demystifies "where did my code go":
-
-- `.pyxle-build/server/pages/…​.py` — the **Python** half: your `@server` /
-  `@action` functions with the runtime imports the compiler injected at the top
-  (`from pyxle.runtime import server`, etc.).
-- `.pyxle-build/client/…​` — the **JavaScript** half: your component, ready for
-  Vite.
-
-In development, Python tracebacks already point at your `.pyxl` file and line
-(see [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md)). A traceback from a
-**production build** points at the compiled `.py`; the compiler preserves your
-code verbatim below the injected header, so mapping back to your `.pyxl` is a
-small, constant offset. The build directory is disposable — delete it and the
-next `pyxle dev`/`build` regenerates it.
-
-## Static checks
-
-Two commands catch problems before you run the page:
-
-- **`pyxle check`** — validates `.pyxl` syntax, Python semantics, and JSX. Note
-  that a green check does not prove a page *renders*: a component reading a loader
-  key that doesn't exist is a runtime error, not a static one.
-- **`pyxle typecheck`** — runs TypeScript over your compiled JSX when you've opted
-  into TypeScript (see the [TypeScript guide](https://pyxle.dev/docs/guides/typescript.md)).
-
-## Common symptoms
-
-| Symptom | Likely cause | Where to look |
-|---------|--------------|---------------|
-| Blank page, overlay shows a Python traceback | Loader/action raised | `pyxle dev` terminal; add a `breakpoint()` |
-| `window is not defined` | Browser global at render scope | The named `.pyxl`; use `useEffect`/`<ClientOnly>` |
-| `'State' object has no attribute 'db'` | Missing plugin | `plugins` in `pyxle.config.json` |
-| Component data is `undefined` | Loader key ≠ component prop | Compare the loader's return dict to the component's `data` usage |
-| Change didn't take effect | Editing built output, or a stale build | Edit the `.pyxl` source, not `.pyxle-build/` |
-| Works in dev, fails in prod | Debug-only behavior / missing env | Server log (prod hides detail from the response) |
-
-## Next steps
-
-- [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md) — breakpoints in `.pyxl` source with VS Code or any DAP client
-- [Error Handling](https://pyxle.dev/docs/guides/error-handling.md) — `LoaderError`, error boundaries, 404s
-- [Testing](https://pyxle.dev/docs/guides/testing.md) — unit-test loaders and actions
-- [Client Components](https://pyxle.dev/docs/guides/client-components.md) — browser-only code and `<ClientOnly>`
-
 ---
 
-Source: https://pyxle.dev/docs/guides/debugging-pyxl.md
-
-# Debugging .pyxl files
-
-Set a breakpoint directly in your `.pyxl` source — on a line inside a `@server` loader *and* on a line inside the JSX below it — and both bind. `pyxle dev --inspect` exposes the Python half to any debugger, dev source maps expose the React half to the browser, and the VS Code extension turns each into one launch: **F5** for the Python side, a second configuration for the React side. No custom debugger, no compiled-file archaeology.
-
----
-
-## Quick start (VS Code)
-
-1. Install the **Pyxle Language Tools** extension (0.3.0 or later). For Python-side breakpoints, also install the **Python** extension (`ms-python.python`) — the debugger prompts you if it's missing and still debugs the React side without it.
-2. Make sure your project uses **pyxle-framework 0.8.0 or newer** (the debugger relies on line mapping shipped in 0.8.0). Nothing else to install: debugpy ships with the framework.
-3. Open a `.pyxl` file and press **F5**. With no `launch.json` yet, Pyxle asks which half to debug — **Backend — Python** or **Frontend — React**. Pick one, or commit the configurations to skip the prompt:
-
-```json
-{
-  "version": "0.2.0",
-  "configurations": [
-    { "type": "pyxle", "request": "launch", "name": "Debug Pyxle app" },
-    { "type": "pyxle", "request": "launch", "name": "Debug Pyxle app (React browser)", "server": false }
-  ]
-}
-```
-
-Choosing **Backend** runs your dev server under the Python debugger — one clean debug session that VS Code owns. A breakpoint in a loader or action pauses the request in VS Code with the `.pyxl` frame in the stack. Once the server is ready, your app opens in the browser. **Stop**, **Restart**, and **Pause** all act on that single session — Stop tears the whole server (Vite, SSR workers) down with it. It needs the **Python** extension (`ms-python.python`); the debugger offers to install it if it's missing.
-
-**To debug the React half too**, run the **"Debug Pyxle app (React browser)"** configuration (it's just `"server": false`) — a standalone Chrome session pointed at the running dev server. A breakpoint you set in the component pauses there, in the same `.pyxl` file you set the loader breakpoint in. It's a *separate* session on purpose: keeping the browser out of the Python session's toolbar means each side has clean, unambiguous Stop / Restart / Pause.
-
-If the Frontend session had to start its own `pyxle dev` (nothing was running), **stopping it offers to stop that server too** — a one-click "Stop server". Restarting the Frontend session keeps the server up (no prompt). If instead it attached to a server something else started (Backend, or a `pyxle dev` you ran yourself), stopping Frontend leaves that server running untouched — you stop it where you started it.
-
-To debug **both** halves, start **Backend** first — it runs the dev server — then start **Frontend**, which attaches its browser to that same server. That way Stop on either side does the right thing: stopping Frontend leaves the server (Backend owns it), stopping Backend tears it down. Frontend on its own works standalone too; just don't start Backend on top of a Frontend-started server, or they'll race for the port (the second one fails to bind with an "address already in use" error — stop the first, then start the other).
-
-The launch configuration accepts a few knobs:
-
-| Property | Default | Description |
-|----------|---------|-------------|
-| `cwd` | `${workspaceFolder}` | Pyxle project root (contains `pages/` and `pyxle.config.json`). |
-| `server` | `true` | Run the dev server under the Python debugger so breakpoints in loaders and actions bind. Set `false` to debug **only** the React side in a standalone Chrome session. |
-| `browser` | `true` | When debugging Python, open the app in your browser once the server is ready. |
-| `url` | dev server root | Page to open. |
-| `args` | `[]` | Extra arguments passed to `pyxle dev` (e.g. `["--port", "3000"]`). |
-| `justMyCode` | `true` | Keep stepping inside your own code. Set `false` to step into framework internals. |
-
-To attach to an already-running server instead of launching one, use `"request": "attach"` (see [Attaching from any DAP client](#attaching-from-any-dap-client)).
-
-The extension also contributes a **"Pyxle: Open Studio"** command, which opens the running server's [Studio dashboard](https://pyxle.dev/docs/guides/studio.md) from the command palette.
-
----
-
-## How it works
-
-There is no bespoke Pyxle debugger — the feature is two stock debuggers plus line mapping, which is why it works so broadly:
-
-- **The Python half** (`@server` loaders, `@action` handlers). The compiler embeds a line map in every generated server module, and in development the server imports those modules with `co_filename` and line numbers remapped to the original `.pyxl` source. To [debugpy](https://github.com/microsoft/debugpy) the running code simply *is* your `.pyxl` file, so breakpoints set there bind natively. The default launch runs the dev server under debugpy directly; `--inspect` instead hosts a debugpy server for clients to attach to.
-- **The React half** (the JSX in the same file). The compiler writes a source-map sidecar for each generated `.jsx` module, and the dev Vite config includes a small dev-only plugin that attaches those maps pointing back at the real `.pyxl` file on disk. VS Code's built-in js-debug resolves that file and binds breakpoints in it; browser devtools map every position the same way.
+## How the breakpoint mapping works
+
+The feature is two stock debuggers plus line mapping, which is why it works so
+broadly:
+
+- **The Python half** (`@server` loaders, `@action` handlers). The compiler embeds
+  a line map in every generated server module, and in development the server
+  imports those modules with `co_filename` and line numbers remapped to the
+  original `.pyxl` source. To [debugpy](https://github.com/microsoft/debugpy) the
+  running code simply *is* your `.pyxl` file, so breakpoints set there bind
+  natively. The default launch runs the dev server under debugpy directly;
+  `--inspect` instead hosts a debugpy server for clients to attach to.
+- **The React half** (the JSX in the same file). The compiler writes a source-map
+  sidecar for each generated `.jsx` module, and the dev Vite config includes a
+  small dev-only plugin that attaches those maps pointing back at the real `.pyxl`
+  file on disk. VS Code's built-in js-debug resolves that file and binds
+  breakpoints in it; browser devtools map every position the same way. The map is
+  fetched by the browser, so it carries only the JSX lines — the `@server` and
+  `@action` Python in the same file is never sent to a client.
 
 Both mappings exist only in development. A production build ships neither.
 
@@ -5199,7 +5214,8 @@ Both mappings exist only in development. A production build ships neither.
 
 ## CLI reference
 
-The debugger flags live on `pyxle dev` (and `pyxle studio`, which accepts `--inspect` and `--inspect-port`):
+The debugger flags live on `pyxle dev` (and `pyxle studio`, which accepts
+`--inspect` and `--inspect-port`):
 
 ```bash
 pyxle dev --inspect
@@ -5211,13 +5227,16 @@ pyxle dev --inspect
 | `--inspect-port` | `5678` | Port for the debug server. When it's busy, Pyxle falls back to an ephemeral port and records the actual endpoint in the discovery file, so editor attach flows keep working. |
 | `--inspect-wait` / `--no-inspect-wait` | `false` | With `--inspect`: block startup until a debugger attaches — for breakpoints in code that runs during boot. |
 
-Only the dev-server process is debugged: the debugger environment is never injected into subprocesses (Vite, SSR workers, or anything a loader shells out to).
+Only the dev-server process is debugged: the debugger environment is never
+injected into subprocesses (Vite, SSR workers, or anything a loader shells out to).
 
 ---
 
 ## Attaching from any DAP client
 
-debugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a requirement. From neovim (`nvim-dap`), Emacs (`dape`), or any other DAP client, attach to the endpoint `--inspect` printed — the equivalent of:
+debugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a
+requirement. From neovim (`nvim-dap`), Emacs (`dape`), or any other DAP client,
+attach to the endpoint `--inspect` printed — the equivalent of:
 
 ```json
 {
@@ -5227,19 +5246,27 @@ debugpy speaks the Debug Adapter Protocol, so VS Code is a convenience, not a re
 }
 ```
 
-Set breakpoints in `.pyxl` files by their real path. Because the server's code objects already carry `.pyxl` filenames, no path mappings or source translations are needed — stack frames, stepping, and `evaluate` in a paused loader all just work.
+Set breakpoints in `.pyxl` files by their real path. Because the server's code
+objects already carry `.pyxl` filenames, no path mappings or source translations
+are needed — stack frames, stepping, and `evaluate` in a paused loader all just
+work.
 
 ---
 
-## Tracebacks point at .pyxl now
+## Tracebacks point at .pyxl
 
-The same line mapping improves life with no debugger attached at all: in development, a Python traceback from a loader or action names your `.pyxl` file and line — not a compiled module under `.pyxle-build/`. The terminal, the browser error overlay, and your logs all agree on where the error actually is.
+The same line mapping improves life with no debugger attached at all: in
+development, a Python traceback from a loader or action names your `.pyxl` file
+and line — not a compiled module under `.pyxle-build/`. The terminal, the browser
+error overlay, and your logs all agree on where the error actually is.
 
 ---
 
 ## The discovery file
 
-While running, the dev server writes `.pyxle-build/dev-server.json` describing itself, and removes it on shutdown. This is what editor tooling (like the VS Code extension's F5 flow and "Open Studio") reads instead of guessing ports:
+While running, the dev server writes `.pyxle-build/dev-server.json` describing
+itself, and removes it on shutdown. This is what editor tooling (the extension's
+F5 flow and "Open Studio") reads instead of guessing ports:
 
 | Key | Type | Meaning |
 |-----|------|---------|
@@ -5257,30 +5284,97 @@ The file is written atomically, and a failed write never takes down the server.
 
 ---
 
-## Caveats
+## Reading the compiled output
+
+Pyxle compiles each `.pyxl` into a Python module and a JavaScript module under
+the build directory (`.pyxle-build/` in dev, `dist/` for a production build).
+Reading them demystifies "where did my code go":
+
+- `.pyxle-build/server/pages/…​.py` — the **Python** half: your `@server` /
+  `@action` functions with the runtime imports the compiler injected at the top
+  (`from pyxle.runtime import server`, etc.).
+- `.pyxle-build/client/…​` — the **JavaScript** half: your component, ready for
+  Vite.
+
+In development you rarely need this, because tracebacks and breakpoints already
+point at your `.pyxl`. A traceback from a **production build** points at the
+compiled `.py`; the compiler preserves your code verbatim below the injected
+header, so mapping back to your `.pyxl` is a small, constant offset. The build
+directory is disposable — delete it and the next `pyxle dev`/`build` regenerates it.
+
+---
 
-Worth knowing before you rely on it:
+## Static checks
 
-- **A paused breakpoint pauses the whole server.** `pyxle dev` is a single process, so while you sit at a breakpoint every in-flight request waits. That's the right trade-off for development — and one reason production never hosts a debugger.
-- **`justMyCode` defaults to `true`.** Stepping stays inside your own code; set it to `false` in the launch configuration to step into Pyxle's internals.
-- **React debugging happens in the browser, not the SSR worker.** Your component renders first in the Node SSR process, but the debugger doesn't attach there — it's the same code with the same source maps in the browser, which is where you debug it. (Server-render `console.log` output still prints to the `pyxle dev` terminal — see [Debugging](https://pyxle.dev/docs/guides/debugging.md#debugging-rendering-the-nodessr-side).)
-- **Production is untouched.** `pyxle serve` never remaps line numbers and never hosts debugpy, regardless of flags or config.
-- **debugpy ships with the framework** — `--inspect` works on a default install, no extra needed.
+Two commands catch problems before you run the page:
+
+- **`pyxle check`** — validates `.pyxl` syntax, Python semantics, and JSX. Note
+  that a green check does not prove a page *renders*: a component reading a loader
+  key that doesn't exist is a runtime error, not a static one.
+- **`pyxle typecheck`** — runs TypeScript over your compiled JSX when you've opted
+  into TypeScript (see the [TypeScript guide](https://pyxle.dev/docs/guides/typescript.md)).
+
+---
+
+## Caveats
+
+Worth knowing before you rely on breakpoint debugging:
+
+- **A paused breakpoint pauses the whole server.** `pyxle dev` is a single
+  process, so while you sit at a breakpoint every in-flight request waits. That's
+  the right trade-off for development — and one reason production never hosts a
+  debugger.
+- **`justMyCode` defaults to `true`.** Stepping stays inside your own code; set it
+  to `false` in the launch configuration to step into Pyxle's internals.
+- **React debugging happens in the browser, not the SSR worker.** Your component
+  renders first in the Node SSR process, but the debugger doesn't attach there —
+  it's the same code with the same source maps in the browser, which is where you
+  debug it. Server-render `console.log` output still prints to the `pyxle dev`
+  terminal (see [the SSR side](#debugging-rendering-the-nodessr-side)).
+- **Production is untouched.** `pyxle serve` never remaps line numbers and never
+  hosts debugpy, regardless of flags or config.
 
 ---
 
 ## Troubleshooting
 
-**"No module named pyxle" when you press F5.** VS Code has a Python interpreter selected that doesn't have pyxle installed — a common split when pyxle lives in one environment (a virtualenv, pyenv, or system Python) while VS Code points at another. The launch runs `python -m pyxle dev` under the *selected* interpreter, so it has to be the one where `pyxle` is installed. The extension checks this before launching and, when it doesn't match, offers a **Select Interpreter** button; you can also run **Python: Select Interpreter** from the command palette and pick the environment your terminal's `pyxle` command uses (`which pyxle` / `where pyxle` shows it). This is the same interpreter selection every Python project needs — nothing pyxle-specific.
+**"No module named pyxle" when you press F5.** VS Code has a Python interpreter
+selected that doesn't have pyxle installed — a common split when pyxle lives in
+one environment (a virtualenv, pyenv, or system Python) while VS Code points at
+another. The launch runs `python -m pyxle dev` under the *selected* interpreter,
+so it has to be the one where `pyxle` is installed. The extension checks this
+before launching and offers a **Select Interpreter** button; you can also run
+**Python: Select Interpreter** from the command palette and pick the environment
+your terminal's `pyxle` command uses (`which pyxle` / `where pyxle` shows it).
+
+**"No module named pyxle.\_\_main\_\_", or the debugger says to upgrade.** The
+selected interpreter has pyxle, but a version older than 0.8.0. Run
+`pip install --upgrade pyxle-framework` in that environment.
 
 ---
 
-## See also
+## Common symptoms
 
-- [Debugging](https://pyxle.dev/docs/guides/debugging.md) — the wider guide: reading errors, `pdb`, the SSR side, common symptoms
+| Symptom | Likely cause | Where to look |
+|---------|--------------|---------------|
+| Blank page, overlay shows a Python traceback | Loader/action raised | `pyxle dev` terminal; set a breakpoint in the loader |
+| `window is not defined` | Browser global at render scope | The named `.pyxl`; use `useEffect`/`<ClientOnly>` |
+| `'State' object has no attribute 'db'` | Missing plugin | `plugins` in `pyxle.config.json` |
+| Component data is `undefined` | Loader key ≠ component prop | Compare the loader's return dict to the component's `data` usage |
+| Change didn't take effect | Editing built output, or a stale build | Edit the `.pyxl` source, not `.pyxle-build/` |
+| Works in dev, fails in prod | Debug-only behavior / missing env | Server log (prod hides detail from the response) |
+| Breakpoint never binds | Wrong interpreter, or framework older than 0.8.0 | See [Troubleshooting](#troubleshooting) |
+
+---
+
+## Next steps
+
+- [Editor setup](https://pyxle.dev/docs/guides/editor-setup.md) — installing the extension and language server, and everything else it does
 - [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md) — the dev dashboard; `pyxle studio --inspect` runs both
+- [Error Handling](https://pyxle.dev/docs/guides/error-handling.md) — `LoaderError`, error boundaries, 404s
+- [Testing](https://pyxle.dev/docs/guides/testing.md) — unit-test loaders and actions
+- [Client Components](https://pyxle.dev/docs/guides/client-components.md) — browser-only code and `<ClientOnly>`
 - [CLI reference → `pyxle dev`](https://pyxle.dev/docs/reference/cli.md#pyxle-dev) — every dev-server flag
-- [Editor setup](https://pyxle.dev/docs/guides/editor-setup.md) — installing the VS Code extension and language server
 
 ---
 
@@ -5380,7 +5474,7 @@ The `/__pyxle` URL prefix is reserved for framework endpoints — Studio lives u
 
 ## See also
 
-- [Debugging `.pyxl` files](https://pyxle.dev/docs/guides/debugging-pyxl.md) — breakpoints in `.pyxl` source; `pyxle studio --inspect` combines both tools
+- [Debugging](https://pyxle.dev/docs/guides/debugging.md) — breakpoints in `.pyxl` source; `pyxle studio --inspect` combines both tools
 - [Observability](https://pyxle.dev/docs/guides/observability.md) — the metrics registry Studio reads, and production-grade exporters
 - [CLI reference → `pyxle studio`](https://pyxle.dev/docs/reference/cli.md#pyxle-studio) — every flag
 - [Configuration reference → Studio](https://pyxle.dev/docs/reference/configuration.md#studio) — the config block
@@ -6700,7 +6794,7 @@ which earlier framework versions don't provide. Python-side breakpoints
 also require the Python extension (`ms-python.python`); the debugger
 offers to install it if it's missing.
 
-Full walkthrough: [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md).
+Full walkthrough: [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging.md).
 
 ### Open Studio
 
@@ -8366,7 +8460,7 @@ pyxle dev [directory] [options]
 | `--print-config` / `--no-print-config` | `false` | Print merged configuration before starting |
 | `--tailwind` / `--no-tailwind` | `true` | Auto-start the **legacy** standalone Tailwind v3 CLI watcher when a hand-written `tailwind.config.*` is present. Tailwind **v4** projects (the scaffold default when you opt into Tailwind) run through the `@tailwindcss/vite` plugin and ignore this flag. |
 | `--dashboard` / `--no-dashboard` | `false` | Periodically print a live [observability](https://pyxle.dev/docs/guides/observability.md#dev-dashboard) panel (request/SSR metrics) to the terminal |
-| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server (bound to `127.0.0.1`) so VS Code or any DAP client can set breakpoints directly in `.pyxl` files — see [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md). debugpy ships with the framework. |
+| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server (bound to `127.0.0.1`) so VS Code or any DAP client can set breakpoints directly in `.pyxl` files — see [Debugging](https://pyxle.dev/docs/guides/debugging.md). debugpy ships with the framework. |
 | `--inspect-port` | `5678` | Port for the debug server (with `--inspect`). Falls back to an ephemeral port when busy; the actual endpoint is recorded in `.pyxle-build/dev-server.json`. |
 | `--inspect-wait` / `--no-inspect-wait` | `false` | With `--inspect`: wait for a debugger to attach before starting the server — for breakpoints in code that runs during boot. |
 | `--verbose` / `-v` | `false` | Restore full output: the raw Vite log firehose, debug-level internals, and `DEBUG` server logs in the browser console. Equivalent to the global `pyxle -v dev`. |
@@ -8430,7 +8524,7 @@ pyxle studio [directory] [options]
 | `--config` | -- | Path to `pyxle.config.json` |
 | `--tailwind` / `--no-tailwind` | `true` | Auto-start the legacy Tailwind v3 watcher when a hand-written `tailwind.config.*` is present (same behavior as `pyxle dev`) |
 | `--open` / `--no-open` | `true` | Open the Studio dashboard in the system browser once the server is ready |
-| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server for `.pyxl` breakpoint debugging — see [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md) |
+| `--inspect` / `--no-inspect` | `false` | Host a debugpy debug server for `.pyxl` breakpoint debugging — see [Debugging](https://pyxle.dev/docs/guides/debugging.md) |
 | `--inspect-port` | `5678` | Port for the debug server (with `--inspect`; falls back to an ephemeral port when busy) |
 | `--verbose` / `-v` | `false` | Restore full output (raw Vite logs, debug internals). Equivalent to `pyxle -v studio`. |
 
@@ -17962,9 +18056,9 @@ Release notes for Pyxle. While we're in beta (`0.x`), minor versions may include
 
 - **Pyxle Studio — a dashboard built into `pyxle dev`.** Served at `/__pyxle/studio`: every route with its loader, actions, cache posture, and boundaries; an interactive tester (loaders run in-process, actions go through their real endpoint — CSRF, validation, and auth hooks included); a live request feed; latency metrics; the effective config (secrets redacted); and in-browser `pyxle check`. Dev-only by construction, with a `Host`-header allowlist. [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md).
 - **New `pyxle studio` command.** Runs the dev server and opens the browser on the dashboard, enabling it for that run even when the config opts out. [CLI](https://pyxle.dev/docs/reference/cli.md#pyxle-studio).
-- **Breakpoint debugging directly in `.pyxl` files.** Set a breakpoint on a line inside a `@server` loader *and* on a line inside the JSX below it — both bind. Compiled server modules are remapped to their `.pyxl` sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md).
-- **One-key debugging from VS Code.** Pyxle Language Tools 0.3.0 contributes a `pyxle` debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate "Debug Pyxle app (React browser)" configuration debugs the React side in a standalone browser session. Plus a "Pyxle: Open Studio" command. [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md#quick-start-vs-code).
-- **`pyxle dev --inspect` for attach-style debugging.** Hosts a debugpy server bound to `127.0.0.1` so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes `.pyxle-build/dev-server.json` (ports, debugpy endpoint) for editor tooling and removes it on shutdown. [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md).
+- **Breakpoint debugging directly in `.pyxl` files.** Set a breakpoint on a line inside a `@server` loader *and* on a line inside the JSX below it — both bind. Compiled server modules are remapped to their `.pyxl` sources, so the Python debugger binds natively; dev source maps chain through Vite so the React half binds in the browser. debugpy ships with the framework — nothing extra to install. [Debugging](https://pyxle.dev/docs/guides/debugging.md).
+- **One-key debugging from VS Code.** Pyxle Language Tools 0.3.0 contributes a `pyxle` debug type: press F5 to run your dev server under the debugger — one clean session with a real Stop button that tears the whole server down — and open your app. A separate "Debug Pyxle app (React browser)" configuration debugs the React side in a standalone browser session. Plus a "Pyxle: Open Studio" command. Install it with `code --install-extension pyxle.pyxle-language-tools`. [Debugging](https://pyxle.dev/docs/guides/debugging.md#quick-start-breakpoints-in-a-pyxl-file).
+- **`pyxle dev --inspect` for attach-style debugging.** Hosts a debugpy server bound to `127.0.0.1` so any DAP client — or a remote VS Code — can attach to a running dev server. The server writes `.pyxle-build/dev-server.json` (ports, debugpy endpoint) for editor tooling and removes it on shutdown. [Debugging](https://pyxle.dev/docs/guides/debugging.md).
 - **Dev tracebacks now point at `.pyxl` sources.** A loader/action error names your `.pyxl` file and line instead of the compiled module under `.pyxle-build/`. [Debugging](https://pyxle.dev/docs/guides/debugging.md).
 - **Breaking: `/__pyxle` is now a reserved URL namespace.** The dev server's Vite asset proxy never forwards paths under it, so an app route under `/__pyxle` no longer resolves in `pyxle dev` (it still serves in production, where the namespace is unused). Move any such route before upgrading. [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md#the-reserved-__pyxle-namespace).
 - **Fixed on Windows: `NODE_PATH` is built with the platform delimiter.** A project that already set `NODE_PATH` got a `:`-joined value, which Node cannot parse on Windows, so neither entry resolved.
diff --git a/public/llms.txt b/public/llms.txt
index 5c08cf1..5273109 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -36,7 +36,6 @@
 - [Error Handling](https://pyxle.dev/docs/guides/error-handling.md): Pyxle provides structured error handling through error exceptions, error boundaries, and not-found pages.
 - [Testing](https://pyxle.dev/docs/guides/testing.md): Pyxle apps are mostly plain Python — your `@server` loaders and `@action` handlers are ordinary `async` functions, and your business logic is whatever Python you write. That means you can test with th
 - [Debugging](https://pyxle.dev/docs/guides/debugging.md): A Pyxle app has two runtimes: **Python** (your `@server` loaders, `@action` handlers, and the request pipeline) and **Node.js** (the SSR worker that renders your React components to HTML). Knowing whi
-- [Debugging .pyxl files](https://pyxle.dev/docs/guides/debugging-pyxl.md): Set a breakpoint directly in your `.pyxl` source — on a line inside a `@server` loader *and* on a line inside the JSX below it — and both bind. `pyxle dev --inspect` exposes the Python half to any deb
 - [Pyxle Studio](https://pyxle.dev/docs/guides/studio.md): Pyxle Studio is the dashboard built into `pyxle dev` — one local page that shows everything the development server knows about your app: every route with its loader and actions, an interactive tester
 - [Client Components](https://pyxle.dev/docs/guides/client-components.md): Pyxle provides built-in React components and hooks importable from `pyxle/client`.
 - [Security](https://pyxle.dev/docs/guides/security.md): Pyxle includes CSRF protection, CORS support, and HEAD element sanitisation out of the box.
diff --git a/public/sitemap.xml b/public/sitemap.xml
index 195da3d..51673e0 100644
--- a/public/sitemap.xml
+++ b/public/sitemap.xml
@@ -33,7 +33,6 @@
   <url><loc>https://pyxle.dev/docs/guides/error-handling</loc><priority>0.7</priority></url>
   <url><loc>https://pyxle.dev/docs/guides/testing</loc><priority>0.7</priority></url>
   <url><loc>https://pyxle.dev/docs/guides/debugging</loc><priority>0.7</priority></url>
-  <url><loc>https://pyxle.dev/docs/guides/debugging-pyxl</loc><priority>0.7</priority></url>
   <url><loc>https://pyxle.dev/docs/guides/studio</loc><priority>0.7</priority></url>
   <url><loc>https://pyxle.dev/docs/guides/client-components</loc><priority>0.7</priority></url>
   <url><loc>https://pyxle.dev/docs/guides/security</loc><priority>0.7</priority></url>
diff --git a/scripts/build-docs.mjs b/scripts/build-docs.mjs
index cb28a60..c7797c9 100644
--- a/scripts/build-docs.mjs
+++ b/scripts/build-docs.mjs
@@ -88,7 +88,6 @@ const NAV_STRUCTURE = [
       { file: "guides/error-handling.md", slug: "error-handling" },
       { file: "guides/testing.md", slug: "testing" },
       { file: "guides/debugging.md", slug: "debugging" },
-      { file: "guides/debugging-pyxl.md", slug: "debugging-pyxl" },
       { file: "guides/studio.md", slug: "studio" },
       { file: "guides/client-components.md", slug: "client-components" },
       { file: "guides/security.md", slug: "security" },
@@ -194,8 +193,7 @@ const SEARCH_KEYWORDS = {
   "guides/api-routes": ["api", "rest", "json api", "endpoint", "websocket", "starlette"],
   "guides/background-tasks": ["background", "background tasks", "tasks", "queue", "async", "fire and forget", "deferred", "post-response", "celery", "arq", "dramatiq", "job queue", "enqueue", "request.state.background", "send email", "webhook"],
   "guides/testing": ["test", "testing", "tests", "pytest", "unit test", "unit testing", "end-to-end", "e2e", "test client", "pyxle.testing", "load_loader", "load_page", "test a loader", "test an action", "httpx", "mock request", "fake request", "PyxleTestClient"],
-  "guides/debugging": ["debug", "debugging", "pdb", "breakpoint", "traceback", "error overlay", "server logs", "console.log", "inspect", "node inspector", "ssr error", "compiled output", ".pyxle-build", "window is not defined", "stack trace", "logging"],
-  "guides/debugging-pyxl": ["debugger", "breakpoints", "breakpoint", "debugpy", "vs code", "vscode", "step through", "step debugging", "dap", "--inspect", "inspect", "f5", "attach", "launch.json", "source maps", "js-debug", "dev-server.json", "pause", "debug extra"],
+  "guides/debugging": ["debug", "debugging", "debugger", "pdb", "breakpoint", "breakpoints", "debugpy", "traceback", "error overlay", "server logs", "console.log", "inspect", "--inspect", "node inspector", "ssr error", "compiled output", ".pyxle-build", "window is not defined", "stack trace", "logging", "vs code", "vscode", "extension", "install extension", "step through", "step debugging", "dap", "f5", "attach", "launch.json", "source maps", "js-debug", "dev-server.json", "pause"],
   "guides/studio": ["studio", "pyxle studio", "dashboard", "devtools", "dev tools", "route tester", "tester", "loader tester", "action tester", "inspect", "request feed", "live requests", "routes panel", "__pyxle", "allowedhosts", "dns rebinding"],
   "guides/middleware": ["middleware", "request hook", "auth guard"],
   "guides/plugins": ["plugin", "plugins", "installed apps", "extensions", "packages"],