caspian-utils 0.1.14 → 0.1.15

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

@@ -39,7 +39,7 @@ If an inspected browser DOM disagrees with authored template source, remember th
 | Refs | `pp.ref(...)`, `pp-ref` | `pp-reactive-v2.js` | generated ref internals are runtime-managed; do not author `data-pp-ref` |
 | Context | `pp.createContext(...)`, lowercase `<themecontext.provider>`, `pp.context(token)` | `TemplateCompiler.ts`, `NestedBoundaryManager.ts`, `pp-reactive-v2.js` | authored provider tags are HTML-first and lowercase; `TemplateCompiler.transformContextProviderTags(...)` rewrites `*.provider` to runtime-owned `pp-context-provider`; ancestry is logical component ancestry; do not invent `pp-context` or `pp.provideContext` |
 | Portals | `pp.portal(ref, target?)` | `pp-reactive-v2.js` | context should preserve logical ancestry through the registry |
-| Lists | `<template pp-for="item in items">` | `pp-reactive-v2.js` | `pp-for` belongs on `<template>`, use plain `key`, not `pp-key` |
+| Lists | `<template pp-for="item in items">` | `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` | `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 | `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 })` | `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 |

package/dist/docs/pulsepoint.md

@@ -419,7 +419,7 @@ Notes:
 
 - The global `pp` singleton auto-mounts once the runtime is loaded and the DOM is ready. Manual `pp.mount()` is still safe because it short-circuits after the first mount.
 - `pp.state` setters accept either a value or an updater function.
-- `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. Returned promises are not awaited.
+- `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. They may return only a synchronous cleanup function; returning a promise warns and is ignored, so start async work inside the effect instead.
 - `pp.portal(ref)` defaults to `document.body` when no target is provided.
 - Older docs may call the RPC helper `pp.fetchFunction()`. In the current bundled runtime the implemented global API is `pp.rpc()`.
 - Keep template-facing bindings at the top level so the AST-based exporter can see them.
@@ -593,12 +593,13 @@ Nested components:
 - `pp-style` is an authoring alias. The compiler rewrites it to a native `style` attribute in rendered output.
 - If the same element already has a static `style` attribute, `pp-style` is merged into that `style` value during compilation.
 - Mixed text like `class="card {isActive ? 'active' : ''}"` is supported.
-- Arrays in template expressions are joined without commas.
-- `null`, `undefined`, and boolean expression results render as an empty string in text output.
+- Arrays in template expressions are joined without commas.
+- `null`, `undefined`, and boolean expression results render as an empty string in text output.
+- Plain objects, functions, and symbols are invalid template children; the runtime warns and omits them instead of rendering accidental strings such as `[object Object]`.
 - Supported boolean attributes are normalized so truthy values emit the bare attribute and falsy values remove it.
 - `<textarea value="{draft}"></textarea>` is normalized into textarea content.
 - Use `pp-spread="{...attrs}"` to spread an object expression into attributes.
-- `pp-spread` omits nullish values and escapes `&`, `"`, and `<` in emitted attribute values.
+- `pp-spread` omits nullish values, omits known HTML boolean attributes when their value is `false`, emits them bare when `true`, preserves string-valued `aria-*`/`data-*` booleans, and escapes `&`, `"`, and `<` in emitted attribute values.
 - Use plain `key` for keyed diffing. `pp-key` is not implemented.
 
 Example:
@@ -659,9 +660,9 @@ Example:
 
 - Use `pp-for` only on `<template>`.
 - Supported forms are `item in items` and `(item, index) in items`.
-- The collection must be an array. Non-arrays are treated as empty lists.
+- Collections may be arrays or synchronous iterables such as `Set`, `Map`, typed arrays, strings, and generators. Non-null non-iterable values warn and render as empty lists.
 - Loop content can contain interpolations, events, refs, and nested components.
-- Event handlers inside loops are rewritten so loop variables still resolve after rerender.
+- Event handlers inside loops capture each rendered item, so later collection changes do not retarget an existing row handler.
 - Use stable unique `key` values on repeated sibling elements.
 - Duplicate keys trigger warnings and reduce diff quality.
 - Keyed reconciliation preserves DOM identity across reorders and insertions.
@@ -718,8 +719,9 @@ Example:
 - Push navigation resets window scroll to the top.
 - Saved history-entry scroll state is used during history traversal instead of relying only on the live DOM scroll at the time the user clicks Back or Forward.
 - Unmarked scrollable containers may keep their outgoing scroll on push navigation so shared shells such as sidebars, rails, and docs nav panes stay stable across child-route changes.
-- `pp-reset-scroll="true"` on a scroll container opts that container into reset-on-navigation behavior. Use it on the main content pane of a grouped shell when page content should start at the top on each child-route navigation.
-- `body[pp-reset-scroll="true"]` is the global override for routes that should reset window scroll and every scrollable element.
+- `pp-reset-scroll="true"` on a scroll container opts that container into reset-on-navigation behavior. Use it on the main content pane of a grouped shell when page content should start at the top on each child-route navigation.
+- `pp-scroll-key="stable-name"` gives a scroll container a stable restoration identity. Prefer it when an element has no stable `id`, or when its classes or position can change between routes.
+- `body[pp-reset-scroll="true"]` is the global override for routes that should reset window scroll and every scrollable element.
 - Navigation dispatches `pp:navigation:start`, `pp:navigation:complete`, and `pp:navigation:error` events on `document`.
 
 RPC notes:

package/package.json

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