@plitzi/sdk-server 0.38.4 → 0.38.5

package/dist/modules/rsc/connectorRscData.js

@@ -1,6 +1,6 @@
 import { createActionResolver } from "../actions/runtime/renderResolver.js";
 import { createConnectorResolver } from "../connectors/resolver.js";
-import { publicFileResolver } from "./publicFileResolver.js";
+import { dataFileResolver, dataLookupResolver, publicFileResolver } from "./publicFileResolver.js";
 import { resolveRscData } from "./resolveRscData.js";
 //#region src/modules/rsc/connectorRscData.ts
 /**
@@ -18,10 +18,12 @@ 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, elementTimeoutMs }) => {
+var connectorRscData = ({ connectors, actions, publicDir, dataDir, 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;
 	/**
 	* An element names ONE producer, and which one decides how its data is fetched.
 	*
@@ -33,9 +35,10 @@ var connectorRscData = ({ connectors, actions, publicDir, elementTimeoutMs }) =>
 		const attributes = context.element.attributes;
 		if (attributes.connector) return resolveConnector ? resolveConnector(context) : void 0;
 		if (attributes.action) return resolveAction ? resolveAction(context) : void 0;
-		return resolvePublicFile ? resolvePublicFile(context) : void 0;
+		const fromData = resolveDataFile ? await resolveDataFile(context) : void 0;
+		return fromData !== void 0 ? fromData : resolvePublicFile ? resolvePublicFile(context) : void 0;
 	};
-	return async ({ req, spaceId, environment, user, ids, loadOfflineData, flagOverrides }) => {
+	return async ({ req, spaceId, environment, user, ids, loadOfflineData, flagOverrides, signal }) => {
 		const offlineData = await loadOfflineData();
 		if (!offlineData || offlineData.schema.rsc?.enabled === false) return {};
 		return resolveRscData({
@@ -47,6 +50,7 @@ var connectorRscData = ({ connectors, actions, publicDir, elementTimeoutMs }) =>
 			ids,
 			resolveElement,
 			...flagOverrides ? { flagOverrides } : {},
+			...signal ? { signal } : {},
 			...elementTimeoutMs === void 0 ? {} : { timeoutMs: elementTimeoutMs }
 		});
 	};

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

@@ -1,21 +1,6 @@
 import { TtlCache } from '../../helpers/cache';
 import { PluginManager } from '../../plugins/manager';
 import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
-/**
- * Rewrites the request to the page the browser is actually on.
- *
- * A refresh is issued against `/_rsc`, not against `/blog/my-post`, so resolving straight from `req.path` matches
- * nothing in `schema.pages` and every client-side refresh silently returns no data. The SDK sends the visitor's
- * location as `?location=`, and route params plus the page parameter are read from that instead.
- *
- * What a refresh asks for besides — the next page of a "load more", a search a provider was reloaded with — rides on
- * the query string beside `location`, and is read over the location's own query. It used to be dropped with the rest
- * of the endpoint's query, so a provider paged in place was answered its first page every time.
- *
- * Reflecting both is safe by construction: the location is matched against this space's own page list, and the rest
- * is what the same visitor could have put in the page's own address; the cache key is the whole request, so no answer
- * is served for a query it was not made for.
- */
 export declare const withPageLocation: (req: SSRRequest) => SSRRequest;
 /**
  * Handles GET /_rsc requests.
@@ -30,4 +15,6 @@ export declare const withPageLocation: (req: SSRRequest) => SSRRequest;
  * - Authenticated requests: Cache-Control: private, max-age=<ttl>
  * - Unauthenticated requests: Cache-Control: public, max-age=<ttl>
  */
-export declare const handleRsc: (req: SSRRequest, res: SSRResponseHelpers, config: SSRPageServerConfig, _pluginManager: PluginManager, cache?: TtlCache<string>) => Promise<void>;
+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. */
+signal?: AbortSignal) => Promise<void>;

package/dist/modules/rsc/handler.js

@@ -39,12 +39,16 @@ var ENDPOINT_PARAMS = /* @__PURE__ */ new Set(["location", "ids"]);
 * is what the same visitor could have put in the page's own address; the cache key is the whole request, so no answer
 * is served for a query it was not made for.
 */
