@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/modules/ssr/prepareRender.js

@@ -1,5 +1,7 @@
 import { authorizesDebugging } from "../../helpers/debugAuthorization.js";
+import { realtimeModuleFor } from "../realtime/index.js";
 import { matchRscPage } from "../rsc/matchRscPage.js";
+import { ssrPaintedCookieName } from "../../helpers/paintedCookie.js";
 import { readCookie } from "../../helpers/readCookie.js";
 import { buildOfflineDataCacheKey } from "../../helpers/cache/keys.js";
 import { loadPluginComponents } from "./loadPluginComponents.js";
@@ -7,18 +9,30 @@ import "../../core/previewToken.js";
 import { resolveActionEndpoint, resolveRscEndpoint } from "../../core/services/resolve.js";
 import { createOfflineDataLoader } from "../../helpers/offlineDataLoader.js";
 import { registerExternalPlugins } from "./registerExternalPlugins.js";
+import { reportMissingPlugins } from "./reportMissingPlugins.js";
 import { resolvePageSeo } from "./resolvePageSeo.js";
 import { sdkAssetVersion } from "../../core/sdkAssets.js";
 import { buildServerInfo } from "../../helpers/buildServerInfo.js";
-import { escapeJson } from "../../helpers/escapeJson.js";
+import { hydrationPayload } from "../../helpers/hydrationPayload.js";
 import { resolveDebugMode } from "../../helpers/resolveDebugMode.js";
 import { hasServerElements } from "@plitzi/sdk-shared/schema/serverElements";
 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";
 //#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";
+/**
+* The theme a space declares a first visit starts in, when it declares one other than `system`.
+*
+* `Partial`, because a style document written before themes existed has no `theme` at all, and a published space
+* is rendered from whatever document it was published with.
+*/
+var declaredTheme = (style) => {
+	const declared = style?.theme?.default;
+	return declared && declared !== "system" ? declared : void 0;
+};
 var prepareRender = async (req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics, offlineDataOverride) => {
 	const m = (name, fn) => metrics ? metrics.measure(name, fn) : Promise.resolve(fn());
 	const offlineCacheKey = environment !== "main" ? buildOfflineDataCacheKey(spaceId, environment, revision) : void 0;
@@ -44,7 +58,9 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	const server = buildServerInfo(req, config, {
 		rscPath,
 		rscData,
-		actionPath: resolveActionEndpoint(config)
+		actionPath: resolveActionEndpoint(config),
+		realtimePath: realtimeModuleFor(config)?.path,
+		realtimeTransport: realtimeModuleFor(config)?.transport
 	});
 	if (offlineDataOverride === void 0 && !cachedOfflineStr && offlineCacheKey && offlineData !== void 0) offlineDataCache?.set(offlineCacheKey, JSON.stringify(offlineData));
 	const version = config.assetVersion ?? sdkAssetVersion();
@@ -80,7 +96,6 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		...analytics,
 		firstViewCounted: true
 	} : void 0;
-	const branding = degrade ? true : void 0;
 	const overQuota = degrade ? true : void 0;
 	/**
 	* The visitor's theme, from the cookie the SDK writes it to.
@@ -93,23 +108,33 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	* `{{ theme.resolved }}` or gate a rule on the scheme, and a client that started at `system` while the server
 	* rendered `dark` would hydrate different markup and throw away the tree.
 	*
-	* Absent — a first visit — is not a problem to solve: nothing is stamped, `system` is what the provider starts
-	* at, and the stylesheet's media queries answer, which is exactly right.
+	* Absent — a first visit — the space's own default applies (`style.theme.default`), painted by the server like a
+	* choice would be. A default of `system` stamps nothing and the stylesheet's media queries answer, which is exactly
+	* right for a space that did not pick.
+	*/
+	const theme = themeFromCookies(req.headers.cookie) ?? declaredTheme(offlineData?.style);
+	/**
+	* The kept state the first paint depends on, from the cookie the SDK writes the space's `settings.paintedState` to.
+	*
+	* The theme's reasoning, for the space's own state: web storage is the browser's alone, so what a visitor chose — the
+	* tool a toolbar shows, their name in an avatar — would reach the page only after hydration, and be swapped in over
+	* the defaults the server drew. Read here, the server draws with it, and the page starts from the same values: it
+	* travels as the SDK's `state`, the starting `runtime.state`, in the render and in the payload alike, or the client
+	* would hydrate other markup. Only the keys the space declares, and only with `keepState` on.
 	*/
