@plitzi/sdk-server 0.38.10 → 0.38.12

package/dist/modules/mysql/jobs/jobQueue.js

@@ -28,6 +28,7 @@ var toJob = (row) => ({
 	dueAt: Number(row.due_at),
 	maxAttempts: Number(row.max_attempts),
 	...row.missed === null ? {} : { missed: Number(row.missed) },
+	...row.job_key === null ? {} : { key: row.job_key },
 	status: row.status,
 	runAt: Number(row.run_at),
 	attempts: Number(row.attempts),
@@ -128,8 +129,8 @@ var createMysqlJobQueue = ({ pool, tablePrefix = "", createTables = true, retent
 			const at = await clock.now();
 			try {
 				await execute(conn, `INSERT INTO ${t.jobs} (id, space_id, action_id, environment, trigger_type, input, due_at, max_attempts,
-            missed, status, run_at, attempts, created_at, updated_at, history)
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, 0, ?, ?, '[]')`, [
+            missed, job_key, status, run_at, attempts, created_at, updated_at, history)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, 0, ?, ?, '[]')`, [
 					job.id,
 					job.spaceId,
 					job.actionId,
@@ -139,6 +140,7 @@ var createMysqlJobQueue = ({ pool, tablePrefix = "", createTables = true, retent
 					job.dueAt,
 					job.maxAttempts,
 					job.missed ?? null,
+					job.key ?? null,
 					job.dueAt,
 					at,
 					at
@@ -368,6 +370,23 @@ var createMysqlJobQueue = ({ pool, tablePrefix = "", createTables = true, retent
 				jobId,
 				spaceIds
 			])).affectedRows === 1;
+		},
+		cancelPending: async ({ spaceId, key, olderThan }) => {
+			const conn = await db();
+			const newest = olderThan === void 0 ? void 0 : await selectOne(conn, `SELECT id, created_at FROM ${t.jobs} WHERE id = ?`, [olderThan]);
+			const at = await clock.now();
+			return (await execute(conn, `UPDATE ${t.jobs} SET status = 'cancelled', updated_at = ?, expires_at = ?, worker_id = NULL
+        WHERE space_id = ? AND job_key = ? AND status = 'pending'${newest ? " AND (created_at < ? OR (created_at = ? AND id < ?))" : ""}`, [
+				at,
+				expiryOf(at),
+				spaceId,
+				key,
+				...newest ? [
+					newest.created_at,
+					newest.created_at,
+					newest.id
+				] : []
+			])).affectedRows;
 		}
 	};
 };

package/dist/modules/mysql/jobs/schema.d.ts

@@ -23,8 +23,9 @@ export declare const jobTables: (prefix?: string) => JobTables;
  */
 export declare const mysqlJobSchemaStatements: (prefix?: string) => string[];
 /**
- * What brings a `kv` table made before the columns above up to them — for a deployment that runs its own migrations,
- * once. `ensureJobTables` does it by itself, and only when the table needs it: the `ALTER` copies the table.
+ * What brings tables made before the columns above up to them — for a deployment that runs its own migrations: each
+ * statement once, the ones its tables still lack. `ensureJobTables` does it by itself, and only where a table needs
+ * it: an `ALTER` copies the table.
  */
 export declare const mysqlJobSchemaUpgrades: (prefix?: string) => string[];
 /** The server's now, in epoch ms, as an SQL expression — what every comparison reads instead of a caller's clock. */

package/dist/modules/mysql/jobs/schema.js

@@ -38,6 +38,7 @@ var mysqlJobSchemaStatements = (prefix = "") => {
       due_at BIGINT NOT NULL,
       max_attempts INT NOT NULL,
       missed INT NULL,
+      job_key VARCHAR(191) NULL,
       status VARCHAR(16) NOT NULL,
       run_at BIGINT NOT NULL,
       attempts INT NOT NULL DEFAULT 0,
@@ -54,6 +55,7 @@ var mysqlJobSchemaStatements = (prefix = "") => {
       KEY action_jobs_pending (status, run_at),
       KEY action_jobs_lease (status, lease_until),
       KEY action_jobs_space (space_id, updated_at),
+      KEY action_jobs_key (space_id, job_key, status),
       KEY action_jobs_expires (expires_at)
     ) ${CHARSET}`,
 		`CREATE TABLE IF NOT EXISTS ${t.schedules} (
@@ -80,18 +82,29 @@ var mysqlJobSchemaStatements = (prefix = "") => {
     ) ${CHARSET}`
 	];
 };
-/**
-* What brings a `kv` table made before the columns above up to them — for a deployment that runs its own migrations,
-* once. `ensureJobTables` does it by itself, and only when the table needs it: the `ALTER` copies the table.
-*/
-var mysqlJobSchemaUpgrades = (prefix = "") => [`ALTER TABLE ${jobTables(prefix).kv} MODIFY k VARBINARY(764) NOT NULL, MODIFY v MEDIUMTEXT NOT NULL`];
-/** Whether the `kv` table still has the columns it was first made with. */
-var kvNeedsUpgrade = async (db, prefix) => {
+/** The columns a table of this database has, by name, with their types. */
+var columnsOf = async (db, table) => {
 	const columns = await selectRows(db, `SELECT COLUMN_NAME AS name, DATA_TYPE AS type FROM INFORMATION_SCHEMA.COLUMNS
-    WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME IN ('k', 'v')`, [`${prefix}action_kv`]);
-	const typeOf = (name) => columns.find((column) => column.name === name)?.type.toLowerCase();
-	return typeOf("k") !== "varbinary" || typeOf("v") !== "mediumtext";
+    WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`, [table]);
+	return new Map(columns.map((column) => [column.name, column.type.toLowerCase()]));
 };
+var UPGRADES = [{
+	needed: async (db, prefix) => {
+		const columns = await columnsOf(db, `${prefix}action_kv`);
+		return columns.get("k") !== "varbinary" || columns.get("v") !== "mediumtext";
+	},
+	statements: (prefix) => [`ALTER TABLE ${jobTables(prefix).kv} MODIFY k VARBINARY(764) NOT NULL, MODIFY v MEDIUMTEXT NOT NULL`]
+}, {
+	needed: async (db, prefix) => !(await columnsOf(db, `${prefix}action_jobs`)).has("job_key"),
+	statements: (prefix) => [`ALTER TABLE ${jobTables(prefix).jobs} ADD COLUMN job_key VARCHAR(191) NULL AFTER missed,
+      ADD KEY action_jobs_key (space_id, job_key, status)`]
+}];
+/**
+* What brings tables made before the columns above up to them — for a deployment that runs its own migrations: each
+* statement once, the ones its tables still lack. `ensureJobTables` does it by itself, and only where a table needs
+* it: an `ALTER` copies the table.
+*/
+var mysqlJobSchemaUpgrades = (prefix = "") => UPGRADES.flatMap((upgrade) => upgrade.statements(prefix));
 /** The server's now, in epoch ms, as an SQL expression — what every comparison reads instead of a caller's clock. */
 var NOW_MS = "CAST(ROUND(UNIX_TIMESTAMP(NOW(3)) * 1000) AS SIGNED)";
 /** Creates the tables once per process, on first use; a failure is retried by the next call rather than remembered. */
@@ -101,7 +114,7 @@ var ensureJobTables = (db, prefix, create) => {
 		if (!create) return;
 		ready ??= (async () => {
 			for (const statement of mysqlJobSchemaStatements(prefix)) await execute(db, statement);
-			if (await kvNeedsUpgrade(db, prefix)) for (const statement of mysqlJobSchemaUpgrades(prefix)) await execute(db, statement);
+			for (const upgrade of UPGRADES) if (await upgrade.needed(db, prefix)) for (const statement of upgrade.statements(prefix)) await execute(db, statement);
 		})().catch((error) => {
 			ready = void 0;
 			throw error;

package/dist/modules/project/plugins.d.ts

@@ -5,7 +5,7 @@ import { PluginSource, SSRServer } from '@plitzi/sdk-shared';
  * plugin of `vendor/plugins` run as it was built — each with its server half, when it has one.
  */
 export type ProjectPlugins = {
-    /** How each is built, by the name a space's `custom({ renderType })` renders it by. */
+    /** How each is built, by the type a space's element of it is — `defineElement(declaration)` — rendered by. */
     sources: Record<string, PluginSource>;
     /**
      * Which of them the space renders with — the deployment's `pluginNames`. Registering a plugin is not turning it on:

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,6 +151,14 @@ 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,
@@ -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,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.12",
   "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.12",
+    "@plitzi/sdk-shared": "0.38.12",
     "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
@@ -53,7 +55,7 @@ form({ id, managedByInteractions: true, flows, children })
 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
+const seats = defineElement(seatsDeclaration); seats({ id }) // a plugin
 ```
 
 ## Styles
@@ -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/plugin.ts

@@ -11,18 +11,20 @@ import {
   onClick,
   setState
 } from '@plitzi/sdk-authoring';
+import { definePlugin } from '@plitzi/sdk-authoring/plugin';
 
 import type { PluginDeclarationData, SpaceSpec } from '@plitzi/sdk-authoring';
 
-// In a project: `import declaration from './plugins/seatPicker/declaration';`
-const declaration = {
+// In a project, `src/plugins/SeatPicker/declaration.ts` — `export default definePlugin<SeatPickerAttributes>()({ … })`.
+const declaration = definePlugin<{ rows?: number }>()({
   type: 'seatPicker',
-  triggers: { onPick: { action: 'onPick', title: 'On Pick', type: 'trigger', params: {}, preview: { seat: '' } } },
-  callbacks: { reset: { action: 'reset', title: 'Reset', type: 'callback', params: {} } },
-  content: { attributes: { rows: 10 }, definition: { label: 'Seat Picker' } }
-} as const;
+  label: 'Seat Picker',
+  attributes: { rows: 10 },
+  triggers: { onPick: { preview: { seat: '' } } },
+  callbacks: { reset: {} }
+});
 
-const seatPicker = defineElement<{ rows?: number }>(declaration);
+const seatPicker = defineElement(declaration);
 
 // `authorSpace(recipe, { plugins })` — in a project, every `src/plugins/<Name>/declaration.ts`, found by folder.
 export const plugins: PluginDeclarationData[] = [declaration];

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' })` |
@@ -232,11 +234,13 @@ Nothing is wrong: the page renders as written. Each is a shorter way to the same
 | `custom-css-notifications` | the toasts or their icon, close button or progress bar dressed with `.Toastify__*` rules in `customCss` | `notifications: { font, fontSize, fontWeight, minHeight, iconSize, closeColor, progressHeight, … }` |
 | `custom-css-sdk-default` | `customCss` repeating what the SDK already does for every space — less motion when asked, the theme toggle showing one icon | nothing: remove it |
 | `custom-css-slot` | a part of a built-in element dressed in `customCss` by the SDK's markup — a form control's `<input>`, a pager's buttons, a heading inside a markdown | a class on the slot of that part — `slots: { field: input }`, `elements.<type>.slots` — with its states |
+| `element-color-inherited` | `elements` giving a type — a heading, a text, a link — `color: inherit` or the page's own colour, which it takes by itself | remove it, and name the colour once on `elements.page`: every element reads in the page’s colour, a link’s words included |
 | `heavy-animation` | keyframes animating what the browser repaints or lays out again on every frame — a size, a position, a blur, a shadow, or a colour in a loop — which stutters whenever the page is busy, most of all while it loads | `opacity` and `transform`: a size or a position is `translate`/`scale`, a blur or a shadow is the `opacity` of a layer carrying it; a loop that must animate anything else starts `paused` and runs under `[data-hydrated]` |
 | `literal-colour` | a colour written out in a class where the space has a token of that value — it stays put in the dark scheme | `var(--token)` when it should follow the scheme; a token of one value of its own when it must stay the same in both |
 | `not-found-page` | a space with no page of its own for an address no other page answers — a plain one was added, in the home page’s layout, sent with status 404 | a page whose slug is `'*'`: `{ id: 'not-found', name: 'Not found', slug: '*', layout: …, body: [...] }` |
+| `plugin-custom-host` | a `custom` element naming, by `renderType`, a plugin whose declaration the space was handed | place it from its declaration — `const seatPicker = defineElement(declaration)`, then `seatPicker({ id, … })`: typed by what it declares (a `definePlugin` declaration carries its attributes), the element the builder adds too |
 | `repeated-on-pages` | the same block — a header, a footer, a side panel — written into several pages | a layout holding it once (`layouts`, and `layout: { id, slot }` on each page) — a component when only some pages of a layout carry it; a link marks its own page with the `current` state |
-| `repeated-shape` | the same structure written again and again with different words — cards, rows, tiles | a component with props (`components`, `component(id, { props })`), or one `list` when they are rows of data side by side — a few cards a person rewords on the canvas can stay cards |
+| `repeated-shape` | the same structure written again and again with different words — cards, rows, tiles; copies that bind different data, read their own template or render on the server are controls, not repeats | a component with props (`components`, `component(id, { props })`), or one `list` when they are rows of data side by side — a few cards a person rewords on the canvas can stay cards |
 | `unused-class` | a class declared in `classes` that no element, binding, flow or other class names | remove it from `classes` — or wear it where it was meant to go |
 | `unused-component` | a component no page, layout or other component places | remove it from `components`, or place it where it was meant to go |
 | `unused-token` | a token of `variables` no `var(--…)` reads — not a class, an element, `customCss` nor another token | remove it, or write it where its colour is written out |

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/elements-and-styles.md

@@ -73,7 +73,7 @@ indented with space below it: `{ margin: '0px', padding: '0px' }` on its class t
 children sit in the parent's layout and a `class` on it styles nothing (`STYLE_WITHOUT_TAG`). Put the layout on the
 parent, or give it `attributes: { subType: 'div' }`.
 
-A plugin's type is authored the same way: `defineElement<Props>({ type, … })` — see [plugins](plugins.md).
+A plugin's type is authored the same way: `defineElement(declaration)` — see [plugins](plugins.md).
 
 **What a type takes:** `npx @plitzi/cli explain formControl`, or the exported catalogues ([validation.md](validation.md)).