@plitzi/sdk-server 0.38.9 → 0.38.11

package/dist/modules/project/serveProject.js

@@ -7,11 +7,14 @@ import { freePort } from "../../core/freePort.js";
 import { createCloudAdapters } from "../../adapters/cloudAdapters.js";
 import { createJsonAdapters } from "../../adapters/jsonAdapters.js";
 import { createFileKv } from "../actions/runtime/fileKv.js";
+import { credentialsFromEnv } from "../actions/runtime/credentials.js";
 import { loadRuntime, loadRuntimeModule } from "../runtime/bundle.js";
 import { serveRuntime } from "../runtime/stages.js";
 import { projectPlugins, watchProjectPlugins } from "./plugins.js";
 import { createSpaceFailure } from "./spaceFailure.js";
 import { watchSpace } from "./watchSpace.js";
+import { fleetKv } from "../../core/server/fleet/stores.js";
+import { networkInterfaces } from "node:os";
 import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { assertProjectLayout, layoutFindingText } from "@plitzi/sdk-shared/project/layout";
@@ -60,8 +63,19 @@ var cloudAdapters = (pluginNames) => {
 		deployment: { pluginNames }
 	});
 };
-var actionLookups = (actions, connectors) => ({
+var LOOPBACK = /* @__PURE__ */ new Set([
+	"127.0.0.1",
+	"::1",
+	"localhost"
+]);
+/** Where another device reaches a server listening on `host`: this machine's own network addresses, when it is open. */
+var networkUrls = (host, port) => {
+	if (LOOPBACK.has(host)) return [];
+	return (host === "0.0.0.0" || host === "::" ? Object.values(networkInterfaces()).flat().flatMap((entry) => entry && entry.family === "IPv4" && !entry.internal ? [entry.address] : []) : [host]).map((address) => `http://${address}:${String(port)}/`);
+};
+var actionLookups = (actions, connectors, credentials) => ({
 	getAction: (_spaceId, actionId) => Promise.resolve(actions.find((entry) => entry.id === actionId)),
+	getCredential: (_spaceId, identifier) => Promise.resolve(Object.hasOwn(credentials, identifier) ? credentials[identifier] : void 0),
 	listActions: () => Promise.resolve([...actions]),
 	getConnector: (_spaceId, connectorId) => Promise.resolve(connectors.get(connectorId)),
 	listScheduledSpaces: () => Promise.resolve([SPACE_ID])
@@ -137,13 +151,21 @@ var startProject = async (options) => {
 		env: process.env,
 		publicUrl
 	});
+	let keptKv;
+	const kv = fleetKv(() => {
+		keptKv = createFileKv({
+			file: path.join(root, KV_FILE),
+			owner: `the server of "${name}", on port ${String(port)}`
+		});
+		return keptKv;
+	});
 	const server = createServer({
 		logLevel: process.argv.includes("--verbose") ? "info" : "warn",
 		logger: consoleLogger,
 		...serverOptions,
 		port,
-		devMode: developing,
-		devReload: developing,
+		devMode: serverOptions.devMode ?? developing,
+		devReload: serverOptions.devReload ?? serverOptions.devMode ?? developing,
 		health: { name },
 		adapters,
 		plugins: plugins.sources,
@@ -155,12 +177,12 @@ var startProject = async (options) => {
 		},
 		action: {
 			signingSecret: process.env.PLITZI_SIGNING_SECRET,
-			kv: createFileKv({ file: path.join(root, KV_FILE) }),
+			kv,
 			...serverOptions.action,
-			...actions ? { lookups: actionLookups(actions, connectors) } : {}
+			...actions ? { lookups: actionLookups(actions, connectors, credentialsFromEnv()) } : {}
 		}
 	}, { preAuth: [spaceFailure.stage, ...runtime ? [runtime.stage] : []] });
-	server.listen(port, host);
+	await server.listen(port, host);
 	const url = `http://127.0.0.1:${String(port)}`;
 	if (speaks) {
 		mkdirSync(path.join(root, PROJECT_TMP), { recursive: true });
@@ -170,6 +192,8 @@ var startProject = async (options) => {
 			url
 		}, null, 2)}\n`);
 		console.log(`pages on ${url}/`);
+		const network = networkUrls(host, port);
+		if (network.length > 0) console.log(`also on ${network.join(", ")} — anyone on this network can open it (HOST=${host})`);
 	}
 	const watching = developing ? [...held ? [watchSpace(root, (authored) => {
 		held.documents = authored;
@@ -180,6 +204,7 @@ var startProject = async (options) => {
 		watching.forEach((stop) => stop());
 		await server.close();
 		await runtime?.close();
+		await keptKv?.close();
 	};
 	const stopListening = closeOnSignals({ close });
 	return {

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

@@ -28,6 +28,8 @@ export type Admission = {
     /** The grant each accepted topic of a `grant: true` channel was opened with. */
     granted: Map<string, string>;
     refused: RealtimeRefusal[];
+    /** It hears and never speaks: the page asked to watch (`OBSERVER_COOKIE_NAME`). */
+    observer: boolean;
 };
 /**
  * Which of the topics a page asked for (`?topics=a,b`) it may open: each checked against the channels the space
@@ -44,10 +46,11 @@ export declare const connectionFor: (admission: Extract<Admission, {
  * may send on, within its size and its rate — and stamped by the server with who sent it and when, whatever the
  * message said.
  */
-export declare const publishFrom: (hub: RealtimeHub, connection: RealtimeConnection, { topic, type, data }: {
+export declare const publishFrom: (hub: RealtimeHub, connection: RealtimeConnection, { topic, type, data, echo }: {
     topic?: unknown;
     type?: unknown;
     data?: unknown;
+    echo?: unknown;
 }) => Promise<RealtimeAnswer>;
 export type SubscribeDeps = {
     req: SSRRequest;

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,13 +15,12 @@ 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";
 import { resolveDebugMode } from "../../helpers/resolveDebugMode.js";
 import { flagUserFromSSR, flagValues, resolveFlags } from "@plitzi/sdk-shared/flags";
-import { collectServerElements, notFoundProvider } from "@plitzi/sdk-shared/schema/serverElements";
+import { collectServerElements, notFoundProvider, pageNotFound, pageServerContext } from "@plitzi/sdk-shared/schema/serverElements";
 import { debugCookieName } from "@plitzi/sdk-shared/devTools";
 import { themeFromCookies } from "@plitzi/sdk-shared/theme";
 import { paintedKeys, paintedStateFor } from "@plitzi/sdk-shared/state/paintedState";
@@ -84,11 +84,13 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		loadOfflineData,
 		flagOverrides
 	})) : rscPath ? { serverData: {} } : void 0;
-	const pageSeo = resolvePageSeo(schema, pageMatch?.pageId);
-	const notFound = pageMatch !== void 0 && rscData?.serverData !== void 0 ? notFoundProvider(serverElements, rscData.serverData, {
-		routeParams: pageMatch.routeParams,
+	const navigation = {
+		routeParams: pageMatch?.routeParams ?? {},
 		queryParams: req.query
-	}) !== void 0 : false;
+	};
+	const pageContext = pageServerContext(serverElements, rscData?.serverData ?? {}, navigation);
+	const pageSeo = resolvePageSeo(schema, pageMatch?.pageId, pageContext);
+	const notFound = pageMatch !== void 0 && rscData?.serverData !== void 0 ? notFoundProvider(serverElements, rscData.serverData, navigation) !== void 0 || pageNotFound(schema?.flat[pageMatch.pageId]?.attributes.notFound, pageContext) : false;
 	const server = buildServerInfo(req, config, {
 		rscPath,
 		rscData,

package/dist/modules/ssr/resolvePageSeo.d.ts

@@ -14,5 +14,8 @@ export type PageSeo = {
  * `seoEnabled: false` returns nothing rather than a default, so the deployment's own title stays in charge of a
  * page that opted out. Blank strings are treated as absent for the same reason — the builder writes one for a
  * field the author cleared, and an empty <title> is worse than a generic one.
+ *
+ * Either may be a template over the page's server providers and the address (`pageServerContext`): a detail page says
+ * the title of the record it shows, in the HTML a crawler reads. One that does not evaluate is nothing, as a blank is.
  */
-export declare const resolvePageSeo: (schema: Schema | undefined, pageId: string | undefined) => PageSeo;
+export declare const resolvePageSeo: (schema: Schema | undefined, pageId: string | undefined, context?: Record<string, unknown>) => PageSeo;

package/dist/modules/ssr/resolvePageSeo.js

@@ -1,3 +1,4 @@
+import { pageSeoText } from "@plitzi/sdk-shared/schema/serverElements";
 //#region src/modules/ssr/resolvePageSeo.ts
 /**
 * The title and description the addressed page declares for itself.
@@ -10,13 +11,16 @@
 * `seoEnabled: false` returns nothing rather than a default, so the deployment's own title stays in charge of a
 * page that opted out. Blank strings are treated as absent for the same reason — the builder writes one for a
 * field the author cleared, and an empty <title> is worse than a generic one.
+*
+* Either may be a template over the page's server providers and the address (`pageServerContext`): a detail page says
+* the title of the record it shows, in the HTML a crawler reads. One that does not evaluate is nothing, as a blank is.
 */
-var resolvePageSeo = (schema, pageId) => {
+var resolvePageSeo = (schema, pageId, context = {}) => {
 	if (!schema || !pageId) return {};
 	const page = schema.flat[pageId];
 	if (!page?.attributes.seoEnabled) return {};
-	const title = page.attributes.seoPageTitle?.trim();
-	const description = page.attributes.seoPageDescription?.trim();
+	const title = pageSeoText(page.attributes.seoPageTitle, context);
+	const description = pageSeoText(page.attributes.seoPageDescription, context);
 	return {
 		...title ? { title } : {},
 		...description ? { description } : {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.9",
+  "version": "0.38.11",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -96,8 +96,8 @@
     "./dist/env.js"
   ],
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.9",
-    "@plitzi/sdk-shared": "0.38.9",
+    "@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
@@ -50,7 +52,7 @@ apiContainer({ id: 'p', query: '/data/x.json', runtime: 'server', children }) //
 apiContainer({ id: 'p', action: 'report', runtime: 'server', children })     // the action's output at p's root: p.rows
                                                // loadingSlot: 'p-skeleton' — a child shown until it answers
 form({ id, managedByInteractions: true, flows, children })
-formControl({ name: 'email', label: 'Email', subType: 'email' })          // select: options: [{ label, value }]
+formControl({ name: 'email', label: 'Email', subType: 'email', required: true })   // optional without required; select: options: [{ label, value }]
 modalContainer({ id, visible: false, title, children })
 component('card', { props: { title }, children: { body: [ … ] } })
 custom({ renderType: 'myPlugin' }); defineElement<Props>(declaration)      // a plugin
@@ -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/filter-a-list.ts

@@ -31,8 +31,6 @@ export const recipe: SpaceSpec = {
             { label: 'Graphics cards', value: 'gpu' }
           ],
           defaultValue: 'all',
-          // A filter always has an answer: the select is not a question that must be filled in.
-          required: false,
           flows: [
             [named('picked', on('onChange')), setState({ key: 'category', type: 'text', value: '{{ picked.value }}' })]
           ]

package/skills/plitzi-authoring/recipes/forms-and-modals.ts

@@ -38,7 +38,8 @@ export const recipe: SpaceSpec = {
             [named('sent', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ sent.values.email }}' })]
           ],
           children: [
-            formControl({ name: 'email', label: 'Email', subType: 'email' }),
+            // Optional unless it says so, as an HTML field is: a sign-up without an address is no sign-up.
+            formControl({ name: 'email', label: 'Email', subType: 'email', required: true }),
             button({ content: 'Sign up', subType: 'submit' })
           ]
         }),

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,12 +98,11 @@ 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: [] }]` |
 | `not-found-in-browser` | `notFound` on a provider asked from the browser — its answer arrives after the page was sent with its status | `runtime: 'server'` on the provider, or `visible` on the page's "not found" part instead |
-| `not-found-not-a-template` | `notFound` that is not one `{{ expression }}` against the answer — never `true`, so never a 404 | `notFound: '{{ source.found == false }}'` |
+| `not-found-not-a-template` | `notFound`, a provider's or a page's, that is not one `{{ expression }}` — never `true`, so never a 404 | `notFound: '{{ source.found == false }}'` |
 | `notifications-shape` | `notifications` with a field it does not have, or a value that is not one CSS value | the field it suggests, or one it lists; one CSS value, like 'var(--card)', '12px' or '500' |
 | `outside-ancestor` | an element that reads the state of an element it is not inside | nest it in the element the message names |
 | `page-access-level` | an `accessLevel` that is not one the router reads | one of the values the message lists |
@@ -110,6 +110,7 @@ The space is not written until these are fixed.
 | `page-route-taken` | two pages at one address for the same visitors | another slug — or `accessLevel` `'public'` on one and `'authenticated'` on the other |
 | `page-target-unknown` | a link or `navigate` to a page id that does not exist | an existing page id, or a path with its slash (`'/about'`) |
 | `page-target-url` | a URL, `mailto:` or `tel:` in a link left in page mode | `mode: 'external'` |
+| `page-template` | a template in a page's `seoTitle`, `seoDescription` or `notFound` that reads what is not there when the server answers — anything but the page's `runtime: 'server'` providers and `navigation` — or cannot be read | read the record from a provider with `runtime: 'server'` on the page or its layout — `'{{ apiContainer_post.title }} — Blog'` — or words of its own |
 | `page-without-slug` | a page with no `slug` | `slug: ''` for the home page, its path for any other: `'about'`, `'blog/:slug'` |
 | `part-missing` | a compound element — a carousel, a tab container, a dropdown — without a part it renders through | the part the message names, inside it (`carousel()` writes its own track) |
 | `prop-missing` | an instance without a prop its component requires | `component('card', { props: { name: … } })`, or bind it |
@@ -131,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 |
@@ -145,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' })` |
@@ -185,6 +188,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `embed-without-title` | an `embed` with no `title` — a frame a screen reader cannot describe | say what it shows in `title` |
 | `flag-rule-empty` | a flag rule with no conditions — skipped, never read as "always" | give it a condition, or set the flag's `value` instead |
 | `flag-unused` | a declared flag nothing gates on and no template reads | gate what it switches (`flag: 'x'`), or remove it once the feature has shipped |
+| `focus-on-field-box` | a `focus` or `focus-visible` state on a text field's or a select's `input` slot — the box the field is drawn in, which never takes focus, so no ring is ever shown | `'focus-within'` on the same class, or the state on the `field` slot |
 | `FORM_SUBMIT_UNMANAGED` | a form the browser would submit itself, reloading the page | `managedByInteractions: true` |
 | `form-control-name-taken` | two controls in one form with one name — one overwrites the other | a name each |
 | `form-control-unnamed` | a control in a form with no `name` — its value never reaches `values` | `formControl({ name: 'email', … })` |
@@ -202,6 +206,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `path-not-in-data` | a binding onto a provider whose answer the author could read (`data`), through a path that answer does not have | the path the message lists the keys for — `p.data.plans`, not `p.data.landing.plans` |
 | `plugin-attribute-reserved` | a plugin attribute named as one of the element’s own fields — a factory never hands it to the plugin | rename it in the plugin (`variant` → `kind`) |
 | `provider-without-source` | an `apiContainer` that asks nothing | a `query` (or `action`, `connector`, `resource`) |
+| `required-message-unused` | a `requiredMessage` on a field nothing requires — fields are optional unless `required: true`, so it is never shown and an empty answer is sent | `required: true` on the field, or no message |
 | `route-param-undeclared` | `navigation.routeParams.x` read on a page whose slug has no `:x` — always empty | add `:x` to the slug, or read `navigation.queryParams.x` |
 | `server-data-without-rsc` | a `runtime: 'server'` provider — `connector`, `action` or `query` — in a space that turns server data off (`rsc: { enabled: false }`) | drop `rsc: { enabled: false }`: server data is on unless a space turns it off |
 | `span-holds-block` | a `container` with `subType: 'span'` or `'p'` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words and inline elements: a `text`, a `link` |

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: [ … ] }]
 ```
@@ -139,8 +140,10 @@ Every page is now its content and nothing else, and every page is guaranteed the
   suggests writing your own (`not-found-page`): say it in the space's words.
 - **A page that exists but finds nothing** — `/products/:slug` for a slug no product has — is sent with 404 too when
   its server provider says so: `notFound: "{{ not (source.data.products|find('slug', navigation.routeParams.slug)) }}"`,
-  one expression against its answer, on a `runtime: 'server'` provider of the page (not of its layout, which every
-  page shares). The page renders as written: show its "not found" part with `visible`.
+  one expression against its answer, on a `runtime: 'server'` provider of the page. When the record comes from a
+  provider of its layout, which every page shares, the page says it: `notFound` on the page reads its server providers
+  by name — `"{{ not (apiContainer_feed.products|find('slug', navigation.routeParams.slug)) }}"`. The page renders as
+  written: show its "not found" part with `visible`.
 
 ## Styles follow the same rule
 

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.