-	const theme = themeFromCookies(req.headers.cookie);
-	const offlineDataStr = escapeJson(JSON.stringify({
-		offlineData,
+	const paintedState = schema?.settings.keepState ? paintedStateFor(req.headers.cookie, ssrPaintedCookieName(req.headers.host), paintedKeys(schema.settings)) : void 0;
+	const offlineDataStr = hydrationPayload(offlineData, {
 		offlineMode: true,
 		environment,
 		renderMode: "raw",
 		server,
 		sdkDevToolsStylePath,
 		...theme ? { theme } : {},
+		...paintedState ? { state: paintedState } : {},
 		...clientAnalytics ? { analytics: clientAnalytics } : {},
-		...branding ? { branding } : {},
 		...overQuota ? { overQuota } : {},
 		...actionRuns ? { actionRuns } : {}
-	}));
+	});
 	const pluginNames = req.ctx.spaceDeployment?.pluginNames ?? [];
 	const pluginSources = req.ctx.spaceDeployment?.pluginSources;
 	const pluginBaseNames = new Set(pluginNames.map((n) => n.replace(/@[^@]*$/, "")));
@@ -118,7 +143,7 @@ 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)) : []).filter((k) => !pluginBaseNames.has(k.replace(/@[^@]*$/, "")));
+	const externalNamesFiltered = (config.autoLoadSchemaPlugins !== false ? await m("extPlugins", () => registerExternalPlugins(pluginManager, offlineData, { allowPrivateHosts: config.allowPrivatePluginHosts === true })) : []).filter((k) => !pluginBaseNames.has(k.replace(/@[^@]*$/, "")));
 	const allPluginNames = [
 		...pluginNames,
 		...dynamicNames,
@@ -126,6 +151,7 @@ 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
@@ -139,9 +165,9 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			environment: req.ctx.spaceDeployment?.environment ?? environment,
 			debugMode: debugRendered,
 			sdkDevToolsStylePath,
-			branding,
 			overQuota,
-			theme
+			theme,
+			...paintedState ? { state: paintedState } : {}
 		},
 		entries,
 		templateParams: {

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

@@ -1,7 +1,10 @@
+import { StoreMethods } from '../../core/server/fleet/channel';
 import { DraftStore, OfflineDataRaw, SSRRequest, SSRServerConfig } from '@plitzi/sdk-shared';
 /** The READ side of draft-preview: a render resolving a stashed draft from its token. The write side — applying
  *  unsaved operations and rendering the result — lives in `@plitzi/sdk-mcp`, which is what knows how to interpret an
  *  operation; a page-only deployment keeps this much and never loads that. */
+/** Every method of the store, for the copy a server's workers share (see `fleet/stores.ts`). */
+export declare const DRAFT_STORE_METHODS: StoreMethods<DraftStore>;
 /** In-memory draft store — the default when the consumer injects none. Fine for a single replica; a multi-replica
  *  deployment must inject a shared store so a preview URL resolves on any replica. */
 export declare const createMemoryDraftStore: () => DraftStore;

package/dist/modules/ssr/preview.js

@@ -3,16 +3,23 @@ import { PREVIEW_COOKIE, readDraftToken } from "../../core/previewToken.js";
 /** The READ side of draft-preview: a render resolving a stashed draft from its token. The write side — applying
 *  unsaved operations and rendering the result — lives in `@plitzi/sdk-mcp`, which is what knows how to interpret an
 *  operation; a page-only deployment keeps this much and never loads that. */
+/** Every method of the store, for the copy a server's workers share (see `fleet/stores.ts`). */
+var DRAFT_STORE_METHODS = {
+	put: true,
+	take: true,
+	drop: true
+};
 /** In-memory draft store — the default when the consumer injects none. Fine for a single replica; a multi-replica
 *  deployment must inject a shared store so a preview URL resolves on any replica. */
 var createMemoryDraftStore = () => {
 	const store = /* @__PURE__ */ new Map();
 	return {
-		put(token, data, { ttlMs, reusable = false }) {
+		put(token, data, { ttlMs, reusable = false, spaceId }) {
 			store.set(token, {
 				data,
 				expiresAt: Date.now() + ttlMs,
-				reusable
+				reusable,
+				spaceId
 			});
 		},
 		take(token) {
@@ -21,7 +28,8 @@ var createMemoryDraftStore = () => {
 			if (!hit.reusable || hit.expiresAt <= Date.now()) store.delete(token);
 			return hit.expiresAt > Date.now() ? {
 				data: hit.data,
-				reusable: hit.reusable
+				reusable: hit.reusable,
+				spaceId: hit.spaceId
 			} : void 0;
 		},
 		drop(token) {
@@ -39,10 +47,12 @@ var takeDraftOverride = async (req, config) => {
 	const token = readDraftToken(req);
 	if (!token || !config.draftStore) return;
 	const entry = await config.draftStore.take(token);
-	return entry ? {
-		...entry,
+	if (!entry || entry.spaceId !== req.ctx.spaceDeployment?.spaceId) return;
+	return {
+		data: entry.data,
+		reusable: entry.reusable,
 		token
-	} : void 0;
+	};
 };
 /** The `Set-Cookie` that carries a draft session through the rest of the visit. */
 var draftSessionCookie = (req, token, ttlMs) => [
@@ -54,4 +64,4 @@ var draftSessionCookie = (req, token, ttlMs) => [
 	...req.protocol === "https" ? ["Secure"] : []
 ].join("; ");
 //#endregion
-export { createMemoryDraftStore, draftSessionCookie, takeDraftOverride };
+export { DRAFT_STORE_METHODS, createMemoryDraftStore, draftSessionCookie, takeDraftOverride };

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

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

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

@@ -1,7 +1,12 @@
 import { PluginManager } from '../../plugins/manager';
 import { OfflineDataRaw } from '@plitzi/sdk-shared';
+/** Where a plugin may be read from: anywhere public, and — on a development machine only — a private address too. */
+type ManifestReach = {
+    allowPrivateHosts: boolean;
+};
 /**
  * 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().
  */
-export declare const registerExternalPlugins: (pluginManager: PluginManager, offlineData: OfflineDataRaw | undefined) => Promise<string[]>;
+export declare const registerExternalPlugins: (pluginManager: PluginManager, offlineData: OfflineDataRaw | undefined, reach?: ManifestReach) => Promise<string[]>;
+export {};

package/dist/modules/ssr/registerExternalPlugins.js

@@ -1,3 +1,6 @@
+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";
@@ -22,17 +25,17 @@ var readDiskEntry = async (dir, resource) => {
 var writeDiskEntry = async (dir, resource, entry) => {
 	try {
 		await fs.mkdir(dir, { recursive: true });
-		await fs.writeFile(cacheFilePath(dir, resource), JSON.stringify(entry), "utf-8");
+		await writeFileAtomic(cacheFilePath(dir, resource), JSON.stringify(entry));
 	} catch (err) {
-		console.warn(`[SSR] Failed to persist plugin manifest cache for ${resource}:`, err);
+		serverLog.warn("SSR", `Failed to persist plugin manifest cache for ${resource}`, err);
 	}
 };
-var fetchAndStore = async (dir, resource) => {
+var fetchAndStore = async (dir, resource, reach) => {
 	try {
 		const url = `${resource}/plugin-manifest.json`;
-		const res = await fetch(url);
+		const res = reach.allowPrivateHosts ? await fetch(url) : await fetchOutbound(fetch, new URL(url));
 		if (!res.ok) {
-			console.warn(`[SSR] Failed to fetch plugin manifest from ${url}: HTTP ${res.status}`);
+			serverLog.warn("SSR", `Failed to fetch plugin manifest from ${url}: HTTP ${res.status}`);
 			return null;
 		}
 		const manifest = await res.json();
@@ -44,24 +47,24 @@ var fetchAndStore = async (dir, resource) => {
 		await writeDiskEntry(dir, resource, entry);
 		return manifest;
 	} catch (err) {
-		console.warn(`[SSR] Error fetching plugin manifest from ${resource}:`, err);
+		serverLog.warn("SSR", `Error fetching plugin manifest from ${resource}`, err);
 		return null;
 	}
 };
-var revalidate = (dir, resource) => {
+var revalidate = (dir, resource, reach) => {
 	if (refreshing.has(resource)) return;
 	refreshing.add(resource);
-	fetchAndStore(dir, resource).finally(() => refreshing.delete(resource));
+	fetchAndStore(dir, resource, reach).finally(() => refreshing.delete(resource));
 };
-var fetchManifest = async (pluginManager, resource) => {
+var fetchManifest = async (pluginManager, resource, reach) => {
 	const dir = manifestCacheDir(pluginManager);
 	const cached = manifestCache.get(resource) ?? await readDiskEntry(dir, resource) ?? void 0;
 	if (cached) {
 		manifestCache.set(resource, cached);
-		if (cached.expiresAt <= Date.now()) revalidate(dir, resource);
+		if (cached.expiresAt <= Date.now()) revalidate(dir, resource, reach);
 		return cached.manifest;
 	}
-	return fetchAndStore(dir, resource);
+	return fetchAndStore(dir, resource, reach);
 };
 var resolveAssetUrl = (resource, asset) => {
 	if (asset.url) return asset.url;
@@ -74,13 +77,13 @@ var findAsset = (manifest, type, resource) => {
 	return main ? resolveAssetUrl(resource, main) ?? void 0 : void 0;
 };
 var isAbsoluteUrl = (url) => url.startsWith("http://") || url.startsWith("https://");
-var registerPlugin = async (pluginManager, plugin) => {
+var registerPlugin = async (pluginManager, plugin, reach) => {
 	if (!plugin.resource || !isAbsoluteUrl(plugin.resource)) return null;
-	const manifest = await fetchManifest(pluginManager, plugin.resource);
+	const manifest = await fetchManifest(pluginManager, plugin.resource, reach);
 	if (!manifest) return null;
 	const jsUrl = findAsset(manifest, "script", plugin.resource);
 	if (!jsUrl) {
-		console.warn(`[SSR] Plugin "${plugin.type}" has no JS asset in manifest, skipping`);
+		serverLog.warn("SSR", `Plugin "${plugin.type}" has no JS asset in manifest, skipping`);
 		return null;
 	}
 	const source = {
@@ -95,10 +98,10 @@ var registerPlugin = async (pluginManager, plugin) => {
 * 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().
 */
-var registerExternalPlugins = async (pluginManager, offlineData) => {
+var registerExternalPlugins = async (pluginManager, offlineData, reach = { allowPrivateHosts: false }) => {
 	const plugins = offlineData?.plugins;
 	if (!plugins || plugins.length === 0) return [];
-	return (await Promise.all(plugins.map((p) => registerPlugin(pluginManager, p)))).filter((k) => k !== null);
+	return (await Promise.all(plugins.map((p) => registerPlugin(pluginManager, p, reach)))).filter((k) => k !== null);
 };
 //#endregion
 export { registerExternalPlugins };

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

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

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

@@ -0,0 +1,9 @@
+import { Schema } from '@plitzi/sdk-shared';
+/**
+ * The plugin types a space renders that this server has nothing for — neither a component in the render nor a bundle
+ * for the browser. Each prints "Custom Component … Not Found" where the plugin should be, and nothing else anywhere
+ * says why, so it is said here: once per space and type, at `error`, because a visitor is looking at the placeholder.
+ *
+ * A `custom` element carrying its own `scriptUrl` loads itself in the browser and is not this server's to supply.
+ */
+export declare const reportMissingPlugins: (spaceId: number, schema: Schema | undefined, available: ReadonlySet<string>) => void;

package/dist/modules/ssr/reportMissingPlugins.js

@@ -0,0 +1,24 @@
+import { serverLog } from "../../helpers/serverLog.js";
+//#region src/modules/ssr/reportMissingPlugins.ts
+var reported = /* @__PURE__ */ new Set();
+/**
+* The plugin types a space renders that this server has nothing for — neither a component in the render nor a bundle
+* for the browser. Each prints "Custom Component … Not Found" where the plugin should be, and nothing else anywhere
+* says why, so it is said here: once per space and type, at `error`, because a visitor is looking at the placeholder.
+*
+* A `custom` element carrying its own `scriptUrl` loads itself in the browser and is not this server's to supply.
+*/
+var reportMissingPlugins = (spaceId, schema, available) => {
+	if (!schema || !serverLog.enabled("error")) return;
+	for (const element of Object.values(schema.flat)) {
+		const { renderType, isPlugin, scriptUrl } = element.attributes;
+		const loadsItself = isPlugin === true && typeof scriptUrl === "string" && scriptUrl !== "";
+		if (element.definition.type !== "custom" || typeof renderType !== "string" || renderType === "" || loadsItself) continue;
+		const key = `${spaceId}:${renderType}`;
+		if (available.has(renderType) || reported.has(key)) continue;
+		reported.add(key);
+		serverLog.error("SSR", `Space ${String(spaceId)} renders the plugin "${renderType}" (element "${element.id}"), and this server has none by that name, so the page shows "Custom Component ${renderType} Not Found". Register it in \`plugins\` and name it in the deployment's \`pluginNames\`.`);
+	}
+};
+//#endregion
+export { reportMissingPlugins };

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

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

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

@@ -1,5 +1,5 @@
-import { TtlCache } from '../../helpers/cache';
+import { CachedPage, TtlCache } from '../../helpers/cache';
 import { RequestMetrics } from '../../helpers/metrics';
 import { PluginManager } from '../../plugins/manager';
 import { Environment, OfflineDataRaw, SSRPageServerConfig, SSRRequest, SSRResponseHelpers, SSRTemplateFn } from '@plitzi/sdk-shared';
-export declare const streamBody: (req: SSRRequest, res: SSRResponseHelpers, config: SSRPageServerConfig, spaceId: number, environment: Environment, revision: number, renderFn: SSRTemplateFn, pluginManager: PluginManager, offlineDataCache?: TtlCache<string>, htmlCache?: TtlCache<string>, cacheKey?: string, metrics?: RequestMetrics, offlineDataOverride?: OfflineDataRaw) => Promise<void>;
+export declare const streamBody: (req: SSRRequest, res: SSRResponseHelpers, config: SSRPageServerConfig, spaceId: number, environment: Environment, revision: number, renderFn: SSRTemplateFn, pluginManager: PluginManager, offlineDataCache?: TtlCache<string>, htmlCache?: TtlCache<CachedPage>, cacheKey?: string, metrics?: RequestMetrics, offlineDataOverride?: OfflineDataRaw) => Promise<void>;

package/dist/modules/ssr/streamBody.js

@@ -30,7 +30,10 @@ var streamBody = async (req, res, config, spaceId, environment, revision, render
 				const tailBuf = Buffer.from(tail, "utf-8");
 				res.write(tailBuf);
 				res.end();
-				if (chunks && cacheKey && htmlCache) htmlCache.set(cacheKey, head + Buffer.concat(chunks).toString("utf-8") + tail);
+				if (chunks && cacheKey && htmlCache) htmlCache.set(cacheKey, {
+					html: head + Buffer.concat(chunks).toString("utf-8") + tail,
+					compressed: {}
+				});
 				resolve();
 				cb();
 			}

package/dist/modules/ssr/template.js

@@ -1,6 +1,6 @@
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 import fs from "node:fs";
-import path from "node:path";
 import ejs from "ejs";
 //#region src/modules/ssr/template.ts
 var __dirname = path.dirname(fileURLToPath(import.meta.url));

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

@@ -122,18 +122,21 @@
     <noscript>You need to enable JavaScript to run this app.</noscript>
     <div id="plitzi" class="plitzi-root-container"><%- locals.html || '' %></div>
     <% if (!locals.ssrOnly) { %>
+    <%# The payload is data, so it travels as JSON: parsing it as a JavaScript literal cost the browser several times
+        what JSON.parse does, on megabytes of it. Escaped by the server — no `<` reaches this block. %>
+    <script type="application/json" id="plitzi-ssr-data"><%- locals.offlineData || '{}' %></script>
     <script type="module">
       import { render } from '<%= locals.jsPath || '' %>';
       <% const activePlugins = (locals.plugins || []).filter(p => p.js); %>
-      <% if (activePlugins.length > 0) { %>
       <% for (const plugin of activePlugins) { %>
       import { default as <%= plugin.varName %> } from '<%= plugin.js %>';
       <% } %>
       const __plitziPlugins = { <%- activePlugins.map(p => `'${p.keyName}': {component: ${p.varName}, props: ${JSON.stringify(p.props)}, clientOnly: ${p.ssr === false}}`).join(', ') %> };
-      render('plitzi', <%- locals.offlineData || '{}' %>, __plitziPlugins, <%= locals.debugMode ? true : false %>, true);
-      <% } else { %>
-      render('plitzi', <%- locals.offlineData || '{}' %>, {}, <%= locals.debugMode ? true : false %>, true);
-      <% } %>
+      const __plitziData = document.getElementById('plitzi-ssr-data');
+      const __plitziParams = JSON.parse(__plitziData.textContent);
+      // Read once: the page would otherwise hold the space twice, as this text and as what it was parsed into.
+      __plitziData.remove();
+      render('plitzi', __plitziParams, __plitziPlugins, <%= locals.debugMode ? true : false %>, true);
     </script>
     <% } %>
   </body>

package/dist/mongo.d.ts

@@ -0,0 +1,25 @@
+/** Job queue and key/value helpers for a deployment that runs Mongo. Import them as `@plitzi/sdk-server/mongo`.
+ *
+ *  The scheduler and the workers are the package's; WHERE the jobs wait is the deployment's — `action.jobs.queue`
+ *  and `action.kv` are adapters, and the defaults keep everything in one process's memory. That is right for one
+ *  replica and wrong for two: each gets its own copy of every schedule, and the jobs a replica was holding go with it
+ *  when it stops. These are those adapters, already written for Mongo, over a database the deployment connects to
+ *  and owns:
+ *
+ *  ```ts
+ *  import { MongoClient } from 'mongodb';
+ *  import { createServer } from '@plitzi/sdk-server';
+ *  import { createMongoJobQueue, createMongoKv } from '@plitzi/sdk-server/mongo';
+ *
+ *  const db = new MongoClient(process.env.MONGO_URL).db('app');
+ *
+ *  createServer({
+ *    adapters,
+ *    action: { lookups, kv: createMongoKv({ db }), jobs: { queue: createMongoJobQueue({ db }) } }
+ *  });
+ *  ```
+ *
+ *  The package holds no connection and keeps no data of its own: it creates the indexes its queries need, in the
+ *  collections it is told to use. `mongodb` is an optional peer dependency, used for its types alone. */
+export { createMongoJobQueue, createMongoKv } from './modules/mongo';
+export type { MongoDbSource, MongoJobQueue, MongoJobQueueOptions, MongoKvOptions } from './modules/mongo';

package/dist/mongo.js

@@ -0,0 +1,3 @@
+import { createMongoJobQueue } from "./modules/mongo/jobQueue.js";
+import { createMongoKv } from "./modules/mongo/kv.js";
+export { createMongoJobQueue, createMongoKv };

package/dist/mysql.d.ts

@@ -22,5 +22,16 @@
  *  The tables are documented in `docs/auth/mysql-schema.md` — what each one is for, and what a deployment mapping
  *  its existing schema onto the adapters has to be able to answer. */
 export { createMysqlStore, mysqlSchemaStatements } from './modules/mysql';
+/**
+ *  The job queue and the key/value store server actions run on, for a deployment that keeps them in MySQL rather than
+ *  in one process's memory — which is what running more than one replica needs. They borrow connections from a pool
+ *  the deployment opened (`store.pool` works) and create their three tables on first use:
+ *
+ *  ```ts
+ *  createServer({ action: { lookups, kv: createMysqlKv({ pool }), jobs: { queue: createMysqlJobQueue({ pool }) } } });
+ *  ```
+ */
+export { createMysqlJobQueue, createMysqlKv, mysqlJobSchemaStatements, mysqlJobSchemaUpgrades } from './modules/mysql/jobs';
+export type { MysqlJobQueue, MysqlJobQueueOptions, MysqlKvOptions } from './modules/mysql/jobs';
 export { SCHEMA_VERSION, TABLE_NAMES, tableNames } from './modules/mysql';
 export type { AccountSeed, MysqlAdmin, MysqlConfig, IdentityStore, LinkedIdentity, MysqlStore, SessionStore, SessionSummary, SpaceTokenSeed, TableKey, Tables } from './modules/mysql';

package/dist/mysql.js

@@ -1,4 +1,7 @@
 import { TABLE_NAMES, tableNames } from "./modules/mysql/config.js";
 import { SCHEMA_VERSION } from "./modules/mysql/schema.js";
 import { createMysqlStore, mysqlSchemaStatements } from "./modules/mysql/index.js";
-export { SCHEMA_VERSION, TABLE_NAMES, createMysqlStore, mysqlSchemaStatements, tableNames };
+import { mysqlJobSchemaStatements, mysqlJobSchemaUpgrades } from "./modules/mysql/jobs/schema.js";
+import { createMysqlJobQueue } from "./modules/mysql/jobs/jobQueue.js";
+import { createMysqlKv } from "./modules/mysql/jobs/kv.js";
+export { SCHEMA_VERSION, TABLE_NAMES, createMysqlJobQueue, createMysqlKv, createMysqlStore, mysqlJobSchemaStatements, mysqlJobSchemaUpgrades, mysqlSchemaStatements, tableNames };

package/dist/oauth.js

@@ -1,10 +1,10 @@
+import { dropPending, getAccess, getClient, getPending, putCode, putPending } from "./core/oauth/records.js";
 import { AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, PROTECTED_RESOURCE_PATH, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, protectedResourceMetadata } from "./core/oauth/metadata.js";
 import { randomId, verifyChallenge } from "./core/oauth/pkce.js";
-import { dropPending, getAccess, getClient, getPending, putCode, putPending } from "./core/oauth/records.js";
 import { redirectToSignIn, redirectWithCode, redirectWithError, sendErrorJson, sendJson } from "./core/oauth/respond.js";
+import { handleRegister } from "./core/oauth/register.js";
 import { handleAuthorizeStart, handleAuthorizeSubmit } from "./core/oauth/authorize.js";
 import { bearerOf, sendChallenge } from "./core/oauth/challenge.js";
-import { handleRegister } from "./core/oauth/register.js";
 import { handleRevoke, handleToken } from "./core/oauth/token.js";
 import { createOAuthGuardStage, createOAuthStage } from "./core/http/stages/oauth.js";
 export { AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, PROTECTED_RESOURCE_PATH, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, bearerOf, createOAuthGuardStage, createOAuthStage, dropPending, getAccess, getClient, getPending, handleAuthorizeStart, handleAuthorizeSubmit, handleRegister, handleRevoke, handleToken, protectedResourceMetadata, putCode, putPending, randomId, redirectToSignIn, redirectWithCode, redirectWithError, sendChallenge, sendErrorJson, sendJson, verifyChallenge };

package/dist/plugins/compile.js

@@ -1,6 +1,7 @@
+import { writeFileAtomic } from "../helpers/atomicFile.js";
 import path from "node:path";
-import fs from "node:fs/promises";
 import esbuild from "esbuild";
+import fs from "node:fs/promises";
 //#region src/plugins/compile.ts
 var EXTERNAL = [
 	"react",
@@ -29,7 +30,8 @@ var ASSET_LOADERS = {
 	".woff2": "dataurl"
 };
 /**
-* Everything that went into the bundle, so a dev server can tell when any of it has moved on.
+* Everything that went into the bundle, so a server can tell when any of it has moved on: a dev server as it is
+* edited, and any server — a deployment — when it finds a bundle built from something else (its content digest).
 *
 * The entry file is one file and a plugin is a directory: a component edited beside its `index.ts` leaves the entry's
 * timestamp exactly where it was, and a watcher looking only at that never rebuilds. esbuild already knows the answer
@@ -52,10 +54,13 @@ var compilePlugin = async (jsPath, outDir, devMode = false) => {
 		minify: !devMode,
 		splitting: false,
 		logLevel: "warning",
-		metafile: devMode
+		metafile: true,
+		write: false
 	});
+	await fs.mkdir(outDir, { recursive: true });
+	await Promise.all(result.outputFiles.map((output) => writeFileAtomic(output.path, output.contents)));
 	return {
-		hasCSS: await fs.access(path.join(outDir, "index.css")).then(() => true).catch(() => false),
+		hasCSS: result.outputFiles.some((output) => path.basename(output.path) === "index.css"),
 		inputs: sourceInputs(result.metafile)
 	};
 };

package/dist/plugins/copy.js

@@ -1,13 +1,13 @@
+import { copyFileAtomic, writeFileAtomic } from "../helpers/atomicFile.js";
 import path from "node:path";
-import fs from "node:fs/promises";
 //#region src/plugins/copy.ts
 var copyPlugin = async (src, destDir, filename) => {
 	const dest = path.join(destDir, filename);
 	if (src.startsWith("http://") || src.startsWith("https://")) {
 		const res = await fetch(src);
 		if (!res.ok) throw new Error(`[SSR] Plugin fetch failed ${src}: ${res.status}`);
-		await fs.writeFile(dest, await res.text(), "utf-8");
-	} else await fs.copyFile(src, dest);
+		await writeFileAtomic(dest, await res.text());
+	} else await copyFileAtomic(src, dest);
 };
 //#endregion
 export { copyPlugin };

package/dist/plugins/manager.d.ts

@@ -14,9 +14,18 @@ export declare class PluginManager {
     hasPlugin(name: string): boolean;
     register(name: string, source: PluginSource): void;
     /**
-     * Registers a plugin only if it is not yet known under its effective key.
-     * Returns the effective key (`name@version` when version is set, `name` otherwise)
-     * so the caller can pass it directly to getEntries().
+     * Keeps a source a render names, and returns the key to pass to getEntries(): `name@version+<identity>`, or
+     * `name@<identity>` without a version.
+     *
+     * The identity is what the source IS — where its files are, how they are served, the props it carries — because a
+     * name and a version are only what its author said about it. Keyed on those alone, the first source to arrive held
+     * the key for as long as the process ran: a plugin published again under the same version kept its old, now missing
+     * URLs, and two spaces each with a `board@1.0.0` of their own were served whichever this process had met first.
+     * Worked out from the source rather than handed out in order of arrival, so every worker names one source the same
+     * way — the key is also the folder a built bundle is written to, and all of them share it.
+     *
+     * Never taken as what a bare name means: {@link resolveKey} answers for the plugins this server was set up with, not
+     * for whichever space rendered last.
      */
     ensure(name: string, source: PluginSource): string;
     /**
@@ -46,6 +55,18 @@ export declare class PluginManager {
      * `checkedAt` is stamped on the cached entry rather than kept in a second map, so it cannot outlive what it is about.
      */
     private isStaleInMemory;
+    /**
+     * Whether what a bundle on disk was built from reads differently now — asked once, when a process first finds the
+     * bundle, in production as much as in development.
+     *
+     * A version names a release, and a release is only as good as whoever bumps it: a deployment rebuilt from new source
+     * under the same version found last deployment's bundle in its cache folder and served it, with nothing anywhere
+     * saying so. The content decides instead. A bundle written before digests were recorded has none, and is built again
+     * once. What this server does not build from files — a download, a CDN, a component — is its version's business.
+     */
+    private contentChanged;
+    /** The local files a bundle is built from: what the compiler reported, or the files it was copied from. */
+    private inputsOf;
     private isStale;
     /**
      * The bundle's URL, stamped with when it was built.
@@ -68,10 +89,21 @@ export declare class PluginManager {
      */
     private toRemoteEntry;
     private isWebUrl;
+    /**
+     * Builds every registered plugin now rather than on first use. A primary does it before starting its workers, so
+     * the workers find each one built — instead of all of them compiling the same plugin into the same folder at once.
+     */
+    prepareAll(): Promise<void>;
     prepare(name: string): Promise<PluginEntry | null>;
     private build;
     getEntries(names: string[]): Promise<PluginEntry[]>;
     getComponents(): Record<string, unknown>;
+    /**
+     * Drops what this process remembers of a plugin — its entry, its failure, which version its name means — and
+     * leaves the disk alone. What an invalidation elsewhere in the fleet does here: that process removes the files,
+     * and each of the others only has to stop pointing at them.
+     */
+    forget(name?: string, version?: string): void;
     invalidate(name?: string, version?: string): Promise<void>;
     destroy(): void;
     private readMeta;