@plitzi/sdk-server 0.38.6 → 0.38.8

package/dist/modules/rsc/connectorRscData.js

@@ -1,6 +1,6 @@
 import { createActionResolver } from "../actions/runtime/renderResolver.js";
 import { createConnectorResolver } from "../connectors/resolver.js";
-import { dataFileResolver, dataLookupResolver, publicFileResolver } from "./publicFileResolver.js";
+import { dataLookupResolver, publicFileResolver } from "./publicFileResolver.js";
 import { resolveRscData } from "./resolveRscData.js";
 //#region src/modules/rsc/connectorRscData.ts
 /**
@@ -18,12 +18,11 @@ import { resolveRscData } from "./resolveRscData.js";
 *
 * A deployment that resolves server elements some other way still supplies its own `getRscData`, and that one wins.
 */
-var connectorRscData = ({ connectors, actions, publicDir, dataDir, elementTimeoutMs }) => {
+var connectorRscData = ({ connectors, actions, publicDir, data, elementTimeoutMs }) => {
 	const resolveConnector = connectors ? createConnectorResolver(connectors) : void 0;
 	const resolveAction = actions ? createActionResolver(actions.lookups, actions.module) : void 0;
 	const resolvePublicFile = publicDir ? publicFileResolver(publicDir) : void 0;
-	const dataLookup = actions?.lookups.getData;
-	const resolveDataFile = dataDir ? dataFileResolver(dataDir) : dataLookup ? dataLookupResolver((spaceId, at) => dataLookup(spaceId, at)) : void 0;
+	const resolveDataFile = data ? dataLookupResolver(data) : void 0;
 	/**
 	* An element names ONE producer, and which one decides how its data is fetched.
 	*

package/dist/modules/rsc/handler.d.ts

@@ -14,6 +14,7 @@ export declare const withPageLocation: (req: SSRRequest) => SSRRequest;
  * - main environment: no-store (development, always fresh)
  * - Authenticated requests: Cache-Control: private, max-age=<ttl>
  * - Unauthenticated requests: Cache-Control: public, max-age=<ttl>
+ * - A request carrying `Cache-Control: no-cache` is resolved again, and its answer replaces the one cached.
  */
 export declare const handleRsc: (req: SSRRequest, res: SSRResponseHelpers, config: SSRPageServerConfig, _pluginManager: PluginManager, cache?: TtlCache<string>, 
 /** The request's own: a browser that stops waiting stops the elements it asked about. */

package/dist/modules/rsc/handler.js

@@ -22,6 +22,15 @@ var meterRsc = async (req, config, spaceId, environment, revision, cached) => {
 		});
 	} catch {}
 };
