@plitzi/sdk-shared 0.33.2 → 0.34.1

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @plitzi/sdk-shared
 
+## 0.34.1
+
+### Patch Changes
+
+- v0.34.1
+
+## 0.34.0
+
+### Minor Changes
+
+- 5aceda0: `authorSpace` returns test handles, and every element carries its id in the DOM.
+
+  An end-to-end suite had nothing stable to address a rendered element by: a class is a styling decision that
+  changes with the design, a text match breaks when the copy is edited, and an `nth-child` chain is invalidated by
+  inserting a section above. What does not move is the element's id — which is also its name, chosen by whoever
+  authored it and unique across the document.
+
+  ```ts
+  const { schema, style, handles } = authorSpace(spec);
+  const el = locate(page, handles);
+
+  await expect(el('hero-title')).toBeVisible();
+  await page.goto(handles.page('pricing').path);
+  ```
+
+  Elements now render `data-plitzi-el="<id>"`. It ships by default — the ids are already in the page, since the
+  schema the browser hydrates from carries every one of them — and a deployment turns it off with
+  `render.testAttributes: false`.
+
+  Each handle reports whether the AUTHOR wrote the id or authoring derived a positional `<type>-<n>`, which is
+  what makes one generic assertion possible for any space: everything a space names must be on screen. A name that
+  does not exist throws at author time with a suggestion, rather than resolving to an empty locator at test time.
+
+- v0.34.0
+- 5aceda0: Draft previews you can iterate against, and a `DraftStore` contract that says so.
+
+  A preview token was one-shot: spent by the render that used it. That is right for a capture and wrong for a
+  person — reloading showed the saved space again, so "look at the change, adjust it, look again" meant minting a
+  new token for every look. `POST /__preview` now takes `mode: 'session'`, which mints a token that stays
+  resolvable until it expires (`preview.sessionTtlMs`, 15 minutes by default) or until `POST /__preview/end` ends
+  it. The token is remembered in an `HttpOnly` cookie on the first render, so the draft follows a navigation —
+  the page after a link carries no query parameter.
+
+  A draft render, either mode, is never cached, never metered and answers `Cache-Control: no-store` plus
+  `X-Robots-Tag: noindex`. Data refreshes (`/_rsc`) made from inside a session are excluded from metering and
+  caching too — without that, an open preview tab would be billed as live traffic.
+
+  **Breaking, for anyone who implements `DraftStore`** (a shared store for a multi-replica deployment). The
+  default in-memory store is unaffected; a custom one needs three changes:
+
+  ```ts
+  // before
+  put(token, data, ttlMs)
+  take(token): OfflineDataRaw | undefined
+
+  // after
+  put(token, data, { ttlMs, reusable })      // `reusable` is a session; absent is one-shot
+  take(token): { data, reusable } | undefined // consume unless reusable — and say which it was
+  drop(token)                                 // end a session before its TTL
+  ```
+
+  `take` reports which kind it resolved because the render that resolves a session is the one that has to remember
+  it for the rest of the visit, and only the store knows whether the token survived the read.
+
 ## 0.33.2
 
 ### Patch Changes

package/dist/actions/cron.d.ts

@@ -0,0 +1,34 @@
+export type CronExpression = Set<number>[];
+/** Parses an expression, or undefined when it is not one this understands — which the validator reports rather
+ *  than letting a silently-never-firing schedule sit in a document. */
+export declare const parseCron: (expression: string) => CronExpression | undefined;
+/** The five numbers a cron expression is matched against — a wall clock, in whatever zone it was read in. */
+type WallClock = {
+    minute: number;
+    hour: number;
+    day: number;
+    month: number;
+    weekday: number;
+};
+/**
+ * The same instant, as the clock on a wall in `timeZone` reads it.
+ *
+ * Through `Intl` rather than an offset table, because an offset is not a constant: "9am in Santiago" is a
+ * different instant in January and in July, and a schedule that means the working day has to follow the change.
+ * `hourCycle: 'h23'` matters — the other cycles render midnight as 24, which cron has no hour for.
+ *
+ * An unknown zone answers `undefined` rather than falling back to UTC. Falling back is what this whole change is
+ * about: a schedule that fires at the wrong hour and says nothing.
+ */
+export declare const zonedClock: (at: Date, timeZone: string) => WallClock | undefined;
+/**
+ * Whether an expression fires at this minute — in `timeZone` when one is named, in UTC when none is.
+ *
+ * Day-of-month and day-of-week are OR'd when both are restricted, which is the rule every cron implementation
+ * follows and the one that surprises people who expect AND — `0 0 1 * 1` fires on the first of the month AND on
+ * every Monday.
+ */
+export declare const cronMatches: (expression: string, at: Date, timeZone?: string) => boolean;
+/** Whether `Intl` knows this zone. The validator asks so an author hears about a typo in the editor. */
+export declare const isKnownTimeZone: (timeZone: string) => boolean;
+export {};

