@plitzi/sdk-shared 0.37.2 → 0.37.4

package/dist/realtime/presence.mjs

@@ -0,0 +1,70 @@
+import { PRESENCE_TYPE as e } from "./topics.mjs";
+//#region src/realtime/presence.ts
+var t = 2e4, n = 65e3, r = /* @__PURE__ */ new WeakMap(), i = (r, i, a) => {
+	let o = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Set(), c = /* @__PURE__ */ new Set(), l, u = !1, d = () => [...u && r.me ? [{
+		from: r.me,
+		state: l,
+		me: !0
+	}] : [], ...[...o.values()].map((e) => e.member)], f = () => {
+		let e = d();
+		c.forEach((t) => t.onChange(e));
+	}, p = (e) => {
+		let t = e.flatMap((e) => {
+			let t = o.get(e);
+			return o.delete(e), t ? [t.member] : [];
+		});
+		if (t.length) {
+			f();
+			for (let e of t) c.forEach((t) => t.onDepart?.(e));
+		}
+	}, m = () => {
+		u && r.publish(i, e, l);
+	}, h = r.subscribe(i, (e) => {
+		if (e.from !== r.me) {
+			if (e.type === "$presence") {
+				let t = {
+					from: e.from,
+					...e.user ? { user: e.user } : {},
+					state: e.data,
+					me: !1
+				}, n = !o.has(e.from) && s.delete(e.from);
+				o.set(e.from, {
+					member: t,
+					heardAt: Date.now()
+				}), f(), n && c.forEach((e) => e.onArrive?.(t));
+			} else e.type === "$leave" ? (s.delete(e.from), p([e.from])) : e.type === "$join" ? (s.add(e.from), m()) : e.type === "$revoked" && e.from === "server" && (o.clear(), s.clear(), f());
+			c.forEach((t) => t.onMessage?.(e));
+		}
+	}), g = r.onStatus((e) => {
+		e === "open" && (m(), f());
+	}), _ = setInterval(() => {
+		m();
+		let e = Date.now();
+		p([...o].filter(([, t]) => e - t.heardAt > n).map(([e]) => e));
+	}, t);
+	return {
+		members: d,
+		set: (e) => {
+			l = e, u = !0, m(), f();
+		},
+		listeners: c,
+		teardown: () => {
+			clearInterval(_), g(), h(), a();
+		}
+	};
+}, a = (e, t, n) => {
+	let a = r.get(e) ?? /* @__PURE__ */ new Map();
+	r.set(e, a);
+	let o = a.get(t) ?? i(e, t, () => a.delete(t));
+	a.set(t, o), o.listeners.add(n);
+	let s = o.members();
+	return s.length && n.onChange(s), {
+		set: o.set,
+		members: o.members,
+		stop: () => {
+			o.listeners.delete(n) && !o.listeners.size && o.teardown();
+		}
+	};
+};
+//#endregion
+export { a as trackPresence };

package/dist/realtime/topics.d.ts

@@ -0,0 +1,36 @@
+import { ChannelDeclaration, ChannelDeclarations } from '../types/RealtimeTypes';
+export declare const isValidTopic: (topic: string) => boolean;
+export type ChannelMatch = {
+    pattern: string;
+    declaration: ChannelDeclaration;
+};
+/**
+ * The declaration a topic falls under — the first pattern that matches it — or `undefined` when none does.
+ *
+ * One function for the server that authorises a subscription, the linter that checks a page's topic and the client
+ * that opens it, so the three cannot disagree about what `board:{id}` covers.
+ */
+export declare const matchChannel: (topic: string, declarations: ChannelDeclarations | undefined) => ChannelMatch | undefined;
+/**
+ * What is wrong with one channel of a space, each as a sentence that says how to write it — empty when nothing is.
+ *
+ * One check for every writer: authoring refuses the first, `lintSpace` reports them all for what the builder and an
+ * agent write, and the server never has to guess what a malformed declaration meant. Read as `unknown`, because a
+ * space from JSON or from an agent has no type to hold it.
+ */
+export declare const channelProblems: (pattern: string, declaration: unknown) => string[];
+/** Channel limits, with the defaults a declaration leaves out. */
+export declare const channelLimits: (declaration: ChannelDeclaration) => {
+    maxMessageBytes: number;
+    messagesPerSecond: number;
+};
+/** The types a channel keeps for itself: a member's state, a member gone, a member arrived. */
+export declare const PRESENCE_TYPE = "$presence";
+export declare const LEAVE_TYPE = "$leave";
+/** A member arrived: the others answer with their `$presence`, so the newcomer sees everyone at once. */
+export declare const JOIN_TYPE = "$join";
+/**
+ * What a page hears on a topic when the grant it opened it with is revoked (`realtime.revoke`): it is let go of the
+ * topic, and hears nothing more on it until a new grant opens it again.
+ */
+export declare const REVOKED_TYPE = "$revoked";

