Add mount docs and tighten browser authoring surface

- add docs for mount(...) browser-owned app surfaces
- document Module payload access, metadata updates, batching, and store subscription callback shape
- compile self.subscribe(store, fn) into lifecycle-managed browser store subscriptions
- refresh browser/runtime stubs and pyi signatures for app, page, mount, shell, env, content, sessions, stores, and urls

Author: BleedingXiko

docs/app/content/docs/framework/mounts.md

@@ -0,0 +1,140 @@
+---
+title: Mounts
+description: Browser-owned client apps — when to use a mount instead of a page route.
+order: 11.8
+---
+
+# Mounts
+
+A mount is a browser-owned client app mounted at a server URL. Use it when the browser owns the entire surface from boot — a search overlay, an admin console, a rich editor — rather than a server-rendered page that hydrates.
+
+## Page route vs mount
+
+| | `page(...)` | `mount(...)` |
+|---|---|---|
+| First paint | Server-rendered HTML | Browser renders from boot |
+| SSR | Yes | No |
+| Interactive | After hydration | From boot |
+| Use for | Most routes | Full client apps |
+
+If you need a fast first paint or SSR for SEO, use a `page(...)` route. Use a mount when the browser owns everything from the start.
+
+## Scaffold
+
+```bash
+sprag add mount search
+```
+
+This creates:
+
+```
+app/mounts/search/
+├── mount.py       # Manifest
+├── web.py         # Root Component
+├── modules.py     # Root Module (optional)
+└── server.py      # Boot controller (optional)
+```
+
+## Manifest
+
+```python
+# app/mounts/search/mount.py
+from sprag import mount
+from .web import SearchApp
+from .modules import SearchModule
+from .server import SearchBoot
+
+search = mount(
+    path="/search",
+    component=SearchApp,
+    module=SearchModule,
+    boot=SearchBoot,
+    metadata={"title": "Search"},
+)
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `path` | Yes | URL path for this mount |
+| `component` | Yes | Root Component class |
+| `module` | No | Root Module class for lifecycle logic |
+| `boot` | No | Controller providing initial data via `load()` |
+| `metadata` | No | Dict of metadata (title, description, etc.) |
+| `shell` | No | Override the app-level shell |
+| `css` | No | Mount-specific CSS files |
+| `js` | No | Extra scripts to include |
+| `modules` | No | JS import aliases: `{"alias": "path/to/module.js"}` |
+| `providers` | No | Browser provider Modules |
+
+## Boot controller
+
+The `boot` controller's `load()` runs on the server and seeds initial state into the mount, just like a page controller. Use it to supply data the mount needs on first load.
+
+```python
+# app/mounts/search/server.py
+from sprag import Controller
+
+class SearchBoot(Controller):
+    route = "/search"
+
+    def load(self):
+        return {"title": "Search the docs"}
+```
+
+The return dict becomes the Module's initial `self.state`. If you don't need server data, omit `boot` — the mount still works with an empty initial state.
+
+## Root Component and Module
+
+The root Component renders the mount's DOM. The root Module owns lifecycle: event delegation, server calls, state.
+
+```python
+# app/mounts/search/web.py
+from sprag import Component, ui
+
+class SearchApp(Component):
+    def render(self, props=None):
+        return ui.div(
+            ui.input(
+                type="text",
+                placeholder="Search…",
+                data_role="search-input",
+                class_="search-input",
+            ),
+            ui.div(data_role="search-status", class_="search-status"),
+            ui.ul(data_role="search-results", class_="search-results"),
+            class_="search-app",
+        )
+```
+
+```python
+# app/mounts/search/modules.py
+from sprag import Module, debounce
+
+class SearchModule(Module):
+    def on_start(self):
+        self.delegate(self.element, "input", "[data-role='search-input']", self.on_input)
+
+    @debounce(0.15)
+    def on_input(self, event, target):
+        self.call_action("search", {"query": target.value}).then(self._on_results)
+
+    def _on_results(self, result):
+        self.set_state(result.value or {})
+```
+
+## Providers
+
+Pass browser-side provider Modules the same way as with `page(...)`:
+
+```python
+search = mount(
+    path="/search",
+    component=SearchApp,
+    module=SearchModule,
+    providers={"toast": ToastProvider},
+)
+```
+
+Resolve them inside any Module with `self.provider("toast")`.

docs/app/content/docs/framework/stores.md

@@ -70,7 +70,7 @@ class CounterService(Service):
 
 ## Browser-side usage
 
-In a `Module`, use `self.subscribe()` to bind store changes to your lifecycle:
+In a `Module`, use `self.subscribe(store, fn)` to bind store changes to your lifecycle:
 
 ```python
 from sprag import Module, store