package/dist/actions/cron.mjs

@@ -0,0 +1,72 @@
+//#region src/actions/cron.ts
+var e = [
+	[0, 59],
+	[0, 23],
+	[1, 31],
+	[1, 12],
+	[0, 6]
+], t = (e, [t, n]) => {
+	let r = /* @__PURE__ */ new Set();
+	for (let i of e.split(",")) {
+		let [e, a] = i.split("/"), o = a === void 0 ? 1 : Number.parseInt(a, 10);
+		if (!Number.isFinite(o) || o < 1) return;
+		let s = t, c = n;
+		if (e !== void 0 && e !== "*" && e !== "") {
+			let [r, i] = e.split("-");
+			if (s = Number.parseInt(r ?? "", 10), c = i === void 0 ? s : Number.parseInt(i, 10), !Number.isFinite(s) || !Number.isFinite(c) || s < t || c > n || s > c) return;
+		}
+		for (let e = s; e <= c; e += o) r.add(e);
+	}
+	return r;
+}, n = (n) => {
+	let r = n.trim().split(/\s+/);
+	if (r.length !== 5) return;
+	let i = r.map((n, r) => t(n, e[r]));
+	return i.every((e) => e !== void 0) ? i : void 0;
+}, r = [
+	"Sun",
+	"Mon",
+	"Tue",
+	"Wed",
+	"Thu",
+	"Fri",
+	"Sat"
+], i = (e) => ({
+	minute: e.getUTCMinutes(),
+	hour: e.getUTCHours(),
+	day: e.getUTCDate(),
+	month: e.getUTCMonth() + 1,
+	weekday: e.getUTCDay()
+}), a = (e, t) => {
+	try {
+		let n = new Intl.DateTimeFormat("en-US", {
+			timeZone: t,
+			hourCycle: "h23",
+			month: "numeric",
+			day: "numeric",
+			hour: "numeric",
+			minute: "numeric",
+			weekday: "short"
+		}).formatToParts(e), i = (e) => n.find((t) => t.type === e)?.value ?? "", a = r.indexOf(i("weekday")), o = {
+			minute: Number(i("minute")),
+			hour: Number(i("hour")),
+			day: Number(i("day")),
+			month: Number(i("month")),
+			weekday: a
+		};
+		return a >= 0 && Object.values(o).every(Number.isFinite) ? o : void 0;
+	} catch {
+		return;
+	}
+}, o = (e, t, r) => {
+	let o = n(e);
+	if (!o) return !1;
+	let s = r ? a(t, r) : i(t);
+	if (!s) return !1;
+	let [c, l, u, d, f] = o;
+	if (!c.has(s.minute) || !l.has(s.hour) || !d.has(s.month)) return !1;
+	let p = u.size !== 31, m = f.size !== 7, h = u.has(s.day), g = f.has(s.weekday);
+	return p && m ? h || g : h && g;
+}, s = (e) => a(/* @__PURE__ */ new Date(), e) !== void 0;
+//#endregion
+export { o as cronMatches, s as isKnownTimeZone, n as parseCron, a as zonedClock };

package/dist/actions/index.d.ts

@@ -0,0 +1,6 @@
+export { cronMatches, isKnownTimeZone, parseCron, zonedClock } from './cron';
+export { triggerAccess, triggerCacheMs, triggerHasStaleVerify, triggerInput, triggerVerify } from './triggerParams';
+export { actionName, actionTriggers, isActionEnabled } from './triggers';
+export { validateActionDocument } from './validateDocument';
+export type { CronExpression } from './cron';
+export type { ActionDocumentIssue, ActionDocumentReport } from './validateDocument';

package/dist/actions/index.mjs

