@plitzi/sdk-server 0.38.4 → 0.38.6

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

@@ -9,13 +9,8 @@ custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best
 
 ## Creating one
 
-The CLI writes it, in the shape Plitzi's own elements are written in:
-
-```bash
-npx @plitzi/cli add plugin seat-picker legend # elements of this project (src/plugins/<Name> in a CLI project)
-npx @plitzi/cli create seat-picker --plugin   # a package of its own, with a preview
-npx @plitzi/cli pack plugin                   # built, with its manifest and the zip the builder takes
-```
+The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli add plugin 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
@@ -38,8 +33,7 @@ by the same name, and so does whatever a binding writes — which is what makes
 panel edits for a plugin it has no controls for; from code, write attributes. A `settings` that is not JSON renders
 "Settings Malformed" in the page.
 
-Every prop is optional and has a default: an attribute not authored yet, or a binding whose source has not answered,
-is `undefined`, and a plugin that renders nothing then is a hole in the page.
+Every prop is optional with a default: an attribute not authored yet, or a binding not answered yet, is `undefined`.
 
 ## The component
 
@@ -73,7 +67,36 @@ const stop = state.subscribe(next => save(next));      // called after every cha
 ```
 
 `state` is the current value, `setState` replaces it (or takes an updater), `setStateByKey` writes one key,
-`clearState` empties it, `subscribe` listens. Bindings on `state.*` re-render at once.
+`clearState` empties it, `subscribe` listens. Bindings on `state.*` re-render at once. With the space's `keepState`
+on ([kept state](kept-state.md)), what a plugin writes there — its layout, a choice — is back after a reload too.
+
+## 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
+places each in a box of its own, by the id it was authored under:
+
+```tsx
+import { elementChildren } from '@plitzi/plitzi-sdk';
+
+{elementChildren(children).map(({ id, node }) => <section key={id} style={placed[id]}>{node}</section>)}
+```
+
+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.
+
+## Its own server code
+
+`plitzi add plugin board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
+under `/fn/plugins/board/`; the component names them, with nothing for the space to wire:
+
+```tsx
+const route = usePluginRoute('board'); // from '@plitzi/plitzi-sdk'
+const url = route('/layout'); // undefined where no server runs code (the canvas)
+```
+
+Its `ctx.kv` is the plugin's own; the space's credentials and channels are not.
 
 ## Talking to other pages
 
@@ -104,13 +127,12 @@ import { useFlag } from '@plitzi/plitzi-sdk';
 const newChart = useFlag('newChart'); // false for a flag the space does not declare
 ```
 
-Gating the whole plugin needs no code: give its element `flag: 'newChart'`. `useFlag` is for a plugin that changes
-inside — a new mode, an extra panel.
+Gating the whole plugin needs no code: give its element `flag: 'newChart'`.
 
 ## Drawing and animating
 
-A canvas, WebGL or a loop of its own: `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` — see
-[drawing](drawing.md).
+A canvas, WebGL or a loop of its own: `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` — and keeping one
+with thousands of shapes fast — see [drawing](drawing.md).
 
 ## Registering
 
@@ -154,6 +176,10 @@ A plugin says what HAPPENED through its events (`onPick`, with the seat in the p
 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.
 
+- A 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`.
+
 ## Behaving in the builder
 
 The builder draws the element on its canvas while somebody edits the page: a click selects it, a drag moves it, a key
@@ -162,10 +188,21 @@ 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.
+- **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.
 
+## The plugin's stylesheet and the space's CSS
+
+A plugin's stylesheet ships in a layer below the space's (`plitzi-sdk-plugin`, written by the build): the space's
+classes and `customCss` win over it whatever their specificity, as over a built-in element's defaults.
+
+A file a library needs whole is imported as Vite imports it, and travels inside the bundle: `worker.js?raw` is its
+text (a worker, started from `URL.createObjectURL(new Blob([source]))`), `engine.wasm?inline` a data URI. Images and
+fonts a stylesheet names are carried the same way.
+
 ## Components that draw into DOM they do not render
 
 A map, a chart library, anything that positions its own markers or popups: its roots are the library's to place. Never
@@ -173,27 +210,3 @@ give them a class that sets `position` — the element falls into the page's flo
 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).
