@plitzi/sdk-shared 0.37.2 → 0.37.3

package/dist/helpers/twigWrapper/processTwig/processTwig.mjs

@@ -1,24 +1,81 @@
-import { evaluate as e } from "../Evaluator/Evaluator.mjs";
-import { finalizeRaw as t, flattenContext as n, renderSimpleTokens as r } from "./helpers.mjs";
-import { getNodes as i, resolveTokens as a } from "../TemplateCache/TemplateCache.mjs";
+import { finalizeRaw as e, flattenContext as t, renderSimpleTokens as n } from "./helpers.mjs";
+import { evaluate as r, evaluateExpression as i } from "../Evaluator/Evaluator.mjs";
+import { getNodes as a, resolveTokens as o } from "../TemplateCache/TemplateCache.mjs";
 //#region src/helpers/twigWrapper/processTwig/processTwig.ts
-var o = (o, s = {}, c = !1, l = !1) => {
-	if (typeof o != "string") return o;
+var s = (i, s = {}, c = !1, l = !1) => {
+	if (typeof i != "string") return i;
 	try {
-		if (o.indexOf("{%") === -1 && o.indexOf("{{") === -1) return o;
-		let u = "variables" in s ? n(s) : s, d = a(o);
-		if (!d) return o;
+		if (i.indexOf("{%") === -1 && i.indexOf("{{") === -1) return i;
+		let u = "variables" in s ? t(s) : s, d = o(i);
+		if (!d) return i;
 		if (!c && !d.hasTags && d.allSimpleOrDotted) {
-			let e = r(d, u);
-			return l ? t(e) : e;
+			let t = n(d, u);
+			return l ? e(t) : t;
 		}
-		let f = i(d, c);
-		if (!f) return o;
-		let { output: p, variables: m, hasSet: h } = e(f, u, c);
-		return h && Object.assign(s, m), c && p === o ? o : l ? t(p) : p;
+		let f = a(d, c);
+		if (!f) return i;
+		let { output: p, variables: m, hasSet: h } = r(f, u, c);
+		return h && Object.assign(s, m), c && p === i ? i : l ? e(p) : p;
 	} catch {
-		return o;
+		return i;
+	}
+}, c = (e) => {
+	let t = e.trimStart();
+	return t.startsWith("{") || t.startsWith("[");
+}, l = (e, n) => {
+	let i = o(e), a = i ? i.nodes ?? i.nodesWithSource : null;
+	if (a) try {
+		let e = "variables" in n ? t(n) : n, { output: i, variables: o, hasSet: s } = r(a, e, !1, !0);
+		if (!c(i)) return;
+		let l = JSON.parse(i);
+		return s && Object.assign(n, o), l;
+	} catch {
+		return;
+	}
+}, u = (e, n = {}) => {
+	if (typeof e != "string") return e;
+	let r = o(e), a = (r ? r.nodes ?? r.nodesWithSource : null)?.filter((e) => e.type !== "text" || e.value.trim() !== "");
+	if (a?.length !== 1 || a[0].type !== "variable") return s(e, n);
+	try {
+		let e = "variables" in n ? t(n) : n;
+		return i(a[0].expression, e);
+	} catch {
+		return e;
+	}
+}, d = /* @__PURE__ */ new Set([
+	"json_encode",
+	"to_json",
+	"object_as_json"
+]), f = (e) => e.type === "filter" && d.has(e.filters[e.filters.length - 1]?.name ?? ""), p = (e) => {
+	let t = e.trim();
+	if (!t.startsWith("{") && !t.startsWith("[")) return e;
+	try {
+		return JSON.parse(t);
+	} catch {
+		return e;
+	}
+}, m = (e, n = {}) => {
+	if (typeof e != "string") return e;
+	let r = o(e), a = (r ? r.nodes ?? r.nodesWithSource : null)?.filter((e) => e.type !== "text" || e.value.trim() !== "");
+	if (a?.length !== 1 || a[0].type !== "variable") {
+		let t = e.includes("\"") ? l(e, n) : void 0;
+		if (t !== void 0) return t;
+		let r = s(e, n);
+		return typeof r == "string" ? p(r) : r;
+	}
+	let { expression: c } = a[0];
+	try {
+		let e = "variables" in n ? t(n) : n, r = i(c, e);
+		if (r === void 0) return "";
+		if (typeof r == "string" && f(c)) try {
+			return JSON.parse(r);
+		} catch {
+			return r;
+		}
+		return r;
+	} catch {
+		return e;
 	}
 };
 //#endregion
-export { o as processTwig };
+export { s as processTwig, m as processTwigParam, u as processTwigValue };

package/dist/helpers/twigWrapper/processTwig/resolveStepParam.d.ts

@@ -0,0 +1,17 @@
+/** How many times a value may resolve to another template before the resolver stops and says so. */
+export declare const MAX_PARAM_PASSES = 5;
+/**
+ * One step param, resolved against the flow's scope — the ONE resolver for the browser's flows and a server action's
+ * steps, so a param means the same on both sides.
+ *
+ * The param as written is a template whatever it holds: a condition, a loop or an object literal as much as a name —
+ * which is why the first pass runs on any template syntax, not only on what `hasValidToken` recognises (it answers a
+ * narrower question, for attributes, where the text around a token is prose). The server used to skip that first pass,
+ * so `{{ { "id": run.id } }}` reached its task as the template text. What a pass RETURNS is data, and is read again only
+ * when it carries a well-formed token — so text a visitor typed that happens to contain braces is not evaluated — up to
+ * {@link MAX_PARAM_PASSES}. `unresolved` says the ceiling was hit with tokens left, for the caller to report.
+ */
+export declare const resolveStepParam: (template: string, scope: Record<string, unknown>) => {
+    value: unknown;
+    unresolved: boolean;
+};

package/dist/helpers/twigWrapper/processTwig/resolveStepParam.mjs

@@ -0,0 +1,14 @@
+import { processTwigParam as e } from "./processTwig.mjs";
+import { hasTemplateSyntax as t } from "../tokens/hasTemplateSyntax.mjs";
+import { hasValidToken as n } from "../tokens/hasValidToken.mjs";
+//#region src/helpers/twigWrapper/processTwig/resolveStepParam.ts
+var r = 5, i = (r, i) => {
+	let a = r, o = 5;
+	for (t(a) && !n(r) && (a = e(r, i), o--); typeof a == "string" && n(a) && o > 0;) a = e(a, i), o--;
+	return {
+		value: a,
+		unresolved: typeof a == "string" && n(a)
+	};
+};
+//#endregion
+export { r as MAX_PARAM_PASSES, i as resolveStepParam };

package/dist/helpers/twigWrapper/templateRoots.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Every path a template reads, as far as it is known before it runs: `{{ computed.tool == 'pen' }}` gives
+ * `computed.tool`, `{{ state.owned[source.id] }}` gives `state.owned` and `source.id` — a bracket whose key is only
+ * known at run time ends the path at what came before it.
+ *
+ * What a caller SUBSCRIBES to, where the root alone would be too much: an element whose template reads
+ * `computed.tool` has no reason to render again when `computed.selectionCount` changes, and every element on a page
+ * reads some computed value. Names the template binds itself — a loop variable, a `set`, an arrow's parameter —
+ * come back too: they resolve to no source, and asking for a path that is not there costs nothing.
+ */
+export declare const templatePaths: (template: string) => string[];
 /**
  * Every top-level name a template reads: `{{ theme.resolved }}` and `{% if state.open %}` both give their first segment.
  *

package/dist/helpers/twigWrapper/templateRoots.mjs

@@ -7,8 +7,8 @@ var t = (e, n) => {
 	}
 	if (typeof e == "object" && e) {
 		if ("type" in e && e.type === "path" && "segments" in e && Array.isArray(e.segments)) {
-			let t = e.segments[0];
-			typeof t == "string" && n.add(t);
+			let t = e.segments.filter((e) => typeof e == "string");
+			t.length > 0 && n.add(t.join("."));
 			return;
 		}
 		for (let r of Object.values(e)) t(r, n);
@@ -18,6 +18,6 @@ var t = (e, n) => {
 	if (!r) return [];
 	let i = /* @__PURE__ */ new Set();
 	return t(r.nodes ?? r.nodesWithSource, i), [...i];
-};
+}, r = (e) => [...new Set(n(e).map((e) => e.split(".")[0]))];
 //#endregion
-export { n as templateRootNames };
+export { n as templatePaths, r as templateRootNames };

package/dist/helpers/twigWrapper/tokens/hasTemplateSyntax.d.ts

@@ -6,4 +6,4 @@
  * are templates by construction, so a condition (`{{ admin ? '1' : '' }}`) or a loop (`{% for %}…{% endfor %}`) is
  * meant to run — read by the narrow test they were handed on as written, and a flag stored its own template text.
  */
-export declare const hasTemplateSyntax: (value: unknown) => value is string;
+export declare const hasTemplateSyntax: (value: unknown) => boolean;

package/dist/history/describe.d.ts

@@ -0,0 +1,29 @@
+import { ChangeEntry } from './types';
+export type FieldChange = {
+    path: string;
+    before?: unknown;
+    after?: unknown;
+};
+/** What a line says was done, for a reader who scans the icon before the words. */
+export type ChangeAction = 'add' | 'remove' | 'move' | 'update' | 'reorder';
+/** One thing a save did, in words, and the element it is about when it is about one. */
+export type ChangeLine = {
+    text: string;
+    action: ChangeAction;
+    elementId?: string;
+};
+/**
+ * What changed inside one entity, field by field (`attributes.content`, `definition.items`). Objects are walked; a list
+ * or a value is compared whole, since "the third item moved" reads worse than the list before and after.
+ */
+export declare const fieldChanges: (before: unknown, after: unknown, path?: string) => FieldChange[];
+/** Each line once, the first time it is said. */
+export declare const uniqueLines: (lines: ChangeLine[]) => ChangeLine[];
+/**
+ * One save, as lines a person reads: each thing it did, said once and in words.
+ *
+ * Adding an element also rewrites its parent's list of children, and a move rewrites two; those are the consequence of
+ * the add or the move, so they are not said again. A parent whose children changed for no other reason in the same
+ * save — a reorder — is said as that.
+ */
+export declare const describeChange: (entries: ChangeEntry[]) => ChangeLine[];

