@plitzi/cli 0.38.10 → 0.38.12

package/CHANGELOG.md

@@ -1,5 +1,290 @@
 # @plitzi/cli
 
+## 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/sdk-authoring@0.38.12
+
+## 0.38.11
+
+### Patch Changes
+
+- cadf70a: - **`server.cache.invalidate` drops what a page is rendered from** (`@plitzi/sdk-server`): the pages, the RSC answers
+  and the schema data they are rendered from go together. It dropped the pages alone, and the next request rendered
+  the same page again from the schema still cached under the same key — a publish that invalidated the space changed
+  nothing until the schema's TTL ran out. `clear()` and `size` cover the three. A filter on `hostname` drops the schema
+  data too, which belongs to no one host. `server.cache` is `null` only when nothing is cached (`cacheTtlMs: 0` and
+  `rsc.cacheTtlMs: 0`).
+
+  ## Style inspector
+  - **Finds a property** (`@plitzi/sdk-style`): a search above the categories narrows them to the ones that edit what was
+    typed — a CSS name in any order of its words (`border radius` finds the four corners), a category's title, or a
+    common word for it (`bg`, `rounded`) — opens them, and shows the advanced rows when the match lives there. Escape
+    clears it. The categories' properties live in one list (`categoryKeys.ts`) that the dots, the advanced hint and the
+    search all read.
+  - **Rows that fit**: a section with more than two controls puts its label above them and lays them out in as many
+    columns as the panel is wide, instead of one row where every label was cut (`Appearan…`, `Cell Spaci…`, the five
+    scroll-snap controls). A row's label column is 80px.
+  - **Where a value comes from, said quietly**: the label's tint keeps its four meanings — set here, from a token, bound
+    to data, inherited — without the solid blocks of colour; hovering says which (an inherited one names its selector and
+    breakpoint) and that a click resets it, the click shows it by striking the label through. The footer's info icon
+    holds the legend, and its arrow folds every category.
+  - **What is being edited**: an "Editing … › Hover" line under the pickers whenever the rules being written are not the
+    selector's plain ones, with a button back to them. Ancestor, pseudo-element and condition fold behind a toggle —
+    never while one is in use.
+  - The class being edited is the panel's one strong mark (violet), the element's type defaults a softer one; the tools'
+    tabs fit the panel and are reachable from the keyboard.
+
+  - **Lists edited in a popover, all alike**: box and text shadows, transforms, transitions and filters share one row
+    (the CSS it writes, a swatch, a remove button) and one popover (a title, a close button, Escape, the focus moved
+    into it). What none of them could read is now kept and edited as text instead of being replaced with a default — a
+    token for the whole value, `drop-shadow(…)`, `url(#…)`.
+  - **Values read the way CSS writes them**: a shadow with two, three or four lengths and its color on either end;
+    `rgba(…)` inside text shadows and filters no longer split; negative shadow offsets accepted; a transition with any
+    of its parts left out; brightness, contrast and saturation past 1. Transition presets are written as CSS — the
+    preset names (`easeInQuad`) made the browser drop the whole declaration — the curve can be dragged into one of your
+    own, and the preview stops with the editor. `font-color` (not CSS) became `color`.
+  - **Background layers keep what they hold**: a repeating gradient (now a switch), a radial gradient's explicit size, a
+    token or `image-set()` as a layer (a "Custom (CSS)" layer), a one-value position read as CSS reads it (`20%` is
+    `20% center`), lists shorter than the layers repeated as CSS repeats them, an unset repeat read as tiling, two-position
+    stops, negative angles — every one of them was rewritten on the next edit of any layer. Defaults are no longer
+    written back, and "Token values" no longer bakes resolved tokens into the layers.
+  - **A layer's editor in two halves** — what it draws, then where it goes (size, position, tile, attachment, clip,
+    which now offers `text`). The gradient's stops sit on one bar, each a handle that drags or moves with the arrow keys;
+    the stop's color and position below it. Previews and swatches resolve the space's tokens.
+  - Spacing tells margin (dashed, outside) from padding; Border's sides are labelled and readable in the dark theme; a
+    class's menu says what each action does to whom; the Style Manager opens at a size that holds both columns.
+
+  ## Builder
+  - **Shortcuts**: `?` shows every shortcut the builder answers to — the same list the "Nothing selected" card teaches
+    from — and ⌘\ / Ctrl+\ hides both side panels for the canvas alone and brings back the ones that were open. Both
+    work with the canvas focused.
+  - **Panels keep their width**: each side panel opens at the width it was left at; the right one starts at 380px.
+  - **Text no smaller than 11px** across the builder's panels (it went down to 10px in fifty places).
+
+  ## Realtime
+  - **A page hears what it sent when it asks to** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`):
+    `publishOn('room', 'react', data, { echo: true })`, `useChannel().publish(type, data, { echo: true })` and the
+    channel's `publish` callback (`echo`) hand the message back to the page that sent it too, once the server took it —
+    stamped like everyone's, with `echo: true`, its `from` the channel's `me`. Without it a page still never hears its
+    own messages, and the docs said "every page on its topic hears it": they now say every OTHER page. Presence never
+    echoes.
+  - **A topic is opened only once it names one** (`@plitzi/sdk-elements`): `useChannel` — and so the `channel` element —
+    opens a topic only when a channel of the space covers it, by the same `matchChannel` the server decides by. A topic
+    written from data that has not arrived (`room:` while its provider loads, or its template still as text) asked the
+    server for both, was refused with a 403 and a console error on every load, and is now waited for.
+  - **Pages that watch** (`@plitzi/sdk-server`, `@plitzi/cli`): a connection whose page carries the `plitzi-observer`
+    cookie hears its topics and says nothing on them — no `$join`, no presence, its publishes taken and dropped.
+    `page check`, `page shot` and `verify` load pages that way, so checking a live site is no longer a visitor walking
+    into a room (`X walked in`, a member more in every picture). `--presence` takes part as a visitor does.
+
+  ## Authoring
+  - **`template-in-value`** (refused): a `{{ }}` inside an attribute that is an object or a list — a provider's
+    `input`, a list's `items`, a plugin's settings — is never evaluated: only an attribute that is text is interpolated,
+    and the page server reads attributes as saved. A provider's `input` also replaced the route param of the same name
+    the action was already given, so `input: { room: '{{ navigation.routeParams.room }}' }` reached the task as `""` and
+    the page answered 404; its refusal says the action is handed the page's route and query params already. Anything
+    else is a binding on the attribute. `mockData`, a sample, is not held to it.
+  - **Rules on top of a class need no `id`** (`class: [card, { gap: '6px' }]`): they are named after the id the element
+    is given, written or not. `modifier-without-id` is gone; a one-off tweak no longer needs a name nothing reads.
+  - **Typed list rows have `inTemplate`**, as untyped ones do, and `bindTemplate`, `visibleWhen`, `hiddenWhen` and
+    `variantFrom` take a typed source's path as well as a name: turning a list typed broke every template of its rows.
+  - **`when({ field, operator: 'empty' })`** takes no `value` (nor `notEmpty`), as flows.md recommends; it did not
+    type-check.
+  - **Data-driven colours**: a style binding on a custom property (`{ to: '--who', category: 'style' }`) is written as
+    named — it was camel-cased into `who` — so a class reads `var(--who, var(--muted))`. A style binding's value carrying
+    `;` or braces is not written: the page server writes inline styles as text, and such a value added declarations of
+    its own. `binding-target-unknown` on `style` or a CSS property says to bind it in the `style` category.
+  - `unknown-attribute` for `decorative` on an `svg` or a `fontAwesome` says what it means: without a `label` it is
+    already hidden from screen readers.
+
+  - **A folder nobody declared says where to declare it**: `folder-undeclared` (a page, a layout, a folder's parent)
+    ends with `pageFolders: [{ id, name }]` on the space, and with the line of the `pageFamily` that wrote the page. A
+    folder starts its pages' addresses (`/docs/quickstart`), so a misspelt one is never declared on the author's behalf.
+    The skill's `pageFamily` example declares its folder.
+  - **A tag is an element**: a `subType` this element has not but another has — `container({ subType: 'ol' })` — names
+    that element (`list({ subType: 'ol' })`) instead of the value two letters away (`dl`). Read off the elements'
+    declarations, for every element and tag.
+  - **A `pageFamily`'s body is written once**: `repeated-shape` and `repeated-on-pages` no longer count the same part of
+    each page of one family as copies — they were offering a component for exactly what the docs recommend. Copies within
+    one page, or across pages written one by one, are still offered.
+  - **Colour emoji are not text to `page check`**: a character painted in its own colours (🎲, `❤️`, a keycap, a ZWJ
+    sequence) is left out of the contrast measure, which compared `color` with the tile behind it and failed `verify`
+    in the theme whose text colour was close to the tile. A symbol drawn as text (✓, ★) is still measured.
+
+  - **`declared-callback-target`** (refused): a value beside `on` in `declaredCallback(…, { on, date })` — written as
+    `openModal`'s target reads — was read nowhere, and the step ran without it. Refused, with the `params` it goes in
+    (`{ on: 'calendar', params: { date } }`) and whether it is one of the callback's declared params.
+  - The skill's list rows show the typed form beside the untyped one: with `items` typed by a sample, `r.item` is a path
+    (`from: r.item.title`), not text to put in a template string.
+  - **`slot-not-class`** (refused): rules written in place in a slot — `slots: { error: [fieldError, { color }] }`, past
+    the type in JavaScript or a spec rebuilt from JSON — were taken for a declaration with no rules, and `authorSpace`
+    failed later with `Cannot read properties of undefined (reading 'desktop')`, naming nothing. Refused where the slot
+    is written, naming the slot and the element, with the `styles()` declaration to hand instead.
+
+  ## CLI
+  - **`page shot --click` (and `--clip`, `--wait-for`, `--scroll-to`, `--steps`) takes any selector**: a value that is
+    not an element's name (letters, digits, `-`, `_`) is a selector, CSS or Playwright's own (`button:has-text("Orbit")`).
+    It was wrapped as a name, and an invalid selector ended the command with Playwright's stack trace; it is now refused
+    with the reason.
+
+  - **`plitzi functions add <package>`**: a package the functions use comes with them, as a function carries its
+    dependencies. Installed in the project, it is bundled (web APIs only, minified, its licence kept) into
+    `src/functions/vendor/<package>.js`, with a `.d.ts` re-exporting the installed package's types, imported as
+    `./vendor/<package>.js` and pushed, built and run with the rest — nothing is resolved anywhere else, so the builder,
+    the sandbox and the push are unchanged. A package that reaches Node (`fs`, `node:*`) is refused, naming what it
+    reached; one past the functions' 1 MB is too; one that reads `process`/`Buffer` is warned about. The build's refusal
+    of a package import now names the command.
+  - **`page shot` targets**: a bare word is an element's name, or — no element named so — a tag (`textarea`); resolved on
+    the loaded page for `--click`, `--clip`, `--scroll-to`, `--wait-for` and `--steps`. In `--steps`, `type` takes a
+    quoted element with spaces (`type ".panel textarea" hola`) — it was cut at its first space and typed the rest — and
+    fails when the click leaves no field focused, rather than sending the keys to the page's shortcuts.
+
+  ## Server
+  - **`server.listen()` resolves once the port answers** (`@plitzi/sdk-server`) — in a fleet, once the first worker
+    does. `serveProject` writes `tmp/dev-server.json` and says `pages on …` after it, not on the line after `listen`:
+    for about 0.4 s a tool trusting the line (CI, Playwright's `webServer`, `page check`) was refused. A port it cannot
+    take still ends the process, or goes to `onListenError`, and the promise is then never resolved.
+  - **Runs set for later** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`, `@plitzi/sdk-authoring`, `@plitzi/plitzi-builder`):
+    a turn that runs out, a bot's move, a hold that lapses — one run starting one of the space's actions in N seconds,
+    whether or not a page is still open. The action says it may be with a **`later` trigger** (no access rule: the run
+    that set it was let in); a flow sets it with `flow.later { action, in, input, key }`, a function with
+    `ctx.later({ … })`, and `flow.cancelLater` / `ctx.cancelLater(key)` drops it. A `key` names it: set again under the
+    same key, the one still waiting is replaced — the newer of two set at once, on every replica — and a running one is
+    left. It is a job of the queue schedules use: due by the store's clock (0 s to 30 days, about a second late at most),
+    once across replicas, retried, shown in Automations → Queue. Refused before anything is queued, with why: no `later`
+    trigger, one switched off, a time out of range, a key that is not one, a server with no jobs. A plugin's functions
+    set none. `ActionJobQueue` gains `cancelPending({ spaceId, key, olderThan? })` and jobs a `key`: the memory, Mongo
+    and MySQL queues implement it, and the shared contract tests it. **MySQL**: `action_jobs` gains `job_key` (and the
+    `action_jobs_key` index), added on first use; with `createTables: false`, run that statement of
+    `mysqlJobSchemaUpgrades()`. A queue of a deployment's own implements `cancelPending` (`09-schedules` shows one).
+  - **A project's `kv` file has one holder** (`@plitzi/sdk-server`): `createFileKv` takes `<file>.lock` with its pid;
+    a second process — another `npm start`, a `--watch` left running — is refused, naming the first (`the server of
+"orbita", on port 8080`) instead of both writing their whole map over each other's changes, and a lock whose process
+    is gone is taken over. `close()` writes what is pending and lets go. A server with `workers` opens the file once, in
+    the primary, and its workers reach it through the fleet (`fleetKv`): each used to open a copy of its own.
+  - **A self-hosted project's credentials** (`@plitzi/sdk-server`, `@plitzi/cli`): `serveProject` answers
+    `getCredential` from `PLITZI_CREDENTIALS` in `.env` — one JSON object, credential id → its keys — so
+    `ctx.fetch({ credential })`, a connector and an `http.request` step work on the project's own server, not only in
+    `functions dev`. The same variable for both (it was `PLITZI_FUNCTIONS_CREDENTIALS`, read by the CLI alone); a value
+    that is not that object is refused with how to write it, instead of every credential going missing.
+  - **`HOST` beyond loopback says where to open it**: with `HOST=0.0.0.0`, `serveProject` prints the machine's network
+    addresses — what a tablet on the same Wi-Fi opens — and that anyone on that network can. `.env.example` names `HOST`
+    and `PLITZI_CREDENTIALS`.
+
+  ## SDK
+  - **`useElementSize(ref)`** (`@plitzi/plitzi-sdk`): the size a plugin's own box is drawn at, followed as it changes —
+    what `useDisplayMode()` cannot say: a tablet held upright is `mobile` by the window and still a week wide by the
+    plugin's box. `undefined` until measured, so the server's page and the hydrated one agree. The breakpoints are
+    unchanged.
+  - The functions docs say how a task's `params` types (how the builder edits them: `codemirror-json`) and an action's
+    `input` types (what the value is: `json`) correspond.
+
+- Updated dependencies [cadf70a]
+  - @plitzi/sdk-authoring@0.38.11
+
 ## 0.38.10
 
 ### Patch Changes