+/**
+* Whether the browser asked for the server's answer as of now — a refresh that exists because something changed (a
+* write, an explicit reload), which the answer kept for the last `cacheTtlMs` would undo.
+*
+* It skips reading the cache, never writing it: the answer it gets is the newest there is, and the next visitor is
+* served it. Nobody gains anything they could not already have by changing the query string, which misses the cache
+* as well.
+*/
+var asksFresh = (req) => (req.headers["cache-control"] ?? "").split(",").some((directive) => directive.trim().toLowerCase() === "no-cache");
 /** The endpoint's own parameters: what it is asked about, never input to what it resolves. */
 var ENDPOINT_PARAMS = /* @__PURE__ */ new Set(["location", "ids"]);
 /**
@@ -70,6 +79,7 @@ var withPageLocation = (req) => {
 * - main environment: no-store (development, always fresh)
 * - Authenticated requests: Cache-Control: private, max-age=<ttl>
 * - Unauthenticated requests: Cache-Control: public, max-age=<ttl>
+* - A request carrying `Cache-Control: no-cache` is resolved again, and its answer replaces the one cached.
 */
 var handleRsc = async (req, res, config, _pluginManager, cache, signal) => {
 	if (!config.adapters.getRscData) {
@@ -110,7 +120,7 @@ var handleRsc = async (req, res, config, _pluginManager, cache, signal) => {
 	const isAuthenticated = !!req.ctx.user;
 	const cacheControl = environment === "main" || uncached ? "no-store" : isAuthenticated ? `private, max-age=${Math.floor(ttlMs / 1e3)}` : `public, max-age=${Math.floor(ttlMs / 1e3)}`;
 	const cacheKey = environment !== "main" && !uncached ? buildRscCacheKey(spaceId, environment, revision, req.ctx.user?.id, idsParam, req) : void 0;
-	const cached = cacheKey ? cache?.get(cacheKey) : void 0;
+	const cached = cacheKey && !asksFresh(req) ? cache?.get(cacheKey) : void 0;
 	if (!previewing) await meterRsc(req, config, spaceId, environment, revision, !!cached);
 	if (cached) {
 		res.setHeader("Content-Type", "application/json; charset=utf-8");

package/dist/modules/rsc/publicFileResolver.d.ts

@@ -7,13 +7,9 @@ import { SpaceRevision } from '@plitzi/sdk-shared';
  */
 export declare const publicFileResolver: (publicDir: string) => RscElementResolver;
 /**
- * A server provider whose `query` is `/data/<file>`, read from `dataDir` — the project's own data, which is never
- * served as a file: nobody downloads the folder. What the provider reads is in the page it renders.
- */
-export declare const dataFileResolver: (dataDir: string) => RscElementResolver;
-/**
- * A server provider whose `query` is `/data/<file>`, answered from the space's own data as Plitzi keeps it — of the
- * version being rendered, read off the same deployment record an action's run is (`req.ctx.spaceDeployment`), so a
- * published page reads the data it was published with. What `dataFileResolver` is for a folder, for a platform.
+ * A server provider whose `query` is `/data/<file>`, answered from the space's own data — of the version being
+ * rendered, read off the same deployment record an action's run is (`req.ctx.spaceDeployment`), so a published page
+ * reads the data it was published with. The lookup is the platform's, or a self-hosted server's `dataDir`
+ * (`dataDirLookup`): the data is never served as a file, and what the provider reads is in the page it renders.
  */
 export declare const dataLookupResolver: (getData: (spaceId: number, at: SpaceRevision) => Promise<Record<string, string> | undefined>) => RscElementResolver;

package/dist/modules/rsc/publicFileResolver.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { readFile } from "node:fs/promises";
+import path from "node:path";
 import { PROJECT_DATA_PREFIX } from "@plitzi/sdk-shared/server/rsc/projectData";
 //#region src/modules/rsc/publicFileResolver.ts
 /** Where a provider's `query` is a path: a URL, a protocol-relative one or one with `{{tokens}}` is not. */
@@ -44,14 +44,10 @@ var fileResolver = (folder, prefix) => {
 */
 var publicFileResolver = (publicDir) => fileResolver(publicDir, "/");
 /**
-* A server provider whose `query` is `/data/<file>`, read from `dataDir` — the project's own data, which is never
-* served as a file: nobody downloads the folder. What the provider reads is in the page it renders.
-*/
-var dataFileResolver = (dataDir) => fileResolver(dataDir, PROJECT_DATA_PREFIX);
-/**
-* A server provider whose `query` is `/data/<file>`, answered from the space's own data as Plitzi keeps it — of the
-* version being rendered, read off the same deployment record an action's run is (`req.ctx.spaceDeployment`), so a
-* published page reads the data it was published with. What `dataFileResolver` is for a folder, for a platform.
+* A server provider whose `query` is `/data/<file>`, answered from the space's own data — of the version being
+* rendered, read off the same deployment record an action's run is (`req.ctx.spaceDeployment`), so a published page
+* reads the data it was published with. The lookup is the platform's, or a self-hosted server's `dataDir`
+* (`dataDirLookup`): the data is never served as a file, and what the provider reads is in the page it renders.
 */
 var dataLookupResolver = (getData) => {
 	return async ({ element, spaceId, environment, req }) => {
@@ -74,4 +70,4 @@ var dataLookupResolver = (getData) => {
 	};
 };
 //#endregion
-export { dataFileResolver, dataLookupResolver, publicFileResolver };
+export { dataLookupResolver, publicFileResolver };

package/dist/modules/runtime/bundle.d.ts

@@ -19,7 +19,7 @@ export declare const inspectRuntime: (bytes: Uint8Array) => {
 };
 /**
  * A project's runtime module, as a server of its own runs it — `src/runtime/index.ts`, or what `build` compiled it to —
- * or nothing when the project has none: a project starts one by writing it (`plitzi add runtime`), with nothing to wire.
+ * or nothing when the project has none: a project starts one by writing it (`plitzi runtime add`), with nothing to wire.
  */
 export declare const loadRuntimeModule: (file: string) => Promise<SpaceRuntime | undefined>;
 /**

package/dist/modules/runtime/bundle.js

@@ -1,8 +1,8 @@
 import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
 import path from "node:path";
 import esbuild from "esbuild";
-import fs from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { gunzipSync, gzipSync } from "node:zlib";
 //#region src/modules/runtime/bundle.ts
@@ -93,7 +93,7 @@ var runtimeOf = (loaded) => {
 };
 /**
 * A project's runtime module, as a server of its own runs it — `src/runtime/index.ts`, or what `build` compiled it to —
-* or nothing when the project has none: a project starts one by writing it (`plitzi add runtime`), with nothing to wire.
+* or nothing when the project has none: a project starts one by writing it (`plitzi runtime add`), with nothing to wire.
 */
 var loadRuntimeModule = async (file) => {
 	try {

package/dist/modules/ssr/prepareRender.js

@@ -14,6 +14,7 @@ import { publishSpaceDocument } from "./spaceDocument.js";
 import { registerExternalPlugins } from "./registerExternalPlugins.js";
 import { reportMissingPlugins } from "./reportMissingPlugins.js";
 import { resolvePageSeo } from "./resolvePageSeo.js";
+import { SPACE_TOKEN_PARAM } from "../../core/auth/credentials.js";
 import { imagesPathOf } from "../../core/http/stages/images.js";
 import { sdkAssetVersion } from "../../core/sdkAssets.js";
 import { buildServerInfo } from "../../helpers/buildServerInfo.js";
@@ -165,7 +166,14 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	* Not for a draft, which no other process could produce when the fetch reaches it, and not for a deployment's own
 	* template, which was written for the space inline; a page with no script needs no space at all.
 	*/
-	const spaceDocumentPath = offlineData !== void 0 && offlineDataOverride === void 0 && config.templateFn === void 0 && config.ssrOnly !== true ? publishSpaceDocument(spaceId, environment, spaceDocument(offlineData)) : void 0;
+	const publishedDocument = offlineData !== void 0 && offlineDataOverride === void 0 && config.templateFn === void 0 && config.ssrOnly !== true ? publishSpaceDocument(spaceId, environment, spaceDocument(offlineData)) : void 0;
+	/**
+	* A page that named its space with a token in its address (`?access-token=`, how a host serving many spaces is asked
+	* for one) has its document asked for the same way: fetched bare, the host's own space answered it — another space's
+	* document, hydrated over this one's page.
+	*/
+	const spaceToken = req.query[SPACE_TOKEN_PARAM];
+	const spaceDocumentPath = publishedDocument && spaceToken ? `${publishedDocument}?${SPACE_TOKEN_PARAM}=${encodeURIComponent(spaceToken)}` : publishedDocument;
 	const offlineDataStr = hydrationPayload(offlineData, {
 		offlineMode: true,
 		environment,
@@ -221,7 +229,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			...deferred ? { deferred } : {}
 		};
 	});
-	const vendorJs = (debugAuthorized ? "/sdk-assets/plitzi-sdk-dev-vendor.js" : "/sdk-assets/plitzi-sdk-vendor.js") + v;
+	const vendorJs = (debugRendered ? "/sdk-assets/plitzi-sdk-dev-vendor.js" : "/sdk-assets/plitzi-sdk-vendor.js") + v;
 	return {
 		componentProps: {
 			plugins: Object.keys(pluginComponents).length > 0 ? pluginComponents : void 0,

package/dist/modules/ssr/registerExternalPlugins.js

@@ -2,8 +2,8 @@ import { serverLog } from "../../helpers/serverLog.js";
 import { fetchOutbound } from "../../helpers/outboundGuard.js";
 import { writeFileAtomic } from "../../helpers/atomicFile.js";
 import crypto from "node:crypto";
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
 //#region src/modules/ssr/registerExternalPlugins.ts
 var MANIFEST_TTL_MS = 6e5;
 var manifestCache = /* @__PURE__ */ new Map();

package/dist/modules/ssr/vendor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/ssr/views/template.ejs

@@ -77,9 +77,10 @@
     <% } %>
 
     <% if (!locals.ssrOnly) { %>
-    <link rel="modulepreload" href="<%= locals.react || '' %>" crossorigin />
-    <link rel="modulepreload" href="<%= locals.reactDom || '' %>" crossorigin />
-
+    <%#
+      The import map before anything that loads a module: a browser that fetched one already (a modulepreload counts)
+      ignores a map that comes after it, and the SDK's `import "react"` then resolves to nothing.
+    %>
     <script type="importmap">
       {
         "imports": {
@@ -92,6 +93,9 @@
         }
       }
     </script>
+
+    <link rel="modulepreload" href="<%= locals.react || '' %>" crossorigin />
+    <link rel="modulepreload" href="<%= locals.reactDom || '' %>" crossorigin />
     <% } %>
 
     <%# The space, fetched beside the page while the scripts load, rather than carried in it. %>

package/dist/plugins/compile.js

@@ -1,7 +1,7 @@
 import { writeFileAtomic } from "../helpers/atomicFile.js";
+import fs from "node:fs/promises";
 import path from "node:path";
 import esbuild from "esbuild";
-import fs from "node:fs/promises";
 import { pluginAssetLoaders, pluginImportQueries } from "@plitzi/sdk-shared/plugins/bundle";
 import { inPluginLayer } from "@plitzi/sdk-shared/style/cssLayers";
 //#region src/plugins/compile.ts

package/dist/plugins/copy.js

@@ -1,6 +1,6 @@
 import { copyFileAtomic, writeFileAtomic } from "../helpers/atomicFile.js";
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { inPluginLayer } from "@plitzi/sdk-shared/style/cssLayers";
 //#region src/plugins/copy.ts
 var copyPlugin = async (src, destDir, filename) => {

package/dist/plugins/manager.js

@@ -5,8 +5,8 @@ import { copyPlugin, copyPluginStylesheet } from "./copy.js";
 import { detectAction, isComponentSource } from "./detect.js";
 import { assertPluginSources } from "./validate.js";
 import { createHash } from "node:crypto";
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
 //#region src/plugins/manager.ts
 var META_FILE = "meta.json";
 var DEFAULT_TTL_MS = 6048e5;

package/dist/project.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The server of a project `@plitzi/cli` writes: its `src/main.ts` hands `serveProject` the space, its actions and its
+ * options, and the rest — the port, the plugins, the functions, the runtime, the files, the reloads while developing —
+ * comes from where the project keeps each part (`@plitzi/sdk-shared/project/paths`). A fix to it arrives with the
+ * package, never as a file to upgrade.
+ */
+export { serveProject } from './modules/project/serveProject';
+export type { ProjectServerOptions, ProjectSpace, ServedProject, ServeProjectOptions } from './modules/project/serveProject';
+export type { AuthoredDocuments } from './modules/project/watchSpace';

package/dist/project.js

@@ -0,0 +1,2 @@
+import { serveProject } from "./modules/project/serveProject.js";
+export { serveProject };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.6",
+  "version": "0.38.8",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -75,6 +75,16 @@
       "import": "./dist/runtime.js",
       "default": "./dist/runtime.js"
     },
+    "./project": {
+      "types": "./dist/project.d.ts",
+      "import": "./dist/project.js",
+      "default": "./dist/project.js"
+    },
+    "./env": {
+      "types": "./dist/env.d.ts",
+      "import": "./dist/env.js",
+      "default": "./dist/env.js"
+    },
     "./functions-api.d.ts": "./dist/functions-api.d.ts"
   },
   "repository": {
@@ -82,10 +92,12 @@
     "url": "https://github.com/plitzi/plitzi-workspace.git"
   },
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/env.js"
+  ],
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.6",
-    "@plitzi/sdk-shared": "0.38.6",
+    "@plitzi/plitzi-sdk": "0.38.8",
+    "@plitzi/sdk-shared": "0.38.8",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -13,7 +13,7 @@ const space: SpaceSpec = {
   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
+  keyframes: { blink: { '50%': { opacity: 0 } } },   // a class plays them: animation: 'blink 1s infinite'
   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
@@ -81,7 +81,7 @@ bind: { alt: 'p.data.title' }                                  // other attribut
 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
+current: 'section'                                             // a link lit on its page and the pages under it
 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 }}' }

package/skills/plitzi-authoring/SKILL.md

@@ -9,173 +9,59 @@ description: >-
 
 # Authoring Plitzi spaces
 
-A space is two JSON documents — a schema and a style — full of cross-referenced ids. **Never write them by hand.**
-`@plitzi/sdk-authoring` derives every id, class name, parent link, breakpoint map and flow chain from a small
-declaration, and refuses a declaration that would not render.
+A space is two JSON documents full of cross-referenced ids — **never write them by hand**. `@plitzi/sdk-authoring`
+derives them from a small declaration, and refuses one that would not render.
 
 ```ts
-import { authorSpace, container, heading, styles, text } from '@plitzi/sdk-authoring';
+import { heading, styles, text } from '@plitzi/sdk-authoring';
 
-const page = styles('page', { display: 'flex', 'flex-direction': 'column', padding: '96px 24px', gap: '16px' });
+const page = styles('page', { display: 'flex', 'flex-direction': 'column', gap: '16px' });
 
 export const space = {
   name: 'My space',
   permanentUrl: 'my-space',
   pages: [{ name: 'Home', slug: '', class: page, body: [heading('Hello', { subType: 'h1' }), text('A paragraph.')] }]
 };
-
-const { schema, style, warnings } = authorSpace(space);
 ```
 
-**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.
+A space on Plitzi — edited in the builder — is edited through the Plitzi MCP server instead, never both on one space.
 
 ## How to work
 
-1. **Read before you write.** Open `src/space/index.ts` (and whatever it imports) and find the layout, the classes and the
-   helpers already there. Extend them; do not add a second way of doing something the space already does.
-2. **Change the declaration, then author it.** `npm run author` (or a restart) runs `authorSpace` — not `doctor`, which
-   is the project's. It checks every field, value, template, name, param and page link, and a refusal says what to
-   write instead: do exactly that. Never work around a check, cast past it, or move the logic into a plugin to escape
-   it. The linter's problems come as ONE list — fix every line before running again. How it checks, and what it
-   cannot see: [validation](reference/validation.md).
-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]`) names a shorter way to the same page — a layout, a component,
-   a `list`, a button's own `content` — or what nothing uses. Take them, the ones that save the most first
-   ([efficiency](reference/efficiency.md)). Then `npm run lint:space`: how the source is written — long files, rows of
-   data inline, colours that are not tokens — at file:line. Leave both clean.
-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
-   (`--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.
+1. **Find, then write.** `npx plitzi element where <id|class|words>` answers the file, the line and the call: edit there, and
+   extend what the space already has. People move files — never keep a note of where something is.
+2. **Author.** `npm run author`. A refusal says what to write instead: do exactly that. Every problem comes at once —
+   fix them all before running again. Zero warnings; take the suggestions, the biggest first.
+3. **Look.** `npm run check -- /path --width 1440,390` says in text whether the page is whole; `npm run shot` only
+   when the text is not enough.
+4. **Before saying done:** `npm run lint:space` clean, and the [review checklist](reference/review-checklist.md).
 
-## The rules that matter most
+What a name means — an element, a step, a trigger, a code, any export (`pageFamily`, `SpaceSpec`): `npx plitzi explain
+<name>`, in a few lines. Never read the `.d.ts`.
 
-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 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-plitzi-el` 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, never a block pasted per item: a short
-   menu mapped in code is fine; rows — cards, dishes, tiles — are one `list` (`items: [ … ]`) whose row is written
-   once. A link or a button says its words as
-   its own `content`, not through a `text` inside it. Pages of one shape are one `pageFamily` over data. See
-   [layouts](reference/layouts.md), [components](reference/components.md), [structure](reference/structure.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. "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). 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
-   full — `apiContainer_stats`, `list_rows` — and a query param is `navigation.queryParams.x`. A template that feeds a
-   list its `items` hands over its value (`returns: 'value'`). `authorSpace` refuses a template it cannot read and a
-   name nothing answers to. See [templates](reference/templates.md).
-6. **Tokens, not colours.** Every colour is a variable of the space with a `light` and a `dark` value; both themes are
-   checked from the first commit.
-7. **Times in UTC, and say so.** Format with an explicit zone (`|date('j M · H:i', 'UTC')`) and print "UTC" beside it:
-   a page rendered on a server and hydrated in a browser in another zone must agree on the hour.
-8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (up to 48rem) each inherit only from `desktop`; a rule
-   meant for both is written under `compact`.
-9. **Never invent data.** Numbers, names and states on screen come from a source. A panel with nothing true to say is
-   an empty state, not a placeholder figure. With no backend, the data is JSON read by an `apiContainer`: a server
-   project's `src/data/*.json`, read on the server and never served; with no server, `public/data/*.json`, which is
-   public — see [data and visibility](reference/data-and-visibility.md).
-10. **Never hand-write** `flat`, derived ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`, or a
-    `styleVariant` binding's key — use the factories, `variantFrom` and `activeOn`.
-11. **A switch is named for how it leaves its default.** `toggleState` turns a key nobody has set yet ON, so a key
-    named for the default (`showPlates`, on by default) takes a first click to do nothing: name it `platesOff`, and read
-    every switch through `computed` (`plates: '{{ state.platesOff ? false : true }}'`) so its default shows before
-    anybody touches it.
-12. **Hand plugins over as their declarations**: `authorSpace(space, { plugins: [declaration] })` holds a plugin —
-    its own type, or a `custom({ renderType })` host — to the events, actions and attributes it declares. See
-    [plugins](reference/plugins.md).
-13. **Usable without sight.** Screen readers and browser agents (Claude in Chrome) find a page's controls in its
-    accessibility tree: every button and link has words (an icon-only button a `title`), every field a `label`
-    (`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).
+## Five rules authoring cannot check for you
 
-## Recipes
+1. **Name what is referred to.** An `id` for every element a binding, a flow or a test addresses; ids are one namespace,
+   so a helper that runs twice builds inside `scope('promos', ref => …)`.
+2. **Share, never copy.** A look used twice is a class; chrome on several pages a layout; a block placed again with
+   other content a component; rows of data one `list`.
+3. **What is revealed starts hidden** (`visible: 'source'`), so it never flashes while its data loads.
+4. **Know where a template runs.** A binding and a step's params are full Twig; an attribute resolves a name with
+   filters. A source is spelled in full: `apiContainer_stats`.
+5. **Tokens, not colours** — a variable with a `light` and a `dark` value.
 
-Each is a whole file that authors with no warning — CI holds it to that. Copy the one that fits, then change the names.
+The rest, and why: [rules](reference/rules.md).
 
-| 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) |
-| Data read by the page server (`--mode server`) | [recipes/server-data.ts](recipes/server-data.ts) |
-| An accordion, one answer open at a time | [recipes/accordion.ts](recipes/accordion.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) |
+## What to read
 
-## References
+Start with [the cheatsheet](CHEATSHEET.md), then only what the task names:
 
-| Read | When |
+| The task | Read |
 | --- | --- |
-| [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 |
-| [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, 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 |
-| [drawing.md](reference/drawing.md) | A plugin that draws or animates: a canvas sized to the device, WebGL shaders that say why they failed, a loop that stops when nobody sees it |
-| [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 |
-| [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.
+| A site — landing, catalogue, blog | [elements-and-styles](reference/elements-and-styles.md), [layouts](reference/layouts.md), [components](reference/components.md), [lists](reference/lists.md) |
+| An app with state and actions | [data-and-visibility](reference/data-and-visibility.md), [templates](reference/templates.md), [flows](reference/flows.md) |
+| A component of your own | [plugins](reference/plugins.md) |
+| A whole working file to copy | [recipes](reference/recipes.md) |
+| A refusal or a warning | `npx plitzi explain <code>` |
+| Tests | [testing](reference/testing.md) |
+| Anything else | [the index](reference/index.md): every reference, and when |

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

@@ -1,5 +1,5 @@
 /**
- * An element of your own (a plugin): authored from its declaration — the one `plitzi add plugin` writes — so a flow on
+ * An element of your own (a plugin): authored from its declaration — the one `plitzi plugin add` writes — so a flow on
  * its events, a step to its actions and its attributes are all checked. Hand the declaration to `authorSpace` too.
  */
 import {

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

@@ -27,8 +27,8 @@ formControl({ name: 'q', label: 'Search the docs', hideLabel: true, placeholder:
 formControl({ name: 'tint', subType: 'color', label: 'Highlight colour', hideLabel: true })
 ```
 
-A `placeholder` names only a field you type into, and only until something is typed. A swatch, a date, a select or a
-checkbox always needs its `label`.
+A `placeholder` names only a field you type into, and only until something is typed. A swatch, a date, a select, a
+checkbox or a switch always needs its `label`.
 
 ## Pictures say what they show, or that they only decorate
 
@@ -111,5 +111,4 @@ can't click something that only appears on focus.
 - `authorSpace` warnings: zero, as always.
 - In a test, `page.getByRole('button', { name: 'Close' })` fails when the name is missing.
   `expect(locator).toMatchAriaSnapshot(…)` pins the whole outline.
-- Through MCP, `plitzi_screenshot` with `view: "accessibility"` returns the page's tree and lists everything that has
-  no name.
+- Through MCP, `plitzi_look` returns the page's tree (its default view) and lists everything that has no name.