@plitzi/sdk-server 0.37.8 → 0.37.9

package/dist/modules/functions/config.js

@@ -1,24 +1,40 @@
+import { DEFAULT_FUNCTION_TIME_LIMITS } from "@plitzi/sdk-shared/actions";
 //#region src/modules/functions/config.ts
+/** What an invocation gets unless its task asks for more CPU or time. */
 var DEFAULT_FUNCTION_LIMITS = {
-	cpuMs: 100,
-	wallMs: 1e4,
+	...DEFAULT_FUNCTION_TIME_LIMITS,
 	memoryMb: 64,
 	outputBytes: 1e6,
 	calls: 100
 };
-/** What one invocation of a space may spend: its own limits, never above the deployment's. */
-var functionLimitsFor = (ceilings = {}, space = {}) => {
-	const ceiling = {
-		...DEFAULT_FUNCTION_LIMITS,
-		...ceilings
-	};
+/**
+* The most a deployment lets one invocation have, unless it says otherwise: two seconds of CPU and half a minute of
+* time for a task that asks; the rest as every invocation gets it.
+*/
+var DEFAULT_FUNCTION_CEILINGS = {
+	...DEFAULT_FUNCTION_LIMITS,
+	cpuMs: 2e3,
+	wallMs: 3e4
+};
+/** A deployment's ceilings, each unset one the default's. */
+var functionCeilings = (ceilings = {}) => ({
+	...DEFAULT_FUNCTION_CEILINGS,
+	...ceilings
+});
+/**
+* What one invocation of a space may spend: the CPU and time its task asked for — the default's when it asked for none
+* — and the rest as the deployment gives it; never above the space's plan, nor above the deployment's ceilings.
+*/
+var functionLimitsFor = (ceilings = {}, space = {}, asked = {}) => {
+	const ceiling = functionCeilings(ceilings);
+	const capOf = (key) => Math.min(space[key] ?? ceiling[key], ceiling[key]);
 	return {
-		cpuMs: Math.min(space.cpuMs ?? ceiling.cpuMs, ceiling.cpuMs),
-		wallMs: Math.min(space.wallMs ?? ceiling.wallMs, ceiling.wallMs),
-		memoryMb: Math.min(space.memoryMb ?? ceiling.memoryMb, ceiling.memoryMb),
-		outputBytes: Math.min(space.outputBytes ?? ceiling.outputBytes, ceiling.outputBytes),
-		calls: Math.min(space.calls ?? ceiling.calls, ceiling.calls)
+		cpuMs: Math.min(asked.cpuMs ?? DEFAULT_FUNCTION_LIMITS.cpuMs, capOf("cpuMs")),
+		wallMs: Math.min(asked.wallMs ?? DEFAULT_FUNCTION_LIMITS.wallMs, capOf("wallMs")),
+		memoryMb: capOf("memoryMb"),
+		outputBytes: capOf("outputBytes"),
+		calls: capOf("calls")
 	};
 };
 //#endregion
-export { DEFAULT_FUNCTION_LIMITS, functionLimitsFor };
+export { DEFAULT_FUNCTION_CEILINGS, DEFAULT_FUNCTION_LIMITS, functionCeilings, functionLimitsFor };

package/dist/modules/functions/contract.d.ts

@@ -1,6 +1,6 @@
 import { RateCount, RateLimit } from '../actions/runtime/rateLimit';
 import { ActionKvStore } from '../actions/types';
-import { Environment, InteractionCallbackParam } from '@plitzi/sdk-shared';
+import { Environment, FunctionTimeLimits, InteractionCallbackParam } from '@plitzi/sdk-shared';
 /**
  * Who started the run, as a space's own code may know them: everything a function decides by — who, their roles and
  * permissions — and never their session. A token inside the sandbox is a token a function could send anywhere.
@@ -85,6 +85,11 @@ export type FunctionTask<T extends Record<string, unknown> = Record<string, unkn
     title: string;
     description?: string;
     params: Record<keyof T, InteractionCallbackParam<T>>;
+    /**
+     * More CPU or time than an invocation gets by default — `{ cpuMs: 1000 }` for a task that reshapes a big feed — up to
+     * what the server allows. Over the functions' own `limits`, for this task.
+     */
+    limits?: FunctionTimeLimits;
     run: (params: T, ctx: FunctionContext) => unknown;
 };
 /** What a route's handler gets besides the request: the context, and the `:params` its key named, by name. */