docs/app/content/docs/guides/payload-design.md

@@ -8,6 +8,15 @@ order: 35
 
 Everything returned from `load()` becomes `window.__SPRAG_PAYLOAD__` — a JSON blob inlined into every page's HTML. Keeping it lean directly reduces page weight, time-to-first-byte, and the size of your build output.
 
+In browser `Module` code, read payload fields with dict-style access:
+
+```python
+payload = browser.window.__SPRAG_PAYLOAD__ or {}
+doc = payload.get("doc")
+```
+
+SPRAG compiles `.get("key", default)` to JavaScript property access, and the spelling stays friendly to Python type checkers.
+
 ## What gets serialized
 
 SPRAG serializes the return value of `load()` using Python's standard JSON encoder. **Dataclasses, Pydantic models, and ORM objects serialize all their fields** — including ones you never intended to send to the browser.

docs/app/content/docs/ragot/modules.md

@@ -88,6 +88,18 @@ def on_save(self, event, target):
     result.then(self._on_saved)
 ```
 
+## Reading JSON payloads
+
+Browser payloads are plain JSON objects. Use dict-style access in Module code:
+
+```python
+payload = browser.window.__SPRAG_PAYLOAD__ or {}
+auth = payload.get("auth")
+count = payload.get("count", 0)
+```
+
+That spelling type-checks cleanly and compiles to JavaScript property access.
+
 ## DOM access
 
 - **`self.element`** — the DOM node this Module is attached to (passed from `hydrate()`)
@@ -168,6 +180,46 @@ def on_click(self, event, target):
     self.navigate("/other-page")
 ```
 
+## Page metadata
+
+Update the page title, description, or canonical URL dynamically from the browser:
+
+```python
+def on_start(self):
+    self.set_metadata({"title": "My Page — App"})
+
+def _on_article_loaded(self, result):
+    article = (result.value or {}).get("article") or {}
+    self.set_metadata({
+        "title": article.get("title", ""),
+        "description": article.get("summary", ""),
+    })
+```
+
+`set_metadata(metadata, options={})` merges the dict onto the active page head. The same keys supported in the static `page(metadata={...})` manifest work here: `title`, `description`, `canonical`, `og:*`. Use it for routes where the document title depends on data fetched after hydration.
+
+## Batching state updates
+
+`batch_state(fn)` calls `fn(state)` with the current mutable state and fires exactly one re-render when the mutator returns. Use it when you need multiple fields updated atomically, reading from the current state:
+
+```python
+class CounterModule(Module):
+    def on_start(self):
+        self.delegate(self.element, "click", "[data-role='reset']", self.on_reset)
+
+    def on_reset(self, event, target):
+        self.batch_state(self._reset)
+
+    def _reset(self, state):
+        self.set_state({
+            "count": 0,
+            "total": state.get("total", 0) + 1,
+            "last_reset": True,
+        })
+```
+
+Pass a method reference — nested `def` inside a method is not supported in browser codegen.
+
 ## Timers
 
 ```python
@@ -189,11 +241,11 @@ class MyModule(Module):
     def on_start(self):
         self.subscribe(counter_store, self._on_store)
 
-    def _on_store(self, state, meta, store):
+    def _on_store(self, state, meta, s):
         self.set_state({"count": state["count"]})
 ```
 
