@plitzi/sdk-dev-tools 0.36.1 → 0.36.2

package/dist/components/DevToolsPanel/tabs/StoreViewer/StoreViewer.mjs

@@ -1,64 +1,62 @@
-import e from "./components/FreshnessPanel/index.mjs";
-import t from "./helpers/mapFunctionValues.mjs";
-import n from "./helpers/renderFunctionValue.mjs";
-import { useSelectedStore as r } from "../../../../scope/useScope.mjs";
-import i from "../../../../scope/useStoreState.mjs";
-import a from "@plitzi/plitzi-ui/hooks/useStorage";
-import o from "clsx";
-import { use as s, useCallback as c, useMemo as l } from "react";
-import u from "@plitzi/sdk-shared/theme/useTheme";
-import d from "@plitzi/sdk-shared/devTools/DevToolsContext";
-import { jsx as f, jsxs as p } from "react/jsx-runtime";
-import m from "@uiw/react-json-view";
-import * as h from "@uiw/react-json-view/vscode";
-import { emptyObject as g } from "@plitzi/sdk-shared/helpers/utils";
+import e from "../../../../freshness/useFreshnessByStore.mjs";
+import t from "../../../../freshness/useSecondsClock.mjs";
+import { useSelectedStore as n, useSelectedStoreEntry as r } from "../../../../scope/useScope.mjs";
+import i from "./helpers/mapFunctionValues.mjs";
+import a from "./helpers/renderFreshnessKey.mjs";
+import o from "./helpers/renderFunctionValue.mjs";
+import s from "../../../../scope/useStoreState.mjs";
+import c from "@plitzi/plitzi-ui/hooks/useStorage";
+import l from "clsx";
+import { use as u, useCallback as d, useMemo as f } from "react";
+import p from "@plitzi/sdk-shared/theme/useTheme";
+import m from "@plitzi/sdk-shared/devTools/DevToolsContext";
+import { jsx as h, jsxs as g } from "react/jsx-runtime";
+import _ from "@uiw/react-json-view";
+import * as v from "@uiw/react-json-view/vscode";
+import { emptyObject as y } from "@plitzi/sdk-shared/helpers/utils";
 //#region src/components/DevToolsPanel/tabs/StoreViewer/StoreViewer.tsx
