@plitzi/sdk-server 0.37.9 → 0.37.10

package/dist/modules/ssr/prepareRender.js

@@ -1,3 +1,4 @@
+import { requestFlagOverrides } from "../../helpers/flagOverrides.js";
 import { authorizesDebugging } from "../../helpers/debugAuthorization.js";
 import { realtimeModuleFor } from "../realtime/index.js";
 import { matchRscPage } from "../rsc/matchRscPage.js";
@@ -11,10 +12,12 @@ import { createOfflineDataLoader } from "../../helpers/offlineDataLoader.js";
 import { registerExternalPlugins } from "./registerExternalPlugins.js";
 import { reportMissingPlugins } from "./reportMissingPlugins.js";
 import { resolvePageSeo } from "./resolvePageSeo.js";
+import { imagesPathOf } from "../../core/http/stages/images.js";
 import { sdkAssetVersion } from "../../core/sdkAssets.js";
 import { buildServerInfo } from "../../helpers/buildServerInfo.js";
 import { hydrationPayload } from "../../helpers/hydrationPayload.js";
 import { resolveDebugMode } from "../../helpers/resolveDebugMode.js";
+import { flagUserFromSSR, flagValues, resolveFlags } from "@plitzi/sdk-shared/flags";
 import { hasServerElements } from "@plitzi/sdk-shared/schema/serverElements";
 import { debugCookieName } from "@plitzi/sdk-shared/devTools";
 import { themeFromCookies } from "@plitzi/sdk-shared/theme";