package/dist/realtime/topics.mjs

@@ -0,0 +1,25 @@
+//#region src/realtime/topics.ts
+var e = /^[A-Za-z0-9:_.-]{1,128}$/, t = (t) => e.test(t), n = (e) => RegExp(`^${e.split(/(\{[A-Za-z0-9_]+\})/).map((e) => /^\{[A-Za-z0-9_]+\}$/.test(e) ? "[A-Za-z0-9_.-]{1,64}" : e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("")}$`), r = (e, r) => {
+	if (!r || !t(e)) return;
+	let i = Object.keys(r).find((t) => n(t).test(e));
+	return i === void 0 ? void 0 : {
+		pattern: i,
+		declaration: r[i]
+	};
+}, i = /^(?=.)[A-Za-z0-9:_.-]*(\{[A-Za-z0-9_]+\}[A-Za-z0-9:_.-]*)*$/, a = /* @__PURE__ */ new Set([
+	"public",
+	"session",
+	"role"
+]), o = (e) => typeof e == "object" && !!e && !Array.isArray(e), s = (e, t) => {
+	let n = [];
+	if (i.test(e) || n.push("a pattern is letters, digits and `:_.-`, with `{name}` for the part a page fills in — `board:{id}`"), !o(t)) return [...n, "a channel is an object: `{ access: { mode: \"public\" } }`"];
+	let { access: r, publish: s, presence: c, grant: l, maxMessageBytes: u, messagesPerSecond: d } = t, f = o(r) ? r.mode : void 0;
+	typeof f != "string" || !a.has(f) ? n.push("`access` is { mode: \"public\" }, { mode: \"session\" } or { mode: \"role\", permissions: […] }") : f === "role" && !(o(r) && Array.isArray(r.permissions) && r.permissions.every((e) => typeof e == "string")) && n.push("`access: { mode: \"role\" }` names the permissions it needs: `permissions: [\"boardEdit\"]`"), s !== void 0 && s !== "clients" && s !== "server" && n.push("`publish` is \"clients\" (pages send) or \"server\" (only a flow's realtime.publish)"), c !== void 0 && typeof c != "boolean" && n.push("`presence` is true or false"), l !== void 0 && typeof l != "boolean" && n.push("`grant` is true (a page needs a grant from `realtime.grant` to open a topic) or false");
+	for (let [e, t] of [["maxMessageBytes", u], ["messagesPerSecond", d]]) t !== void 0 && (typeof t != "number" || !Number.isInteger(t) || t <= 0) && n.push(`\`${e}\` is a whole number above zero`);
+	return n;
+}, c = (e) => ({
+	maxMessageBytes: e.maxMessageBytes ?? 4096,
+	messagesPerSecond: e.messagesPerSecond ?? 30
+}), l = "$presence", u = "$leave", d = "$join", f = "$revoked";
+//#endregion
+export { d as JOIN_TYPE, u as LEAVE_TYPE, l as PRESENCE_TYPE, f as REVOKED_TYPE, c as channelLimits, s as channelProblems, t as isValidTopic, r as matchChannel };

package/dist/server/actions/useRealtimeSync.d.ts

@@ -0,0 +1,9 @@
+import { ServerSSR } from '../../types';
+/**
+ * Seeds where this origin's realtime channels answer, once, at the SDK root — as `useActionsSync` does for actions.
+ *
+ * Only a server that mounts the endpoint publishes the path, so a render without one (the builder, an embed, an
+ * offline widget) leaves every `channel` closed rather than reconnecting forever to a 404.
+ */
+declare const useRealtimeSync: (ssr?: ServerSSR) => void;
+export default useRealtimeSync;

package/dist/server/actions/useRealtimeSync.mjs

@@ -0,0 +1,7 @@
+import { useCommonStoreSync as e } from "../../store/index.mjs";
+//#region src/server/actions/useRealtimeSync.ts
+var t = (t) => {
+	e(["realtime.endpoint", "realtime.transport"], [t?.realtimePath, t?.realtimeTransport]);
+};
+//#endregion
+export { t as default };

package/dist/state/index.d.ts

@@ -1 +1,2 @@
+export * from './paintedState';
 export * from './runtimeStatePersist';