package/README.md

@@ -22,7 +22,7 @@ npx @plitzi/cli plugin upload                  # that zip, on the space you work
   several separated by commas), `--api` for the platform, `--json` for a tool or an agent.
 - **`--dry-run` says what it would do, and does none of it** — on every command that writes or sends: `create`,
   `plugin add`, `runtime add`, `space pull`, `space push`, `plugin pack`, `source pack`, `page import`, `plugin upload`, `functions pull`/
-  `functions push`, `runtime push`/`start`/`stop`/`size`/`vars`, `skills update`, `doctor --fix`. Each file it would write (`+` new, `~` replaced, `-`
+  `functions push`/`functions add`, `runtime push`/`start`/`stop`/`size`/`vars`, `skills update`, `doctor --fix`. Each file it would write (`+` new, `~` replaced, `-`
   removed), what it would install or run, what it would send and where. It still reads what it needs to say so — the
   project, the files it would send, the space it would pull, signing in for that. `upgrade` and `space fix` only show until
   `--write`.
@@ -160,7 +160,8 @@ with its fix). A plugin is declared by its folder: the server, `author` and `pag
 `src/plugins/<Name>/declaration.ts` (`pluginDeclarations` from `@plitzi/sdk-authoring/node`). What the server does
 besides serving the space is the project's own, in files it reads: `src/config/serverOptions.ts` (handed to `serveProject` —
 `images`, `action.limits`, `action.kv`, `rsc`) and, with `--source local`, `src/actions/index.ts` (the space's server
-actions, one `defineAction` each, a file each as they grow).
+actions, one `defineAction` each — `taskAction(task, { trigger })` for one that only runs a task — a file each as they
+grow).
 What `serveProject` wires itself — where the space comes from, the plugins, `public/`, `src/data/`, `src/functions/`,
 the actions' lookups — is left out of `serverOptions`' type (`ProjectServerOptions`), and comes after it, so an option
 there can never unwire it.
@@ -237,6 +238,12 @@ default, and `page shot` names the file by the theme it was painted in. The dev
 full-page `page shot` is the whole page — the pane the SDK scrolls in unrolled, every lazy picture loaded, every arrival
 waiting for the scroll shown as it ends — in `tmp/shots/` unless `--out` says where.
 
+Both load a page as one that watches its realtime channels: it hears them — a topic the server refuses is still
+reported — and says nothing on them, so nobody on the page sees it arrive, join their members or send. `--presence`
+makes it take part as a visitor does. `--click` in `page shot` takes an element's name, a tag no element is named by
+(`textarea`) or any selector, CSS or Playwright's own (`button:has-text("Orbit")`). In `--steps`, an element with a
+space in it is quoted — `type ".panel textarea" hola` — and `type` fails when the click leaves no field focused.
+
 `page shot --compare` writes the two pictures side by side and the differences in red. It compares each section where it
 is on the other page, so a page 400 px longer is said once, with the section the drift starts at; then it pairs the
 texts both pages have and says what each does differently there — `h1 "Learn CSS" — font-size 68px → 60px · y +19px`.
@@ -421,8 +428,8 @@ What a name means when authoring, from the catalogues the checks themselves read
 otherwise be a search through the SDK's types. A name no catalogue holds — `pageFamily`, `styles`, `SpaceSpec` — is any
 export of `@plitzi/sdk-authoring`, answered from the `.d.ts` the project installed, so it is the version the project
 runs. An element of the project's own — `src/plugins/<Name>/` — is explained by its type the same way: what it takes
-(each attribute at its default), fires and answers, and the `custom({ … renderType })` that places it, which `plugin
-add` prints too. `--json` answers in one object; over MCP it is `plitzi://explain/{name}`.
+(each attribute at its default), fires and answers, and how it is placed — its declaration imported and
+`defineElement(declaration)` called — which `plugin add` prints too. `--json` answers in one object; over MCP it is `plitzi://explain/{name}`.
 
 ## `doctor`
 
