@plitzi/sdk-interactions 0.37.8 → 0.37.10

package/CHANGELOG.md

@@ -1,5 +1,838 @@
 # @plitzi/sdk-interactions
 
+## 0.37.10
+
+### Patch Changes
+
+- 8d1cc02: ## The builder's sidebar, one entry per subject
+
+  From 21 entries to 9. **Elements** ends with the space's **Components**, one search for both — each is dragged
+  onto the canvas the same way. **Server** gathers Actions, Functions, Connectors, Credentials and Runtime behind tabs, with
+  the warning that a space has no server-rendered deployment said once above them. **Variables** holds Feature Flags,
+  **Assets** holds files and fonts, **Settings** holds Visitors, the Pages panel opens the **Sitemap** in place of the
+  canvas, and **History** moved to the header beside undo and redo. Each grouped entry remembers the tab left open.
+
+  The builder is drawn with the website's design system: Geist and Geist Mono, the `#5b3df5` violet, cool neutrals and
+  8 / 10 / 14px radii, from the tokens `@plitzi/plitzi-ui/theme.css` now ships. The published SDK stylesheet does not
+  take them, so a space's own elements look as they did.
+
+  The Sitemap is drawn by `TreeCanvas`, a new `@plitzi/plitzi-ui` component: the site laid out as a tree on its own, panned
+  and zoomed like a design canvas, a page moved by dropping it onto a folder or onto the top level. `@xyflow/react` — and
+  zustand and d3 with it — is no longer a dependency of the builder.
+  From the map a page is found (search lights it and the folders leading to it), opened in the canvas (double click,
+  Enter or its card), and created inside a folder; folders fold away what they hold, remembered between visits; arrows walk
+  it. Each card says who may open the page, its layout, the flag it exists under, where it sends somebody it refuses, and
+  marks its dynamic segments and the page being edited. Fixed on the way: a page with no access level was labelled
+  "Public", which in Plitzi means guests only — it is open to everyone, and now says so.
+
+  ## Feature flags
+  - **What they are:** `schema.flags`, a space's switches by name — a default and rules over the environment, the host,
+    the URL and the visitor. Read with the document, stored apart from its snapshots: one set per environment, turned
+    without a new revision; a snapshot keeps a copy, read only when the environment's flags (and their Redis copy)
+    cannot be. See `docs/en/feature-flags.md`.
+  - **Caches follow them:** `SSRSpaceDeployment.flagsVersion` (the flags' hash) keys the HTML, RSC and `offlineData`
+    caches of `@plitzi/sdk-server`; `createCloudAdapters` probes `flagsHash` and fetches `SpaceFlags` only when it moved
+    — a pinned revision included — and keeps the last flags in its shared cache for a cold start with Plitzi down.
+  - **Who decides:** the space, then the server rendering it (`createServer({ flags })`), then the SDK embedding it (the
+    `flags` prop), then a tester (the dev tools' Flags tab, only where debugging is authorized) — each only for flags the
+    space declares.
+  - **Gating:** `definition.flag: { name, is }` renders an element only while the flag agrees — not a visibility: gated
+    off, none of it is rendered, on the server or in the browser, and RSC resolves no data for it. A gated page is not
+    found. Its declaration still ships with the space's document: a flag switches a feature off, it does not hide it.
+  - **Reading:** the `flags` global source (`{{ flags.x }}`), `useFlag(name)` for plugins, and `flags` in a server
+    action's scope (the `getFlags` action lookup).
+  - **Builder:** Feature Flags beside the variables (declare, rule, force in the canvas, publish), the gate in an element's tools, a
+    marker in the tree. Its own flags come from the platform (`PlatformFlags`) instead of a constant.
+  - **Authoring and MCP:** `SpaceSpec.flags`, `flag: 'name' | '!name'` on elements and pages, linter codes
+    `flag-undeclared`, `flag-unknown`, `flag-unused`, `flag-rule-empty`; MCP `upsertFlag`, `deleteFlag`, `flag` on
+    element and page ops, `plitzi://flags/{env}`.
+  - **Global sources** are one list now (`@plitzi/sdk-shared/dataSource/globalSources`), read by the runtime and the
+    authoring validator alike.
+
+  ## Element templates are Snippets
+
+  What the builder saves from a subtree and drops into a page was called a template, the word a space's own starting
+  point already goes by. It is a **snippet** now, everywhere, with no alias for the old names:
+
+  - **Builder:** "Save as snippet" on an element, **Snippets** in the resources list. A snippet has an icon of its own
+    (an object group) beside the component's cube, in the canvas overlay and the context menu alike, and each says on
+    hover what sets it apart: a component stays linked, a snippet is a copy.
+  - **CDN:** a snippet is uploaded to `snippets/` in the space's folder, with the resource type `snippet`. A file already
+    in `templates/` is no longer listed as one: upload it again.
+  - **Authoring:** `authorSnippet`, `validateSnippet`, `SnippetSpec` and `AuthoredSnippet`, which returns `{ snippet,
+warnings }`. The validator codes are `SNIPPET_*`.
+  - **Shared and schema:** the `Snippet` type (`@plitzi/sdk-shared/types/SnippetTypes`), `SpaceAddSnippet` and
+    `SPACE_ADD_SNIPPET`, `SCHEMA_ADD_SNIPPET` and `STYLE_ADD_SNIPPET`, `schemaAddSnippet` / `styleAddSnippet` on the
+    event bridge, and `FlatMap.flatAsSnippet`.
+  - **Plugins:** the builder config key `canTemplate` is `canSnippet`.
+  - **One document, whoever writes it:** a snippet's `schema` is only what travels — `flat` and `variables` — whether
+    `authorSnippet` wrote it or the builder saved it. Until now an authored one carried a whole space (`pages: []`, its
+    settings), which the builder's preview laid over the space being edited, and one the builder saved failed
+    `validateSnippet` (`INVALID_PAGES`).
+  - **The same snippet, dropped twice:** the second drop renamed its elements in the editor while the server was sent
+    the names it arrived with, refused them as taken, and the drop was undone. The names are now fitted where the
+    snippet is dropped (`fitSnippet`, `@plitzi/sdk-schema/helpers/fitSnippet`) and carried by the insert to the server
+    and every collaborator; `SCHEMA_ADD_SNIPPET` inserts under them and refuses a name taken since, as the server does.
+    `SpaceAddSnippet` checks what it is sent against the `SPACE_ADD_SNIPPET` event before applying it.
+  - **A snippet never restyles the space it lands in:** a class it brings under a name the space uses for something
+    else is renamed (`card` → `card-2`) on its rule, its elements and the rules naming it as an ancestor, and its CSS
+    recompiled; one that says the same is shared. The space keeps its rules for element types and its tokens, and a
+    snippet's tokens the space lacks are now added — the editor merged its rules only, and the server neither
+    (`mergeSnippetStyle`, `@plitzi/sdk-shared/style/snippetStyle`; `SnippetStyle`; `STYLE_ADD_SNIPPET` carries `style`).
+  - **A snippet is known by what it holds:** `isSnippet` (`@plitzi/sdk-shared/schema/snippet`). A JSON uploaded in
+    **Assets** that is a snippet goes among the snippets — before, an authored one landed as a plain file — and an upload
+    declared a snippet that is not one is refused. A file among the snippets the builder cannot read is shown as such,
+    with a way to remove it, instead of breaking the panel.
+  - **Saving says how it went:** "Save as snippet" announces the snippet once the upload answered, and says why when it
+    did not — it used to report it created before knowing, and from the context menu said nothing at all.
+
+  Space templates — what a new space starts as — keep their name.
+
+  ## A link to a section of a page
+  - **`anchor`** on any element is its `id` in the DOM — the element's own id only ever reached it as `data-id` — so
+    `/page#plans` has somewhere to land. Written by `authorSpace` (`anchor: 'plans'`), the builder (the element's
+    **Anchor** field), the MCP (`upsertElement` / `patchElement`) and read back by `specFromSpace`.
+  - **`link` takes `hash`**: `link({ href: 'home', hash: 'plans' })` goes to `/#plans`; a flow's `navigate('home#plans')`
+    resolves the page and keeps the fragment.
+  - **The router scrolls to the fragment** after every client-side navigation and on arrival, and waits up to 3 s for a
+    section that renders once its data arrives — a visitor who scrolls first is left where they are.
+  - **Refused while authoring:** an anchor that is not lowercase letters, digits and `-` (`anchor-invalid`), one on an
+    element with no tag (`anchor-no-tag`), inside a list row or a component (`anchor-repeated`), twice on one page with
+    its layouts (`anchor-duplicate`), and a link to a section the page does not have (`anchor-missing`).
+
+  ## Every problem in one run
+  - **`authorSpace` reports everything it cannot write at once**, as a `SpaceRefusedError` whose `refusals` list each
+    one — instead of stopping at the first. An element it cannot write is left out and its siblings carry on; a class
+    worn with `css`, `states` or a `selector` of its own is reported and written with the class, so the linter still
+    reads the rest of the space and its findings join the same report.
+  - **Each problem says where:** the line of your own code that called the factory (`src/site/home.ts:417`) and the
+    nearest named element with the steps from it (`"store-footer" › container[1]`) — not a path of indices.
+  - **The project's `npm run author`** prints one line on success, the numbered problems (no stack from inside the
+    package) on failure, and one JSON object with `--json`.
+
+  ## A class, plus one thing
+
+  `class: [cover, { opacity: '0.25' }]` puts rules of the element's own on top of the classes it wears — the commonest
+  shape there is, which until now took a class of its own every time. The rules become the class `<id>--own`, declared
+  after every shared class so it wins over them, editable in the builder like any class; they take states and
+  breakpoints as `styles()` does, need the element's `id`, and read back from a document as the same inline object.
+
+  ## Every few seconds, with no plugin
+
+  `onInterval(ms)` is a trigger every element has: a flow that repeats every `ms` milliseconds — an autoplay, a clock, a
+  refresh — while the element is mounted and the tab is in view, and never in the builder outside preview. Each flow
+  names its own interval and counts its own ticks (`{{ <step>.count }}`); one below 250 ms is refused (`trigger-interval`).
+  It is in the builder's flow editor beside `onKey`, and `@plitzi/sdk-shared/helpers/interval` holds the rule all of them
+  read.
+
+  ## Data in `public/`, in the page from the first byte
+  - **`plitzi create --mode server`** writes `public/data/` and passes `publicDir` to `createServer`: `public/data/*.json`
+    is served with no change to `src/main.ts`.
+  - **A server provider reads a file of the server's own:** an `apiContainer` with `runtime: 'server'` and a `query`
+    that is a plain path in `publicDir` (`/data/home.json`) is resolved by the page server from disk — no connector or
+    action configured — so the page arrives with the section in it rather than fetching it after load. A URL, a path
+    outside `publicDir` or a `query` with `{{tokens}}` is left to the browser as before.
+
+  ## A project's server, findable
+  - **`npm start` starts beside whatever holds 8080** while developing: the next free port (`freePort`, from
+    `@plitzi/sdk-server`), printed and written to `.plitzi/dev-server.json`. With `PORT` set, that port or an error.
+  - **`/health` answers with the space's name**, and `npm run shot` checks it before taking a picture — another server
+    on the port is reported, instead of photographed. `playwright.config.ts` and `shot` read the port from `PORT`, else
+    from `.plitzi/dev-server.json`.
+
+  ## Every document type, from the package you author with
+
+  `@plitzi/sdk-authoring` exports the types of what it writes — `Schema`, `Style`, `SpaceFont`, `Element` and the rest
+  of the documents, plus `SchemaValidationError`, `SchemaValidationOptions` and `SchemaValidationResult` — so a project
+  types its own helpers without reaching into `@plitzi/sdk-shared`.
+
+  ## Breakpoint warnings that read `display: none`
+
+  `tablet-rule-skips-mobile` no longer warns about a tablet rule the phone hides anyway: an element with
+  `display: none` under `mobile` never shows the rule it skips. When it does warn, it points to `compact`, which reaches
+  both.
+
+  ## An inline container
+
+  `container({ subType: 'span' })` renders a `<span>`: a dot before a title, a word dressed apart, a badge in a line of
+  text — inline by default, and in the builder's container settings as "Span (inline)". A span holding a heading, a
+  paragraph, a list, a form or prose is warned about (`span-holds-block`).
+
+  ## Every problem has a code, and a page that cannot miss one
+  - **Every refusal and warning carries a code** — `[class-and-css]`, `[id-taken]`, `[tablet-rule-skips-mobile]` — in
+    the message and in `SpaceRefusedError.refusals[].code`. `AUTHORING_CODES` (exported) is the one table they are raised
+    from: whether each is refused or warned, what was wrong and what to write instead. A check raised with a code that is
+    not in it does not compile.
+  - **The skill's `authoring-errors.md` is generated from that table**, as is the website's Authoring errors page
+    (`authoringCodesTable`), so neither can miss a code; a test fails when the page and the table disagree.
+  - `AuthoringError` is what a factory or `authorSpace` throws for one problem on its own, with its `code` and `reason`.
+
+  ## The skills, packaged for a project
+  - **A cheatsheet to start from** (`CHEATSHEET.md`): the factories, fields, steps and the problems met most, on one
+    page. `SKILL.md` starts there, says what to read for each kind of task, and what never to read whole.
+  - **Recipes by intent, as files** (`recipes/*.ts`): show data from a file, filter a list, a detail page, link to a
+    section, something every few seconds (a carousel), a marquee, a link built from a row, forms and modals, a feature
+    flag, a plugin, controls usable without sight, styling, and an embed or an SVG. CI authors each one: a recipe that
+    stops authoring fails the build.
+  - **Every link in a skill resolves inside a project**, and none names a file only the workspace has; a test walks them
+    as `plitzi create` copies them. Realtime channels have a reference of their own.
+  - **Each skill file has a budget** — about 4k tokens for a `SKILL.md`, 3k for a reference — held by a test.
+  - **When to use the MCP and when the CLI**, in both skills: the MCP for a space that lives on Plitzi, the CLI for one
+    that lives in code; a sign-in nobody can give never blocks the second.
+  - New guidance: animations (keyframes, entering with `visible`, pausing on hover, staggering), a list's `index` as
+    text, rows kept by position, a provider around a layout's slot, checking motion in a test.
+
+  ## A project an agent finds its way around
+  - **`AGENTS.md` says the port, where data goes, how to look at a page, and what not to read**: the generated
+    `space/offline-data.json`, `.sdk-plugins/`, a large `public/data/*.json` and the bundles in `node_modules`.
+  - **`plitzi data describe <file>`** prints a JSON file's shape — every field, its type, how many rows have it — and one
+    row of its longest list; `--json` for a tool.
+  - **Quiet by default:** the server prints only what goes wrong (`npm start -- --verbose` for every request), and
+    `typecheck` one line per error.
+  - **The welcome space follows the skill's rules:** a box one class owns whole is a shorthand; a test holds it to that.
+  - `.claude` is left out of a project's lint and formatting.
+
+  ## Problems over MCP come with their code and their fix
+
+  An agent editing a space over MCP has no skill page to look a code up in: each problem a batch meets now leads with its
+  `[code]` and its hint says what to write instead, from the same `AUTHORING_CODES` row `authorSpace` raises it from
+  (`authoringCodeEntry(code)` looks one up).
+
+  ## Scrolling, as steps
+  - **`scrollBy`, `scrollTo` and `scrollIntoView`** are callbacks every element answers: `scrollBy('cards', { x: '80%' })`
+    moves a box by most of what it shows, `scrollTo('cards', { x: 'end' })` to an end or a place, `scrollIntoView` brings
+    an element into view. In the builder's flow editor, in authoring and over MCP.
+  - **`onScroll`** fires as an element's box moves — at most once a frame, and once on mount — with
+    `{ x, y, atStart, atEnd }`, so an arrow can hide at the end already reached (recipe: `recipes/scroll-a-row.ts`).
+
+  ## A list names its rows by the field you choose
+
+  `list({ itemKey: 'slug' })` keys each row by that field of its item, so a row's state follows its item when the list is
+  filtered or reordered, and a row whose item changes mounts again — a one-row list showing the current slide replays its
+  entrance. Left out, rows follow the items' `id` (when every item has its own), else their position. In the builder it
+  is the list's "Row key"; `list-item-key-missing` warns when fixed items lack it or share one.
+
+  ## A skeleton while a provider loads
+
+  `apiContainer({ loadingSlot: 'catalog-skeleton' })` names one of its children to show in place of the others until the
+  first answer arrives — the shape of what is coming — and to drop after it. In the builder every child shows, so the
+  slot is edited beside what it stands for; `loading-slot-unknown` refuses a slot no child answers to.
+
+  ## `plitzi create --template blank`
+
+  A space written in the project can start empty: tokens for both themes, a layout whose `site-main` the pages render in,
+  one page, `public/data/` and no example plugin — for a project that is about to be a specific site, where the welcome
+  tour is the first thing that would be deleted. `emptySpaceSpec` / `emptySpaceSource` in `@plitzi/sdk-authoring`.
+
+  ## `plitzi add plugin` writes the shape it is told
+
+  `--prop interval:number=5000`, `--trigger onTick:count`, `--callback reset` and `--headless` write an element in its
+  final shape — typed props with defaults, bindable and with a control each in its panel; a `use<Name>Events()` hook that
+  fires its events with typed payloads; a function per action; and, headless, hidden on a page and a badge in the builder
+  — instead of the counter example, which is what it writes without them. Flags that cannot make an element (a type that
+  is not one, an event every element already fires, a name used twice) are refused with how to write them, and the files
+  are written as the project's Prettier writes them.
+
+  ## Skills that say their version, and `plitzi skills update`
+
+  The skills `plitzi create` copies into a project carry the version of the package they came from (`version:` in
+  `SKILL.md`). `npm run author` says when the authoring skill is older than the `@plitzi/sdk-authoring` installed, and
+  `plitzi skills update` replaces each Plitzi skill with the installed package's — whole, leaving any other skill alone.
+  The CLI skill's references for `create --from` / `pull` and for a space's functions are files of their own now, read
+  when a task names them.
+
+  ## `plitzi explain`
+
+  What a name means when authoring, in a few lines: an element (its attributes and their values, what it fires and
+  answers, its slots), a step (its params and the function that writes it), a trigger (what it hands its flow, what fires
+  it), a problem's code (what was wrong, what to write instead) or a transformer. `--list steps` names every one of a
+  kind, `--json` answers in one object, and over MCP it is the resource `plitzi://explain/{name}`. Read from the same
+  catalogues the checks use (`explain`, `explainList`, `explanationText` in `@plitzi/sdk-authoring`).
+
+  ## `plitzi check` and `plitzi shot`: a page in numbers before pictures
+  - **`plitzi check / --width 1440,390`** says whether a page of the running project is whole, in text: every element the
+    space owes it on screen (or why not), no broken image, no sideways scroll, no text in the colour behind it, no console
+    error, no refused request — per width, `--json` for a tool. A space in code is checked against what each page owes;
+    any other, against what every page does.
+  - **`plitzi shot`** takes the picture, and `--compare <url>` puts the same page of another site beside it — the
+    differences in red, and the share that differs in each landmark (`section#plans 14%`); `--frames 4 --every 500` says
+    what moves; `--wait-for` and `--reduced-motion` set it up. The comparison runs in the browser
+    (`comparePictures`, `pageRegions` in `@plitzi/sdk-authoring`), so nothing is installed for it.
+  - Both use the project's own Playwright and refuse a port that answers as another project. A project `create` writes
+    installs `@plitzi/cli` and runs them as `npm run check` / `npm run shot`, which replaces its `scripts/shot.ts`.
+
+  ## The builder's problems panel says the fix
+
+  Each problem in the builder's panel shows what to write instead, from the same `AUTHORING_CODES` row `authorSpace` and
+  the MCP use — `SpaceIssue.fix` over GraphQL, its code set apart.
+
+  ## Scroll snap, and anchors under a fixed header
+
+  `scroll-snap-type`, `scroll-snap-align` and `scroll-snap-stop` — a row of cards that comes to rest on a card — and
+  `scroll-padding-top` / `scroll-margin-top` — an anchor that lands below a fixed header rather than under it — are part
+  of the style vocabulary, with a "Scroll snap" section in the style editor.
+
+  ## CSS as a React style object, and a value per breakpoint in place
+  - **camelCase keys and numbers:** `{ paddingTop: 8, fontWeight: 800, WebkitLineClamp: 2 }` is `padding-top: 8px`,
+    `font-weight: 800`, `-webkit-line-clamp: 2` — a bare number on a length is pixels. The document keeps kebab-case; one
+    property written under both spellings is refused (`css-property-twice`).
+  - **One property per breakpoint:** `{ fontSize: { desktop: '24px', compact: '18px' }, fontWeight: 700 }` changes the
+    size on tablet and phone without splitting the rule set; it mixes with the per-breakpoint form.
+
+  ## A link's mode follows from its href
+
+  `link({ href: '/games/nebula' })` is internal, `link({ href: 'https://…' })` (or `mailto:`, `tel:`) external, and
+  `link({ href: 'about' })` a page — `mode` is written only to say otherwise. A link that opens another tab gets
+  `rel="noopener noreferrer"`.
+
+  ## `from` and `as`: an element shows its data in a line
+  - **`from`** binds the attribute a type shows its data in — a text's or heading's `content`, an image's `src`, a link's
+    `href`, a list's `items` — and leaves it empty until the data answers: `heading({ from: 'site.data.hero.title' })`.
+    It writes the same binding `bind` does; `bind` keeps the other attributes.
+  - **`as`** shows it through a template (`as: '{{ source }} left'`) or a format the space names once:
+    `formats: { price: "{{ source|currency('USD', 'en', { trimZeros: true }) }}" }`, then `as: 'price'` anywhere.
+  - **New template filters:** `currency('USD', locale?, { trimZeros })` and `percent(decimals?)`, in `en` unless told,
+    so a server and a browser in different locales write the same text.
+  - Refused: `from` on a type with no main attribute, the main attribute bound twice, a format nobody declared, `as`
+    without `from`.
+
+  ## A list in one line: `items` and `row`
+
+  `list({ id: 'grid', items: 'catalog.data.products', row: 'product-card' })` is a controlled list fed by that source,
+  placing the component once per item with the row bound to its `item` prop (or its only prop). `row` can also be a
+  function handed the row's names — `row: r => text({ from: `${r.item}.title` })`, `r.inTemplate.item` for a template.
+  `items` (an array, or a source's name) and `from` make a list controlled without saying so. Refused: a row and
+  children at once, a function row on a list with no `id`, a row naming a component that cannot take it.
+
+  ## `activeWhen`, and a list's index is a number
+  - **`activeWhen(dot, '{{ list_dots.index == state.slide }}')`** wears a class's `active` variant while a condition
+    holds (`idle` otherwise) — the general form of `activeOn`, without a hand-written ternary.
+  - **`list_<id>.index` is a number** from 0, so a template counts with it (`index + 1`). `==` compares text and numbers
+    alike, so templates that compared it as text read the same.
+
+  ## `cycleState` and `stepState`
+
+  `cycleState({ key: 'slide', length: 4 })` moves a number in state round a cycle — after the last the first, `by: -1`
+  before the first the last — and `stepState({ key: 'shown', by: 40, max: 'apiContainer_site.data.total' })` adds and
+  stops at its bounds. Both are the `setState` they stand for, with the arithmetic written once; a length or a bound is a
+  number or a template expression for one.
+
+  ## `scope()` for what a helper builds
+
+  `scope('promos', ref => container({ id: 'panel', … }))` prefixes every `id` given inside it (`promos-panel`), so a
+  helper that builds the same block twice writes two sets of names instead of being refused `id-taken`. `ref('slides')` is
+  the full name, for a binding, a step's target or a template; scopes nest. `id-taken` now points at it.
+
+  ## Typed tokens, and `unknown-variable`
+  - **`tokens(variables)`** turns the space's variables into the values a rule writes — `t.surface === 'var(--surface)'`
+    — so a token that does not exist is a type error where it is written.
+  - **`unknown-variable`** warns of a bare `var(--x)` nothing declares (a space variable, a selector's variable, a custom
+    property a rule sets, or `customCss`): the browser drops the property and the page shows what it inherits. A
+    `var(--x, fallback)` is taken as meant.
+
+  ## Typed sources: `source()` and `twig`
+
+  `const site = source('site', home)` names a provider's source from a sample of its answer — the JSON file it reads,
+  imported — so every path is completed by the editor and checked: `site.data.hero.titel` is a type error, and refused
+  `source-field-unknown` where the types were not looking. A path is the full source name, so it goes in `from`, `items`,
+  `bind` and `visible` as it is, and into a template through `` twig`{{ ${site.data.total} + 1 }}` ``. A list fed by a
+  path hands its `row` the item typed (`row: g => text({ from: g.item.title })`). Nothing of the sample is written into
+  the space; inside a `scope()` the id is the scoped one.
+
+  ## `tw()`: Tailwind classes as Plitzi styles
+
+  `styles('pill', tw('inline-flex items-center gap-2 px-5 rounded-full bg-slate-950/90 hover:scale-105 md:text-sm'))`
+  writes the rules the classes mean when the space is authored — Tailwind v4's scales and palette, arbitrary values,
+  `[property:value]`. Its breakpoints become Plitzi's ranges (`md:` tablet and desktop, `lg:` desktop, `max-md:`,
+  `max-lg:`), its states the class's states, `group-hover/<class>:` an ancestor's. Composed properties (transform,
+  filter, gradient, ring and shadow) are put together once. `createTw({ colors: tokens(variables) })` names the space's
+  tokens. What has no exact equivalent (`sm:`, `dark:`, `space-x-*`, `animate-*`) is refused with what to write instead.
+
+  ## `create --template catalog`, and a file per part
+
+  `npx @plitzi/cli create shop --template catalog` writes a complete small site to read and change: a layout with a menu,
+  a product card component, `public/data/products.json` read as a typed source, a catalog filtered by category and a page
+  per product — each part a short file of its own under `src/site/`, assembled by `src/space.ts`. The template is
+  authored by sdk-authoring's tests, and a generated project authors, typechecks and lints clean. The skills point to it,
+  and `AGENTS.md` asks for a file per part.
+
+  ## `embed` and `svg` elements
+  - **`embed({ src, title })`** puts another page in a frame — a map, a video player — lazily loaded, with `allow`,
+    `sandbox` and `referrerPolicy` when it needs them. Only a web address or a path of the site is loaded, and in the
+    builder the frame does not swallow the click that selects it. `embed-without-title` warns of one a screen reader
+    cannot describe.
+  - **`svg('<svg …>…</svg>', { label })`** draws SVG markup inside a box its class colours (`currentColor`): checked to be
+    one `<svg>` (`svg-not-svg` otherwise) and sanitised as rich text is, plus what only SVG can carry (`foreignObject`,
+    animations writing a `javascript:` link). Decorative unless it has a `label`, then `role="img"`. `{{ }}` tokens
+    resolve in it like in any attribute.
+
+  ## Pictures resized by the page server
+
+  `createServer({ images: { domains: ['images.example.com'] } })` resizes other sites' pictures at `/_plitzi/img`: an
+  `image` whose `src` is one of them offers a `srcset` from 320 to 1920 px, in AVIF or WebP when the browser takes them.
+  Each original is downloaded once and each size made once, both kept on disk; a week on they keep answering while the
+  original is revalidated with its `ETag` / `Last-Modified`, so an unchanged picture is never resized again. Only the listed hosts (`*.example.com` for subdomains) are fetched, every redirect is
+  held to the list and to the outbound guard, and SVG is refused. `sharp` is an optional peer: without it pictures are
+  passed through and kept. `image` also takes `sizes`, and `width`/`height` so the browser keeps the picture's space.
+
+  ## `plitzi check` says what the page holds
+
+  Every `plitzi check` now lists the flows that failed while the page loaded, each with the step that failed and why.
+  `--state` adds the page's state and every source by its full name (with the shape of what it holds), and `--element
+<id>` one element: what it reads, its own state, how many copies, whether it is on screen and its box. Read from the
+  page's dev tools, which keep the flows a page runs before they mount; in a test, `readDevTools(page)` from
+  `@plitzi/sdk-authoring` answers the same.
+
+  ## `carousel`
+
+  A structure element for slides that change, a marquee and a row that swipes: `carousel({ id: 'hero', items, row,
+autoplay: 5000, children: [arrows, dots] })`. Its `row` is written into a `carouselTrack`, and its other children are
+  its controls, reading `carousel_<id>.index`, `.count`, `.item` and `.items`. `mode: 'slide'` shows one at a time
+  (`transition` `slide`, `fade` or `none`, back entering from the left); `'marquee'` scrolls the items past at `speed`
+  px/s with no seam; `'scroll'` is a snapping row a visitor swipes. Steps `carouselNext`, `carouselPrevious`,
+  `carouselGoTo`, `carouselPlay` and `carouselPause`; trigger `onChange`. Autoplay holds still under the pointer, with
+  keyboard focus inside, in a hidden tab and for reduced motion, and never in the builder. Slides are announced as "2
+  of 5" in a region named by `label`.
+
+  ## `plitzi fix`: the fixes authoring knows, written in your source
+
+  `plitzi fix` shows what authoring would fix — a key the element never reads, `'true'` where a boolean goes, a URL in
+  page mode, a `state.` prefix on a state key, a binding nothing reads — as a diff of the project's own source: each
+  edit made in the call that wrote the element (found by the line and column it remembers), and only where the value is
+  a literal. `--write` writes them, formatted as the project formats, authors the space again in a fresh process and
+  keeps them only if every fix is gone and no problem was added; one that would add a problem is put back and said with
+  the reason. `npm run author` says how many of its problems have one fix. From `@plitzi/sdk-authoring`, `planFixes`
+  returns the plan: every problem, and each fix with its place and edit.
+
+  `fixSpace` now reads an element with the linter's own context, so a component instance's props and slot are no longer
+  taken for attributes nobody reads — it used to remove the binding of a list row to its component's `item`.
+
+  `plitzi import <url>` measures a page you own in the project's Playwright and writes it into the project as a place to
+  start from: `tokens.ts` (the page's custom properties by name, then its dominant colours, each with the value the same
+  place shows in the dark scheme; repeated corners and shadows; Google fonts), `outline.ts` (`container()`s for its
+  landmarks and blocks, with their layout per breakpoint as what each narrower width changes), its repeated lists as
+  `data/*.json`, `assets.json`, a screenshot per width and `IMPORT.md`. Never its words. It imports only a site that is
+  the person's: a verified domain of one of their spaces covering the host (the `_plitzi` TXT record, asked of the
+  platform's new `GET /account/domains/covering`), or one served from this machine; `--out`, `--widths`, `--force`,
+  `--json`, `--api`. From `@plitzi/sdk-authoring`: `importProbe` (runs
+  in the page), `importedFiles` and `darkScheme`.
+
+  A compound element without the part it shows its content through — a `carousel` with no `carouselTrack`, a
+  `tabContainer` missing its header or body, a `dropdown` with no `dropdownPopup` — is now refused (`part-missing`):
+  it rendered nothing of what it held, without a word. The parts are read off the declarations (`elementPartTypes`, the
+  `partTypes` catalog), so the builder's issues and publish gate, the MCP's validate and `authorSpace` all hold to it.
+  The MCP guide says how a compound element is written.
+
+  The dev tools catch up. **Elements** shows what is on screen as the trees it comes from — the layouts around the page,
+  outermost first, the page, and every component an instance places — at their depth, searched together (a match is kept
+  with what holds it), each element outlined on the page while it is pointed at. Selected, its **Runtime** tab is the
+  report `window.__plitzi.element()` and `plitzi check --element` give: own state, what it reads, the component it places
+  or sits in, copies and box, read again every second. That report now finds an element inside a component, which it
+  missed. **Logs** has a `realtime` category: the page's connection opening and dropping, each message in (←) and out
+  (→), and every topic the server refused, with why. One hook outlines an element for every tab.
+
+  A `webHook` step that gets no answer at all — offline, refused, blocked by CORS — now fails, with the request and the
+  reason, so the flow stops and its `onFailure` runs. It used to succeed with an empty response, and the flow carried on
+  as if the request had been made. Any answer is still the step's result, an error status included: a flow reads
+  `{{ <step>.response.status }}` to tell a 401 from a 200. `response.data` is typed as what the body parsed to.
+
+  The server checks what a deployment's config hands it in one place (`configSeam`): each action document and connector
+  manifest a lookup returns goes through the validator the builder saves with, as it is read — an action that is not a
+  document is refused by name, and one in a list is left out and said rather than failing the space's schedule — and the
+  database drivers and functions config are checked once, as the server starts. Four unchecked casts are gone.
+
+  `@plitzi/sdk-shared/helpers/eventTarget` reads an event's target as a node (`nodeOf`, `isNodeTarget`) or an element
+  (`elementOf`, `isElementTarget`) by its own type rather than `instanceof`, which is false for a target in the builder's
+  canvas iframe. The builder, the style inspector and the dev tools use it, and type their change and key handlers by
+  the input they listen on; the casts of `event.target` are gone.
+
+  The builder's flag form checks each rule's `when` is a group of conditions before it saves, rather than passing
+  whatever the field held.
+
+  The CLI's commands now work the same way: the answer on stdout and errors and sign-in prompts on stderr, so `--json`
+  is only the answer (`import --json` printed the sign-in prompt into it); exit 1 whenever a command did not do what it
+  was asked (`fix --json` with a problem exited 0); and a flag's value checked where the flag is declared, refused with
+  what it takes — `--width abc` or `--scheme darkk` used to check at no width or in light, saying nothing. One flag means
+  one thing everywhere: `import --widths` is `--width`, like `check`, and `-o`, `-f` and `-e` are the short forms on
+  every command that writes, overwrites or names an environment. `import` no longer repeats a sign-in error. `whoami`
+  and `runtime status` take `--json` too; `functions` and `runtime push` refuse outside a project, as every other command
+  that works on one does, instead of writing `functions/` into whatever folder they were run from; and every command
+  says a finished action the same way, in green.
+
+  The SDK's production build keeps `console.warn` and `console.error`, and drops only `log`, `info` and `debug`. It used
+  to drop them all: an override of a flag the space does not declare, or a render that failed, said nothing on a
+  published site — exactly where nobody can attach a debugger.
+
+  A link to the page being shown says so: it carries `aria-current="page"` — read from the address the page was rendered
+  at, so the first paint has it — and a class dresses it with the new `current` style state (`states: { current: … }`,
+  a tab in the style editor, folded from `[aria-current="page"]` rules when a space is exported). A site's header now
+  goes in a layout once, instead of a copy per page to mark the right navigation item.
+
+  `notifications` dresses the whole toast, not only its colours: `font`, `fontSize`, `border`, `shadow` and `padding`
+  join `radius` — the library's variables where it has them, a rule on the toast where it has none. A space no longer
+  writes `.Toastify__toast { … }` into its `customCss` for them.
+
+  A visitor whose machine asks for less motion gets it on every space: the SDK's base layer cuts animations and
+  transitions to an instant (each still ends where it would) and turns smooth scrolling off. Spaces used to copy that
+  rule into their own custom CSS, and one that did not moved anyway.
+
+  Authoring suggests, beside what it refuses and warns: `authorSpace` returns `suggestions` — a shorter way to the same
+  page, each with its code, the elements it is about and how many it would save, the largest first. The same header in
+  every page is a layout (`repeated-on-pages`, which also names the `current` state when the copies differ only in the
+  active link), one structure copied with other words a component or a list (`repeated-shape`), a `text` alone inside a
+  button or a link the element's own `content` (`content-attribute`), and `customCss` that a class's states, the SDK or
+  `notifications` already say (`custom-css-*`). Copies are compared by what they read too — a block reading its own
+  provider is still one block, two pagers over two lists are not — a block only some pages of a layout carry is offered as
+  a component rather than a layout of its own, and a text that is a shape drawn inside a button is left alone.
+  `suggestSpace({ schema, style })` gives them for any document; they never block. `plitzi_validate` and `plitzi_apply`
+  answer with the ones a batch opened up, `npm run author` prints them under the warnings (and `--json` carries them), and
+  the authoring skill's new `reference/efficiency.md` teaches the short way first.
+
+  A `link` has words of its own: `content`, drawn before or after its children (`contentPlacement`), as a button's — a
+  link with only a label no longer needs a `text` inside it.
+
+  A style that writes its rules beside `states`, `variants` or `ancestors` — `{ desktop: { … }, ancestors: { … } }` — is
+  refused with what to write (`rule-set-mixed`: the rules go under `css`), instead of reporting `desktop: [object Object]`
+  as a CSS value it could not read.
+
+  `plitzi explain` and `plitzi://explain` name a suggestion's code `suggested`, with its short way, instead of calling it
+  `warned`. The MCP server's guide teaches the short way first — a link's own `content`, the `current` state for the link
+  to the page being shown, a component for a block only some pages of a layout carry — and how to read the
+  `suggestions` `plitzi_validate` and `plitzi_apply` answer with.
+
+  The MCP server dresses the notifications too: `patchSettings { notifications: { background, border, … } }`, merged
+  field by field (`null` removes one), and `plitzi://settings` reads them apart from the space's own `customCss` — the
+  same rule authoring writes for a space's `notifications`, kept when either changes. The builder's Export gives that
+  rule back as `notifications` instead of leaving it in `customCss` (`splitNotificationsCss`, `withNotificationsCss`).
+
+  A `button` and a `link` draw an icon beside their words: `icon` (Font Awesome classes, `'fa-solid fa-arrow-right'`) and
+  `iconPlacement` (`before` or `after` the words), dressed through a new `icon` slot; it takes the size of the words and
+  no space of its own — the box's `gap`, or a margin on the slot, separates them. One element instead of the element, a
+  `text` and a `fontAwesome`; alone, with a `title`, it is an icon button. The builder offers the icon picker in both
+  elements' settings (shared now with `fontAwesome`'s), and the `content-attribute` suggestion points at a plain
+  `fontAwesome` beside the words too.
+
+  The builder lists the suggestions: `SpaceIssues` answers `suggestions` beside `errors` and `warnings`, the problems
+  panel shows them last — the short way, how many elements it saves, and each element it is about, a link to it — and
+  the header's issues button, with nothing wrong, shows a light bulb and how many there are.
+
+  The builder edits the notifications' look in the space settings (Notifications: surface, text, accents, radius, font,
+  size, border, shadow, padding), checked as it is typed; the custom CSS editor shows the space's own CSS without the
+  rule they are stored as, and keeps it. The mechanism moved to `@plitzi/sdk-shared/style/notifications`
+  (`notificationsCss`, `notificationsProblem`, `splitNotificationsCss`, `withNotificationsCss`); `@plitzi/sdk-authoring`
+  re-exports it, refusing a spec that is not sound as before.
+
+  ## Motion that waits for the page to wake
+
+  The SDK's root carries `data-hydrated` once the page is hydrated, so a space can hold decorative motion that runs on
+  the main thread — a custom property, a `background-position`, a `top` — until then, when it would stutter behind the
+  hydration's long tasks: `animation-play-state: paused` on the element, and `[data-hydrated] .x { animation-play-state:
+running }`. Opacity and transform animations run on the compositor and need no gate.
+
+  Hydration is lighter on the way: the fonts' Google URLs sort their families by code point instead of `localeCompare`,
+  whose first call built a collator in the middle of the page's first render, and twig's compiled-template cache holds
+  1024 templates instead of a number a large space outgrew, compiling the same ones again on every render.
+
+  Good practices for motion, said wherever a space is written: `docs/en/motion.md`, the authoring skill (a rule in
+  `SKILL.md` and `reference/colours-and-motion.md`), the MCP server's guide and quickstart, and the website's styling
+  docs — animate `opacity` and `transform`, never blur, a shadow or a size; fake the expensive ones with the cheap ones;
+  hold main-thread decoration until `data-hydrated`; short entrances, one slow loop per screen, no `transition: all`.
+
+  `heavy-animation`, a new suggestion: keyframes that something runs and that animate a size or a position, a blur or a
+  shadow — or, in a loop, a colour, a gradient or a custom property — are named with each property and the way out of
+  its cost. A loop that starts `paused` and runs under `[data-hydrated]` is let through, a property that only switches
+  (`visibility`) is not counted, and keyframes nothing runs are not mentioned. It reaches `authorSpace`, `npm run
+author`, `plitzi_validate`/`plitzi_apply`, `plitzi explain` and the builder's problems panel like every suggestion. The
+  stylesheet scanner `customCss` folding used is shared now (`style/stylesheet`), and reads at-rules' blocks.
+
+  `authorSpace` suggests `heavy-animation` for keyframes something runs off the compositor — a size, a position, a
+  blur, a shadow every time; a colour, a gradient or a custom property in a loop — naming each property and the way out
+  of its cost. A loop that starts `paused` and runs under `[data-hydrated]` is let through; a property that only
+  switches (`visibility`) is not counted. It reaches `plitzi_validate`, `npm run author` and the builder's problems
+  panel like every suggestion, and never blocks. The scanner `customCss` is read with is shared now
+  (`style/stylesheet`), so the fold and this read the same segments.
+
+  `@plitzi/plitzi-ui` 1.6.29: every field is labelled by its `label` and described by its error message, the code
+  editor included.
+
+  ## A layout grid over the canvas
+
+  The builder's header has a layout grid switch beside the element outlines: the columns a page is laid out on, drawn
+  over the canvas — twelve on a desktop, eight on a tablet, four on a phone, with their gutters and margins — so an
+  element is lined up by eye with the rest of the page — switching at the page's own breakpoints. It follows the canvas
+  zoom, lets every click through, and is remembered between visits like the outlines.
+
+  ## A QA tab in the dev tools
+
+  The dev tools — wherever debugging is authorized, a pre-production deployment included — have a **QA** tab for whoever
+  checks a build in the browser it will be used in. A bar of tools over the page: an **inspector** — point at any element
+  for its box model, type, colours and their contrast; click to keep it in the tab with its computed box, type, classes
+  and every CSS rule that reaches it as written (copyable); hold Alt over another to measure the distance between them —
+  the builder's layout grid, every element's outline, the order the Tab key walks the controls in, the viewport's size
+  and the breakpoint showing, animations paused, the page with reduced motion, and the page as seen without one kind of
+  colour, in grayscale or out of focus. Beside it, six checks that outline what they find and scroll to it: whatever
+  sticks out past the page's sides, controls and pictures with no name, text under AA contrast, pictures stretched past
+  their pixels or far bigger than shown, a heading outline with no h1 or a skipped level, and touch targets under 24 × 24
+  px with another too close (WCAG 2.2). The tab lays the checks and the inspector side by side when the panel is wide.
+  Folding the panel away stops the inspector and the checks; the views — grid, outlines, vision — stay, in this browser.
+  The tab is offered where `DevToolsContainer` is given `qa` — the SDK does, over its page; an application shell such as
+  the builder does not, so its own UI is never walked by the checks. Its settings are kept under a key of their own
+  (`plitzi-sdk-dev-tools-qa`), the checks run when the page is idle, and the tab order is worked out again only when the
+  page changes.
+
+  The layout grid and the breakpoints are one definition in `@plitzi/sdk-shared/style` (`LAYOUT_GRIDS`,
+  `layoutGridLook`, `layoutGridCss`, `DISPLAY_MODE_MIN_WIDTH`, `displayModeAt`), which `@plitzi/sdk-style` compiles its
+  media queries from and the builder's grid draws with. The SDK's stylesheet applies its reduced-motion rule under the
+  class `plitzi-reduced-motion` on the document too, from the same mixin as the media query.
+
+- Updated dependencies [8d1cc02]
+  - @plitzi/sdk-auth@0.37.10
+  - @plitzi/sdk-dev-tools@0.37.10
+  - @plitzi/sdk-event-bridge@0.37.10
+  - @plitzi/sdk-navigation@0.37.10
+  - @plitzi/sdk-schema@0.37.10
+  - @plitzi/sdk-shared@0.37.10
+
+## 0.37.9
+
+### Patch Changes
+
+- 3ae61a4: ## Components replace segments
+
+  - **What a component is:** a reusable block written once and placed anywhere as an instance. An edit to the component
+    is an edit to every instance.
+  - **Where it lives:** in the space document, as `schema.components`, one tree per component and never in
+    `schema.flat`. It is published, rolled back, copied by templates and exported with the space.
+  - **Props and slots:**
+    - A component declares props (`type`, `description`, `required`, `default`, `options`). An instance hands them in
+      as its own attributes, so templates and bindings reach them. Inside, they are read as `{{ props.<name> }}`.
+    - Slots are elements an instance fills; each child names its slot in `attributes.slot`.
+  - **A prop an instance leaves out prints nothing.** It is its `default`, or `null`. `props` is a settled source:
+    - `processTwig` takes `{ settled }` in place of `keepEmptyTokens: true`.
+    - Every other empty token is still kept for a later pass.
+    - `COMPONENT_PROPS_SOURCE` names the source.
+  - **Fixed: a flow in a list row or a component instance acts on its own copy.** A step's target resolves in the
+    replica the flow fired in first, then outwards. It used to reach whichever copy registered last.
+  - **Fixed: an instance's own `visible` hides it in preview.** The same goes for an element reference.
+  - **Fixed: a list row keeps its state with its record.** Rows are keyed by each record's unique `id`, so filtering no
+    longer moves one row's state onto another.
+  - **Closed scope:** inside, a component reads only its props and the globals. The validator, `lintSpace` and
+    `authorSpace` each refuse a read of the page around an instance. Components nest, and a cycle is refused.
+  - **Where to use them:**
+    - In code (`@plitzi/sdk-authoring`): `SpaceSpec.components` and `component(id, { props, children })`.
+      `specFromSpace` and `specToSource` read and write both.
+    - In the builder:
+      - a Components panel lists them, and an open component becomes the canvas;
+      - an element becomes a component with **Save as component**;
+      - in an instance's settings, an instance gets its props and slots, or is **detached** back into a copy.
+    - In the MCP: `upsertComponent` and `deleteComponent`. Element ops work inside a component through `pageRef`.
+  - **Schema helpers:** `@plitzi/sdk-schema` gains `addComponent`, `updateComponent`, `removeComponent`,
+    `detachInstance`, `renameElement`, `treeOf`, `flatMapOf` and `documentIds`.
+  - **GraphQL and live events:** `SpaceAddComponent`, `SpaceUpdateComponent`, `SpaceRemoveComponent` and
+    `SpaceDetachInstance`, each with a live event. History records a declaration change as a `component` entry.
+  - **Breaking: segments are removed.** This covers:
+    - `@plitzi/sdk-shared`'s segment types, queries, mutations, context and `SEGMENT_*` events;
+    - `referenceType: 'segment'`;
+    - the `Segments` builder module;
+    - `Space.segments` and the `Segment`/`Segments` queries;
+    - `CommonState.prevSchema`.
+  - **Breaking: `ElementLayout` and `LayoutBody` change shape.**
+    - `ElementLayout` is `{ slots, rootId, type }`; it was `{ containerId }`.
+    - `LayoutBody` takes `bodies` keyed by slot.
+    - `reference`'s `referenceContainer` attribute is removed.
+  - Guide: `docs/en/components.md`.
+
+  ## Functions ask for the time they need
+  - **What changes:** a task can ask for more CPU or wall time than the default with `limits`, in milliseconds. Example:
+    `limits: { cpuMs: 1000, wallMs: 20_000 }`. `defineFunctions({ limits })` asks it for every task and route at once,
+    and a task's own limits win over those.
+  - **What a run is given:** what it asked for, or the default (100 ms of CPU, 10 s) when it asked for nothing. Never
+    above the space's plan or the deployment's ceiling.
+  - **Deployment ceilings:** `functions.limits` sets them. `DEFAULT_FUNCTION_CEILINGS` covers each unset one, at 2 s of
+    CPU and 30 s.
+  - **Asking for more than the ceiling** is a problem when the functions are saved; it is never quietly cut down.
+  - **Manifest:** carries what each task asked for, and the builder shows it beside the task.
+
+  ## Functions answer under `/fn`, not `/api`
+
+  A space's routes are served at `/fn/<path>` (`FUNCTION_ROUTES_PREFIX`). `/api` is a slug a site wants for a page of its
+  own. A page under `/fn` is refused instead (`page-route-reserved`).
+
+  ## The builder's Functions panel
+
+  Rebuilt around the code. The panel reads `defineFunctions` as it is typed and writes into it, so the code stays the one
+  place a function is declared.
+
+  - **Layout:** the tasks, routes and files on the left, the code in the middle, the selected task on the right.
+  - **Live list:** tasks and routes are listed as the code declares them, including tasks imported from another file.
+    A task you have written but not saved says so. Tasks built by calling something are counted, and listed once saved.
+  - **Code and panel follow each other:** clicking a task or a route opens its file at its line. Putting the cursor inside
+    a task's code selects that task.
+  - **New task:** + in Tasks asks for its namespace, action and title. The task is written into `defineFunctions` with a
+    `run` to start from, in the file's own quotes, and the editor opens on it.
+  - **Time limit:** each task gets a slider from 100 ms to 1 s of CPU per run, with presets. The value is written into
+    the task as `limits: { cpuMs }`. "Use default" takes it out. `DEFAULT_FUNCTION_TIME_LIMITS` in
+    `@plitzi/sdk-shared/actions` is the default both the panel and the server use.
+  - **Test:** fills a task's params the way its step does, from their defaults: a select, a switch or text. JSON stays a
+    toggle away. With unsaved changes, the button reads "Save & run": it saves, then runs. If the save fails, it says why.
+  - **Header:** shows Saved, Unsaved (and in how many files) or the number of problems the last save found. ⌘S saves.
+    **Discard** asks first, then puts every file back to what was last saved, or back to nothing for functions never
+    saved. Removing the functions is a quiet button beside Save.
+  - **Problems:** clicking one opens its file at its line.
+  - **Editor:** each file has its own editor and undo history. Opening another file no longer marks the one you left as
+    changed. Before this, it could also write the newly opened file's text into the one you left. The cause was in
+    `@plitzi/plitzi-ui`'s CodeMirror, fixed in 1.6.25, which every package now depends on. That release also sets code
+    editors (several lines) in a monospaced face again. Long lines scroll inside the editor, and the line numbers stay
+    in place.
+
+  ## A space's own functions are their own category of steps
+
+  In the action editor's step picker, the space's own functions are listed under **Functions**, apart from the
+  platform's **Tasks**. The other headings now read Callbacks, Global callbacks and Utilities. The saved step is still a
+  `task` node.
+
+  - `@plitzi/sdk-server`: every registered task has an `origin`, `'deployment'` (shipped with the server or a native
+    function) or `'space'` (from the space's functions). `describeCatalog`, `/_action/catalog` and the builder's
+    `SpaceActionTasks` carry it (`ActionTaskDescriptor.origin`).
+  - `@plitzi/sdk-shared`: an `InteractionCallback` may name the `group` the picker lists it under.
+
+  ## Fixed: preview no longer breaks a builder that is embedded in a page
+
+  When the builder is mounted inside a Plitzi page (the platform's `/spaces/:id/update`), going to preview with a page
+  that has SEO turned on left the builder unstyled. The previewed page wrote its title and description through a head
+  manager of the builder's own, and that manager rewrote the host page's head, removing the builder's own stylesheet.
+
+  - `@plitzi/sdk-shared`: a new render setting, `ownsHead`, says whether the page may write the document head. It is on
+    by default (`DEFAULT_RENDER_SETTINGS`).
+  - `@plitzi/sdk-elements`: `Page` writes its SEO only where `ownsHead` is on.
+  - Builder: sets `ownsHead: false` for its canvas. A page drawn there is in a frame, and the document head is the
+    editor's. The canvas's own `HelmetProvider` is gone.
+
+  ## Fixed: the builder's plan usage panel shows the space being edited
+  - **The 404 is gone.** Opening Plan usage said "The account breakdown could not be read (The server answered 404.)".
+    The panel asked `/account/usage`, which went away when accounts became workspaces.
+  - **Only this space.** The panel listed every space of the workspace. It now reads `/spaces/:spaceId/usage`, which
+    now also answers the space's own `pages` (the heaviest ten), `pagesTotal` and `periodEndsAt`. The plan's ceilings
+    stay on top. Anyone who can edit the space can read it, including a guest of another workspace.
+  - **It scrolls.** A long breakdown scrolls inside the modal, where it used to overflow.
+  - **`getKeyDecoded(webKey, true)` reads the token's subject.** The function, in `@plitzi/sdk-shared`, looked for
+    `data.spaceId`, which space tokens no longer carry, so every space decoded as 0. The builder asked about space 0, and
+    the builder and the SDK kept every space's persisted state under the same key on a host. Pages served without a
+    `webKey` (SSR) still decode as 0, which is what their painted-state cookie is named after.
+
+  ## Fixed: a remote plugin in the builder reads the canvas it sits in
+
+  The builder carries its own copy of the Plitzi runtime. A remote plugin imports `@plitzi/plitzi-sdk`, which the page's
+  import map resolves to the SDK's copy. Each copy made its own React contexts, so on the builder's canvas a plugin read
+  none of the canvas's providers. In the builder embedded in Plitzi's site, it read the site around the builder instead:
+  the site's element as its own, the site's live mode (so it stayed interactive while being edited), and the site's store
+  and interactions.
+
+  - `@plitzi/sdk-shared` gains `sharedContext(name, default)`: a context made once per page and handed to every copy of
+    the runtime that asks for it.
+  - The runtime's contexts now go through it, so a provider from any copy reaches a consumer from any copy:
+    - `@plitzi/sdk-shared`: service, component, schema, network, theme scope, dev tools, builder.
+    - `@plitzi/sdk-elements`: element, element parent, layout body.
+    - interactions, plugins, event bridge, auth, variables and style.
+  - The store's contexts need `@plitzi/nexus` 1.4.0, which does the same. Every `@plitzi/*` package now asks for
+    `^1.4.0`, which is published.
+
+  ## The source of plugins and runtimes is kept on the space
+
+  What a plugin or a runtime is built from now goes up with it, so a space can be taken back out as a project
+  (`plitzi create --from`, below).
+
+  - `@plitzi/cli`:
+    - `plitzi pack plugin` writes the plugin's source beside its zip: every file of the project its elements import,
+      `import type` included, and the packages they need. `--source-root` names the project those paths are relative to.
+    - `plitzi upload plugin` and `plitzi runtime push` keep that source on the space, in its private bucket.
+    - `plitzi pack source` writes it to a file.
+    - A source that cannot be kept (a file outside the project, an undeclared package, a credential in the code) never
+      stops the upload or the push: they say why, and the artifact is kept built only.
+  - `@plitzi/sdk-shared/source`: the snapshot's format, the paths it may hold and the credential check, shared by the CLI
+    and the platform.
+
+  ## `plitzi create --from` and `plitzi pull`: a space on Plitzi as a project of your own
+
+  The way back from everything the CLI puts on Plitzi. `plitzi create my-board --from pizarra` writes a server project
+  holding what the space is made of, and runs it with nothing of Plitzi's: neither its servers nor its CDN. `plitzi pull`
+  keeps it in step with the space. See `docs/en/projects-from-spaces.md`.
+
+  - **What lands in the project:**
+    - its pages as authoring code;
+    - its server actions as `defineAction` code — JSON, with the reason said, for one that would not read back exactly;
+    - its plugins and runtime as the source they were uploaded from, and its functions;
+    - its files, downloaded into `public/`, with every CDN address rewritten to the project's.
+  - **`src/main.ts`** serves all of it, the runtime in the same process.
+  - **`.env`** gets a key made for the project's actions to sign with, and the names of the variables and credentials
+    the space had. Their values stay on Plitzi.
+  - **Who may run it:** the person must be signed in and able to change the space (owner, administrator or writer).
+  - **Plugins** are rebuilt against the project's SDK. One uploaded before sources were kept runs as it was built, from
+    `vendor/plugins/`, and the report says to upload it again.
+  - **The end of `create`** says what came across differently, including a space whose visitors sign in with Plitzi.
+  - `--source cloud` keeps the pages on Plitzi and runs the rest locally.
+  - **Any version:** `--environment` and `--revision` take out a published snapshot — its latest, or one revision pinned
+    — instead of the draft, with the source its plugins and runtime were built from then. A cloud project serves that
+    revision pinned.
+  - **`plitzi pull`** writes what changed on the space, keeps what changed in the project, and writes nothing when a
+    file changed on both — naming them, with `--force` to take the space's copy. It never touches `.env`, only adds to
+    `package.json`, and keeps `plitzi functions push` working from the project. It follows the version the project was
+    made from, and `--environment`/`--revision` move it.
+  - `@plitzi/sdk-authoring`:
+    - `actionSpecFromEntry` reads an action document back into its `defineAction` declaration, only when the round trip
+      is exact, and `actionToSource` writes it as a module.
+    - `defineAction` takes `limits`.
+    - `specToSource` takes `importExtension: '.ts'`, for split files that Node imports as they are.
+
+  ## The builder shows what a snapshot holds
+
+  **Make Snapshot** lists what it will freeze — pages, layouts and elements, server actions, connectors, functions, the
+  runtime and the plugins, each with whether its source is kept — and what no snapshot freezes: the space's files, its
+  variables and credentials. A space's components are part of its document, so they are frozen with its pages. **Publish Snapshot** lists what the chosen environment's snapshot holds.
+
+  ## Fixed: a space read from Plitzi kept its server elements
+  - **What happened:** a page server reading its space from Plitzi (`createCloudAdapters`) never ran an element's
+    `render` action, and a browser-rendered space ignored `loadStrategy`. The space's GraphQL answered neither
+    `runtime` nor `loadStrategy` of an element, nor the space's `rsc` settings.
+  - **Now:** the platform answers them, and the SDK, the builder and the cloud adapters ask for them.
+
+  ## A plugin the deployment registers is not looked for elsewhere
+
+  `@plitzi/sdk-server` used to fetch the manifest of every plugin the space lists on its CDN, even one the deployment
+  registers itself, and logged a warning when the CDN was out of reach. It now asks only for the ones it does not have.
+
+  ## Fixed: inline code in Markdown carries nothing of the syntax tree
+
+  A `markdown` element wrote every inline `` `code` `` as `<code node="[object Object]">`: `react-markdown` hands its
+  renderers the syntax-tree node as a prop, and the inline branch spread it onto the tag. Fixed in
+  `@plitzi/plitzi-ui` 1.6.26 (with a test), which every package now asks for.
+
+  ## Dev tools hear about the render run the page stopped waiting for
+
+  When a server element's action ran past the section's budget, the page was answered without it. The run ended a moment
+  later, after the page's runs had been sent, so the dev tools never showed the one run that needed debugging. It is now
+  told the moment the page stops waiting, as `aborted`, with the reason.
+
+  ## Fixed: a tab you come back to no longer loses its session
+  - **What happened:** a page left in another tab past its access token's life signed its visitor out on return. A
+    reload put them right back in.
+  - **Why:** the browser drops the cookie carrying the access token the moment the token expires, and the background
+    tab's renewal timer had not run. The first check on return was told `missing`, which the client took as no
+    session at all.
+  - **Now:** a `missing` refusal is renewed instead whenever the browser can still renew, meaning it holds a refresh
+    token or a session hint whose renewal window is open. The session ends only if that renewal fails.
+  - **Requests made in that moment:** `reportAuthFailure` now answers whether it renewed the session. A read refused
+    as the tab came back is asked again, once, once the session is renewed. This covers an api container's read and a
+    server section's refresh, so they no longer show a 401 that only a reload cleared.
+
+- Updated dependencies [3ae61a4]
+  - @plitzi/sdk-auth@0.37.9
+  - @plitzi/sdk-dev-tools@0.37.9
+  - @plitzi/sdk-event-bridge@0.37.9
+  - @plitzi/sdk-navigation@0.37.9
+  - @plitzi/sdk-schema@0.37.9
+  - @plitzi/sdk-shared@0.37.9
+
 ## 0.37.8
 
 ### Patch Changes

package/dist/InteractionsContext.mjs

@@ -1,5 +1,4 @@
-import { createContext as e } from "react";
-var t = e({});
-t.displayName = "InteractionsContext";
+import { sharedContext as e } from "@plitzi/sdk-shared/helpers/sharedContext";
+var t = e("InteractionsContext", {});
 //#endregion
 export { t as default };

package/dist/InteractionsManager.d.ts

@@ -34,6 +34,14 @@ declare class InteractionsManager {
     private getSubscriptorInternal;
     getSubscriptor(subscriptorId: string): Subscriptor | undefined;
     private getCallbacksAvailablesInternal;
+    /**
+     * Every callback a flow fired here can reach, by the id of the element it belongs to.
+     *
+     * A replica — a list row, a component instance — renders the same ids as every other copy of it, so an id alone
+     * names several elements. The one a flow means is the nearest: in the replica the flow fired in, else in the
+     * replicas around it, else anywhere on the page. Merged the other way, the copy that registered last answered for
+     * all of them, and a card's "Details" opened another card's panel.
+     */
     getCallbacksAvailables(): {
         [x: string]: Record<string, InteractionCallback> | Record<string, InteractionCallback<any>>;
     };

package/dist/InteractionsManager.mjs

@@ -1,13 +1,16 @@
 import { flowTrigger as e } from "./InteractionsHelper.mjs";
 import { get as t, set as n } from "@plitzi/plitzi-ui/helpers";
 import r from "@plitzi/sdk-event-bridge";
-import { KEY_TRIGGER as i } from "@plitzi/sdk-shared/helpers/keys";
+import { INTERVAL_TRIGGER as i, intervalOf as a } from "@plitzi/sdk-shared/helpers/interval";
+import { KEY_TRIGGER as o } from "@plitzi/sdk-shared/helpers/keys";
 //#region src/InteractionsManager.ts
-var a = (e, t) => {
-	if (e.action !== i) return !0;
-	let { shortcuts: n } = t;
-	return Array.isArray(n) && n.includes(e.params.keys);
-}, o = class i {
+var s = (e, t) => {
+	if (e.action === o) {
+		let { shortcuts: n } = t;
+		return Array.isArray(n) && n.includes(e.params.keys);
+	}
+	return e.action !== i || a(e.params.interval) === t.interval;
+}, c = class i {
 	eventBridge;
 	parentManager;
 	childManagers;
@@ -24,15 +27,15 @@ var a = (e, t) => {
 			...n
 		}, this.lastUpdate = Date.now();
 	}
-	eventBridgeCallback = (n) => async (r, i, o) => {
+	eventBridgeCallback = (n) => async (r, i, a) => {
 		if (!n || !i || !r) return;
-		let s = this.subscriptors[r];
-		if (await Promise.resolve(), !s || this.subscriptors[r] !== s) return;
+		let o = this.subscriptors[r];
+		if (await Promise.resolve(), !o || this.subscriptors[r] !== o) return;
 		let c = t(this.subscriptors, `${r}.getAdditionalParams`, void 0), l = () => ({
 			...this.interactionsData,
 			...typeof c == "function" ? c().dataSource : void 0
-		}), u = Object.values(n).filter((e) => e.type === "trigger" && e.action === i && e.enabled && a(e, o));
-		await Promise.all(u.map((t) => this.runFlow(`${r}.${t.id}`, t.whileRunning ?? "skip", () => e(t, n, this.getCallbacksAvailables(), { [t.id]: o }, l, r))));
+		}), u = Object.values(n).filter((e) => e.type === "trigger" && e.action === i && e.enabled && s(e, a));
+		await Promise.all(u.map((t) => this.runFlow(`${r}.${t.id}`, t.whileRunning ?? "skip", () => e(t, n, this.getCallbacksAvailables(), { [t.id]: a }, l, r))));
 	};
 	runFlow(e, t, n) {
 		let r = this.flowsRunning.get(e);
@@ -101,7 +104,18 @@ var a = (e, t) => {
 		};
 	}
 	getCallbacksAvailables() {
-		return this.parentManager ? this.getRootManager()?.getCallbacksAvailablesInternal() ?? {} : this.getCallbacksAvailablesInternal();
+		if (!this.parentManager) return this.getCallbacksAvailablesInternal();
+		let e = [];
+		for (let t = this.parentManager; t; t = t.parentManager) e.unshift(t);
+		let t = this.getRootManager()?.getCallbacksAvailablesInternal() ?? {};
+		for (let n of e) t = {
+			...t,
+			...n.callbacksAvailables
+		};
+		return {
+			...t,
+			...this.getCallbacksAvailablesInternal()
+		};
 	}
 	interactionTrigger(e, t, n = {}) {
 		if (e) return this.eventBridge.emit("interaction", e, e, t, n);
@@ -125,4 +139,4 @@ var a = (e, t) => {
 	}
 };
 //#endregion
-export { o as default };
+export { c as default };

package/dist/utility/webHook.mjs

@@ -10,37 +10,34 @@ var a = /* @__PURE__ */ new Set(["GET", "HEAD"]), o = /* @__PURE__ */ new Set([
 	let n = Number(t);
 	return (Number.isFinite(n) && n >= 0 ? n : Number(e.params.staleTime.default)) * 1e3;
 }, c = (e) => e ? { Authorization: `Bearer ${e}` } : {}, l = (e) => typeof e == "object" && e ? e : {}, u = /* @__PURE__ */ new Set(["authorization", "content-type"]), d = (e) => typeof e == "object" && e ? Object.fromEntries(Object.entries(e).flatMap(([e, t]) => (typeof t == "string" || typeof t == "number") && t !== "" && !u.has(e.toLowerCase()) ? [[e, String(t)]] : [])) : {}, f = async ({ url: e, authorizationToken: t, headers: n, body: r, credentials: i }, a) => {
-	let s = l(r), u = Object.values(s).some((e) => e instanceof Blob);
-	try {
-		let r = {
-			method: a,
-			headers: {
-				...d(n),
-				...u ? {} : { "Content-Type": "application/json" },
-				...c(t)
-			},
-			credentials: i
-		};
-		if (!o.has(a)) {
-			if (!u) r.body = JSON.stringify(s);
-			else {
-				let e = new FormData();
-				Object.entries(s).forEach(([t, n]) => {
-					e.append(t, n);
-				}), r.body = e;
-			}
+	let s = l(r), u = Object.values(s).some((e) => e instanceof Blob), f = {
+		method: a,
+		headers: {
+			...d(n),
+			...u ? {} : { "Content-Type": "application/json" },
+			...c(t)
+		},
+		credentials: i
+	};
+	if (!o.has(a)) {
+		if (!u) f.body = JSON.stringify(s);
+		else {
+			let e = new FormData();
+			Object.entries(s).forEach(([t, n]) => {
+				e.append(t, n);
+			}), f.body = e;
 		}
-		let l = await fetch(e, r), f = "";
-		try {
-			f = await l.json();
-		} catch {}
-		return {
-			status: l.status,
-			data: f
-		};
-	} catch (e) {
-		return console.error(e), {};
 	}
+	let p = await fetch(e, f).catch((t) => {
+		throw Error(`${a} ${e} got no answer: ${t instanceof Error ? t.message : String(t)}`);
+	}), m = "";
+	try {
+		m = await p.json();
+	} catch {}
+	return {
+		status: p.status,
+		data: m
+	};
 }, p = t("webHook", e, async (e) => {
 	let t = (e.method || "get").toUpperCase();
 	if (a.has(t)) {
@@ -58,11 +55,11 @@ var a = /* @__PURE__ */ new Set(["GET", "HEAD"]), o = /* @__PURE__ */ new Set([
 			meta: { url: e.url },
 			fetcher: () => f(e, t),
 			staleTime: s(e.staleTime),
-			isCacheable: (e) => e.status !== void 0 && e.status < 400
-		}) ?? {} };
+			isCacheable: (e) => e.status < 400
+		}) };
 	}
 	let o = await f(e, t);
-	return o.status !== void 0 && o.status >= 200 && o.status < 300 && n({
+	return o.status >= 200 && o.status < 300 && n({
 		mode: e.invalidateQueries,
 		fallback: "origin",
 		elements: e.invalidateElements,

package/dist/utility/webHookSpec.d.ts

@@ -5,5 +5,8 @@ import { BuiltinActionSpec } from '@plitzi/sdk-shared/authoring/builder';
  * A read may be served from the page's query cache — the same one api containers use, under the same key, so a
  * flow reading a URL a container already loaded does not ask again. A write says what it refreshes once it
  * succeeded, which by default is every cached request to the site it wrote to.
+ *
+ * Any answer is the step's result, an error status included — `{{ <step>.response.status }}` is how a flow tells a 401
+ * from a 200. No answer at all fails the step, so the flow stops and its `onFailure` runs.
  */
 export declare const webHookSpec: BuiltinActionSpec;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-interactions",
-  "version": "0.37.8",
+  "version": "0.37.10",
   "license": "AGPL-3.0",
   "files": [
     "dist"
@@ -189,12 +189,12 @@
     "vitest": "^5.0.1"
   },
   "dependencies": {
-    "@plitzi/plitzi-ui": "^1.6.24",
-    "@plitzi/sdk-auth": "0.37.8",
-    "@plitzi/sdk-dev-tools": "0.37.8",
-    "@plitzi/sdk-event-bridge": "0.37.8",
-    "@plitzi/sdk-navigation": "0.37.8",
-    "@plitzi/sdk-schema": "0.37.8",
-    "@plitzi/sdk-shared": "0.37.8"
+    "@plitzi/plitzi-ui": "^1.6.29",
+    "@plitzi/sdk-auth": "0.37.10",
+    "@plitzi/sdk-dev-tools": "0.37.10",
+    "@plitzi/sdk-event-bridge": "0.37.10",
+    "@plitzi/sdk-navigation": "0.37.10",
+    "@plitzi/sdk-schema": "0.37.10",
+    "@plitzi/sdk-shared": "0.37.10"
   }
 }