caspian-utils 0.2.7 → 0.2.8

package/dist/docs/fetch-data.md

@@ -320,7 +320,7 @@ async def chat(message: str):
             yield text
 ```
 
-Client side, append each chunk to reactive state so the UI grows token by token:
+Client side, append each chunk to reactive state so the UI grows token by token:
 
 ```html
 <script>
@@ -333,10 +333,12 @@ Client side, append each chunk to reactive state so the UI grows token by token:
       onStreamComplete: () => console.log("done"),
     });
   }
-</script>
-```
-
-In the current runtime, generator and async-generator RPC results are wrapped with `SSE(...)` inside `casp.rpc.py`, and route-level generator results are also wrapped by `main.py` before the response is returned.
+</script>
+```
+
+When a streaming call uses `abortPrevious: true`, it remains the active cancellable RPC until the stream's final chunk. A later RPC call with `abortPrevious: true` can therefore cancel a response even after its headers and early chunks have arrived. Cancellation resolves to `{ cancelled: true }`; use a request generation as well when the UI must state explicitly which response is authoritative.
+
+In the current runtime, generator and async-generator RPC results are wrapped with `SSE(...)` inside `casp.rpc.py`, and route-level generator results are also wrapped by `main.py` before the response is returned.
 
 ## File Uploads
 
