@plitzi/sdk-server 0.37.9 → 0.37.10

package/README.md

@@ -169,6 +169,7 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `devMode` | `boolean` | `false` | Enables development mode: appends `?dev` to esm.sh CDN URLs for React, and activates per-request timing metrics (see [Dev metrics](#dev-metrics)). Off, the process must run with `NODE_ENV=production` or React renders with its development build; the server says so once, at `error`. |
 | `assetVersion` | `string` | — | Cache-buster appended as `?v=<assetVersion>` to all default SDK asset URLs. Compute from file mtime or package version at startup. |
 | `cacheTtlMs` | `number` | `300000` | TTL in milliseconds for the SSR render cache. Set to `0` to disable. |
+| `flags` | `Record<string, boolean> \| ({ spaceId, environment }) => Record<string, boolean>` | — | This deployment's say over the spaces' feature flags: above what a space declares, below the SDK's `flags` prop and a tester's dev tools, and only for flags the space declares. A function answers per space. Server actions and RSC resolve with it too. See `docs/en/feature-flags.md` in the workspace. |
 | `loginPath` | `string \| false` | `'/auth/login'` | Path for the built-in login endpoint. Set to `false` to disable it entirely. |
 | `logoutPath` | `string \| false` | `'/auth/logout'` | Path for the built-in logout endpoint. Set to `false` to disable it entirely. |
 | `signIn` | `SSRSignInConfig` | — | Sign visitors in by redirect through an OAuth 2.1 authorization server: `GET /auth/sign-in?return=/x` registers this host as a client, sends the browser out with PKCE (state in a `__Host-` cookie), and `/auth/sign-in/callback` redeems the code server to server and hands the token to `exchangeCredential`, which makes the session here. Needs the `exchangeCredential` adapter. |
@@ -180,6 +181,7 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `allowPrivatePluginHosts` | `boolean` | `false` | Read a schema plugin from a private address (`localhost`, this server's own network). A plugin's address is typed by whoever edits a space, so leave it off anywhere but a development machine whose bucket is local. |
 | `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. |
 | `static` | `Record<string, string>` | — | URL prefix → filesystem path mappings for static file serving. |
+| `images` | `{ domains, cacheDir? }` | — | Pictures from other sites resized at `/_plitzi/img`, for an `image` to offer as a `srcset` (see [Images](#images)). |
 | `ssrOnly` | `boolean` | `false` | Omit client-side JS from the rendered page. Useful for verifying SSR HTML without hydration. |
 | `streaming` | `boolean` | `false` | Stream HTML to the browser incrementally to reduce TTFB. See [Streaming](#streaming). |
 | `middlewares` | `SSRMiddleware[]` | — | Array of custom middleware functions executed before the SSR renderer on every request (see [Custom middlewares](#custom-middlewares)). |
@@ -386,6 +388,21 @@ createServer({
 
 Static responses include `ETag`, `Last-Modified`, and `Cache-Control` headers. Subsequent requests with `If-None-Match` receive `304 Not Modified` when the file has not changed. JS, CSS, and font files are served with `Cache-Control: immutable`; all other assets use a 1-hour max-age.
 
+### Images
+
+```ts
+createServer({ images: { domains: ['images.example.com', '*.cdn.example.com'] }, adapters: { ... } });
+```
+
+An `image` whose `src` is another site's then offers the browser a `srcset` of widths this server makes (320 to 1920
+px) at `/_plitzi/img?url=…&w=…`, in AVIF or WebP when the browser takes them. Everything is kept on disk (`cacheDir`,
+default `.plitzi/images`): each original is downloaded once, and each size is made once from it. A week on, the kept
+files keep answering while the original is asked for with its `ETag` / `Last-Modified` — unchanged, nothing is resized
+again; changed, its sizes are made anew. A picture that could not be fetched is not asked for again for five minutes.
+Only the listed hosts are fetched, every redirect is held to the same
+list and to the rule every outbound request follows (no private network), and SVG is refused. Resizing needs `sharp`
+(an optional peer): without it pictures are passed through and kept, and the server says so once.
+
 ### Public directory
 
 Use `publicDir` to serve your own root-level files (e.g. `robots.txt`, `sitemap.xml`, `favicon.png`) without prefixes:

package/dist/adapters/cloudAdapters.d.ts

@@ -35,7 +35,8 @@ export type CloudAdaptersConfig = {
      * revisions, it has whatever the builder last saved.
      *
      * Pinned to a number, this deployment serves that exact version until somebody changes the config: a revision
-     * cannot change, so it is fetched once and kept for the life of the process. That is what a deployment wants
+     * cannot change, so it is fetched once and kept for the life of the process. Its feature flags are not part of it
+     * and still follow the environment — a flag turned in production reaches a pinned deployment too. That is what a deployment wants
      * when it rolls forward on its own schedule, or when it has to be able to say precisely what it is serving.
      *
      * Left out, it serves the **latest** revision of that environment and notices when a new one is published: a
@@ -52,8 +53,9 @@ export type CloudAdaptersConfig = {
      * - A **pinned revision** never expires. Expiring an immutable document on a timer would be paying for a
      *   question whose answer is already known.
      *
-     * So this paces exactly one thing: the "which revision is current" probe, in latest mode. Even then it never
-     * sits in front of a visitor — the copy already held is served while the probe runs behind it.
+     * So this paces exactly one thing: the probe — "which revision is current" in latest mode, and in both modes "what
+     * are the flags at", whose answer is a hash and whose flags are fetched only when it moved. It never sits in front
+     * of a visitor: the copy already held is served while the probe runs behind it.
      */
     cacheSeconds?: number;
     /** Where fetched spaces are kept. Omitted, they are kept in this process only — see {@link CloudSpaceCache}. */

package/dist/adapters/cloudAdapters.js

@@ -1,4 +1,6 @@
 import { serverLog } from "../helpers/serverLog.js";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
+import { schemaFromWire } from "@plitzi/sdk-shared/schema/wire";
 //#region src/adapters/cloudAdapters.ts
 /**
 * A space fetched from Plitzi, for a server that is not Plitzi's.
@@ -28,9 +30,10 @@ var SPACE_QUERY = `query InitQuery($environment: String!, $revision: Int) {
     schema {
       settings
       rsc
-      flat { id definition { label type initialState styleSelectors bindings interactions parentId rootId items runtime loadStrategy } attributes }
+      flat { id definition { label type initialState styleSelectors bindings interactions parentId rootId items runtime loadStrategy flag { name is } anchor } attributes }
       pages
       components
+      flags
       pageFolders { id name slug parentId }
       variables { name type value subValues { when value } }
     }
@@ -48,28 +51,19 @@ var SPACE_QUERY = `query InitQuery($environment: String!, $revision: Int) {
 var LATEST_REVISION_QUERY = `query SpaceLatestRevisionQuery($environment: String!) {
   SpaceLatestRevision(environment: $environment) {
     snapshot { revision }
+    flagsHash
   }
 }`;
 /**
-* GraphQL answers `flat` as a LIST; every reader of a schema indexes it BY ID (`schema.flat[pageId]`, and the same
-* for `parentId`/`rootId`/`items`). The two are the `SchemaRaw` and `Schema` types, and the conversion is the wire
-* format's whole difference from the runtime one.
-*
-* Without it nothing throws — an array is a perfectly good object — it just answers `undefined` to every lookup, so
-* the page router matches no page and every URL is a 404 on a space that fetched and parsed correctly.
+* The environment's feature flags. Asked only when the probe's `flagsHash` moved: flags change apart from revisions —
+* one set per environment, shared by every revision it serves — so they are fetched and kept on their own, and a flag
+* turned in production costs this deployment a few hundred bytes rather than the space again.
 */
-var byElementId = (flat) => {
-	if (!Array.isArray(flat)) return flat ?? {};
-	return flat.reduce((acum, element) => {
-		if (element.id) acum[element.id] = element;
-		return acum;
-	}, {});
-};
-/** The runtime shape of a schema: the wire's `flat` list, keyed. */
-var toSchema = (schema) => ({
-	...schema,
-	flat: byElementId(schema.flat)
-});
+var FLAGS_QUERY = `query SpaceFlagsQuery($environment: String!) {
+  SpaceFlags(environment: $environment) { flags hash }
+}`;
+/** What the shared cache holds under a flags key — written by this module, but read back from outside the process. */
+var isHeldFlags = (value) => isRecord(value) && typeof value.hash === "string" && isRecord(value.flags);
 /**
 * The `scope` claim, read without verifying anything.
 *
@@ -147,15 +141,74 @@ var createCloudAdapters = (config) => {
 		}, `space ${env}@${rev ?? "latest"}`))?.Space;
 		if (!space?.schema) return;
 		return {
-			schema: toSchema(space.schema),
+			schema: schemaFromWire(space.schema),
 			style: space.style,
 			plugins: space.plugins
 		};
 	};
-	const fetchLatestRevision = async (env) => {
-		return (await post(LATEST_REVISION_QUERY, { environment: env }, `latest revision of ${env}`))?.SpaceLatestRevision?.snapshot?.revision;
+	/** Which revision is current, and what the flags are at — one small question for both halves of a served space. */
+	const probe = async (env) => {
+		const answer = (await post(LATEST_REVISION_QUERY, { environment: env }, `latest revision of ${env}`))?.SpaceLatestRevision;
+		return {
+			revision: answer?.snapshot?.revision,
+			flagsHash: answer?.flagsHash ?? void 0
+		};
 	};
 	const cacheKey = (env, rev) => `plitzi:space:${env}:${rev}`;
+	const flagsCacheKey = (env) => `plitzi:flags:${env}`;
+	/** Each environment's flags as last fetched, and when the probe last confirmed them. */
+	const heldFlags = /* @__PURE__ */ new Map();
+	/** The flags this process last held, or — on a cold start — the shared cache's, so a restart with Plitzi down keeps
+	*  serving the flags it knew rather than the ones frozen into a cached revision. */
+	const restoreFlags = async (env) => {
+		if (heldFlags.has(env)) return;
+		try {
+			const stored = await cache?.get(flagsCacheKey(env));
+			const held = stored ? JSON.parse(stored) : void 0;
+			if (isHeldFlags(held)) heldFlags.set(env, {
+				...held,
+				checkedAt: 0
+			});
+		} catch {}
+	};
+	/** Brings the flags up to the hash the probe answered, fetching them only when it moved. A failed probe or fetch keeps
+	*  the flags already held. */
+	const syncFlags = async (env, hash) => {
+		if (hash === void 0) return;
+		const current = heldFlags.get(env);
+		if (current?.hash === hash) {
+			current.checkedAt = Date.now();
+			return;
+		}
+		const fetched = (await post(FLAGS_QUERY, { environment: env }, `flags of ${env}`))?.SpaceFlags;
+		if (!fetched) return;
+		heldFlags.set(env, {
+			...fetched,
+			checkedAt: Date.now()
+		});
+		await cache?.set(flagsCacheKey(env), JSON.stringify(fetched)).catch(() => void 0);
+	};
+	/** A served space with the flags held for its environment — the same object for the same pair, so the page server
+	*  serialises it once rather than per request. */
+	const combined = /* @__PURE__ */ new WeakMap();
+	const withFlags = (env, data) => {
+		const flags = heldFlags.get(env);
+		if (!flags) return data;
+		const known = combined.get(data);
+		if (known?.hash === flags.hash) return known.data;
+		const joined = {
+			...data,
+			schema: {
+				...data.schema,
+				flags: flags.flags
+			}
+		};
+		combined.set(data, {
+			hash: flags.hash,
+			data: joined
+		});
+		return joined;
+	};
 	const held = /* @__PURE__ */ new Map();
 	/** One request per key at a time: a burst of renders on a cold cache joins the first, it does not multiply it. */
 	const inFlight = /* @__PURE__ */ new Map();
@@ -203,7 +256,9 @@ var createCloudAdapters = (config) => {
 	* A probe that fails leaves `checkedAt` alone so the next request tries again, and leaves the held copy serving.
 	*/
 	const refreshLatest = async (env) => {
-		const current = await fetchLatestRevision(env);
+		await restoreFlags(env);
+		const { revision: current, flagsHash } = await probe(env);
+		await syncFlags(env, flagsHash);
 		const previous = held.get(env);
 		if (current === void 0) return previous?.data;
 		if (previous && previous.revision === current) {
@@ -213,10 +268,27 @@ var createCloudAdapters = (config) => {
 		return await loadRevision(env, current) ?? previous?.data;
 	};
 	/**
+	* A pinned revision's flags: waited for once — the first render must not go out with the flags frozen into the copy
+	* it fetched — and then checked behind the answer, on the window.
+	*/
+	const refreshPinnedFlags = async (env) => {
+		await restoreFlags(env);
+		const flags = heldFlags.get(env);
+		if (!flags) {
+			await syncFlags(env, (await probe(env)).flagsHash);
+			return;
+		}
+		if (Date.now() - flags.checkedAt >= cacheSeconds * 1e3) {
+			flags.checkedAt = Date.now();
+			probe(env).then(({ flagsHash }) => syncFlags(env, flagsHash)).catch(() => void 0);
+		}
+	};
+	/**
 	* The space, and how hard this deployment leans on Plitzi to get it.
 	*
 	* - **`main`**: read live, every time. It is being edited; a cached answer is a wrong one.
-	* - **A pinned revision**: from cache forever after the first read. It cannot change.
+	* - **A pinned revision**: from cache forever after the first read. It cannot change — its flags can, so they are
+	*   probed on the same window as the latest mode's revision, and fetched only when they moved.
 	* - **Latest**: the held copy is served immediately and a revision probe runs behind it once the window is up.
 	*   After the first render no page ever waits on Plitzi, and a failed probe or fetch changes nothing — the last
 	*   good copy keeps serving, because a self-hosted site going blank over somebody else's bad minute is not a
@@ -226,16 +298,21 @@ var createCloudAdapters = (config) => {
 		if (isLive(env)) return once(`live:${env}`, () => fetchSpace(env));
 		const pinned = rev ?? revision;
 		if (pinned !== void 0 && isPinned(env, pinned)) {
+			await refreshPinnedFlags(env);
 			const already = held.get(env);
-			return already?.revision === pinned ? already.data : loadRevision(env, pinned);
+			const data = already?.revision === pinned ? already.data : await loadRevision(env, pinned);
+			return data && withFlags(env, data);
 		}
 		const current = held.get(env);
-		if (!current) return refreshLatest(env);
+		if (!current) {
+			const data = await refreshLatest(env);
+			return data && withFlags(env, data);
+		}
 		if (Date.now() - current.checkedAt >= cacheSeconds * 1e3) {
 			current.checkedAt = Date.now();
 			refreshLatest(env).catch(() => void 0);
 		}
-		return current.data;
+		return withFlags(env, current.data);
 	};
 	/**
 	* Every request is this one space.
@@ -244,7 +321,7 @@ var createCloudAdapters = (config) => {
 	* builds two servers or supplies its own resolver — which is more honest than a lookup table that silently
 	* serves the wrong space when a domain is added and this is not.
 	*
-	* The revision it reports is the one actually being served, which in latest mode is whatever the last probe
+	* The revision it reports is the one actually being served, with what its flags are at, which in latest mode is whatever the last probe
 	* found: a deployment reading `at: { environment, revision }` must be told the version its page was built from,
 	* not the zero that means "whatever is live".
 	*/
@@ -255,18 +332,27 @@ var createCloudAdapters = (config) => {
 			environment,
 			revision: 0
 		};
-		if (isPinned(environment, revision)) return {
-			...deployment,
-			spaceId,
-			environment,
-			revision
+		const flagsVersion = () => {
+			const flags = heldFlags.get(environment);
+			return flags ? { flagsVersion: flags.hash } : {};
 		};
+		if (isPinned(environment, revision)) {
+			await refreshPinnedFlags(environment);
+			return {
+				...deployment,
+				spaceId,
+				environment,
+				revision,
+				...flagsVersion()
+			};
+		}
 		if (!held.has(environment)) await refreshLatest(environment);
 		return {
 			...deployment,
 			spaceId,
 			environment,
-			revision: held.get(environment)?.revision ?? 0
+			revision: held.get(environment)?.revision ?? 0,
+			...flagsVersion()
 		};
 	};
 	return {

package/dist/adapters/space/types.d.ts

@@ -20,6 +20,9 @@ export interface SpaceResolution {
     templateProps?: SSRTemplateProps;
     pluginNames?: string[];
     pluginSources?: Record<string, PluginSource>;
+    /** What the space's flags are at, when they change apart from its revisions — see `SSRSpaceDeployment.flagsVersion`.
+     *  Usually set by `decorate`, which runs on every request: a cached resolution would hold a stale one. */
+    flagsVersion?: string;
 }
 /** A resolver that has decided this request gets nothing, and that no later resolver should be asked. */
 export interface SpaceRefusal {

package/dist/core/configSeam.d.ts

@@ -0,0 +1,14 @@
+import { ActionDbDriver, ActionLookups, ActionsConfig } from '../modules/actions/types';
+import { ConnectorLookups } from '../modules/connectors/resolver';
+import { ActionLookupsConfig, ConnectorLookupsConfig } from '@plitzi/sdk-shared';
+/** The connector lookups a deployment configured, each manifest checked as it is read. One per config object. */
+export declare const connectorLookupsOf: (config: ConnectorLookupsConfig) => ConnectorLookups;
+/**
+ * The action lookups a deployment configured, each document checked as it is read. Asked for one, a document that is
+ * not one is refused; listed, it is left out and said, so one broken action does not take its space's schedule down.
+ */
+export declare const actionLookupsOf: (config: ActionLookupsConfig) => ActionLookups;
+/** The deployment's database drivers, each held to what a `db` task calls — or why one is not, as the server starts. */
+export declare const dbDriversOf: (drivers: readonly unknown[] | undefined) => ActionDbDriver[] | undefined;
+/** The deployment's functions config, held to what runs a space's code — or why it is not, as the server starts. */
+export declare const functionsConfigOf: (config: unknown) => ActionsConfig["functions"];

package/dist/core/configSeam.js

@@ -0,0 +1,114 @@
+import { serverLog } from "../helpers/serverLog.js";
+import { isActionDocument, validateActionDocument } from "@plitzi/sdk-shared/actions";
+import { isConnectorManifestDraft, validateConnectorManifest } from "@plitzi/sdk-shared/connectors";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
+//#region src/core/configSeam.ts
+/**
+* A guard that checks each object once: a deployment that caches what it reads hands back the same object on every
+* call, and a render must not pay for validating its action again.
+*/
+var checkedOnce = (guard) => {
+	const seen = /* @__PURE__ */ new WeakMap();
+	return (value) => {
+		if (!isRecord(value)) return false;
+		const known = seen.get(value);
+		if (known !== void 0) return known;
+		const valid = guard(value);
+		seen.set(value, valid);
+		return valid;
+	};
+};
+var isManifest = checkedOnce(isConnectorManifestDraft);
+var isDocument = checkedOnce(isActionDocument);
+/** What `getFunctions` answers: built by `@plitzi/sdk-server/functions` from a space's saved bundle, a live object. */
+var isSpaceFunctions = (value) => isRecord(value) && isRecord(value.bundle) && typeof value.bundle.id === "string" && typeof value.bundle.load === "function" && isRecord(value.manifest);
+/** Why a document is not one this server runs: the first problem its validator found, by where it is. */
+var firstProblem = (errors) => {
+	const first = errors.at(0);
+	if (!first) return "it is not a document";
+	return first.path ? `${first.path}: ${first.message}` : first.message;
+};
+var manifestFrom = (found, spaceId, connectorId) => {
+	if (found === void 0 || found === null) return;
+	if (!isManifest(found)) throw new Error(`Connector "${connectorId}" of space ${String(spaceId)} is not a manifest this server can run — ${firstProblem(validateConnectorManifest(found).errors)}`);
+	return {
+		...found,
+		id: connectorId
+	};
+};
+/** An action as a lookup found it: the entry, or why it is not one. */
+var readAction = (found) => {
+	const document = isRecord(found) ? found.document : void 0;
+	if (!isRecord(found) || typeof found.id !== "string") return { problem: "it has no id" };
+	return isDocument(document) ? { entry: {
+		id: found.id,
+		document
+	} } : { problem: firstProblem(validateActionDocument(document).errors) };
+};
+var connectorSeams = /* @__PURE__ */ new WeakMap();
+/** The connector lookups a deployment configured, each manifest checked as it is read. One per config object. */
+var connectorLookupsOf = (config) => {
+	const existing = connectorSeams.get(config);
+	if (existing) return existing;
+	const lookups = {
+		getConnector: async (spaceId, connectorId, at) => manifestFrom(await config.getConnector(spaceId, connectorId, at), spaceId, connectorId),
+		...config.getCredential ? { getCredential: config.getCredential } : {},
+		...config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}
+	};
+	connectorSeams.set(config, lookups);
+	return lookups;
+};
+/**
+* The action lookups a deployment configured, each document checked as it is read. Asked for one, a document that is
+* not one is refused; listed, it is left out and said, so one broken action does not take its space's schedule down.
+*/
+var actionLookupsOf = (config) => {
+	const { getConnector, getFunctions, listActions } = config;
+	return {
+		getAction: async (spaceId, actionId, at) => {
+			const found = await config.getAction(spaceId, actionId, at);
+			if (found === void 0 || found === null) return;
+			const read = readAction(found);
+			if ("problem" in read) throw new Error(`Action "${actionId}" of space ${String(spaceId)} is not a document this server can run — ${read.problem}`);
+			return read.entry;
+		},
+		...listActions ? { listActions: async (spaceId, at) => (await listActions(spaceId, at)).flatMap((found) => {
+			const read = readAction(found);
+			if ("problem" in read) {
+				serverLog.warn("actions", `An action of space ${String(spaceId)} is left out — ${read.problem}`);
+				return [];
+			}
+			return [read.entry];
+		}) } : {},
+		...config.listScheduledSpaces ? { listScheduledSpaces: config.listScheduledSpaces } : {},
+		...config.getCredential ? { getCredential: config.getCredential } : {},
+		...getConnector ? { getConnector: async (spaceId, connectorId, at) => manifestFrom(await getConnector(spaceId, connectorId, at), spaceId, connectorId) } : {},
+		...getFunctions ? { getFunctions: async (spaceId, at) => {
+			const found = await getFunctions(spaceId, at);
+			if (found === void 0 || found === null) return;
+			if (!isSpaceFunctions(found)) throw new Error(`The functions of space ${String(spaceId)} are not what @plitzi/sdk-server/functions builds for one`);
+			return found;
+		} } : {},
+		...config.getFlags ? { getFlags: config.getFlags } : {}
+	};
+};
+var isFunction = (value) => typeof value === "function";
+/** A driver as `createDbDrivers` builds one: the engine a credential names, and how to query it. */
+var isDbDriver = (value) => isRecord(value) && typeof value.engine === "string" && isFunction(value.query);
+/** The functions config as `@plitzi/sdk-server/functions` builds it: native definitions, a runner, ceilings. */
+var isFunctionsConfig = (value) => isRecord(value) && (value.native === void 0 || Array.isArray(value.native) && value.native.every(isRecord)) && (value.runner === void 0 || isRecord(value.runner) && isFunction(value.runner.describe) && isFunction(value.runner.invoke)) && (value.limits === void 0 || isRecord(value.limits));
+/** The deployment's database drivers, each held to what a `db` task calls — or why one is not, as the server starts. */
+var dbDriversOf = (drivers) => {
+	if (drivers === void 0) return;
+	const wrong = drivers.findIndex((driver) => !isDbDriver(driver));
+	if (wrong >= 0) throw new Error(`action.dbDrivers[${String(wrong)}] is not a database driver: it needs an \`engine\` and a \`query\` function.`);
+	return drivers.filter(isDbDriver);
+};
+/** The deployment's functions config, held to what runs a space's code — or why it is not, as the server starts. */
+var functionsConfigOf = (config) => {
+	if (config === void 0) return;
+	if (!isFunctionsConfig(config)) throw new Error("`functions` is not what @plitzi/sdk-server/functions configures: `native` definitions, a `runner` with `describe` and `invoke`, `limits`.");
+	return config;
+};
+//#endregion
+export { actionLookupsOf, connectorLookupsOf, dbDriversOf, functionsConfigOf };

package/dist/core/configSeam.test.d.ts

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

package/dist/core/createServer.js

@@ -1,3 +1,4 @@
+import { actionLookupsOf, connectorLookupsOf } from "./configSeam.js";
 import { actionsModuleFor } from "../modules/actions/moduleFor.js";
 import { connectorRscData } from "../modules/rsc/connectorRscData.js";
 import { createAuthApiStage } from "./http/stages/authApi.js";
@@ -12,8 +13,8 @@ import { createPageServer } from "./server/pageServer.js";
 *  A dedicated MCP server is `createServer` from `@plitzi/sdk-mcp` — it builds none of the render template,
 *  caches or plugin manager this one does. */
 /**
-* Fills in `getRscData` from whatever can produce a server element's data — `connectors`, `action.lookups`, or
-* both — when the deployment did not write one.
+* Fills in `getRscData` from whatever can produce a server element's data — `connectors`, `action.lookups`, the
+* files of `publicDir` — when the deployment did not write one.
 *
 * The lookups are already here and the assembly is entirely this package's — a resolver over `resolveRscData`.
 * Leaving it out meant every deployment passed the same lookups twice: once as config, for the write endpoint,
@@ -24,17 +25,22 @@ import { createPageServer } from "./server/pageServer.js";
 * with no configuration missing anywhere.
 */
 var withConnectorRsc = (config) => {
-	if (config.adapters.getRscData || !config.connectors && !config.action?.lookups) return config;
+	if (config.adapters.getRscData || !config.connectors && !config.action?.lookups && !config.publicDir) return config;
 	const resolved = {
 		...config,
 		adapters: { ...config.adapters }
 	};
 	const module = actionsModuleFor(resolved);
 	const actions = module && config.action?.lookups ? {
-		lookups: config.action.lookups,
+		lookups: actionLookupsOf(config.action.lookups),
 		module
 	} : void 0;
-	resolved.adapters.getRscData = connectorRscData(config.connectors, actions, config.rsc?.elementTimeoutMs);
+	resolved.adapters.getRscData = connectorRscData({
+		connectors: config.connectors ? connectorLookupsOf(config.connectors) : void 0,
+		actions,
+		publicDir: config.publicDir,
+		elementTimeoutMs: config.rsc?.elementTimeoutMs
+	});
 	return resolved;
 };
 /** The renewal stage in front of whatever else gates itself, when there is anywhere to renew. */

package/dist/core/createServer.publicData.test.d.ts

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

package/dist/core/freePort.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The first port from `preferred` up that nothing uses — for a development server, which should start beside
+ * whatever else is running rather than refuse to.
+ *
+ * Free means both that nothing answers there and that this process may listen there: a server bound to every
+ * address leaves `127.0.0.1` bindable on some systems, and a page server started beside it would never be reached —
+ * the other one would answer, with a `200` that looks like success. A deployment that sets its port does not need
+ * this: a fixed port that is taken is an error worth stopping for.
+ */
+export declare const freePort: (preferred: number, host?: string, attempts?: number) => Promise<number>;

package/dist/core/freePort.js

@@ -0,0 +1,36 @@
+import { connect, createServer } from "node:net";
+//#region src/core/freePort.ts
+/** Whether something already answers at `port` — the one test that sees a listener on every address, not just `host`. */
+var answers = (port, host) => new Promise((resolve) => {
+	const socket = connect({
+		port,
+		host
+	});
+	socket.once("connect", () => {
+		socket.destroy();
+		resolve(true);
+	});
+	socket.once("error", () => resolve(false));
+});
+/** Whether this process could listen at `port` on `host`. */
+var bindable = (port, host) => new Promise((resolve) => {
+	const probe = createServer();
+	probe.once("error", () => resolve(false));
+	probe.once("listening", () => probe.close(() => resolve(true)));
+	probe.listen(port, host);
+});
+/**
+* The first port from `preferred` up that nothing uses — for a development server, which should start beside
+* whatever else is running rather than refuse to.
+*
+* Free means both that nothing answers there and that this process may listen there: a server bound to every
+* address leaves `127.0.0.1` bindable on some systems, and a page server started beside it would never be reached —
+* the other one would answer, with a `200` that looks like success. A deployment that sets its port does not need
+* this: a fixed port that is taken is an error worth stopping for.
+*/
+var freePort = async (preferred, host = "127.0.0.1", attempts = 20) => {
+	for (let port = preferred; port < preferred + attempts; port += 1) if (!await answers(port, host) && await bindable(port, host)) return port;
+	throw new Error(`No free port between ${preferred} and ${preferred + attempts - 1} on ${host}. Set PORT to one.`);
+};
+//#endregion
+export { freePort };

package/dist/core/freePort.test.d.ts

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

package/dist/core/http/stages/images.d.ts

@@ -0,0 +1,6 @@
+import { Stage } from '../types';
+import { SSRServerConfig } from '@plitzi/sdk-shared';
+/** Where pictures are resized, when this server resizes them: published to the SDK, which builds every `srcset` on it. */
+export declare const imagesPathOf: (config: Pick<SSRServerConfig, "images">) => string | undefined;
+/** `/_plitzi/img?url=…&w=…` — a remote picture at one of the widths the SDK asks for. See `SSRImagesConfig`. */
+export declare const imagesStage: Stage;

package/dist/core/http/stages/images.js

@@ -0,0 +1,47 @@
+import { serverLog } from "../../../helpers/serverLog.js";
+import { createImageProxy } from "../../../modules/images/imageProxy.js";
+import { loadSharpTransform } from "../../../modules/images/transform.js";
+import path from "node:path";
+import { IMAGE_PATH } from "@plitzi/sdk-shared/helpers/images";
+//#region src/core/http/stages/images.ts
+/** Where pictures are resized, when this server resizes them: published to the SDK, which builds every `srcset` on it. */
+var imagesPathOf = (config) => config.images && config.images.domains.length > 0 ? IMAGE_PATH : void 0;
+/** One proxy per configuration, made on the first request: `sharp` is looked for once, and said once when missing. */
+var proxies = /* @__PURE__ */ new WeakMap();
+var proxyFor = (images) => {
+	const known = proxies.get(images);
+	if (known) return known;
+	const made = loadSharpTransform().then((transform) => {
+		if (!transform) serverLog.warn("IMAGES", "sharp is not installed: pictures are passed through and kept, not resized (npm i sharp).");
+		return createImageProxy({
+			domains: images.domains,
+			cacheDir: path.resolve(images.cacheDir ?? ".plitzi/images"),
+			fetch: globalThis.fetch,
+			transform
+		});
+	});
+	proxies.set(images, made);
+	return made;
+};
+/** `/_plitzi/img?url=…&w=…` — a remote picture at one of the widths the SDK asks for. See `SSRImagesConfig`. */
+var imagesStage = async (ctx) => {
+	const { images } = ctx.config;
+	if (!images || imagesPathOf(ctx.config) === void 0 || ctx.req.path !== IMAGE_PATH) return false;
+	if (ctx.req.method !== "GET" && ctx.req.method !== "HEAD") {
+		ctx.res.setStatus(405);
+		ctx.res.setHeader("Allow", "GET, HEAD");
+		ctx.res.send("Method not allowed");
+		return true;
+	}
+	const answer = await (await proxyFor(images))({
+		url: ctx.req.query.url,
+		width: ctx.req.query.w,
+		accept: ctx.req.headers.accept ?? ""
+	});
+	ctx.res.setStatus(answer.status);
+	for (const [name, value] of Object.entries(answer.headers)) ctx.res.setHeader(name, value);
+	ctx.res.send(answer.body);
+	return true;
+};
+//#endregion
+export { imagesPathOf, imagesStage };

package/dist/core/http/stages/images.test.d.ts

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

package/dist/core/server/fleet/channel.js

@@ -1,5 +1,5 @@
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/core/server/fleet/channel.ts
-var isRecord = (value) => typeof value === "object" && value !== null;
 /** The channel is shared with `node:cluster` and anything else the deployment sends: only these are ours. */
 var isFleetMessage = (value) => {
 	if (!isRecord(value)) return false;

package/dist/core/server/fleet/relay.js

@@ -1,5 +1,6 @@
 import { serverLog } from "../../../helpers/serverLog.js";
 import { broadcast, onBroadcast } from "./link.js";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/core/server/fleet/relay.ts
 /**
 * `server.cache` and `server.plugins` in a fleet, whose workers each keep their own: what one process is told, every
@@ -10,7 +11,6 @@ import { broadcast, onBroadcast } from "./link.js";
 * Code that runs in every process (a pub/sub subscription made where the server is created) is told N times; what
 * is relayed is safe to apply again, and cheap: it only drops entries from memory.
 */
-var isRecord = (value) => typeof value === "object" && value !== null;
 var PLUGIN_ACTIONS = [
 	"copy",
 	"compile",