+/** What a refresh asked for beside the endpoint's own parameters. */
+var refreshParams = (req) => Object.fromEntries(Object.entries(req.query).filter(([key]) => !ENDPOINT_PARAMS.has(key)));
 var withPageLocation = (req) => {
 	const location = req.query.location;
 	if (!location || !location.startsWith("/") || location.length > MAX_PAGE_LOCATION) return req;
 	const url = new URL(location, `${req.protocol}://${req.hostname}`);
-	const asked = Object.entries(req.query).filter(([key]) => !ENDPOINT_PARAMS.has(key));
-	const query = Object.fromEntries([...url.searchParams.entries(), ...asked]);
+	const query = {
+		...Object.fromEntries(url.searchParams.entries()),
+		...refreshParams(req)
+	};
 	const search = new URLSearchParams(query).toString();
 	return {
 		...req,
@@ -67,7 +71,7 @@ var withPageLocation = (req) => {
 * - Authenticated requests: Cache-Control: private, max-age=<ttl>
 * - Unauthenticated requests: Cache-Control: public, max-age=<ttl>
 */
-var handleRsc = async (req, res, config, _pluginManager, cache) => {
+var handleRsc = async (req, res, config, _pluginManager, cache, signal) => {
 	if (!config.adapters.getRscData) {
 		res.setStatus(501);
 		res.send(JSON.stringify({ error: "getRscData adapter not configured" }));
@@ -83,6 +87,7 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 	const ids = idsRaw ? idsRaw.split(",").filter(Boolean).slice(0, 50).map((id) => id.slice(0, 128)) : void 0;
 	const idsParam = ids?.join(",");
 	const pageRequest = withPageLocation(req);
+	req.ctx.rscParams = refreshParams(req);
 	/**
 	* Whether this refresh belongs to somebody looking at a draft.
 	*
@@ -130,7 +135,8 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 			user: req.ctx.user,
 			ids,
 			loadOfflineData,
-			flagOverrides
+			flagOverrides,
+			...signal ? { signal } : {}
 		});
 	} catch (err) {
 		serverLog.error("RSC", "getRscData error", err);

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

@@ -1,16 +1,19 @@
 import { RscElementResolver } from './resolveRscData';
+import { SpaceRevision } from '@plitzi/sdk-shared';
 /**
- * A server provider whose `query` is a file this server serves from `publicDir` — `/data/home.json` — read from disk
- * and handed to the render, so the page arrives with the section in it.
- *
- * A project with no backend keeps its data in `public/data/*.json`, and an `apiContainer` fetching it from the browser
- * leaves the server-rendered page without those sections: a flash of nothing, no content for a crawler, and no
- * anchor in place for `/#section` to land on. Read here, it is the same bytes the browser would have fetched.
- *
- * Only a plain path inside `publicDir`: a URL, one that climbs out of the folder, or one with `{{tokens}}` (resolved
- * in the browser against the visitor's route and state) is not this resolver's, and the element is left as it was.
- *
- * Answered in the shape a browser request publishes — `{ status, data }`, the body under `data` — so a provider reads
- * `<source>.data.<field>` whichever runtime it has, and moving it to the server changes no binding.
+ * A server provider whose `query` is a file this server serves from `publicDir` — `/hours.json` — read from disk, so
+ * the page arrives with the section in it rather than fetching in the browser what the server already has. The same
+ * bytes the browser would have fetched.
  */
 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.
+ */
+export declare const dataLookupResolver: (getData: (spaceId: number, at: SpaceRevision) => Promise<Record<string, string> | undefined>) => RscElementResolver;

package/dist/modules/rsc/publicFileResolver.js

@@ -1,32 +1,28 @@
 import path from "node:path";
 import { readFile } from "node:fs/promises";
+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. */
+var pathOf = (query) => {
+	if (typeof query !== "string" || !query.startsWith("/") || query.startsWith("//") || query.includes("{{")) return;
+	try {
+		return decodeURIComponent(query.split(/[?#]/)[0]);
+	} catch {
+		return;
+	}
+};
 /**
-* A server provider whose `query` is a file this server serves from `publicDir` — `/data/home.json` — read from disk
-* and handed to the render, so the page arrives with the section in it.
-*
-* A project with no backend keeps its data in `public/data/*.json`, and an `apiContainer` fetching it from the browser
-* leaves the server-rendered page without those sections: a flash of nothing, no content for a crawler, and no
-* anchor in place for `/#section` to land on. Read here, it is the same bytes the browser would have fetched.
-*
-* Only a plain path inside `publicDir`: a URL, one that climbs out of the folder, or one with `{{tokens}}` (resolved
-* in the browser against the visitor's route and state) is not this resolver's, and the element is left as it was.
-*
-* Answered in the shape a browser request publishes — `{ status, data }`, the body under `data` — so a provider reads
-* `<source>.data.<field>` whichever runtime it has, and moving it to the server changes no binding.
+* A server provider whose `query` names a JSON file under `prefix`, read from the same path inside `folder` and handed
+* to the render — answered in the shape a browser request publishes, `{ status, data }`, so a provider reads
+* `<source>.data.<field>` whichever runtime it has. A path outside `prefix`, or one that climbs out of the folder, is
+* not this resolver's, and the element is left as it was; a file not there, or not JSON, is the provider's error state.
 */
-var publicFileResolver = (publicDir) => {
-	const root = path.resolve(publicDir);
+var fileResolver = (folder, prefix) => {
+	const root = path.resolve(folder);
 	return async ({ element, signal }) => {
-		const query = element.attributes.query;
-		if (typeof query !== "string" || !query.startsWith("/") || query.startsWith("//") || query.includes("{{")) return;
-		let pathname;
-		try {
-			pathname = decodeURIComponent(query.split(/[?#]/)[0]);
-		} catch {
-			return;
-		}
-		const file = path.resolve(root, `.${pathname}`);
+		const pathname = pathOf(element.attributes.query);
+		if (pathname === void 0 || !pathname.startsWith(prefix)) return;
+		const file = path.resolve(root, `.${pathname.slice(prefix.length - 1)}`);
 		if (!file.startsWith(`${root}${path.sep}`)) return;
 		try {
 			return {
@@ -41,5 +37,41 @@ var publicFileResolver = (publicDir) => {
 		}
 	};
 };
+/**
+* A server provider whose `query` is a file this server serves from `publicDir` — `/hours.json` — read from disk, so
+* the page arrives with the section in it rather than fetching in the browser what the server already has. The same
+* bytes the browser would have fetched.
+*/
+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.
+*/
+var dataLookupResolver = (getData) => {
+	return async ({ element, spaceId, environment, req }) => {
+		const pathname = pathOf(element.attributes.query);
+		if (pathname === void 0 || !pathname.startsWith(PROJECT_DATA_PREFIX)) return;
+		const deployment = req.ctx.spaceDeployment;
+		const text = (await getData(spaceId, {
+			environment: deployment?.environment ?? environment,
+			revision: deployment?.revision ?? 0
+		}))?.[pathname.slice(PROJECT_DATA_PREFIX.length)];
+		if (text === void 0) return null;
+		try {
+			return {
+				status: 200,
+				data: JSON.parse(text)
+			};
+		} catch {
+			return null;
+		}
+	};
+};
 //#endregion
-export { publicFileResolver };
+export { dataFileResolver, dataLookupResolver, publicFileResolver };

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

@@ -39,6 +39,8 @@ export type ResolveRscDataOptions = {
      * per deployment as `rsc.elementTimeoutMs`.
      */
     timeoutMs?: number;
+    /** Whoever asked stopped waiting: every element still resolving is cancelled, as when its budget runs out. */
+    signal?: AbortSignal;
 };
 /**
  * Resolves the server-side data slices for the page addressed by `req`.
@@ -47,4 +49,4 @@ export type ResolveRscDataOptions = {
  * and the route params are what the browser will see. Each `runtime: 'server'` element resolves independently:
  * a provider that fails or hangs costs its own slice and nothing else.
  */
-export declare const resolveRscData: ({ schema, req, spaceId, environment, user, ids, resolveElement, flagOverrides, timeoutMs }: ResolveRscDataOptions) => Promise<SSRRscData>;
+export declare const resolveRscData: ({ schema, req, spaceId, environment, user, ids, resolveElement, flagOverrides, timeoutMs, signal }: ResolveRscDataOptions) => Promise<SSRRscData>;

package/dist/modules/rsc/resolveRscData.js

@@ -1,4 +1,5 @@
 import { serverLog } from "../../helpers/serverLog.js";
+import onAbort from "../../helpers/onAbort.js";
 import { matchRscPage } from "./matchRscPage.js";
 import { flagUserFromSSR, flagValues, resolveFlags } from "@plitzi/sdk-shared/flags";
 import { collectServerElements } from "@plitzi/sdk-shared/schema/serverElements";
@@ -11,18 +12,20 @@ var DEFAULT_ELEMENT_TIMEOUT_MS = 5e3;
 * the loser running to its own timeout — for actions, five more seconds of a held slot and an in-flight request
 * per element, for a page that was answered without it.
 */
-var withBudget = async (run, timeoutMs, label) => {
+var withBudget = async (run, timeoutMs, label, asked) => {
 	const controller = new AbortController();
 	let timer;
+	const releaseAsked = asked ? onAbort(asked, () => controller.abort()) : void 0;
 	try {
 		return await Promise.race([run(controller.signal), new Promise((_resolve, reject) => {
 			timer = setTimeout(() => {
 				controller.abort();
-				reject(/* @__PURE__ */ new Error(`RSC resolution timed out after ${timeoutMs}ms for ${label}`));
+				reject(/* @__PURE__ */ new Error(`RSC resolution timed out after ${timeoutMs}ms for ${label} — its section arrives empty. A slower producer is given more with \`createServer({ rsc: { elementTimeoutMs } })\`.`));
 			}, timeoutMs);
 		})]);
 	} finally {
 		if (timer) clearTimeout(timer);
+		releaseAsked?.();
 	}
 };
 /**
@@ -32,7 +35,7 @@ var withBudget = async (run, timeoutMs, label) => {
 * and the route params are what the browser will see. Each `runtime: 'server'` element resolves independently:
 * a provider that fails or hangs costs its own slice and nothing else.
 */
-var resolveRscData = async ({ schema, req, spaceId, environment, user, ids, resolveElement, flagOverrides, timeoutMs = DEFAULT_ELEMENT_TIMEOUT_MS }) => {
+var resolveRscData = async ({ schema, req, spaceId, environment, user, ids, resolveElement, flagOverrides, timeoutMs = DEFAULT_ELEMENT_TIMEOUT_MS, signal }) => {
 	if (schema.rsc?.enabled === false) return {};
 	const match = matchRscPage(schema, req.path, user);
 	if (!match) return { serverData: {} };
@@ -58,10 +61,10 @@ var resolveRscData = async ({ schema, req, spaceId, environment, user, ids, reso
 			environment,
 			user,
 			signal
-		}), timeoutMs, `element ${element.id}`)
+		}), timeoutMs, `element ${element.id}`, signal)
 	})))).reduce((acum, result, index) => {
 		if (result.status === "rejected") {
-			serverLog.error("RSC", `element ${targets[index].id} failed to resolve`, result.reason);
+			if (!signal?.aborted) serverLog.error("RSC", `element ${targets[index].id} failed to resolve`, result.reason);
 			return acum;
 		}
 		if (result.value.data !== void 0) acum[result.value.id] = result.value.data;

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

@@ -17,6 +17,11 @@ export declare const inspectRuntime: (bytes: Uint8Array) => {
     entry: string;
     files: string[];
 };
+/**
+ * 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.
+ */
+export declare const loadRuntimeModule: (file: string) => Promise<SpaceRuntime | undefined>;
 /**
  * A packed runtime written into `dir` and imported: its module's default export. `dir` must be inside the host's own
  * project, so the packages the bundle leaves to the host resolve to the host's — one copy of each.

package/dist/modules/runtime/bundle.js

@@ -85,6 +85,24 @@ var inspectRuntime = (bytes) => {
 	};
 };
 var isRuntime = (value) => isRecord(value) && typeof value.start === "function";
+/** A module's default export, held to what a runtime is — or refused, saying how to write one. */
+var runtimeOf = (loaded) => {
+	const runtime = isRecord(loaded) ? loaded.default : void 0;
+	if (!isRuntime(runtime)) throw new Error("A runtime module exports its runtime by default: export default defineRuntime({ start: … })");
+	return runtime;
+};
+/**
+* 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.
+*/
+var loadRuntimeModule = async (file) => {
+	try {
+		await fs.access(file);
+	} catch {
+		return;
+	}
+	return runtimeOf(await import(pathToFileURL(file).href));
+};
 /**
 * A packed runtime written into `dir` and imported: its module's default export. `dir` must be inside the host's own
 * project, so the packages the bundle leaves to the host resolve to the host's — one copy of each.
@@ -93,10 +111,7 @@ var loadRuntime = async (bytes, dir) => {
 	const { entry, files } = unpack(bytes);
 	await fs.mkdir(dir, { recursive: true });
 	await Promise.all(Object.entries(files).map(([name, content]) => fs.writeFile(path.join(dir, name), Buffer.from(content, "base64"))));
-	const loaded = await import(pathToFileURL(path.join(dir, entry)).href);
-	const runtime = isRecord(loaded) ? loaded.default : void 0;
-	if (!isRuntime(runtime)) throw new Error("A runtime module exports its runtime by default: export default defineRuntime({ start: … })");
-	return runtime;
+	return runtimeOf(await import(pathToFileURL(path.join(dir, entry)).href));
 };
 //#endregion
-export { MAX_RUNTIME_BUNDLE_BYTES, inspectRuntime, loadRuntime, packRuntime, runtimeBundleId };
+export { MAX_RUNTIME_BUNDLE_BYTES, inspectRuntime, loadRuntime, loadRuntimeModule, packRuntime, runtimeBundleId };

package/dist/modules/sqlite/kv.d.ts

@@ -0,0 +1,34 @@
+import { DatabaseSync } from 'node:sqlite';
+import { ActionKvAdapter } from '../actions/types';
+export type SqliteKvOptions = ({
+    /** The database file — created, with its folder, when it is not there. Opened in WAL mode. */
+    file: string;
+    db?: never;
+} | {
+    /** A database the deployment opened and shares with its own tables (a job queue, an activity log). */
+    db: DatabaseSync;
+    file?: never;
+}) & {
+    /** The table the keys live in, created when it is not there. Default `action_kv`. */
+    table?: string;
+};
+/**
+ * A key/value store in a SQLite file, over Node's own `node:sqlite` — nothing to install, nothing to run beside the
+ * server. For a deployment with no database that wants what `kv` keeps to survive a restart AND to be shared: every
+ * process pointed at the same file — replicas on one machine, a server started with `workers` — sees the same keys,
+ * the same counters and the same single-flight keys.
+ *
+ * ```ts
+ * import { createSqliteKv } from '@plitzi/sdk-server/sqlite';
+ *
+ * createServer({ action: { kv: createSqliteKv({ file: 'data/kv.sqlite' }) } });
+ * ```
+ *
+ * Every operation is ONE statement, so it is atomic without a transaction: an increment is an upsert that adds in
+ * place, a swap is an update whose `WHERE` names the value it expects. Lifetimes are instants on the store's clock,
+ * enforced on every read, and expired rows are swept as writes go by.
+ *
+ * Needs a Node with `node:sqlite` unflagged (22.13 and later), which still prints an `ExperimentalWarning` once when
+ * it loads — the reason this is its own entry rather than the default.
+ */
+export declare const createSqliteKv: (options: SqliteKvOptions) => ActionKvAdapter;

package/dist/modules/sqlite/kv.js

@@ -0,0 +1,99 @@
+import path from "node:path";
+import fs from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+//#region src/modules/sqlite/kv.ts
+/**
+* The STORE's clock in epoch ms, read inside each statement: every process on the file agrees on what "now" is.
+* `julianday()` with no argument is the current instant.
+*/
+var NOW_MS = "CAST((julianday() - 2440587.5) * 86400000 AS INTEGER)";
+var open = (file) => {
+	fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+	const db = new DatabaseSync(file);
+	db.exec("PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA synchronous = NORMAL;");
+	return db;
+};
+/**
+* A key/value store in a SQLite file, over Node's own `node:sqlite` — nothing to install, nothing to run beside the
+* server. For a deployment with no database that wants what `kv` keeps to survive a restart AND to be shared: every
+* process pointed at the same file — replicas on one machine, a server started with `workers` — sees the same keys,
+* the same counters and the same single-flight keys.
+*
+* ```ts
+* import { createSqliteKv } from '@plitzi/sdk-server/sqlite';
+*
+* createServer({ action: { kv: createSqliteKv({ file: 'data/kv.sqlite' }) } });
+* ```
+*
+* Every operation is ONE statement, so it is atomic without a transaction: an increment is an upsert that adds in
+* place, a swap is an update whose `WHERE` names the value it expects. Lifetimes are instants on the store's clock,
+* enforced on every read, and expired rows are swept as writes go by.
+*
+* Needs a Node with `node:sqlite` unflagged (22.13 and later), which still prints an `ExperimentalWarning` once when
+* it loads — the reason this is its own entry rather than the default.
+*/
+var createSqliteKv = (options) => {
+	const table = options.table ?? "action_kv";
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) throw new Error(`createSqliteKv: "${table}" is not a table name (letters, digits and _, not starting with a digit).`);
+	const db = options.db ?? open(options.file);
+	db.exec(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER)`);
+	const live = `(expires_at IS NULL OR expires_at > ${NOW_MS})`;
+	const expiry = (ttlSeconds) => ttlSeconds === void 0 ? null : ttlSeconds * 1e3;
+	const expiresAt = `CASE WHEN ? IS NULL THEN NULL ELSE ${NOW_MS} + ? END`;
+	const statements = {
+		get: db.prepare(`SELECT value FROM ${table} WHERE key = ? AND ${live}`),
+		set: db.prepare(`INSERT INTO ${table} (key, value, expires_at) VALUES (?, ?, ${expiresAt})
+       ON CONFLICT (key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`),
+		delete: db.prepare(`DELETE FROM ${table} WHERE key = ?`),
+		increment: db.prepare(`INSERT INTO ${table} (key, value, expires_at) VALUES (?, ?, NULL)
+       ON CONFLICT (key) DO UPDATE SET
+         value = CASE WHEN ${table}.expires_at IS NOT NULL AND ${table}.expires_at <= ${NOW_MS}
+           THEN excluded.value ELSE CAST(${table}.value + ? AS TEXT) END,
+         expires_at = CASE WHEN ${table}.expires_at IS NOT NULL AND ${table}.expires_at <= ${NOW_MS}
+           THEN NULL ELSE ${table}.expires_at END
+       RETURNING value`),
+		expire: db.prepare(`UPDATE ${table} SET expires_at = ${expiresAt} WHERE key = ? AND ${live}`),
+		claim: db.prepare(`INSERT INTO ${table} (key, value, expires_at) VALUES (?, ?, ${expiresAt})
+       ON CONFLICT (key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at
+       WHERE ${table}.expires_at IS NOT NULL AND ${table}.expires_at <= ${NOW_MS}`),
+		replace: db.prepare(`UPDATE ${table} SET value = ?, expires_at = ${expiresAt} WHERE key = ? AND value = ? AND ${live}`),
+		sweep: db.prepare(`DELETE FROM ${table} WHERE expires_at IS NOT NULL AND expires_at <= ${NOW_MS}`)
+	};
+	/** Used-once keys (a delivery's idempotency key, a caller's window) expire and stay until swept: once a minute. */
+	let sweptAt = 0;
+	const sweep = () => {
+		if (Date.now() - sweptAt < 6e4) return;
+		sweptAt = Date.now();
+		statements.sweep.run();
+	};
+	const text = (row) => typeof row?.value === "string" ? row.value : void 0;
+	return {
+		get: (key) => Promise.resolve(text(statements.get.get(key))),
+		set: (key, value, ttlSeconds) => {
+			statements.set.run(key, value, expiry(ttlSeconds), expiry(ttlSeconds));
+			sweep();
+			return Promise.resolve();
+		},
+		delete: (key) => {
+			statements.delete.run(key);
+			return Promise.resolve();
+		},
+		increment: (key, amount) => {
+			const step = Number.isInteger(amount) ? BigInt(amount) : amount;
+			const value = text(statements.increment.get(key, String(amount), step));
+			sweep();
+			return Promise.resolve(Number(value ?? amount));
+		},
+		expire: (key, ttlSeconds) => {
+			statements.expire.run(expiry(ttlSeconds), expiry(ttlSeconds), key);
+			return Promise.resolve();
+		},
+		swap: (key, expected, next, ttlSeconds) => {
+			const written = expected === void 0 ? statements.claim.run(key, next, expiry(ttlSeconds), expiry(ttlSeconds)) : statements.replace.run(next, expiry(ttlSeconds), expiry(ttlSeconds), key, expected);
+			sweep();
+			return Promise.resolve(written.changes === 1);
+		}
+	};
+};
+//#endregion
+export { createSqliteKv };

package/dist/modules/sqlite/kv.test.d.ts

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

package/dist/modules/ssr/prepareRender.js

@@ -9,13 +9,14 @@ import { loadPluginComponents } from "./loadPluginComponents.js";
 import "../../core/previewToken.js";
 import { resolveActionEndpoint, resolveRscEndpoint } from "../../core/services/resolve.js";
 import { createOfflineDataLoader } from "../../helpers/offlineDataLoader.js";
+import { hydrationPayload, spaceDocument } from "../../helpers/hydrationPayload.js";
+import { publishSpaceDocument } from "./spaceDocument.js";
 import { registerExternalPlugins } from "./registerExternalPlugins.js";
 import { reportMissingPlugins } from "./reportMissingPlugins.js";
 import { resolvePageSeo } from "./resolvePageSeo.js";
 import { imagesPathOf } from "../../core/http/stages/images.js";
 import { sdkAssetVersion } from "../../core/sdkAssets.js";
 import { buildServerInfo } from "../../helpers/buildServerInfo.js";
-import { hydrationPayload } from "../../helpers/hydrationPayload.js";
 import { resolveDebugMode } from "../../helpers/resolveDebugMode.js";
 import { flagUserFromSSR, flagValues, resolveFlags } from "@plitzi/sdk-shared/flags";
 import { hasServerElements } from "@plitzi/sdk-shared/schema/serverElements";
@@ -23,6 +24,8 @@ import { debugCookieName } from "@plitzi/sdk-shared/devTools";
 import { themeFromCookies } from "@plitzi/sdk-shared/theme";
 import { paintedKeys, paintedStateFor } from "@plitzi/sdk-shared/state/paintedState";
 import { fontUrlResolver, fontsToHead } from "@plitzi/sdk-shared/style";
+import { pluginDeclarationOf, pluginTypesOf } from "@plitzi/sdk-shared/plugins/declaration";
+import { pageElementTypes } from "@plitzi/sdk-shared/schema/pageElements";
 //#region src/modules/ssr/prepareRender.tsx
 /** Last resort only: used for a page that declares no SEO title and a deployment that supplies none either. */
 var DEFAULT_TITLE = "Plitzi App";
@@ -36,6 +39,14 @@ var declaredTheme = (style) => {
 	const declared = style?.theme?.default;
 	return declared && declared !== "system" ? declared : void 0;
 };
+var declarations = /* @__PURE__ */ new WeakMap();
+var declarationOf = (component) => {
+	const known = declarations.get(component);
+	if (known) return known;
+	const declaration = pluginDeclarationOf(component);
+	declarations.set(component, declaration);
+	return declaration;
+};
 var prepareRender = async (req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics, offlineDataOverride) => {
 	const m = (name, fn) => metrics ? metrics.measure(name, fn) : Promise.resolve(fn());
 	const offlineCacheKey = environment !== "main" ? buildOfflineDataCacheKey(spaceId, environment, revision, req.ctx.spaceDeployment?.flagsVersion) : void 0;
@@ -147,6 +158,13 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	* page, so it hydrates with the flags it was drawn with.
 	*/
 	const { server: serverFlags, qa: forcedFlags } = flagOverrides;
+	/**
+	* The space travels beside the page rather than in it, fetched while the scripts are — see `spaceDocument`.
+	*
+	* 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 offlineDataStr = hydrationPayload(offlineData, {
 		offlineMode: true,
 		environment,
@@ -160,7 +178,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		...actionRuns ? { actionRuns } : {},
 		...serverFlags ? { serverFlags } : {},
 		...forcedFlags ? { forcedFlags } : {}
-	});
+	}, { apart: spaceDocumentPath !== void 0 });
 	const pluginNames = req.ctx.spaceDeployment?.pluginNames ?? [];
 	const pluginSources = req.ctx.spaceDeployment?.pluginSources;
 	const pluginBaseNames = new Set(pluginNames.map((n) => n.replace(/@[^@]*$/, "")));
@@ -178,10 +196,29 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	const entries = allPluginNames.length > 0 ? await pluginManager.getEntries(allPluginNames) : [];
 	const pluginComponents = await m("plugins", () => loadPluginComponents(entries, pluginManager.getComponents()));
 	reportMissingPlugins(spaceId, schema, /* @__PURE__ */ new Set([...Object.keys(pluginComponents), ...entries.map((entry) => entry.keyName)]));
-	const templatePlugins = (entries.length > 0 ? entries : req.ctx.spaceDeployment?.templateProps?.plugins)?.map((entry) => ({
-		...entry,
-		ssr: entry.keyName in pluginComponents
-	}));
+	const templateEntries = entries.length > 0 ? entries : req.ctx.spaceDeployment?.templateProps?.plugins;
+	/**
+	* The plugins this page draws none of: the browser is sent what they declare, and loads one when a page that draws
+	* it is opened. Their code is what the first paint waited on — a page of the website downloaded the builder's.
+	*
+	* Only one the server holds the component of can wait, since its declaration is read from it; a page matched to
+	* nothing, which cannot say what it draws, waits for none.
+	*/
+	const pageTypes = schema !== void 0 && pageMatch !== void 0 ? pageElementTypes(schema, pageMatch.pageId) : void 0;
+	const deferredOf = (entry) => {
+		const plugin = pageTypes && entry.js ? pluginComponents[entry.keyName] : void 0;
+		if (!plugin) return;
+		const declaration = declarationOf(plugin.component);
+		return pluginTypesOf(entry.keyName, declaration).some((type) => pageTypes?.has(type)) ? void 0 : declaration;
+	};
+	const templatePlugins = templateEntries?.map((entry) => {
+		const deferred = deferredOf(entry);
+		return {
+			...entry,
+			ssr: entry.keyName in pluginComponents,
+			...deferred ? { deferred } : {}
+		};
+	});
 	const vendorJs = (debugAuthorized ? "/sdk-assets/plitzi-sdk-dev-vendor.js" : "/sdk-assets/plitzi-sdk-vendor.js") + v;
 	return {
 		componentProps: {
@@ -202,6 +239,8 @@ 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}`,
+			spaceDocumentPath,
 			react: vendorJs,
 			reactJsx: vendorJs,
 			reactDom: vendorJs,

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

@@ -0,0 +1,25 @@
+import { TtlCache } from '../../helpers/cache';
+import { SpaceDocument } from '../../helpers/hydrationPayload';
+import { Environment, SSRPageServerConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/**
+ * The whole space as a resource of its own, beside the page rather than inside it.
+ *
+ * Embedded, it was most of every document — megabytes of a big space, before the first word of the page — and it was
+ * downloaded again on every page and every visit. Apart, the page arrives at the size of what it shows, and the space
+ * is fetched while the scripts are, once: its address is its content's hash, so it is kept until it changes.
+ *
+ * It is still the whole space: the server draws the first page, and every page after it is the browser's, with no
+ * server to ask.
+ */
+export declare const SPACE_DOCUMENT_PATH = "/_plitzi/space/";
+/** Where the page fetches `document` from — and the promise that this process can answer it. */
+export declare const publishSpaceDocument: (spaceId: number, environment: Environment, document: SpaceDocument) => string;
+/**
+ * Answers `/_plitzi/space/<hash>.json` for the space this host serves, behind the same gates as its pages.
+ *
+ * Every page of a space already carried all of it, so whoever may open one page may read this. A hash this process
+ * did not just publish is looked up from the space as it is now: the same text when another process published it,
+ * or the space as it changed since — answered all the same, since it is what the page will find on its next load,
+ * but not to be kept under a name that is not its own.
+ */
+export declare const handleSpaceDocument: (req: SSRRequest, res: SSRResponseHelpers, config: SSRPageServerConfig, offlineDataCache?: TtlCache<string>) => Promise<void>;