@@ -92,7 +97,7 @@ export type FunctionRouteContext = FunctionContext & {
     params: Record<string, string>;
 };
 /**
- * An HTTP endpoint of the space, under `/api/`: a web-standard handler, the shape every edge runtime runs. The request
+ * An HTTP endpoint of the space, under `/fn/`: a web-standard handler, the shape every edge runtime runs. The request
  * carries no credentials — `ctx.user` says who is asking — and the response sets no cookies: the host's are the
  * platform's.
  */
@@ -104,8 +109,10 @@ export type FunctionsDefinition = {
         hosts?: string[];
     };
     tasks?: FunctionTask<never>[];
-    /** `'GET /board-assets/:board/:asset'` → a handler, served at `/api/board-assets/…`. */
+    /** `'GET /board-assets/:board/:asset'` → a handler, served at `/fn/board-assets/…`. */
     routes?: Record<string, FunctionRoute>;
+    /** More CPU or time than an invocation gets by default, for every task and route — a task may ask for its own. */
+    limits?: FunctionTimeLimits;
 };
 /**
  * What a function throws to refuse, with a reason written for whoever asked — a wrong password, a board that is

package/dist/modules/functions/driver.js

@@ -14,9 +14,11 @@ var describeFunctions = (definition) => {
 			action: task.action,
 			title: task.title,
 			description: task.description,
-			params: task.params
+			params: task.params,
+			limits: task.limits
 		} : {}),
-		routes: isRecord(found.routes) ? Object.keys(found.routes) : []
+		routes: isRecord(found.routes) ? Object.keys(found.routes) : [],
+		limits: found.limits
 	};
 };
 /**

package/dist/modules/functions/manifest.d.ts

@@ -1,3 +1,4 @@
+import { FunctionLimits } from './protocol';
 import { FunctionsManifest } from '@plitzi/sdk-shared';
 export declare const ROUTE_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
 export type RouteMethod = (typeof ROUTE_METHODS)[number];
@@ -6,7 +7,7 @@ export type RouteKey = {
     segments: string[];
 };
 /**
- * A route key, `'<METHOD> /<path>'`: literal segments and `:params`, served under `/api/`. Anything else — a query, a
+ * A route key, `'<METHOD> /<path>'`: literal segments and `:params`, served under `/fn/`. Anything else — a query, a
  * wildcard, `..` — is not a key, so what a space may answer is only ever a path it spelled out.
  */
 export declare const parseRouteKey: (key: string) => RouteKey | undefined;