-var _ = {
-	...h.vscodeTheme,
+var b = {
+	...v.vscodeTheme,
 	width: "100%",
 	height: "100%",
 	overflow: "auto",
 	padding: "8px",
 	fontSize: "14px"
-}, v = (e) => o("cursor-pointer rounded px-2 py-0.5 font-medium transition-colors", e ? "bg-violet-500/15 text-violet-600 dark:text-violet-300" : "text-zinc-500 hover:bg-zinc-200/70 hover:text-zinc-800 dark:text-zinc-400 dark:hover:bg-zinc-700/50 dark:hover:text-zinc-100"), y = ({ elementSelected: o }) => {
-	let { resolvedTheme: h } = u(), { getData: y } = s(d), b = r(), [x, S] = a("plitzi-sdk.dev-tools.store.view", "own"), C = i(o ? void 0 : b, x === "merged"), w = c(() => S("own"), [S]), T = c(() => S("merged"), [S]), E = o ? y?.(`getElementDataSource-${o}`) : C, D = l(() => t(E), [E]);
-	return /* @__PURE__ */ p("div", {
+}, x = (e) => l("cursor-pointer rounded px-2 py-0.5 font-medium transition-colors", e ? "bg-violet-500/15 text-violet-600 dark:text-violet-300" : "text-zinc-500 hover:bg-zinc-200/70 hover:text-zinc-800 dark:text-zinc-400 dark:hover:bg-zinc-700/50 dark:hover:text-zinc-100"), S = {}, C = [], w = ({ elementSelected: l }) => {
+	let { resolvedTheme: v } = p(), { getData: w } = u(m), T = r(), E = n(), [D, O] = c("plitzi-sdk.dev-tools.store.view", "own"), k = s(l ? void 0 : E, D === "merged"), A = d(() => O("own"), [O]), j = d(() => O("merged"), [O]), M = l ? w?.(`getElementDataSource-${l}`) : k, N = f(() => i(M), [M]), P = f(() => T ? [T] : C, [T]), F = e(P)[0]?.records ?? S, I = f(() => Object.values(F).reduce((e, t) => Math.max(e, t.updatedAt), 0), [F]), L = t(Object.keys(F).length > 0, I), R = f(() => a(F, L), [F, L]);
+	return /* @__PURE__ */ g("div", {
 		className: "flex h-full w-full flex-col",
-		children: [
-			!o && /* @__PURE__ */ p("div", {
-				className: "flex shrink-0 items-center gap-1 border-b border-zinc-200 px-2 py-1 text-[11px] dark:border-zinc-800",
-				children: [
-					/* @__PURE__ */ f("span", {
-						className: "mr-1 text-zinc-400 dark:text-zinc-500",
-						children: "View"
-					}),
-					/* @__PURE__ */ f("button", {
-						className: v(x === "own"),
-						onClick: w,
-						title: "Only this scope's own layer",
-						children: "Own"
-					}),
-					/* @__PURE__ */ f("button", {
-						className: v(x === "merged"),
-						onClick: T,
-						title: "Own layer merged over the parent scope chain",
-						children: "Merged"
-					})
-				]
-			}),
-			!o && /* @__PURE__ */ f(e, { store: b }),
-			/* @__PURE__ */ f(m, {
-				value: D ?? g,
-				style: h === "dark" ? _ : void 0,
-				enableClipboard: !1,
-				indentWidth: 15,
-				collapsed: 2,
-				displayObjectSize: !1,
-				displayDataTypes: !1,
-				children: /* @__PURE__ */ f(m.String, { render: n })
-			})
-		]
+		children: [!l && /* @__PURE__ */ g("div", {
+			className: "flex shrink-0 items-center gap-1 border-b border-zinc-200 px-2 py-1 text-[11px] dark:border-zinc-800",
+			children: [
+				/* @__PURE__ */ h("span", {
+					className: "mr-1 text-zinc-400 dark:text-zinc-500",
+					children: "View"
+				}),
+				/* @__PURE__ */ h("button", {
+					className: x(D === "own"),
+					onClick: A,
+					title: "Only this scope's own layer",
+					children: "Own"
+				}),
+				/* @__PURE__ */ h("button", {
+					className: x(D === "merged"),
+					onClick: j,
+					title: "Own layer merged over the parent scope chain",
+					children: "Merged"
+				})
+			]
+		}), /* @__PURE__ */ g(_, {
+			value: N ?? y,
+			style: v === "dark" ? b : void 0,
+			enableClipboard: !1,
+			indentWidth: 15,
+			collapsed: 2,
+			displayObjectSize: !1,
+			displayDataTypes: !1,
+			children: [/* @__PURE__ */ h(_.String, { render: o }), /* @__PURE__ */ h(_.KeyName, { render: R })]
+		})]
 	});
 };
 //#endregion
-export { y as default };
+export { w as default };

package/dist/components/DevToolsPanel/tabs/StoreViewer/components/FreshnessMark/FreshnessMark.d.ts

@@ -0,0 +1,16 @@
+import { PathFreshness } from '@plitzi/nexus';
+export type FreshnessMarkProps = {
+    record: PathFreshness;
+    /** A clock the caller moves, so every mark on the tree counts down in step. */
+    now: number;
+};
+/**
+ * What a path in the state tree is worth in time: how long before it stops being current, or that it already has.
+ *
+ * On the path itself, because the question a reader arrives at the tree with is about the state in front of them —
+ * which of these is cached, and for how much longer. A path with no mark was written with no `ttl` at all, which is
+ * every path unless somebody asked for one. The rest of what there is to say about it is the Cache tab's job, so
+ * nothing here hides behind a tooltip.
+ */
+declare const FreshnessMark: ({ record: { expiresAt }, now }: FreshnessMarkProps) => import("react").JSX.Element;
+export default FreshnessMark;

package/dist/components/DevToolsPanel/tabs/StoreViewer/components/FreshnessMark/FreshnessMark.mjs

@@ -0,0 +1,13 @@
+import e from "../../../../../../freshness/formatDuration.mjs";
+import t from "clsx";
+import { jsx as n } from "react/jsx-runtime";
+//#region src/components/DevToolsPanel/tabs/StoreViewer/components/FreshnessMark/FreshnessMark.tsx
+var r = ({ record: { expiresAt: r }, now: i }) => {
+	let a = i >= r, o = Number.isFinite(r) ? `${e(r - i)} left` : "no expiry";
+	return /* @__PURE__ */ n("span", {
+		className: t("ml-1 rounded px-1 align-middle text-[10px] font-medium", a ? "bg-amber-500/15 text-amber-700 dark:text-amber-300" : "bg-emerald-500/15 text-emerald-700 dark:text-emerald-300"),
+		children: a ? "stale" : o
+	});
+};
+//#endregion
+export { r as default };

package/dist/components/DevToolsPanel/tabs/StoreViewer/components/FreshnessMark/index.d.ts

@@ -0,0 +1,3 @@
+import { default as FreshnessMark } from './FreshnessMark';
+export * from './FreshnessMark';
+export default FreshnessMark;

package/dist/components/DevToolsPanel/tabs/StoreViewer/components/{FreshnessPanel → FreshnessMark}/index.mjs

@@ -1,5 +1,5 @@
-import e from "./FreshnessPanel.mjs";
-//#region src/components/DevToolsPanel/tabs/StoreViewer/components/FreshnessPanel/index.ts
+import e from "./FreshnessMark.mjs";
+//#region src/components/DevToolsPanel/tabs/StoreViewer/components/FreshnessMark/index.ts
 var t = e;
 //#endregion
 export { t as default };

package/dist/components/DevToolsPanel/tabs/StoreViewer/helpers/renderFreshnessKey.d.ts

@@ -0,0 +1,14 @@
+import { PathFreshness } from '@plitzi/nexus';
+import { default as JsonView } from '@uiw/react-json-view';
+import { ComponentProps } from 'react';
+/** Taken from the component rather than from a type the package does not export at its root. */
+export type FreshnessKeyRenderer = NonNullable<ComponentProps<typeof JsonView.KeyName>['render']>;
+/**
+ * The tree's key names, with a countdown on the paths that have one.
+ *
+ * Only the path a record was written AT is marked, never the ones it covers: a record answers for its whole subtree,
+ * so marking those too would say that every field under a cached answer had a TTL of its own. Returning nothing
+ * leaves the key to the viewer's own renderer, which is every path nobody gave a `ttl`.
+ */
+declare const renderFreshnessKey: (records: Readonly<Partial<Record<string, PathFreshness>>>, now: number) => FreshnessKeyRenderer;
+export default renderFreshnessKey;

package/dist/components/DevToolsPanel/tabs/StoreViewer/helpers/renderFreshnessKey.mjs

@@ -0,0 +1,18 @@
+import e from "../components/FreshnessMark/index.mjs";
+import { Fragment as t, jsx as n, jsxs as r } from "react/jsx-runtime";
+//#region src/components/DevToolsPanel/tabs/StoreViewer/helpers/renderFreshnessKey.tsx
+var i = (i, a) => (o, { keys: s }) => {
+	let c = i[(s ?? []).join(".")];
+	if (!c) return null;
+	let { className: l, style: u, children: d } = o;
+	return /* @__PURE__ */ r(t, { children: [/* @__PURE__ */ n("span", {
+		className: l,
+		style: u,
+		children: d
+	}), /* @__PURE__ */ n(e, {
+		record: c,
+		now: a
+	})] });
+};
+//#endregion
+export { i as default };

package/dist/components/DevToolsPanel/tabs/TracingViewer/helpers.d.ts

@@ -97,6 +97,11 @@ export type TreeIndex = {
     base: Map<string, number>;
     children: Map<string, string[]>;
     elementOf: Map<string, string>;
+    /** When each instance was on the page, for the ones whose presence is not the whole timeline. */
+    lifetime: Map<string, {
+        mountedAt: number;
+        unmountedAt: number;
+    }>;
 };
 export declare const buildTreeIndex: (tree: TracingTree) => TreeIndex;
 export declare const buildFlameModel: (commit: CommitEntry, tree: TracingTree, flat: Record<string, Element> | undefined, index?: TreeIndex) => FlameModel;

package/dist/components/DevToolsPanel/tabs/TracingViewer/helpers.mjs

@@ -66,21 +66,31 @@ var t = (e) => {
 }, g = (e, t) => t?.[e]?.definition.type ?? "unknown", _ = (t, n) => {
 	let r = e(n?.[t], "definition.initialState.visibility", !0);
 	return r !== !1 && r !== "false";
-}, v = (e, t) => t === "self" ? e.selfDuration : e.actualDuration, y = .01, b = 1e-6, x = (e) => {
-	let t = /* @__PURE__ */ new Map(), n = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
-	for (let i of Object.keys(e)) t.set(i, e[i].parentId), n.set(i, e[i].baseDuration), r.set(i, e[i].elementId);
-	let i = /* @__PURE__ */ new Map();
+}, v = (e, t) => t === "self" ? e.selfDuration : e.actualDuration, y = .01, b = 1e-6, x = (e, t, n) => {
+	let r = e.lifetime.get(t);
+	return !r || r.mountedAt <= n && n < r.unmountedAt;
+}, S = (e) => {
+	let t = /* @__PURE__ */ new Map(), n = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map(), i = /* @__PURE__ */ new Map();
+	for (let a of Object.keys(e)) {
+		let { parentId: o, baseDuration: s, elementId: c, mountedAt: l, unmountedAt: u } = e[a];
+		t.set(a, o), n.set(a, s), r.set(a, c), (l !== void 0 || u !== void 0) && i.set(a, {
+			mountedAt: l ?? 0,
+			unmountedAt: u ?? Infinity
+		});
+	}
+	let a = /* @__PURE__ */ new Map();
 	for (let [e, n] of t) if (n !== void 0 && t.has(n)) {
-		let t = i.get(n);
-		t ? t.push(e) : i.set(n, [e]);
+		let t = a.get(n);
+		t ? t.push(e) : a.set(n, [e]);
 	}
 	return {
 		parent: t,
 		base: n,
-		children: i,
-		elementOf: r
+		children: a,
+		elementOf: r,
+		lifetime: i
 	};
-}, S = (e, t) => {
+}, C = (e, t) => {
 	let { parent: n } = t, r = new Map(e.elements.map((e) => [e.id, e])), i = /* @__PURE__ */ new Map();
 	for (let t of e.elements) i.set(t.id, t.actualDuration);
 	for (let t of e.elements) {
@@ -100,62 +110,62 @@ var t = (e) => {
 		self: i,
 		roots: [...a]
 	};
-}, C = (e, t, n, r = x(t)) => {
-	let { children: i, base: a, elementOf: o } = r, { rendered: s, self: c, roots: l } = S(e, r), u = (e) => {
+}, w = (e, t, n, r = S(t)) => {
+	let { children: i, base: a, elementOf: o } = r, { rendered: s, self: c, roots: l } = C(e, r), u = (e) => {
 		let t = a.get(e) ?? 0;
 		if (t > 0) return t;
 		let n = s.get(e)?.actualDuration ?? 0;
 		return n > 0 ? n : y;
-	}, d = [], f = [], p = 0, m = 0, v = 0, C = [], w = l.map(u), T = w.reduce((e, t) => e + t, 0) || 1, E = 0;
+	}, d = [], f = [], p = 0, m = 0, v = 0, w = [], T = l.map(u), E = T.reduce((e, t) => e + t, 0) || 1, D = 0;
 	for (l.forEach((e, t) => {
-		let n = (w[t] || y) / T;
-		C.push({
+		let n = (T[t] || y) / E;
+		w.push({
 			id: e,
 			parentId: void 0,
-			x: E,
+			x: D,
 			width: n,
 			depth: 0,
 			ancestorRendered: !1
-		}), E += n;
-	}), C.reverse(); C.length > 0;) {
-		let e = C.pop();
-		if (e === void 0) break;
-		let { id: t, parentId: r, x: l, width: x, depth: S, ancestorRendered: w } = e, T = s.get(t), E = c.get(t) ?? 0, D = T ? E > b ? "rendered" : "bubbled" : "hatched", O = D === "rendered" && !w;
-		D === "rendered" && (m += E, v += 1), O && f.push(t), p = Math.max(p, S);
-		let k = o.get(t) ?? T?.elementId ?? t;
+		}), D += n;
+	}), w.reverse(); w.length > 0;) {
+		let t = w.pop();
+		if (t === void 0) break;
+		let { id: l, parentId: S, x: C, width: T, depth: E, ancestorRendered: D } = t, O = s.get(l), k = c.get(l) ?? 0, A = O ? k > b ? "rendered" : "bubbled" : "hatched", j = A === "rendered" && !D;
+		A === "rendered" && (m += k, v += 1), j && f.push(l), p = Math.max(p, E);
+		let M = o.get(l) ?? O?.elementId ?? l;
 		d.push({
-			id: t,
-			elementId: k,
-			name: h(k, n),
-			type: g(k, n),
-			state: D,
-			visible: _(k, n),
-			trigger: O,
-			phase: T?.phase,
-			actualDuration: T?.actualDuration ?? 0,
-			baseDuration: a.get(t) ?? T?.baseDuration ?? 0,
-			selfDuration: E,
-			depth: S,
-			parentId: r,
-			changedProps: T?.changedProps,
-			x: l,
-			width: x
+			id: l,
+			elementId: M,
+			name: h(M, n),
+			type: g(M, n),
+			state: A,
+			visible: _(M, n),
+			trigger: j,
+			phase: O?.phase,
+			actualDuration: O?.actualDuration ?? 0,
+			baseDuration: a.get(l) ?? O?.baseDuration ?? 0,
+			selfDuration: k,
+			depth: E,
+			parentId: S,
+			changedProps: O?.changedProps,
+			x: C,
+			width: T
 		});
-		let A = i.get(t) ?? [];
-		if (A.length === 0) continue;
-		let j = A.map(u), M = j.reduce((e, t) => e + t, 0), N = Math.max(u(t), M) || 1, P = l, F = [];
-		A.forEach((e, n) => {
-			let r = (j[n] || y) / N * x;
-			F.push({
+		let N = (i.get(l) ?? []).filter((t) => s.has(t) || x(r, t, e.commitId));
+		if (N.length === 0) continue;
+		let P = N.map(u), F = P.reduce((e, t) => e + t, 0), I = Math.max(u(l), F) || 1, L = C, R = [];
+		N.forEach((e, t) => {
+			let n = (P[t] || y) / I * T;
+			R.push({
 				id: e,
-				parentId: t,
-				x: P,
-				width: r,
-				depth: S + 1,
-				ancestorRendered: w || D === "rendered"
-			}), P += r;
+				parentId: l,
+				x: L,
+				width: n,
+				depth: E + 1,
+				ancestorRendered: D || A === "rendered"
+			}), L += n;
 		});
-		for (let e = F.length - 1; e >= 0; --e) C.push(F[e]);
+		for (let e = R.length - 1; e >= 0; --e) w.push(R[e]);
 	}
 	return {
 		nodes: d,
@@ -164,10 +174,10 @@ var t = (e) => {
 		renderedCount: v,
 		triggers: f
 	};
-}, w = (e, t, n) => {
-	let r = x(t), i = /* @__PURE__ */ new Map();
+}, T = (e, t, n) => {
+	let r = S(t), i = /* @__PURE__ */ new Map();
 	for (let t of e) {
-		let { self: e } = S(t, r);
+		let { self: e } = C(t, r);
 		for (let n of t.elements) {
 			let t = e.get(n.id) ?? 0;
 			if (t <= b) continue;
@@ -194,4 +204,4 @@ var t = (e) => {
 	}));
 };
 //#endregion
-export { d as BUBBLED_COLOR, a as COMMIT_ORIGIN_BADGE, i as COMMIT_ORIGIN_LABEL, o as COMMIT_ORIGIN_LEGEND, u as DURATION_LEGEND, f as HATCH_STYLE, n as SSR_COMMIT_ID, C as buildFlameModel, w as buildHotspots, x as buildTreeIndex, r as commitOrigin, l as durationColor, _ as elementVisible, s as formatMs, c as formatPercent, p as frameColor, m as frameTextColor, v as rowDuration };
+export { d as BUBBLED_COLOR, a as COMMIT_ORIGIN_BADGE, i as COMMIT_ORIGIN_LABEL, o as COMMIT_ORIGIN_LEGEND, u as DURATION_LEGEND, f as HATCH_STYLE, n as SSR_COMMIT_ID, w as buildFlameModel, T as buildHotspots, S as buildTreeIndex, r as commitOrigin, l as durationColor, _ as elementVisible, s as formatMs, c as formatPercent, p as frameColor, m as frameTextColor, v as rowDuration };

package/dist/components/PayloadView/PayloadView.d.ts

@@ -0,0 +1,11 @@
+export type PayloadViewProps = {
+    value: unknown;
+};
+/**
+ * A value, read the way the panel reads values: the same JSON viewer everywhere, wearing the panel's theme.
+ *
+ * Shared rather than per tab because the viewer ships a light palette and nothing else — on a dark panel its keys
+ * come out near-black on near-black — and every tab that shows a payload had to remember to dress it.
+ */
+declare const PayloadView: ({ value }: PayloadViewProps) => import("react").JSX.Element;
+export default PayloadView;

package/dist/components/{DevToolsPanel/tabs/ActionsViewer/components/PayloadView → PayloadView}/PayloadView.mjs

@@ -2,7 +2,7 @@ import e from "@plitzi/sdk-shared/theme/useTheme";
 import { jsx as t } from "react/jsx-runtime";
 import n from "@uiw/react-json-view";
 import * as r from "@uiw/react-json-view/vscode";
-//#region src/components/DevToolsPanel/tabs/ActionsViewer/components/PayloadView/PayloadView.tsx
+//#region src/components/PayloadView/PayloadView.tsx
 var i = {
 	...r.vscodeTheme,
 	width: "100%",

package/dist/components/PayloadView/index.mjs

@@ -0,0 +1,5 @@
+import e from "./PayloadView.mjs";
+//#region src/components/PayloadView/index.ts
+var t = e;
+//#endregion
+export { t as default };

package/dist/freshness/describeQueryPath.d.ts

@@ -0,0 +1,22 @@
+import { DescribePath } from './rows';
+/**
+ * A query cache path, read as the request it holds and as what is keeping it.
+ *
+ * The cache keys its entries by a hash of the request, because a URL is full of the store's path separator — so the
+ * path alone (`entries.22yn2ezdarx`) says nothing about which provider asked. The entry itself carries the URL and the
+ * tags, and a provider's tag is its element id.
+ *
+ * The usage is the other half, and the one that stops a panel reading as a leak: an answer nobody renders is kept on
+ * purpose, so that coming back within the grace period paints at once. Saying which of the two a row is — and when the
+ * grace period runs out — is the difference between "this page is holding rubbish" and "this page is holding this".
+ */
+declare const describeQueryPath: DescribePath;
+/**
+ * Lets go of a cached answer now, rather than at the end of its grace period.
+ *
+ * Here rather than in the panel because only this file knows a query path from any other: the cache has to be told,
+ * so that the request still out for it is dropped too and the next reader asks afresh. Answers false for a path this
+ * does not own, and for a query something still renders — that one has nothing to ask again with.
+ */
+export declare const forgetQueryPath: (store: object, path: string) => boolean;
+export default describeQueryPath;

package/dist/freshness/describeQueryPath.mjs

@@ -0,0 +1,22 @@
+import { queryCache as e } from "@plitzi/sdk-shared/queries";
+//#region src/freshness/describeQueryPath.ts
+var t = e.store, n = "entries.", r = (r, i) => {
+	if (r === t && i.startsWith(n)) return e.store.getState().entries[i.slice(n.length)];
+}, i = (t, n) => {
+	let i = r(t.entry.store, n);
+	if (!i) return;
+	let a = e.usage(i.key);
+	return {
+		label: i.url,
+		tags: i.tags,
+		usage: a && {
+			inUse: a.observers > 0 || a.holds > 0,
+			collectAt: a.collectAt
+		}
+	};
+}, a = (t, n) => {
+	let i = r(t, n);
+	return i ? e.remove(i.key) : !1;
+};
+//#endregion
+export { i as default, a as forgetQueryPath };

package/dist/freshness/formatDuration.d.ts

@@ -0,0 +1,3 @@
+/** A span of milliseconds as a countdown reads it: `18s`, `2m 5s`, `1h 12m`. */
+declare const formatDuration: (ms: number) => string;
+export default formatDuration;

package/dist/freshness/formatDuration.mjs

@@ -0,0 +1,9 @@
+//#region src/freshness/formatDuration.ts
+var e = (e) => {
+	let t = Math.max(0, Math.round(e / 1e3));
+	if (t < 60) return `${t}s`;
+	let n = Math.floor(t / 60);
+	return n < 60 ? `${n}m ${t % 60}s` : `${Math.floor(n / 60)}h ${n % 60}m`;
+};
+//#endregion
+export { e as default };

package/dist/freshness/index.d.ts

@@ -0,0 +1,8 @@
+import { default as describeQueryPath } from './describeQueryPath';
+import { default as formatDuration } from './formatDuration';
+import { default as useFreshnessByStore } from './useFreshnessByStore';
+import { default as useSecondsClock } from './useSecondsClock';
+export * from './describeQueryPath';
+export * from './rows';
+export * from './useFreshnessByStore';
+export { describeQueryPath, formatDuration, useFreshnessByStore, useSecondsClock };

package/dist/freshness/index.mjs

@@ -0,0 +1,6 @@
+import e, { forgetQueryPath as t } from "./describeQueryPath.mjs";
+import n from "./formatDuration.mjs";
+import r from "./useFreshnessByStore.mjs";
+import i from "./useSecondsClock.mjs";
+import { toRows as a } from "./rows.mjs";
+export { e as describeQueryPath, t as forgetQueryPath, n as formatDuration, a as toRows, r as useFreshnessByStore, i as useSecondsClock };

package/dist/freshness/rows.d.ts

@@ -0,0 +1,42 @@
+import { FreshnessGroup } from './useFreshnessByStore';
+/** Whether anything is rendering what a path holds, and when it is let go of if nothing starts. */
+export type PathUsage = {
+    inUse: boolean;
+    collectAt?: number;
+};
+/** What a path stands for, when the path itself is an opaque key — a query cache entry is a hash of its request. */
+export type PathDescription = {
+    label: string;
+    tags: string[];
+    usage?: PathUsage;
+};
+export type DescribePath = (group: FreshnessGroup, path: string) => PathDescription | undefined;
+export type FreshnessRowModel = {
+    /** The store and path together: two stores can hold the same path. */
+    key: string;
+    uid: string;
+    storeLabel: string;
+    path: string;
+    label: string;
+    tags: string[];
+    isStale: boolean;
+    /** How long ago it was written, e.g. `12s ago`. */
+    age: string;
+    /** `18s left` while current, `stale` once it is not. */
+    status: string;
+    /** The TTL it was written with — not what is left of it, which is what `status` says. */
+    ttl: string;
+    /** What is left of the TTL, `1` down to `0` — a bar says "half gone" in a glance that a countdown does not. */
+    progress: number;
+    /** Whether anything renders this, where that is known: only what can be let go of can be offered to. */
+    inUse?: boolean;
+    /** `forgotten in 3m 58s`, while a grace period is running. */
+    kept?: string;
+};
+/**
+ * One row per record of every store, stale ones last so what is still being served is what the panel shows first.
+ *
+ * `now` is never earlier than the newest write: the clock is a render-time snapshot, and a record written after it
+ * read as written in the future — "0s ago" and "0s left" on an answer that was never current at all.
+ */
+export declare const toRows: (groups: ReadonlyArray<FreshnessGroup>, labelOf: (group: FreshnessGroup) => string, now: number, describe?: DescribePath) => FreshnessRowModel[];

package/dist/freshness/rows.mjs

@@ -0,0 +1,29 @@
+import e from "./formatDuration.mjs";
+//#region src/freshness/rows.ts
+var t = (t, n, r, { updatedAt: i, expiresAt: a, ttl: o }, s, c) => {
+	let l = s >= a, u = Number.isFinite(a), d = "no expiry";
+	return l ? d = "stale" : u && (d = `${e(a - s)} left`), {
+		key: `${t.entry.uid}:${r}`,
+		uid: t.entry.uid,
+		storeLabel: n,
+		path: r,
+		label: c?.label ?? r,
+		tags: c?.tags ?? [],
+		isStale: l,
+		age: `${e(s - i)} ago`,
+		status: d,
+		ttl: Number.isFinite(o) ? e(o) : "∞",
+		inUse: c?.usage?.inUse,
+		kept: c?.usage?.collectAt ? `forgotten in ${e(c.usage.collectAt - s)}` : void 0,
+		progress: l ? 0 : Math.min(1, Number.isFinite(o) ? (a - s) / o : 1)
+	};
+}, n = (e, n, r, i) => {
+	let a = r;
+	for (let t of e) for (let e of Object.values(t.records)) a = Math.max(a, e.updatedAt);
+	return e.flatMap((e) => {
+		let r = n(e);
+		return Object.entries(e.records).map(([n, o]) => t(e, r, n, o, a, i?.(e, n)));
+	}).sort((e, t) => Number(e.isStale) - Number(t.isStale) || e.storeLabel.localeCompare(t.storeLabel) || e.label.localeCompare(t.label));
+};
+//#endregion
+export { n as toRows };

package/dist/freshness/useFreshnessByStore.d.ts

@@ -0,0 +1,15 @@
+import { DevStoreEntry, PathFreshness } from '@plitzi/nexus';
+export type FreshnessGroup = {
+    entry: DevStoreEntry;
+    records: Readonly<Record<string, PathFreshness>>;
+};
+/**
+ * The paths written with a TTL, across every store given — the stores that hold none are left out.
+ *
+ * Across all of them because the one holding a TTL is rarely the one being looked at: a provider's answers live in the
+ * query cache, not in the provider's own scope, and a panel that only read the picked store showed nothing unless its
+ * reader already knew where to look. Each store hands out the same records object until one changes, so the list is
+ * rebuilt only when something did.
+ */
+declare const useFreshnessByStore: (entries: ReadonlyArray<DevStoreEntry>) => ReadonlyArray<FreshnessGroup>;
+export default useFreshnessByStore;

package/dist/freshness/useFreshnessByStore.mjs

@@ -0,0 +1,20 @@
+import { useCallback as e, useRef as t, useSyncExternalStore as n } from "react";
+//#region src/freshness/useFreshnessByStore.ts
+var r = [], i = (e, t) => e.length === t.length && e.every((e, n) => e.entry === t[n].entry && e.records === t[n].records), a = (e) => Object.fromEntries(Object.entries(e).filter(([, e]) => e.ttl > 0)), o = (o) => {
+	let s = t(r), c = t(/* @__PURE__ */ new WeakMap()), l = e((e) => {
+		let t = o.map(({ store: t }) => t.watchFreshness(e));
+		return () => t.forEach((e) => e());
+	}, [o]), u = e(() => {
+		let e = o.map((e) => {
+			let t = e.store.getFreshnessRecords(), n = c.current.get(t);
+			return n || (n = a(t), c.current.set(t, n)), {
+				entry: e,
+				records: n
+			};
+		}).filter((e) => Object.keys(e.records).length > 0);
+		return i(s.current, e) || (s.current = e.length > 0 ? e : r), s.current;
+	}, [o]);
+	return n(l, u, u);
+};
+//#endregion
+export { o as default };

package/dist/freshness/useSecondsClock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `Date.now()`, moving once a second while `active` — the finest step a countdown shows.
+ *
+ * Never earlier than `floor`: the clock is a render-time snapshot, and a value written after it read as written in
+ * the future — "0s ago" and "0s left" on an answer that was never current at all.
+ */
+declare const useSecondsClock: (active: boolean, floor?: number) => number;
+export default useSecondsClock;

package/dist/freshness/useSecondsClock.mjs

@@ -0,0 +1,12 @@
+import { useEffect as e, useState as t } from "react";
+//#region src/freshness/useSecondsClock.ts
+var n = (n, r = 0) => {
+	let [i, a] = t(() => Date.now());
+	return e(() => {
+		if (!n) return;
+		let e = setInterval(() => a(Date.now()), 1e3);
+		return () => clearInterval(e);
+	}, [n]), Math.max(i, r);
+};
+//#endregion
+export { n as default };