@@ -479,7 +486,7 @@ did you mean `index.ts`, `src/plugins/`? — and one that differs only in case s
 | `machinery` | the CLI's files (`MACHINERY`), as `upgrade` sees them: gone, behind, or the project's own (said, never failed); one it no longer writes, left over (`src/env.ts`); the scaffold record |
 | `config` | `tsconfig.json` reads `src/` and `plitzi/` and sets what Node's type stripping needs; `tsconfig.build.json` writes the file `start:prod` runs; `.gitignore` keeps `.env` out (and `node_modules`, `tmp`, `dist`, `state`) and `.plitzi/` in; `.env` not in git; the signing secret, as long as the project's own server wants it; a cloud project's key |
 | `sources` | what Node runs as written — `src/main.ts`, `src/config/`, `src/actions/`, `src/space/`, `src/runtime/`, `plitzi/author.ts`, the plugins' declarations, and all they import: every relative import a file that is there, with its extension; JSON imported `with { type: 'json' }`; no JSX; every package declared (a devDependency, in what production runs, is said); what the server loads by name exported (`space`, `actions`, the runtime's default) |
-| `plugins` | each folder of `src/plugins/` the server can build: its entry builds and exports its component, its packages declared; its `declaration.ts` loads and its `type` is the folder's (`StatCard` → `statCard`) |
+| `plugins` | each folder of `src/plugins/` the server can build: its entry builds and exports its component, its packages declared; its `declaration.ts` loads and its `type` is the folder's (`StatCard` → `statCard`); its `Settings.tsx`, the panel the builder edits it with, written and passed as `pluginSettings` — even with nothing to set |
 | `data` | every JSON file of `src/data/` and `public/data/` parses — what the server answers with and `space push` sends |
 | `functions` | `src/functions/` built by the project's own `@plitzi/sdk-server` (`buildFunctions`), as every runner builds them |
 | `records` | `.plitzi/space.json`, `scaffold.json` and `functions.json` readable, and of the same space |