@@ -19,6 +20,7 @@ export type ManifestReading = {
  * afterwards, because what is stored is only ever what passed it.
  *
  * `reserved` is every namespace this deployment's own tasks use: a space's task may take none of them, so a step that
- * names a platform task always runs the platform's.
+ * names a platform task always runs the platform's. `ceilings` is the most this deployment gives one invocation: what a
+ * task may ask for.
  */
-export declare const readManifest: (value: unknown, reserved: ReadonlySet<string>) => ManifestReading;
+export declare const readManifest: (value: unknown, reserved: ReadonlySet<string>, ceilings: FunctionLimits) => ManifestReading;

package/dist/modules/functions/manifest.js

@@ -10,7 +10,7 @@ var ROUTE_METHODS = [
 var SEGMENT = /^(:[a-zA-Z][a-zA-Z0-9]*|[A-Za-z0-9._~-]+)$/;
 var isRouteMethod = (method) => ROUTE_METHODS.some((known) => known === method);
 /**
-* A route key, `'<METHOD> /<path>'`: literal segments and `:params`, served under `/api/`. Anything else — a query, a
+* A route key, `'<METHOD> /<path>'`: literal segments and `:params`, served under `/fn/`. Anything else — a query, a
 * wildcard, `..` — is not a key, so what a space may answer is only ever a path it spelled out.
 */
 var parseRouteKey = (key) => {
@@ -83,14 +83,41 @@ var paramOf = (value) => {
 		default: return `has a type the builder cannot draw ("${String(value.type)}"): text, textarea, codemirror-text, codemirror-json, boolean, elements or select`;
 	}
 };
+/** What each asked limit is, in words a problem is written in. */
+var LIMIT_WORDS = {
+	cpuMs: "of CPU",
+	wallMs: "to finish"
+};
+/**
+* What `where` asks for beyond the default, read: whole milliseconds above nothing — and never more than `ceilings`, which
+* is said rather than quietly cut down, so the author knows what the code will get.
+*/
+var limitsOf = (value, where, ceilings, problems) => {
+	if (value === void 0) return;
+	if (!isRecord(value)) {
+		problems.push(`${where}: limits is not an object like { cpuMs: 1000, wallMs: 20000 }`);
+		return;
+	}
+	const limits = {};
+	["cpuMs", "wallMs"].forEach((key) => {
+		const asked = value[key];
+		if (asked === void 0) return;
+		if (typeof asked !== "number" || !Number.isInteger(asked) || asked <= 0) problems.push(`${where}: limits.${key} is not a whole number of milliseconds above 0`);
+		else if (asked > ceilings[key]) problems.push(`${where}: asks for ${String(asked)} ms ${LIMIT_WORDS[key]}, and this server allows at most ${String(ceilings[key])} ms`);
+		else limits[key] = asked;
+	});
+	Object.keys(value).filter((key) => key !== "cpuMs" && key !== "wallMs").forEach((key) => problems.push(`${where}: limits.${key} is not a limit a function asks for (cpuMs, wallMs)`));
+	return Object.keys(limits).length ? limits : void 0;
+};
 /**
 * Reads what a bundle said it declares, and every rule it must meet — the one validator, at save and nowhere else
 * afterwards, because what is stored is only ever what passed it.
 *
 * `reserved` is every namespace this deployment's own tasks use: a space's task may take none of them, so a step that
-* names a platform task always runs the platform's.
+* names a platform task always runs the platform's. `ceilings` is the most this deployment gives one invocation: what a
+* task may ask for.
 */
-var readManifest = (value, reserved) => {
+var readManifest = (value, reserved, ceilings) => {
 	const problems = [];
 	const raw = isRecord(value) ? value : {};
 	const hosts = Array.isArray(raw.hosts) ? raw.hosts.filter((host) => typeof host === "string") : [];
@@ -130,12 +157,14 @@ var readManifest = (value, reserved) => {
 			else params[key] = read;
 		});
 		const description = stringOf(task.description);
+		const limits = limitsOf(task.limits, where, ceilings, problems);
 		tasks.push({
 			namespace,
 			action,
 			title,
 			...description ? { description } : {},
-			params
+			params,
+			...limits ? { limits } : {}
 		});
 	});
 	const routes = Array.isArray(raw.routes) ? raw.routes.filter((route) => typeof route === "string") : [];
@@ -150,11 +179,13 @@ var readManifest = (value, reserved) => {
 		if (routed.has(shape)) problems.push(`Route "${route}" answers the same requests as another one`);
 		routed.add(shape);
 	});
+	const limits = limitsOf(raw.limits, "The functions", ceilings, problems);
 	return {
 		manifest: {
 			hosts,
 			tasks,
-			routes
+			routes,
+			...limits ? { limits } : {}
 		},
 		problems
 	};

package/dist/modules/functions/routes.d.ts

@@ -31,6 +31,6 @@ export type RouteSources = {
  * each run with the same context a task of theirs gets, `trigger: 'route'`.
  */
 export declare const createRoutes: ({ config, getFunctions, taskContext }: RouteSources) => {
-    /** The route that answers `method path` (the path after `/api`), for this visit — or none. */
+    /** The route that answers `method path` (the path after `/fn`), for this visit — or none. */
     routeFor: (visit: RouteVisit, method: string, path: string) => Promise<RouteHandler | undefined>;
 };

package/dist/modules/functions/routes.js

@@ -1,9 +1,9 @@
 import { serverLog } from "../../helpers/serverLog.js";
 import { ActionRefusal } from "../actions/runtime/errors.js";
 import { functionContextFor } from "./context.js";
+import { functionLimitsFor } from "./config.js";
 import { parseRouteKey } from "./manifest.js";
 import { answerCall, readCall, responseOf, wireRequestOf, wireResponseFrom } from "./capabilities.js";
-import { functionLimitsFor } from "./config.js";
 import { FunctionFailure } from "./protocol.js";
 import { randomUUID } from "node:crypto";
 //#region src/modules/functions/routes.ts
@@ -151,7 +151,7 @@ var createRoutes = ({ config, getFunctions, taskContext }) => {
 								...fnCtx.user ? { user: fnCtx.user } : {}
 							}
 						},
