@plitzi/sdk-elements 0.38.14 → 0.38.15

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @plitzi/sdk-elements
 
+## 0.38.15
+
+### Patch Changes
+
+- 6cdd5cf: ## Security
+
+  - **A write another site caused is refused, cookie or none** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): the page
+    server guarded nothing it answers past `/auth` — a server action (`/_action`), a realtime publish, a space's `/fn/`
+    route, its runtime's endpoints, the deployment's own `data` stages, the adapter-only `loginPath`, `logoutPath` and
+    `exchangePath`. A plain `text/plain` POST from any page open in the same browser ran them, with the visitor's session
+    cookie when there was one (`SameSite=None` off this machine) and, in a project nobody signs in to, as whoever holds
+    the server's own credentials. Every unsafe request a browser says another site caused (`Sec-Fetch-Site: cross-site`,
+    or a foreign `Origin`) is now refused `403 reason: 'foreign'`, saying how to allow it: `crossSiteWrites.origins`
+    (with `auth`, `identity.platformOrigins` too) and `crossSiteWrites.paths` for a form other sites post to by design.
+    `Authorization`, and callers that are not browsers — webhooks, scripts — pass as before. One rule for this and the
+    sign-in check (`crossSiteRequest`, `csrf.ts`). A self-hosted runtime's endpoints now sit where the platform forwards a
+    space's — after the auth chain and this guard (`data`, was `preAuth`).
+
+  ## Testing
+  - **`page check` and `page shot` anywhere the project is served** (`@plitzi/cli`): `--url <origin>` for a second server
+    of it, staging or a deploy, instead of `npm start`'s port; `page check --space <module>` holds the pages to that space
+    instead of the project's — an agent's page — authored with `authorIsolated`.
+  - **A route with a query is checked as its page** (`@plitzi/cli`): `page check "/?v=2"` matched the query as part of
+    the path, found no page, and checked the space's "not found" page in its place.
+
+  - **What an element that chooses its children draws is checked** (`@plitzi/sdk-authoring`, `@plitzi/cli`): with
+    `choosesChildren`, the page checks owed none of its children — and checked none of them either: a dashboard drawing
+    three panels reported `checked: 1`. Each child it may draw, and what is inside one under no condition of its own,
+    now carries `shownWith` (the child it comes with) on its handle: once that child is on screen it and everything
+    named in it are owed like the rest of the page, and `checked` counts them. `onScreenIfChosen(handles, page)` lists
+    them.
+  - **A page that met a server error is looked at once more** (`@plitzi/cli`): `page check` and `verify` failed a page
+    for a `500` from somebody else's service having a bad second (`/fn/<space>/weather`), and passed on the next run with
+    nothing changed. A page whose requests got a `5xx` is checked again once; its report is the second look, and says
+    what failed the first time (`retriedAfter`). A `4xx` fails the same way twice, and is never retried.
+
+  ## Plugins
+  - **`useNotify`** (`@plitzi/plitzi-sdk`): a plugin shows the page's notifications — `notify('Deleted 79 recordings', {
+appearance: 'danger' })` — the same toasts an `addNotification` step shows, in the space's theme and `notifications`
+    look, with no trigger, flow or `window` event of the space's to wire. The step's vocabulary (`NOTIFICATION_PLACEMENTS`,
+    `NOTIFICATION_APPEARANCES`, `NOTIFICATION_DEFAULTS`) is one list in `@plitzi/sdk-shared`, read by both.
+  - **`appearance: 'danger'` looks like one** (`@plitzi/plitzi-sdk`): it reached the toast library as a type it does not
+    know, so a danger notification showed neither the error icon nor the colour `notifications.danger` sets.
+    A value a notification does not take — from a flow, or a plugin in plain JavaScript — is set aside by name and said
+    in the console, rather than shown as the default in silence (`readNotificationOptions`, `@plitzi/sdk-shared`).
+  - **`useServerAction`** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-authoring`, `@plitzi/sdk-interactions`,
+    `@plitzi/sdk-server`): a plugin runs one of the space's server actions, awaited —
+    `useServerAction<typeof habitDone>('habits-done')({ id })` answers `{ ok, output }` or `{ ok: false, reason, error }`
+    — through the `runServerAction` step itself: the same access, refusals, session handling and dev-tools entry.
+    `defineAction` keeps the literal types of its `call` way in, so the input is typed by the fields it declares (the
+    required ones required); `taskAction` types both ends from the task's `run`, and `FunctionTask<T, R>` takes what
+    `run` answers. `CallInputOf` / `CallOutputOf` read them. One operation is one action, never a `case` in one route.
+    What a run answers is typed (`ServerActionStatus`): a status the server never uses reads as a run that did not
+    complete, never as one that did.
+    The key those types ride under (`CALL_TYPES`) is exported, by `@plitzi/sdk-shared` and `@plitzi/sdk-authoring` with
+    `TypedActionEntry`, `CallInputOf` and `CallOutputOf`: a package that emits declarations could not write the type of an
+    action it exports (`TS4023` on every `export const actions = [defineAction(…)]`).
+  - **A plugin is drawn on the server first** (docs): a preference per device belongs in kept state (`keepState`,
+    `paintedState`) as a bound prop, never read from `localStorage` while rendering — React discards the whole tree on the
+    mismatch, and only in the browser of whoever saved something. `@plitzi/plitzi-ui` is not the page's: a plugin
+    importing it bundles its own copy, with its own contexts and its own look. The authoring skill's `plugin-reach.md`
+    says what a plugin says and to whom: a notification, another element (an event and the space's flow), a server
+    action, shared state, other pages.
+
+  ## Realtime
+  - **A channel that retains** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`): declared
+    `retain: true` (with `publish: 'server'`, which authoring requires), the server keeps the latest message of each type
+    on a topic — said by `ctx.publish` or a flow's `realtime.publish` — and hands them to every page that joins, marked
+    `retained`. A page reads them as `<channel>.retained.<type>`, a plugin as `useChannel(topic).retained`, the newest of
+    a type holding whichever order they arrive in; `null` forgets a type. Kept in the store the actions' `kv` uses (beside
+    the grants, by compare-and-swap), so every replica hands out the same; a topic keeps at most 64 types and 512 KB, and
+    a publish past that is refused before anything is sent. State every screen shares is one publish and one binding —
+    no kv key, initial read or copy in `state` of the project's own. The fleet store `realtime.grants` is now
+    `realtime.kv`.
+  - **The MCP writes every field a channel takes** (`@plitzi/sdk-mcp`): `patchSettings`'s channel had no `grant` — which
+    the guide taught — nor `retain` or the limits, so an agent could not declare a private channel at all. All are there
+    now, and the guide says what `retain` is for and that `channel_<id>.retained` holds it.
+
+  ## Authoring
+  - **`plitzi explain` knows every `@plitzi` package installed** (`@plitzi/cli`): a name that was not
+    `@plitzi/sdk-authoring`'s (`createServer`, `createJsonAdapters`, `useChannel`) was answered as the project's own code,
+    to `grep` in `src/`. It is read from the published types of every one installed, through their re-exports and entry
+    points (`@plitzi/sdk-server/handlers`), and a name two packages export — `createServer` is sdk-server's and sdk-mcp's
+    — is answered with both.
+
+  - **A space module somebody else wrote, authored where it reaches nothing** (`@plitzi/sdk-authoring`):
+    `authorIsolated(file, { timeoutMs })` of `@plitzi/sdk-authoring/node` runs `authorSpace` on it in a process Node's
+    permission model holds to reading the module's folder and its packages — no file written, no process started, no
+    variable of the caller's environment — kills one that runs too long, and validates what it answers again, so a forged
+    answer gains nothing. A refusal comes back as `authorSpace` says it, with the problems as data.
+  - **Pages an agent writes, served** (`@plitzi/sdk-server`): `createAuthoringHost({ dir, frameAncestors })` serves each
+    space it is handed at an address of its own (`put(space, { id }) → /?__pt=<id>`) as a draft of its one space, kept in
+    `dir` across restarts; `drop(id)` forgets one, and anything else answers `404` saying where the pages are.
+  - **A space is chosen by host or credential** (`@plitzi/sdk-server`, docs): `getSpaceDeployment` is asked on every
+    request, and what a page fetches after it carries nothing of its address but the host — a space chosen by the page's
+    query or path lost everything it asked for, and `/_plitzi/space/<hash>.json` answered a bare `404`. The contract and
+    the README say so (the README offered "by path prefix"), and that `404` says why.
+
+  - **`plitzi explain on` says how to read what a trigger carries** (`@plitzi/sdk-authoring`): its doc sat above a
+    helper, so `explain` printed only the signature. It now leads with `[named('picked', on('onPick')), …('{{ picked.seat
+}}')]`, and the CLI skill's plugin section says the same.
+
+- Updated dependencies [6cdd5cf]
+  - @plitzi/sdk-auth@0.38.15
+  - @plitzi/sdk-event-bridge@0.38.15
+  - @plitzi/sdk-interactions@0.38.15
+  - @plitzi/sdk-navigation@0.38.15
+  - @plitzi/sdk-schema@0.38.15
+  - @plitzi/sdk-shared@0.38.15
+
 ## 0.38.14
 
 ### Patch Changes

package/dist/elements/provider/Channel/Channel.mjs

@@ -62,11 +62,13 @@ var S = (e) => {
 		me: R.me ?? "",
 		members: R.members,
 		messages: N,
-		last: N.at(-1) ?? null
+		last: N.at(-1) ?? null,
+		retained: R.retained
 	}), [
 		R.connected,
 		R.me,
 		R.members,
+		R.retained,
 		N
 	]), H = c(() => i(V), [V]);
 	_({

package/dist/elements/provider/Channel/declaration.mjs

@@ -93,7 +93,7 @@ var n = e()({
 		},
 		definition: {
 			label: "Channel",
-			description: "A realtime channel: every OTHER page on the same `topic` hears what one publishes, within milliseconds — the page that sent it too with `echo` (its `from` is then the `me` of the channel). The topic must match a channel the space declares in its settings (`channels`), e.g. `board:{{ id }}` under `board:{id}`. A topic of a private channel (`grant: true`) opens only with `grant`, bound to the grant the action that let this visitor in returned (its `realtime.grant` step). ITS DESCENDANTS bind to its source `channel_<id>`: `connected`, `members` (with the state each announced), `messages` (the last `keep`) and `last`. It fires `onMessage`; `onJoin` when somebody who came after this page has announced who they are, and `onLeave` when somebody goes — each with `from`, `user` and the `state` they announced; and answers `publish({ type, data, echo })` and `setPresence({ data })`; `presence` is the state this page announces (a name, a colour). Closed in the builder and anywhere without a server.",
+			description: "A realtime channel: every OTHER page on the same `topic` hears what one publishes, within milliseconds — the page that sent it too with `echo` (its `from` is then the `me` of the channel). The topic must match a channel the space declares in its settings (`channels`), e.g. `board:{{ id }}` under `board:{id}`. A topic of a private channel (`grant: true`) opens only with `grant`, bound to the grant the action that let this visitor in returned (its `realtime.grant` step). ITS DESCENDANTS bind to its source `channel_<id>`: `connected`, `members` (with the state each announced), `messages` (the last `keep`), `last` and — on a `retain: true` channel — `retained`, the latest data the server said of each type, there as the page joins (`retained.lists`). It fires `onMessage`; `onJoin` when somebody who came after this page has announced who they are, and `onLeave` when somebody goes — each with `from`, `user` and the `state` they announced; and answers `publish({ type, data, echo })` and `setPresence({ data })`; `presence` is the state this page announces (a name, a colour). Closed in the builder and anywhere without a server.",
 			items: []
 		},
 		market: {

package/dist/realtime/useChannel.d.ts

@@ -20,6 +20,11 @@ export type ChannelHandle = {
     /** This page's name on the channel — the `from` of what it sends. */
     me: string | undefined;
     members: RealtimeMember[];
+    /**
+     * What a `retain: true` channel keeps, by type: the latest data the server said of each — there as the page joins,
+     * and changed as it is said again. Empty on any other channel.
+     */
+    retained: Record<string, unknown>;
     /** Heard by every other page on the topic — and by this one too with `{ echo: true }`, once the server took it. */
     publish: (type: string, data: unknown, options?: RealtimePublishOptions) => Promise<boolean>;
     setPresence: (state: unknown) => void;
@@ -29,7 +34,8 @@ export type ChannelHandle = {
  * the speed of a cursor reads directly.
  *
  * Messages arrive through `onMessage` rather than as state, so a canvas redrawing sixty cursors a second does not
- * re-render the component sixty times a second. Closed — no connection, no members — where the page has no server to
+ * re-render the component sixty times a second — all but what a `retain: true` channel keeps, which is state
+ * (`retained`): a page that joins hears each kept message as if it had just been said. Closed — no connection, no members — where the page has no server to
  * connect to (the builder, an embed), and on the server.
  */
 declare const useChannel: (asked: string | undefined, { grant, presence, onMessage, onJoin, onLeave }?: UseChannelOptions) => ChannelHandle;

package/dist/realtime/useChannel.mjs

@@ -2,56 +2,64 @@ import { useCallback as e, useEffect as t, useMemo as n, useRef as r, useState a
 import { useCommonStore as a } from "@plitzi/sdk-shared/store";
 import { REVOKED_TYPE as o, isValidTopic as s, matchChannel as c, realtimeClientFor as l, trackPresence as u } from "@plitzi/sdk-shared/realtime";
 //#region src/realtime/useChannel.ts
-var d = (d, { grant: f, presence: p, onMessage: m, onJoin: h, onLeave: g } = {}) => {
-	let [_] = a("schema.settings.channels"), v = d && (_ ? c(d, _) : s(d)) ? d : void 0, [y] = a("realtime.endpoint"), [b] = a("realtime.transport"), x = n(() => y && typeof window < "u" ? l(y, b) : void 0, [y, b]), [S, C] = i(!1), [w, T] = i([]), E = r(void 0), D = r({
-		onMessage: m,
-		onJoin: h,
-		onLeave: g
+var d = (e, t) => {
+	if (Object.hasOwn(e, t.type) && e[t.type].at > t.at) return e;
+	let n = Object.fromEntries(Object.entries(e).filter(([e]) => e !== t.type));
+	return t.data === null ? n : {
+		...n,
+		[t.type]: t
+	};
+}, f = (f, { grant: p, presence: m, onMessage: h, onJoin: g, onLeave: _ } = {}) => {
+	let [v] = a("schema.settings.channels"), y = f && (v ? c(f, v) : s(f)) ? f : void 0, [b] = a("realtime.endpoint"), [x] = a("realtime.transport"), S = n(() => b && typeof window < "u" ? l(b, x) : void 0, [b, x]), [C, w] = i(!1), [T, E] = i([]), [D, O] = i({}), k = r(void 0), A = r({
+		onMessage: h,
+		onJoin: g,
+		onLeave: _
 	});
 	t(() => {
-		D.current = {
-			onMessage: m,
-			onJoin: h,
-			onLeave: g
+		A.current = {
+			onMessage: h,
+			onJoin: g,
+			onLeave: _
 		};
 	}), t(() => {
-		x && v && f && x.grant(v, f);
+		S && y && p && S.grant(y, p);
 	}, [
-		x,
-		v,
-		f
+		S,
+		y,
+		p
 	]), t(() => {
-		if (!x || !v) return;
-		let e = u(x, v, {
-			onChange: T,
+		if (!S || !y) return;
+		let e = u(S, y, {
+			onChange: E,
 			onMessage: (e) => {
-				e.type === o && e.from === "server" && C(!1), D.current.onMessage?.(e);
+				e.type === o && e.from === "server" && w(!1), e.retained === !0 && e.from === "server" && O((t) => d(t, e)), A.current.onMessage?.(e);
 			},
-			onArrive: (e) => D.current.onJoin?.(e),
-			onDepart: (e) => D.current.onLeave?.(e)
+			onArrive: (e) => A.current.onJoin?.(e),
+			onDepart: (e) => A.current.onLeave?.(e)
 		});
-		E.current = e, C(x.status === "open" && !x.refusal(v));
-		let t = x.onStatus((e) => C(e === "open" && !x.refusal(v)));
+		k.current = e, w(S.status === "open" && !S.refusal(y));
+		let t = S.onStatus((e) => w(e === "open" && !S.refusal(y)));
 		return () => {
-			t(), e.stop(), E.current = void 0, T([]), C(!1);
+			t(), e.stop(), k.current = void 0, E([]), O({}), w(!1);
 		};
-	}, [x, v]);
-	let O = p === void 0 ? void 0 : JSON.stringify(p);
+	}, [S, y]);
+	let j = m === void 0 ? void 0 : JSON.stringify(m);
 	t(() => {
-		O !== void 0 && E.current?.set(JSON.parse(O));
+		j !== void 0 && k.current?.set(JSON.parse(j));
 	}, [
-		O,
-		x,
-		v
+		j,
+		S,
+		y
 	]);
-	let k = e((e, t, n) => x && v ? x.publish(v, e, t, n) : Promise.resolve(!1), [x, v]), A = e((e) => E.current?.set(e), []);
+	let M = e((e, t, n) => S && y ? S.publish(y, e, t, n) : Promise.resolve(!1), [S, y]), N = e((e) => k.current?.set(e), []), P = n(() => Object.fromEntries(Object.entries(D).map(([e, t]) => [e, t.data])), [D]);
 	return {
-		connected: S,
-		me: S ? x?.me : void 0,
-		members: w,
-		publish: k,
-		setPresence: A
+		connected: C,
+		me: C ? S?.me : void 0,
+		members: T,
+		retained: P,
+		publish: M,
+		setPresence: N
 	};
 };
 //#endregion
-export { d as default };
+export { f as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-elements",
-  "version": "0.38.14",
+  "version": "0.38.15",
   "license": "AGPL-3.0",
   "files": [
     "dist"
@@ -1423,12 +1423,12 @@
     "@dr.pogodin/react-helmet": "^3.3.2",
     "@plitzi/nexus": "^1.4.0",
     "@plitzi/plitzi-ui": "^1.6.33",
-    "@plitzi/sdk-auth": "0.38.14",
-    "@plitzi/sdk-event-bridge": "0.38.14",
-    "@plitzi/sdk-interactions": "0.38.14",
-    "@plitzi/sdk-navigation": "0.38.14",
-    "@plitzi/sdk-schema": "0.38.14",
-    "@plitzi/sdk-shared": "0.38.14",
+    "@plitzi/sdk-auth": "0.38.15",
+    "@plitzi/sdk-event-bridge": "0.38.15",
+    "@plitzi/sdk-interactions": "0.38.15",
+    "@plitzi/sdk-navigation": "0.38.15",
+    "@plitzi/sdk-schema": "0.38.15",
+    "@plitzi/sdk-shared": "0.38.15",
     "clsx": "^2.1.1",
     "immer": "^11.1.21",
     "react-markdown": "^10.1.0",