@plitzi/sdk-shared 0.38.6 → 0.38.8

package/dist/project/paths.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The layout of a project `@plitzi/cli` writes, relative to its root: the one place the CLI that writes and checks it,
+ * the server that serves it (`@plitzi/sdk-server/project`) and the authoring that checks its space
+ * (`@plitzi/sdk-authoring/node`'s `projectAuthoring`) read it from.
+ *
+ * `tmp/` is what the project writes for itself, never committed, everything in it rebuilt when it is missing — the
+ * server's plugin bundles (`tmp/.sdk-plugins`) and resized pictures (`tmp/images`), both `@plitzi/sdk-server`'s
+ * defaults, beside what the files below name. One folder, so a reader of the project — a person, an agent — knows at a
+ * glance what is the project and what is a by-product of running it.
+ */
+export declare const PROJECT_TMP = "tmp";
+/** The project's own code — its space, plugins, data, functions and server — which the server watches while developing. */
+export declare const SOURCE_DIR = "src";
+/**
+ * The CLI's own part of a project — the script that authors the space, the types its plugins import besides code, the
+ * page's base styles — apart from `src/`, which is the project's: `plitzi upgrade` keeps this folder current, and a
+ * person reads `src/` without wading through it.
+ */
+export declare const CLI_DIR = "plitzi";
+/**
+ * What authors the space and says what it found: `npm run author`, and the server's re-authoring on a save, which runs
+ * it in a process of its own and is handed the documents over IPC (`--ipc`).
+ */
+export declare const AUTHOR_FILE = "plitzi/author.ts";
+/**
+ * The space, in a folder of its own — it grows a page, a layout, a component at a time — whose `index.ts` exports it as
+ * `space`: what the server's entry point, the author script, the visual test and the CLI's checks import.
+ */
+export declare const SPACE_DIR = "src/space";
+export declare const SPACE_ENTRY = "src/space/index.ts";
+/**
+ * The project's own components: every folder is one, registered under its name in camelCase — `src/plugins/StatCard`
+ * renders a space's `custom({ renderType: 'statCard' })` — built from its entry (`PLUGIN_ENTRIES`) and declared by its
+ * `declaration.ts`.
+ */
+export declare const PLUGINS_DIR = "src/plugins";
+/**
+ * What a plugin folder is built from: `index.ts`, or `index.tsx` for one that writes its JSX there — TypeScript both,
+ * and one of them, never both.
+ */
+export declare const PLUGIN_ENTRIES: readonly ["index.ts", "index.tsx"];
+/** What a plugin folder declares itself in — its type, attributes, triggers — as `plitzi plugin add` writes it. */
+export declare const PLUGIN_DECLARATION_FILE = "declaration.ts";
+/** A plugin's server half, a folder of its own beside its component: built from its `index.ts`. */
+export declare const PLUGIN_FUNCTIONS_DIR = "functions";
+/**
+ * Plugins no source of was kept, as they were built (a project made from a space): `vendor/plugins/<type>/`, each
+ * beside the manifest it was published with (`PLUGIN_MANIFEST_FILE`).
+ */
+export declare const VENDOR_PLUGINS_DIR = "vendor/plugins";
+/** What `plitzi plugin pack` writes beside a plugin's bundle: its version, its files, and the elements it provides. */
+export declare const PLUGIN_MANIFEST_FILE = "plugin-manifest.json";
+/** A runtime that came across built only (a project made from a space): run as it was built. */
+export declare const RUNTIME_BUNDLE = "vendor/runtime.bundle";
+/** Served to anyone as it is: pictures, a favicon — every file in it is on the internet once the project is deployed. */
+export declare const PUBLIC_DIR = "public";
+/**
+ * The project's own data, server mode: JSON its server reads (`dataDir`) and never serves — a provider asks for
+ * `/data/<file>` on the server. A project with no server keeps it in `public/data/`, where the browser fetches it.
+ */
+export declare const DATA_DIR = "src/data";
+/** The project's own server code — the tasks and `/fn/` routes `defineFunctions` declares — built at boot. */
+export declare const FUNCTIONS_DIR = "src/functions";
+/**
+ * The space's runtime — its own server code, run as a process of its own on Plitzi and by the project's server in its
+ * process — a folder like the space, whose `index.ts` exports it.
+ */
+export declare const RUNTIME_DIR = "src/runtime";
+export declare const RUNTIME_ENTRY = "src/runtime/index.ts";
+/**
+ * What `npm run build` compiles `src/` into — the server's own code, as JavaScript, for `start:prod` to run with no
+ * TypeScript in the process. The same tree: `src/runtime/index.ts` is `dist/runtime/index.js`.
+ */
+export declare const BUILD_DIR = "dist";
+/**
+ * What the running server keeps for the space — its `kv`: saved layouts, counters, a source's cached answer. Not
+ * committed either, but not a by-product: it is the deployment's state, so it is never rebuilt and `tmp/` is no place
+ * for it. A deployment that keeps it elsewhere says so in `src/config/serverOptions.ts` (`action.kv`).
+ */
+export declare const PROJECT_STATE = "state";
+/** The `kv` a project's server keeps, as one JSON file (`createFileKv`). */
+export declare const KV_FILE = "state/kv.json";
+/** The port the server took and the name its `/health` answers with: what `check`, `shot` and `visual` find it by. */
+export declare const DEV_SERVER_FILE = "tmp/dev-server.json";

package/dist/project/paths.mjs

@@ -0,0 +1,4 @@
+//#region src/project/paths.ts
+var e = "tmp", t = "src", n = "plitzi", r = `${n}/author.ts`, i = "src/space", a = `${i}/index.ts`, o = "src/plugins", s = ["index.ts", "index.tsx"], c = "declaration.ts", l = "functions", u = "vendor/plugins", d = "plugin-manifest.json", f = "vendor/runtime.bundle", p = "public", m = "src/data", h = "src/functions", g = "src/runtime", _ = `${g}/index.ts`, v = "dist", y = "state", b = `${y}/kv.json`, x = "tmp/dev-server.json";
+//#endregion
+export { r as AUTHOR_FILE, v as BUILD_DIR, n as CLI_DIR, m as DATA_DIR, x as DEV_SERVER_FILE, h as FUNCTIONS_DIR, b as KV_FILE, o as PLUGINS_DIR, c as PLUGIN_DECLARATION_FILE, s as PLUGIN_ENTRIES, l as PLUGIN_FUNCTIONS_DIR, d as PLUGIN_MANIFEST_FILE, y as PROJECT_STATE, e as PROJECT_TMP, p as PUBLIC_DIR, f as RUNTIME_BUNDLE, g as RUNTIME_DIR, _ as RUNTIME_ENTRY, t as SOURCE_DIR, i as SPACE_DIR, a as SPACE_ENTRY, u as VENDOR_PLUGINS_DIR };

package/dist/project/root.d.ts

@@ -0,0 +1,24 @@
+/** A process started outside the project's root: its message names what is missing, and where to run it instead. */
+export declare class ProjectRootError extends Error {
+    constructor(root: string, missing: readonly string[]);
+}
+/**
+ * `root`, when it is the root of a project `@plitzi/cli` writes; refused otherwise, naming what it lacks. What
+ * `projectRoot` holds the working directory to — and what a tool working on a project from another folder (the CLI, run
+ * anywhere inside one) holds the root it found to.
+ */
+export declare const checkProjectRoot: (root: string) => string;
+/**
+ * The root of the project this process runs: its working directory. Every script of the project's `package.json` runs
+ * there, and a deployment starts `node dist/main.js` there too — so the root is never worked out from where a file is,
+ * and a process started from anywhere else is refused, saying what is missing (`checkProjectRoot`).
+ */
+export declare const projectRoot: () => string;
+/**
+ * Where a module of the project's source (`entry`, under `src/` — `src/space/index.ts`) is, in the form the process
+ * runs in: what `build` emitted (`dist/space/index.js`) when it was started on that — `node dist/main.js`, which carries
+ * no TypeScript at all — and the source otherwise. Told by the script the process was started with (`script`,
+ * `process.argv[1]`), followed through any link, rather than by `NODE_ENV`: a production server run from its source
+ * still finds the source, and one run compiled never imports a `.ts` file.
+ */
+export declare const projectModule: (root: string, entry: string, script: string | undefined) => string;

package/dist/project/root.mjs

@@ -0,0 +1,26 @@
+import { BUILD_DIR as e } from "./paths.mjs";
+import t from "node:path";
+import { existsSync as n, realpathSync as r } from "node:fs";
+//#region src/project/root.ts
+var i = ["package.json", "src/"], a = class extends Error {
+	constructor(e, t) {
+		super(`${e} is not the root of a Plitzi project: it has no ${t.join(" and no ")}. Run it from the project's root, the folder its package.json is in — where its scripts run it (npm start, npm run author).`), this.name = "ProjectRootError";
+	}
+};
+Object.defineProperty(a, "name", { value: "ProjectRootError" });
+var o = (e) => {
+	let r = i.filter((r) => !n(t.join(e, r)));
+	if (r.length > 0) throw new a(e, r);
+	return e;
+}, s = () => o(process.cwd()), c = (e) => {
+	try {
+		return r(e);
+	} catch {
+		return t.resolve(e);
+	}
+}, l = (n, r, i) => {
+	let a = c(t.join(n, e)), o = i !== void 0 && c(i).startsWith(`${a}${t.sep}`);
+	return t.join(n, o ? t.join(e, t.relative("src", r)).replace(/\.tsx?$/, ".js") : r);
+};
+//#endregion
+export { a as ProjectRootError, o as checkProjectRoot, l as projectModule, s as projectRoot };

package/dist/queries/index.d.ts

@@ -1,10 +1,15 @@
 import { default as queryCache, QueryMeta } from './queryCache';
 export { QueryCache, GC_TIME, queryId, queryPath } from './queryCache';
+export { registerServerQuery } from './serverQueries';
 export { default as useQuery } from './useQuery';
+export { default as useServerQuery } from './useServerQuery';
 export type { QueriesState, QueryEntry, QueryMeta, QueryObserverOptions } from './queryCache';
+export type { ServerQuery } from './serverQueries';
 export type { UseQueryOptions, UseQueryResult } from './useQuery';
+export type { UseServerQueryOptions } from './useServerQuery';
 /**
- * Every query that could have read what `url` just wrote: the ones on the same origin.
+ * Every query that could have read what `url` just wrote: the ones on the same origin — a server provider's too, when
+ * it reads a URL.
  *
  * The origin, not the path: `POST /api/cart/items` changes what `GET /api/cart` answers, and no path rule tells
  * those apart from two unrelated resources. Another origin is another backend, and nothing it writes shows up here.
@@ -25,7 +30,12 @@ export type QuerySelector = {
  * template nobody can write down.
  */
 export declare const matchesQuery: ({ url, elements }: QuerySelector) => (meta: QueryMeta) => boolean;
-/** The `invalidateQueries` step, and anything else that knows which data changed. */
+/**
+ * The `invalidateQueries` step, and anything else that knows which data changed.
+ *
+ * Both halves of the page's data: the cached browser requests, and the providers the page server answers, which
+ * never pass through the cache. Either is marked and asks when shown if nobody is looking at it now.
+ */
 export declare const invalidateQueries: (selector?: QuerySelector) => Promise<void>;
 /**
  * One key for one request, whoever makes it — an api container and a webhook step asking the same thing share the

package/dist/queries/index.mjs

@@ -1,37 +1,47 @@
 import e, { GC_TIME as t, QueryCache as n, queryId as r, queryPath as i } from "./queryCache.mjs";
-import a from "./useQuery.mjs";
+import { refreshServerQueries as a, registerServerQuery as o } from "./serverQueries.mjs";
+import s from "./useQuery.mjs";
+import c from "./useServerQuery.mjs";
 //#region src/queries/index.ts
-var o = () => typeof location > "u" ? void 0 : location.href, s = (e) => {
+var l = () => typeof location > "u" ? void 0 : location.href, u = (e) => {
 	try {
-		return new URL(e, o()).origin;
+		return new URL(e, l()).origin;
 	} catch {
 		return;
 	}
-}, c = (t) => {
-	let n = s(t);
-	return n ? e.invalidate((e) => s(e.url) === n) : Promise.resolve();
-}, l = (e) => Array.isArray(e) ? e.filter((e) => typeof e == "string" && e.trim() !== "").map((e) => e.trim()) : typeof e == "string" ? e.split(",").map((e) => e.trim()).filter(Boolean) : [], u = (e) => {
+}, d = (e, t) => ({ id: n, url: r }) => (!t || r !== void 0) && e({
+	url: r ?? "",
+	tags: [n]
+}), f = (t) => {
+	let n = u(t);
+	if (!n) return Promise.resolve();
+	let r = (e) => u(e.url) === n;
+	return Promise.all([e.invalidate(r), a(d(r, !0))]).then(() => void 0);
+}, p = (e) => Array.isArray(e) ? e.filter((e) => typeof e == "string" && e.trim() !== "").map((e) => e.trim()) : typeof e == "string" ? e.split(",").map((e) => e.trim()).filter(Boolean) : [], m = (e) => {
 	try {
-		return new URL(e, o()).href;
+		return new URL(e, l()).href;
 	} catch {
 		return e;
 	}
-}, d = ({ url: e, elements: t }) => {
-	let n = e ? u(e) : void 0;
-	return (e) => (n === void 0 || u(e.url).startsWith(n)) && (!t?.length || t.some((t) => e.tags?.includes(t) ?? !1));
-}, f = (t = {}) => t.url || t.elements?.length ? e.invalidate(d(t)) : e.invalidate(), p = ({ method: e, url: t, credentials: n, headers: r }) => JSON.stringify([
+}, h = ({ url: e, elements: t }) => {
+	let n = e ? m(e) : void 0;
+	return (e) => (n === void 0 || m(e.url).startsWith(n)) && (!t?.length || t.some((t) => e.tags?.includes(t) ?? !1));
+}, g = (t = {}) => {
+	let n = t.url || t.elements?.length ? h(t) : void 0;
+	return Promise.all([e.invalidate(n), a(n && d(n, !!t.url))]).then(() => void 0);
+}, _ = ({ method: e, url: t, credentials: n, headers: r }) => JSON.stringify([
 	e.toLowerCase(),
 	t,
 	n,
 	Object.entries(r).filter(([e]) => e.toLowerCase() !== "content-type").sort(([e], [t]) => e < t ? -1 : +(e > t))
-]), m = ({ mode: e, fallback: t, elements: n, url: r }) => {
+]), v = ({ mode: e, fallback: t, elements: n, url: r }) => {
 	let i = e === "origin" || e === "all" || e === "elements" || e === "none" ? e : t;
 	if (i === "none") return Promise.resolve();
 	if (i === "elements") {
-		let e = l(n);
-		return e.length > 0 ? f({ elements: e }) : Promise.resolve();
+		let e = p(n);
+		return e.length > 0 ? g({ elements: e }) : Promise.resolve();
 	}
-	return i === "origin" && r ? c(r) : f();
+	return i === "origin" && r ? f(r) : g();
 };
 //#endregion
-export { t as GC_TIME, n as QueryCache, m as invalidateAfterWrite, f as invalidateQueries, c as invalidateQueriesForWrite, d as matchesQuery, l as parseIds, e as queryCache, r as queryId, i as queryPath, p as requestKey, a as useQuery };
+export { t as GC_TIME, n as QueryCache, v as invalidateAfterWrite, g as invalidateQueries, f as invalidateQueriesForWrite, h as matchesQuery, p as parseIds, e as queryCache, r as queryId, i as queryPath, o as registerServerQuery, _ as requestKey, s as useQuery, c as useServerQuery };

package/dist/queries/serverQueries.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A query the page server answers for a provider (`runtime: 'server'`), as the invalidations see it.
+ *
+ * Its answer arrives in the RSC payload, never through the {@link QueryCache}, so an invalidation that only reached
+ * the cache left every server-driven list showing what it held before the write.
+ */
+export type ServerQuery = {
+    /** The provider's element id: what an invalidation naming containers names. */
+    id: string;
+    /** The URL the server reads for it — only a provider that has nothing but a `query`; a connector or action has none. */
+    url?: string;
+    /** Asks the server again for this provider's slice, around every cache. */
+    refresh: () => Promise<void>;
+};
+/** Makes `query` reachable by the invalidations until the returned function is called. */
+export declare const registerServerQuery: (query: ServerQuery) => (() => void);
+/**
+ * Asks again for every server query `matches` accepts — all of them without one.
+ *
+ * Settled, not all-or-nothing: one provider that could not ask again is its own to report, and the rest still refresh.
+ */
+export declare const refreshServerQueries: (matches?: (query: ServerQuery) => boolean) => Promise<void>;

package/dist/queries/serverQueries.mjs

@@ -0,0 +1,9 @@
+//#region src/queries/serverQueries.ts
+var e = /* @__PURE__ */ new Set(), t = (t) => {
+	let n = { ...t };
+	return e.add(n), () => {
+		e.delete(n);
+	};
+}, n = (t) => Promise.allSettled([...e].filter((e) => !t || t(e)).map((e) => e.refresh())).then(() => void 0);
+//#endregion
+export { n as refreshServerQueries, t as registerServerQuery };

package/dist/queries/useServerQuery.d.ts

@@ -0,0 +1,19 @@
+export type UseServerQueryOptions = {
+    id: string;
+    /** The URL the server reads for a provider that has nothing but a `query`. */
+    url?: string;
+    /** Whether the provider has a live answer to refresh at all — never in the builder, which has no page server. */
+    enabled: boolean;
+    /** Whether it is on screen: an invalidation of a hidden one waits until it is shown, as a cached query does. */
+    active: boolean;
+    refresh: () => Promise<void>;
+};
+/**
+ * Keeps a server-driven provider reachable by the invalidations — `invalidateQueries`, and the refresh a write step
+ * asks for — for as long as it is mounted and `enabled`.
+ *
+ * The same saving the cache makes for a hidden query: a provider in a tab nobody is looking at is only marked, and
+ * asks when it is shown, so a write does not turn into a request for every section the visitor cannot see.
+ */
+declare const useServerQuery: ({ id, url, enabled, active, refresh }: UseServerQueryOptions) => void;
+export default useServerQuery;

package/dist/queries/useServerQuery.mjs

@@ -0,0 +1,21 @@
+import { registerServerQuery as e } from "./serverQueries.mjs";
+import { useEffect as t, useRef as n } from "react";
+//#region src/queries/useServerQuery.ts
+var r = ({ id: r, url: i, enabled: a, active: o, refresh: s }) => {
+	let c = n(!1);
+	t(() => {
+		if (a) return o && c.current && (c.current = !1, s()), e({
+			id: r,
+			url: i,
+			refresh: () => o ? s() : (c.current = !0, Promise.resolve())
+		});
+	}, [
+		a,
+		o,
+		r,
+		i,
+		s
+	]);
+};
+//#endregion
+export { r as default };

package/dist/server/rsc/refreshRsc.d.ts

@@ -13,6 +13,25 @@ export declare const currentRscLocation: () => string;
 export declare const cancelRsc: (store: StoreApi<CommonState>, ids?: readonly string[]) => void;
 /** Every refresh of this root aborted and forgotten — the SDK root that owned them is going away. */
 export declare const releaseRscRequests: (instance: string) => void;
+export type RscRefreshOptions = {
+    /**
+     * Resolve for somewhere the visitor is not yet.
+     *
+     * A route change that renders first and fetches after paints a page whose sections have no answer, so the
+     * navigation asks for the destination BEFORE it commits. Absent means where the visitor already is, which is
+     * every other caller: the initial load, a pager, an element refreshing itself.
+     */
+    location?: string;
+    /**
+     * Ask the server itself, around the browser's cache and the page server's.
+     *
+     * Outside `main` an answer is kept for a while on both — the same question from many visitors is resolved once —
+     * which is right for a page window and wrong for a refresh that exists because something changed: a write, an
+     * explicit reload. Asked through either cache, that refresh is answered with the slice from before the write. A
+     * header rather than a query parameter, because every parameter of the request is input to what it resolves.
+     */
+    fresh?: boolean;
+};
 /**
  * Re-fetches RSC data into the store.
  *
@@ -20,7 +39,8 @@ export declare const releaseRscRequests: (instance: string) => void;
  * has what it needs through the store it can reach, and an element buried under any number of scopes writes to the
  * root by delegation (nothing but the root owns `rsc`).
  *
- * Pass `ids` to refresh only those elements — the response is merged over the existing payload. Omit them for a full
+ * Pass `requestedIds` to refresh only those elements — the response is merged over the existing payload; of them,
+ * only the ones the server resolves at that location are asked for, and none is no request. Omit them for a full
  * refresh, which replaces it. `params` ride along on the query string; that is how a provider asks for a different
  * page window.
  *
@@ -29,13 +49,5 @@ export declare const releaseRscRequests: (instance: string) => void;
  * again, an element asked for again — is aborted, here and on the server. Before this a click on a link asked twice
  * (its prefetch, then the route change), and a slow answer could land over a newer one.
  */
-export declare const refreshRsc: (store: StoreApi<CommonState>, ids?: string[], params?: Record<string, string>, 
-/**
- * Resolve for somewhere the visitor is not yet.
- *
- * A route change that renders first and fetches after paints a page whose sections have no answer, so the
- * navigation asks for the destination BEFORE it commits. Absent means where the visitor already is, which is
- * every other caller: the initial load, a pager, an element refreshing itself.
- */
-location?: string) => Promise<void>;
+export declare const refreshRsc: (store: StoreApi<CommonState>, requestedIds?: string[], params?: Record<string, string>, { location, fresh }?: RscRefreshOptions) => Promise<void>;
 export default refreshRsc;

package/dist/server/rsc/refreshRsc.mjs

@@ -1,96 +1,108 @@
 import { authFailureFromResponse as e, reportAuthFailure as t } from "../../auth/failureChannel.mjs";
 import { recordRenderActionRuns as n } from "../../store/actionRuns/actionRunsRecorder.mjs";
-import { hasServerElements as r } from "../../schema/serverElements.mjs";
-import { getPaths as i, matchRoutePath as a } from "../../navigation/routes.mjs";
+import { collectServerElements as r, hasServerElements as i } from "../../schema/serverElements.mjs";
+import { getPaths as a, matchRoutePath as o } from "../../navigation/routes.mjs";
 //#region src/server/rsc/refreshRsc.ts
-var o = (e, t, n) => {
+var s = (e, t, n) => {
 	if (!e) return;
 	let r = e.pages.reduce((t, n) => (n in e.flat && (t[n] = e.flat[n]), t), {});
-	return a(i(r, e.pageFolders, n), t.split("?")[0], n).pageId;
-}, s = (e) => `rsc.data.${e}`, c = () => typeof window > "u" ? "" : `${window.location.pathname}${window.location.search}`, l = "*", u = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new WeakMap(), f = () => ({
+	return o(a(r, e.pageFolders, n), t.split("?")[0], n).pageId;
+}, c = (e, t, n, i) => {
+	let a = new Set(r(e, t, [...n], i).map(({ id: e }) => e));
+	return n.filter((e) => a.has(e));
+}, l = (e) => `rsc.data.${e}`, u = () => typeof window > "u" ? "" : `${window.location.pathname}${window.location.search}`, d = "*", f = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new WeakMap(), m = () => ({
 	seq: 0,
 	inFlight: /* @__PURE__ */ new Set(),
 	asked: /* @__PURE__ */ new Map()
-}), p = (e) => {
+}), h = (e) => {
 	let t = e.get("rsc.instance");
 	if (typeof t == "string" && t) {
-		let e = u.get(t);
+		let e = f.get(t);
 		if (e) return e;
-		let n = f();
-		return u.set(t, n), n;
+		let n = m();
+		return f.set(t, n), n;
 	}
-	let n = d.get(e);
+	let n = p.get(e);
 	if (n) return n;
-	let r = f();
-	return d.set(e, r), r;
-}, m = (e, t) => {
+	let r = m();
+	return p.set(e, r), r;
+}, g = (e, t) => {
 	let n = {};
 	t.inFlight.forEach((e) => {
-		e.here && (e.ids ?? [l]).forEach((e) => {
+		e.here && (e.ids ?? [d]).forEach((e) => {
 			n[e] = !0;
 		});
 	}), e.set("rsc.refreshing", n);
-}, h = (e, t) => !e || !!t && t.every((t) => e.includes(t)), g = (e, t) => {
-	p(e).inFlight.forEach((e) => {
+}, _ = (e, t) => !e || !!t && t.every((t) => e.includes(t)), v = (e, t) => {
+	h(e).inFlight.forEach((e) => {
 		(!t || e.ids?.some((e) => t.includes(e))) && e.controller.abort();
 	});
-}, _ = (e) => {
-	u.get(e)?.inFlight.forEach((e) => e.controller.abort()), u.delete(e);
-}, v = (e, t, n, r, i) => {
+}, y = (e) => {
+	f.get(e)?.inFlight.forEach((e) => e.controller.abort()), f.delete(e);
+}, b = (e, t, n, r, i) => {
 	let { ids: a, seq: o } = n;
 	e.batch(() => {
 		if (a?.length) Object.entries(r).forEach(([n, r]) => {
-			(t.asked.get(n) ?? 0) <= o && (t.asked.get(l) ?? 0) <= o && e.set(s(n), r);
+			(t.asked.get(n) ?? 0) <= o && (t.asked.get(d) ?? 0) <= o && e.set(l(n), r);
 		});
 		else {
-			let n = e.get("rsc.data") ?? {}, i = (e) => e !== l && (t.asked.get(e) ?? 0) > o, a = Object.fromEntries([...Object.entries(r).filter(([e]) => !i(e)), ...Object.entries(n).filter(([e]) => i(e))]);
+			let n = e.get("rsc.data") ?? {}, i = (e) => e !== d && (t.asked.get(e) ?? 0) > o, a = Object.fromEntries([...Object.entries(r).filter(([e]) => !i(e)), ...Object.entries(n).filter(([e]) => i(e))]);
 			e.set("rsc.data", a);
 		}
 		e.set("rsc.loaded", !0), e.set("rsc.stale", !1), e.set("rsc.location", i);
 	});
-}, y = async (i, a, s, u) => {
-	let { enabled: d, endpoint: f } = i.get("rsc") ?? {};
-	if (!d || !f || typeof window > "u") return;
-	let g = u ?? c(), _ = i.get("schema"), y = i.get("runtime.sources.auth"), b = u ? o(_, u, !!y?.details) : i.get("navigation.currentPageId"), x = u ? void 0 : i.get("runtime.sources.flags");
-	if (!_ || !r(_, b, x)) return;
-	let S = new URLSearchParams({ location: g });
-	a?.length && S.set("ids", a.join(",")), Object.entries(s ?? {}).forEach(([e, t]) => S.set(e, t));
-	let C = `${f}?${S.toString()}`, w = p(i), T = [...w.inFlight].find((e) => e.url === C);
-	if (T) return T.promise;
-	w.inFlight.forEach((e) => {
-		h(a, e.ids) && e.controller.abort();
+}, x = async (r, a, o, { location: l, fresh: f = !1 } = {}) => {
+	let { enabled: p, endpoint: m } = r.get("rsc") ?? {};
+	if (!p || !m || typeof window > "u") return;
+	let v = l ?? u(), y = r.get("schema"), x = r.get("runtime.sources.auth"), S = l ? s(y, l, !!x?.details) : r.get("navigation.currentPageId"), C = l ? void 0 : r.get("runtime.sources.flags");
+	if (!y) return;
+	let w = a?.length ? c(y, S, a, C) : void 0;
+	if (w ? !w.length : !i(y, S, C)) return;
+	let T = new URLSearchParams({ location: v });
+	w?.length && T.set("ids", w.join(",")), Object.entries(o ?? {}).forEach(([e, t]) => T.set(e, t));
+	let E = `${m}?${T.toString()}`, D = h(r), O = [...D.inFlight].find((e) => e.url === E && (e.fresh || !f));
+	if (O) return O.promise;
+	D.inFlight.forEach((e) => {
+		_(w, e.ids) && e.controller.abort();
 	});
-	let E = ++w.seq;
-	a?.length ? a.forEach((e) => w.asked.set(e, E)) : (w.asked.clear(), w.asked.set(l, E));
-	let D = new AbortController(), O = {
-		url: C,
-		...a?.length ? { ids: a } : {},
-		here: g === c(),
-		seq: E,
-		controller: D,
+	let k = ++D.seq;
+	w?.length ? w.forEach((e) => D.asked.set(e, k)) : (D.asked.clear(), D.asked.set(d, k));
+	let A = new AbortController(), j = {
+		url: E,
+		...w?.length ? { ids: w } : {},
+		here: v === u(),
+		fresh: f,
+		seq: k,
+		controller: A,
 		promise: Promise.resolve()
-	}, k = async (r) => {
-		let a = await fetch(C, {
-			headers: { Accept: "application/json" },
-			signal: D.signal
+	}, M = async (i) => {
+		let a = await fetch(E, {
+			...f ? {
+				cache: "no-cache",
+				headers: {
+					Accept: "application/json",
+					"Cache-Control": "no-cache"
+				}
+			} : { headers: { Accept: "application/json" } },
+			signal: A.signal
 		});
 		if (!a.ok) {
 			let n = e(a.status, await a.json().catch(() => void 0));
 			if (n && await t({
 				reason: n,
-				url: f
-			}) && !r) return k(!0);
-			i.set("rsc.stale", !0);
+				url: m
+			}) && !i) return M(!0);
+			r.set("rsc.stale", !0);
 			return;
 		}
 		let { serverData: o, actionRuns: s } = await a.json();
-		s?.length && n(s), v(i, w, O, o ?? {}, g);
+		s?.length && n(s), b(r, D, j, o ?? {}, v);
 	};
-	return O.promise = k(!1).catch(() => {
-		D.signal.aborted || i.set("rsc.stale", !0);
+	return j.promise = M(!1).catch(() => {
+		A.signal.aborted || r.set("rsc.stale", !0);
 	}).finally(() => {
-		w.inFlight.delete(O), m(i, w);
-	}), w.inFlight.add(O), m(i, w), O.promise;
+		D.inFlight.delete(j), g(r, D);
+	}), D.inFlight.add(j), g(r, D), j.promise;
 };
 //#endregion
-export { g as cancelRsc, c as currentRscLocation, y as default, y as refreshRsc, _ as releaseRscRequests, s as rscDataPath };
+export { v as cancelRsc, u as currentRscLocation, x as default, x as refreshRsc, y as releaseRscRequests, l as rscDataPath };

package/dist/server/rsc/useRscRefresh.d.ts

@@ -1,2 +1,3 @@
-declare const useRscRefresh: () => (ids?: string[], params?: Record<string, string>) => Promise<void>;
+import { RscRefreshOptions } from './refreshRsc';
+declare const useRscRefresh: () => (ids?: string[], params?: Record<string, string>, { fresh }?: Pick<RscRefreshOptions, "fresh">) => Promise<void>;
 export default useRscRefresh;

package/dist/server/rsc/useRscRefresh.mjs

@@ -4,7 +4,7 @@ import { useStoreById as n } from "@plitzi/nexus/react";
 //#region src/server/rsc/useRscRefresh.ts
 var r = () => {
 	let r = n();
-	return t((t, n) => e(r, t, n), [r]);
+	return t((t, n, { fresh: i } = {}) => e(r, t, n, { fresh: i }), [r]);
 };
 //#endregion
 export { r as default };

package/dist/source/export.d.ts

@@ -29,7 +29,7 @@ export type SpaceExport = {
     /** The version taken out: the draft (`main`, revision 0), or a snapshot an environment holds. */
     version: Pick<SpaceVersionContents, 'environment' | 'revision' | 'snapshot'>;
     /**
-     * Which state of the draft's documents this is — its schema, style, actions and connectors — what `plitzi push`
+     * Which state of the draft's documents this is — its schema, style, actions and connectors — what `plitzi space push`
      * checks the space's draft has not moved on from. `null` for a snapshot, which no push writes.
      */
     draft: string | null;
@@ -62,7 +62,7 @@ export type SpaceExport = {
     };
     /**
      * The space's own data, by path in `src/data/` (JSON its providers read on the server, never served), and the version
-     * of it this is — what `plitzi push` checks the space's copy has not moved on from.
+     * of it this is — what `plitzi space push` checks the space's copy has not moved on from.
      */
     data: {
         version: string;

package/dist/source/import.d.ts

@@ -1,6 +1,6 @@
 import { Schema, Style } from '../types';
 /**
- * A project's space put back on Plitzi as the space's draft (docs/en/projects-from-spaces.md): what `plitzi push` sends
+ * A project's space put back on Plitzi as the space's draft (docs/en/projects-from-spaces.md): what `plitzi space push` sends
  * to `PUT /spaces/:spaceId/import`, and what it is answered. The way back of `SpaceExport` — one shape for both ends.
  */
 export declare const SPACE_IMPORT_FORMAT = 1;