pyweb-stack 0.2.0__tar.gz → 0.4.0__tar.gz

{pyweb_stack-0.2.0 → pyweb_stack-0.4.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 MaanavKrishna and Claude
+Copyright (c) 2026 MaanavKrishna
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{pyweb_stack-0.2.0 → pyweb_stack-0.4.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pyweb-stack
-Version: 0.2.0
+Version: 0.4.0
 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>, Claude <noreply@anthropic.com>
+Author-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
 Maintainer-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
 License: MIT
 Project-URL: Homepage, https://maanavkrishna.github.io/PyWeb/
@@ -64,6 +64,9 @@ functions, without a JavaScript toolchain.
 ![PyPI](https://img.shields.io/pypi/v/pyweb-stack)
 ![License](https://img.shields.io/badge/license-MIT-lightgrey)
 
+**[Try it in your browser](https://maanavkrishna.github.io/PyWeb/playground.html)**: the playground runs
+the real PyWeb, server functions included, on Python compiled to WebAssembly.
+
 ```pyweb
 from pyweb import App, server
 
@@ -120,11 +123,20 @@ pyweb dev app.pyweb        # http://localhost:8000
 - **Boundaries are checked.** Database handles, imports and secrets can't
   leak into browser code: it's a compile error with a line number.
   `pyweb inspect` explains where every name runs and why.
+- **Pages that keep up.** `live(db, "select ...")` keeps page data in
+  step with the database in every open window; `@server` functions that
+  `yield` stream to the browser (AI replies included, with a Stop
+  button that really stops).
+- **Real multi-page apps.** Shared layouts that keep their state, links
+  that load without a full reload, typed query parameters, per-page
+  titles and social tags, error pages written in `.pyweb`.
+- **npm without Node.** `pyweb add chart.js/auto` vendors a package for
+  browser code; no `node_modules`, no bundler.
 - **Stateless servers.** Signed-cookie sessions and plain HTTP RPC scale
   horizontally behind any load balancer. Deploy with `pyweb serve`,
   uvicorn/gunicorn (ASGI) or the generated Dockerfile.
 
-A typical interactive page ships under 1 KB of page code plus a ~10 KB
+A typical interactive page ships under 1 KB of page code plus a ~14 KB
 (gzip) runtime that's cached across pages. Pages without interactivity
 ship no JavaScript.
 
@@ -134,17 +146,17 @@ ship no JavaScript.
 small SaaS products and content sites with interactive parts, built by
 people who'd rather stay in Python.
 
-**Not a fit:** large client-heavy single-page apps that need the npm
-ecosystem (use React/Svelte/Vue), or running scientific Python in the
-browser (use Pyodide/PyScript). See the
+**Not a fit:** large client-heavy single-page apps built around a
+JavaScript component framework (use React/Svelte/Vue), or running
+scientific Python in the browser (use Pyodide/PyScript). See the
 [comparison](https://maanavkrishna.github.io/PyWeb/introduction.html)
 and [current limitations](docs/16-limitations-roadmap.md).
 
 ## Build it with AI
 
 PyWeb ships an MCP server so AI assistants can scaffold, check, inspect,
-render and test your app, with errors that come back as line numbers and
-fix hints:
+render, screenshot and test your app, with errors that come back as line
+numbers and fix hints:
 
 ```bash
 claude mcp add pyweb -- pyweb mcp          # Claude Code
@@ -165,10 +177,10 @@ See [AI assistants & MCP](docs/17-ai-assistants.md).
 | | |
 |---|---|
 | Start | [Introduction](docs/01-introduction.md) · [Quickstart](docs/02-quickstart.md) · [Tutorial](docs/03-tutorial.md) · [AI assistants & MCP](docs/17-ai-assistants.md) |
-| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) |
-| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Data](docs/09-data.md) · [Auth](docs/10-auth.md) |
+| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) · [npm packages](docs/18-npm-packages.md) |
+| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Layouts & navigation](docs/19-layouts-navigation.md) · [Data](docs/09-data.md) · [Live data](docs/21-live-data.md) · [Building AI apps](docs/20-ai-apps.md) · [Auth](docs/10-auth.md) |
 | Ship | [Testing](docs/11-testing.md) · [Deployment](docs/12-deployment.md) · [Security](docs/13-security.md) · [CLI](docs/14-cli.md) |
-| Reference | [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
+| Reference | [Recipe: wallets & web3](docs/22-recipe-web3.md) · [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
 
 The same docs are published at
 **[maanavkrishna.github.io/PyWeb](https://maanavkrishna.github.io/PyWeb/)**,
@@ -185,26 +197,46 @@ a real browser by the test suite.
 | [`todo`](examples/todo/app.pyweb) | components, list mutation, filters, keyed lists |
 | [`blog`](examples/blog/app.pyweb) | SQL database, server functions, route params, 404s, validation errors |
 | [`auth`](examples/auth/app.pyweb) | registration, password hashing, sessions, protected pages |
-| [`chat`](examples/chat/app.pyweb) | route params, shared server state, polling with `on_mount` |
+| [`chat`](examples/chat/app.pyweb) | route params, shared server state, live updates with `publish`/`subscribe` |
 | [`showcase`](examples/showcase/app.pyweb) | everything on one page, with a stylesheet |
+| [`site`](examples/site/app.pyweb) | a layout, client-side navigation, query parameters, page titles, a 404 page |
+| [`dashboard`](examples/dashboard/app.pyweb) | live queries and a Chart.js chart from npm, in every open window |
+| [`ai-chat`](examples/ai-chat/app.pyweb) | streaming AI replies with Stop and Markdown (Anthropic, OpenAI-compatible or a demo model) |
 
 ## Command line
 
 ```bash
-pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat)
+pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat|ai-chat)
+pyweb add chart.js/auto                          # an npm package for browser code (no Node.js)
 pyweb dev app.pyweb                              # dev server: live reload + error overlay
 pyweb inspect app.pyweb                          # where each name runs, and why
 pyweb check app.pyweb                            # compile + security checks for CI
 pyweb build app.pyweb --out dist --production    # self-contained, hashed, minified dist/
 pyweb serve dist                                 # production server (/healthz, CSP, graceful shutdown)
 pyweb mcp                                        # MCP server for AI assistants (stdio)
+pyweb lsp                                        # language server for editors (stdio)
 ```
 
+Editors: the [VS Code extension](editors/vscode) adds highlighting, errors as you
+type, hover that shows where code runs, completion and go to definition. Any
+other LSP editor can run `pyweb lsp` ([setup](docs/14-cli.md#editor-support)).
+
 ## Status
 
-PyWeb 0.1 is the first public release (beta). The language, server API,
-RPC protocol and CLI are documented and tested, and changes to them are
-announced in the changelog (see [stability](docs/15-toolkit.md#stability)). The test suite covers the
+PyWeb is in beta (0.x; see the PyPI badge above for the latest version).
+The language, server API, RPC protocol and CLI are documented and tested,
+and changes to them are announced in the [changelog](CHANGELOG.md) (see
+[stability](docs/15-toolkit.md#stability)). Upgrade with
+`pip install -U pyweb-stack`.
+
+| Version | Highlights |
+|---|---|
+| 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.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |
+| 0.2 | MCP server for AI assistants, AI guide, project templates, `AGENTS.md`/`CLAUDE.md`, `llms.txt` |
+| 0.1 | First public release: compiler, reactive runtime, server rendering, typed RPC, sessions, databases, CLI |
+
+The test suite covers the
 parser, the Python→JavaScript translation (differentially, against
 CPython), the reactive runtime, server rendering, RPC, sessions, every
 example app in Chromium, and the database/Redis layers against real
@@ -212,7 +244,7 @@ Postgres, MySQL and Redis servers, on Python 3.10–3.13.
 
 ## Authors
 
-Built by [MaanavKrishna](https://github.com/MaanavKrishna) and Claude.
+Built by [MaanavKrishna](https://github.com/MaanavKrishna).
 
 ## Contributing
 

{pyweb_stack-0.2.0 → pyweb_stack-0.4.0}/README.md

@@ -10,6 +10,9 @@ functions, without a JavaScript toolchain.
 ![PyPI](https://img.shields.io/pypi/v/pyweb-stack)
 ![License](https://img.shields.io/badge/license-MIT-lightgrey)
 
+**[Try it in your browser](https://maanavkrishna.github.io/PyWeb/playground.html)**: the playground runs
+the real PyWeb, server functions included, on Python compiled to WebAssembly.
+
 ```pyweb
 from pyweb import App, server
 
@@ -66,11 +69,20 @@ pyweb dev app.pyweb        # http://localhost:8000
 - **Boundaries are checked.** Database handles, imports and secrets can't
   leak into browser code: it's a compile error with a line number.
   `pyweb inspect` explains where every name runs and why.
+- **Pages that keep up.** `live(db, "select ...")` keeps page data in
+  step with the database in every open window; `@server` functions that
+  `yield` stream to the browser (AI replies included, with a Stop
+  button that really stops).
+- **Real multi-page apps.** Shared layouts that keep their state, links
+  that load without a full reload, typed query parameters, per-page
+  titles and social tags, error pages written in `.pyweb`.
+- **npm without Node.** `pyweb add chart.js/auto` vendors a package for
+  browser code; no `node_modules`, no bundler.
 - **Stateless servers.** Signed-cookie sessions and plain HTTP RPC scale
   horizontally behind any load balancer. Deploy with `pyweb serve`,
   uvicorn/gunicorn (ASGI) or the generated Dockerfile.
 
-A typical interactive page ships under 1 KB of page code plus a ~10 KB
+A typical interactive page ships under 1 KB of page code plus a ~14 KB
 (gzip) runtime that's cached across pages. Pages without interactivity
 ship no JavaScript.
 
@@ -80,17 +92,17 @@ ship no JavaScript.
 small SaaS products and content sites with interactive parts, built by
 people who'd rather stay in Python.
 
-**Not a fit:** large client-heavy single-page apps that need the npm
-ecosystem (use React/Svelte/Vue), or running scientific Python in the
-browser (use Pyodide/PyScript). See the
+**Not a fit:** large client-heavy single-page apps built around a
+JavaScript component framework (use React/Svelte/Vue), or running
+scientific Python in the browser (use Pyodide/PyScript). See the
 [comparison](https://maanavkrishna.github.io/PyWeb/introduction.html)
 and [current limitations](docs/16-limitations-roadmap.md).
 
 ## Build it with AI
 
 PyWeb ships an MCP server so AI assistants can scaffold, check, inspect,
-render and test your app, with errors that come back as line numbers and
-fix hints:
+render, screenshot and test your app, with errors that come back as line
+numbers and fix hints:
 
 ```bash
 claude mcp add pyweb -- pyweb mcp          # Claude Code
@@ -111,10 +123,10 @@ See [AI assistants & MCP](docs/17-ai-assistants.md).
 | | |
 |---|---|
 | Start | [Introduction](docs/01-introduction.md) · [Quickstart](docs/02-quickstart.md) · [Tutorial](docs/03-tutorial.md) · [AI assistants & MCP](docs/17-ai-assistants.md) |
-| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) |
-| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Data](docs/09-data.md) · [Auth](docs/10-auth.md) |
+| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) · [npm packages](docs/18-npm-packages.md) |
+| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Layouts & navigation](docs/19-layouts-navigation.md) · [Data](docs/09-data.md) · [Live data](docs/21-live-data.md) · [Building AI apps](docs/20-ai-apps.md) · [Auth](docs/10-auth.md) |
 | Ship | [Testing](docs/11-testing.md) · [Deployment](docs/12-deployment.md) · [Security](docs/13-security.md) · [CLI](docs/14-cli.md) |
-| Reference | [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
+| Reference | [Recipe: wallets & web3](docs/22-recipe-web3.md) · [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
 
 The same docs are published at
 **[maanavkrishna.github.io/PyWeb](https://maanavkrishna.github.io/PyWeb/)**,
@@ -131,26 +143,46 @@ a real browser by the test suite.
 | [`todo`](examples/todo/app.pyweb) | components, list mutation, filters, keyed lists |
 | [`blog`](examples/blog/app.pyweb) | SQL database, server functions, route params, 404s, validation errors |
 | [`auth`](examples/auth/app.pyweb) | registration, password hashing, sessions, protected pages |
-| [`chat`](examples/chat/app.pyweb) | route params, shared server state, polling with `on_mount` |
+| [`chat`](examples/chat/app.pyweb) | route params, shared server state, live updates with `publish`/`subscribe` |
 | [`showcase`](examples/showcase/app.pyweb) | everything on one page, with a stylesheet |
+| [`site`](examples/site/app.pyweb) | a layout, client-side navigation, query parameters, page titles, a 404 page |
+| [`dashboard`](examples/dashboard/app.pyweb) | live queries and a Chart.js chart from npm, in every open window |
+| [`ai-chat`](examples/ai-chat/app.pyweb) | streaming AI replies with Stop and Markdown (Anthropic, OpenAI-compatible or a demo model) |
 
 ## Command line
 
 ```bash
-pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat)
+pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat|ai-chat)
+pyweb add chart.js/auto                          # an npm package for browser code (no Node.js)
 pyweb dev app.pyweb                              # dev server: live reload + error overlay
 pyweb inspect app.pyweb                          # where each name runs, and why
 pyweb check app.pyweb                            # compile + security checks for CI
 pyweb build app.pyweb --out dist --production    # self-contained, hashed, minified dist/
 pyweb serve dist                                 # production server (/healthz, CSP, graceful shutdown)
 pyweb mcp                                        # MCP server for AI assistants (stdio)
+pyweb lsp                                        # language server for editors (stdio)
 ```
 
+Editors: the [VS Code extension](editors/vscode) adds highlighting, errors as you
+type, hover that shows where code runs, completion and go to definition. Any
+other LSP editor can run `pyweb lsp` ([setup](docs/14-cli.md#editor-support)).
+
 ## Status
 
-PyWeb 0.1 is the first public release (beta). The language, server API,
-RPC protocol and CLI are documented and tested, and changes to them are
-announced in the changelog (see [stability](docs/15-toolkit.md#stability)). The test suite covers the
+PyWeb is in beta (0.x; see the PyPI badge above for the latest version).
+The language, server API, RPC protocol and CLI are documented and tested,
+and changes to them are announced in the [changelog](CHANGELOG.md) (see
+[stability](docs/15-toolkit.md#stability)). Upgrade with
+`pip install -U pyweb-stack`.
+
+| Version | Highlights |
+|---|---|
+| 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.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |
+| 0.2 | MCP server for AI assistants, AI guide, project templates, `AGENTS.md`/`CLAUDE.md`, `llms.txt` |
+| 0.1 | First public release: compiler, reactive runtime, server rendering, typed RPC, sessions, databases, CLI |
+
+The test suite covers the
 parser, the Python→JavaScript translation (differentially, against
 CPython), the reactive runtime, server rendering, RPC, sessions, every
 example app in Chromium, and the database/Redis layers against real
@@ -158,7 +190,7 @@ Postgres, MySQL and Redis servers, on Python 3.10–3.13.
 
 ## Authors
 
-Built by [MaanavKrishna](https://github.com/MaanavKrishna) and Claude.
+Built by [MaanavKrishna](https://github.com/MaanavKrishna).
 
 ## Contributing
 

{pyweb_stack-0.2.0 → pyweb_stack-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyweb-stack"
-version = "0.2.0"
+version = "0.4.0"
 description = "Full-stack web apps in one Python file: server-rendered pages, reactive browser UI, typed RPC."
 readme = "README.md"
 license = { text = "MIT" }
@@ -12,7 +12,6 @@ requires-python = ">=3.10"
 dependencies = []
 authors = [
     { name = "MaanavKrishna", email = "67054795+MaanavKrishna@users.noreply.github.com" },
-    { name = "Claude", email = "noreply@anthropic.com" },
 ]
 maintainers = [{ name = "MaanavKrishna", email = "67054795+MaanavKrishna@users.noreply.github.com" }]
 keywords = ["web", "framework", "full-stack", "reactive", "rpc", "ssr", "compiler"]

{pyweb_stack-0.2.0 → pyweb_stack-0.4.0}/pyweb/__init__.py

@@ -3,25 +3,36 @@
 from .app import App
 from .models import Email, Model
 from . import auth, cache, jobs, realtime, security, observability, forms, testing
-from . import sync, deploy, uploads, lsp, live
+from . import sync, deploy, uploads, lsp, livetable
 from . import browser as browser_api
 from . import build, css, plugins, platform
 from .jobs import task
-from .context import NotFound, redirect, request, session
+from .context import NotFound, head, redirect, request, session
 from .rpc import RPCError
 from .decorators import component, edge, server, worker
+from .realtime import channel, publish, subscribe
+from .packages import npm
+from .markdown import Markdown
+from .livedata import live
 
 __all__ = [
     "App",
     "request",
     "session",
     "redirect",
+    "head",
     "NotFound",
     "RPCError",
     "component",
     "edge",
     "server",
     "worker",
+    "channel",
+    "publish",
+    "subscribe",
+    "npm",
+    "Markdown",
+    "live",
     "Email",
     "Model",
     "task",
@@ -34,7 +45,7 @@ __all__ = [
     "forms",
     "testing",
     "sync",
-    "live",
+    "livetable",
     "deploy",
     "uploads",
     "lsp",

{pyweb_stack-0.2.0 → pyweb_stack-0.4.0}/pyweb/ai/guide.md

@@ -135,8 +135,13 @@ def Home():
 
 Props are parameters (defaults = optional). Pass callbacks as props
 (`on_delete={lambda: delete(i)}`) and use them as handlers inside
-(`onclick={on_delete}`). Components must be in the same file and their
-initial state must be computable in the browser (pass server data as props).
+(`onclick={on_delete}`). A component's initial state must be computable in
+the browser (pass server data as props).
+
+Bigger apps can split into files: put components, `@server` functions and
+constants in e.g. `widgets.pyweb` (or `ui/cards.pyweb`) next to `app.pyweb`
+and `from widgets import Card, save`. Pages stay in `app.pyweb`; import
+server functions without `as`; each file keeps its own constants.
 
 ## 6. Server functions, sessions, routing
 
@@ -166,9 +171,41 @@ def Item(item_id: int):
 - Database: `from pyweb.db import connect; db = connect("sqlite:///app.db")`;
   `db.execute("select ... where id = ?", (x,)).dicts()`; always use `?`
   parameters; `with db.transaction(): ...`.
-- In handlers, navigate with `window.location.href = "/path"`.
-- Run code after load with a handler named `on_mount` (e.g.
-  `setInterval(refresh, 2000)` for polling).
+- Query parameters: page params not in the route come from the query
+  string, typed by annotation: `def Search(q: str = "", page: int = 1)`.
+  Missing required / bad values -> 400.
+- Layouts: `@app.layout` (or `@app.layout("/admin")`) on a function with
+  markup containing `{children}` once wraps every page under the prefix;
+  `@app.page(..., layout=None)` opts out. Links between pages load without
+  a full reload and keep the layout's state; mark nothing yourself: links
+  to the current page get `aria-current="page"` automatically.
+- In handlers, navigate with `navigate("/path")` (`from pyweb.browser import navigate`).
+- Head tags: `@app.page("/", title=..., description=..., image=...)`, or
+  `head(title=..., description=...)` in the page body (server). `App(base_url=...)`
+  adds canonical URLs.
+- Error pages: `@app.error(404)` on a page function taking `path` (and/or
+  `status`, `message`, `request_id`).
+- Run code after load with a handler named `on_mount`; stop timers in
+  `on_unmount` (runs when the user navigates away). React to a value
+  changing with `watch(lambda: value, handler)` in `on_mount`
+  (`from pyweb.browser import watch`).
+- Live data: `rows = live(db, "select ... where x = ?", (x,))` in a page
+  (`from pyweb import live`) renders the rows and keeps them current in
+  every open page when the tables are written through `pyweb.db`. No
+  publish/subscribe needed. Use `db.notify("table")` after writes made
+  outside `pyweb.db`. Keep live queries small (`LIMIT`).
+- Streaming (AI replies, progress): a `@server` function that `yield`s;
+  in an `async def` handler `stream = fn(...)` then
+  `async for piece in stream: ...`; `stream.cancel()` stops it (closes the
+  generator on the server). Show model output with `<Markdown text={reply} />`
+  (`from pyweb import Markdown`): safe, renders as it streams. Template:
+  `pyweb new NAME --template ai-chat`. Keep API keys in server code
+  (`os.environ`), never in page variables.
+- Live updates: in a server function `publish("room:1", data)`; in the
+  page `feed = channel("room:1")` (runs on the server); in `on_mount`
+  `subscribe(feed, handler)`, where `handler(message)` assigns page
+  variables. Import all three from `pyweb`. Never poll with
+  `setInterval` when `publish` fits.
 
 ## 7. Python that compiles to the browser
 
@@ -183,7 +220,16 @@ JS globals are available directly: `window`, `document`, `localStorage`,
 
 Not supported in browser code: classes, imports, `with`, generators,
 walrus, `*args/**kwargs` parameters, slice assignment, keyword arguments to
-JS functions, server-only names. Move such code into `@server` functions.
+browser globals, server-only names. Move such code into `@server` functions.
+
+npm packages (no Node.js needed): run `pyweb add chart.js/auto` in the app
+folder (writes `pyweb.lock` and `static/vendor/`; commit both), then bind at
+module level with literal strings: `Chart = npm("chart.js/auto")`,
+`Gauge = npm("pkg", "Gauge")` (named export), `lib = npm("pkg", "*")` (whole
+module). Calling a class constructs it (`new`); keyword arguments become one
+options object. npm names work only in browser code (handlers, `on_mount`,
+lambdas), never directly in markup. Give libraries an element with
+`ref={el}` (declare `el = None`; it is set before `on_mount`).
 
 ## 8. Errors and fixes
 
@@ -195,21 +241,29 @@ JS functions, server-only names. Move such code into `@server` functions.
 | `cannot assign to ... derived/read-only` | Assign to a variable the handler owns (make it state), not a computed/constant. |
 | `server secret ... would be sent to the browser` | Keep the value inside `@server` functions; don't read it in markup/handlers. |
 | `bind={x} must name a local variable` | Declare `x = ""` (or a number/bool) in the page before the markup. |
-| `unknown component <X>` | Define `def X(...)` with markup in the same file (capitalized). |
+| `unknown component <X>` | Define `def X(...)` with markup (capitalized) in this file, or import it: `from widgets import X`. |
 | `mismatched </tag>` / `is never closed` | Close every tag; void tags (`input`, `img`, `br`) need no close (`<input ... />`). |
 | `... is not supported in browser code` | Rewrite with supported constructs or move it to `@server`. |
+| `npm package 'x' isn't installed` | Run `pyweb add x` in the app folder (the folder with `pyweb.lock`). |
+| `uses X from npm(...), which only exists in the browser` | Use the package in a handler or `on_mount` and store the result in a page variable that markup shows. |
+| `layout ... has no {children}` | Put `{children}` exactly once in the layout's markup where pages go. |
+| `isn't a valid int` / `missing ?name=` (400) | Give the query parameter a default, or link with a valid value. |
+| `pyweb add`: `is CommonJS` / `imports the Node.js module` | Pick an ES-module browser package (e.g. `lodash-es`), or do the work in an `@server` function. |
 
 ## 9. Workflow for agents
 
 1. Start from a template: `pyweb new NAME --template todo` (or the
-   `pyweb_new_app` MCP tool). Templates: blank, counter, todo, blog, auth, chat.
+   `pyweb_new_app` MCP tool). Templates: blank, counter, todo, blog, auth, chat, ai-chat.
 2. Edit `app.pyweb`. After every edit run `pyweb check app.pyweb`
    (MCP: `pyweb_check`) and fix errors by line number.
 3. Use `pyweb inspect` (MCP: `pyweb_inspect`) to confirm what runs in the
    browser vs server and what is sent to the browser.
 4. Verify behaviour: render pages (`pyweb_render`) and call server
-   functions (`pyweb_call`), or write tests with `pyweb.testing.TestClient`.
-5. Ship: `pyweb build app.pyweb --out dist --production` then
+   functions (`pyweb_call`). See the page and try interactions in a real
+   browser with `pyweb_screenshot` (steps: click, fill, press, ...).
+5. Test: new apps include `test_app.py` (`pyweb.testing.TestClient`); add
+   tests for what you change and run `pytest` (MCP: `pyweb_test`).
+6. Ship: `pyweb build app.pyweb --out dist --production` then
    `pyweb serve dist` (set `PYWEB_AUTH_SECRET` in production).
 
 Full docs: https://maanavkrishna.github.io/PyWeb/

pyweb_stack-0.4.0/pyweb/app.py

@@ -0,0 +1,78 @@
+"""Application object: page registry and configuration."""
+
+from __future__ import annotations
+
+
+class App:
+    """The app: its pages, layouts, error pages and site-wide settings.
+
+    ``base_url`` (e.g. ``"https://example.com"``) gives every page a
+    canonical URL and absolute social-card links; ``description`` and
+    ``image`` are the defaults for pages that don't set their own.
+    ``client_nav=False`` makes links do full page loads.
+    """
+
+    def __init__(self, database=None, cache=None, auth=None, plugins=(), *,
+                 title="PyWeb", stylesheets=(), lang="en", base_url=None, description=None,
+                 image=None, client_nav=True):
+        self.title = title
+        self.stylesheets = list(stylesheets)
+        self.lang = lang
+        self.base_url = base_url.rstrip("/") if base_url else None
+        self.description = description
+        self.image = image
+        self.client_nav = client_nav
+        self.database = database
+        self.cache = cache
+        self.auth = auth
+        self.pages: list[tuple[str, str, dict]] = []
+        self.layouts: list[tuple[str, str]] = []
+        self.errors: dict[int, str] = {}
+        from pyweb.plugins import Registry
+        self.plugins = Registry()
+        for plugin in plugins:
+            self.use(plugin)
+
+    def page(self, route, *, title=None, render="server", description=None, image=None, canonical=None,
+             noindex=False, layout=...):
+        """Register a page at ``route``. ``{name}`` segments and other parameters of the
+        function (from the query string) become its arguments."""
+        def deco(fn):
+            self.pages.append((route, fn.__name__, {"render": render, "title": title}))
+            fn.__pyweb_route__ = route
+            fn.__pyweb_title__ = title
+            fn.__pyweb_render__ = render
+            return fn
+
+        return deco
+
+    def layout(self, prefix="/"):
+        """Wrap every page under ``prefix`` in this function's markup (``{children}`` is the page).
+
+        Use as ``@app.layout`` or ``@app.layout("/admin")``.
+        """
+        if callable(prefix):
+            self.layouts.append(("/", prefix.__name__))
+            return prefix
+
+        def deco(fn):
+            self.layouts.append((prefix, fn.__name__))
+            return fn
+
+        return deco
+
+    def error(self, status, *, title=None, layout=...):
+        """Render this page for HTTP ``status`` (404, 500, ...) instead of the built-in one."""
+        def deco(fn):
+            self.errors[status] = fn.__name__
+            return fn
+
+        return deco
+
+    def use(self, plugin):
+        """Attach a :class:`pyweb.plugins.Plugin`; merges its routes."""
+        self.plugins.add(plugin)
+        for route, fn in plugin.routes:
+            self.pages.append((route, fn.__name__, {"render": "server",
+                                                   "plugin": plugin.name}))
+        return plugin