@plitzi/sdk-server 0.38.10 → 0.38.11

package/dist/modules/realtime/handlers.js

@@ -1,9 +1,10 @@
 import onAbort from "../../helpers/onAbort.js";
 import { openEventStream } from "../../core/http/sse.js";
 import { warnRealtime } from "./failure.js";
+import { readCookies } from "../../core/auth/credentials.js";
 import { accessRefusal } from "@plitzi/sdk-shared/actions";
 import { randomBytes, randomUUID } from "node:crypto";
-import { PRESENCE_TYPE, channelLimits, matchChannel } from "@plitzi/sdk-shared/realtime";
+import { OBSERVER_COOKIE_NAME, PRESENCE_TYPE, channelLimits, matchChannel } from "@plitzi/sdk-shared/realtime";
 //#region src/modules/realtime/handlers.ts
 /** Topics one connection may hold. A page shows a handful; past this it is somebody enumerating. */
 var MAX_TOPICS = 8;
@@ -91,7 +92,8 @@ var admit = async (req, resolveChannels, grants) => {
 		} } : {},
 		accepted,
 		granted,
-		refused
+		refused,
+		observer: Object.hasOwn(readCookies(req), OBSERVER_COOKIE_NAME)
 	};
 };
 /** A new connection for what was admitted, speaking through `send`. */