package/dist/state/index.mjs

@@ -1,2 +1,3 @@
-import { runtimeStatePersist as e, stateOwner as t } from "./runtimeStatePersist.mjs";
-export { e as runtimeStatePersist, t as stateOwner };
+import { PAINTED_STATE_BUDGET as e, clearPaintedEntry as t, paintedEntryFromCookies as n, paintedKeys as r, paintedStateCookieName as i, paintedStateFor as a, pickPainted as o, readPaintedEntry as s, writePaintedEntry as c } from "./paintedState.mjs";
+import { runtimeStatePersist as l, stateOwner as u } from "./runtimeStatePersist.mjs";
+export { e as PAINTED_STATE_BUDGET, t as clearPaintedEntry, n as paintedEntryFromCookies, r as paintedKeys, i as paintedStateCookieName, a as paintedStateFor, o as pickPainted, s as readPaintedEntry, l as runtimeStatePersist, u as stateOwner, c as writePaintedEntry };

package/dist/state/paintedState.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The kept state a space's first paint depends on, where the server can read it.
+ *
+ * Kept state (`keepState`) lives in web storage, which only the browser can read, and it is restored after hydration
+ * — it has to be: restored during it, the markup would differ from the server's and React would throw the tree away.
+ * So anything kept that changes what is drawn arrives a moment late: the server paints the space's defaults, and the
+ * page swaps in what the visitor chose. A toolbar showing the tool last picked, a name in an avatar, a panel left off.
+ *
+ * The keys a space declares in `settings.paintedState` are written to a cookie as well. The server reads it, renders
+ * with those values and hands them to the page as its starting state — so the first paint is already the visitor's,
+ * and the restore that follows finds nothing to change. Everything else stays in web storage: the cookie travels with
+ * every request, so it holds only what the first paint needs, and never more than {@link PAINTED_STATE_BUDGET}.
+ *
+ * The entry carries who wrote it, as the kept state in web storage does, and a page that finds it written by somebody
+ * else discards what it rendered with. The server cannot tell — who the visitor is, for a space with its own sign-in,
+ * is only settled in the browser.
+ */
+/** Bytes of the encoded value: well inside the 4096 a browser allows a cookie, name and attributes included. */
+export declare const PAINTED_STATE_BUDGET = 3072;
+export type PaintedEntry = {
+    owner: string;
+    values: Record<string, unknown>;
+};
+/**
+ * Per space, as the web storage key is (`plitzi_<webId>_state`) — and per port, because a cookie's scope is the host
+ * without it: two spaces served from `localhost` on two ports would otherwise read each other's. See `debugCookieName`.
+ */
+export declare const paintedStateCookieName: (webId: number, host: string | undefined) => string;
+/** The keys a space declared, as a set — an empty one when it declared none. */
+export declare const paintedKeys: (settings: {
+    paintedState?: unknown;
+} | undefined) => Set<string>;
+/** The declared keys' values out of `runtime.state` — a key with no value is left out, not written as `undefined`. */
+export declare const pickPainted: (state: unknown, keys: ReadonlySet<string>) => Record<string, unknown>;
+/**
+ * The entry in a `Cookie` header, or `undefined` when there is none or it is not one — a cookie is the visitor's to
+ * edit, so its shape is checked rather than assumed.
+ */
+export declare const paintedEntryFromCookies: (cookies: string | undefined, name: string) => PaintedEntry | undefined;
+/**
+ * What the server renders with: the entry's values for the keys the space declares — a key it no longer declares, or
+ * one the visitor added, is not the server's to render.
+ */
+export declare const paintedStateFor: (cookies: string | undefined, name: string, keys: ReadonlySet<string>) => Record<string, unknown> | undefined;
+/** The entry in this document's cookies. */
+export declare const readPaintedEntry: (name: string) => PaintedEntry | undefined;
+/**
+ * Writes the entry, or says why it did not: `too-large` over the budget — the cookie is then removed, so a stale value
+ * is not rendered in its place — and `unavailable` where cookies may not be written at all.
+ */
+export declare const writePaintedEntry: (name: string, entry: PaintedEntry) => "written" | "too-large" | "unavailable";
+export declare const clearPaintedEntry: (name: string) => void;

package/dist/state/paintedState.mjs