@@ -598,14 +605,15 @@ said before anything is sent, with what to do: a provider reading a file `src/da
 
 Adds elements of your own to the project you are in — one, several at once (`plugin add seat-picker legend`), or one at
 a time as the need comes. Each is a folder, written the way Plitzi's own elements are (`@plitzi/sdk-elements`): the
-component, its `declaration.ts` (its `type`, the events it fires, the actions it answers to, and the element the builder
-adds), its `Settings.tsx` panel for the builder, and the `index.ts` that puts them together — what the folder is built
+component, its `declaration.ts` (`definePlugin` from `@plitzi/sdk-authoring/plugin`: its `type`, the events it fires,
+the actions it answers to, its defaults — the element the builder adds is derived from them), its `Settings.tsx` panel for the builder, and the `index.ts` that puts them together — what the folder is built
 from: `index.ts`, or `index.tsx` for one that writes its JSX there, never both. It asks what to call each, what the
 builder shows, and what it is for, and checks every folder is free before writing any.
 
 - **In a project `plitzi create` wrote**, it goes in `src/plugins`, where the project already looks: nothing to
-  register, and a running `start:dev` picks it up without a restart. Host it with `custom({ renderType: 'seatPicker' })` in `src/space/`
-  — or, when the space lives in Plitzi, with a Custom element in the builder.
+  register, and a running `start:dev` picks it up without a restart. Place it in `src/space/` from its declaration —
+  `defineElement(declaration)`, then `seatPicker({ id: 'seats' })` — or, when the space lives in
+  Plitzi, pack and upload it and add it in the builder.
 - **In a plugin package**, it goes in `src/`, and is added to `src/elements.ts` and `src/declarations.ts`, from which
   the package publishes it.
 - **In any other project**, it asks which folder holds the project's components (`--dir` answers it) and prints how
@@ -622,7 +630,8 @@ plitzi plugin add ticker --prop interval:number=5000 --prop paused:boolean --tri
 `--prop name:type=default` (string, number or boolean) is an attribute: in the props, the declaration's defaults and
 `bindingsAllowed`, and a control in `Settings.tsx`; `--prop rows:list` and `--prop meta:json` are data a binding fills
 (`unknown[]`, `Record<string, unknown>`, empty until it does). `--trigger onTick:count,at` is an event and what a flow
-started by it reads, fired with the `useTickerEvents()` hook it gets — never on the builder's canvas. `--callback reset`
+started by it reads, fired with `usePluginTrigger(declaration)` — `fire('onTick', { count, at })`, typed by the
+declaration, and never on the builder's canvas. `--callback reset`
 is an action a flow can call. `--headless` is an element with nothing to see: hidden on a page, a badge in the builder,
 and `drawsNothing` in its declaration, so a page check does not look for it. The files are written as the project's
 Prettier writes them.
@@ -690,7 +699,6 @@ plitzi source pack src/runtime/index.ts --kind runtime --name runtime -o runtime
 
 What `plugin upload` and `runtime push` keep, written to a file to look at: the closure of the entries named, gzipped.
 
-
 ## `login`, `space use` and `plugin upload`
 
 ```bash
@@ -765,13 +773,14 @@ plitzi functions pull                                              # the space's
 plitzi functions push                                              # src/functions/ saved as the space's draft, built and checked
 plitzi functions try seismic.feed --params '{"minMagnitude":"4"}'  # one task of the saved draft, in the sandbox
 plitzi functions dev seismic.feed --params '{}' --watch            # on this machine, as the platform runs it
+plitzi functions add ical.js                                       # an installed package bundled into src/functions/vendor/
 ```
 
 A space's own server code — tasks its actions run as steps, routes under `/fn/` — and `src/functions/` is a working copy
 of it: `.plitzi/functions.json` keeps what was pulled, so `functions pull` refuses to overwrite what is not pushed (`--force`
 throws it away) and `functions push` refuses when the space moved on since. A problem comes back as
 `src/functions/<file>:<line> <message>`. `dev` runs with the project's own `@plitzi/sdk-server` (`isolated-vm` and
-`core-js` beside it); credentials come from `PLITZI_FUNCTIONS_CREDENTIALS`. See `docs/en/functions.md`.
+`core-js` beside it); credentials come from `PLITZI_CREDENTIALS` (`.env`), as they do for the project's server. See `docs/en/functions.md`.
 
 ## Credentials