-Auto-cleaned on `on_stop()`.
+Auto-cleaned on `on_stop()`. The callback receives `(state, meta, store)` — trailing args can be omitted if unused.
 
 ## Page and Mount Providers
 

docs/app/routes/blog/components.py

@@ -1,6 +1,5 @@
-from sprag import Component, ui
-
 from app.site import blog_card
+from sprag import Component, ui
 
 
 class BlogIndexPage(Component):
@@ -16,6 +15,7 @@ def render(self, props=None):
             )
             for post in posts
         ]
+
         return ui.div(
             ui.header(
                 ui.h1("Blog"),

sprag/__init__.py

@@ -1,6 +1,6 @@
 """Public SPRAG framework surface."""
 
-__version__ = "0.1.18"
+__version__ = "0.1.19"
 
 from .runtime import dom
 from .runtime.app import App

sprag/dev/codegen/expressions.py

@@ -204,6 +204,28 @@ def _compile_expr(node, env, method_names=None):
                 ms_js = f"({_compile_expr(sec_arg, env, method_names=method_names)} * 1000)"
             js_method = node.func.attr  # timeout / interval map identity
             return f"this.{js_method}({fn_js}, {ms_js})"
+        # self.subscribe(store, fn) — lifecycle-managed store subscription.
+        # The Python API mirrors Specter's store.subscribe(fn, owner=self).
+        # In the browser this must compile to store.subscribe(fn) +
+        # this.addCleanup(unsub) so the subscription tears down with the Module.
+        # Ragot's Module.subscribe(fn, options) is for Module-local state only
+        # and silently no-ops when its first arg is not a function.
+        if (
+            isinstance(node.func, ast.Attribute)
+            and node.func.attr == "subscribe"
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id == "self"
+            and len(node.args) == 2
+            and isinstance(node.args[0], ast.Name)
+            and (env.get("__sprag_stores__") or {}).get(node.args[0].id)
+        ):
+            store_refs = env["__sprag_stores__"]
+            store_js_name = store_refs[node.args[0].id]
+            fn_arg = node.args[1]
+            fn_js = _compile_expr(fn_arg, env, method_names=method_names)
+            if _is_bound_method_reference(fn_arg, method_names):
+                fn_js = f"{fn_js}.bind(this)"
+            return f"this.addCleanup({store_js_name}.subscribe({fn_js}))"
         # Store method translation. The Python local name is mapped to the
         # JS bridge name via env, and the SPRAG method name is translated
         # to its JS counterpart via the STORE_METHOD_JS table (nearly

sprag/dev/templates/labs/app/routes/auth_demo/protected/modules.py.tmpl

@@ -36,7 +36,7 @@ class ProtectedAuthModule(Module):
             self.on_switch_profile,
         )
         payload = browser.window.__SPRAG_PAYLOAD__ or {}
-        client_auth = payload.auth or None
+        client_auth = payload.get("auth") or None
         self.set_state(
             {
                 "client_auth": client_auth,

sprag/dev/templates/labs/app/routes/login/modules.py.tmpl

@@ -22,7 +22,7 @@ class LoginModule(Module):
     def on_start(self):
         self.delegate(self.element, "submit", "[data-role='login-form']", self.on_submit)
         payload = browser.window.__SPRAG_PAYLOAD__ or {}
-        client_auth = payload.auth or None
+        client_auth = payload.get("auth") or None
         self.set_state(
             {
                 "client_auth": client_auth,

sprag/runtime/app.py

@@ -24,7 +24,13 @@ def __init__(self, name: str):
 
 @dataclass
 class App:
-    """Configured SPRAG application: providers, surfaces, build, and server runtime."""
+    """Application container for a SPRAG project.
+
+    Create this once in ``app/__init__.py``. Configure providers, route and
+    mount packages, the app shell, global ESM modules, metadata, sessions,
+    uploads, and server mode. Use ``build(...)`` for static output and
+    ``serve(...)`` for local/runtime serving.
+    """
 
     providers: dict = field(default_factory=dict)
     routes: str = "app.routes"