-
-## Components that draw a lot
-
-A canvas with thousands of shapes on it — a whiteboard, a diagram, a map of points — is judged on a slower machine than
-yours: sixty frames a second here says nothing about a four-year-old laptop. What keeps one fast is doing work in
-proportion to what CHANGED, not to what is there:
-
-- **Two layers.** Paint what stands still on one canvas and leave it; clear and draw the one over it every frame, with
-  only what moves: the cursor, the selection, what is being dragged.
-- **Repaint the part that changed.** Something added, edited or removed repaints the area it was and is in, clipped,
-  with whatever reaches into it — not the whole board. A pan moves the picture already painted by whole device pixels
-  and paints the edges it uncovers.
-- **Draw a dragged group once.** Everything picked up moves by the same amount at every step: draw it to a canvas of its
-  own when the drag begins and copy that into place after.
-- **Cache per object, not per frame.** Treat elements as immutable and key what is derived from one — its bounds, its
-  shape, a resolved connector — on the object itself (a `WeakMap`), so nothing is worked out twice for the same thing.
-- **Hand the space outcomes, not motion.** A stroke finished, a selection changed: a trigger each. Firing one at every
-  pointer move runs a flow and renders the page at every pointer move.
-- **Measure with a bench, throttled.** A script that drives the real thing in a browser with the CPU slowed
-  (`Emulation.setCPUThrottlingRate`) and reports script time per frame, not only frames per second — and a test that
-  counts WORK (full repaints, strokes drawn during a drag), which holds on any machine where a timing does not.
-
-Pizarra, the collaborative whiteboard on the platform (`pizarra.plitzi.app`), does all of it on a board of thousands
-of elements.

package/skills/plitzi-authoring/reference/review-checklist.md

@@ -9,6 +9,8 @@ of it; each line is something that has shipped broken before.
 - [ ] Every **suggestion** is taken, or left for a reason you can say (the copies are about to diverge; three cards a
       person rewords on the canvas) — and then quieted where it is written, `quiet: ['repeated-shape']`, so it stops
       burying the ones that matter. The ones your change opened up first — [efficiency.md](efficiency.md).
