@plitzi/sdk-server 0.38.10 → 0.38.12

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

@@ -69,12 +69,11 @@ 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 says the same without the 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
-`operator: 'empty'` / `'notEmpty'`, which treat missing and `''` alike.
+`operator: 'empty'` / `'notEmpty'` (no `value`), which treat missing and `''` alike.
 
 ## Writes and what they refresh
 
@@ -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/layouts.md

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

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

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

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

@@ -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
@@ -83,8 +91,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 +116,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
 ```
 
@@ -137,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
 
@@ -159,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:
 
@@ -174,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`.
 
@@ -185,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
 
@@ -208,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/realtime.md

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

package/skills/plitzi-authoring/reference/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`

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

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