pyweb-stack 0.6.1__tar.gz → 0.6.2__tar.gz

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/CHANGELOG.md

@@ -6,6 +6,65 @@ project uses [semantic versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [0.6.2]
+
+The dev loop. Saves update the open page in place with every page and
+component keeping its state, any element opens its own line in your
+editor, error pages fix themselves with AI (your assistant's model through
+MCP, or your own key), a timeline steps back through every change, and
+`pyweb dev --share` gives someone a link to try what you're building. All
+of it lives in `pyweb dev`: production output is unchanged and there is
+nothing to change in your apps. See [The dev loop](docs/35-dev-loop.md).
+
+### Added
+- **Hot reload without a page load.** A save swaps the page in place
+  through client navigation: no reload, no flash. Page variables,
+  component variables (each instance keeps its own), form fields, scroll,
+  focus and the selection stay. A stylesheet-only save swaps just that
+  stylesheet. When the page changed too much to swap, it reloads with the
+  same state, also after a compile error is fixed.
+- **Click to source.** Hold Alt to see where any element comes from;
+  Alt-click opens that line in your editor (`PYWEB_EDITOR`, else VS Code,
+  Cursor, Windsurf, Zed or Sublime Text, else a `vscode://` link) and
+  shows the **inspector**: the components around it with their live
+  variables, which you can edit.
+- **Fix with AI and Edit with AI.** Compile error pages and dev 500 pages
+  have Fix with AI; Alt+Shift-click any element to ask for a change. The
+  answer is a compiled diff of one app file: Apply writes it (refused if
+  the file changed since) and Undo puts it back (`.pyweb/history/`). It is
+  answered by the assistant connected through `pyweb mcp` when its app
+  supports MCP sampling, else `ANTHROPIC_API_KEY` or
+  `OPENAI_API_KEY`/`OPENAI_BASE_URL`, else the page offers the prompt to
+  copy. Credentials in what's sent are replaced by placeholders and put
+  back in the answer.
+- **Time-travel timeline.** The toolbar's Timeline tab records every change
+  to the page's variables with its cause (a click, typing, a server call);
+  a slider steps back through them with the page paused, and Resume
+  returns to now.
+- **`pyweb dev --share`**: a temporary public link (cloudflared, else
+  localhost.run) with a QR code. The link's token sets a cookie that every
+  request through the tunnel needs; guests get the app and hot reload, not
+  your tools.
+- **A better first five minutes.** `pyweb new` with no name asks for the
+  name, a starter and a colour preset (`--theme` without asking); `pyweb
+  dev` opens the browser, prints the network URL with a QR code for a phone
+  with `--host 0.0.0.0`, and shows a one-time Welcome panel with what to
+  try and how to connect your assistant.
+- **A faster first start.** Parse results and compiled code are cached on
+  disk (`~/.cache/pyweb`; `PYWEB_CACHE=0` turns it off): loading the saas
+  example in a fresh process went from about 340 to 210 ms.
+  `pyweb.bench --system` reports `cold_dev_ms`.
+- MCP: the `pyweb_assist_requests` tool and the `fix_errors` prompt;
+  `pyweb mcp` answers the page's AI requests through sampling.
+
+### Changed
+- `pyweb dev`'s toolbar and its `/__pyweb/dev/` endpoints answer only the
+  person running it: a request from this machine to a loopback address.
+  Visitors from the network (`--host 0.0.0.0`) or a share link get hot
+  reload only.
+- The runtime is 25 bytes bigger (gzip) for the dev hooks; nothing runs
+  in production.
+
 ## [0.6.1]
 
 Better error messages, `pyweb doctor`, a `pyweb dev` that keeps your place

{pyweb_stack-0.6.1/pyweb_stack.egg-info → pyweb_stack-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyweb-stack
-Version: 0.6.1
+Version: 0.6.2
 Summary: Full-stack web apps in one Python file: server-rendered pages, reactive browser UI, typed RPC.
 Author-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
 Maintainer-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
@@ -400,6 +400,17 @@ develop a toolbar on every page shows each request's queries and flags
 N+1 loops. [Scaling & deploying →](docs/25-scaling.md) ·
 [Logs, metrics & tracing →](docs/26-observability.md)
 
+### A dev loop that keeps up
+
+Save, and the open page changes in place: no reload, and every page and
+component keeps its state. Hold Alt and click any element to open its
+line in your editor; Alt+Shift-click to change it with AI, and error
+pages have **Fix with AI** (your assistant's model through MCP, or your
+own API key), with a diff to apply and Undo. The toolbar's timeline
+steps back through every change and what caused it, and
+`pyweb dev --share` gives someone a link to try what you're building.
+[The dev loop →](docs/35-dev-loop.md)
+
 ### Small, fast and boring to run
 
 - **Every page is server-rendered**: complete HTML on first paint, then
@@ -442,7 +453,7 @@ it runs the real PyWeb, server functions included, in your browser.
 pip install pyweb-stack
 pyweb new myapp --template saas      # saas | desktop | blank | counter | todo | blog | auth | chat | ai-chat
 cd myapp
-pyweb dev app.pyweb                  # edit app.pyweb; the page reloads on save
+pyweb dev app.pyweb                  # saves update the open page in place, state kept
 ```
 
 Then:
@@ -478,7 +489,7 @@ The [architecture overview](ARCHITECTURE.md) goes through each stage.
 
 ## Build it with AI
 
-PyWeb ships an MCP server with 30 tools, so AI assistants can do what
+PyWeb ships an MCP server with 31 tools, so AI assistants can do what
 you'd do: scaffold an app, search the docs, check each edit (errors come
 back as line numbers with fix hints), build with the UI kit and a theme,
 render pages and call server functions as any signed-in member, look at
@@ -566,7 +577,7 @@ Upgrade with `pip install -U pyweb-stack`.
 
 | Version | Highlights |
 |---|---|
-| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests |
+| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests; 0.6.2: the dev loop (hot reload in place with component state, Alt-click to source, Fix/Edit with AI, a time-travel timeline, `pyweb dev --share`, a guided `pyweb new`) |
 | 0.5 | Models with migrations, forms, auth kit with passkeys, OAuth and an admin, row-level live updates over WebSockets on PyWeb's own server, durable jobs and schedules, `pyweb deploy` for docker, compose, k8s, fly, render and railway, logs, metrics, tracing and a dev toolbar, data-aware editor and MCP tools, the `saas` template, `pyweb upgrade` |
 | 0.4 | npm packages without Node, layouts and client-side navigation, streaming server functions and `<Markdown>` for AI apps, live queries, page head tags, `.pyweb` error pages; 0.4.1: richer MCP tools; 0.4.2: VS Code run, new-app and MCP commands; 0.4.3: fixes, security hardening, gzip and caching; 0.4.4: key rotation, session revocation, typed arguments, Redis-shared limits, `check --production` |
 | 0.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/README.md

@@ -326,6 +326,17 @@ develop a toolbar on every page shows each request's queries and flags
 N+1 loops. [Scaling & deploying →](docs/25-scaling.md) ·
 [Logs, metrics & tracing →](docs/26-observability.md)
 
+### A dev loop that keeps up
+
+Save, and the open page changes in place: no reload, and every page and
+component keeps its state. Hold Alt and click any element to open its
+line in your editor; Alt+Shift-click to change it with AI, and error
+pages have **Fix with AI** (your assistant's model through MCP, or your
+own API key), with a diff to apply and Undo. The toolbar's timeline
+steps back through every change and what caused it, and
+`pyweb dev --share` gives someone a link to try what you're building.
+[The dev loop →](docs/35-dev-loop.md)
+
 ### Small, fast and boring to run
 
 - **Every page is server-rendered**: complete HTML on first paint, then
@@ -368,7 +379,7 @@ it runs the real PyWeb, server functions included, in your browser.
 pip install pyweb-stack
 pyweb new myapp --template saas      # saas | desktop | blank | counter | todo | blog | auth | chat | ai-chat
 cd myapp
-pyweb dev app.pyweb                  # edit app.pyweb; the page reloads on save
+pyweb dev app.pyweb                  # saves update the open page in place, state kept
 ```
 
 Then:
@@ -404,7 +415,7 @@ The [architecture overview](ARCHITECTURE.md) goes through each stage.
 
 ## Build it with AI
 
-PyWeb ships an MCP server with 30 tools, so AI assistants can do what
+PyWeb ships an MCP server with 31 tools, so AI assistants can do what
 you'd do: scaffold an app, search the docs, check each edit (errors come
 back as line numbers with fix hints), build with the UI kit and a theme,
 render pages and call server functions as any signed-in member, look at
@@ -492,7 +503,7 @@ Upgrade with `pip install -U pyweb-stack`.
 
 | Version | Highlights |
 |---|---|
-| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests |
+| 0.6 | Teams with roles, invitations and tenant-scoped Models (Postgres row-level security), API tokens and OpenAPI, webhooks, installable apps with Web Push, desktop windows and installers, a UI kit with themes and motion, Trusted Types, encrypted fields and a threat model, about 2.5× faster serving, Python 3.15 and free-threaded builds, a much richer MCP server; 0.6.1: error messages with code frames and suggestions, `pyweb doctor`, dev reloads that keep page state, 4× faster reloads and tests; 0.6.2: the dev loop (hot reload in place with component state, Alt-click to source, Fix/Edit with AI, a time-travel timeline, `pyweb dev --share`, a guided `pyweb new`) |
 | 0.5 | Models with migrations, forms, auth kit with passkeys, OAuth and an admin, row-level live updates over WebSockets on PyWeb's own server, durable jobs and schedules, `pyweb deploy` for docker, compose, k8s, fly, render and railway, logs, metrics, tracing and a dev toolbar, data-aware editor and MCP tools, the `saas` template, `pyweb upgrade` |
 | 0.4 | npm packages without Node, layouts and client-side navigation, streaming server functions and `<Markdown>` for AI apps, live queries, page head tags, `.pyweb` error pages; 0.4.1: richer MCP tools; 0.4.2: VS Code run, new-app and MCP commands; 0.4.3: fixes, security hardening, gzip and caching; 0.4.4: key rotation, session revocation, typed arguments, Redis-shared limits, `check --production` |
 | 0.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/THREAT_MODEL.md

@@ -177,6 +177,21 @@ websites in the user's browser.
 | T | An assistant's "read-only" SQL changing data | One statement, write keywords refused (even in a CTE), a read-only transaction that is rolled back; secrets redacted | `test_dx_v5.py::test_mcp_data_tools` |
 | T | Malformed tool arguments reaching app code | Arguments are checked against each tool's schema before it runs | `test_mcp_v6.py::test_arguments_are_checked_before_the_tool_runs` |
 
+## 7d. The dev loop: sharing, AI help, open in editor
+
+`pyweb dev` only. Its tools change files, open programs and show request data, so they are for the
+person running it, on that machine: a request must come from a loopback address and name a loopback
+`Host` (a tunnel's or the LAN's requests don't), and writes must be same-origin.
+
+| | Threat | Mitigation | Proof |
+|---|---|---|---|
+| S | Someone who learns the `--share` address (or guesses the tunnel name) using the app | Every request through the tunnel needs a cookie (`HttpOnly`, `Secure`, `SameSite=Lax`) set by the printed link's random token; forged cookies are refused | `test_share.py::test_the_link_sets_a_cookie_and_nothing_else_gets_in`, `test_share.py::test_pyweb_dev_share_end_to_end` |
+| E/I | A share-link guest (or someone on the LAN) using the developer's tools: the toolbar's SQL and requests, the agent endpoints, AI fixes, opening files, saving the theme | Guests get the app and hot reload only; every `/__pyweb/dev/` endpoint but change polling answers 403 to them, and their pages carry no toolbar or tool scripts | `test_share.py::test_guests_get_the_app_and_hot_reload_only`, `test_share.py::test_you_still_get_everything_and_the_lan_gets_hot_reload`, `test_share.py::test_a_compile_error_page_for_guests_has_no_tools` |
+| T | A web page making "Fix with AI" or "Edit with AI" write to the app | Same-origin, loopback-only POSTs; the answer is compiled first, applied only on Apply, only to `.pyweb` files in the app, refused if the file changed since; the old version is kept for Undo | `test_assist.py::test_endpoints_refuse_other_sites_and_other_machines`, `test_assist.py::test_a_change_that_does_not_compile_is_refused`, `test_assist.py::test_apply_refuses_when_the_file_changed_since`, `test_assist.py::test_only_app_files_are_targets` |
+| I | Credentials in the app's source sent to a model | Known key formats and random-looking secret values are replaced by placeholders before sending and put back in the answer | `test_assist.py::test_secrets_are_replaced_before_sending_and_put_back`, `test_assist.py::test_the_connected_assistant_answers_through_mcp_sampling` |
+| E | Alt-click "open in editor" used to open arbitrary files or run commands | Only `.pyweb` files inside the app folder or the UI kit; the editor gets an argument list, never a shell; same-origin and loopback only | `test_devopen.py::test_only_app_and_kit_files_resolve`, `e2e/test_dev_inspect_browser.py::test_open_refuses_cross_site_and_outside_files` |
+| I | Dev-only markers or scripts in production pages | `data-pw-src` markers come from dev compiles only; the dev scripts are added by the dev server only | `test_devopen.py::test_other_builds_have_no_marks`, `test_trusted_types.py::test_dev_scripts_never_ship_in_built_pages` |
+
 ## 8. The release
 
 | | Threat | Mitigation | Proof |

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/docs/01-introduction.md

@@ -43,6 +43,10 @@ Around that core, PyWeb has what a product needs, in the same file:
   ([Installable apps](31-pwa-push.md), [Desktop apps](32-desktop.md))
 - **Webhooks and files**: signed webhooks in and out, and unused uploads
   cleaned up. ([Webhooks & files](33-webhooks-files.md))
+- **A dev loop that keeps up**: saves update the open page in place with
+  its state kept; Alt-click opens any element's source; Fix with AI and
+  Edit with AI; a time-travel timeline; `pyweb dev --share`.
+  ([The dev loop](35-dev-loop.md))
 - **Shipping**: `pyweb deploy` writes Docker, Compose, Kubernetes, Fly,
   Render or Railway files; logs, metrics and traces come built in.
   ([Scaling & deploying](25-scaling.md))

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/docs/02-quickstart.md

@@ -20,9 +20,14 @@ pip install "pyweb-stack[all]"     # optional: Postgres, MySQL, Redis, argon2, O
 ```bash
 pyweb new hello
 cd hello
-pyweb dev app.pyweb          # http://localhost:8000, reloads on save
+pyweb dev app.pyweb          # opens http://localhost:8000; saves update the page in place
 ```
 
+(`pyweb new` with no name asks for one, a starter and colours.) Save a
+change and the open page updates without losing its state; hold Alt and
+click anything to open its line in your editor. [The dev loop](35-dev-loop.md)
+has the rest: Fix with AI, time travel and sharing with `--share`.
+
 `pyweb new` writes `app.pyweb`, a starter test (`test_app.py`) and
 `AGENTS.md`/`CLAUDE.md` (instructions for AI coding agents). Add
 `--template saas` for a small product with teams, accounts, a database,
@@ -107,6 +112,7 @@ ships it. Then, depending on what you're building:
 - work that runs later or on a schedule: [Background jobs](24-jobs.md);
 - teams that share data: [Teams & organizations](30-teams.md);
 - components, a theme and animation: [UI kit & motion](34-ui-and-motion.md);
+- everything `pyweb dev` does for you: [The dev loop](35-dev-loop.md);
 - an app people install, or a desktop app: [Installable apps & push](31-pwa-push.md),
   [Desktop apps](32-desktop.md);
 - several pages with a shared header: [Layouts & navigation](19-layouts-navigation.md);

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/docs/14-cli.md

@@ -1,15 +1,21 @@
 # Command line
 
 ```text
-pyweb new NAME [--template T]        create NAME/ with app.pyweb, test_app.py, AGENTS.md, CLAUDE.md, static/;
+pyweb new [NAME] [--template T] [--theme PRESET]
+                                     create NAME/ with app.pyweb, test_app.py, AGENTS.md, CLAUDE.md, static/;
                                      T = blank | counter (default) | todo | blog | saas | auth | chat | ai-chat | desktop
-                                     (apps with a database also get migrations/0001_initial.py and a README)
-pyweb dev FILE [--port 8000] [--host 127.0.0.1] [--no-reload]
-                                     development server: recompile on save, live reload that keeps the
-                                     page's variables, form fields, scroll and focus (add ?fresh to
-                                     the URL to start over), error overlay,
-                                     the dev toolbar (requests, SQL, jobs, emails, theme and motion
-                                     editors), and background jobs in the same process; writes
+                                     (apps with a database also get migrations/0001_initial.py and a README);
+                                     PRESET = indigo | zinc | slate | rose | ocean | violet | emerald | amber
+                                     (written into App(theme=...)); with no NAME, in a terminal, it asks
+pyweb dev FILE [--port 8000] [--host 127.0.0.1] [--no-reload] [--no-open] [--share]
+                                     development server (see The dev loop): saves update the open page
+                                     in place, keeping page and component state (?fresh starts over);
+                                     Alt-click opens an element's line in your editor, Alt+Shift-click
+                                     changes it with AI, error pages have Fix with AI; the dev toolbar
+                                     (requests, SQL, jobs, emails, theme, motion, a time-travel timeline);
+                                     background jobs in the same process; opens the browser (not in CI,
+                                     over SSH or with --no-open); --host 0.0.0.0 prints the network URL
+                                     with a QR code; --share prints a temporary public link; writes
                                      .pyweb/dev.json so `pyweb mcp` can see its errors and logs
 pyweb check FILE [--production] [--strict]
                                      compile, security and accessibility checks; --production also checks

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/docs/16-limitations-roadmap.md

@@ -11,9 +11,9 @@ can decide up front whether they matter for your app.
 - **npm packages must ship ES modules.** CommonJS-only packages and
   packages built on Node.js modules can't run in the browser; see
   [npm packages](18-npm-packages.md).
-- **Dev reload keeps page variables, not component state.** After a save,
-  `pyweb dev` reloads the page with its variables, form fields, scroll
-  and focus as they were; state inside components starts over.
+- **Time travel moves the page's state only.** The dev timeline puts the
+  page's and components' variables back; data on the server isn't
+  rolled back.
 - **SQLite is for one machine.** Several processes on one host share it
   fine, but more than one server needs Postgres or MySQL;
   `pyweb check --production` and `pyweb deploy` say so.
@@ -36,7 +36,11 @@ can decide up front whether they matter for your app.
   faster serving, Python 3.15 and free-threaded builds, and a much richer
   MCP server. 0.6.1 added error messages with code frames and
   suggestions, `pyweb doctor`, dev reloads that keep page state, and 4×
-  faster reloads and tests.
+  faster reloads and tests. 0.6.2 made the [dev loop](35-dev-loop.md):
+  saves update the page in place with component state kept, Alt-click
+  opens any element's source, Fix with AI and Edit with AI, a
+  time-travel timeline, `pyweb dev --share`, a faster first start and a
+  guided `pyweb new`.
 - **0.5**: production apps. Models with relations and migrations, forms
   checked in the browser and on the server, an auth kit (passwords,
   passkeys, emailed links, OAuth, two-step sign-in, an admin), row-level
@@ -67,8 +71,8 @@ Planned, roughly in order. Nothing here is promised for a date.
 1. **1.0**: the API, RPC protocol and CLI frozen under semantic versioning,
    after 0.6 has been used in production for a while.
 2. **File uploads from the playground and the admin.**
-3. **Hot reload without a page reload** while developing (0.6.1 already
-   keeps the page's variables, fields, scroll and focus across reloads).
+3. **Fix with AI in the editor**, from the same proposals the dev page
+   shows (diff, apply, undo), through the VS Code extension.
 
 Ideas, bug reports and pull requests are welcome; see
 [CONTRIBUTING.md](https://github.com/MaanavKrishna/PyWeb/blob/main/CONTRIBUTING.md).

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/docs/17-ai-assistants.md

@@ -108,6 +108,7 @@ tool runs. Slow tools (tests, screenshots, profiling) report progress.
 | `pyweb_dev` | Whether `pyweb dev` is running for this app: its URL, whether the app compiles right now (with the error and traceback), its pages and recent 500 errors. |
 | `pyweb_doctor` | Project health, as `pyweb doctor`: each check with `status` (ok, warn, fail), `detail` and a `fix`; `production=true` adds the production settings. |
 | `pyweb_logs` | The dev server's log lines (warnings, errors with tracebacks, slow queries, job failures); `since` returns only newer ones. |
+| `pyweb_assist_requests` | What the developer asked for from the page (Fix with AI on an error page, Alt+Shift-click → Edit with AI) while no AI was set up to answer: the file, the error or the element's line, and the instruction. |
 
 When `pyweb dev` starts, it writes `.pyweb/dev.json` next to the app: its
 address and a random token, readable only by you (the folder has its own
@@ -149,6 +150,7 @@ Prompts are step-by-step workflows that name the tools to use:
 | `design_pass` | Kit components, a theme and motion, reviewed in light, dark and on a phone. |
 | `fix_failing_test` | Reproduce, find the cause in the app, fix, re-run. |
 | `debug_page` | Errors, logs, requests and a profile for one page. |
+| `fix_errors` | Check, fix and test in a loop until the app compiles cleanly and the tests pass; first does what was asked from the page. |
 
 ### What a session looks like
 
@@ -172,6 +174,24 @@ Prompts are step-by-step workflows that name the tools to use:
    click around, the assistant reads the error with `pyweb_dev` and
    `pyweb_logs` and fixes it.
 
+### Fix with AI from the page (sampling)
+
+`pyweb dev` puts a **Fix with AI** button on error pages, and
+Alt+Shift-click asks for a change to any element (see
+[The dev loop](35-dev-loop.md#fix-with-ai-and-edit-with-ai)). When your
+assistant's app supports MCP **sampling** (the client lets a server ask
+its model a question, after you approve), `pyweb mcp` answers those
+requests with your assistant's own model: it notices the client offers
+sampling when it connects, finds the running `pyweb dev` through
+`.pyweb/dev.json`, and hands each request over. The page shows the
+answer as a diff to apply or discard. This works over stdio (`pyweb
+mcp`); set `PYWEB_APP` when the app file isn't `app.pyweb` in the folder
+the assistant starts in.
+
+Assistants without sampling see the same requests with
+`pyweb_assist_requests` and can do them with their own file tools; the
+`fix_errors` prompt starts there.
+
 `pyweb_render`, `pyweb_call`, `pyweb_screenshot`, `pyweb_review`,
 `pyweb_profile`, `pyweb_webhook_send`, `pyweb_jobs` and `pyweb_test` run
 your app's code, as `pyweb dev` or `pytest` would; `pyweb_packages`

pyweb_stack-0.6.2/docs/35-dev-loop.md

@@ -0,0 +1,151 @@
+# The dev loop
+
+`pyweb dev app.pyweb` is where you spend your day, so it does a lot for
+you: saves show up in the open page without a reload, any element opens
+its own line in your editor, errors come with a "Fix with AI" button, you
+can step back through what the page did, and a link lets someone else
+try what you're building. Everything on this page exists only under
+`pyweb dev`: production builds, `pyweb serve` and `TestClient` are
+unchanged.
+
+## Your first run
+
+```bash
+pyweb new                 # in a terminal: asks for a name, a starter and colours
+cd my-app
+pyweb dev app.pyweb       # opens the browser
+```
+
+`pyweb new` with no name asks three questions: the folder name, a
+starter (each with a line saying what it is) and a colour preset, which
+it writes into `App(theme=Theme(...))`. `pyweb new shop --template todo
+--theme rose` does the same without asking.
+
+`pyweb dev` opens your browser (not in CI, over SSH, or with
+`--no-open`) and, the first time a project runs, shows a short Welcome
+panel: what to try, and the snippet that connects your AI assistant.
+**Got it** hides it for good (`PYWEB_WELCOME=0` turns it off).
+
+## Saves update the page in place
+
+Change some markup, a style or a function and save. The open page
+updates in about a tenth of a second, without a reload and without a
+flash:
+
+- **page and component state stays.** Every page variable and every
+  component's variables keep their values; two `<Counter />`s keep their
+  own counts. A variable you renamed, or whose type changed (a number
+  that is now a string), starts over.
+- **form fields, scroll position, focus and the text selection stay**,
+  for fields that have an `id` or a `name`.
+- **a stylesheet-only save** swaps that stylesheet and nothing else.
+
+When the page's structure changed too much to swap in place (a new
+layout, different npm packages), it reloads, and the same state comes
+back. After a compile error the browser shows the error; fix it, save,
+and you're back where you were, state included. Add `?fresh` to the URL
+to start over every time.
+
+The first start is fast too: parse results and compiled code are kept in
+`~/.cache/pyweb` (`PYWEB_CACHE_DIR` to move it, `PYWEB_CACHE=0` to turn
+it off), keyed by each file's contents and the PyWeb and Python versions.
+
+## Alt-click to open the source
+
+Hold **Alt** (Option on a Mac) and point at anything: it is outlined,
+with the components it sits in and its file and line. **Alt-click** it
+to open that line in your editor. It also opens the **inspector**: the
+chain of components around the element, each with its live variables.
+Type a new value (JSON: `3`, `"hi"`, `[1, 2]`) and the page follows.
+
+The editor is `$PYWEB_EDITOR` when you set it, a command with `{file}`
+and `{line}` in it:
+
+```bash
+export PYWEB_EDITOR='code -g {file}:{line}'        # VS Code
+export PYWEB_EDITOR='idea --line {line} {file}'    # JetBrains
+export PYWEB_EDITOR='nvim +{line} {file}'          # in a terminal editor, use a new window
+```
+
+Otherwise the first of VS Code (`code`), Cursor, Windsurf, Zed and
+Sublime Text found on your `PATH`; with none of them, the inspector shows
+a `vscode://` link. Elements that come from the UI kit open the line in
+your app that uses them.
+
+## Fix with AI, and Edit with AI
+
+When the app doesn't compile, or a page fails with an exception, the
+error page has a **Fix with AI** button. **Alt+Shift-click** any element
+to say what should change ("make this a card with a delete button").
+
+Either way you get a **diff** of one file in your app, already compiled:
+a change that doesn't compile is shown but can't be applied. **Apply**
+writes it (only if the file hasn't changed since), the page updates in
+place, and **Undo** puts the old version back (every replaced version is
+also kept in `.pyweb/history/`).
+
+Who answers, in this order:
+
+1. **Your assistant, through `pyweb mcp`.** If the assistant's app
+   supports MCP *sampling*, `pyweb mcp` hands the request to it: its own
+   model does the work, and the app asks you before each request.
+2. **An API key** in the environment `pyweb dev` runs in:
+   `ANTHROPIC_API_KEY`, or `OPENAI_API_KEY` / `OPENAI_BASE_URL` (any
+   OpenAI-compatible server, Ollama included), with `AI_MODEL` to choose
+   the model.
+3. **Nobody yet.** The page gives you the prompt to copy into any
+   assistant, and a connected assistant can pick the request up with the
+   `pyweb_assist_requests` tool (the `fix_errors` prompt starts there).
+
+What's sent is the file and the error (or your instruction). Credentials
+in them, in the formats `pyweb check` knows and random-looking values in
+secret-named variables, are replaced by placeholders before sending and
+put back in the answer.
+
+## Time travel
+
+The toolbar's **Timeline** tab (the ⚡ badge, bottom left) records every
+change to the page's variables with what caused it: a click on which
+button, typing in which field, Enter, a server function call. Each event
+is one step. Drag the slider, press **Step back** or click a step and
+every variable goes back to its value then; the page is paused while you
+look (clicks and typing are held back). **Resume** puts the latest values
+back. Only the page's own state moves: data on the server isn't rolled
+back. The last 500 changes are kept.
+
+## On your phone, and with someone else
+
+```bash
+pyweb dev app.pyweb --host 0.0.0.0     # prints the network URL and a QR code
+pyweb dev app.pyweb --share            # a temporary public link (and a QR code)
+```
+
+`--host 0.0.0.0` listens on your network: scan the QR code with a phone
+on the same Wi-Fi.
+
+`--share` starts a tunnel, with `cloudflared` when it's installed or
+`ssh` to localhost.run otherwise, and prints a link like
+`https://quiet-fox-12.trycloudflare.com/__pyweb/share?t=…`. Anyone with
+the link can use the app and sees your saves live. Nobody gets in with
+the address alone: the link's token sets a cookie, and every other
+request through the tunnel is refused. The link works until you stop
+`pyweb dev`.
+
+People on the network or coming through a share link get the app and
+hot reload, never your tools: no toolbar (it shows SQL and request
+data), inspector, AI help, editor opening or theme saving. Those
+answer only requests from your machine to `localhost`.
+
+## Security limits
+
+| Feature | Who can use it |
+|---|---|
+| Hot reload, the error page | Everyone who can open the page |
+| Toolbar, timeline, inspector, Alt-click, Fix/Edit with AI, theme saving, Welcome | You: a request from this machine, to a loopback address, from the page itself |
+| Files AI may change | `.pyweb` files inside the app folder; only after Apply; never if the file changed since |
+| Files Alt-click may open | `.pyweb` files in the app folder or in PyWeb's UI kit |
+| `--share` guests | The app, with the link's cookie; nothing under `/__pyweb/dev/` but change polling |
+| `pyweb mcp`'s view of the dev server | With the token in `.pyweb/dev.json` (readable by you only), from this machine |
+
+The [threat model](https://github.com/MaanavKrishna/PyWeb/blob/main/THREAT_MODEL.md) lists each of these with the tests
+that prove it.

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyweb-stack"
-version = "0.6.1"
+version = "0.6.2"
 description = "Full-stack web apps in one Python file: server-rendered pages, reactive browser UI, typed RPC."
 readme = "README.md"
 license = "MIT"

pyweb_stack-0.6.2/pyweb/_templates.py

@@ -0,0 +1,18 @@
+"""The `pyweb new` template names (kept apart so the CLI can list them without loading the MCP server)."""
+
+TEMPLATES = ("blank", "counter", "todo", "blog", "saas", "auth", "chat", "ai-chat", "desktop")
+
+# The colour presets `pyweb new --theme` offers (pyweb.ui.theme.PRESETS has their values; a test keeps the two in step).
+THEME_PRESETS = ("indigo", "zinc", "slate", "rose", "ocean", "violet", "emerald", "amber")
+
+DESCRIPTIONS = {
+    "blank": "one empty page",
+    "counter": "a page with a button: the smallest app with state",
+    "todo": "a list you add to and tick off, with the UI kit",
+    "blog": "pages with routes, a database and server functions",
+    "saas": "teams, sign-in, data, background jobs and an admin",
+    "auth": "accounts: sign up, sign in, passkeys",
+    "chat": "a live chat room (realtime)",
+    "ai-chat": "a streaming chat with an AI model",
+    "desktop": "a notes app in its own window",
+}

{pyweb_stack-0.6.1 → pyweb_stack-0.6.2}/pyweb/app_loader.py

@@ -51,6 +51,8 @@ def _module_code(source, filename, infos):
     import hashlib
     key = (filename, hashlib.sha256(source.encode()).hexdigest(), tuple(getattr(i, "name", "") for i in infos))
     code = _CODE.get(key)
+    if code is None:
+        code = _disk_code(key)
     if code is None:
         py_source, _ui = P.split_sources(source)
         tree = ast.parse(py_source, filename=filename)
@@ -60,9 +62,32 @@ def _module_code(source, filename, infos):
         if len(_CODE) > 256:
             _CODE.clear()
         _CODE[key] = code
+        _disk_code(key, code)
+    elif key not in _CODE:
+        _CODE[key] = code
     return code
 
 
+def _disk_code(key, code=None):
+    """Read (or with ``code``, write) a module's code object in the on-disk cache."""
+    import marshal
+
+    from .compiler import diskcache
+    if not diskcache.enabled():
+        return None
+    k = diskcache.key("code", key[0], key[1], *key[2])
+    if code is not None:
+        diskcache.put("code", k, marshal.dumps(code))
+        return code
+    data = diskcache.get("code", k)
+    if data is None:
+        return None
+    try:
+        return marshal.loads(data)
+    except Exception:  # noqa: BLE001 - a corrupt entry: compile again
+        return None
+
+
 def _kit_markup(path):
     """Whether a component file is kit markup (a component copied with ``pyweb ui add``)."""
     try:
@@ -75,7 +100,7 @@ def _kit_markup(path):
 
 class LoadedApp:
     def __init__(self, path=None, *, source=None, filename=None, asset_urls=None,
-                 stylesheets=None):
+                 stylesheets=None, dev=False):
         if source is None:
             with open(path, encoding="utf-8") as fh:
                 source = fh.read()
@@ -84,7 +109,7 @@ class LoadedApp:
         self.source = source
         self.asset_urls = dict(asset_urls or {})
         self.extra_stylesheets = list(stylesheets or [])
-        self.compiled = compile_source(source, filename=self.filename)
+        self.compiled = compile_source(source, filename=self.filename, dev=dev)
         self.ctx = self.compiled["context"]
         # Other .pyweb files the app imports run as real modules, registered
         # under their import name so `from widgets import Card` works.