@@ -0,0 +1,37 @@
+import { cookieFromHeader as e, documentCookies as t } from "../helpers/cookies.mjs";
+//#region src/state/paintedState.ts
+var n = 3072, r = 31536e3, i = (e, t) => {
+	let n = t?.split(":")[1];
+	return n ? `plitzi_${e}_painted_${n}` : `plitzi_${e}_painted`;
+}, a = (e) => typeof e == "object" && !!e && !Array.isArray(e), o = (e) => new Set(Array.isArray(e?.paintedState) ? e.paintedState.filter((e) => typeof e == "string" && e !== "") : []), s = (e, t) => a(e) ? Object.fromEntries(Object.entries(e).filter(([e, n]) => t.has(e) && n !== void 0)) : {}, c = (t, n) => {
+	let r = e(t, n);
+	if (r !== void 0) try {
+		let e = JSON.parse(r);
+		return a(e) && typeof e.owner == "string" && a(e.values) ? {
+			owner: e.owner,
+			values: e.values
+		} : void 0;
+	} catch {
+		return;
+	}
+}, l = (e, t, n) => {
+	if (n.size === 0) return;
+	let r = c(e, t);
+	if (!r) return;
+	let i = s(r.values, n);
+	return Object.keys(i).length > 0 ? i : void 0;
+}, u = (e) => c(t(), e), d = (e, t) => {
+	let n = encodeURIComponent(JSON.stringify(t));
+	if (n.length > 3072) return f(e), "too-large";
+	try {
+		return document.cookie = `${e}=${n};path=/;max-age=${r};SameSite=Lax`, "written";
+	} catch {
+		return "unavailable";
+	}
+}, f = (e) => {
+	try {
+		document.cookie = `${e}=;path=/;max-age=0;SameSite=Lax`;
+	} catch {}
+};
+//#endregion
+export { n as PAINTED_STATE_BUDGET, f as clearPaintedEntry, c as paintedEntryFromCookies, o as paintedKeys, i as paintedStateCookieName, l as paintedStateFor, s as pickPainted, u as readPaintedEntry, d as writePaintedEntry };

package/dist/state/runtimeStatePersist.d.ts

@@ -15,6 +15,13 @@ export type StateOwner = {
     kind: 'account';
     id: string;
 };
-/** `undefined` while auth has not settled: nothing kept can be told apart yet from somebody else's. */
+/**
+ * `undefined` while nobody can say yet: nothing kept can be told apart from somebody else's.
+ *
+ * That includes the moment before the `auth` source EXISTS. GlobalSources publishes it for every space — `{}` for one
+ * with no accounts, a `status` for one with a provider — but only once it mounts, and the store is asked for its
+ * storage before that. Read as "the browser" there, the first read of every visit found the guest's entry, called it
+ * somebody else's, and deleted it: a space with `keepState` kept nothing past a reload.
+ */
 export declare const stateOwner: (state: CommonState) => StateOwner | undefined;
 export declare const runtimeStatePersist: <TState extends CommonState>(webId: number) => StoreMiddleware<TState>;

package/dist/state/runtimeStatePersist.mjs

@@ -1,23 +1,27 @@
-import { persistMiddleware as e } from "@plitzi/nexus";
+import { pConsole as e } from "../devTools/utils/PlitziConsole.mjs";
+import { clearPaintedEntry as t, paintedKeys as n, paintedStateCookieName as r, pickPainted as i, readPaintedEntry as a, writePaintedEntry as o } from "./paintedState.mjs";
+import { persistMiddleware as s } from "@plitzi/nexus";
 //#region src/state/runtimeStatePersist.ts