@@ -0,0 +1,5 @@
+import { cronMatches as e, isKnownTimeZone as t, parseCron as n, zonedClock as r } from "./cron.mjs";
+import { triggerAccess as i, triggerCacheMs as a, triggerHasStaleVerify as o, triggerInput as s, triggerVerify as c } from "./triggerParams.mjs";
+import { actionName as l, actionTriggers as u, isActionEnabled as d } from "./triggers.mjs";
+import { validateActionDocument as f } from "./validateDocument.mjs";
+export { l as actionName, u as actionTriggers, e as cronMatches, d as isActionEnabled, t as isKnownTimeZone, n as parseCron, i as triggerAccess, a as triggerCacheMs, o as triggerHasStaleVerify, s as triggerInput, c as triggerVerify, f as validateActionDocument, r as zonedClock };

package/dist/actions/triggerParams.d.ts

@@ -0,0 +1,41 @@
+import { ActionAccess, ActionField, ActionTriggerParams, ActionWebhookVerification } from '../types';
+/**
+ * Who may start a run this way.
+ *
+ * `undefined` is a trigger that states no rule, which is refused rather than guessed at — every guess is either a
+ * lock-out or a hole. A `schedule` has no caller and states none, and the runner does not ask.
+ */
+export declare const triggerAccess: (params: ActionTriggerParams) => ActionAccess | undefined;
+/** What a caller may send through this way in. An unparseable map reads as no contract at all, which drops every key. */
+export declare const triggerInput: (params: ActionTriggerParams) => Record<string, ActionField>;
+/** How an inbound webhook proves itself, or nothing — which is an endpoint anyone who learns the URL can start. */
+/**
+ * How this webhook proves who is calling it — assembled from the trigger's own fields, not parsed out of a blob.
+ *
+ * **Naming the credential is what turns it on.** Everything else has a working default, so there is no state
+ * between "unsigned" and "verified" for an author to get stuck in: it was a JSON object with an empty
+ * `credential` in it, which the editor offered by default and the validator then refused, so picking the webhook
+ * trigger produced an error before anybody had typed anything.
+ */
+export declare const triggerVerify: (params: ActionTriggerParams) => ActionWebhookVerification | undefined;
+/**
+ * Whether this trigger carries a signature check that USED TO VERIFY something and no longer does.
+ *
+ * A guard, not a compatibility layer: nothing here interprets the old shape, and the only question it answers is
+ * whether ignoring it would fail OPEN. A stored `verify: '{…}'` that named a credential was a protected endpoint;
+ * read as "unsigned" it becomes a public one with nothing in the document changing, which is the one degradation
+ * that must never happen by omission — so it is refused until somebody moves it across.
+ *
+ * A leftover blob that named NO credential verified nothing to begin with. It is not a downgrade, it is a field
+ * the editor used to offer filled in with a default and never completed — and treating it as an error would be an
+ * error about something the editor no longer shows, on a webhook that was always unsigned. That one is simply
+ * unsigned, and warned about like any other.
+ */
+export declare const triggerHasStaleVerify: (params: ActionTriggerParams) => boolean;
+/**
+ * How long a `render` answer may be reused, in milliseconds.
+ *
+ * Read through here rather than parsed at the call site so the validator and the runtime agree on what an
+ * unparseable value means: nothing, which is the same as not caching — never an accidental eternity.
+ */
+export declare const triggerCacheMs: (params: ActionTriggerParams) => number;

package/dist/actions/triggerParams.mjs