package/dist/history/describe.mjs

@@ -0,0 +1,93 @@
+//#region src/history/describe.ts
+var e = (e) => typeof e == "object" && !!e && !Array.isArray(e), t = (n, r, i = "") => e(n) && e(r) ? [.../* @__PURE__ */ new Set([...Object.keys(n), ...Object.keys(r)])].flatMap((e) => t(n[e], r[e], i ? `${i}.${e}` : e)) : JSON.stringify(n) === JSON.stringify(r) ? [] : [{
+	path: i,
+	...n === void 0 ? {} : { before: n },
+	...r === void 0 ? {} : { after: r }
+}], n = (t) => e(t) ? t : {}, r = (e) => {
+	let t = n(e).definition?.type;
+	return t ? t === "layoutContainer" ? "layout" : t.replace(/([a-z])([A-Z])/gu, "$1 $2").toLowerCase() : "element";
+}, i = (e) => n(e).definition?.parentId ?? void 0, a = (e, t) => {
+	let n = t.get(e);
+	return n === void 0 ? `“${e}”` : `${r(n)} “${e}”`;
+}, o = (e) => {
+	let t = e.split("."), n = t[0], r = t.length > 1 ? t[1] : n;
+	if (n === "attributes") return r;
+	let i = {
+		label: "label",
+		styleSelectors: "classes",
+		bindings: "bindings",
+		interactions: "interactions",
+		initialState: "initial state",
+		items: void 0,
+		parentId: void 0,
+		rootId: void 0,
+		type: "type"
+	};
+	return Object.hasOwn(i, r) ? i[r] : r;
+}, s = (e, t = 3) => e.length > t ? `${e.slice(0, t).join(", ")} and ${e.length - t} more` : e.join(", "), c = {
+	folder: "folder",
+	variable: "variable",
+	setting: "setting",
+	selector: "class",
+	globalStyle: "global style for",
+	idStyle: "id style",
+	token: "token",
+	font: "font",
+	file: "function file"
+}, l = {
+	add: "Added",
+	update: "Changed",
+	remove: "Removed"
+}, u = (t, n) => {
+	let r = e(t) ? t : {}, i = e(n) ? n : {};
+	return [.../* @__PURE__ */ new Set([...Object.keys(r), ...Object.keys(i)])].filter((e) => JSON.stringify(r[e]) !== JSON.stringify(i[e]));
+}, d = (e) => e.kind !== "element", f = (e) => {
+	let { kind: t } = e;
+	if (t === "setting" && e.id === "pages") return {
+		text: "Reordered the pages",
+		action: "reorder"
+	};
+	let n = `${l[e.op]} ${c[t]} “${e.id}”`;
+	if (e.op === "update" && (t === "selector" || t === "globalStyle" || t === "idStyle")) {
+		let t = u(e.before, e.after);
+		return {
+			text: t.length > 0 ? `${n} on ${t.join(", ")}` : n,
+			action: e.op
+		};
+	}
+	return {
+		text: n,
+		action: e.op
+	};
+}, p = (e) => {
+	let t = /* @__PURE__ */ new Set();
+	return e.filter((e) => !t.has(e.text) && (t.add(e.text), !0));
+}, m = (e) => {
+	let r = e.filter((e) => e.kind === "element"), c = new Map(r.map((e) => [e.id, e.after ?? e.before])), l = new Set(r.filter((e) => e.op !== "update" || i(e.before) !== i(e.after)).map((e) => e.id)), u = [];
+	for (let e of r) {
+		let r = a(e.id, c), d = (t, n) => u.push({
+			text: t,
+			action: n,
+			elementId: e.id
+		});
+		if (e.op === "add") {
+			let t = i(e.after);
+			d(t ? `Added ${r} to ${a(t, c)}` : `Added ${r}`, "add");
+			continue;
+		}
+		if (e.op === "remove") {
+			let t = i(e.before);
+			d(t ? `Removed ${r} from ${a(t, c)}` : `Removed ${r}`, "remove");
+			continue;
+		}
+		let f = i(e.before), p = i(e.after);
+		f !== p && f && p && d(`Moved ${r} from ${a(f, c)} to ${a(p, c)}`, "move");
+		let m = t(e.before, e.after), h = [...new Set(m.map((e) => o(e.path)).filter((e) => e !== void 0))];
+		h.length > 0 && d(`Changed ${s(h)} of ${r}`, "update");
+		let g = (e) => (n(e).definition?.items ?? []).filter((e) => !l.has(e)), _ = m.some((e) => e.path === "definition.items");
+		_ && JSON.stringify(g(e.before)) !== JSON.stringify(g(e.after)) && d(`Reordered the children of ${r}`, "reorder"), (m.length === 0 || h.length === 0 && !_ && f === p) && d(`Changed ${r}`, "update");
+	}
+	return u.push(...e.filter(d).map(f)), p(u);
+};
+//#endregion
+export { m as describeChange, t as fieldChanges, p as uniqueLines };

package/dist/history/diff.d.ts

@@ -0,0 +1,33 @@
+import { ChangeEntry } from './types';
+import { Schema, Style } from '../types';
+/**
+ * Structural equality for documents as they are stored: JSON — objects, arrays and scalars, nothing else.
+ *
+ * Written out rather than borrowed because it runs on every save of a space, over every element of it, and almost
+ * every pair it compares is equal: what it has to be is a walk that stops at the first difference, with nothing to
+ * set up per call.
+ */
+export declare const sameValue: (a: unknown, b: unknown) => boolean;
+/**
+ * A copy of a stored document, for the model that has to remember what it last saved.
+ *
+ * JSON rather than a structural clone: documents are JSON by definition, and the round trip measures about half of
+ * `cloneDeep` on a 5 000-element schema — a cost every save of a space pays.
+ */
+export declare const jsonCopy: <T>(value: T) => T;
+/** The part of a schema a history reads: what is stored, never what the runtime derives from it. */
+export type HistorySchema = Pick<Schema, 'flat' | 'pages' | 'pageFolders' | 'variables' | 'settings' | 'definition'>;
+/**
+ * What changed between two versions of a schema, entity by entity.
+ *
+ * An element is one entity: whatever changed inside it — an attribute, a binding, a flow, its place in the tree —
+ * the entry carries it whole, before and after. Pages are elements; their ORDER is the setting `pages`.
+ */
+export declare const diffSchema: (before: Partial<HistorySchema>, after: Partial<HistorySchema>) => ChangeEntry[];
+/** The part of a style a history reads. Its `cache` is not: it is the whole stylesheet, compiled from the rest. */
+export type HistoryStyle = Pick<Style, 'platform' | 'variables' | 'fonts' | 'theme' | 'mode'>;
+/**
+ * What changed between two versions of a style. A selector is one entity across the display modes, so "tablet only"
+ * reads as one change to it, with the modes compared inside the entry.
+ */
+export declare const diffStyle: (before: Partial<HistoryStyle>, after: Partial<HistoryStyle>) => ChangeEntry[];