+- [ ] `npm run lint:space` is clean — no file past 400 lines, no rows of data inline, no colour that is not a token —
+      or each departure says why where it is ([structure.md](structure.md#checked-for-you)).
 - [ ] No console errors on any page you touched.
 
 ## Nothing flashes, nothing jumps

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

@@ -1,6 +1,6 @@
 # Structuring a space that grows
 
-A one-screen space fits in `src/space.ts`. Past a few pages, split it by what changes together — a file per part, short
+A one-screen space fits in `src/space/index.ts`. Past a few pages, split it by what changes together — a file per part, short
 enough to read whole — and keep every repeated thing in exactly one place. `npx @plitzi/cli create shop --template
 catalog` writes a complete small site in this shape (tokens, a layout, a card component, typed data, a page per file)
 to read before writing one.
@@ -71,6 +71,30 @@ container({ id: 'quick', class: quickGrid, children: QUICK.map(item => quickCard
 When items differ in ONE detail (one link needs a binding), put that detail in the item's data as an optional field
 — never an `if (item.id === 'team')` inside the map.
 
+## Pages of one shape are a family
+
+Docs pages, a menu's sections, a team's profiles: the same shape, different words. Write the shape once and the pages
+as data with `pageFamily` — it gives each page its id, slug, titles, folder and layout, and builds each body inside
+`scope(entry.id, …)`, so the ids two pages of the family give are never one:
+
+```ts
+import { pageFamily, heading, markdown } from '@plitzi/sdk-authoring';
+import { SECTIONS } from '../data/sections';   // [{ id: 'starters', title: 'Starters', slug: 'starters', description, body }]
+
+pages: [
+  home,
+  ...pageFamily(
+    { folder: 'menu', layout: { id: 'site', slot: 'site-slot' }, seoTitle: entry => `${entry.title} — Menu`,
+      body: entry => [heading({ id: 'title', content: entry.title }), markdown(entry.body, { id: 'body' })] },
+    SECTIONS
+  )
+]
+```
+
+Adding a page is adding an entry; two entries of one id or slug are refused as any two pages are. For one shape over
+records a visitor browses — a product, a post — a single page with a route param (`slug: 'posts/:postId'`) reading
+the record is the answer instead: one page, as many addresses as records.
+
 ## Names
 
 - **Ids:** `area-role` in kebab-case — `hm-traffic-title`, `docs-nav-docs-data`. Never the builder's positional
@@ -90,3 +114,10 @@ per page. It renders; it is not maintainable. When you work on such a file, leav
 
 Each of those is safe to do on its own: authoring refuses anything that would not render, and the visual check shows
 the rest.
+
+## Checked for you
+
+`npm run lint:space` (`plitzi lint`) reads the source for what this page asks — a file past 400 lines, pages in one
+file, rows of data inline, a colour that is not a token, CSS copied three times, a row singled out by its id inside a
+`map`, a minted id, a file nothing imports — at file:line, beside authoring's suggestions. Leave it clean; a departure
+on purpose says why where it is: `// plitzi-lint-disable-next-line <code> -- why`.

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

@@ -26,7 +26,7 @@ characters. Only what you authored is interpolated.
 
 A binding's template renders TEXT by default. For an attribute that holds a list, a number or a flag — a list's
 `items` above all — hand over the VALUE with `returns: 'value'` (`returnMode: 'value'` on the transformer). The
-template must be a single `{{ expression }}`:
+template must be a single `{{ expression }}`, after any `{% set %}` that name its parts:
 
 ```ts
 list({ id: 'shown', source: 'controlled',
@@ -63,7 +63,8 @@ outside the element that publishes it — each with the name it should have been
   `rows|sort((a, b) => b.score - a.score)`, `rows|filter(r => r.score >= min)`, `rows|map(r => r.name)`.
 - Tests: `is defined`, `is empty`, `is null`, `is iterable`, `is even`, `is odd`, `is same as(x)` (strict: `false` is
   not `'false'`, `0` or an unset value), `is divisible by(n)`, and their `is not` forms. `null` and `none` are literals.
-- Functions: `range`, `min`, `max`, `cycle`.
+- Functions: `range`, `min`, `max`, `cycle`. `abs` is a filter (`x|abs`); floor and ceil are `x|round(0, 'floor')` and
+  `x|round(0, 'ceil')`; a clamp is `min(max(x, low), high)`.
 - **Not supported**: `matches` (no regular expressions are evaluated — use `starts with`, `ends with`, `in`), macros,
   `include`/`extends`, and any filter or function not listed here. `authorSpace` refuses them, and anything else the
   interpreter would read past, rather than letting a template render a value nobody wrote.
@@ -99,6 +100,8 @@ A lookup across two sources — a row joined to the stats around it:
   string stays a string however it looks — a password typed `1234` arrives as `"1234"`. Nothing is guessed from the
   text: to convert, declare the type where the value lands (`setState`'s `type`, the action's input field). Text around
   the tokens is text, unless it makes a JSON object or array — then it is that document (see `json_encode` above).
+  **One exception: a param that is only a JSON filter (`{{ rows|json_encode }}`) is the value it encodes** — the list,
+  not its text — so an action input receiving it is declared `json`; a `text` field refuses it (422).
 
 ## Dates
 

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

@@ -3,13 +3,20 @@
 ## One call: `inspectPage`
 
 ```ts
-import { authorSpace, inspectPage } from '@plitzi/sdk-authoring';
+import { answerAction, authorSpace, inspectPage, openPage } from '@plitzi/sdk-authoring';
 
 const { handles } = authorSpace(space);
-await page.goto('/');
+await openPage(page, '/');
 expect((await inspectPage(page, handles)).problems).toEqual([]);
 ```
 
+`openPage` waits for the page to settle — loaded, and nothing asked for in half a second — counting no stream that
+stays open: Playwright's `networkidle` never comes on a page with a realtime `channel`.
+
+A test that would SAVE something answers that action itself, before opening the page, so it never writes the server's
+`kv` the next test (or the developer) reads: `await answerAction(page, 'wall', { windows: [] })` — or a function of the
+input. Every other call goes through.
+
 It checks the open page and returns EVERY problem at once, one sentence each, naming the element and the reason:
 
 - every element the page owes is present and visible — its own and those of the layouts around it

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

@@ -1,7 +1,7 @@
 # Data typed by a sample
 
 `source('site', home)` names a provider's source from a sample of its answer — the JSON file it reads, imported
-(`import home from '../../public/data/home.json' with { type: 'json' }`). Every path is then completed by the editor
+(`import home from '../data/home.json' with { type: 'json' }` — `src/data/`, or `public/data/` with no server). Every path is then completed by the editor
 and checked: `site.data.hero.titel` is a type error, and refused `source-field-unknown` if it gets past the types.
 
 ```ts
@@ -18,3 +18,5 @@ apiContainer({ id: site.id, query: '/data/home.json', children: [
   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.
 - 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.

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

@@ -33,7 +33,7 @@ bar.
    ```ts
    import { authorSpace } from '@plitzi/sdk-authoring';
 
-   import { space } from './src/space.ts';
+   import { space } from './src/space/index.ts';
 
    try {
      const { schema, warnings, suggestions } = authorSpace(space, { plugins: [] /* your declarations */ });