@@ -379,11 +381,11 @@ Client example:
 <script>
   async function uploadSelectedFiles(fileList, collection = "auto") {
     for (const file of Array.from(fileList ?? [])) {
-      const response = await pp.rpc("upload_file", { file, collection }, {
-        onUploadProgress: (progress) => {
-          console.log(progress.percentage ?? 0);
-        },
-      });
+      const response = await pp.rpc("upload_file", { file, collection }, {
+        onUploadProgress: (progress) => {
+          console.log(progress.percent ?? 0);
+        },
+      });
 
       if (response?.data) {
         setFileManagerData(response.data);
@@ -391,9 +393,11 @@ Client example:
     }
   }
 </script>
-```
-
-Use this pattern for real file managers:
+```
+
+`onUploadProgress` receives `{ loaded, total, percent }`; there is no `percentage` field. A payload containing a `File` or non-empty `FileList` becomes multipart. PulsePoint emits all non-file fields before file parts so companion values are available to a server that starts handling a streamed file before the browser has finished sending the body. Object values are JSON-stringified, nullish values are omitted, and every file in a `FileList` is appended under the original field name.
+
+Use this pattern for real file managers:
 
 - Keep upload and delete actions in the owning route `index.py`, not in `main.py`.
 - Use `page()` to render the initial manager payload.

package/dist/docs/file-uploads.md

@@ -129,11 +129,11 @@ Keep route-specific auth checks, input validation, and final response shape here
 
     async function uploadSelectedFiles(fileList) {
       for (const file of Array.from(fileList ?? [])) {
-        const response = await pp.rpc("upload_asset", { file }, {
-          onUploadProgress: (progress) => {
-            console.log(progress.percentage ?? 0);
-          },
-        });
+        const response = await pp.rpc("upload_asset", { file }, {
+          onUploadProgress: (progress) => {
+            console.log(progress.percent ?? 0);
+          },
+        });
 
         if (response?.data) {
           setFileManagerData(response.data);
@@ -142,9 +142,11 @@ Keep route-specific auth checks, input validation, and final response shape here
     }
   </script>
 </section>
-```
-
-Prefer this state-driven shape over manual `innerHTML` list painting. In Caspian pages, manual DOM writes are easy to lose when PulsePoint rerenders the owner template.
+```
+
+`onUploadProgress` receives `{ loaded, total, percent }`; `total` and `percent` may be `null` when the browser cannot compute the upload length. A multipart RPC writes companion non-file values before all `File`/`FileList` parts, so route parameters are available even when the server begins processing a streamed upload before the full request body arrives. A `FileList` is sent as repeated parts under one field name.
+
+Prefer this state-driven shape over manual `innerHTML` list painting. In Caspian pages, manual DOM writes are easy to lose when PulsePoint rerenders the owner template.
 
 ## Persistence Rules
 

package/dist/docs/pulsepoint-runtime-map.md

@@ -50,10 +50,10 @@ If an inspected browser DOM disagrees with authored template source, remember th
 | Conditional UI | `hidden="{!cond}"`, a ternary inside `{...}`, or `pp-for` over a 0/1-length array | `public/js/pp-reactive-v2.js` | **there is no `pp-if`, `pp-show`, or `pp-else`, and no JSX `{cond && <div/>}`**; `hidden` is a bound boolean attribute (Tailwind preflight makes `[hidden]` `display:none !important`, so it beats a `flex`/`grid` utility; without preflight a `display` rule wins); a hidden subtree still renders, so guard with `?.`. See [pulsepoint.md](./pulsepoint.md) "Conditional rendering" |
 | Lists | `<template pp-for="item in items">` | `public/js/pp-reactive-v2.js` | `pp-for` belongs on `<template>`, accepts arrays and synchronous iterables, captures rendered row values for events/props, and uses plain `key`, not `pp-key` |
 | Events | native `onclick`, `oninput`, `onchange`, `onsubmit` | `public/js/pp-reactive-v2.js` | first-party events belong in `on*` attributes; event scope exposes `event`, `e`, `$event`, `target`, `currentTarget`, and `el`; normal form submits should use `Object.fromEntries(new FormData(event.currentTarget).entries())` instead of per-input refs; avoid id-driven `querySelector`/`addEventListener` for normal UI |
-| RPC | `pp.rpc(...)` in scripts, `@rpc()` in Python | `public/js/pp-reactive-v2.js`, `casp/rpc.py` | use `pp.rpc`, not legacy `pp.fetchFunction`; protected actions use `@rpc(require_auth=True)` |
-| Upload progress | `pp.rpc(..., { onUploadProgress })` | `public/js/pp-reactive-v2.js`, `casp/rpc.py` | XHR path is used for progress callbacks; the callback receives `{ loaded, total, percent }` and `percent` can be `null` when length is not computable; replace state from returned payload |
-| Streaming | `pp.rpc(..., { onStream })` | `public/js/pp-reactive-v2.js`, `casp/rpc.py`, `casp/streaming.py` | server generators become SSE responses |
-| SPA navigation | `body[pp-spa="true"]`, links | `public/js/pp-reactive-v2.js`, `main.py` | same-origin eligible links intercept; root-layout mismatches hard reload |
+| RPC | `pp.rpc(...)` in scripts, `@rpc()` in Python | `public/js/pp-reactive-v2.js`, `casp/rpc.py` | use `pp.rpc`, not legacy `pp.fetchFunction`; options include abort, URL/CSRF URL, credentials, streaming, and upload callbacks; protected actions use `@rpc(require_auth=True)` |
+| Upload progress | `pp.rpc(..., { onUploadProgress })` | `public/js/pp-reactive-v2.js`, `casp/rpc.py` | XHR path is used for progress callbacks; the callback receives `{ loaded, total, percent }`, never `percentage`; multipart scalar/object fields precede file parts, and a `FileList` repeats its field name; replace state from returned payload |
+| Streaming | `pp.rpc(..., { onStream })` | `public/js/pp-reactive-v2.js`, `casp/rpc.py`, `casp/streaming.py` | server generators become SSE responses; an `abortPrevious` stream stays cancellable until its final chunk |
+| SPA navigation | links after `pp.mount()`; `a[pp-spa="false"]` opts out | `public/js/pp-reactive-v2.js`, `main.py` | interception is enabled automatically without a body opt-in; same-origin eligible links intercept; root-layout mismatches hard reload |
 | Scroll restoration | `pp-reset-scroll="true"` | `public/js/pp-reactive-v2.js` | push navigation resets window; mark only content panes that should reset |
 | Tailwind merge | `{twMerge(...)}`, Python `merge_classes(...)` | `html_attrs.py`, `public/js/pp-reactive-v2.js` | Python emits frontend-ready expressions when Tailwind is enabled |
 | Markup deferral | `<template pp-component>` / `<template pp-owner>` wrappers | render pipeline (`main.py`), `public/js/pp-reactive-v2.js` (`materializeTemplateComponentBoundaries`) | top-level roots ship inside an inert `<template>`; runtime materializes them on mount and SPA navigation before scanning. Browser never validates `<template>` contents, so `{...}` is safe in any attribute/position (SVG geometry, `src`/`href`, form `value`/date, table/select text) — no per-tag workarounds. See [pulsepoint.md](./pulsepoint.md) "Component markup is deferred inside an inert `<template>`" |

package/dist/docs/pulsepoint.md

@@ -93,9 +93,8 @@ Before writing a template, ask: *"Would this file be valid HTML if I deleted eve
 | `pp-ref="name"` / `pp-ref="{expr}"` | Native elements and `x-*` component tags | Imperative element access |
 | `pp-style="{cssText}"` | Any element | Dynamic inline style, as a **CSS string** |
 | `pp-spread="{...obj}"` | Any element | Spread an object into attributes |
-| `pp-ref-forward` | *Server-set* on component roots — see note below | Ref forwarding through layout-neutral hosts |
-| `<token.provider value="{v}">` (lowercase) | Anywhere in markup | Context provider |
-| `pp-spa="true"` / `pp-spa="false"` | `<body>` enables SPA navigation; `pp-spa="false"` on an `<a>` opts that link out | SPA navigation interception |
+| `<token.provider value="{v}">` (lowercase) | Anywhere in markup | Context provider |
+| `pp-spa="false"` | An `<a>` that must use normal browser navigation | Opt one link out of the SPA interception enabled automatically by `pp.mount()` |
 | `pp-reset-scroll="true"` | A scroll container, or `<body>` | Reset that container's scroll on navigation |
 | `pp-scroll-key="stable-name"` | A scroll container | Stable scroll-restoration identity |
 | `pp-loading-content="true"` | The region swapped during navigation | Marks the navigation content region |
@@ -106,11 +105,11 @@ There is **no** `pp-if`, `pp-show`, `pp-else`, `pp-model`, `pp-bind`, `pp-class`
 
 ### Runtime-managed — never author these
 
-The render pipeline or the browser runtime writes these. Handwriting them corrupts instance tracking:
-
-`pp-component`, `pp-owner`, `pp-event-owner`, `pp-ref-owner`, `pp-ref-forward`, `pp-context-provider` (the generated tag), `pp-context-token`, `pp-context-value`, `pp-root-layout`, `pp-fragment-root`, `data-pp-ref`, `data-pp-input-value`, `data-pp-default-value`, `data-pp-checked-value`, `data-pp-default-checked`, `data-pp-select-value`, `pp-dynamic-script`, `pp-dynamic-meta`, `pp-dynamic-link`.
-
-`pp-ref-forward` appears in the author-facing table only because you will see it in rendered HTML and in composition components; the server component compiler sets it on a root whose own root is another `x-*` component. Do not write it yourself.
+The render pipeline or the browser runtime writes these. Handwriting them corrupts instance tracking or reconciliation:
+
+`pp-component`, `pp-owner`, `pp-event-owner`, `pp-ref-owner`, `pp-ref-forward`, `<pp-context-provider>` (the generated tag), `data-pp-context-token`, `data-pp-context-value`, `data-pp-fragment-root`, `data-pp-script-source`, `data-pp-ref`, `data-pp-input-value`, `data-pp-default-value`, `data-pp-checked-value`, `data-pp-default-checked`, `data-pp-select-value`, `pp-keep`, `pp-keep-run`, and `pp-keep-content`.
+
+The server also emits `meta[name="pp-root-layout"]` for SPA compatibility checks. These names may appear in rendered or transient runtime HTML, but none belongs in authored route or component templates.
 
 ### Component-script hooks (the whole list)
 
@@ -444,18 +443,16 @@ Important:
 - `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
 - Props are not auto-injected as standalone top-level template or handler variables. Read them through `pp.props` or explicitly destructure them in the component script.
 
-Bindings exported to the template:
-
-- Top-level function declarations.
-- Top-level identifier declarations such as `const title = "Pulse"`.
-- Top-level object destructuring identifiers such as `const { title, subtitle } = pp.props`.
-- Top-level array destructuring identifiers when the initializer is `pp.state(...)`, such as `const [count, setCount] = pp.state(0)`.
-
-Bindings that should not be assumed:
-
-- Generic top-level array destructuring is not auto-exported unless it comes from `pp.state(...)`.
-- Nested declarations inside functions, conditions, loops, and callbacks are not auto-exported.
-- There is no standalone `props` variable injected by the runtime. Use `pp.props`.
+Bindings exported to the template:
+
+- Top-level function declarations.
+- Top-level identifier declarations such as `const title = "Pulse"`.
+- Every identifier in a top-level destructuring pattern, regardless of initializer: arrays, objects, nested patterns, defaults, rest elements, and holes. This includes `const { title, subtitle } = pp.props`, `const [count, setCount] = pp.state(0)`, and tuples returned by any other hook or helper.
+
+Bindings that should not be assumed:
+
+- Nested declarations inside functions, conditions, loops, and callbacks are not auto-exported.
+- There is no standalone `props` variable injected by the runtime. Use `pp.props`.
 
 Example:
 
@@ -1213,7 +1210,7 @@ The render pipeline wraps each top-level `pp-component` root in an inert `<templ
 - Plain `pp-ref` bindings are preserved across rerenders, including no-op rerenders that skip DOM diffing.
 - Ref callbacks may be called with `null` during cleanup.
 - The runtime generates `data-pp-ref` internally. Do not author it.
-- Do not author `pp-event-owner`, `pp-owner`, or `pp-dynamic-*` attributes by hand.
+- Do not author `pp-event-owner`, `pp-owner`, or the other runtime-managed names listed above.
 
 Example:
 
@@ -1343,10 +1340,10 @@ Example:
 - Do not replace normal PulsePoint event attributes with id-driven `querySelector(...)` plus `addEventListener(...)` wiring. If an imperative listener is unavoidable for an integration, attach and clean it up from `pp.effect(...)`.
 - Do not replace a normal `onclick` with a `data-action`, `data-target`, or similar attribute plus a script that scans the DOM. PulsePoint event attributes are the event contract for first-party Caspian UI.
 
-## SPA, loading, and navigation helpers
-
-- `body[pp-spa="true"]` enables client-side navigation interception.
-- `a[pp-spa="false"]` disables interception for that link.
+## SPA, loading, and navigation helpers
+
+- `pp.mount()` enables client-side navigation interception automatically; no `<body pp-spa="true">` opt-in is required.
+- `a[pp-spa="false"]` disables interception for that link.
 - External links, downloads, `_blank`, and modifier-key clicks bypass SPA interception.
 - `pp-loading-content="true"` marks the page region that gets swapped or faded during navigation.
 - Route-specific loading states are looked up with `pp-loading-url`.
@@ -1362,18 +1359,22 @@ Example:
 
 RPC notes:
 
-- `pp.rpc(name, data?, optionsOrAbort?)` posts to the current route.
-- Passing `true` as the third argument means `abortPrevious: true`.
-- The options object supports `abortPrevious`, `onStream`, `onStreamError`, `onStreamComplete`, `onUploadProgress`, and `onUploadComplete`.
-- File uploads switch to the XHR path when upload progress callbacks are needed.
-- The `onUploadProgress` callback receives `{ loaded, total, percent }`. `percent` is a 0-100 number, and both `total` and `percent` are `null` when the browser cannot compute the upload length. Do not document or generate `event.percentage`.
-- For file managers, use upload callbacks for progress UI but replace the asset list from returned RPC state with `pp.state(...)` and `pp-for` instead of manual DOM repainting. See [file-uploads.md](./file-uploads.md).
-- Streamed `text/event-stream` responses are supported when a stream handler is provided. Each `onStream` chunk is JSON-parsed when the event data looks like JSON; otherwise the raw string is passed through. If the response streams but no `onStream` handler was given, the runtime warns and discards the stream.
-- Redirect headers are honored through `pp.redirect()`.
+- `pp.rpc(name, data?, optionsOrAbort?)` posts to the current route.
+- Passing `true` as the third argument means `abortPrevious: true`.
+- The complete options object supports `abortPrevious`, `url`, `csrfUrl`, `credentials`, `onStream`, `onStreamError`, `onStreamComplete`, `onUploadProgress`, and `onUploadComplete`.
+- `url` overrides the current-route RPC URL. `csrfUrl` overrides the URL used for the preliminary CSRF-cookie bootstrap GET. `credentials` is a standard Fetch `RequestCredentials` value; same-origin calls default to `"same-origin"` and cross-origin overrides default to `"include"`.
+- When `abortPrevious` is enabled, a later aborting call cancels the active request and the cancelled promise resolves to `{ cancelled: true }`. A streamed response remains the active request until its final chunk, so it can still be cancelled after the response headers and early chunks have arrived.
+- File uploads switch to the XHR path when upload progress callbacks are needed.
+- A payload containing a `File` or non-empty `FileList` becomes multipart. The runtime writes every non-file field before the first file so a streaming server upload handler can read companion arguments even when the caller's object listed a file first. Objects are JSON-stringified, nullish fields are omitted, and a `FileList` becomes repeated parts under its original field name.
+- The `onUploadProgress` callback receives `{ loaded, total, percent }`. `percent` is a 0-100 number, and both `total` and `percent` are `null` when the browser cannot compute the upload length. Do not document or generate `event.percentage`.
+- `onUploadComplete` belongs to the same XHR progress path and runs only after a successful upload response (and any accepted redirect).
+- For file managers, use upload callbacks for progress UI but replace the asset list from returned RPC state with `pp.state(...)` and `pp-for` instead of manual DOM repainting. See [file-uploads.md](./file-uploads.md).
+- Streamed `text/event-stream` responses are supported when a stream handler is provided. Each `onStream` chunk is JSON-parsed when the event data looks like JSON; otherwise the raw string is passed through. If the response streams but no `onStream` handler was given, the runtime warns and discards the stream.
+- Same-origin `X-PP-Redirect` headers (and redirect-status `Location` headers) are honored through `pp.redirect()`. Invalid or cross-origin server redirect targets are ignored.
 
 Notes:
 
-- `pp.redirect()` uses SPA navigation for same-origin URLs when SPA mode is enabled. Otherwise it falls back to normal navigation.
+- After the runtime mounts, `pp.redirect()` uses SPA navigation for same-origin URLs. Cross-origin targets use normal browser navigation.
 - Root-layout mismatches during SPA navigation trigger a hard reload.
 - `pp.mount()` bootstraps every `[pp-component]` it finds, so generated code should call it only through the global runtime if you are manually mounting at all.
 
@@ -1493,20 +1494,14 @@ JSX constructs in markup — these are the highest-frequency generation failure,
 
 Also avoid:
 
-- React, Vue, Svelte, Alpine, HTMX, or JSX-first patterns as the default Caspian frontend approach
-- standard DOM scripting as the default first-party interaction model, including id/data-attribute driven `querySelector(...)`, `addEventListener(...)`, or manual `innerHTML` rendering for normal buttons, forms, filters, toggles, uploads, and reactive lists
-- `pp-context`
-- `pp-key`
-- `data-pp-ref`
-- `pp-context-provider`
-- `pp-owner`
-- `pp-event-owner`
-- `pp-dynamic-script`
-- `pp-dynamic-meta`
-- `pp-dynamic-link`
+- React, Vue, Svelte, Alpine, HTMX, or JSX-first patterns as the default Caspian frontend approach
+- standard DOM scripting as the default first-party interaction model, including id/data-attribute driven `querySelector(...)`, `addEventListener(...)`, or manual `innerHTML` rendering for normal buttons, forms, filters, toggles, uploads, and reactive lists
+- `pp-context`
+- `pp-key`
+- any runtime-managed name listed in [Runtime-managed — never author these](#runtime-managed--never-author-these)
 - handwritten `pp-component="..."` in authored route, layout, or component templates
-- `pp.fetchFunction()` as the current raw runtime helper name
-- made-up hooks, directives, or globals not present in the current bundled runtime
+- `pp.fetchFunction()` as the current raw runtime helper name
+- made-up hooks, directives, or globals not present in the current bundled runtime
 
 ## Review notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {