@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/helpers/cache/keys.js

@@ -1,7 +1,21 @@
+import { ssrPaintedCookieName } from "../paintedCookie.js";
 import { readCookie } from "../readCookie.js";
 import { debugCookieName } from "@plitzi/sdk-shared/devTools";
 import { themeFromCookies } from "@plitzi/sdk-shared/theme";
 //#region src/helpers/cache/keys.ts
+/** The fields of an HTML key, in the order they are joined. */
+var HTML_KEY_FIELDS = [
+	"accessToken",
+	"spaceId",
+	"environment",
+	"revision",
+	"theme",
+	"painted",
+	"debugHidden",
+	"hostname",
+	"path",
+	"search"
+];
 /**
 * The key a rendered document is cached under.
 *
@@ -14,15 +28,43 @@ import { themeFromCookies } from "@plitzi/sdk-shared/theme";
 * one keyed — a space that switched dev tools on for its published site would otherwise hand the first visitor's
 * choice to the rest.
 *
-* Read from the request here rather than handed in, so a call site cannot key the page without it. Only those two
+* So is the kept state the first paint depends on (`settings.paintedState`): `prepareRender` renders with that cookie's
+* values, so a page drawn with one visitor's toolbar must not be served to the next. Keyed by its raw value — this
+* key does not know which keys a space declares, and a space that declares none has no such cookie to split on.
+*
+* Read from the request here rather than handed in, so a call site cannot key the page without it. Only those
 * cookies are read: keying the whole header would split the cache on every analytics cookie a visitor carries.
 */
 var buildHtmlCacheKey = (accessToken = "anonymous", spaceId, environment, revision, req) => {
-	const theme = themeFromCookies(req.headers.cookie) ?? "";
-	const debugHidden = readCookie(req.headers.cookie, debugCookieName(req.headers.host)) === "false" ? "debug-off" : "";
-	return `${accessToken}\0${spaceId ?? 1}\0${environment}\0${revision}\0${theme}\0${debugHidden}\0${req.hostname}\0${req.path}\0${req.search}`;
+	const fields = {
+		accessToken,
+		spaceId: String(spaceId ?? 1),
+		environment,
+		revision: String(revision),
+		theme: themeFromCookies(req.headers.cookie) ?? "",
+		painted: readCookie(req.headers.cookie, ssrPaintedCookieName(req.headers.host)) ?? "",
+		debugHidden: readCookie(req.headers.cookie, debugCookieName(req.headers.host)) === "false" ? "debug-off" : "",
+		hostname: req.hostname,
+		path: req.path,
+		search: req.search
+	};
+	return HTML_KEY_FIELDS.map((field) => fields[field]).join("\0");
+};
+/**
+* What an HTML key says about the page it holds, read by the one list that also writes it. `server.cache.invalidate`
+* filters on these; it used to split the key by positions of its own, and when the key grew a field in front the
+* filter went on reading the wrong ones — every invalidation by space matched nothing.
+*/
+var readHtmlCacheKey = (key) => {
+	const parts = key.split("\0");
+	const at = (field) => parts[HTML_KEY_FIELDS.indexOf(field)] ?? "";
+	return {
+		spaceId: at("spaceId"),
+		environment: at("environment"),
+		hostname: at("hostname")
+	};
 };
 var buildOfflineDataCacheKey = (spaceId, environment, revision) => `${spaceId}|${environment}|${revision}`;
 var buildRscCacheKey = (spaceId, environment, revision, userId, idsParam, req) => `${spaceId}\0${environment}\0${revision}\0${userId ?? "anon"}\0${idsParam ?? ""}\0${req.hostname}\0${req.path}\0${req.search}`;
 //#endregion
-export { buildHtmlCacheKey, buildOfflineDataCacheKey, buildRscCacheKey };
+export { buildHtmlCacheKey, buildOfflineDataCacheKey, buildRscCacheKey, readHtmlCacheKey };

package/dist/helpers/cache/serverCaches.d.ts

@@ -1,6 +1,12 @@
 import { TtlCache } from './TtlCache';
+import { CompressedBodies } from '@plitzi/sdk-shared';
+/** A rendered page, and the compressed forms of it that have been sent — kept together, so they expire together. */
+export type CachedPage = {
+    html: string;
+    compressed: CompressedBodies;
+};
 export type ServerCaches = {
-    html: TtlCache<string> | undefined;
+    html: TtlCache<CachedPage> | undefined;
     rsc: TtlCache<string> | undefined;
     /** JSON-serialized OfflineDataRaw — keyed by spaceId|env|revision, same TTL as html. */
     offlineData: TtlCache<string> | undefined;

package/dist/helpers/compress.d.ts

@@ -5,6 +5,7 @@ export declare const DEFAULT_COMPRESSION: {
     encodings: ("br" | "gzip")[];
     threshold: number;
     brotliQuality: number;
+    keptBrotliQuality: number;
     gzipLevel: number;
 };
 export type ResolvedCompression = typeof DEFAULT_COMPRESSION;
@@ -15,4 +16,5 @@ export type ResolvedCompression = typeof DEFAULT_COMPRESSION;
 export declare const resolveCompression: (config?: SSRCompressionConfig | false) => ResolvedCompression;
 /** The first encoding this server prefers that the client actually takes. `*` counts as taking anything. */
 export declare const selectEncoding: (acceptEncoding: string | undefined, compression?: ResolvedCompression) => ContentEncoding;
-export declare const compressBody: (body: string, encoding: ContentEncoding, compression?: ResolvedCompression) => Buffer | string;
+/** `kept`: the result is stored and served again, so it is worth compressing harder once. */
+export declare const compressBody: (body: string, encoding: ContentEncoding, compression?: ResolvedCompression, kept?: boolean) => Buffer | string;

package/dist/helpers/compress.js

@@ -4,7 +4,8 @@ import { brotliCompressSync, constants, gzipSync } from "node:zlib";
 var DEFAULT_COMPRESSION = {
 	encodings: ["br", "gzip"],
 	threshold: 1024,
-	brotliQuality: 4,
+	brotliQuality: 2,
+	keptBrotliQuality: 6,
 	gzipLevel: 6
 };
 /**
@@ -43,10 +44,17 @@ var selectEncoding = (acceptEncoding, compression = DEFAULT_COMPRESSION) => {
 	const accepted = acceptedEncodings(acceptEncoding);
 	return compression.encodings.find((encoding) => accepted.has(encoding) || accepted.has("*")) ?? "identity";
 };
-var compressBody = (body, encoding, compression = DEFAULT_COMPRESSION) => {
+/** `kept`: the result is stored and served again, so it is worth compressing harder once. */
+var compressBody = (body, encoding, compression = DEFAULT_COMPRESSION, kept = false) => {
 	if (encoding === "identity" || body.length < compression.threshold) return body;
 	const buf = Buffer.from(body, "utf-8");
-	if (encoding === "br") return brotliCompressSync(buf, { params: { [constants.BROTLI_PARAM_QUALITY]: compression.brotliQuality } });
+	if (encoding === "br") {
+		const quality = kept ? compression.keptBrotliQuality : compression.brotliQuality;
+		return brotliCompressSync(buf, { params: {
+			[constants.BROTLI_PARAM_QUALITY]: quality,
+			[constants.BROTLI_PARAM_SIZE_HINT]: buf.length
+		} });
+	}
 	return gzipSync(buf, { level: compression.gzipLevel });
 };
 //#endregion

package/dist/helpers/hydrationPayload.d.ts

@@ -0,0 +1,11 @@
+import { OfflineDataRaw } from '@plitzi/sdk-shared';
+/**
+ * What the page's bootstrap reads: `{ offlineData, ...rest }` as escaped JSON, byte for byte what serializing the
+ * whole object would give. The escaping replaces characters one by one, so escaping the parts and joining them is
+ * the same as escaping the whole.
+ *
+ * The compiled stylesheet is left out when the page's own runtime stylesheet carries it in a form the browser reads
+ * back exactly (`styleCacheTravelsInDocument`), and `styleCacheInDocument` tells the bootstrap to. It is the largest
+ * part of the style document, and the page would otherwise ship it twice.
+ */
+export declare const hydrationPayload: (offlineData: OfflineDataRaw | undefined, rest: Record<string, unknown>) => string;

package/dist/helpers/hydrationPayload.js

@@ -0,0 +1,51 @@
+import { escapeJson } from "./escapeJson.js";
+import { styleCacheTravelsInDocument } from "@plitzi/sdk-shared/style";
+//#region src/helpers/hydrationPayload.ts
+var serializedSpaces = /* @__PURE__ */ new WeakMap();
+/**
+* The space as the page embeds it, serialized once per space object rather than once per render.
+*
+* It is most of the payload — tens of kilobytes of schema and style — and the adapters hand every request the same
+* object until the space changes, so turning it into escaped JSON on each render was a tenth of a render's CPU spent
+* producing the same string. Keyed weakly: a space the adapters let go of takes its string with it.
+*/
+var serializeSpace = (offlineData, withoutStyleCache) => {
+	let serialized = serializedSpaces.get(offlineData);
+	if (!serialized) {
+		serialized = {};
+		serializedSpaces.set(offlineData, serialized);
+	}
+	if (withoutStyleCache) {
+		serialized.withoutStyleCache ??= escapeJson(JSON.stringify({
+			...offlineData,
+			style: {
+				...offlineData.style,
+				cache: ""
+			}
+		}));
+		return serialized.withoutStyleCache;
+	}
+	serialized.whole ??= escapeJson(JSON.stringify(offlineData));
+	return serialized.whole;
+};
+/**
+* What the page's bootstrap reads: `{ offlineData, ...rest }` as escaped JSON, byte for byte what serializing the
+* whole object would give. The escaping replaces characters one by one, so escaping the parts and joining them is
+* the same as escaping the whole.
+*
+* The compiled stylesheet is left out when the page's own runtime stylesheet carries it in a form the browser reads
+* back exactly (`styleCacheTravelsInDocument`), and `styleCacheInDocument` tells the bootstrap to. It is the largest
+* part of the style document, and the page would otherwise ship it twice.
+*/
+var hydrationPayload = (offlineData, rest) => {
+	const inDocument = offlineData !== void 0 && styleCacheTravelsInDocument(offlineData.style.cache);
+	const serializedRest = escapeJson(JSON.stringify(inDocument ? {
+		...rest,
+		styleCacheInDocument: true
+	} : rest));
+	if (offlineData === void 0) return serializedRest;
+	const separator = serializedRest === "{}" ? "" : ",";
+	return `{"offlineData":${serializeSpace(offlineData, inDocument)}${separator}${serializedRest.slice(1)}`;
+};
+//#endregion
+export { hydrationPayload };

package/dist/helpers/hydrationPayload.test.d.ts

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

package/dist/helpers/metrics.d.ts

@@ -6,6 +6,6 @@ export declare class RequestMetrics {
     /** Formats as Server-Timing header value. */
     toServerTimingHeader(): string;
     record(name: string, dur: number): void;
-    /** Logs a one-line summary to stdout (dev mode only). */
+    /** Logs a one-line summary at `debug`. */
     log(label: string): void;
 }

package/dist/helpers/metrics.js

@@ -1,3 +1,4 @@
+import { serverLog } from "./serverLog.js";
 //#region src/helpers/metrics.ts
 var RequestMetrics = class {
 	start;
@@ -25,11 +26,11 @@ var RequestMetrics = class {
 			dur
 		});
 	}
-	/** Logs a one-line summary to stdout (dev mode only). */
+	/** Logs a one-line summary at `debug`. */
 	log(label) {
 		const total = Math.round(performance.now() - this.start);
 		const parts = this.phases.map((p) => `${p.name}=${p.dur}ms`).join(" ");
-		console.log(`[SSR] ${label} — ${parts} | total=${total}ms`);
+		serverLog.debug("SSR", `${label} — ${parts} | total=${total}ms`);
 	}
 };
 //#endregion

package/dist/helpers/outboundGuard.d.ts

@@ -1,12 +1,9 @@
 /**
- * Where a customer-authored request may go.
+ * Whether a hostname — or an address a name resolved to — may never be the other end of an authored request.
  *
- * Two things reach the outside world on somebody else's say-so: the `http.request` task, whose URL is typed into
- * a flow, and the connector engine, whose `baseUrl` is typed into a manifest. Both run inside the cluster, from a
- * trusted network position, which is what turns "fetch this URL for me" into a way to read the instance's cloud
- * credentials at `169.254.169.254` or talk to Redis on `localhost`. One rule, in one place, for both of them.
+ * A NAME is only refused for what it says it is (`localhost`, `*.internal`); anything else about a name is decided by
+ * what it resolves to, in `assertOutboundAllowed`.
  */
-/** Literal forms an authored URL can hold, and the ones this refuses outright. */
 export declare const isBlockedHost: (hostname: string) => boolean;
 export type HostLookup = (hostname: string) => Promise<{
     address: string;
@@ -25,3 +22,14 @@ export type HostLookup = (hostname: string) => Promise<{
  * only by resolving and connecting to the same address, and that belongs in the transport rather than here.
  */
 export declare const assertOutboundAllowed: (url: URL, lookup?: HostLookup) => Promise<void>;
+/**
+ * Sends an authored request, judging EVERY hop it takes by `assertOutboundAllowed`.
+ *
+ * Checking the URL and handing it to `fetch` judged only the first hop: `fetch` follows redirects on its own, so a
+ * public server answering `302 Location: http://169.254.169.254/` took the request wherever it liked. Redirects are
+ * therefore taken manually and each destination is checked before anything is sent to it.
+ *
+ * `base` is the caller's own transport — the action runner's is budgeted and capped — so every hop is also counted
+ * against whatever that transport enforces.
+ */
+export declare const fetchOutbound: (base: typeof fetch, url: URL, init?: RequestInit, lookup?: HostLookup) => Promise<Response>;

package/dist/helpers/outboundGuard.js

@@ -1,4 +1,5 @@
 import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
 //#region src/helpers/outboundGuard.ts
 /**
 * Where a customer-authored request may go.
@@ -8,14 +9,64 @@ import { lookup } from "node:dns/promises";
 * trusted network position, which is what turns "fetch this URL for me" into a way to read the instance's cloud
 * credentials at `169.254.169.254` or talk to Redis on `localhost`. One rule, in one place, for both of them.
 */
-/** Literal forms an authored URL can hold, and the ones this refuses outright. */
+/**
+* Every range that is never a public peer, as ranges rather than string patterns.
+*
+* A `BlockList` also judges an IPv4-mapped IPv6 address (`::ffff:7f00:1`) against the IPv4 rules, which is the form a
+* URL parser turns `[::ffff:127.0.0.1]` into and a dual-stack socket happily connects to loopback. The prefix
+* patterns this replaced matched neither that nor `::`, and matched DNS names that merely began with `fc` or `fe8`.
+*/
+var privateRanges = new BlockList();
+var IPV4_RANGES = [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+];
+var IPV6_RANGES = [
+	["::", 96],
+	["64:ff9b:1::", 48],
+	["fc00::", 7],
+	["fe80::", 10],
+	["ff00::", 8]
+];
+/** An IPv4 address as the two 16-bit groups it occupies inside an IPv6 one. */
+var ipv4Groups = (address) => {
+	const [a = 0, b = 0, c = 0, d = 0] = address.split(".").map(Number);
+	return [(a << 8 | b).toString(16), (c << 8 | d).toString(16)];
+};
+/**
+* The same private IPv4 ranges where IPv6 carries an IPv4 address inside it.
+*
+* NAT64 (`64:ff9b::/96`) is how an IPv6-only cluster reaches EVERY IPv4 host — DNS64 answers a public API with an address
+* in it — so the prefix cannot be refused whole; what it carries is judged instead. 6to4 (`2002::/16`) carries its
+* address in bits 16–47.
+*/
+var EMBEDDED_IPV4_RANGES = IPV4_RANGES.flatMap(([network, prefix]) => {
+	const [high, low] = ipv4Groups(network);
+	return [[`64:ff9b::${high}:${low}`, 96 + prefix], [`2002:${high}:${low}::`, 16 + prefix]];
+});
+IPV4_RANGES.forEach(([network, prefix]) => privateRanges.addSubnet(network, prefix, "ipv4"));
+[...IPV6_RANGES, ...EMBEDDED_IPV4_RANGES].forEach(([network, prefix]) => privateRanges.addSubnet(network, prefix, "ipv6"));
+var isBlockedName = (host) => host === "localhost" || host.endsWith(".localhost") || host.endsWith(".internal");
+/**
+* Whether a hostname — or an address a name resolved to — may never be the other end of an authored request.
+*
+* A NAME is only refused for what it says it is (`localhost`, `*.internal`); anything else about a name is decided by
+* what it resolves to, in `assertOutboundAllowed`.
+*/
 var isBlockedHost = (hostname) => {
-	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-	if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".internal") || host === "::1") return true;
-	const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
-	if (!ipv4) return /^f[cd]/.test(host) || host.startsWith("fe8") || host.startsWith("fe9") || /^fe[ab]/.test(host);
-	const [a = 0, b = 0] = ipv4.slice(1).map((part) => Number.parseInt(part, 10));
-	return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
+	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+	const family = isIP(host);
+	if (family === 0) return isBlockedName(host);
+	return privateRanges.check(host, family === 6 ? "ipv6" : "ipv4");
 };
 var resolveAll = (hostname) => lookup(hostname, {
 	all: true,
@@ -45,5 +96,78 @@ var assertOutboundAllowed = async (url, lookup = resolveAll) => {
 	}
 	if (addresses.some(({ address }) => isBlockedHost(address))) throw new Error("Request host is not allowed");
 };
+var MAX_REDIRECTS = 5;
+var REDIRECT_STATUSES = [
+	301,
+	302,
+	303,
+	307,
+	308
+];
+/** What the Fetch standard strips when a redirect leaves the origin that was given them. */
+var CROSS_ORIGIN_HEADERS = [
+	"authorization",
+	"cookie",
+	"proxy-authorization"
+];
+var BODY_HEADERS = [
+	"content-type",
+	"content-length",
+	"content-encoding",
+	"content-language",
+	"content-location"
+];
+/**
+* The request a redirect continues as — the rules `fetch` itself follows, applied by hand because it no longer does.
+*
+* A 303, and a 301/302 answering a POST, become a bodiless GET; 307 and 308 repeat the request exactly. Leaving the
+* origin drops the headers the Fetch standard drops, and only those: a key the author put in a header of its own
+* travels on as it did before, and the author already decides where it is sent.
+*/
+var redirectedInit = (init, status, crossOrigin) => {
+	const method = (init.method ?? "GET").toUpperCase();
+	const becomesGet = status === 303 && method !== "HEAD" || (status === 301 || status === 302) && method === "POST";
+	const headers = new Headers(init.headers);
+	if (crossOrigin) CROSS_ORIGIN_HEADERS.forEach((name) => headers.delete(name));
+	if (!becomesGet) return {
+		...init,
+		headers
+	};
+	BODY_HEADERS.forEach((name) => headers.delete(name));
+	return {
+		...init,
+		method: "GET",
+		body: void 0,
+		headers
+	};
+};
+/**
+* Sends an authored request, judging EVERY hop it takes by `assertOutboundAllowed`.
+*
+* Checking the URL and handing it to `fetch` judged only the first hop: `fetch` follows redirects on its own, so a
+* public server answering `302 Location: http://169.254.169.254/` took the request wherever it liked. Redirects are
+* therefore taken manually and each destination is checked before anything is sent to it.
+*
+* `base` is the caller's own transport — the action runner's is budgeted and capped — so every hop is also counted
+* against whatever that transport enforces.
+*/
+var fetchOutbound = async (base, url, init = {}, lookup = resolveAll) => {
+	let target = url;
+	let request = init;
+	for (let hop = 0;; hop += 1) {
+		await assertOutboundAllowed(target, lookup);
+		const response = await base(target.toString(), {
+			...request,
+			redirect: "manual"
+		});
+		const location = response.headers.get("location");
+		if (!REDIRECT_STATUSES.includes(response.status) || !location) return response;
+		await response.body?.cancel();
+		if (hop >= MAX_REDIRECTS) throw new Error(`Request followed more than ${MAX_REDIRECTS} redirects`);
+		const next = new URL(location, target);
+		request = redirectedInit(request, response.status, next.origin !== target.origin);
+		target = next;
+	}
+};
 //#endregion
-export { assertOutboundAllowed, isBlockedHost };
+export { assertOutboundAllowed, fetchOutbound, isBlockedHost };

package/dist/helpers/paintedCookie.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The name the painted state of a server-rendered page is kept under, for this request's host.
+ *
+ * The page this server sends carries no `webKey`, so the SDK keeps its state under the web id an empty key decodes to —
+ * the same one its web storage key uses. One helper for both readers of the cookie, the render and the HTML cache key,
+ * so they cannot come to disagree about which cookie the page was drawn from.
+ */
+export declare const ssrPaintedCookieName: (host: string | undefined) => string;

package/dist/helpers/paintedCookie.js

@@ -0,0 +1,13 @@
+import { getKeyDecoded } from "@plitzi/sdk-shared/helpers/utils";
+import { paintedStateCookieName } from "@plitzi/sdk-shared/state/paintedState";
+//#region src/helpers/paintedCookie.ts
+/**
+* The name the painted state of a server-rendered page is kept under, for this request's host.
+*
+* The page this server sends carries no `webKey`, so the SDK keeps its state under the web id an empty key decodes to —
+* the same one its web storage key uses. One helper for both readers of the cookie, the render and the HTML cache key,
+* so they cannot come to disagree about which cookie the page was drawn from.
+*/
+var ssrPaintedCookieName = (host) => paintedStateCookieName(getKeyDecoded("", true), host);
+//#endregion
+export { ssrPaintedCookieName };

package/dist/helpers/reportReactBuild.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Says, once per process, that a production server is rendering with React's development build.
+ *
+ * React picks its build from `NODE_ENV` when it is first imported, not from anything a server is configured with, so
+ * `devMode: false` without `NODE_ENV=production` renders every page with the development build — measured at about 40%
+ * fewer pages a second. An `error` because it is the only level a production server shows, and a deployment that
+ * never sees this line never learns why it needs twice the CPU.
+ */
+export declare const reportReactBuild: (devMode: boolean | undefined, nodeEnv?: string | undefined) => void;

package/dist/helpers/reportReactBuild.js

@@ -0,0 +1,18 @@
+import { serverLog } from "./serverLog.js";
+//#region src/helpers/reportReactBuild.ts
+var reported = false;
+/**
+* Says, once per process, that a production server is rendering with React's development build.
+*
+* React picks its build from `NODE_ENV` when it is first imported, not from anything a server is configured with, so
+* `devMode: false` without `NODE_ENV=production` renders every page with the development build — measured at about 40%
+* fewer pages a second. An `error` because it is the only level a production server shows, and a deployment that
+* never sees this line never learns why it needs twice the CPU.
+*/
+var reportReactBuild = (devMode, nodeEnv = process.env.NODE_ENV) => {
+	if (reported || devMode || nodeEnv === "production") return;
+	reported = true;
+	serverLog.error("server", `NODE_ENV is ${nodeEnv === void 0 ? "unset" : `"${nodeEnv}"`}: React renders with its development build. Start the process with NODE_ENV=production.`);
+};
+//#endregion
+export { reportReactBuild };

package/dist/helpers/reportReactBuild.test.d.ts

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

package/dist/helpers/serverLog.d.ts

@@ -1,4 +1,4 @@
-import { ServerLogEvent, ServerLogger } from '@plitzi/sdk-shared';
+import { LogLevel, ServerLogEvent, ServerLogger } from '@plitzi/sdk-shared';
 /** One line for any {@link ServerLogEvent}: an HTTP request reads as an access-log line
  *  (`[SSR] 203.0.113.7 GET /pricing 200 12ms ok`), the MCP events as what happened inside one
  *  (`[MCP] tools/call plitzi_apply {operations:[3]} 41ms ok`), a server action as what its flow did
@@ -8,6 +8,30 @@ import { ServerLogEvent, ServerLogger } from '@plitzi/sdk-shared';
  *  reduced a run to its steps; the client IP it does carry is personal data, so a sink that persists these lines
  *  must say so. */
 export declare const renderLogEvent: (event: ServerLogEvent) => string;
+/**
+ * How severe an event is: what it says it is, or — for a request, a tool call, a run — whether it went wrong. A
+ * refusal is never `ok` yet never the server's failure: the caller was turned away, which is a `warn`.
+ */
+export declare const logLevelOf: (event: ServerLogEvent) => LogLevel;
+/** Whether a server at `threshold` says something at `level`. */
+export declare const isLogged: (threshold: LogLevel | "silent", level: LogLevel) => boolean;
+/** What a server says when the deployment did not choose: what went wrong in production, more while developing. */
+export declare const defaultLogLevel: (devMode?: boolean) => LogLevel;
 /** A drop-in `SSRServerConfig.logger` for consumers that just want the log on the console. Consumers with their
  *  own logging stack should pass their own sink instead and read the structured event. */
 export declare const consoleLogger: ServerLogger;
+export declare const configureServerLog: (options: {
+    level: LogLevel | "silent";
+    logger?: ServerLogger;
+}) => void;
+/** The server's own voice: `serverLog.error('RSC', 'element failed to resolve', error)`. Below the threshold, nothing. */
+export declare const serverLog: {
+    error: (scope: string, message: string, cause?: unknown) => void;
+    warn: (scope: string, message: string, cause?: unknown) => void;
+    info: (scope: string, message: string, cause?: unknown) => void;
+    debug: (scope: string, message: string, cause?: unknown) => void;
+    /** Whether a level would be said — to skip building a costly message nobody will read. */
+    enabled: (level: LogLevel) => boolean;
+    /** Hands an event to a sink the consumer wired itself (`onRun`, `onReject`) only when the process would say it. */
+    emit: (logger: ServerLogger, event: ServerLogEvent) => void;
+};

package/dist/helpers/serverLog.js

@@ -23,6 +23,7 @@ var renderReject = (event) => {
 	const caller = event.callerId ? ` from ${event.callerId}` : "";
 	return `[Action] ${event.name} via ${event.trigger} space=${event.spaceId} REFUSED ${event.reason}${caller} ${outcomeOf(event)}`;
 };
+var renderMessage = (event) => `[${event.scope}] ${event.message}${event.error ? `: ${event.error}` : ""}`;
 /** One line for any {@link ServerLogEvent}: an HTTP request reads as an access-log line
 *  (`[SSR] 203.0.113.7 GET /pricing 200 12ms ok`), the MCP events as what happened inside one
 *  (`[MCP] tools/call plitzi_apply {operations:[3]} 41ms ok`), a server action as what its flow did
@@ -38,14 +39,78 @@ var renderLogEvent = (event) => {
 		case "resource": return renderResource(event);
 		case "run": return renderRun(event);
 		case "reject": return renderReject(event);
+		case "message": return renderMessage(event);
 	}
 };
+var RANK = {
+	silent: 0,
+	error: 1,
+	warn: 2,
+	info: 3,
+	debug: 4
+};
+/**
+* How severe an event is: what it says it is, or — for a request, a tool call, a run — whether it went wrong. A
+* refusal is never `ok` yet never the server's failure: the caller was turned away, which is a `warn`.
+*/
+var logLevelOf = (event) => {
+	if (event.kind === "message") return event.level;
+	if (event.kind === "reject") return "warn";
+	return event.ok ? "info" : "error";
+};
+/** Whether a server at `threshold` says something at `level`. */
+var isLogged = (threshold, level) => RANK[level] <= RANK[threshold];
+/** What a server says when the deployment did not choose: what went wrong in production, more while developing. */
+var defaultLogLevel = (devMode = false) => devMode ? "info" : "error";
 /** A drop-in `SSRServerConfig.logger` for consumers that just want the log on the console. Consumers with their
 *  own logging stack should pass their own sink instead and read the structured event. */
 var consoleLogger = (event) => {
 	const line = renderLogEvent(event);
-	if (event.ok) console.log(line);
-	else console.error(line);
+	const level = logLevelOf(event);
+	if (level === "error") console.error(line);
+	else if (level === "warn") console.warn(line);
+	else console.log(line);
+};
+var errorText = (cause) => cause instanceof Error ? cause.stack ?? cause.message : typeof cause === "string" ? cause : JSON.stringify(cause);
+/**
+* Where everything the server says that is not a request goes — one threshold and one sink for the process.
+*
+* Process-wide because what speaks is often created before any server exists (an adapter, a job worker) and has no
+* config to read. `createServer` sets it from its own `logLevel` and `logger`; until then it is `error` under
+* `NODE_ENV=production` and `info` otherwise, to the console.
+*/
+var state = {
+	level: process.env.NODE_ENV === "production" ? "error" : "info",
+	sink: consoleLogger
+};
+var configureServerLog = (options) => {
+	state.level = options.level;
+	state.sink = options.logger ?? consoleLogger;
+};
+var say = (level, scope, message, cause) => {
+	if (!isLogged(state.level, level)) return;
+	state.sink({
+		kind: "message",
+		level,
+		scope,
+		message,
+		ok: level !== "error",
+		...cause === void 0 ? {} : { error: errorText(cause) },
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	});
+};
+/** The server's own voice: `serverLog.error('RSC', 'element failed to resolve', error)`. Below the threshold, nothing. */
+var serverLog = {
+	error: (scope, message, cause) => say("error", scope, message, cause),
+	warn: (scope, message, cause) => say("warn", scope, message, cause),
+	info: (scope, message, cause) => say("info", scope, message, cause),
+	debug: (scope, message, cause) => say("debug", scope, message, cause),
+	/** Whether a level would be said — to skip building a costly message nobody will read. */
+	enabled: (level) => isLogged(state.level, level),
+	/** Hands an event to a sink the consumer wired itself (`onRun`, `onReject`) only when the process would say it. */
+	emit: (logger, event) => {
+		if (isLogged(state.level, logLevelOf(event))) logger(event);
+	}
 };
 //#endregion
-export { consoleLogger, renderLogEvent };
+export { configureServerLog, consoleLogger, defaultLogLevel, isLogged, logLevelOf, renderLogEvent, serverLog };

package/dist/helpers/serverLog.test.d.ts

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

package/dist/helpers/wsFrame.d.ts

@@ -0,0 +1,3 @@
+import { RawData } from 'ws';
+/** A WebSocket frame as text, whichever of its three shapes `ws` delivered it in. */
+export declare const frameText: (frame: RawData) => string;

package/dist/helpers/wsFrame.js

@@ -0,0 +1,5 @@
+//#region src/helpers/wsFrame.ts
+/** A WebSocket frame as text, whichever of its three shapes `ws` delivered it in. */
+var frameText = (frame) => Buffer.isBuffer(frame) ? frame.toString("utf8") : Array.isArray(frame) ? Buffer.concat(frame).toString("utf8") : Buffer.from(frame).toString("utf8");
+//#endregion
+export { frameText };