@@ -35,7 +38,7 @@ var declaredTheme = (style) => {
 };
 var prepareRender = async (req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics, offlineDataOverride) => {
 	const m = (name, fn) => metrics ? metrics.measure(name, fn) : Promise.resolve(fn());
-	const offlineCacheKey = environment !== "main" ? buildOfflineDataCacheKey(spaceId, environment, revision) : void 0;
+	const offlineCacheKey = environment !== "main" ? buildOfflineDataCacheKey(spaceId, environment, revision, req.ctx.spaceDeployment?.flagsVersion) : void 0;
 	const cachedOfflineStr = offlineDataOverride === void 0 && offlineCacheKey ? offlineDataCache?.get(offlineCacheKey) : void 0;
 	const loadOfflineData = createOfflineDataLoader(() => {
 		if (offlineDataOverride !== void 0) return Promise.resolve(offlineDataOverride);
@@ -46,13 +49,27 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	const rscPath = resolveRscEndpoint(config);
 	const schema = offlineData?.schema;
 	const pageMatch = schema !== void 0 ? matchRscPage(schema, req.path, req.ctx.user) : void 0;
-	const rscData = rscPath !== void 0 && schema !== void 0 && schema.rsc?.enabled !== false && pageMatch !== void 0 && hasServerElements(schema, pageMatch.pageId) && config.adapters.getRscData ? await m("rsc", () => config.adapters.getRscData?.({
+	const rscEnabled = rscPath !== void 0 && schema !== void 0 && schema.rsc?.enabled !== false;
+	const debugAuthorized = !Boolean(req.query["__pt"]) && authorizesDebugging(config, schema?.settings);
+	const flagOverrides = await requestFlagOverrides(config, req, {
+		spaceId: req.ctx.spaceDeployment?.spaceId ?? spaceId,
+		environment: req.ctx.spaceDeployment?.environment ?? environment
+	}, debugAuthorized);
+	const pageFlags = schema !== void 0 && pageMatch !== void 0 ? flagValues(resolveFlags(schema.flags, {
+		environment: req.ctx.spaceDeployment?.environment ?? environment,
+		hostname: req.hostname,
+		routeParams: pageMatch.routeParams,
+		queryParams: req.query,
+		user: flagUserFromSSR(req.ctx.user)
+	}, flagOverrides)) : void 0;
+	const rscData = rscEnabled && pageMatch !== void 0 && hasServerElements(schema, pageMatch.pageId, pageFlags) && config.adapters.getRscData ? await m("rsc", () => config.adapters.getRscData?.({
 		req,
 		spaceId: req.ctx.spaceDeployment?.spaceId ?? spaceId,
 		environment: req.ctx.spaceDeployment?.environment ?? environment,
 		revision: req.ctx.spaceDeployment?.revision ?? revision,
 		user: req.ctx.user,
-		loadOfflineData
+		loadOfflineData,
+		flagOverrides
 	})) : rscPath ? { serverData: {} } : void 0;
 	const pageSeo = resolvePageSeo(schema, pageMatch?.pageId);
 	const server = buildServerInfo(req, config, {
@@ -60,7 +77,8 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		rscData,
 		actionPath: resolveActionEndpoint(config),
 		realtimePath: realtimeModuleFor(config)?.path,
-		realtimeTransport: realtimeModuleFor(config)?.transport
+		realtimeTransport: realtimeModuleFor(config)?.transport,
+		imagePath: imagesPathOf(config)
 	});
 	if (offlineDataOverride === void 0 && !cachedOfflineStr && offlineCacheKey && offlineData !== void 0) offlineDataCache?.set(offlineCacheKey, JSON.stringify(offlineData));
 	const version = config.assetVersion ?? sdkAssetVersion();
@@ -81,7 +99,6 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	* so does the space itself (`settings.debugMode`) — an owner inspecting their own published site. The space is read
 	* from what this server loaded, never from the request, so a visitor has no say in it.
 	*/
-	const debugAuthorized = !Boolean(req.query["__pt"]) && authorizesDebugging(config, schema?.settings);
 	const debugRendered = resolveDebugMode(debugAuthorized, readCookie(req.headers.cookie, debugCookieName(req.headers.host)));
 	/**
 	* The runs this render's server elements started, handed to a page that may debug them — and to no other.
@@ -123,6 +140,13 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	* would hydrate other markup. Only the keys the space declares, and only with `keepState` on.
 	*/
 	const paintedState = schema?.settings.keepState ? paintedStateFor(req.headers.cookie, ssrPaintedCookieName(req.headers.host), paintedKeys(schema.settings)) : void 0;
+	/**
+	* The two layers of the space's flags this server answers for. Its own (`config.flags`), asked per space when it
+	* serves several; and the ones a tester forced from the dev tools, read from their cookie — only for a page allowed
+	* to debug, or any visitor could switch on a feature still behind a flag. Both travel to the browser beside the
+	* page, so it hydrates with the flags it was drawn with.
+	*/
+	const { server: serverFlags, qa: forcedFlags } = flagOverrides;
 	const offlineDataStr = hydrationPayload(offlineData, {
 		offlineMode: true,
 		environment,
@@ -133,7 +157,9 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		...paintedState ? { state: paintedState } : {},
 		...clientAnalytics ? { analytics: clientAnalytics } : {},
 		...overQuota ? { overQuota } : {},
-		...actionRuns ? { actionRuns } : {}
+		...actionRuns ? { actionRuns } : {},
+		...serverFlags ? { serverFlags } : {},
+		...forcedFlags ? { forcedFlags } : {}
 	});
 	const pluginNames = req.ctx.spaceDeployment?.pluginNames ?? [];
 	const pluginSources = req.ctx.spaceDeployment?.pluginSources;
@@ -167,7 +193,9 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			sdkDevToolsStylePath,
 			overQuota,
 			theme,
-			...paintedState ? { state: paintedState } : {}
+			...paintedState ? { state: paintedState } : {},
+			...serverFlags ? { serverFlags } : {},
+			...forcedFlags ? { forcedFlags } : {}
 		},
 		entries,
 		templateParams: {
@@ -202,7 +230,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			ssrOnly: config.ssrOnly === true,
 			offlineData: offlineDataStr
 		},
-		cacheable: actionRuns === void 0
+		cacheable: actionRuns === void 0 && forcedFlags === void 0
 	};
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.37.9",
+  "version": "0.37.10",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -79,8 +79,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.37.9",
-    "@plitzi/sdk-shared": "0.37.9",
+    "@plitzi/plitzi-sdk": "0.37.10",
+    "@plitzi/sdk-shared": "0.37.10",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",
@@ -94,7 +94,8 @@
     "mongodb": "^6 || ^7",
     "mysql2": "^3",
     "react": "^19",
-    "react-dom": "^19"
+    "react-dom": "^19",
+    "sharp": "^0.34.0"
   },
   "peerDependenciesMeta": {
     "core-js": {
@@ -108,6 +109,9 @@
     },
     "mysql2": {
       "optional": true
+    },
+    "sharp": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -129,6 +133,7 @@
     "mysql2": "^3.24.4",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "sharp": "^0.34.5",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",
     "vite": "^8.3.1",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -0,0 +1,135 @@
+# Plitzi authoring — cheatsheet
+
+What most changes need, on one page. Everything is imported from `@plitzi/sdk-authoring`. For the rest, ask by name —
+`npx @plitzi/cli explain navigate` (an element, a step, a trigger, a problem's code), `--list steps` for every one of a
+kind — rather than reading its `.d.ts`.
+
+## The space
+
+```ts
+const space: SpaceSpec = {
+  name, permanentUrl,                          // permanentUrl: lowercase, digits, `-`
+  variables: { color: { card: { light, dark, default } } },   // every colour a token, both themes; tokens(variables).card
+  classes: { card },                           // styles() declarations, by their own name; styles('card', tw('p-4 rounded-xl'))
+  computed: { total: '{{ … }}' },              // values read anywhere as computed.total
+  flags: { beta: { description, value: false, rules: [] } },
+  customCss: '@keyframes …',                   // keyframes and what no property says
+  layouts: [{ id: 'shell', body }],           // chrome shared by pages
+  components: [{ id, props, slots, root }],    // a block placed many times with different content
+  pages: [{ id, name, slug: '', layout: { id: 'shell', slot: 'main' }, body: [] }]   // slot: where the body goes
+};                                             // slug '' is home; 'products/:slug' takes a param
+const { schema, style, warnings } = authorSpace(space, { plugins: [declaration] });
+```
+
+## Elements
+
+Every factory takes the element's attributes and these fields: `id`, `class`, `css`, `states`, `slots`, `bind`,
+`visible`, `flows`, `anchor`, `flag`, `runtime`, `loadStrategy`, `children`.
+
+```ts
+text('Words', { class })                       // also text({ content }); a <div> — `display: inline` to flow
+heading('Title', { subType: 'h2' })            // h1–h6; holds no children
+paragraph('A paragraph.')
+container([children], { subType: 'section' })  // div, section, nav, header, footer, main, article, li, h1–h6, span…
+link({ href: 'about', children })              // a page id, a '/path', or a URL — the mode follows from the href
+link({ href: 'home', hash: 'plans' })          // → /#plans, onto the element with anchor: 'plans'
+button({ content: 'Save', flows })             // holds children too: then content: ''
+image({ src, alt })                            // or decorative: true
+embed({ src, title })                          // a map, a player: another page in a frame
+svg('<svg …>…</svg>', { label })               // checked, sanitised; currentColor follows the class
+fontAwesome({ icon: 'fa-solid fa-xmark' })
+list({ id: 'rows', items: 'p.data.rows', row: 'row-card' })    // a <ul>; a component per row (its `item` prop)
+list({ id: 'rows', items: 'p.data.rows', row: r => text({ from: `${r.item}.title` }) })  // or a tree per row
+carousel({ id: 'hero', items: 'p.data.slides', autoplay: 5000, row: 'slide-card', children: [/* carouselNext('hero') arrows */] })
+                                               // rows follow their item's `id`, or `itemKey: 'slug'`
+apiContainer({ id: 'p', query: '/data/x.json', cache: true, children })   // publishes p.data; no box of its own
+                                               // loadingSlot: 'p-skeleton' — a child shown until it answers
+form({ id, managedByInteractions: true, flows, children })
+formControl({ name: 'email', label: 'Email', subType: 'email' })          // select: options: [{ label, value }]
+modalContainer({ id, visible: false, title, children })
+component('card', { props: { title }, children: { body: [ … ] } })
+custom({ renderType: 'myPlugin' }); defineElement<Props>(declaration)      // a plugin
+```
+
+## Styles
+
+```ts
+const card = styles('card', { padding: 24, borderRadius: 16 });        // shorthands, camelCase, numbers as px
+styles('title', { fontSize: { desktop: '48px', compact: '32px' }, fontWeight: 700 });   // one property per breakpoint
+styles('card', { css: { desktop: { … }, compact: { … } }, states: { hover: { … } }, variants: { active: { … } } });
+container({ class: card });                                    // a shared class…
+container({ id: 'hero', class: [card, { opacity: '0.5' }] });  // …plus one thing (needs an id)
+container({ css: { padding: '8px' } });                        // rules of its own — never with `class`
+```
+
+Breakpoints: `desktop` (base), `tablet` (48–64rem), `mobile` (<48rem), `compact` (tablet AND mobile). Each inherits
+from `desktop` alone. States: `hover`, `focus`, `focus-visible`, `active`, `disabled`…. An ancestor's state:
+`ancestors: { [card.name]: { states: { hover: { … } } } }`.
+
+## Data, bindings, visibility
+
+```ts
+from: 'p.data.title'                                           // the main attribute: content, src, href, items
+from: 'rows.item.price', as: 'price'                           // shown as a format (space `formats`) or a template
+from: site.data.title                                          // const site = source('p', sampleJson): typed, checked
+bind: { alt: 'p.data.title' }                                  // other attributes; short source names
+bind: [bindTemplate('content', 'p.data.items', '{{ source|length }} items')]
+bind: [bindTemplate('items', 'p.data.rows', '{{ source|filter(r => r.on) }}', { returns: 'value' })]
+bind: [variantFrom(pill, 'rows.item.status')]                  // a variant chosen by the data
+bind: [activeOn(navLink, 'about')]                             // the current page's link
+bind: [activeWhen(dot, '{{ list_dots.index == state.slide }}')] // a variant while a condition holds
+visible: 'p.data.signedIn'                                     // shown while true; '!p.data.signedIn' inverts
+visible: { source: 'p.data.rows', template: '{{ source is defined and source|length == 0 }}' }
+visible: false                                                 // hidden until a step shows it
+```
+
+Inside a list row: `rows.item` in a binding, `{{ list_rows.item.x }}` in a template or an attribute,
+`list_rows.index` is a number from 0. A provider's source in a template is `apiContainer_p`… —
+spelled in full, as the element publishes it. Globals: `state`, `navigation` (`routeParams`, `queryParams`),
+`auth`, `variables`, `computed`, `flags`, `theme`, `host`.
+
+## Flows
+
+A flow is `[trigger, …steps]`, in an element's `flows`.
+
+```ts
+[onClick(), setState({ key: 'saved', type: 'boolean', value: true })]  // types: boolean, number, text, json
+[named('sent', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ sent.values.email }}' })]
+[on('onChange'), …]; [on('onMouseEnter'), …]; [onPageLoad(), …]; [onKey('mod+k, escape'), …]
+[onInterval(5000), …]                                          // every 5 s, while the tab is in view
+[onClick(), scrollBy('cards', { x: '80%' })]; scrollTo('cards', { x: 'end' }); scrollIntoView('answer')
+[named('row', onScroll()), …]                                  // { x, y, atStart, atEnd } of its own box
+[onClick(), toggleState({ key: 'menuOpen' })]
+[onClick(), cycleState({ key: 'slide', length: 3, by: -1 })]   // goes round; stepState({ key, by, min, max }) stops
+[onClick(), openModal('details')]; closeModal('details')
+[onClick(), navigate({ urlType: 'page', url: 'about' })]
+[onClick(), runServerAction({ actionId: 'checkout', input: { id: '{{ list_rows.item.id }}' } })]
+[onClick(), when({ field: 'state.step', operator: '=', value: '2' }, setState({ … }))]
+[whileRunning('queue', onClick()), delay(1000), …]
+[named('picked', declaredTrigger(declaration, 'onPick')), …]; declaredCallback(declaration, 'reset', { on: 'seats' })
+```
+
+## The problems met most
+
+Each comes with its code in brackets; reference/authoring-errors.md has a row for every one — search it by code.
+
+| Code | Write instead |
+| --- | --- |
+| `class-and-css` | `class: [card, { … }]` with an `id`, or the rules in the class |
+| `id-taken` | ids are one namespace for the whole space, pages included: build a repeated helper inside `scope()` |
+| `unknown-attribute` | the attribute it lists; an event is a flow, not an attribute |
+| `children-in-leaf` | a `container` — a heading made of parts is `container({ subType: 'h1' })` |
+| `template-short-source` | the source in full in templates: `list_rows`, `apiContainer_p` |
+| `template-unknown-name` | a source, a variable, `navigation.queryParams.x` or `source` |
+| `template-text-into-value` | `{ returns: 'value' }` on a template feeding `items` |
+| `list-items-ignored` | `source: 'controlled'` |
+| `condition-starts-visible` | `visible: { source, template }`, which starts hidden |
+| `tablet-rule-skips-mobile` | the rule under `compact` |
+| `colour-without-dark` | `{ light, dark, default }` |
+| `click-on-static-element` | the flow on a `button` (it holds children) or a `link` |
+| `image-without-alt` / `control-without-name` | `alt` or `decorative: true`; `title` on an icon button |
+| `anchor-missing` | the `anchor` on the section the `hash` names |
+
+## Recipes
+
+Whole, authoring examples by intent — copy one, then change the names: see the Recipes table in SKILL.md.

package/skills/plitzi-authoring/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plitzi-authoring
 description: >-
-  Write or change a Plitzi space or template in TypeScript with @plitzi/sdk-authoring — pages, layouts, components,
+  Write or change a Plitzi space or snippet in TypeScript with @plitzi/sdk-authoring — pages, layouts, components,
   elements, CSS classes, data bindings, providers and flows — instead of hand-writing schema JSON. Use whenever the task is to
   create, extend, restyle or fix a space: adding a page or a section, sharing a header across pages, binding an
   element to data, showing or hiding something, wiring what happens on click, or turning an exported JSON into code.
@@ -27,10 +27,14 @@ export const space = {
 const { schema, style, warnings } = authorSpace(space);
 ```
 
-The published `.d.ts` is the reference for every factory, field and step builder
-(`node_modules/@plitzi/sdk-authoring/dist/index.d.ts`) — read it instead of guessing a name or a param. For one element
-type, the exported catalogues answer faster (`elementDefaultAttributes`, `elementTriggers`, `elementSlots`… — see
-[elements and styles](reference/elements-and-styles.md)).
+**Start with [the cheatsheet](CHEATSHEET.md)** — the factories, fields, steps and the problems met most, on one page —
+and open a reference below only when the task names its subject. What an element takes, a step's params, what a
+trigger hands its flow: `npx @plitzi/cli explain <name>` answers in a few lines (over MCP, `plitzi://explain/<name>`).
+The published `.d.ts` documents the rest — search it by name, never read it whole.
+
+This skill writes a space that lives in code. One that lives on Plitzi — edited in the builder, published from there —
+is edited through the Plitzi MCP server instead, never both on one space; `plitzi create --from <space>` turns the
+second into the first. If the MCP asks for a sign-in nobody can give, a project in code needs no account.
 
 ## How to work
 
@@ -41,8 +45,13 @@ type, the exported catalogues answer faster (`elementDefaultAttributes`, `elemen
    do exactly that. Never work around a check, cast past it, or move the logic into a plugin to escape it. The first
    refusals come one at a time; the linter's come as ONE list — fix every line of it before running again. How it
    checks, a one-file author script for any project, and what it cannot see: [validation](reference/validation.md).
-3. **Read every warning.** Each one names something written that will not do what it says. Zero warnings is the bar.
-4. **Look at it.** `npm run shot -- /about --width 390 --scheme dark` saves a picture of one page; `npm run visual`
+3. **Read every warning, then every suggestion.** A warning names something written that will not do what it says —
+   zero warnings is the bar. A suggestion (`[suggest]`, `suggestions` in `authorSpace`'s result) names a shorter way to
+   the same page: a layout for chrome on every page, a component or a `list` for copies, a button's own `content`. Take
+   them, the ones that save the most first. See [efficiency](reference/efficiency.md).
+4. **Look at it.** `npm run check -- /about --width 1440,390` says in text whether the page is whole — every element on
+   screen, nothing overflowing, a clean console; `npm run shot -- /about --width 390 --scheme dark` is the picture, for
+   when it says something is wrong (`--frames 4` shows what moves); `npm run visual`
    runs the checks. Look at desktop, tablet and mobile, light and dark, and the page while its data is still loading.
 5. **Go through the [review checklist](reference/review-checklist.md) before saying it is done.** It is the feedback a
    reviewer gives on every change, written down so you do not need to hear it.
@@ -50,22 +59,28 @@ type, the exported catalogues answer faster (`elementDefaultAttributes`, `elemen
 ## The rules that matter most
 
 1. **Name what is referred to.** Give an `id` to every element a binding, a flow or a test addresses. Ids are ONE
-   namespace for the whole space — layouts and every page share it — so an element built by a helper that runs more
-   than once gets its id prefixed by what it is for: `` `${pageId}-foot` ``.
+   namespace for the whole space — layouts and every page share it — so a helper that runs more than once builds inside
+   `scope('promos', ref => …)`: every id in it is prefixed (`promos-panel`), and `ref('slides')` names one in full. An `id` is the element's name in the
+   space (`data-id` in the page); the DOM id a URL's `#fragment` lands on is its `anchor`.
 2. **Share with classes, layouts and components, never with copies.** A look used twice is a `styles()` class.
    Chrome shown on several pages — a header, a sidebar, a footer — is a **layout** the pages name, written once. A block
    placed many times with different content — a product card, a testimonial — is a **component** placed with
-   `component(id, { props })`. A menu, a card grid, a list of steps is DATA mapped to elements
-   (`entries.map(entry => link(…))`), not a block pasted per item. See [layouts and duplication](reference/layouts.md)
-   and [components](reference/components.md).
+   `component(id, { props })`. A menu, a card grid, a list of steps is DATA, never a block pasted per item: a short
+   menu mapped in code (`entries.map(entry => link({ href, content: entry.title }))`) is fine; rows — cards, dishes,
+   tiles — are one `list` over them (`items: [ … ]`) whose row is written once. A link or a button says its words as
+   its own `content`, not through a `text` inside it. See [layouts and duplication](reference/layouts.md),
+   [components](reference/components.md) and [efficiency](reference/efficiency.md).
 3. **One element, one base selector.** An element takes a shared `class` OR its own `css`, never both — authoring
-   refuses the pair. A look that never changes is its own class.
+   refuses the pair. "This class plus one thing" is the class with rules on top, last in the list:
+   `class: [cover, { opacity: '0.25' }]` (needs the element's `id`; it becomes the class `<id>--own`). A look that
+   never changes is its own class.
 4. **Visible by default; decide which way the logic flips.** An element is on screen unless something hides it. When
    the logic REVEALS it (hidden → shown: an empty state, a "get started" card, an admin-only panel), it starts hidden —
    `visible: 'source'`, or `visible: false` plus a binding for a computed condition — so it never flashes while data
    loads (`condition-starts-visible` warns). When a flag HIDES it (shown → hidden: a sidebar label until the sidebar
    is folded), it keeps the default and an absent flag must leave it shown. See
-   [data and visibility](reference/data-and-visibility.md).
+   [data and visibility](reference/data-and-visibility.md). What a PERSON switches on — a feature in beta, a rollout —
+   is a feature flag, not a visibility: gated off, it is not rendered at all. See [feature flags](reference/feature-flags.md).
 5. **Know where a template is evaluated.** A binding's template (`bindTemplate`) and a step's params evaluate full
    Twig. An ATTRIBUTE resolves a name with filters (`{{ list_games.item.slug }}`, `{{ post.slug|url_encode }}`) against
    the sources around the element; a condition there is used as written. Inside any template a source is spelled in
@@ -95,82 +110,67 @@ type, the exported catalogues answer faster (`elementDefaultAttributes`, `elemen
     (`hideLabel: true` hides it and keeps the name), every image an `alt` or `decorative: true`. Clicks go on a
     `button` — it holds children, so a whole card can be one — or a `link`, never on a container. See
     [accessibility](reference/accessibility.md).
+14. **Motion that stays smooth.** Animate `opacity` and `transform` only; no animated blur, shadow or size. See
+    [motion](reference/colours-and-motion.md).
 
 ## Recipes
 
-Copy the one that fits, then change the names. Each is the shape `authorSpace` accepts on the first try.
+Each is a whole file that authors with no warning — CI holds it to that. Copy the one that fits, then change the names.
 
-```ts
-// Data with no backend: a JSON file the project serves (public/data/games.json), read by a provider.
-apiContainer({ id: 'catalog', query: '/data/games.json', cache: true, children: [ /* reads catalog.data.… */ ] })
-
-// A list of rows from that data. Inside a row: short form in bindings, full name in templates and attributes.
-list({ id: 'games', source: 'controlled', bind: { items: 'catalog.data.games' }, children: [
-  link({ mode: 'internal', href: '/games/{{ list_games.item.slug }}', children: [
-    text('', { bind: { content: 'games.item.title' } })
-  ] })
-] })
-
-// A filtered list: a template that hands over its VALUE.
-list({ id: 'shown', source: 'controlled',
-  bind: [bindTemplate('items', 'catalog.data.games', "{{ source|filter(g => g.genre == state.genre) }}", { returns: 'value' })],
-  children: [ … ] })
-
-// Text computed from data.
-text('', { bind: [bindTemplate('content', 'catalog.data.games', '{{ source|length }} games')] })
-
-// Shown only when a computed condition says so (starts hidden, no flash).
-text('Nothing here yet', { visible: { source: 'catalog.data.games', template: '{{ source is defined and source|length == 0 }}' } })
-
-// A value used in many places: declare it once in the space, read it anywhere as computed.xp.
-computed: { xp: '{{ (state.favourites|length) * 10 }}' }
-
-// A button that does something: a flow is [trigger, steps…].
-button({ content: 'Save', flows: [[onClick(), setState({ key: 'saved', type: 'boolean', value: true })]] })
-
-// A form: the flow goes on the form, which manages its own submit.
-form({ id: 'signup', managedByInteractions: true,
-  flows: [[named('sent', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ sent.values.email }}' })]],
-  children: [formControl({ name: 'email', label: 'Email', subType: 'email' }), button({ content: 'Sign up', subType: 'submit' })] })
-
-// A modal: hidden until a flow opens it.
-modalContainer({ id: 'details', visible: false, title: 'Details', children: [ … ] })
-button({ content: 'Open', flows: [[onClick(), openModal('details')]] })
-
-// A plugin: author it from its own declaration, flow on its events, call its actions — all checked.
-const seats = defineElement<SeatPickerAttributes>(declaration);
-seats({ id: 'seats', flows: [[named('picked', declaredTrigger(declaration, 'onPick')), setState({ key: 'seat', type: 'text', value: '{{ picked.seat }}' })]] })
-button({ content: 'Clear', flows: [[onClick(), declaredCallback(declaration, 'reset', { on: 'seats' })]] })
-authorSpace(space, { plugins: [declaration] })
-
-// Usable without sight: an icon-only button says what it does; a clickable card IS a button; a field keeps its label
-// out of sight rather than dropping it; a picture says what it shows, or that it only decorates.
-button({ content: '', title: 'Close', children: [fontAwesome({ icon: 'fa-solid fa-xmark' })], flows: [[onClick(), closeModal('details')]] })
-button({ content: '', class: card, children: [text('Pro'), text('12 € a month')], flows: [[onClick(), setState({ key: 'plan', type: 'text', value: 'pro' })]] })
-formControl({ name: 'q', label: 'Search the docs', hideLabel: true, placeholder: 'Search…' })
-image({ src: '/team.jpg', alt: 'The team at the 2026 offsite' }); image({ src: '/grain.png', decorative: true })
-
-// A link: to a page by its id, to a path with mode 'internal', to anything else with mode 'external'.
-link({ href: 'about' }); link({ href: '/games/nebula', mode: 'internal' }); link({ href: 'mailto:hi@x.com', mode: 'external' })
-```
+| To… | Open |
+| --- | --- |
+| Show data with no backend: a JSON file, a card per row, a count, an empty state, a computed value | [recipes/show-data.ts](recipes/show-data.ts) |
+| Data typed by a sample of it: completed and checked paths, typed rows | [recipes/typed-data.ts](recipes/typed-data.ts) |
+| Filter and sort a list from a select | [recipes/filter-a-list.ts](recipes/filter-a-list.ts) |
+| A page per record (`/products/:slug`), and "not found" | [recipes/detail-page.ts](recipes/detail-page.ts) |
+| Link to a section of a page (`/#plans`) | [recipes/link-to-a-section.ts](recipes/link-to-a-section.ts) |
+| A carousel: slides with arrows, dots and autoplay; a marquee; a row that swipes | [recipes/carousel.ts](recipes/carousel.ts) |
+| Do something every few seconds — a ticker, a poll, a slideshow by hand | [recipes/every-few-seconds.ts](recipes/every-few-seconds.ts) |
+| A marquee that scrolls for ever and stops under the pointer | [recipes/marquee.ts](recipes/marquee.ts) |
+| A row that scrolls sideways, with arrows that hide at its ends | [recipes/scroll-a-row.ts](recipes/scroll-a-row.ts) |
+| A link built from a row: WhatsApp with the product's name, `mailto:` | [recipes/link-with-data.ts](recipes/link-with-data.ts) |
+| React to a click or a submit; a modal; a switch | [recipes/forms-and-modals.ts](recipes/forms-and-modals.ts) |
+| A feature behind a flag | [recipes/feature-flag.ts](recipes/feature-flag.ts) |
+| An element of your own (a plugin), checked | [recipes/plugin.ts](recipes/plugin.ts) |
+| Controls a screen reader and a browser agent can use | [recipes/usable-without-sight.ts](recipes/usable-without-sight.ts) |
+| Tokens, a shared class, "the class plus one thing", tablet and phone at once | [recipes/style-a-page.ts](recipes/style-a-page.ts) |
+| A design in Tailwind classes, kept as classes the builder edits | [recipes/from-tailwind.ts](recipes/from-tailwind.ts) |
+| A page from elsewhere in a frame (`embed`: a map, a player) and a drawing of your own (`svg`) | [recipes/embed-and-svg.ts](recipes/embed-and-svg.ts) |
 
 ## References
 
 | Read | When |
 | --- | --- |
 | [elements-and-styles.md](reference/elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
+| [colours-and-motion.md](reference/colours-and-motion.md) | Colours for both themes, tokens, keyframes, and motion that stays smooth (good practices) |
+| [tailwind.md](reference/tailwind.md) | A design written in Tailwind classes: `tw()`, its breakpoints and states, what it refuses |
 | [layouts.md](reference/layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
+| [efficiency.md](reference/efficiency.md) | The same page with fewer elements: the suggestions `authorSpace` makes, and the short way for each long one |
 | [components.md](reference/components.md) | One block placed many times — a card, a tier, a testimonial: props, slots, binding a row into one, why it is closed |
 | [data-and-visibility.md](reference/data-and-visibility.md) | Bindings, providers, offline data, loading/empty/error states, live data, caching, showing and hiding, kept state |
-| [lists.md](reference/lists.md) | Rendering rows, filtering and sorting them, a detail page for one record |
+| [kept-state.md](reference/kept-state.md) | State that outlives a reload: `keepState`, transient and painted keys |
+| [feature-flags.md](reference/feature-flags.md) | Switching a part of the space on or off — a beta, a rollout, the old version kept until the new one ships |
+| [lists.md](reference/lists.md) | Rendering rows, filtering and sorting them, a detail page for one record, carousels |
+| [typed-sources.md](reference/typed-sources.md) | Data typed by a sample of it: `source()`, typed rows, `twig` for templates |
 | [validation.md](reference/validation.md) | How `authorSpace` checks, the loop that wastes no attempts, and what it cannot see |
 | [authoring-errors.md](reference/authoring-errors.md) | What `authorSpace` refuses or warns about, and what to write instead |
 | [templates.md](reference/templates.md) | Any `{{ … }}` or `{% … %}`: where it runs, naming sources, filters, tests, dates |
-| [flows.md](reference/flows.md) | Clicks, submits, page loads, server actions, realtime channels, modals, state |
+| [flows.md](reference/flows.md) | Clicks, submits, page loads, every few seconds, server actions, modals, state |
+| [realtime.md](reference/realtime.md) | Pages that see each other: channels, presence, cursors, a shared board, who may hear a topic |
 | [plugins.md](reference/plugins.md) | A component of your own: props, binding them, writing state, channels, registering, behaving in the builder |
 | [structure.md](reference/structure.md) | A space bigger than one screen: files, helpers, naming, keeping it short |
 | [testing.md](reference/testing.md) | Any test: `inspectPage` (one call, every problem), handles, fixtures, catching a flash from the first frame, shortcuts, counting renders |
 | [performance.md](reference/performance.md) | A page with many elements, a busy flow, something that feels slow: what renders, what it costs, how to measure it |
-| [templates-and-export.md](reference/templates-and-export.md) | Publishing a template; turning an exported JSON — or a server action — into code |
+| [snippets-and-export.md](reference/snippets-and-export.md) | Publishing a snippet; turning an exported JSON — or a server action — into code |
 | [accessibility.md](reference/accessibility.md) | Icon buttons, fields, images, clickable cards, toggles, headings, landmarks, a canvas — anything a screen reader or a browser agent has to use |
 | [review-checklist.md](reference/review-checklist.md) | Before you say it is done |
+
+**What to read for a kind of task** — the cheatsheet, then only these:
+
+- A site — landing, catalogue, blog: elements-and-styles, layouts, components, lists.
+- An app with state and actions: data-and-visibility, templates, flows — realtime when pages see each other.
+- A component of your own: plugins.
+- A refusal or a warning: search authoring-errors.md for its code — never read it whole.
+- Tests: testing.
+
+Nothing else needs reading up front.

package/skills/plitzi-authoring/recipes/carousel.ts

@@ -0,0 +1,114 @@
+/**
+ * Three carousels from one element: slides that change on their own with arrows and dots, a marquee of logos that
+ * never ends, and a row of cards a visitor swipes. The slides, the dots and anything else inside read the carousel's
+ * source — `carousel_<id>.index`, `.count`, `.item`, `.items` — and the arrows and dots are steps on it.
+ */
+import {
+  activeWhen,
+  bindTemplate,
+  button,
+  carousel,
+  carouselGoTo,
+  carouselNext,
+  carouselPrevious,
+  container,
+  heading,
+  list,
+  onClick,
+  styles,
+  text
+} from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const SLIDES = [
+  { id: 'one', title: 'Lamps', lede: 'Warm light for long evenings' },
+  { id: 'two', title: 'Paper', lede: 'Notebooks that lie flat' },
+  { id: 'three', title: 'Pens', lede: 'Six colours, quick to dry' }
+];
+
+const slide = styles('hero-slide', { padding: '64px 32px', backgroundColor: 'var(--card)', borderRadius: '16px' });
+
+const dot = styles('hero-dot', {
+  css: { width: 10, height: 10, padding: '0px', borderRadius: '999px', backgroundColor: 'var(--muted)' },
+  variants: { active: { backgroundColor: 'var(--primary)' } }
+});
+
+const dots = styles('hero-dots', { display: 'flex', gap: 8, margin: '0px', padding: '0px', listStyleType: 'none' });
+
+// Several slides at once: the carousel's class says how wide each is and the gap between them.
+const cards = styles('picks-row', { '--plitzi-carousel-slide-width': '240px', '--plitzi-carousel-gap': '16px' });
+
+export const recipe: SpaceSpec = {
+  name: 'Carousels',
+  permanentUrl: 'carousels',
+  variables: {
+    color: {
+      card: { light: '#f4f4f8', dark: '#1c1c22', default: '#f4f4f8' },
+      muted: { light: '#c4c4cc', dark: '#3a3a44', default: '#c4c4cc' },
+      primary: { light: '#4f46e5', dark: '#818cf8', default: '#4f46e5' }
+    }
+  },
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        // One slide at a time, on its own every 5 s — held while the pointer or the keyboard is on it.
+        carousel({
+          id: 'hero',
+          label: 'Featured',
+          items: SLIDES,
+          autoplay: 5000,
+          row: r =>
+            container({
+              class: slide,
+              children: [heading({ subType: 'h2', from: `${r.item}.title` }), text({ from: `${r.item}.lede` })]
+            }),
+          children: [
+            button({ content: '‹', title: 'Previous slide', flows: [[onClick(), carouselPrevious('hero')]] }),
+            button({ content: '›', title: 'Next slide', flows: [[onClick(), carouselNext('hero')]] }),
+            list({
+              id: 'hero-dots',
+              class: dots,
+              items: 'hero.items',
+              row: r =>
+                button({
+                  content: '',
+                  class: dot,
+                  bind: [
+                    bindTemplate('title', r.index, 'Slide {{ source + 1 }}'),
+                    activeWhen(dot, `{{ ${r.inTemplate.index} == carousel_hero.index }}`)
+                  ],
+                  flows: [[onClick(), carouselGoTo('hero', `{{ ${r.inTemplate.index} }}`)]]
+                })
+            })
+          ]
+        }),
+        // Scrolling past for ever at 40 px a second, still under the pointer.
+        carousel({
+          id: 'logos',
+          label: 'Brands we carry',
+          mode: 'marquee',
+          speed: 40,
+          items: ['Acme', 'Globex', 'Initech', 'Umbrella', 'Hooli'],
+          row: r => text({ from: r.item, css: { padding: '0px 24px', fontWeight: 600 } })
+        }),
+        // A row that swipes on a phone and snaps to each card; the arrows move it a card at a time.
+        carousel({
+          id: 'picks',
+          label: 'Picks',
+          mode: 'scroll',
+          class: cards,
+          items: SLIDES,
+          row: r => container({ class: slide, children: [text({ from: `${r.item}.title` })] }),
+          children: [
+            button({ content: '›', title: 'More picks', flows: [[onClick(), carouselNext('picks')]] }),
+            text({ from: 'picks.index', as: '{{ source + 1 }} of {{ carousel_picks.count }}' })
+          ]
+        })
+      ]
+    }
+  ]
+};