@@ -0,0 +1,40 @@
+//#region src/actions/triggerParams.ts
+var e = (e) => {
+	if (typeof e == "string" && e.trim() !== "") try {
+		return JSON.parse(e);
+	} catch {
+		return;
+	}
+}, t = (e) => typeof e == "object" && !!e && !Array.isArray(e), n = (e) => {
+	let { access: t } = e;
+	if (t === "public" || t === "session") return { mode: t };
+	if (t === "role") return {
+		mode: "role",
+		permissions: (e.permissions ?? "").split(",").map((e) => e.trim()).filter(Boolean)
+	};
+}, r = (n) => {
+	let r = e(n.input);
+	return t(r) ? r : {};
+}, i = (e) => {
+	let t = e.signatureCredential?.trim();
+	if (!t) return;
+	let n = e.signatureSecretField?.trim(), r = e.signatureTimestampHeader?.trim(), i = Number.parseFloat(e.signatureToleranceSeconds ?? "");
+	return {
+		type: "hmac",
+		header: e.signatureHeader?.trim() || "x-signature",
+		algorithm: e.signatureAlgorithm?.trim() === "sha1" ? "sha1" : "sha256",
+		credential: t,
+		...n ? { secretField: n } : {},
+		...r ? { timestampHeader: r } : {},
+		...Number.isFinite(i) && i > 0 ? { toleranceSeconds: Math.round(i) } : {}
+	};
+}, a = (n) => {
+	if (n.signatureCredential?.trim()) return !1;
+	let r = e(n.verify);
+	return t(r) && typeof r.credential == "string" && r.credential.trim() !== "";
+}, o = (e) => {
+	let t = Number.parseFloat(e.cacheSeconds ?? "");
+	return Number.isFinite(t) && t > 0 ? Math.round(t * 1e3) : 0;
+};
+//#endregion
+export { n as triggerAccess, o as triggerCacheMs, a as triggerHasStaleVerify, r as triggerInput, i as triggerVerify };

package/dist/actions/triggers.d.ts

@@ -0,0 +1,29 @@
+import { ActionDocument, ElementInteraction } from '../types';
+/**
+ * The ways into an action, read off the flow.
+ *
+ * A way in is a trigger STEP, so this is the only place that has to know it — the builder's list, the MCP summary
+ * and the schedule sweep all ask the same question of the same document and cannot answer it differently.
+ */
+export declare const actionTriggers: (document: ActionDocument) => ElementInteraction[];
+/**
+ * Whether this action can run at all: whether ANY way into it is switched on.
+ *
+ * DERIVED, never stored. The switch belongs to the trigger — one per way in — and an action-level copy of it was a
+ * second answer to the same question: the builder computed it from the steps, the store overwrote it from its own
+ * column, and the two could disagree with nothing to say which won. A store that keeps a column for it (to index
+ * the schedule sweep, say) writes what this returns, and reads it back as a cache rather than as a decision.
+ */
+export declare const isActionEnabled: (document: ActionDocument) => boolean;
+/**
+ * What to call this action, read off the flow that starts it.
+ *
+ * The trigger step is already named — the editor puts an editable title on every node — so a field beside the flow
+ * asked the author to name the same thing twice, and left two names with no rule for which one anybody meant. The
+ * FIRST trigger wins because it is the one the list and the picker show; an action with several ways in is still
+ * one action, and naming it after the way most callers reach it is the honest summary.
+ *
+ * Falls back to whatever the document already carries, so a document written before this — or by a caller that
+ * names it directly, like the authoring API — keeps the name it was given.
+ */
+export declare const actionName: (document: ActionDocument) => string;

package/dist/actions/triggers.mjs

@@ -0,0 +1,4 @@
+//#region src/actions/triggers.ts
+var e = (e) => Object.values(e.nodes).filter((e) => e.type === "trigger"), t = (t) => e(t).some((e) => e.enabled), n = (t) => e(t).find((e) => e.title.trim() !== "")?.title.trim() ?? t.name;
+//#endregion
+export { n as actionName, e as actionTriggers, t as isActionEnabled };

package/dist/actions/validateDocument.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The one server-action validator.
+ *
+ * Three places decide whether a document is fit to store — the builder panel, the MCP write ops and the GraphQL
+ * mutation that persists it — and a document is only ever wrong in one way, so the rules live here instead of
+ * being restated (and drifting) at each entry point. The input is `unknown` because the server runs it last, on
+ * whatever JSON actually arrived: it validates a document, it does not assume one.
+ *
+ * Errors are what the runner cannot recover from at request time; warnings are what will run but probably does
+ * not do what the author meant.
+ */
+export type ActionDocumentIssue = {
+    /** Dotted path into the document, e.g. `nodes.send.action`. */
+    path: string;
+    message: string;
+    hint?: string;
+};
+export type ActionDocumentReport = {
+    valid: boolean;
+    errors: ActionDocumentIssue[];
+    warnings: ActionDocumentIssue[];
+};
+export declare const validateActionDocument: (document: unknown) => ActionDocumentReport;

package/dist/actions/validateDocument.mjs