@@ -103,6 +105,7 @@ var connectionFor = (admission, send, end) => ({
 	topics: admission.accepted,
 	grants: admission.granted,
 	announced: /* @__PURE__ */ new Set(),
+	observer: admission.observer,
 	sent: /* @__PURE__ */ new Map(),
 	send,
 	end
@@ -123,7 +126,7 @@ var withinRate = (connection, topic, perSecond) => {
 * may send on, within its size and its rate — and stamped by the server with who sent it and when, whatever the
 * message said.
 */
-var publishFrom = async (hub, connection, { topic, type, data }) => {
+var publishFrom = async (hub, connection, { topic, type, data, echo }) => {
 	const name = typeof topic === "string" ? topic : "";
 	const declaration = connection.topics.get(name);
 	if (!declaration) return {
@@ -136,6 +139,7 @@ var publishFrom = async (hub, connection, { topic, type, data }) => {
 		error: `Only the server publishes on "${name}"`,
 		reason: "server_only"
 	};
+	if (connection.observer) return { status: 204 };
 	const kind = typeof type === "string" ? type : "";
 	const presence = kind === PRESENCE_TYPE && declaration.presence === true;
 	if (!presence && !TYPE.test(kind)) return {
@@ -157,7 +161,7 @@ var publishFrom = async (hub, connection, { topic, type, data }) => {
 	};
 	if (presence) connection.announced.add(name);
 	try {
-		await hub.publish(connection.space, hub.from(connection, name, kind, value));
+		await hub.publish(connection.space, hub.from(connection, name, kind, value, echo === true && !presence));
 	} catch (error) {
 		warnRealtime("a message was not delivered")(error);
 		return {

package/dist/modules/realtime/hub.d.ts

@@ -18,6 +18,8 @@ export type RealtimeConnection = {
     grants: Map<string, string>;
     /** The topics it announced itself on, which hear `$leave` when it goes. */
     announced: Set<string>;
+    /** A page that watches (`page check`, `page shot`): it hears its topics, arrives on none and says nothing on any. */
+    observer: boolean;
     /** Messages sent this second, by topic — the rate a channel allows is per connection, and a connection is here. */
     sent: Map<string, {
         second: number;
@@ -38,7 +40,7 @@ export type RealtimeHub = ReturnType<typeof createRealtimeHub>;
  */
 export declare const createRealtimeHub: (pubsub: PubSubAdapter) => {
     publish: (space: RealtimeSpace, message: RealtimeMessage) => Promise<void>;
-    from: (connection: RealtimeConnection, topic: string, type: string, data: unknown) => RealtimeMessage;
+    from: (connection: RealtimeConnection, topic: string, type: string, data: unknown, echo?: boolean) => RealtimeMessage;
     find: (token: string) => RealtimeConnection | undefined;
     /**
      * Lets go of `topic` every connection, on every replica, that opened it with `grant` — or with any grant, naming

package/dist/modules/realtime/hub.js

@@ -65,14 +65,18 @@ var createRealtimeHub = (pubsub) => {
 			await (await entry.release)();
 		}
 	};
-	/** A stamped message from this connection: `from` and `user` are the server's, whatever was sent. */
-	const from = (connection, topic, type, data) => ({
+	/**
+	* A stamped message from this connection: `from` and `user` are the server's, whatever was sent. `echo` carries the
+	* sender's asking to hear it too, which its page reads.
+	*/
+	const from = (connection, topic, type, data, echo = false) => ({
 		topic,
 		type,
 		data,
 		from: connection.id,
 		...connection.user ? { user: connection.user } : {},
-		at: Date.now()
+		at: Date.now(),
+		...echo ? { echo: true } : {}
 	});
 	/**
 	* Lets `connection` go of `topic`: it is told, the others on a presence channel hear it leave, and it no longer
@@ -111,7 +115,7 @@ var createRealtimeHub = (pubsub) => {
 			byToken.set(connection.token, connection);
 			for (const [topic, declaration] of connection.topics) {
 				await join(connection, topic);
-				if (declaration.presence) await publish(connection.space, from(connection, topic, JOIN_TYPE, null));
+				if (declaration.presence && !connection.observer) await publish(connection.space, from(connection, topic, JOIN_TYPE, null));
 			}
 		},
 		/** Unsubscribes a connection that went away, and tells the channels it announced itself on. */

package/dist/modules/ssr/prepareRender.js

@@ -1,5 +1,6 @@
 import { requestFlagOverrides } from "../../helpers/flagOverrides.js";
 import { authorizesDebugging } from "../../helpers/debugAuthorization.js";
+import { SPACE_TOKEN_PARAM } from "../../core/auth/credentials.js";
 import { realtimeModuleFor } from "../realtime/index.js";
 import { matchRscPage } from "../rsc/matchRscPage.js";
 import { ssrPaintedCookieName } from "../../helpers/paintedCookie.js";
@@ -14,7 +15,6 @@ import { publishSpaceDocument } from "./spaceDocument.js";
 import { registerExternalPlugins } from "./registerExternalPlugins.js";
 import { reportMissingPlugins } from "./reportMissingPlugins.js";
 import { resolvePageSeo } from "./resolvePageSeo.js";
-import { SPACE_TOKEN_PARAM } from "../../core/auth/credentials.js";
 import { imagesPathOf } from "../../core/http/stages/images.js";
 import { sdkAssetVersion } from "../../core/sdkAssets.js";
 import { buildServerInfo } from "../../helpers/buildServerInfo.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.10",
+  "version": "0.38.11",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -96,8 +96,8 @@
     "./dist/env.js"
   ],
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.10",
-    "@plitzi/sdk-shared": "0.38.10",
+    "@plitzi/plitzi-sdk": "0.38.11",
+    "@plitzi/sdk-shared": "0.38.11",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -19,6 +19,7 @@ const space: SpaceSpec = {
   pages: [{ id, name, slug: '', layout: { id: 'shell', slot: 'main' }, body: [] }]   // slot: where the body goes
 };                                             // slug '' is home; 'products/:slug' takes a param
 pageFamily({ folder, layout, seoTitle, body: entry => [...] }, ENTRIES)   // pages of one shape, from data; ids scoped per page
+pageFolders: [{ id: 'docs', name: 'Docs' }]                               // on the space: a `folder` is declared here, /docs/…
 const { schema, style, warnings, suggestions } = authorSpace(space, { plugins: [declaration] });
 ```
 
@@ -43,6 +44,7 @@ svg(svgFile(new URL('./logo.svg', import.meta.url)))  // a file, compacted: svgF
 fontAwesome({ icon: 'fa-solid fa-xmark' })
 list({ id: 'rows', items: 'p.data.rows', row: 'row-card' })    // a <ul>; a component per row, its root an <li>
 list({ id: 'rows', items: 'p.data.rows', row: r => listItem({ children: [text({ from: `${r.item}.title` })] }) })
+// typed items (site.data.rows): r.item is a path — from: r.item.title
 carousel({ id: 'hero', items: 'p.data.slides', autoplay: 5000, row: 'slide-card', children: [/* carouselNext('hero') arrows */] })
                                                // rows follow their item's `id`, or `itemKey: 'slug'`
 apiContainer({ id: 'p', query: '/data/x.json', cache: true, children })   // publishes p.data; no box of its own
@@ -63,7 +65,7 @@ const card = styles('card', { padding: 24, borderRadius: 16 });        // shorth
 styles('title', { fontSize: { desktop: '48px', compact: '32px' }, fontWeight: 700 });   // one property per breakpoint
 styles('card', { css: { desktop: { … }, compact: { … } }, states: { hover: { … } }, variants: { active: { … } } });
 container({ class: card });                                    // a shared class…
-container({ id: 'hero', class: [card, { opacity: '0.5' }] });  // …plus one thing (needs an id)
+container({ class: [card, { opacity: '0.5' }] });              // …plus one thing
 container({ css: { padding: '8px' } });                        // rules of its own — never with `class`
 ```
 

package/skills/plitzi-authoring/recipes/style-a-page.ts

@@ -1,6 +1,6 @@
 /**
  * Style without copies: colours are tokens with a light and a dark value, a look used twice is a class, "this class
- * plus one thing" is rules on top of it (`class: [card, { … }]`, which needs an `id`), and a rule for tablet AND phone
+ * plus one thing" is rules on top of it (`class: [card, { … }]`), and a rule for tablet AND phone
  * is written once under `compact`.
  */
 import { container, heading, styles, text } from '@plitzi/sdk-authoring';

package/skills/plitzi-authoring/reference/accessibility.md

@@ -38,6 +38,7 @@ image({ src: '/grain.png', decorative: true })                      // an orname
 image({ decorative: true, bind: { src: 'post.record.cover' } })     // a cover under its own headline adds nothing
 image({ bind: { src: 'row.item.cover', alt: 'row.item.title' } })   // …unless it is alone in a link: then it names it
 fontAwesome({ icon: 'fa-solid fa-triangle-exclamation', label: 'Overdue' })  // an icon that says something alone
+svg(MARK, { class: logoMark })                                       // no `label`: an svg or an icon decorates
 text('福', { decorative: true })                                     // a seal or a mark drawn for the look alone
 list({ label: 'Kinds of capsule', … })                               // a group of options is named, as a group
 ```

package/skills/plitzi-authoring/reference/authoring-errors.md

@@ -47,7 +47,7 @@ The space is not written until these are fixed.
 | `channel-grant` | a topic of a private channel opened with no grant to it | the grant the message names, or a public channel |
 | `channel-topic` | a `channel` element with no topic | a topic a channel of the space covers |
 | `children-in-leaf` | children on a type that renders only its own attributes (`heading`, `text`, `image`…) | a `container` — for a heading made of parts, `container({ subType: 'h1', children })` |
-| `class-and-css` | an element wearing a shared class AND `css` or `states` of its own — it has one base selector | the rules on top of the class: `class: [card, { opacity: '0.5' }]` (needs an `id`) — or into the class |
+| `class-and-css` | an element wearing a shared class AND `css` or `states` of its own — it has one base selector | the rules on top of the class: `class: [card, { opacity: '0.5' }]` — or into the class |
 | `class-and-selector` | an element with a shared class and a `selector` of its own | drop one: a shared class IS its selector |
 | `class-conflict` | two different declarations for one class name | rename one, or make them agree |
 | `class-listed-under-other-name` | a `styles()` declaration listed in `classes` under another name | list it under its own name |
@@ -64,6 +64,7 @@ The space is not written until these are fixed.
 | `css-property-twice` | one property written twice in a rule set — `paddingTop` beside `'padding-top'` — so one would silently win | keep one |
 | `css-property-unknown` | a CSS property that does not exist | the property it suggests; a custom property starts with `--` |
 | `css-value` | an empty CSS value, or one with `;` or `{}` | one value per property; leave a property out instead of writing it empty |
+| `declared-callback-target` | a `declaredCallback` target with a key beside `on` and `params` — read nowhere, so the step runs without it | the value in `params`: `{ on: 'calendar', params: { date } }` |
 | `element-ids-target` | a step refreshing containers by id (`invalidateElements`, `invalidateQueries({ elements })`) naming one the space does not have, or one that is not an `apiContainer` | the id of the `apiContainer` whose data the step changes: `invalidateElements: ['posts']` |
 | `element-load-strategy` | a `loadStrategy` the element does not take | one of the values the message lists |
 | `element-rejected` | an element the schema refused to hold | the problem listed with it |
@@ -79,7 +80,7 @@ The space is not written until these are fixed.
 | `flow-empty` | a flow with no steps | `[onClick(), setState({ … })]` |
 | `flow-without-trigger` | a flow whose first step is not the event that runs it | `[onClick(), setState(…)]` |
 | `folder-cycle` | a page folder inside itself | a `parent` that leads to the top |
-| `folder-undeclared` | a page, a layout or a folder filed in a folder the space does not declare | declare the folder, or the name it suggests |
+| `folder-undeclared` | a page, a layout or a folder filed in a folder the space does not declare | declare it on the space — `pageFolders: [{ id: 'docs', name: 'Docs' }]`, its slug starting its pages' addresses — or use the name it suggests |
 | `font-invalid` | a font the space cannot load as declared | the field the message names |
 | `format-unknown` | an `as` that names no format of the space's `formats` | declare it once — `formats: { price: "{{ source\|currency('USD') }}" }` — or write the template in its place |
 | `from-and-bind` | the main attribute bound twice, with `from` and in `bind` | keep `from`, and give `bind` the other attributes |
@@ -97,7 +98,6 @@ The space is not written until these are fixed.
 | `list-without-items` | a controlled list with nothing to render | `items: [ … ]` or `bind: { items: 'provider.data.rows' }` |
 | `loading-slot-unknown` | an `apiContainer`'s `loadingSlot` that is not the id of one of its children | the id of the child to show until the first answer — `loadingSlot: 'catalog-skeleton'` beside that child |
 | `modifier-count` | more than one set of rules in a class list | one set, after the classes: `class: [card, { opacity: '0.5', 'margin-top': '8px' }]` |
-| `modifier-without-id` | rules on top of a class on an element with no `id` — the id names the class they become | `id: 'hero-bg'` |
 | `motion-invalid` | a `motion` with a preset, a trigger or a timing the page cannot play | `motion: { enter: 'fade-up', on: 'view' }` — the message lists the presets |
 | `motion-no-tag` | a `motion` on an element with no tag of its own — nothing to move | the motion on what it wraps, or a `subType` on it |
 | `no-pages` | a space with no pages | `pages: [{ id: 'home', name: 'Home', slug: '', body: [] }]` |
@@ -132,6 +132,7 @@ The space is not written until these are fixed.
 | `server-provider-in-component` | a `runtime: 'server'` element inside a component: the page server resolves a page's and its layouts', never a component's | put the provider on the page, around the instance, and hand the component its rows as a prop |
 | `setting-misplaced` | `settings.computed` or `settings.channels` written inside `settings` | `computed` and `channels` at the top of the space |
 | `slot-children` | children handed to an instance outside its slots | `children: { slotName: [ … ] }`; a component with no slots takes no children |
+| `slot-not-class` | a `slots` entry that is not a class — rules written in place, or nothing — which a slot cannot wear | the rules as a `styles()` declaration, handed to the slot beside its other classes |
 | `slot-unknown` | a component slot that is not an element of its tree | the id of an element inside the component — usually an empty container |
 | `source-field-unknown` | a path into a typed source that its sample does not have | read a field the sample has, or add the field to the sample |
 | `state-key-list` | `settings.transientState` / `paintedState` that is not a list of top-level state keys | `transientState: ['demoStep']` — a dotted path names its top key |
@@ -146,6 +147,7 @@ The space is not written until these are fixed.
 | `style-pseudo-unknown` | a pseudo-element a class cannot dress | one of `before`, `after`, `marker`, `placeholder`, `first-letter`, `first-line`, `selection` — without the `::` |
 | `style-state-unknown` | a state a selector does not react to | one of the states it lists (`hover`, `focus`, `active`…) |
 | `svg-not-svg` | an `svg` whose `content` is not one `<svg>…</svg>` — it draws nothing | the SVG markup alone; HTML around it goes in a `blockHtml` |
+| `template-in-value` | a `{{ }}` inside an attribute that is an object or a list — a provider's `input`, a list's `items`, a plugin's settings: only an attribute that is text is evaluated | a binding on the attribute (`bindTemplate(name, source, template, { returns: 'value' })`); for a provider's `input`, nothing for a route or query param — the action is already handed them as `input.<name>` |
 | `template-short-source` | a source named without its prefix inside a template or a step | the full name: `apiContainer_stats`, `list_rows` |
 | `template-source-out-of-scope` | a template reading the source of an element it is not inside | move the element inside it, or share the value through `state` |
 | `template-text-into-value` | a template, which renders text, feeding an attribute that holds a list or an object | `bindTemplate('items', source, '{{ … }}', { returns: 'value' })` |

package/skills/plitzi-authoring/reference/data-and-visibility.md

@@ -18,6 +18,8 @@ the value), or a format the space names once in `formats: { price: "{{ source|cu
 `bindTemplate(to, source, template, { category?, returns? })` is the computed attribute — a template over the value
 at `source`. `returns: 'value'` hands over what a single `{{ expression }}` evaluates to instead of its text: a list's
 `items`, a number, a flag (see [lists](lists.md)).
+A colour from data binds a custom property — `[{ to: '--who', source, category: 'style' }]` — that the class reads
+(`var(--who, var(--muted))`); a value with `;` or braces is not written.
 
 **A source names the id you gave the element** — `'posts.title'`, `'postList.item.cover'` — and the prefix is
 completed from what the element publishes (`apiContainer_posts`, `list_postList`; a `form` publishes under
@@ -72,6 +74,8 @@ apiContainer({ id: 'board', runtime: 'server', action: 'queue-board' })
   `"{{ source ? apiUrl ~ '/workspaces/' ~ source ~ '/stats' : '' }}"` with `source: 'state.workspace.id'`. A server
   provider's bound `input` (`bindTemplate('input', 'state.c', '{{ { country: source } }}', { returns: 'value' })`)
   asks again on every change; `reloadApi('p', { … })` asks once.
+- An action is handed the page's route and query params as input (`r/:room` → `input.room`). A written `input` is
+  sent as is: a `{{ }}` in it is refused (`template-in-value`) — bind it.
 - `isLoading` is true while it is asked again, in either runtime. A newer ask drops the older one; `cancelApi('p')` is a
   STOP: what is shown stays.
 - `runtime: 'server'` is resolved by the page server — server data is on unless a space says `rsc: { enabled: false }`.
@@ -106,9 +110,8 @@ server action answering only what is shown, its `access` checking who asks.
 - **Refreshed by writes:** a `webHook` that is not a GET refreshes every request to its own site by default
   (`invalidateQueries: 'origin'`); a `runServerAction` refreshes everything (`'all'`). Narrow it with
   `'elements'` + `invalidateElements: ['orders']`, or stop it with `'none'`.
-- **Say `'none'` when a refresh would move the page on.** A page that decides where to go from a provider's answer
-  ("profile complete → leave") will act on the refreshed answer in the middle of a multi-step form that saves as it
-  goes, and skip the last step.
+- **Say `'none'` when a refresh would move the page on.** A page that leaves on a provider's answer ("profile complete
+  → leave") would leave in the middle of a multi-step form that saves as it goes.
 
 ## Visibility
 
@@ -156,10 +159,9 @@ Rules for a condition's template:
   `'true'` or `'false'` is written as it says. A plain source, or a template that answers nothing (`''`), writes
   nothing: the element stays as it started — hidden for `visible`, shown for a binding written by hand.
 - **So a hiding flag is `visible: '!state.folded'`** (or a binding with no `visible`): on screen before anybody has set
-  it. A condition that answers "not known yet" with `'false'` from a value that IS there — a "folded" read off
-  something always set — hid every label of a sidebar for everybody.
-- **Hide the element itself.** Never wrap it in a container that is shown while the inner one is hidden: an empty
-  visible wrapper still takes a slot in its parent's `gap`, and leaves a hole in the page.
+  it.
+- **Hide the element itself**, not inside a wrapper left shown: an empty wrapper still takes a slot in its parent's
+  `gap`, a hole in the page.
 
 ### Loading, empty, error
 
@@ -183,9 +185,8 @@ shows on every load. Test for "arrived and empty" (`is defined and … is empty`
 
 ## Never ask the data for an opposite
 
-Both sides of one question are `visible: 'x'` and `visible: '!x'`, not an `x` and a `notX` in the server's answer.
-`!` reads a boolean that travelled as text (`"false"`, `"0"`) correctly. A three-state condition
-(`Boolean(post) && !canEdit`) still belongs where the data is made.
+Both sides of one question are `visible: 'x'` and `visible: '!x'`, never a `notX` in the answer — `!` reads `"false"`
+and `"0"` as false. A three-state condition still belongs where the data is made.
 
 ## State that outlives a reload
 

package/skills/plitzi-authoring/reference/flows.md

@@ -70,11 +70,11 @@ a row's button posts `{ jobId: '{{ list_jobRows.item.id }}' }` — the row that
 
 **Pass objects, not JSON text.** `input: { title: '{{ form.values.title }}' }` rather than `input: '{"title": …}'`:
 each value keeps its own type, and nothing depends on the quoting. (JSON text works — a value inside one of its strings
-is escaped for it — but an object says the same without the punctuation.)
+is escaped for it — but an object needs no punctuation.)
 
 **A field left empty is not in `values`.** A form sends what was typed, and a field nobody typed in sends nothing —
 so `when({ field: 'sent.values.code', operator: '=', value: '' }, …)` never holds for it. Ask
-`operator: 'empty'` / `'notEmpty'`, which treat missing and `''` alike.
+`operator: 'empty'` / `'notEmpty'` (no `value`), which treat missing and `''` alike.
 
 ## Writes and what they refresh
 

package/skills/plitzi-authoring/reference/layouts.md

@@ -25,6 +25,7 @@ export const docsLayout: LayoutSpec = {
 };
 
 // in the space
+pageFolders: [{ id: 'docs', name: 'Docs' }],   // declared once: its slug (the id) starts its pages' addresses — /docs/quickstart
 layouts: [appLayout, docsLayout],
 pages: [{ name: 'Quickstart', slug: 'quickstart', folder: 'docs', layout: { id: 'docs-layout', slot: 'docs-slot' }, body: [ … ] }]
 ```

package/skills/plitzi-authoring/reference/lists.md

@@ -9,6 +9,7 @@ list bound to its records (see the provider in data-and-visibility).
 ```ts
 list({ id: 'games', class: gameGrid, items: 'catalog.data.games', row: 'game-card' })   // a component per game
 list({ id: 'games', items: 'catalog.data.games', row: r => listItem({ children: [text({ from: `${r.item}.title` })] }) })
+// typed by a sample (`items: catalog.data.games`): `r.item` is a path — `from: r.item.title`, never `${r.item}.title`
 list({ id: 'plans', items: ['Free', 'Pro'], children: [listItem({ children: [text({ from: 'plans.item' })] })] })  // fixed
 ```
 

package/skills/plitzi-authoring/reference/plugins.md

@@ -83,8 +83,8 @@ import { elementChildren } from '@plitzi/plitzi-sdk';
 ```
 
 Never write `style` onto an element the plugin does not render: nothing promises to keep it. Its boxes share one
-stacking context, the plugin's. `useDisplayMode()` names the breakpoint showing — `desktop`, `tablet` or `mobile` — at
-the widths the space's styles use, instead of a width of the plugin's own.
+stacking context, the plugin's. `useDisplayMode()` names the breakpoint showing (`desktop`, `tablet`, `mobile`) at the
+space's widths; `useElementSize(ref)`, its own box (`undefined` until measured).
 
 ## Its own server code
 
@@ -108,6 +108,7 @@ import { useChannel } from '@plitzi/plitzi-sdk';
 
 const room = useChannel(roomTopic, { onMessage: message => move(message.from, message.data) });
 room.publish('pointer', { x, y });   // throttle it: ~20 a second, the latest position each time
+room.publish('react', { emoji }, { echo: true }); // and heard here too
 room.members;                        // who is here, with the state each announced
 ```
 

package/skills/plitzi-authoring/reference/realtime.md

@@ -14,7 +14,10 @@ channel({ id: 'room', topic: 'room:{{ id }}', keep: 0, bind: { presence: 'comput
 
 Its descendants bind `room.members`, `room.connected`, `room.last`; flows use `on('onMessage')` (`type`, `data`,
 `from`), `onJoin`/`onLeave` (`from`, `user` and the `state` the member announced — `onJoin` only for who came after
-this page), `publishOn('room', 'reaction', data)` and `announceOn('room', state)`. State everyone must
+this page), `publishOn('room', 'reaction', data)` and `announceOn('room', state)`. What a page publishes reaches
+every OTHER page on the topic: one that shows it the moment it sends — a reaction, a chat line — says
+`publishOn('room', 'reaction', data, { echo: true })` and hears it back once the server took it (its `from` is
+`room.me`). What a server action publishes reaches every page, the one that ran it included. State everyone must
 agree on goes through a server action whose last step is `realtime.publish` — validated and saved first, announced
 after.
 

package/skills/plitzi-authoring/reference/typed-sources.md

@@ -13,10 +13,12 @@ apiContainer({ id: site.id, query: '/data/home.json', children: [
 ] })
 ```
 
-- A path is the source's full name (`apiContainer_site.data.hero.title`), so it goes in `from`, `items`, `bind` and
-  `visible` as it is, and into a template through `twig` (a plain template literal writes the same text, but a
-  type-checked lint refuses an object in one).
-- A list fed by a path hands its `row` the item typed: every field any item of the sample has.
+- A path is the source's full name (`apiContainer_site.data.hero.title`), so it goes in `from`, `items`, `bind`,
+  `visible` and the binding helpers (`bindTemplate`, `visibleWhen`, `hiddenWhen`, `variantFrom`) as it is, and into a
+  template through `twig` (a plain template literal writes the same text, but a type-checked lint refuses an object in
+  one).
+- A list fed by a path hands its `row` the item typed: every field any item of the sample has — `p.item`, `p.index`,
+  and `p.inTemplate` as an untyped row has it, so turning a list typed changes none of its templates.
 - An item of a list is read by position: `site.data.sections[1]`.
 - A provider fed by a server action publishes the action's output at its root: `actionSource('feed', sample)` types
   it — `feed.stories`, and `feed.data` is a type error — with a sample of what the action's last step answers.