-						limits: functionLimitsFor(config.limits, functions.limits),
+						limits: functionLimitsFor(config.limits, functions.limits, functions.manifest.limits),
 						answer: (call) => answerCall(fnCtx, readCall(call)),
 						signal: visit.signal,
 						onUsage: (usage) => {
@@ -174,7 +174,7 @@ var createRoutes = ({ config, getFunctions, taskContext }) => {
 		};
 	};
 	return { 
-	/** The route that answers `method path` (the path after `/api`), for this visit — or none. */
+	/** The route that answers `method path` (the path after `/fn`), for this visit — or none. */
 routeFor: async (visit, method, path) => nativeRoute(visit, method, path) ?? await spaceRoute(visit, method, path) };
 };
 //#endregion

package/dist/modules/functions/space.d.ts

@@ -2,12 +2,13 @@ import { FunctionsSource } from './build';
 import { FunctionsConfig } from './config';
 import { FunctionsBundle, FunctionLimits, FunctionRunner, SpaceFunctions } from './protocol';
 import { ActionTask, ActionTaskRegistry } from '../actions/types';
-import { FunctionsManifest, FunctionsProblem } from '@plitzi/sdk-shared';
+import { FunctionsManifest, FunctionsProblem, FunctionTimeLimits } from '@plitzi/sdk-shared';
 /**
  * A space's tasks as the registry holds them — each run by the runner, answering the code's calls with the run's own
- * {@link FunctionContext}: the same one native functions get, built by the same function.
+ * {@link FunctionContext}: the same one native functions get, built by the same function. Each is given what
+ * `limitsFor` answers for what it asked: its own limits, over its functions'.
  */
