@plitzi/sdk-server 0.38.5 → 0.38.7

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.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

package/dist/modules/ssr/Component.d.ts

@@ -8,6 +8,7 @@ export type ComponentProps = {
     plugins?: Record<string, SSRPlugin>;
     ssrResult?: SSRRenderResult;
     sdkDevToolsStylePath?: string;
+    sdkIconsStylePath?: string;
     debugMode?: boolean;
     /** Set when the metering adapter degrades this render: the account behind this space is over its quota. */
     overQuota?: boolean;
@@ -20,5 +21,5 @@ export type ComponentProps = {
     /** The flags a tester forced, for a page allowed to debug. See `prepareRender`. */
     forcedFlags?: Record<string, boolean>;
 };
-declare const Component: ({ server, renderMode, previewMode, offlineData, environment, plugins, ssrResult, sdkDevToolsStylePath, debugMode, overQuota, theme, state, serverFlags, forcedFlags }: ComponentProps) => import('react').JSX.Element;
+declare const Component: ({ server, renderMode, previewMode, offlineData, environment, plugins, ssrResult, sdkDevToolsStylePath, sdkIconsStylePath, debugMode, overQuota, theme, state, serverFlags, forcedFlags }: ComponentProps) => import('react').JSX.Element;
 export default Component;

package/dist/modules/ssr/Component.js

@@ -1,7 +1,7 @@
 import PlitziSdk from "@plitzi/plitzi-sdk";
 import { jsx } from "react/jsx-runtime";
 //#region src/modules/ssr/Component.tsx
-var Component = ({ server, renderMode = "raw", previewMode = true, offlineData, environment = "main", plugins, ssrResult, sdkDevToolsStylePath, debugMode = false, overQuota, theme, state, serverFlags, forcedFlags }) => {
+var Component = ({ server, renderMode = "raw", previewMode = true, offlineData, environment = "main", plugins, ssrResult, sdkDevToolsStylePath, sdkIconsStylePath, debugMode = false, overQuota, theme, state, serverFlags, forcedFlags }) => {
 	const serverWithResult = {
 		...server,
 		ssr: {
@@ -17,6 +17,7 @@ var Component = ({ server, renderMode = "raw", previewMode = true, offlineData,
 		offlineMode: !!offlineData && Object.keys(offlineData).length > 0,
 		offlineData,
 		sdkDevToolsStylePath,
+		sdkIconsStylePath,
 		debugMode,
 		...overQuota === void 0 ? {} : { overQuota },
 		...theme === void 0 ? {} : { theme },

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";
@@ -95,6 +96,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	const version = config.assetVersion ?? sdkAssetVersion();
 	const v = version ? `?v=${version}` : "";
 	const sdkDevToolsStylePath = `/sdk-assets/plitzi-sdk-devtools.css${v}`;
+	const sdkIconsStylePath = `/sdk-assets/plitzi-sdk-icons.css${v}`;
 	/**
 	* Two facts, and they have to leave this server separately.
 	*
@@ -164,13 +166,21 @@ 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,
 		renderMode: "raw",
 		server,
 		sdkDevToolsStylePath,
+		sdkIconsStylePath,
 		...theme ? { theme } : {},
 		...paintedState ? { state: paintedState } : {},
 		...clientAnalytics ? { analytics: clientAnalytics } : {},
@@ -219,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,
@@ -228,6 +238,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			environment: req.ctx.spaceDeployment?.environment ?? environment,
 			debugMode: debugRendered,
 			sdkDevToolsStylePath,
+			sdkIconsStylePath,
 			overQuota,
 			theme,
 			...paintedState ? { state: paintedState } : {},
@@ -239,7 +250,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			title: DEFAULT_TITLE,
 			jsPath: `/sdk-assets/plitzi-sdk.js${v}`,
 			cssPath: `/sdk-assets/plitzi-sdk.css${v}`,
-			iconsCssPath: `/sdk-assets/plitzi-sdk-icons.css${v}`,
+			iconsCssPath: sdkIconsStylePath,
 			spaceDocumentPath,
 			react: vendorJs,
 			reactJsx: vendorJs,

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.5",
+  "version": "0.38.7",
   "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.5",
-    "@plitzi/sdk-shared": "0.38.5",
+    "@plitzi/plitzi-sdk": "0.38.7",
+    "@plitzi/sdk-shared": "0.38.7",
     "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

@@ -153,6 +153,7 @@ Each is a whole file that authors with no warning — CI holds it to that. Copy
 | [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 |
+| [auth.md](reference/auth.md) | Signing people in: providers, `authLogin`, `auth.*`, visitor roles |
 | [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 |
@@ -162,9 +163,9 @@ Each is a whole file that authors with no warning — CI holds it to that. Copy
 | [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 |
+| [drawing.md](reference/drawing.md) | A plugin that draws or animates: a canvas sized to the device, WebGL, a loop that stops when unseen |
 | [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 |
+| [testing.md](reference/testing.md) | Any test: `inspectPage`, 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 |

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
 

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

@@ -0,0 +1,75 @@
+# Signing people in
+
+## Where they sign in
+
+A page signs in with one provider: the space's `settings.userProvider`, or — when it declares none — the one the server
+that rendered it serves.
+
+| The space runs… | Declare |
+| --- | --- |
+| on the Plitzi platform, visitors signing in with their Plitzi account | `userProvider: 'server'` — and `visitorRoles` |
+| on a self-hosted server with `auth` (`createServer({ auth })`; in a project, `src/config/serverOptions.ts`) | nothing: the server tells its pages where they sign in |
+| against an API of your own over HTTP+JSON | `userProvider: 'basic'`, `loginUrl`, `userUrl`, `refreshUrl`, `logoutUrl`, and `sessionHintCookie` when it writes one |
+
+What the space declares wins, setting by setting; a space naming another provider than the server's ignores the
+server's altogether. A page with no provider at all offers no auth actions, and an `authLogin` there says why in the
+console (`[plitzi] auth.login: …`) — read it before suspecting the form.
+
+On the platform, `userProvider: 'server'` signs in by leaving the page: a `link` with `mode: 'external'` to
+`/auth/sign-in?return=/` sends the visitor to sign in and back, signed in on the space's own host.
+
+## The steps
+
+```ts
+form({
+  id: 'signIn',
+  managedByInteractions: true,
+  flows: [
+    [
+      named('sent', onSubmit()),
+      named('signedIn', authLogin({ username: '{{ sent.values.username }}', password: '{{ sent.values.password }}' })),
+      when({ field: 'signedIn.ok', operator: '=', value: true }, navigate({ urlType: 'page', url: 'dashboard' })),
+      when(
+        { field: 'signedIn.reason', operator: '=', value: 'unverified' },
+        addNotification({ content: 'Confirm your address first — the link is in your inbox', appearance: 'warning' })
+      )
+    ]
+  ],
+  children: [
+    formControl({ name: 'username', label: 'Username' }),
+    formControl({ name: 'password', label: 'Password', subType: 'password' }),
+    button({ content: 'Sign in', subType: 'submit' })
+  ]
+});
+```
+
+- `authLogin(params)` — `{ username, password }`; `{ mode: 'token', token }` adopts a credential obtained elsewhere,
+  checked against `userUrl`; `{ mode: 'mfa', mfaToken, code }` completes a sign-in that owed a second factor.
+- What it answers: `ok`; when not, `reason` (`unverified`, `inactive`, `network`, `missing`…) and, for `reason: 'mfa'`,
+  `mfaToken` — the challenge `mode: 'mfa'` completes. Test it on `<step>.ok` with `when`, never `whenSucceeded` /
+  `whenFailed`, which are a server action's ([flows](flows.md)).
+- `authLogout()` ends the session; `authRefreshDetails()` reloads who is signed in.
+
+## Who is signed in
+
+The `auth` source: `{{ auth.isAuthenticated }}`, `{{ auth.status }}` (`init` … `authenticated` | `guest`, while it is
+being found out), `{{ auth.details.username }}` — `details` carries `id`, `username`, `email`, `verified`, `roles` and
+`permissions`. Show a signed-in part with `visible: 'auth.isAuthenticated'`; never bind a token into the page.
+
+## Pages for one kind of visitor
+
+A page's `accessLevel`: `'authenticated'` (signed in), `'public'` (signed OUT only — the sign-in page), or nothing
+(everybody). A lone `public` page vanishes the moment anyone signs in, so leave it out unless the page has a signed-in
+twin on the same slug. `unauthorizedRedirect` names where a visitor the page is not for goes — a page's id or slug
+(`''` is the home page), or a URL; without it they are answered 403.
+
+## What a visitor may do
+
+`settings.visitorRoles` — `{ author: ['postPublish'] }` — is what each role gives. A visitor holds exactly the
+permissions of their roles in this space; who holds a role is given by email in the builder, never written here. A page
+reads them in `auth.details.permissions`, a plugin asks `can('postPublish')` of the auth context.
+
+A server action's trigger says who may run it: `access: { mode: 'public' }`, `{ mode: 'session' }` (signed in) or
+`{ mode: 'role', permissions: ['postPublish'] }`. The page hiding a button is not the check — the trigger is. Inside,
+its steps read who asked as `{{ user.id }}`, and a function as `ctx.user` (`id`, `username`, `email`, `verified`,
+`roles`, `permissions`) — never their session.

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

@@ -27,7 +27,7 @@ The space is not written until these are fixed.
 | `action-without-entry` | an action with no way in, so nothing can start it | a `trigger` — `{ type: 'call', access }`, or `render`, `webhook`, `custom`, `schedule` |
 | `action-without-steps` | an action with no steps | the steps it runs |
 | `active-when-constant` | an `activeWhen` condition that reads nothing — always or never true | name what it depends on: `'{{ list_dots.index == state.slide }}'` |
-| `ancestor-not-class` | an ancestor condition keyed by something that is not a class name | `[card.name]` for a `styles()` declaration |
+| `ancestor-not-class` | an ancestor condition keyed by something that is neither a class name nor `'>'` (the parent) | `[card.name]` for a `styles()` declaration, or `'>'` for the parent whatever it wears |
 | `anchor-duplicate` | one anchor on two elements of the same page (layouts included) | rename all but one |
 | `anchor-invalid` | an `anchor` or a link's `hash` that is not lowercase letters, digits and `-` | `anchor: 'plans'`, `hash: 'plans'` — no `#` |
 | `anchor-missing` | a link whose `hash` no element on the page it goes to carries — it would land at the top | the anchor the message lists, or give the section that `anchor` |
@@ -59,20 +59,23 @@ The space is not written until these are fixed.
 | `computed-not-template` | a computed value that is not a template | `'{{ state.x * 2 }}'` |
 | `computed-reads-element` | a computed value reading an element's source — no element is around the whole space | compute it from the globals and the variables, or bind it on the element |
 | `computed-unknown` | a computed value read before it is declared, or never declared | declare it in `computed`, above the one that reads it |
+| `condition-field-unpublished` | a `when` asking a step of its flow for a key it never publishes — `whenSucceeded` / `whenFailed` on anything but `runServerAction` | a key the step publishes (`explain <step>`): after `authLogin`, `when({ field: 'signedIn.ok', operator: '=', value: true }, …)` |
 | `controls-unknown` | a button's `controls` naming no element of the space | the id of the element it shows and hides: `controls: 'faq-answer'` |
 | `css-property-twice` | one property written twice in a rule set — `paddingTop` beside `'padding-top'` — so one would silently win | keep one |
 | `css-property-unknown` | a CSS property that does not exist | the property it suggests; a custom property starts with `--` |
 | `css-value` | an empty CSS value, or one with `;` or `{}` | one value per property; leave a property out instead of writing it empty |
+| `element-ids-target` | a step refreshing containers by id (`invalidateElements`, `invalidateQueries({ elements })`) naming one the space does not have, or one that is not an `apiContainer` | the id of the `apiContainer` whose data the step changes: `invalidateElements: ['posts']` |
 | `element-load-strategy` | a `loadStrategy` the element does not take | one of the values the message lists |
 | `element-rejected` | an element the schema refused to hold | the problem listed with it |
 | `element-runtime` | a `runtime` the element does not run in | one of the values the message lists |
 | `element-shape` | an element that is not an object with a `type`, `attributes` and a list of `children` | build elements with their factories — `text(…)`, `container(…)` |
+| `element-slot-unknown` | a `slots` key the element type does not have — its class would dress nothing | one of the slots `plitzi explain <type>` lists; the element itself takes `class` |
 | `flag-gate` | an element's or a page's `flag` that is not a flag name | `flag: 'newCheckout'`, or `flag: '!newCheckout'` for "only while off" |
 | `flag-name` | a flag whose name a template cannot read as `flags.x` | letters, digits and `_` |
 | `flag-rule-shape` | a flag rule that is not `{ when, value }`, or whose `value` is not `true` or `false` | `{ when: { … }, value: true }` |
 | `flag-shape` | a flag whose `value` is not `true` or `false` | `{ value: false, rules: [] }` |
 | `flag-undeclared` | a gate on a flag the space does not declare — it reads as off, so the element never (or always) renders | declare it in `flags`, or remove the gate |
-| `flag-unknown` | a template reading a flag the space does not declare | the declared name it suggests, or declare it |
+| `flag-unknown` | a template, a binding or a `when` reading a flag the space does not declare | the declared name it suggests, or declare it |
 | `flow-empty` | a flow with no steps | `[onClick(), setState({ … })]` |
 | `flow-without-trigger` | a flow whose first step is not the event that runs it | `[onClick(), setState(…)]` |
 | `folder-cycle` | a page folder inside itself | a `parent` that leads to the top |
@@ -83,9 +86,11 @@ The space is not written until these are fixed.
 | `from-without-attribute` | `from` on a type with no one attribute that shows its data (a container, a form) | bind the attribute you mean: `bind: { attribute: 'source' }` |
 | `global-callback-module` | a global callback sent to a module other than the one that registers it | the step builder, which knows the module |
 | `global-callback-undeclared` | a global-callback step builder naming an action no source declares | one of the actions it lists |
+| `global-field-unknown` | a binding, a template or a `when` reading a field `navigation`, `auth` or `theme` never has — `auth.authenticated` | the field it suggests: `auth.isAuthenticated`, `auth.details.username`, `navigation.queryParams.next`, `theme.resolved` |
 | `id-invalid` | an id a binding, a template or a test cannot name | a letter first, then letters, digits, `-` and `_`: `'hero-title'` |
 | `id-shadows-global` | an element named like a global data source (`state`, `navigation`, `auth`…) | another id |
 | `id-taken` | two elements with one id — ids are one namespace for the whole space | a name taken by a page or a layout: a name of its own; a helper called twice: `scope('promos', ref => …)`, every id inside prefixed |
+| `keyframes-shape` | keyframes with a name CSS does not accept or the SDK keeps for itself, or a frame that is not an offset | a plain name (`slide-in`), frames keyed `from`, `to` or a percentage (`'50%'`, `'0%, 100%'`) |
 | `layout-slot-unknown` | a layout `slot` that is not an element inside that layout | the id of the element in the shell where the body goes |
 | `layout-undeclared` | a page or a layout inside a layout the space does not declare | the layout's id, or declare it in `layouts` |
 | `list-items-ignored` | a list whose items nothing reads — `source: 'none'` renders its children once | `source: 'controlled'` |
@@ -96,7 +101,7 @@ The space is not written until these are fixed.
 | `motion-invalid` | a `motion` with a preset, a trigger or a timing the page cannot play | `motion: { enter: 'fade-up', on: 'view' }` — the message lists the presets |
 | `motion-no-tag` | a `motion` on an element with no tag of its own — nothing to move | the motion on what it wraps, or a `subType` on it |
 | `no-pages` | a space with no pages | `pages: [{ id: 'home', name: 'Home', slug: '', body: [] }]` |
-| `notifications-shape` | `notifications` with a field it does not have, or a value that is not one CSS value | the fields it lists; a colour or a length, like 'var(--card)' or '12px' |
+| `notifications-shape` | `notifications` with a field it does not have, or a value that is not one CSS value | the field it suggests, or one it lists; one CSS value, like 'var(--card)', '12px' or '500' |
 | `outside-ancestor` | an element that reads the state of an element it is not inside | nest it in the element the message names |
 | `page-access-level` | an `accessLevel` that is not one the router reads | one of the values the message lists |
 | `page-route-reserved` | a page under `/fn`, where the space's functions answer | another slug |
@@ -131,6 +136,10 @@ The space is not written until these are fixed.
 | `step-name` | a step name a later step cannot read as `{{ name.field }}` | a letter first, then letters, digits, `-` and `_` |
 | `step-params` | a step param that does not exist, or a value outside its options | the params and values it lists |
 | `step-type` | a step `type` that does not exist | the step builders — `setState(…)`, `navigate(…)` — write it |
+| `style-condition-unknown` | a condition a class's rules cannot hold under | `motion-reduce`, `motion-safe`, or a container width — `container (max-width: 30rem)`, `container card (min-width: 480px)` |
+| `style-pseudo-content` | a `content` CSS cannot read — text without its quotes draws nothing — or a `before`/`after` with no `content`, which is not there at all | the text in quotes inside the string — `content: '"→"'`, `'""'` for an empty box — or a function such as `counter(step)` |
+| `style-pseudo-property` | a property the pseudo-element ignores — the browser drops it without a word | one it honours (`::selection` paints, `::marker` and `::placeholder` take text and font), or style the element |
+| `style-pseudo-unknown` | a pseudo-element a class cannot dress | one of `before`, `after`, `marker`, `placeholder`, `first-letter`, `first-line`, `selection` — without the `::` |
 | `style-state-unknown` | a state a selector does not react to | one of the states it lists (`hover`, `focus`, `active`…) |
 | `svg-not-svg` | an `svg` whose `content` is not one `<svg>…</svg>` — it draws nothing | the SVG markup alone; HTML around it goes in a `blockHtml` |
 | `template-short-source` | a source named without its prefix inside a template or a step | the full name: `apiContainer_stats`, `list_rows` |
@@ -161,6 +170,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | Code | What was wrong | Write instead |
 | --- | --- | --- |
 | `action-output-path` | a read of `.data` on a provider fed by a server action — it publishes the action’s output at its root, and `.data` is a `query` provider’s answer | the output’s own field — `apiContainer_feed.stories`, not `apiContainer_feed.data.stories` |
+| `animation-name-unknown` | `animation-name` naming keyframes the space does not declare — nothing plays | declare them in the space's `keyframes`, or name one it has |
 | `click-on-static-element` | a click flow on a container, text, heading, image or list item — no keyboard reaches it | the flow on a `button` (it holds children) or a `link` |
 | `colour-without-dark` | a colour token with no dark value | `{ light, dark, default }` |
 | `condition-starts-visible` | a computed visibility that shows until its data answers | `visible: { source, template }` |
@@ -176,9 +186,11 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `form-control-name-taken` | two controls in one form with one name — one overwrites the other | a name each |
 | `form-control-unnamed` | a control in a form with no `name` — its value never reaches `values` | `formControl({ name: 'email', … })` |
 | `form-value-compared-to-blank` | a `when` comparing a submitted field to `""` — a field nobody typed in is not sent | `operator: 'empty'` / `'notEmpty'` |
+| `heading-level-overridden` | a markdown's or richText's `heading` slot and a level's (`heading3`) both setting one property, the general class written later in the stylesheet — the level's value is lost | set the property on one of the two: the level slot for that level alone, `heading` for every heading |
 | `heading-level-skipped` | an `h4` right after an `h2` — the outline misses a level | the next level down; size it with its class |
 | `image-without-alt` | an image that is not `decorative` and has no `alt` | say what it shows, or `decorative: true` |
 | `label-ignored` | a `label` on a container whose tag is named by what it holds (`li`, a heading) | the words inside, or a landmark tag (`nav`, `section`…) |
+| `link-current-section` | `current: 'section'` on a link that is never current (an external one) or current everywhere (to `/`) | leave `current` out — `'section'` is for a link to a section's own page, `/automations/runs` |
 | `list-item-key-missing` | a list's `itemKey` that some of its items lack, or two of them share — the rows fall back to `id`, then position | a field every item has, once each |
 | `list-row-not-li` | a row of a list with `items` that is not an `<li>` — that list is a `<ul>` (or `<ol>`), so the row is a box inside a list, no item to a screen reader | `container({ subType: 'li' })` — or the component's root one, or a wrapper for a link or a button |
 | `overlay-never-opened` | a modal or a dialog that starts hidden and that no step opens | a flow with `openModal('id')` / `openDialog('id')` |
@@ -208,10 +220,12 @@ Nothing is wrong: the page renders as written. Each is a shorter way to the same
 
 | Code | Written the long way | The short way |
 | --- | --- | --- |
+| `class-overrides-class` | one class's shorthand erasing the longhand another class on the same element writes out — `padding` over `padding-top` — because the stylesheet writes it later: classes in the order they are first met, a breakpoint's rules after the base, never the order of a class list | the longhands the shorthand means instead of it (`padding-left`, `padding-right`), so it leaves the other class's alone — or `quiet: ['class-overrides-class']` when the shorthand is meant to win |
 | `content-attribute` | a button or a link whose children are only its words and an icon — a `text`, a `fontAwesome` — elements more than it needs | its own `content` and `icon` (`link({ href, content: 'Docs', icon: 'fa-solid fa-arrow-right', iconPlacement: 'after' })`); the icon's class goes on the `icon` slot, and what the text's class adds on the box's class, never the class itself |
 | `custom-css-class` | a `customCss` rule a class can hold — `.card:hover`, `.panel .icon` | the class's own `states` or `ancestors`, where the style editor reads it back and a breakpoint can change it |
-| `custom-css-notifications` | the toasts dressed with `.Toastify__toast` rules in `customCss` | `notifications: { font, fontSize, border, shadow, padding, background, text, radius }` |
+| `custom-css-notifications` | the toasts or their icon, close button or progress bar dressed with `.Toastify__*` rules in `customCss` | `notifications: { font, fontSize, fontWeight, minHeight, iconSize, closeColor, progressHeight, … }` |
 | `custom-css-sdk-default` | `customCss` repeating what the SDK already does for every space — less motion when asked, the theme toggle showing one icon | nothing: remove it |
+| `custom-css-slot` | a part of a built-in element dressed in `customCss` by the SDK's markup — a form control's `<input>`, a pager's buttons, a heading inside a markdown | a class on the slot of that part — `slots: { field: input }`, `elements.<type>.slots` — with its states |
 | `heavy-animation` | keyframes animating what the browser repaints or lays out again on every frame — a size, a position, a blur, a shadow, or a colour in a loop — which stutters whenever the page is busy, most of all while it loads | `opacity` and `transform`: a size or a position is `translate`/`scale`, a blur or a shadow is the `opacity` of a layer carrying it; a loop that must animate anything else starts `paused` and runs under `[data-hydrated]` |
 | `literal-colour` | a colour written out in a class where the space has a token of that value — it stays put in the dark scheme | `var(--token)` when it should follow the scheme; a token of one value of its own when it must stay the same in both |
 | `repeated-on-pages` | the same block — a header, a footer, a side panel — written into several pages | a layout holding it once (`layouts`, and `layout: { id, slot }` on each page) — a component when only some pages of a layout carry it; a link marks its own page with the `current` state |

package/skills/plitzi-authoring/reference/colours-and-motion.md

@@ -2,8 +2,9 @@
 
 ## Animations
 
-- **Keyframes go in the space's `customCss`** (`'@keyframes marquee { to { transform: translateX(-50%); } }'`) and
-  the class names them: `animation: 'marquee 30s linear infinite'`.
+- **Keyframes go in the space's `keyframes`** (`keyframes: { marquee: { to: { transform: 'translateX(-50%)' } } }`)
+  and the class names them: `animation: 'marquee 30s linear infinite'`. A name no keyframes declare is warned
+  (`animation-name-unknown`).
 - **An element hidden by `visible` is `display: none`**, so an animation in its class runs again every time it is
   shown — the way to animate a slide in (see recipes/every-few-seconds.ts).
 - **Pause on hover** from the element around it: `ancestors: { [band.name]: { states: { hover: