more docs pages updates

Author: deeleeramone

pywry/docs/docs/guides/app-show.md

@@ -1,4 +1,4 @@
-# The `app.show()` Method
+# The app.show() Method
 
 `app.show()` is the primary entry point for rendering content in PyWry. It accepts HTML (as a string or `HtmlContent` object), determines the correct rendering path for the current environment, and returns a handle you can use to interact with the result.
 
@@ -36,7 +36,7 @@ app.show(
 
 ## Parameters in Detail
 
-### `content` — what to render
+### content — what to render
 
 Accepts either a plain HTML string or an `HtmlContent` object. When you pass a string, PyWry wraps it in a minimal document structure automatically. When you pass `HtmlContent`, you get control over CSS files, JS files, inline styles, JSON data injection, and hot reload watching. See the [HtmlContent guide](html-content.md) for details.
 
@@ -58,15 +58,15 @@ content = HtmlContent(
 app.show(content)
 ```
 
-### `title` — window title
+### title — window title
 
 Sets the title bar text in native window mode. Defaults to `"PyWry"`. Ignored in notebook and browser modes.
 
 ```python
 app.show("<h1>Dashboard</h1>", title="Sales Dashboard")
 ```
 
-### `width` and `height` — dimensions
+### width and height — dimensions
 
 In native mode, `width` accepts an integer (pixels) for the OS window size. In notebook mode, `width` can also be a CSS string like `"100%"` or `"500px"`. `height` is always an integer (pixels).
 
@@ -80,7 +80,7 @@ app.show(html, width="100%", height=400)
 
 Defaults come from `WindowConfig` — 1280×720 unless overridden in your configuration.
 
-### `callbacks` — event handlers
+### callbacks — event handlers
 
 A dictionary mapping event names to Python callback functions. These are registered before the content is rendered, so they're ready to receive events immediately.
 
@@ -99,7 +99,7 @@ app.show(html, callbacks={
 
 See the [Event System guide](events.md) for the full callback signature and registration patterns.
 
-### `include_plotly` and `include_aggrid` — library loading
+### include_plotly and include_aggrid — library loading
 
 When `True`, PyWry injects the Plotly.js or AG Grid JavaScript and CSS libraries into the page. You don't need to set these manually if you use `app.show_plotly()` or `app.show_dataframe()` — they set the flags automatically.
 
@@ -111,7 +111,7 @@ app.show(plotly_html, include_plotly=True)
 app.show_plotly(fig)
 ```
 
-### `label` — window identity
+### label — window identity
 
 In `MULTI_WINDOW` mode, the `label` identifies which window to create or update. In `SINGLE_WINDOW` mode, the label is fixed and this parameter is ignored. Labels are used in callbacks to target events back to a specific window.
 
@@ -127,7 +127,7 @@ def on_filter(data, event_type, label):
     app.emit("app:update", {"filter": data}, "chart")  # target the chart window
 ```
 
-### `watch` — hot reload
+### watch — hot reload
 
 When `True`, PyWry watches the CSS and JS files referenced by `HtmlContent.css_files` and `HtmlContent.script_files` for changes, and live-reloads them in the browser without a full page refresh.
 
@@ -142,7 +142,7 @@ app.show(content, watch=True)  # or override here
 
 See the [Hot Reload guide](hot-reload.md) for details.
 
-### `toolbars` and `modals` — UI chrome
+### toolbars and modals — UI chrome
 
 Lists of `Toolbar` or `Modal` objects (or their dict equivalents) that wrap your content in an interactive layout. Toolbars are positioned around the content area; modals are hidden until triggered by events.
 
@@ -193,7 +193,7 @@ All implement the `BaseWidget` protocol, so `emit()` and `on()` work identically
 
 `app.show()` is the general-purpose method. PyWry also provides specialized variants that configure the right options automatically:
 
-### `app.show_plotly(figure, ...)`
+### app.show_plotly(figure, ...)
 
 Converts a Plotly figure to HTML, injects Plotly.js, and pre-wires chart events (`plotly:click`, `plotly:hover`, `plotly:selected`, `plotly:relayout`).
 
@@ -204,7 +204,7 @@ fig = px.scatter(x=[1, 2, 3], y=[1, 4, 9])
 app.show_plotly(fig, callbacks={"plotly:click": on_click})
 ```
 
-### `app.show_dataframe(data, ...)`
+### app.show_dataframe(data, ...)
 
 Converts a DataFrame to AG Grid HTML, injects the AG Grid library, and pre-wires grid events (`grid:cell-clicked`, `grid:selection-changed`, `grid:cell-edited`).
 
@@ -224,14 +224,14 @@ Both methods accept all the same optional parameters as `app.show()` (`title`, `
 ```mermaid
 flowchart TD
     A["app.show(content)"] --> B{"mode = BROWSER?"}
-    B -- Yes --> C["InlineWidget\nFastAPI + WebSocket\nopens system browser"]
+    B -- Yes --> C["InlineWidget<br>FastAPI + WebSocket<br>opens system browser"]
     B -- No --> D{"In a notebook?"}
-    D -- Yes --> E{"include_plotly\nor include_aggrid?"}
-    E -- Yes --> F["InlineWidget\nIFrame + WebSocket\nspecialized JS"]
-    E -- No --> G{"anywidget\navailable?"}
-    G -- Yes --> H["PyWryWidget\nanywidget + traitlet sync"]
-    G -- No --> I["InlineWidget\nIFrame + WebSocket\nfallback"]
-    D -- No --> J["NativeWindowHandle\nPyTauri + OS webview"]
+    D -- Yes --> E{"include_plotly<br>or include_aggrid?"}
+    E -- Yes --> F["InlineWidget<br>IFrame + WebSocket<br>specialized JS"]
+    E -- No --> G{"anywidget<br>available?"}
+    G -- Yes --> H["PyWryWidget<br>anywidget + traitlet sync"]
+    G -- No --> I["InlineWidget<br>IFrame + WebSocket<br>fallback"]
+    D -- No --> J["NativeWindowHandle<br>PyTauri + OS webview"]
 ```
 
 You can force a specific mode by setting it on the app:

pywry/docs/docs/guides/browser-mode.md

@@ -1,80 +1,123 @@
 # Browser Mode
 
-Browser mode runs PyWry as a web server, opening content in your default browser instead of native windows.
+Browser mode runs PyWry without native OS windows. Instead, it starts a local web server and opens your content in the system browser. All communication between Python and JavaScript happens over WebSocket.
 
-## When to Use
+## When to Use Browser Mode
 
-- **SSH/Remote access** — No GUI available
-- **Cross-platform sharing** — Share via URL
-- **Development** — Use browser DevTools
+| Scenario | Why browser mode helps |
+|:---|:---|
+| SSH / remote server | No display server available |
+| Docker / CI containers | No GUI libraries installed |
+| WSL | Native windows can't reach the Linux display |
+| Cross-browser testing | Use browser DevTools directly |
+| Sharing with others | Send a URL instead of installing an app |
 
-## Enable Browser Mode
+## Enabling Browser Mode
 
-### Programmatic
+### In Code
 
 ```python
 from pywry import PyWry, WindowMode
 
 app = PyWry(mode=WindowMode.BROWSER)
 handle = app.show("<h1>Hello Browser!</h1>")
-
-app.block()  # Keep server running
+app.block()  # Keeps the server running
 ```
 
-### Environment Variable
+### Via Environment Variable
 
 ```bash
 export PYWRY_WINDOW__MODE=browser
 python my_app.py
 ```
 
+### Via Config File
+
+```toml
+# pywry.toml
+[window]
+mode = "browser"
+```
+
 ## How It Works
 
-1. PyWry starts a FastAPI server with WebSocket support
-2. Content is served at `http://localhost:8765/widget/{label}`
-3. Browser opens automatically
-4. WebSocket maintains bidirectional communication
+When you call `app.show()` in browser mode:
+
+1. **Server starts** — A FastAPI + uvicorn server launches in a background daemon thread (once, on first `show()`)
+2. **Widget registers** — The rendered HTML is stored in the server's widget registry, keyed by label
+3. **Browser opens** — The system default browser navigates to `http://127.0.0.1:8765/widget/{label}`
+4. **WebSocket connects** — The page's JavaScript bridge opens a WebSocket back to the server for bidirectional events
+5. **Events flow** — `window.pywry.emit()` in the browser sends JSON over WebSocket to Python; `handle.emit()` in Python pushes JSON back
+
+### Server Routes
+
+| Route | Method | Description |
+|:---|:---|:---|
+| `/widget/{widget_id}` | GET | Serves the widget's HTML page |
+| `/ws/{widget_id}` | WebSocket | Bidirectional event bridge |
+| `/health` | GET | Health check (requires internal API token) |
+| `/register_widget` | POST | Re-register a widget (kernel restart recovery) |
+| `/disconnect/{widget_id}` | POST | Clean disconnect of a widget |
 
 ## Server Configuration
 
-### pywry.toml
+### Default Settings
 
-```toml
-[server]
-host = "127.0.0.1"
-port = 8765
-auto_start = true
+| Setting | Default | Environment variable |
+|:---|:---|:---|
+| Host | `127.0.0.1` | `PYWRY_SERVER__HOST` |
+| Port | `8765` | `PYWRY_SERVER__PORT` |
+| Widget URL prefix | `/widget` | `PYWRY_SERVER__WIDGET_PREFIX` |
+| Auto-start | `True` | `PYWRY_SERVER__AUTO_START` |
+
+### Custom Host and Port
+
+```python
+import os
+
+os.environ["PYWRY_SERVER__HOST"] = "0.0.0.0"  # Bind to all interfaces
+os.environ["PYWRY_SERVER__PORT"] = "9000"
+
+from pywry import PyWry, WindowMode
+
+app = PyWry(mode=WindowMode.BROWSER)
+handle = app.show("<h1>Available on the network</h1>")
+app.block()
 ```
 
-### Environment Variables
+Or in a config file:
 
-```bash
-export PYWRY_SERVER__HOST=0.0.0.0
-export PYWRY_SERVER__PORT=8080
+```toml
+# pywry.toml
+[server]
+host = "0.0.0.0"
+port = 9000
 ```
 
 ## Multiple Widgets
 
-Each widget gets its own URL:
+Each widget gets its own URL. The server can serve many widgets simultaneously:
 
 ```python
-from pywry import PyWry, WindowMode
-
 app = PyWry(mode=WindowMode.BROWSER)
 
-h1 = app.show("<h1>Widget 1</h1>", label="widget-1")
-h2 = app.show("<h1>Widget 2</h1>", label="widget-2")
+h1 = app.show("<h1>Chart</h1>", label="chart")
+h2 = app.show("<h1>Table</h1>", label="table")
 
-# URLs:
-# http://localhost:8765/widget/widget-1
-# http://localhost:8765/widget/widget-2
+# Two browser tabs open:
+#   http://127.0.0.1:8765/widget/chart
+#   http://127.0.0.1:8765/widget/table
+print(h1.url)  # Full URL for the chart widget
+print(h2.url)  # Full URL for the table widget
 
 app.block()
 ```
 
-## HTTPS Configuration
+## HTTPS
+
+Enable TLS by providing certificate and key files:
 
-Enable HTTPS via configuration:
+### Via Config
 
 ```toml
 # pywry.toml
@@ -85,22 +128,72 @@ ssl_certfile = "/path/to/cert.pem"
 ssl_keyfile = "/path/to/key.pem"
 ```
 
-Or environment variables:
+### Via Environment Variables
 
 ```bash
 export PYWRY_SERVER__SSL_CERTFILE=/path/to/cert.pem
 export PYWRY_SERVER__SSL_KEYFILE=/path/to/key.pem
 ```
 
+When SSL is configured, widget URLs use `https://` and WebSocket connections use `wss://`.
+
 ## WebSocket Security
 
-Enable per-widget authentication tokens:
+By default, each widget gets a unique token generated with `secrets.token_urlsafe(32)`. The browser sends this token via the `Sec-WebSocket-Protocol` header during the WebSocket handshake. Connections without a valid token are rejected.
+
+```toml
+# pywry.toml
+[server]
+websocket_require_token = true   # Default — enforce per-widget tokens
+```
+
+### Origin Validation
+
+Restrict which origins can connect:
 
 ```toml
 [server]
-websocket_require_token = true
+websocket_allowed_origins = ["https://myapp.example.com"]
+```
+
+An empty list (the default) allows connections from any origin.
+
+### CORS
+
+```toml
+[server]
+cors_origins = ["https://myapp.example.com"]  # Default: ["*"]
+```
+
+## Callbacks and Events
+
+Callbacks work identically in browser mode — the WebSocket transport is transparent:
+
+```python
+app = PyWry(mode=WindowMode.BROWSER)
+
+def on_click(data, event_type, label):
+    handle.emit("app:response", {"message": "Button clicked!"})
+
+handle = app.show(
+    '<button onclick="window.pywry.emit(\'app:click\', {})">Click me</button>',
+    callbacks={"app:click": on_click},
+)
+app.block()
 ```
 
-## Deploy Mode
+## Blocking
+
+`app.block()` in browser mode monitors WebSocket connections. It returns when all widgets have disconnected (i.e., every browser tab has been closed or navigated away):
+
+```python
+app.show(content)
+app.block()  # Waits until all browser tabs close
+# Code continues after disconnect
+```
+
+Press `Ctrl+C` to stop immediately — PyWry calls `app.destroy()` to shut down the server cleanly.
+
+## Relationship to Deploy Mode
 
-For production deployments with multiple workers, see [Deploy Mode](deploy-mode.md).
+Browser mode runs the server in a **background thread** alongside your script. For **production** deployments where the server _is_ your application, use [Deploy Mode](deploy-mode.md) instead — it runs uvicorn in the foreground with multi-worker support, Redis state, and proper process management.

pywry/docs/docs/guides/content-assembly.md

@@ -24,7 +24,7 @@ Here's what happens when `app.show(content)` is called in native window mode (th
 6. Assemble final HTML document
 7. Send to rendering path (native / notebook / browser)
 
-## What Goes Into `<head>`
+## What Goes Into &lt;head&gt;
 
 The `<head>` section is built from these components, injected in this exact order:
 
@@ -153,7 +153,7 @@ Each file in `HtmlContent.script_files` is injected as a `<script>` tag.
 
 `HtmlContent.init_script` runs last — it's the final `<script>` tag in the document. By the time it executes, everything else is available: `window.pywry`, `window.json_data`, all CSS applied, all libraries loaded.
 
-## What Goes Into `<body>`
+## What Goes Into &lt;body&gt;
 
 ### Content Wrapping