package/dist/history/diff.mjs

@@ -0,0 +1,73 @@
+//#region src/history/diff.ts
+var e = (t, n) => {
+	if (t === n) return !0;
+	if (typeof t != "object" || typeof n != "object" || t === null || n === null || Array.isArray(t) !== Array.isArray(n)) return !1;
+	if (Array.isArray(t) && Array.isArray(n)) return t.length === n.length && t.every((t, r) => e(t, n[r]));
+	let r = t, i = n, a = Object.keys(r).filter((e) => r[e] !== void 0);
+	return a.length === Object.keys(i).filter((e) => i[e] !== void 0).length && a.every((t) => Object.hasOwn(i, t) && e(r[t], i[t]));
+}, t = (e) => JSON.parse(JSON.stringify(e)), n = (t, n, r) => {
+	let i = [];
+	for (let [a, o] of Object.entries(r)) Object.hasOwn(n, a) ? e(n[a], o) || i.push({
+		kind: t,
+		id: a,
+		op: "update",
+		before: n[a],
+		after: o
+	}) : i.push({
+		kind: t,
+		id: a,
+		op: "add",
+		after: o
+	});
+	for (let [e, a] of Object.entries(n)) Object.hasOwn(r, e) || i.push({
+		kind: t,
+		id: e,
+		op: "remove",
+		before: a
+	});
+	return i;
+}, r = (e, t) => Object.fromEntries((e ?? []).map((e) => [t(e), e])), i = (e, t) => Object.fromEntries(Object.entries(t ?? {}).map(([t, n]) => [`${e}.${t}`, n])), a = (e, t) => [
+	...n("element", e.flat ?? {}, t.flat ?? {}),
+	...n("folder", r(e.pageFolders, (e) => e.id), r(t.pageFolders, (e) => e.id)),
+	...n("variable", r(e.variables, (e) => e.name), r(t.variables, (e) => e.name)),
+	...n("setting", {
+		...i("settings", e.settings),
+		...i("definition", e.definition),
+		pages: e.pages
+	}, {
+		...i("settings", t.settings),
+		...i("definition", t.definition),
+		pages: t.pages
+	})
+], o = {
+	class: "selector",
+	element: "globalStyle",
+	id: "idStyle"
+}, s = (e) => {
+	let t = {};
+	for (let [n, r] of Object.entries(e ?? {})) for (let [e, i] of Object.entries(r)) {
+		let r = o[i.type], a = t[r] ??= {};
+		(a[e] ??= {})[n] = i;
+	}
+	return t;
+}, c = (e) => Object.fromEntries(Object.entries(e ?? {}).flatMap(([e, t]) => Object.entries(t).map(([t, n]) => [`${e}/${t}`, n]))), l = (e, t) => {
+	let i = s(e.platform), a = s(t.platform);
+	return [
+		...[
+			"selector",
+			"globalStyle",
+			"idStyle"
+		].flatMap((e) => n(e, i[e] ?? {}, a[e] ?? {})),
+		...n("token", c(e.variables), c(t.variables)),
+		...n("font", r(e.fonts, (e) => e.family), r(t.fonts, (e) => e.family)),
+		...n("setting", {
+			theme: e.theme,
+			mode: e.mode
+		}, {
+			theme: t.theme,
+			mode: t.mode
+		})
+	];
+};
+//#endregion
+export { a as diffSchema, l as diffStyle, t as jsonCopy, e as sameValue };

package/dist/history/index.d.ts

@@ -0,0 +1,3 @@
+export * from './describe';
+export * from './diff';
+export * from './types';

package/dist/history/index.mjs

@@ -0,0 +1,3 @@
+import { describeChange as e, fieldChanges as t, uniqueLines as n } from "./describe.mjs";
+import { diffSchema as r, diffStyle as i, jsonCopy as a, sameValue as o } from "./diff.mjs";
+export { e as describeChange, r as diffSchema, i as diffStyle, t as fieldChanges, a as jsonCopy, o as sameValue, n as uniqueLines };

package/dist/history/types.d.ts

@@ -0,0 +1,48 @@
+/** Which of a space's documents a change was made to: its schema, its style, or its functions' source. */
+export type ChangeDocument = 'schema' | 'style' | 'functions';
+/**
+ * Where a change came from: a person in the builder, an agent over MCP, the builder's co-worker, the autofix, a GraphQL
+ * client that is not a person, or a writer with nothing to say (a seed, a script).
+ */
+export type ChangeOrigin = 'builder' | 'mcp' | 'coworker' | 'autofix' | 'api' | 'system';
+/**
+ * What one entry is about. Schema: an element (pages and layouts are elements too), a page folder, a schema variable,
+ * a setting (`settings.<key>`, `definition.<key>`, the page order `pages`). Style: a class selector, a global style
+ * (a bare element selector), an id style, a design token (`<category>/<name>`), a font family, a style setting
+ * (`theme`, `mode`). Functions: a file of their source, by its path (`index.ts`, `lib/feed.ts`).
+ */
+export type ChangeKind = 'element' | 'folder' | 'variable' | 'setting' | 'selector' | 'globalStyle' | 'idStyle' | 'token' | 'font' | 'file';
+/** One entity that changed, whole, before and after: the field-level difference is derived from the two. */
+export type ChangeEntry = {
+    kind: ChangeKind;
+    id: string;
+    op: 'add' | 'remove' | 'update';
+    /** Absent on `add`. */
+    before?: unknown;
+    /** Absent on `remove`. */
+    after?: unknown;
+};
+export type ChangeAuthor = {
+    userId: number | null;
+    name: string;
+};
+/** One save that changed something: who, from where, and every entity it touched. */
+export type SpaceChange = {
+    spaceId: number;
+    environment: string;
+    /** Monotonic per space and environment: the timeline's order and the address of a point in it. */
+    seq: number;
+    /** Milliseconds. */
+    at: number;
+    document: ChangeDocument;
+    author: ChangeAuthor;
+    origin: ChangeOrigin;
+    /** The MCP client's name, or the builder tab's instance id. */
+    client?: string;
+    /** Everything one request wrote shares it: one builder request, one `plitzi_apply`, one autofix. */
+    batch: string;
+    entries: ChangeEntry[];
+    summary: string;
+    /** The entries name what changed but carry no values: the whole change was too large to store as one record. */
+    truncated?: boolean;
+};

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export * from './devTools';
 export * from './theme';
 export * from './server';
 export * from './state';
+export * from './history';