@plitzi/sdk-server 0.38.11 → 0.38.13

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # @plitzi/sdk-server
 
+## 0.38.13
+
+### Patch Changes
+
+- v0.38.13
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.38.13
+  - @plitzi/sdk-shared@0.38.13
+
+## 0.38.12
+
+### Patch Changes
+
+- 1301338: ## Builder
+
+  - **Icons in the canvas again** (`@plitzi/plitzi-builder`): the canvas inlined the SDK's Font Awesome sheet into its
+    `<style>`, where the sheet's `url(webfonts/…)` resolved against the editor's URL — a `srcdoc` frame takes it as its
+    base — so every icon was a 404 under `/spaces/<space>/webfonts/` and drew as an empty box. Only the Vite dev server,
+    which rewrites the URL, hid it. The canvas and the element preview now link the sheet from where the host serves it:
+    a new prop, `sdkIconsStylePath`, the one the host already gives the pages it renders
+    (`/sdk-assets/plitzi-sdk-icons.css` for sdk-server). Absent, the canvas links no icon sheet.
+
+  ## Plugins
+  - **A plugin's other elements, hosted by `custom`** (`@plitzi/sdk-elements`): `custom({ renderType: 'jamDisc' })` on a
+    space with a plugin installed whose main element is another (`plitzi plugin pack` of several folders: the first is the
+    plugin, the rest go in it) rendered "Custom Component jamDisc Not Found" — the page registers only the plugin's main
+    element, and a `custom` host looked nowhere else. It now loads the type from the installed plugin that packs it, as
+    an element of the type itself always did, so the two ways the docs give to place a plugin's element are the same
+    everywhere: in a project `plitzi create` wrote, and once the project is on Plitzi.
+  - **One way to place a plugin's element** (`@plitzi/sdk-authoring`, `@plitzi/cli`, docs): from its declaration,
+    `const seatPicker = defineElement(declaration)` then `seatPicker({ id, … })` — typed by what it
+    declares, and the element the builder adds when somebody drops it. The welcome space `plitzi create` writes, the
+    plugin package's preview, `plitzi plugin add` and `plitzi explain` all write it so (the template's
+    `PluginHostOptions` now takes the plugin's `type` and `declaration: { from, attributes? }`; `custom`/`element` hosting
+    is gone). `pluginFolders(folder)` (`@plitzi/sdk-authoring/node`) reads each plugin with the folder it is in;
+    `pluginDeclarations` is built on it. A `custom({ renderType })` naming a plugin the space was handed the declaration
+    of is offered the declaration instead — suggestion `plugin-custom-host`. `custom` stays for a component registered
+    by name with no declaration. The skills, the CLI README, the MCP guide, `docs/en` and the website say the same.
+  - **`definePlugin`** (`@plitzi/sdk-authoring/plugin`, a new entry of 3 KB with nothing else in it): a plugin's
+    declaration written from what only it can say —
+    `definePlugin<SeatPickerAttributes>()({ type, label, attributes, triggers, callbacks })` — and every other field
+    at the default all plugins share (the builder's gestures, the catalogue entry, each attribute bindable, an empty
+    style). It answers the whole declaration, branded with its attributes, so `defineElement(declaration)` is typed
+    without a generic. `plitzi plugin add` and `create --plugin` write declarations with it (about a third of the lines).
+  - **`usePluginTrigger(declaration)`** (`@plitzi/plitzi-sdk`): fires a plugin's declared event on its element — the
+    event name and what each hands a flow typed off the declaration's `preview` — on a live page only. The hook every
+    plugin wrote for itself (and `plugin add` generated as `use<Name>Events`) is gone from the scaffold.
+  - **Attributes as the types their defaults are** (`@plitzi/sdk-elements`): a plugin's attribute bound from text — a
+    state, a row, a channel message — reaches its component as the number or the flag its declared default is (`'112'`
+    as 112, `'true'` as true). A plugin no longer types its props `number | string` and parses them.
+
+  ## Server actions and functions
+  - **Task params with rules** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): a task declares `required`, a text's
+    `maxLength` and a number's `min`/`max`, and the runner refuses a call that breaks any of them — every rule broken at
+    once, in the words the page shows (`Title is required; Seconds is at most 300`) — before the code runs. A `text` param
+    bound to a number arrives as its digits. The manifest keeps the rules, so the platform's sandbox checks the same.
+  - **`taskAction(task, { trigger })`** (`@plitzi/sdk-authoring`): the action that runs one of the space's tasks and
+    answers its result, derived from the task — its id (`<namespace>-<action>`), name, description and input (the task's
+    params, once). An action of more than one step is still `defineAction`.
+  - **`ctx.rateLimit(bucket, { …, refuse })`**: past the limit the call is refused with those words instead of answering
+    `allowed: false` for the code to check — natively and in the sandbox.
+
+  ## Authoring
+  - **`runServerActionOrNotify(id, params, fallback)`**: a server action run and the notice the visitor reads when it
+    fails — the action's own refusal, or the fallback — as two steps to spread into a flow.
+  - **`repeated-shape` reads what copies bind**: copies whose bindings read their data in different forms (a count, a
+    total of a quota) and copies holding a provider resolved on the server (found by its own id) are no longer offered
+    as one component.
+  - **`element-color-inherited`** (suggestion): `elements` giving a heading, a text, a link… `color: inherit` or the
+    page's own colour. **A link inherits the page's colour** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-elements`) rather than
+    holding the SDK's grey — the same by default, and the space's palette inside a card that is a link. The template
+    every space starts from writes its colours once, on the page.
+
+  ## Fixes
+  - **A dialog opened with an id** (`@plitzi/sdk-elements`): `openDialog('dialog', '{{ row.id }}')` reads the id as its
+    `content`, as `openModal` already did — a numeric id parsed as the number and the dialog's bindings read nothing.
+  - **A select's chevron** (`@plitzi/plitzi-sdk`): a drawn chevron in the field's own colour, sized by its type, in place
+    of the `▼` glyph — and laid out in the box, so it ends where the box's padding begins whatever that padding is, and
+    the chosen option stops short of it instead of running under it. A disabled select's is faded.
+  - **Every element has its settings** (`@plitzi/plitzi-builder`, `@plitzi/sdk-elements`): the builder found none for
+    `tabContainerHeader` (registered under a misspelt type), `themeToggle`, `dropdownPopup`, `loading` and `notFound`.
+    The theme toggle's panel sets its mode, its labels and whether it offers "System"; the registry is typed by element
+    type and must hold one for each.
+  - **A plugin's panel** (`@plitzi/cli`): `plitzi doctor` warns of a plugin with no `Settings.tsx`, or one its entry never
+    passes as `pluginSettings` (`plugin-settings-missing`); the example `create` writes has its panel, as every element
+    `plugin add` writes does, and the panels it generates are laid out as the project's Prettier lays them out.
+  - **A refused or failed run reaches `onFlowError` in every mode** (`@plitzi/sdk-interactions`): an awaited server
+    action the server refused fired no `onFlowError` on the element that started it, as `detached` and `stream` ones do
+    — a board rolling its edits back on a refusal never did; and a run answered `status: 'failed'` fired `onFlowEnd`
+    (detached) or nothing (awaited) rather than `onFlowError`.
+  - **A source renamed** (`@plitzi/sdk-shared`): the binding picker lists a provider, a form or a modal by the name its
+    element has now, not the one it had when it mounted.
+  - **A text's words in the builder** (`@plitzi/sdk-elements`): a `paragraph`, `text` or `heading` whose `content` is
+    `0` shows `0` while editing too, not its placeholder; one bound to nothing shows nothing rather than `null`.
+  - **Built-in declarations** (`@plitzi/sdk-shared`): `elementDeclaration` fills in what every element shares — the
+    builder's gestures, Plitzi's catalogue entry, a visible element with no bindings, its style named by its label —
+    from the defaults `definePlugin` uses; each element's declaration says only what is its own (a third of the lines).
+
+  ## Typed for plugins and hosts
+  - **`usePlitzi()` and `PlitziProvider`** (`@plitzi/sdk-shared/hooks/usePlitzi`, `@plitzi/plitzi-sdk`): what were
+    `usePlitziServiceContext()` and `PlitziServiceProvider` (and `PlitziServiceContextValue`, now `PlitziContextValue`),
+    holding only what the host rendering a space knows — `settings`, `root`, `utils`. Its `contexts` and
+    `customContexts` are gone: every context it carried is a shared one already, imported from its own module
+    (`@plitzi/sdk-interactions/InteractionsContext`, `@plitzi/sdk-shared/network/NetworkContext`…), and
+    `PluginsContext` moves to `@plitzi/sdk-shared/plugins/PluginsContext` beside the others.
+  - **`InteractionsManagerApi`** (`@plitzi/sdk-shared`): the interactions manager as everything outside
+    `@plitzi/sdk-interactions` reaches it, declared where every package can name it and implemented by
+    `InteractionsManager`, so `use(InteractionsContext)` is typed — `interactionTrigger`, `createChildManager`… — where it
+    was `any`.
+  - **`getPathsFromObject`** (`@plitzi/sdk-shared/helpers/utils`), spelt right; `getPathsFromObeject` is gone.
+  - **`ElementWords` places itself** (`@plitzi/sdk-elements`): `contentPlacement` and the element's children, so a button
+    and a link write their words once.
+
+- Updated dependencies [1301338]
+  - @plitzi/plitzi-sdk@0.38.12
+  - @plitzi/sdk-shared@0.38.12
+
 ## 0.38.11
 
 ### Patch Changes

package/dist/functions-api.d.ts

@@ -211,17 +211,28 @@ declare type InteractionCallbackParam<T extends Record<string, unknown> = Record
      * space's credentials of that kind to pick from, rather than a text box somebody has to type an identifier into.
      */
     credentialProvider?: SpaceCredentialProvider;
-} & ({
+    /**
+     * A space's task refuses to run without it — empty, or only spaces — saying so with the param's `label`, before its
+     * code runs: what a task otherwise checked by hand in its first lines.
+     */
+    required?: boolean;
+} & 
+/** Handed to a task as text, whatever was written or bound — a number as its digits — at most `maxLength` long. */
+({
     type: 'text';
     defaultValue?: string | number;
+    maxLength?: number;
 }
-/** Written as text — a number or a template — and handed to the callback as a number. */
+/** Written as text — a number or a template — and handed to the callback as a number, within `min` and `max`. */
 | {
     type: 'number';
     defaultValue?: number;
+    min?: number;
+    max?: number;
 } | {
     type: 'textarea';
     defaultValue?: string | number;
+    maxLength?: number;
 } | {
     type: 'codemirror-text';
     defaultValue?: string;
@@ -334,6 +345,11 @@ declare type RateLimit = {
     most: number;
     perSeconds: number;
     per?: 'caller' | 'everyone';
+    /**
+     * Over the limit, the call is refused with these words — the step's error, on the page — rather than answered
+     * `allowed: false` for the code to check: `ctx.rateLimit('make', { most: 5, perSeconds: 600, refuse: 'Wait ten minutes' })`.
+     */
+    refuse?: string;
 };
 
 declare type SpaceCredentialProvider = 's3' | 'r2' | 'ssr' | 'custom' | 'smtp';

package/dist/modules/actions/jobs/later.js

@@ -1,11 +1,11 @@
 import { findTriggerNode } from "../runtime/triggers.js";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 import { randomUUID } from "node:crypto";
 //#region src/modules/actions/jobs/later.ts
 /** A month: past it, a run set for later is a schedule, and a cron says it better. */
 var MAX_LATER_SECONDS = 2592e3;
 /** A name a run set for later is known by, as a topic is written: what it is replaced and cancelled by. */
 var KEY = /^[A-Za-z0-9:_.-]{1,128}$/;
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
 * Runs of a space's actions that start in a while — a turn that runs out, a bot's move, a hold that lapses — held by the
 * same queue as its schedules: they outlive a restart where the queue does, run once across replicas, retry, and show

package/dist/modules/actions/runtime/credentials.js

@@ -1,7 +1,7 @@
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/modules/actions/runtime/credentials.ts
 /** Where a project's server — and `plitzi functions dev` — reads the credentials its space's code names. */
 var CREDENTIALS_ENV = "PLITZI_CREDENTIALS";
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var EXAMPLE = "{\"google\":{\"clientId\":\"…\",\"clientSecret\":\"…\"}}";
 /**
 * The credentials a deployment with no credential store keeps in its environment: one JSON object, credential id → its

package/dist/modules/actions/runtime/rateLimit.d.ts

@@ -4,6 +4,11 @@ export type RateLimit = {
     most: number;
     perSeconds: number;
     per?: 'caller' | 'everyone';
+    /**
+     * Over the limit, the call is refused with these words — the step's error, on the page — rather than answered
+     * `allowed: false` for the code to check: `ctx.rateLimit('make', { most: 5, perSeconds: 600, refuse: 'Wait ten minutes' })`.
+     */
+    refuse?: string;
 };
 /** Where a limit stands after counting one more: whether that one was within it, and how many are left. */
 export type RateCount = {
@@ -17,3 +22,5 @@ export type RateCount = {
  * together. Refusing is the caller's: a step refuses the run, a function decides what to answer.
  */
 export declare const countRate: (kv: ActionKvStore, callerId: string, bucket: string, { most, perSeconds, per }: RateLimit) => Promise<RateCount>;
+/** A count past its limit, refused with the limit's own words when it says some; within it, or with none, as counted. */
+export declare const refusedOver: (count: RateCount, limit: RateLimit) => RateCount;

package/dist/modules/actions/runtime/rateLimit.js

@@ -1,3 +1,4 @@
+import { ActionRefusal } from "./errors.js";
 //#region src/modules/actions/runtime/rateLimit.ts
 /**
 * Counts one more of `bucket` in the current window and says whether it was within the limit — the one count behind
@@ -15,5 +16,10 @@ var countRate = async (kv, callerId, bucket, { most, perSeconds, per = "caller"
 		remaining: Math.max(0, most - count)
 	};
 };
+/** A count past its limit, refused with the limit's own words when it says some; within it, or with none, as counted. */
+var refusedOver = (count, limit) => {
+	if (!count.allowed && limit.refuse) throw new ActionRefusal(limit.refuse);
+	return count;
+};
 //#endregion
-export { countRate };
+export { countRate, refusedOver };

package/dist/modules/actions/runtime/runAction.js

@@ -1,6 +1,6 @@
 import { serverLog } from "../../../helpers/serverLog.js";
 import "../jobs/schedules.js";
-import { ActionRunError, isActionRefusal } from "./errors.js";
+import { ActionRefusal, ActionRunError, isActionRefusal } from "./errors.js";
 import { runCancelKey } from "./guards.js";
 import { createKvStore } from "./kvStore.js";
 import { resolveLimits } from "./limits.js";
@@ -151,10 +151,12 @@ var MAX_LOG_LINES = 100;
 var MAX_LOG_LINE = 1e3;
 /**
 * A value written as text, read as the type its task declares: a `number` param written `5` — or bound to text that says
-* it — arrives as 5, a `boolean` one written `'true'` as `true`, an empty number as nothing (so the default applies). The
-* browser reads a callback's params the same way (`coerceDeclaredParams`): a task's author never writes `Number(…)`.
+* it — arrives as 5, a `boolean` one written `'true'` as `true`, an empty number as nothing (so the default applies), and
+* a `text` one bound to a number as its digits. The browser reads a callback's params the same way
+* (`coerceDeclaredParams`): a task's author never writes `Number(…)` or `String(…)`.
 */
 var asDeclared = (type, value) => {
+	if (typeof value === "number" && (type === "text" || type === "textarea")) return String(value);
 	if (typeof value !== "string") return value;
 	if (type === "number") {
 		const parsed = Number(value.trim());
@@ -162,11 +164,36 @@ var asDeclared = (type, value) => {
 	}
 	return type === "boolean" && (value === "true" || value === "false") ? value === "true" : value;
 };
-var withDefaults = (task, params) => Object.entries(task.params).reduce((acum, [key, param]) => {
-	const value = asDeclared(typeof param.type === "function" ? param.type(acum) : param.type, acum[key]);
-	acum[key] = value === void 0 || value === "" ? param.defaultValue ?? "" : value;
-	return acum;
-}, { ...params });
+/**
+* Why a value does not fit the rules its param declares — `required`, a text's `maxLength`, a number's `min` and `max` —
+* in the words the page shows: what a task's code otherwise checked by hand before doing anything. A param that
+* declares none is never judged.
+*/
+var paramProblem = (key, param, value) => {
+	const name = param.label ?? key;
+	if (value === void 0 || value === null || typeof value === "string" && value.trim() === "") {
+		const defaulted = param.defaultValue !== void 0 && param.defaultValue !== "";
+		return param.required && !defaulted ? `${name} is required` : void 0;
+	}
+	if ((param.type === "text" || param.type === "textarea") && param.maxLength !== void 0) return typeof value === "string" && value.length > param.maxLength ? `${name} is longer than ${String(param.maxLength)} characters` : void 0;
+	if (param.type === "number" && (param.min !== void 0 || param.max !== void 0)) {
+		if (typeof value !== "number") return `${name} is not a number`;
+		if (param.min !== void 0 && value < param.min) return `${name} is at least ${String(param.min)}`;
+		if (param.max !== void 0 && value > param.max) return `${name} is at most ${String(param.max)}`;
+	}
+};
+var withDefaults = (task, params) => {
+	const problems = [];
+	const values = Object.entries(task.params).reduce((acum, [key, param]) => {
+		const value = asDeclared(typeof param.type === "function" ? param.type(acum) : param.type, acum[key]);
+		const problem = paramProblem(key, param, value);
+		if (problem) problems.push(problem);
+		acum[key] = value === void 0 || value === "" ? param.defaultValue ?? "" : value;
+		return acum;
+	}, { ...params });
+	if (problems.length > 0) throw new ActionRefusal(problems.join("; "));
+	return values;
+};
 var runNode = async (node, scope, registry, buildContext) => {
 	if (!node.action || !node.enabled) return {
 		status: "disabled",

package/dist/modules/functions/context.js

@@ -1,6 +1,6 @@
 import { prefixKv } from "../actions/runtime/namespaceKv.js";
 import { fetchOutbound } from "../../helpers/outboundGuard.js";
-import { countRate } from "../actions/runtime/rateLimit.js";
+import { countRate, refusedOver } from "../actions/runtime/rateLimit.js";
 import { pluginKvPrefix, pluginSigned } from "./scope.js";
 import { processTwigParam } from "@plitzi/sdk-shared/helpers/twigWrapper";
 //#region src/modules/functions/context.ts
@@ -92,7 +92,7 @@ var functionContextFor = (ctx, hosts, scope) => {
 	if (!scope) return {
 		...shared,
 		kv: ctx.kv,
-		rateLimit: (bucket, limit) => countRate(ctx.kv, ctx.callerId, bucket, limit),
+		rateLimit: async (bucket, limit) => refusedOver(await countRate(ctx.kv, ctx.callerId, bucket, limit), limit),
 		sign: ctx.sign ?? unsigned,
 		verify: ctx.verify ?? unsigned,
 		publish: ctx.publish ?? unavailable("publish"),
@@ -109,7 +109,7 @@ var functionContextFor = (ctx, hosts, scope) => {
 	return {
 		...shared,
 		kv,
-		rateLimit: (bucket, limit) => countRate(kv, ctx.callerId, bucket, limit),
+		rateLimit: async (bucket, limit) => refusedOver(await countRate(kv, ctx.callerId, bucket, limit), limit),
 		sign: sign ? (value) => sign(pluginSigned(scope.plugin, value)) : unsigned,
 		verify: verify ? (value, signature) => verify(pluginSigned(scope.plugin, value), signature) : unsigned,
 		publish: noChannel,

package/dist/modules/functions/driver.js

@@ -107,11 +107,15 @@ var createFunctionsDriver = (environment) => {
 				op: "cancelLater",
 				key
 			}),
-			rateLimit: (bucket, limit) => call({
-				op: "rateLimit",
-				bucket,
-				limit
-			}),
+			rateLimit: async (bucket, limit) => {
+				const count = await call({
+					op: "rateLimit",
+					bucket,
+					limit
+				});
+				if (isRecord(limit) && typeof limit.refuse === "string" && isRecord(count) && count.allowed === false) throw refusal(limit.refuse);
+				return count;
+			},
 			sign: (value) => call({
 				op: "sign",
 				value

package/dist/modules/functions/manifest.js

@@ -47,20 +47,25 @@ var paramOf = (value) => {
 	const base = {
 		...typeof value.canBind === "boolean" ? { canBind: value.canBind } : {},
 		...typeof value.label === "string" ? { label: value.label } : {},
-		...typeof value.when === "boolean" ? { when: value.when } : {}
+		...typeof value.when === "boolean" ? { when: value.when } : {},
+		...typeof value.required === "boolean" ? { required: value.required } : {}
 	};
+	const bound = (key) => typeof value[key] === "number" && Number.isFinite(value[key]) ? { [key]: value[key] } : {};
 	const defaultValue = value.defaultValue;
 	switch (value.type) {
 		case "text":
 		case "textarea": return {
 			...base,
 			type: value.type,
-			...typeof defaultValue === "string" || typeof defaultValue === "number" ? { defaultValue } : {}
+			...typeof defaultValue === "string" || typeof defaultValue === "number" ? { defaultValue } : {},
+			...bound("maxLength")
 		};
 		case "number": return {
 			...base,
 			type: "number",
-			...typeof defaultValue === "number" ? { defaultValue } : {}
+			...typeof defaultValue === "number" ? { defaultValue } : {},
+			...bound("min"),
+			...bound("max")
 		};
 		case "codemirror-text":
 		case "codemirror-json": return {

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/package.json

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

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -55,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

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/reference/authoring-errors.md

@@ -234,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/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)).
 

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

@@ -69,8 +69,7 @@ A step's params are templates, evaluated in full (conditions, loops, filters). A
 a row's button posts `{ jobId: '{{ list_jobRows.item.id }}' }` — the row that was clicked; the short name is refused.
 
 **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 needs no punctuation.)
+each value keeps its own type, and nothing depends on the quoting.
 
 **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
@@ -106,7 +105,7 @@ ticks while the element is mounted and the tab is in view, never in the builder
 
 **A number that goes round, or stops:** `cycleState({ key: 'slide', length: 4 })` is "next" — after the last the first
 — and `by: -1` "previous"; `stepState({ key: 'shown', by: 40, max: 'apiContainer_site.data.total' })` adds and stops
-at the bound. Each is the `setState` it stands for, with the arithmetic written once.
+at the bound.
 
 **Scrolling** is a step on the element whose box scrolls (`overflow-x: auto` on a row of cards): `scrollBy('cards',
 { x: '80%' })` moves it by most of what it shows (`'-80%'` back, `'240'` pixels), `scrollTo('cards', { x: 'end' })`
@@ -165,6 +164,8 @@ Pages that see each other — cursors, presence, a shared board — talk over a
 asks it. `appendState({ key, value, withId: true })` stores `{ id, value }` — bind `.value`, address by `.id`.
 `whenFailed` matches every outcome that is not `completed` (also `skipped`, `aborted`). A failed run gives `reason`,
 and `error` only when the server or a step wrote one for the caller (a task throwing `ActionRefusal`, `flow.fail` with
-`tellCaller`) — so show `{{ saved.error ? saved.error : "…" }}`, never the bare `error`.
+`tellCaller`) — so show `{{ saved.error ? saved.error : "…" }}`, never the bare `error`. That pair is one call:
+`...runServerActionOrNotify('saved', { actionId, input }, 'Could not save')` — the named run, then that toast
+(`{ appearance, placement }` fourth).
 
 `when(rule, step)` around a step that already has a `when` adds to it: both must hold.

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

@@ -1,31 +1,37 @@
 # Plugins
 
-A plugin is a React component of the project's own — a chart, a map, a game — hosted in the space by a `custom`
-element that names it by `renderType`:
+A plugin is a React component of the project's own — a chart, a map, a game — and an element type of its own. The
+space places it from its `declaration.ts`, typed by what it declares:
 
 ```ts
-custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best: 'state.arcadeBest' } })
+const nebulaRun = defineElement(nebulaRunDeclaration);
+nebulaRun({ id: 'arcade', shipColor: 'amber', bind: { best: 'state.arcadeBest' } })
 ```
 
+(`custom({ renderType })` is for a component registered by name, with no declaration.)
+
 ## Creating one
 
 The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli plugin add seat-picker` (a
 package of its own and packing it: the CLI skill).
 
-One folder, four files: `SeatPicker.tsx` (the component), `declaration.ts` (its `type`, the `triggers` it fires, the
-`callbacks` it answers to, and the element the builder adds — data only), `Settings.tsx` (its panel in the builder), and
-`index.ts` (`Object.assign(Component, declaration, { pluginSettings: Settings })`). An event or an action is declared in
-`declaration.ts` and registered by the component from there, never only in the component.
-
-A plugin fires its events with `interactionsManager.interactionTrigger(id, action, payload)` whenever it has news —
-from its first effect too: a flow starts once the page has finished mounting, so the `setState` it calls is there. No
-`queueMicrotask` or delay of your own. An event that REPORTS a state, and may fire again before its flow ends (as a
+One folder, four files: `SeatPicker.tsx` (the component), `declaration.ts`, `Settings.tsx` (its panel in the builder),
+and `index.ts` (`Object.assign(Component, declaration, { pluginSettings: Settings })`). The declaration is data only,
+`definePlugin<SeatPickerAttributes>()({ type, label, attributes, triggers, callbacks })` from
+`@plitzi/sdk-authoring/plugin`: the rest of what the builder needs is derived. An event or an action is declared there
+and registered by the component from there, never only in the component.
+
+A plugin fires its events with `const fire = usePluginTrigger(declaration)` (`@plitzi/plitzi-sdk`), typed by the
+declaration: `fire('onPick', { seat })` — an undeclared event, or a payload missing a field its `preview` names, does
+not compile. Nothing fires while the page is edited. Fire whenever there is news — from the first effect too: a flow
+starts once the page has finished mounting, so the `setState` it calls is there. No `queueMicrotask` or delay of your
+own. An event that REPORTS a state, and may fire again before its flow ends (as a
 component reads its real value right after mounting), wants `whileRunning('queue', …)` on the flow: by default a firing
 while the flow runs is dropped, and the stale first report would stick.
 
 ## Props
 
-**The host element's attributes ARE the component's props.** Whatever the space writes on the `custom` element arrives
+**The element's attributes ARE the component's props.** Whatever the space writes on it arrives
 by the same name, and so does whatever a binding writes — which is what makes a plugin live: bind an attribute to
 `state`, a provider or a row, and the component re-renders with the answer. Prefer this to anything else.
 
@@ -34,6 +40,8 @@ panel edits for a plugin it has no controls for; from code, write attributes. A
 "Settings Malformed" in the page.
 
 Every prop is optional with a default: an attribute not authored yet, or a binding not answered yet, is `undefined`.
+One whose declared default is a number or a boolean arrives as one, written or bound: type it `number`, never
+`number | string`.
 
 ## The component
 
@@ -73,7 +81,7 @@ on ([kept state](kept-state.md)), what a plugin writes there — its layout, a c
 ## Laying out the space's elements
 
 A plugin that arranges elements — a dock, tabs, a masonry — HOLDS them: they are its children in the space
-(`custom({ renderType: 'dock', children: [feed, tools] })`, or dropped into it in the builder), and the component
+(`dock({ id: 'dock', children: [feed, tools] })`, or dropped into it in the builder), and the component
 places each in a box of its own, by the id it was authored under:
 
 ```tsx
@@ -138,16 +146,15 @@ with thousands of shapes fast — see [drawing](drawing.md).
 ## Registering
 
 A project `plitzi create` wrote registers every folder of `src/plugins` by itself, under the folder's name in
-camelCase (`StatCard` → `statCard`). Anywhere else, the entry registers the component under its `renderType`: the
-third argument to `render()`, `<PlitziSdk.Plugin>` in a React application, `plugins` on a page server of your own. A `renderType` nothing registered
-renders "Custom Component … Not Found", and a page server logs the missing `renderType` at `error` once per
-space: on a server, register it in `plugins` AND name it in the deployment's `pluginNames`.
+camelCase (`StatCard` → `statCard`): its type. Anywhere else, the entry registers the component under its type: the
+third argument to `render()`, `<PlitziSdk.Plugin>` in a React application, `plugins` on a page server of your own. A
+type nothing registered renders "Custom Component … Not Found", and a page server logs it at `error` once per space:
+on a server, register it in `plugins` AND name it in the deployment's `pluginNames`.
 
-A plugin PACKAGE, loaded by a space from its `plugin-manifest.json`, is an element TYPE of its own rather than a
-`custom` host — it is how the builder adds one somebody dropped. Author it with a typed factory:
-`defineElement<SeatPickerAttributes>(declaration)` from the plugin's own `declaration.ts`, or
-`elementsFromManifest<{ seatPicker: SeatPickerAttributes }>(manifest)` from what it published — or untyped,
-`element('seatPicker', { id: 'seats', start: 3 })`.
+On Plitzi, every element loads from the plugin the space installed (`plitzi plugin pack` and `upload`: several folders
+are one plugin). A plugin PACKAGE is placed the same way:
+`defineElement` from its `declaration.ts`, or `elementsFromManifest<{ seatPicker: SeatPickerAttributes }>(manifest)`
+from what it published.
 
 ## Checked like a built-in element
 
@@ -160,11 +167,10 @@ import declaration from './plugins/SeatPicker/declaration';
 authorSpace(space, { plugins: [declaration] });
 ```
 
-It is then held to what it declares, whether it is authored as its own type or hosted by `custom({ renderType:
-'seatPicker' })`: a flow on an event it never fires, a step sent to an action it does not answer, an attribute it does
-not read — each is refused with the name it should have been. (`pluginTypes: ['seatPicker']` only tells the linter the
-type exists; nothing about how the space uses it is checked.) A `custom` host whose component is NOT handed over is not
-judged on its events at all — nothing here knows them.
+It is then held to what it declares: a flow on an event it never fires, a step sent to an action it does not answer,
+an attribute it does not read — each is refused with the name it should have been. (`pluginTypes: ['seatPicker']`
+only tells the linter the type exists; nothing about how the space uses it is checked.) A plugin whose declaration is
+NOT handed over is not judged on its events at all — nothing here knows them.
 
 Its events and actions have builders typed from the same declaration, so a name it does not declare is a compile error:
 
@@ -175,9 +181,9 @@ button({ content: 'Clear', flows: [[onClick(), declaredCallback(declaration, 're
 
 A plugin says what HAPPENED through its events (`onPick`, with the seat in the payload) and lets the space's flows
 decide what that means — write `state`, open a modal, call a server action. Prefer that to writing `state` from inside
-the component: the flow is visible in the space, the builder shows it, and the same act can come from a button too.
+the component: the flow is visible in the space, and a button can do the same.
 
-- A param declared `number` or `boolean` arrives as one, written or bound; any other arrives as written.
+- An action's param declared `number` or `boolean` arrives as one, written or bound; any other arrives as written.
 - To act when another element appears, `useElementVisible('tools')` (`@plitzi/plitzi-sdk`) — never watch classes.
 - A name for screen readers is a prop of its own: declare `label`, write it as the root's `aria-label`.
 
@@ -186,14 +192,14 @@ the component: the flow is visible in the space, the builder shows it, and the s
 The builder draws the element on its canvas while somebody edits the page: a click selects it, a drag moves it, a key
 belongs to the editor.
 
-- **Outside preview, do nothing on your own.** `usePlitziServiceContext().settings.previewMode` is `false` while the
-  page is edited. Declared interactions are already held back then; your own click handlers, timers, global listeners,
-  permission prompts and map gestures are not — gate them on `previewMode`, and still render something to select.
+- **Outside preview, do nothing on your own.** `usePlitzi().settings.previewMode` is `false` while the
+  page is edited: gate your own click handlers, timers, listeners, permission prompts and map gestures on it, and
+  still render something to select.
 - **A drag lives in state, not in refs read while rendering** (the project's lint refuses that): keep the gesture
   in `useState`, mirror the latest props into a ref inside an effect, and attach `pointermove` on `pointerdown`.
 - **Never the global `window` or `document`.** The canvas is a frame of its own and the code runs in the builder's
   window: listen, measure and go full screen through the node's own page (`ref.current.ownerDocument`, its
-  `defaultView`) or `usePlitziServiceContext().utils.getWindow()`. An `instanceof` check takes its class from there too.
+  `defaultView`) or `usePlitzi().utils.getWindow()`. An `instanceof` check takes its class from there too.
 
 ## The plugin's stylesheet and the space's CSS
 
@@ -209,5 +215,4 @@ fonts a stylesheet names are carried the same way.
 A map, a chart library, anything that positions its own markers or popups: its roots are the library's to place. Never
 give them a class that sets `position` — the element falls into the page's flow, offset by every marker before it. Put
 the look in the plugin's own stylesheet (imported CSS ships beside the bundle) and take colours from custom properties
-the space sets (`--seat-accent: var(--accent)` in `customCss`); a canvas or WebGL layer resolves them through a probe
-element with `getComputedStyle(probe).color`, again whenever `theme.resolved` changes (bind it as a prop).
+the space sets (`--seat-accent: var(--accent)` in `customCss`).

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

@@ -50,7 +50,7 @@ refuses or warns of, with the fix.
     every switch through `computed` (`plates: '{{ state.platesOff ? false : true }}'`) so its default shows before
     anybody touches it.
 12. **Hand plugins over as their declarations**: `authorSpace(space, { plugins: [declaration] })` holds a plugin —
-    its own type, or a `custom({ renderType })` host — to the events, actions and attributes it declares. See
+    placed with `defineElement(declaration)` — to the events, actions and attributes it declares. See
     [plugins](plugins.md).
 13. **Usable without sight.** Screen readers and browser agents (Claude in Chrome) find a page's controls in its
     accessibility tree: every button and link has words (an icon-only button a `title`), every field a `label`