@@ -0,0 +1,267 @@
+import { isKnownTimeZone as e, parseCron as t } from "./cron.mjs";
+import { triggerAccess as n, triggerHasStaleVerify as r, triggerVerify as i } from "./triggerParams.mjs";
+//#region src/actions/validateDocument.ts
+var a = [
+	"text",
+	"number",
+	"boolean",
+	"date",
+	"json",
+	"file"
+], o = [
+	"public",
+	"session",
+	"role"
+], s = [
+	"call",
+	"webhook",
+	"schedule",
+	"render",
+	"custom"
+], c = ["sha256", "sha1"], l = /* @__PURE__ */ new Set([
+	"input",
+	"user",
+	"spaceId",
+	"environment",
+	"trigger",
+	"runId"
+]), u = /^[a-z][a-zA-Z0-9]*\.[a-z][a-zA-Z0-9]*$/, d = (e) => typeof e == "object" && !!e && !Array.isArray(e), f = (e) => typeof e == "string" && e.trim() !== "", p = (e) => {
+	try {
+		let t = JSON.parse(e);
+		return d(t) ? t : void 0;
+	} catch {
+		return;
+	}
+}, m = (e, t, n) => {
+	if (e !== void 0) {
+		if (!d(e)) {
+			n.push({
+				path: t,
+				message: "must be an object of field definitions"
+			});
+			return;
+		}
+		Object.entries(e).forEach(([e, r]) => {
+			if (!d(r) || !f(r.type)) {
+				n.push({
+					path: `${t}.${e}`,
+					message: "must declare a type"
+				});
+				return;
+			}
+			a.includes(r.type) || n.push({
+				path: `${t}.${e}.type`,
+				message: `unknown field type "${r.type}"`,
+				hint: `one of ${a.join(", ")}`
+			});
+		});
+	}
+}, h = (a, l, u, h) => {
+	let g = `nodes.${a}`, _ = l.action;
+	if (!f(_) || !s.includes(_)) {
+		u.push({
+			path: `${g}.action`,
+			message: `"${String(_)}" is not a way an action can be started`,
+			hint: `one of ${s.join(", ")}`
+		});
+		return;
+	}
+	let v = d(l.params) ? l.params : {};
+	if (f(v.input)) {
+		let e = p(v.input);
+		e === void 0 ? u.push({
+			path: `${g}.params.input`,
+			message: "is not valid JSON"
+		}) : m(e, `${g}.params.input`, u);
+	}
+	if (_ !== "schedule") {
+		if (!f(v.access) || !o.includes(v.access)) u.push({
+			path: `${g}.params.access`,
+			message: "must say who may start a run this way",
+			hint: `one of ${o.join(", ")}`
+		});
+		else if (v.access === "role") {
+			let e = n(v);
+			e?.mode === "role" && e.permissions.length === 0 && u.push({
+				path: `${g}.params.permissions`,
+				message: "role access must name at least one permission"
+			});
+		}
+	}
+	if (_ === "schedule" && (f(v.cron) ? t(v.cron) || u.push({
+		path: `${g}.params.cron`,
+		message: `"${v.cron}" is not an expression this server can read, so it would never fire`,
+		hint: "five fields — minute hour day-of-month month day-of-week — with *, lists, ranges and steps"
+	}) : u.push({
+		path: `${g}.params.cron`,
+		message: "a scheduled trigger needs a cron expression"
+	}), f(v.timezone) && !e(v.timezone) && u.push({
+		path: `${g}.params.timezone`,
+		message: `"${v.timezone}" is not a time zone this server knows, so the schedule would never fire`,
+		hint: "an IANA name like America/Santiago or Europe/Madrid — leave it empty for UTC"
+	})), f(v.cacheSeconds)) {
+		let e = Number.parseFloat(v.cacheSeconds);
+		!Number.isFinite(e) || e < 0 ? u.push({
+			path: `${g}.params.cacheSeconds`,
+			message: "must be a number of seconds, or left empty"
+		}) : _ !== "render" && h.push({
+			path: `${g}.params.cacheSeconds`,
+			message: `a "${_}" trigger is never answered from a cache`,
+			hint: "reuse only applies to a render, where the same page is built for one visitor after another"
+		});
+	}
+	_ === "custom" && !f(v.name) && u.push({
+		path: `${g}.params.name`,
+		message: "a custom trigger needs a name to be mounted under"
+	}), _ === "webhook" && (r(v) && u.push({
+		path: `${g}.params.signatureCredential`,
+		message: "this signature check is in a format nothing reads any more, so the webhook is unverified",
+		hint: "name the credential holding the signing secret in \"Signing secret\", and its header beside it"
+	}), i(v) || h.push({
+		path: `${g}.params.signatureCredential`,
+		message: "this webhook accepts unsigned requests",
+		hint: "name the credential holding the signing secret, and only the sender you expect can start a run"
+	}), f(v.signatureAlgorithm) && !c.includes(v.signatureAlgorithm) && h.push({
+		path: `${g}.params.signatureAlgorithm`,
+		message: `"${v.signatureAlgorithm}" is not an algorithm this server signs with, so sha256 is used`,
+		hint: `one of ${c.join(", ")}`
+	}), f(v.signatureToleranceSeconds) && !f(v.signatureTimestampHeader) && h.push({
+		path: `${g}.params.signatureToleranceSeconds`,
+		message: "a tolerance with no timestamp header expires nothing",
+		hint: "name the header the sender puts the signing time in, or drop the tolerance"
+	})), _ === "call" && v.access === "public" && h.push({
+		path: `${g}.params.access`,
+		message: "anyone can run this action, including signed-out visitors",
+		hint: "use session access unless the page needs it before anyone signs in"
+	});
+}, g = (e, t, n, r) => {
+	if (!d(e)) {
+		n.push({
+			path: "nodes",
+			message: "must be an object of steps"
+		});
+		return;
+	}
+	let i = Object.entries(e), a = i.filter(([, e]) => d(e) && e.type === "trigger");
+	a.length === 0 && n.push({
+		path: "nodes",
+		message: "this action has no way in",
+		hint: "add a trigger step — call, webhook, schedule, render or custom"
+	});
+	let o = /* @__PURE__ */ new Map();
+	a.forEach(([e, t]) => {
+		f(t.action) && o.set(t.action, [...o.get(t.action) ?? [], e]);
+	}), o.forEach((e, t) => {
+		e.length > 1 && n.push({
+			path: `nodes.${e[1]}`,
+			message: `this action has ${e.length} "${t}" triggers`,
+			hint: "one step per way in — a second flow starts from a different kind of trigger"
+		});
+	}), i.forEach(([t, i]) => {
+		let a = `nodes.${t}`;
+		if (!d(i)) {
+			n.push({
+				path: a,
+				message: "must be an object"
+			});
+			return;
+		}
+		if (i.type === "trigger") {
+			h(t, i, n, r);
+			return;
+		}
+		if (i.type !== "task") {
+			n.push({
+				path: `${a}.type`,
+				message: `"${String(i.type)}" steps run in the browser and cannot run on the server`,
+				hint: "a server action is made of task steps"
+			});
+			return;
+		}
+		if (!f(i.action) || !u.test(i.action)) {
+			n.push({
+				path: `${a}.action`,
+				message: "must name a task as <namespace>.<action>",
+				hint: "for example flow.output or http.request"
+			});
+			return;
+		}
+		f(i.afterNode) && !Object.hasOwn(e, i.afterNode) && n.push({
+			path: `${a}.afterNode`,
+			message: `points at "${i.afterNode}", which is not a step here`
+		});
+	}), i.forEach(([e]) => {
+		l.has(e) && n.push({
+			path: `nodes.${e}`,
+			message: `"${e}" is what the run itself publishes in the flow scope, so a step may not take the name`,
+			hint: `rename the step — every later step reads {{ ${e} }} expecting the run's own value`
+		});
+	});
+	let s = /* @__PURE__ */ new Set(), c = /* @__PURE__ */ new Set();
+	a.forEach(([t]) => {
+		let n = /* @__PURE__ */ new Set(), r = t;
+		for (; r;) {
+			if (n.has(r)) {
+				c.add(r);
+				break;
+			}
+			n.add(r), s.add(r);
+			let t = e[r];
+			r = f(t?.afterNode) ? t.afterNode : "";
+		}
+	}), c.forEach((e) => {
+		n.push({
+			path: `nodes.${e}`,
+			message: "this step is reached again by its own chain, so the flow never ends",
+			hint: "break the `afterNode` chain that comes back to it"
+		});
+	}), i.forEach(([e]) => {
+		s.has(e) || r.push({
+			path: `nodes.${e}`,
+			message: "no trigger reaches this step, so it never runs",
+			hint: "chain it with `afterNode` from a trigger, or delete it"
+		});
+	});
+	let p = i.filter(([, e]) => d(e) && e.action === "flow.output");
+	for (let [t, n] of p) f(n.afterNode) && Object.hasOwn(e, n.afterNode) && r.push({
+		path: `nodes.${t}.afterNode`,
+		message: "the output step is not the last one, so the steps after it run for nothing",
+		hint: "move flow.output to the end of the flow"
+	});
+	p.length === 0 && d(t) && Object.keys(t).length > 0 && r.push({
+		path: "nodes",
+		message: "this action is expected to answer values but no step names any",
+		hint: "add a flow.output step at the end naming what the caller should get"
+	});
+}, _ = /\{\{\s*credential\./, v = (e, t) => {
+	Object.entries(e).forEach(([e, n]) => {
+		if (!d(n) || !d(n.params)) return;
+		let r = f(n.params.credential) ? n.params.credential : "";
+		Object.entries(n.params).forEach(([n, i]) => {
+			typeof i == "string" && _.test(i) && r === "" && t.push({
+				path: `nodes.${e}.params.${n}`,
+				message: "this step reads a credential it did not ask for, so the token resolves to nothing",
+				hint: "set the step’s `credential` to the identifier it should use"
+			});
+		});
+	});
+}, y = (e) => {
+	let t = [], n = [];
+	return d(e) ? (f(e.name) || t.push({
+		path: "name",
+		message: "must have a name"
+	}), m(e.output, "output", t), g(e.nodes, e.output, t, n), v(d(e.nodes) ? e.nodes : {}, n), {
+		valid: t.length === 0,
+		errors: t,
+		warnings: n
+	}) : {
+		valid: !1,
+		errors: [{
+			path: "",
+			message: "the document must be an object"
+		}],
+		warnings: n
+	};
+};
+//#endregion
+export { y as validateActionDocument };

package/dist/auth/failureChannel.d.ts

@@ -16,10 +16,15 @@ export declare const onAuthFailure: (listener: AuthFailureListener) => (() => vo
  * What an HTTP refusal means for the session. Stated once, because the provider and the network layers must not
  * disagree about which refusals are renewable.
  *
- * A backend that names the reason (Plitzi's API answers `reason` on every 401) is believed. One that says nothing
- * gets the benefit of the doubt — an unexplained 401 is treated as renewable, so a stale access token costs one
- * refused renewal instead of signing out a session that was still good. Nothing below 401 or above 499 is an answer
- * about the session at all: a 5xx means the backend failed, not that the caller is a stranger.
+ * Only a 401 is about the session. A backend that names the reason (Plitzi's API answers `reason` on every 401) is
+ * believed; one that says nothing gets the benefit of the doubt — an unexplained 401 is treated as renewable, so a
+ * stale access token costs one refused renewal instead of signing out a session that was still good.
+ *
+ * A 403 is never about the session, whatever it carries. It is "you may not do THIS": a permission the account does
+ * not hold, or a CSRF check that failed — and the kernel's CSRF refusal names reasons (`missing`, `expired`) that are
+ * spelled like session ones. It used to be read as `inactive`, so any screen that asked for something its visitor may
+ * not have signed that visitor out on the spot, with nothing on the page to say why. An account that really was
+ * deactivated is refused with a 401 naming `inactive`, which is still believed.
  */
 export declare const authFailureFromResponse: (status: number, body?: unknown) => AuthFailureReason | undefined;
 /**

package/dist/auth/failureChannel.mjs

@@ -6,13 +6,14 @@ var e = /* @__PURE__ */ new Set(), t = (t) => {
 	"expired",
 	"revoked",
 	"inactive",
+	"unverified",
 	"malformed",
 	"outdated",
 	"network"
 ], i = (e, t) => {
-	if (e < 400 || e >= 500 || e !== 401 && e !== 403) return;
+	if (e !== 401) return;
 	let n = t?.reason;
-	return typeof n == "string" && r.includes(n) ? n : e === 403 ? "inactive" : "expired";
+	return typeof n == "string" && r.includes(n) ? n : "expired";
 }, a = (e) => /([^.]+\.[^.]+)$/.exec(e)?.[1] ?? e, o = (e, t) => {
 	if (!e || !t) return !1;
 	try {