-export declare const spaceTasks: (functions: SpaceFunctions, runner: FunctionRunner, limits: FunctionLimits, { admit, onUsage }?: Pick<FunctionsConfig, "admit" | "onUsage">) => ActionTask<Record<string, unknown>>[];
+export declare const spaceTasks: (functions: SpaceFunctions, runner: FunctionRunner, limitsFor: (asked: FunctionTimeLimits) => FunctionLimits, { admit, onUsage }?: Pick<FunctionsConfig, "admit" | "onUsage">) => ActionTask<Record<string, unknown>>[];
 export type SpaceRegistries = {
     /** The tasks one run of that space can use: the deployment's, and its own functions' when it has any. */
     registryFor: (functions: SpaceFunctions | undefined) => ActionTaskRegistry;
@@ -35,6 +36,7 @@ export type PreparedFunctions = {
 };
 /**
  * A space's source made ready to save: built, read by the runner, and checked — the only way a space's functions are
- * stored, so what is stored always passed every rule. `reserved` is every namespace the deployment's own tasks use.
+ * stored, so what is stored always passed every rule. `reserved` is every namespace the deployment's own tasks use;
+ * `ceilings`, the most it gives one invocation — what a task may ask for.
  */
-export declare const prepareFunctions: (source: FunctionsSource, runner: FunctionRunner, reserved: ReadonlySet<string>) => Promise<PreparedFunctions>;
+export declare const prepareFunctions: (source: FunctionsSource, runner: FunctionRunner, reserved: ReadonlySet<string>, ceilings: FunctionLimits) => Promise<PreparedFunctions>;

package/dist/modules/functions/space.js

@@ -1,9 +1,9 @@
 import { ActionRefusal } from "../actions/runtime/errors.js";
 import { functionContextFor } from "./context.js";
 import { taskName } from "../actions/tasks/registry.js";
+import { functionLimitsFor } from "./config.js";
 import { readManifest } from "./manifest.js";
 import { answerCall, readCall } from "./capabilities.js";
-import { functionLimitsFor } from "./config.js";
 import { FunctionFailure } from "./protocol.js";
 import { FunctionsBuildError, buildFunctions } from "./build.js";
 import { createHash } from "node:crypto";
@@ -18,10 +18,15 @@ var invocationContextOf = ({ spaceId, environment, runId, trigger, callerId, use
 });
 /**
 * A space's tasks as the registry holds them — each run by the runner, answering the code's calls with the run's own
-* {@link FunctionContext}: the same one native functions get, built by the same function.
+* {@link FunctionContext}: the same one native functions get, built by the same function. Each is given what
+* `limitsFor` answers for what it asked: its own limits, over its functions'.
 */
-var spaceTasks = (functions, runner, limits, { admit, onUsage } = {}) => functions.manifest.tasks.map((task) => {
+var spaceTasks = (functions, runner, limitsFor, { admit, onUsage } = {}) => functions.manifest.tasks.map((task) => {
 	const name = taskName(task);
+	const limits = limitsFor({
+		...functions.manifest.limits,
+		...task.limits
+	});
 	return {
 		namespace: task.namespace,
 		action: task.action,
@@ -73,7 +78,8 @@ var composeRegistry = (base, tasks) => {
 		const name = taskName(task);
 		if (!base.get(name)) own.set(name, {
 			...task,
-			name
+			name,
+			origin: "space"
 		});
 	});
 	return {
@@ -91,11 +97,11 @@ var createSpaceRegistries = (base, config = {}) => {
 	return { registryFor: (functions) => {
 		const runner = functions?.runner ?? config.runner;
 		if (!functions || !runner) return base;
-		const limits = functionLimitsFor(config.limits, functions.limits);
-		const key = `${functions.bundle.id}:${JSON.stringify(limits)}`;
+		const key = `${functions.bundle.id}:${JSON.stringify(functions.limits ?? {})}`;
 		const found = cache.get(key);
 		if (found) return found;
-		const registry = composeRegistry(base, spaceTasks(functions, runner, limits, config));
+		const limitsFor = (asked) => functionLimitsFor(config.limits, functions.limits, asked);
+		const registry = composeRegistry(base, spaceTasks(functions, runner, limitsFor, config));
 		cache.set(key, registry);
 		if (cache.size > REGISTRY_CACHE) {
 			const oldest = cache.keys().next().value;
@@ -114,9 +120,10 @@ var functionsInHand = ({ bundle, manifest }) => ({
 });
 /**
 * A space's source made ready to save: built, read by the runner, and checked — the only way a space's functions are
-* stored, so what is stored always passed every rule. `reserved` is every namespace the deployment's own tasks use.
+* stored, so what is stored always passed every rule. `reserved` is every namespace the deployment's own tasks use;
+* `ceilings`, the most it gives one invocation — what a task may ask for.
 */
-var prepareFunctions = async (source, runner, reserved) => {
+var prepareFunctions = async (source, runner, reserved, ceilings) => {
 	let code;
 	try {
 		({code} = await buildFunctions(source));
@@ -143,7 +150,7 @@ var prepareFunctions = async (source, runner, reserved) => {
 			}]
 		};
 	}
-	const { manifest, problems } = readManifest(declared, reserved);
+	const { manifest, problems } = readManifest(declared, reserved, ceilings);
 	return problems.length ? {
 		ok: false,
 		problems: problems.map((message) => ({

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

@@ -14,7 +14,7 @@ export type SpaceRuntimeContext = {
 export type SpaceRuntimeEndpoint = (request: Request) => Response | Promise<Response>;
 /** What a started runtime is made of. */
 export type SpaceRuntimeParts = {
-    /** Its tasks and `/api/` routes, run with a `ctx` that is the platform's — the space's `kv`, its channels, its key. */
+    /** Its tasks and `/fn/` routes, run with a `ctx` that is the platform's — the space's `kv`, its channels, its key. */
     functions?: FunctionsDefinition;
     /** Paths it answers itself, each with everything beneath it (`/mcp` answers `/mcp/…`) — see {@link endpointProblem}. */
     endpoints?: Record<string, SpaceRuntimeEndpoint>;

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

@@ -45,6 +45,6 @@ export type RuntimeProxyConfig = {
  * The page server forwarding a space's endpoints to its runtime: the request as it came, streamed both ways — an agent's
  * event stream included — without the visitor's cookies or `Authorization`, and with who asked in `X-Forwarded-*`.
  *
- * A data stage: after the auth chain, so the space is known, and before the space's `/api/` routes and its pages.
+ * A data stage: after the auth chain, so the space is known, and before the space's `/fn/` routes and its pages.
  */
 export declare const createRuntimeProxyStage: ({ lookup, onForward }: RuntimeProxyConfig) => Stage<SSRContext>;

package/dist/modules/runtime/stages.js

@@ -55,7 +55,7 @@ var NOT_ANSWERED = /* @__PURE__ */ new Set([...HOP_BY_HOP, "set-cookie"]);
 * The page server forwarding a space's endpoints to its runtime: the request as it came, streamed both ways — an agent's
 * event stream included — without the visitor's cookies or `Authorization`, and with who asked in `X-Forwarded-*`.
 *
-* A data stage: after the auth chain, so the space is known, and before the space's `/api/` routes and its pages.
+* A data stage: after the auth chain, so the space is known, and before the space's `/fn/` routes and its pages.
 */
 var createRuntimeProxyStage = ({ lookup, onForward }) => async (ctx) => {
 	const { spaceId, environment = "main" } = ctx.req.ctx.spaceDeployment ?? {};

package/dist/modules/ssr/prepareRender.js

@@ -143,11 +143,11 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		const key = pluginManager.ensure(pluginName, pluginSource);
 		if (!pluginBaseNames.has(pluginName)) dynamicNames.push(key);
 	}
-	const externalNamesFiltered = (config.autoLoadSchemaPlugins !== false ? await m("extPlugins", () => registerExternalPlugins(pluginManager, offlineData, { allowPrivateHosts: config.allowPrivatePluginHosts === true })) : []).filter((k) => !pluginBaseNames.has(k.replace(/@[^@]*$/, "")));
+	const externalNames = config.autoLoadSchemaPlugins !== false ? await m("extPlugins", () => registerExternalPlugins(pluginManager, offlineData, { allowPrivateHosts: config.allowPrivatePluginHosts === true }, pluginBaseNames)) : [];
 	const allPluginNames = [
 		...pluginNames,
 		...dynamicNames,
-		...externalNamesFiltered
+		...externalNames
 	];
 	const entries = allPluginNames.length > 0 ? await pluginManager.getEntries(allPluginNames) : [];
 	const pluginComponents = await m("plugins", () => loadPluginComponents(entries, pluginManager.getComponents()));

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

@@ -7,6 +7,10 @@ type ManifestReach = {
 /**
  * Reads plugins listed in offlineData.plugins, fetches their manifests, downloads and caches
  * JS/CSS via the PluginManager, and returns the effective plugin keys to pass to getEntries().
+ *
+ * `registered`: the types this deployment registers itself — a project's own build of a plugin the space also lists
+ * on its CDN. Those are never looked for elsewhere: the deployment's copy is the one rendered, and asking the CDN for a
+ * manifest nobody will use is a request, and a warning, for nothing.
  */
-export declare const registerExternalPlugins: (pluginManager: PluginManager, offlineData: OfflineDataRaw | undefined, reach?: ManifestReach) => Promise<string[]>;
+export declare const registerExternalPlugins: (pluginManager: PluginManager, offlineData: OfflineDataRaw | undefined, reach?: ManifestReach, registered?: ReadonlySet<string>) => Promise<string[]>;
 export {};

package/dist/modules/ssr/registerExternalPlugins.js

@@ -97,9 +97,13 @@ var registerPlugin = async (pluginManager, plugin, reach) => {
 /**
 * Reads plugins listed in offlineData.plugins, fetches their manifests, downloads and caches
 * JS/CSS via the PluginManager, and returns the effective plugin keys to pass to getEntries().
+*
+* `registered`: the types this deployment registers itself — a project's own build of a plugin the space also lists
+* on its CDN. Those are never looked for elsewhere: the deployment's copy is the one rendered, and asking the CDN for a
+* manifest nobody will use is a request, and a warning, for nothing.
 */
-var registerExternalPlugins = async (pluginManager, offlineData, reach = { allowPrivateHosts: false }) => {
-	const plugins = offlineData?.plugins;
+var registerExternalPlugins = async (pluginManager, offlineData, reach = { allowPrivateHosts: false }, registered = /* @__PURE__ */ new Set()) => {
+	const plugins = offlineData?.plugins?.filter((plugin) => !registered.has(plugin.type));
 	if (!plugins || plugins.length === 0) return [];
 	return (await Promise.all(plugins.map((p) => registerPlugin(pluginManager, p, reach)))).filter((k) => k !== null);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.37.8",
+  "version": "0.37.9",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -79,8 +79,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.37.8",
-    "@plitzi/sdk-shared": "0.37.8",
+    "@plitzi/plitzi-sdk": "0.37.9",
+    "@plitzi/sdk-shared": "0.37.9",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: plitzi-authoring
 description: >-
-  Write or change a Plitzi space or template in TypeScript with @plitzi/sdk-authoring — pages, layouts, elements,
-  CSS classes, data bindings, providers and flows — instead of hand-writing schema JSON. Use whenever the task is to
+  Write or change a Plitzi space or template 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.
 ---
@@ -52,10 +52,12 @@ type, the exported catalogues answer faster (`elementDefaultAttributes`, `elemen
 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` ``.
-2. **Share with classes and layouts, 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 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).
+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).
 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.
 4. **Visible by default; decide which way the logic flips.** An element is on screen unless something hides it. When
@@ -158,16 +160,17 @@ link({ href: 'about' }); link({ href: '/games/nebula', mode: 'internal' }); link
 | --- | --- |
 | [elements-and-styles.md](reference/elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
 | [layouts.md](reference/layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
+| [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 |
 | [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 |
-| [plugins.md](reference/plugins.md) | A component of your own: props, binding them, writing state, channels, registering |
+| [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 into code |
+| [templates-and-export.md](reference/templates-and-export.md) | Publishing a template; 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 |

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

@@ -0,0 +1,75 @@
+# Components: a block written once, placed anywhere
+
+A product card, a pricing tier, a testimonial: the same block on several pages, or several times on one, differing
+only in what it says. A helper function that returns `ElementSpec` writes a COPY of the block wherever it is called —
+the document holds every copy, and a person who later edits one in the builder edits that one. A **component** is the
+block written ONCE: the document holds one tree, every placement is an instance of it, and an edit to it is an edit to
+all of them, in code and in the builder alike.
+
+```ts
+import { component, container, heading, text } from '@plitzi/sdk-authoring';
+
+import type { ComponentSpec } from '@plitzi/sdk-authoring';
+
+export const productCard: ComponentSpec = {
+  id: 'product-card',
+  label: 'Product card',
+  props: {
+    title: { type: 'text', description: 'The product name', required: true },
+    price: { type: 'number', description: 'In euros' },
+    featured: { type: 'boolean', description: 'Wears the accent border', default: false }
+  },
+  slots: ['product-card-actions'],
+  root: container({
+    id: 'product-card-root',
+    class: card,
+    children: [
+      heading({ id: 'product-card-title', bind: { content: 'props.title' } }),
+      text({ id: 'product-card-price', content: '{{ props.price }} €' }),
+      container({ id: 'product-card-actions' })
+    ]
+  })
+};
+
+// in the space
+components: [productCard],
+pages: [{ name: 'Shop', slug: 'shop', body: [
+  component('product-card', { props: { title: 'Lamp', price: 40 }, children: { 'product-card-actions': [button('Buy')] } })
+] }]
+```
+
+- **Props are attributes of the instance**, declared like a step's params (`type`, `description`, `required`,
+  `default`, `options`) and read inside as `{{ props.<name> }}` — in a binding's `source`, a template or an attribute.
+  A prop name is letters, digits and `_`, never one an instance already has (`referenceId`, `slot`, `className`…).
+  A prop an instance leaves out, with no `default`, is `null`: `{{ props.blurb }}` prints nothing and
+  `visible: 'props.featured'` keeps the element hidden.
+- **A prop can be bound** like any attribute: `component('product-card', { bind: [{ to: 'title', source: 'list_products.item.name' }] })`.
+  That is how a list row hands its record to a card — bind the record, not each field, if the card reads several:
+  a `json` prop `item`, read as `{{ props.item.name }}`.
+- **Slots** are elements of the component's tree that an instance fills. `children: [ … ]` fills a component with one
+  slot; `children: { '<slot>': [ … ] }` names the slot for each. What fills a slot is the instance's, not the
+  component's: it is authored on the page and sees the page's sources.
+- **Closed.** Inside, nothing but `props` and the globals (`state`, `auth`, `navigation`, `theme`, `variables`,
+  `computed`). A binding inside a component onto a provider of the page is refused — "nothing in this component answers
+  to …" — because the component would render differently wherever it was placed. Put the provider inside the component,
+  or hand the value in as a prop.
+- **Ids are shared** with the whole space, like a layout's: name a component's elements after it (`product-card-title`).
+  The same ids render once per instance, each with state of its own.
+- **State of its own per instance.** A flow inside a component that names one of its elements —
+  `toggleElement({ category: 'state', key: 'visibility' }, 'product-card-details')` — acts on THAT instance's copy.
+  Global state is shared: `toggleInState({ key: 'favourites', value: '{{ props.product.id }}' })` from any card.
+- **Components nest**: a component may place another. One that places itself, directly or through another, is refused.
+- **Checked when written**: a component the space does not declare, a prop it does not declare, a required one left out,
+  a value of the wrong kind (`featured: 'true'` for a boolean) and a child for a slot it does not have each throw, by name.
+
+## Component, layout or helper?
+
+| You have | Write |
+| --- | --- |
+| Chrome a page renders INSIDE — top bar, sidebar, footer | a **layout** ([layouts.md](layouts.md)) |
+| One block placed many times, differing in its content | a **component** |
+| Many blocks of DIFFERENT structure built by the same logic | a **helper** returning `ElementSpec` |
+| A list of the same block over data | a **list** whose row is the block — or places the component ([lists.md](lists.md)) |
+
+A component is also what a person editing the space in the builder will find in its Components panel, open and edit
+once; a helper's output is, to them, a pile of copies.

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

@@ -39,7 +39,7 @@ never a nested tree. Use the step builders — they fill in where a step runs an
 
 ## What a trigger hands the flow
 
-Name the trigger (`named('changed', onChange())`) and read its payload as `{{ changed.<field> }}`:
+Name the trigger (`named('changed', on('onChange'))`) and read its payload as `{{ changed.<field> }}`:
 
 | Trigger                                                                                                | Payload                                                 |
 | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |

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

@@ -134,6 +134,18 @@ A plugin says what HAPPENED through its events (`onPick`, with the seat in the p
 decide what that means — write `state`, open a modal, call a server action. Prefer that to writing `state` from inside
 the component: the flow is visible in the space, the builder shows it, and the same act can come from a button too.
 
+## Behaving in the builder
+
+The builder draws the element on its canvas while somebody edits the page: a click selects it, a drag moves it, a key
+belongs to the editor.
+
+- **Outside preview, do nothing on your own.** `usePlitziServiceContext().settings.previewMode` is `false` while the
+  page is edited. Declared interactions are already held back then; your own click handlers, timers, global listeners,
+  permission prompts and map gestures are not — gate them on `previewMode`, and still render something to select.
+- **Never the global `window` or `document`.** The canvas is a frame of its own and the code runs in the builder's
+  window: listen, measure and go full screen through the node's own page (`ref.current.ownerDocument`, its
+  `defaultView`) or `usePlitziServiceContext().utils.getWindow()`. An `instanceof` check takes its class from there too.
+
 ## Components that draw into DOM they do not render
 
 A map, a chart library, anything that positions its own markers or popups: its roots are the library's to place. Never

package/skills/plitzi-authoring/reference/templates-and-export.md

@@ -27,6 +27,12 @@ Never rewrite an exported space by hand. `specFromSpace({ schema, style })` read
 `compareSpaces(original, authorSpace(spec))` must list nothing but what `corrections` explains. The builder's
 **Export** does all three. Edit the code from then on — and tidy it as you go ([structure.md](structure.md)).
 
+A server action reads back the same way: `actionSpecFromEntry({ id, document })` gives the `defineAction` spec that writes
+it — only when that spec writes the very same document, otherwise `reason` says why and it stays JSON — and
+`actionToSource(spec)` writes the module. For the whole space as a project — pages, actions, functions, the source of
+its plugins and runtime, its files — use `plitzi create --from <space>` (and `plitzi pull` later) rather than exporting
+the parts by hand.
+
 For a document you did not author — an export, a JSON edited by hand — run the gate before serving it:
 `validateSpace({ schema, style })`.