-var t = /* @__PURE__ */ new Set([
+var c = /* @__PURE__ */ new Set([
 	"init",
 	"initLoading",
 	"authenticating"
-]), n = (e) => {
-	let n = e.runtime?.sources.auth;
-	if (!n || n.status === void 0) return { kind: "browser" };
-	if (!t.has(n.status)) return n.isAuthenticated && n.details?.id !== void 0 ? {
-		kind: "account",
-		id: String(n.details.id)
-	} : { kind: "guest" };
-}, r = (e) => {
+]), l = (e) => {
+	let t = e.runtime?.sources.auth;
+	if (t) {
+		if (t.status === void 0) return { kind: "browser" };
+		if (!c.has(t.status)) return t.isAuthenticated && t.details?.id !== void 0 ? {
+			kind: "account",
+			id: String(t.details.id)
+		} : { kind: "guest" };
+	}
+}, u = (e) => {
 	switch (e.kind) {
 		case "account": return `user:${e.id}`;
 		case "guest": return "guest";
 		case "browser": return "";
 	}
-}, i = (e, t) => ({
+}, d = (e, t) => ({
 	getItem: (n) => {
 		let r = e.getItem(n);
 		if (r === null) return null;
@@ -32,35 +36,81 @@ var t = /* @__PURE__ */ new Set([
 		payload: r
 	})),
 	removeItem: (t) => e.removeItem(t)
-}), a = (e) => {
+}), f = "runtime.state", p = (e) => typeof e == "object" && !!e && !Array.isArray(e), m = (e, t) => Object.fromEntries(Object.entries(e).filter(([e]) => !t.has(e))), h = (e, t) => p(e) ? Object.fromEntries(Object.entries(e).filter(([e]) => t.has(e))) : {}, g = (e) => e.schema?.settings, _ = (e) => new Set((e?.transientState ?? []).filter((e) => typeof e == "string" && e !== "")), v = (e) => {
 	try {
 		return e === "session" ? globalThis.sessionStorage : globalThis.localStorage;
 	} catch {
 		return;
 	}
-}, o = (t) => {
-	let o = e({
-		key: `plitzi_${t}_state`,
-		paths: ["runtime.state"],
+}, y = (s, c) => {
+	let d = r(c, typeof window > "u" ? void 0 : window.location.host), f = !1, h;
+	return () => {
+		let r = s.getState();
+		if (typeof document > "u" || r.render?.isHydrating && !r.render.hydrated) return;
+		let c = g(r), _ = n(c), v = l(r);
+		if (!c?.keepState || _.size === 0 || v === void 0) return;
+		let y = u(v), b = r.runtime?.state;
+		if (!f) {
+			f = !0;
+			let e = a(d);
+			if (e && e.owner !== y && (t(d), p(b) && [..._].some((e) => e in b))) {
+				s.setState("runtime.state", m(b, _));
+				return;
+			}
+			h = e?.owner === y ? JSON.stringify(i(e.values, _)) : void 0;
+		}
+		let x = i(b, _), S = JSON.stringify(x);
+		if (S !== h) {
+			if (h = S, Object.keys(x).length === 0) {
+				t(d);
+				return;
+			}
+			o(d, {
+				owner: y,
+				values: x
+			}) === "too-large" && e.warning("store", `settings.paintedState holds more than a cookie can carry — the first paint uses the space's defaults for ${[..._].join(", ")}. Declare only what the first paint shows.`, {
+				storeName: "runtime",
+				path: "runtime.state",
+				prev: void 0,
+				next: x
+			});
+		}
+	};
+}, b = (e) => {
+	let t = s({
+		key: `plitzi_${e}_state`,
+		paths: [f],
+		partializePath: (e, t, n) => p(t) ? m(t, _(g(n))) : t,
+		mergePath: (e, t, n, r) => {
+			let i = _(g(r));
+			return i.size > 0 && p(t) ? {
+				...m(t, i),
+				...h(n, i)
+			} : t;
+		},
 		storage: (e) => {
-			let { schema: t, render: o } = e;
-			if (o?.isHydrating && !o.hydrated) return !1;
-			let s = t?.settings, c = n(e);
-			if (!s?.keepState || c === void 0) return !1;
-			let l = a(s.stateStorage === "sessionStorage" ? "session" : "local");
-			return l ? i(l, r(c)) : !1;
+			let { render: t } = e;
+			if (t?.isHydrating && !t.hydrated) return !1;
+			let n = g(e), r = l(e);
+			if (!n?.keepState || r === void 0) return !1;
+			let i = v(n.stateStorage === "sessionStorage" ? "session" : "local");
+			return i ? d(i, u(r)) : !1;
 		}
 	});
-	return (e) => {
-		let t = o(e), i = e.getState().runtime?.state, a = n(e.getState());
+	return (r) => {
+		let i = t(r), a = r.getState().runtime?.state, o = l(r.getState()), s = y(r, e);
 		return {
-			...t,
-			onChange: (o) => {
-				let s = a, c = n(e.getState());
-				c !== void 0 && (a = c), s?.kind === "account" && c !== void 0 && r(c) !== r(s) && e.setState("runtime.state", i), t?.onChange?.(o);
+			...i,
+			onChange: (e) => {
+				let t = o, c = l(r.getState());
+				if (c !== void 0 && (o = c), t?.kind === "account" && c !== void 0 && u(c) !== u(t)) {
+					let e = p(a) ? m(a, n(g(r.getState()))) : a;
+					r.setState("runtime.state", e);
+				}
+				i?.onChange?.(e), s();
 			}
 		};
 	};
 };
 //#endregion
-export { o as runtimeStatePersist, n as stateOwner };
+export { b as runtimeStatePersist, l as stateOwner };