@psnext/design-system 2.3.0 → 2.4.0

package/SKILL.md

@@ -12,18 +12,44 @@ component catalog, full token inventory, theming model — is in
 
 ## Decision order
 
+Work down this ladder in order — each step is only allowed after the one above it
+demonstrably can't produce the design:
+
 1. **Pattern first**: does a pattern (`patterns/Header`, `DataTable`, `Footer`,
    `SectionCard`, `SectionHeading`, `MediaObject`) or layout (`Container`, `Stack`,
-   `TwoColumn`, `PageBackground`) already solve it? Use it.
+   `TwoColumn`, `MultiColumn`, `PageBackground`) already solve it? Use it.
 2. **Primitive second**: compose from `primitives/*` (64 of them — check the catalog
    in DESIGN.md §6 before writing anything custom).
-3. **Custom last**: build with token utilities only; never raw colors, never a
-   parallel component that shadows an existing one.
+3. **Stock rendering**: render the chosen component with its variants/props as
+   designed. Pick the variant from its "Choosing a variant" table in DESIGN.md
+   (intent + light/dark look + tell) — don't guess from the variant name.
+4. **Layout tweaks only**: `className` may place and size the component in its
+   context — margin, width, flex/grid placement, alignment. It must never repaint
+   it (no `bg-*`/`text-*` color/`border-*` color/`hover:*` on a variant).
+5. **Exception — last resort, and marked**: only when 1–4 can't get there:
+   - **Component missing from the DS** → build custom from token utilities only
+     (tokens, px-named radii, `ring-focus`; never raw colors, never `dark:`,
+     never a parallel component that shadows an existing one).
+   - **Component exists but no variant fits** → do NOT re-skin it (see the
+     anti-pattern below); add or request a variant. If you must ship now, mark
+     the deviation at the call site so it stays auditable:
+     `// DS-EXCEPTION: <why> — <what the DS should provide instead>`
+
+Every `DS-EXCEPTION` is a design-system backlog item — sweep them with
+`grep -rn "DS-EXCEPTION"` and either upstream the need into a real
+variant/component or remove the deviation. Exceptions feed the DS; they must
+never silently erode it.
 
 Import per subpath: `@psnext/design-system/primitives/Button`. The DS bundles Radix,
 cva, lucide-react, recharts, sonner, react-hook-form, zod — import primitives from the
-DS, not from those libraries directly (exception: `toast()` from `"sonner"`, and
-`lucide-react` icons which are the standard icon set).
+DS, not from those libraries directly (exception: `toast()` from `"sonner"`).
+
+**Icons**: prefer the DS `Icon` — `<Icon icon="search" />` (typed lucide name, lazy /
+code-split) for content icons, or `<Icon as={Search} />` (sync, bare `<svg>`) with a
+lucide **or a custom** icon component, e.g. inside a component's icon slot. `Icon`
+inherits the surrounding text color by default, so it's correct on a Button; pass
+`color` or a `text-*` class to override. Raw `lucide-react` icons still work as icon-slot
+children (`<Button><Search /></Button>`) — those slots style a direct-child `[&>svg]`.
 
 ## Class-writing rules (do / don't)
 
@@ -38,10 +64,41 @@ DS, not from those libraries directly (exception: `toast()` from `"sonner"`, and
 | `text-danger-txt` for errors | `text-destructive`, `text-red-500` | severity family is info/success/warning/danger |
 | `cn(...)` from the DS for merged classes | template-string concat | cn's tailwind-merge knows the numeric radius scale |
 | suffix matches property: `bg-*-bg`, `text-*-txt` | `text-primary-bg` | token suffix encodes the valid context |
+| pick the variant that already looks right | re-skin a variant with paint classes | variants bundle hover/active/focus states — overrides break them (see below) |
 
 Figma → code: px ÷ 4 = spacing step (16px → `p-4`); radius px maps 1:1 (`rounded-12`);
 heading levels map to `<Heading size={n}>`.
 
+## Never re-skin a variant (anti-pattern)
+
+A component variant is a **package deal**: rest + hover + active + focus + disabled
+states, tuned together. Overriding its paint with `className` only changes the rest
+state — the interaction states still belong to the original variant, and the result
+is visibly broken.
+
+Real failure seen in the wild:
+
+```tsx
+// ✗ WRONG — outline button "made primary" with a bg override
+<Button variant="outline" className="bg-primary-invert-bg text-primary-invert-txt">
+// Looks primary at rest. On hover, outline's own hover:bg-outline-hover-bg fires
+// and the fill flickers to a translucent gray — broken hover, broken contrast.
+
+// ✓ RIGHT — that look already exists as a variant
+<Button variant="default">
+```
+
+Rules:
+
+- **`className` on a DS component is for layout only** — margin, width, flex/grid
+  placement, alignment. Never for paint: `bg-*`, `text-*` color, `border-*` color,
+  `hover:*`, `rounded-*` that fight the variant.
+- **If the look you want isn't a variant, that's a DS gap** — don't patch it at the
+  call site. Add/request a variant (cva) so the states are designed together.
+- This applies to **every** cva-styled component (Button, Badge, Tabs, Card, Alert, …),
+  not just Button. If you catch yourself writing a paint class on one, stop and check
+  the component's variant table in DESIGN.md first.
+
 ## Recipes
 
 **Page scaffold**
@@ -85,6 +142,27 @@ tokens inside flip; do not hand-pick dark colors.
   with `cn`); don't wrap in extra divs to fight specificity.
 - **`!important` on library-styled elements** (e.g. toast classNames) will override
   richColors/severity styling — scope with `data-[type=…]` variants instead.
+- **App-defined `@layer base` wiping the tokens**: an app that declares its own
+  base-layer `:root`/`body` rules (or a reset) can silently override the DS token
+  variables — every component then renders colorless while classes look correct.
+  Don't redefine base-layer custom properties; put app-level overrides *after* the
+  DS styles import, outside `@layer base`.
+
+**If the DS token variables are missing entirely** (components render but
+`--primary-bg` etc. aren't on `:root`), walk this tree in order:
+
+1. Devtools → inspect `<html>` → computed styles → search `--primary-bg`.
+   Present? The tokens are fine — suspect a wrong class name or missing `@source`.
+2. Absent → check the Tailwind entry CSS: `@import "tailwindcss"` then
+   `@import "@psnext/design-system/styles"`, and **all `@import`s before any other
+   statement** (including `@source` — a misplaced import can abort the rest).
+3. Confirm Tailwind is **v4** and this file is actually compiled by
+   `@tailwindcss/vite` / `@tailwindcss/postcss` (not served as plain CSS).
+4. Check nothing *later* redefines the vars: app `@layer base` blocks, resets, or
+   `:root` rules after the import (see the pitfall above — this has happened).
+5. Isolation test: `@import "@psnext/design-system/dist/styles/tokens/mode-light.css"`.
+   If vars appear now, the `/styles` subpath isn't resolving in your bundler —
+   report that, don't ship the workaround.
 - **Logo**: never recolor; wordmark ink follows mode automatically; no ThemeProvider
   needed.
 

package/bin/install-agent-skill.mjs

@@ -2,14 +2,14 @@
 // Install the design-system agent docs (SKILL.md + DESIGN.md) into a consumer
 // project as an Agent Skill, so coding agents load them for UI work.
 //
-//   npx @psnext/design-system              → .agents/skills/design-system/
+//   npx @psnext/design-system              → .agent/skills/design-system/
 //   npx @psnext/design-system <dir>        → <dir>/  (explicit destination)
 //
 // The two docs are copied verbatim from the installed package; SKILL.md links to
 // DESIGN.md as a sibling, so they must land in the same folder (this does that).
 
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -20,7 +20,7 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log(`Install @psnext/design-system agent docs as an Agent Skill.
 
 Usage:
-  npx @psnext/design-system              Copy SKILL.md + DESIGN.md into .agents/skills/design-system/
+  npx @psnext/design-system              Copy SKILL.md + DESIGN.md into .agent/skills/design-system/
   npx @psnext/design-system <dir>        Copy into an explicit destination folder
   npx @psnext/design-system --help       Show this help
 
@@ -32,7 +32,7 @@ The agent then loads the skill when writing or reviewing UI in this project.`);
 const positional = args.find((a) => !a.startsWith("-"));
 const dest = positional
   ? resolve(process.cwd(), positional)
-  : resolve(process.cwd(), ".agents/skills/design-system");
+  : resolve(process.cwd(), ".agent/skills/design-system");
 
 for (const doc of DOCS) {
   const src = join(PKG_ROOT, doc);
@@ -42,13 +42,45 @@ for (const doc of DOCS) {
   }
 }
 
-mkdirSync(dest, { recursive: true });
+// Whether the skill was already installed here (a re-run just refreshes the two
+// docs in place) — checked before we create anything.
+const isRefresh = DOCS.every((doc) => existsSync(join(dest, doc)));
+
+// Validate/create the destination one level at a time (for the default that's
+// .agent → skills → design-system): reuse a folder that already exists, create
+// the ones that don't, and bail with a clear message if a segment is occupied
+// by a file — otherwise mkdir would fail cryptically. Only walk segments under
+// the cwd; anything outside falls through to the recursive mkdir below.
+const chain = [];
+for (let cur = dest; cur.startsWith(process.cwd() + sep); cur = dirname(cur)) {
+  chain.unshift(cur);
+}
+for (const dir of chain) {
+  if (existsSync(dir)) {
+    if (!statSync(dir).isDirectory()) {
+      console.error(`✗ ${dir} already exists but is not a directory — move it aside and re-run.`);
+      process.exit(1);
+    }
+    continue; // reuse the existing folder
+  }
+  mkdirSync(dir); // parent already ensured by the outer→inner order
+}
+
+try {
+  mkdirSync(dest, { recursive: true }); // covers a destination outside the cwd
+} catch (err) {
+  console.error(`✗ Could not create ${dest}: ${err.message}`);
+  process.exit(1);
+}
+
 for (const doc of DOCS) {
   copyFileSync(join(PKG_ROOT, doc), join(dest, doc));
 }
 
 const rel = dest.startsWith(process.cwd()) ? `.${dest.slice(process.cwd().length)}` : dest;
-console.log(`✓ Installed @psnext/design-system agent skill → ${rel}/`);
+console.log(
+  `✓ ${isRefresh ? "Refreshed" : "Installed"} @psnext/design-system agent skill → ${rel}/`,
+);
 console.log("  • SKILL.md   — workflow playbook (the Agent Skill entry point)");
 console.log("  • DESIGN.md  — full token + component reference");
 console.log("\nRe-run this after upgrading the package to refresh the docs.");

package/dist/Header.cjs

@@ -1,5 +1,6 @@
 const require_chunk = require("./chunk.cjs");
 const require_cn = require("./cn.cjs");
+const require_Icon = require("./Icon.cjs");
 const require_primitives_Button_index = require("./primitives/Button/index.cjs");
 const require_primitives_Avatar_index = require("./primitives/Avatar/index.cjs");
 const require_primitives_Credits_index = require("./primitives/Credits/index.cjs");
@@ -12,8 +13,8 @@ const require_primitives_ThemeProvider_index = require("./primitives/ThemeProvid
 let react = require("react");
 let react$1 = require_chunk.__toESM(react, 1);
 react = require_chunk.__toESM(react);
-let lucide_react = require("lucide-react");
 let react_jsx_runtime = require("react/jsx-runtime");
+let lucide_react = require("lucide-react");
 let _tanstack_react_query = require("@tanstack/react-query");
 //#region src/patterns/Header/project-tree.ts
 /** True when a node with the given id exists anywhere in the tree. */
@@ -77,7 +78,10 @@ function ProjectPicker({ projectsTree, selectedProjectId, selectedProjectName, o
 				children: [projectLabel, ":"]
 			}),
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_primitives_Skeleton_index.Skeleton, { className: "h-3 flex-1" }),
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronDown, { className: "size-4 shrink-0 text-muted-txt opacity-40" })
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_Icon.Icon, {
+				as: lucide_react.ChevronDown,
+				className: "size-4 shrink-0 text-muted-txt opacity-40"
+			})
 		]
 	});
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(require_primitives_Popover_index.Popover, {
@@ -98,7 +102,10 @@ function ProjectPicker({ projectsTree, selectedProjectId, selectedProjectName, o
 					className: require_cn.cn("max-w-36 truncate", selectedName ? "font-medium" : "text-muted-txt"),
 					children: selectedName ?? projectPlaceholder
 				}),
-				/* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronDown, { className: "ml-1 size-4 shrink-0 text-muted-txt" })
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_Icon.Icon, {
+					as: lucide_react.ChevronDown,
+					className: "ml-1 size-4 shrink-0 text-muted-txt"
+				})
 			]
 		}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(require_primitives_Popover_index.PopoverContent, {
 			align: "start",
@@ -109,7 +116,10 @@ function ProjectPicker({ projectsTree, selectedProjectId, selectedProjectName, o
 				className: "border-b p-2",
 				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 					className: "relative",
-					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Search, { className: "absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2 text-muted-txt" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_primitives_Input_index.Input, {
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_Icon.Icon, {
+						as: lucide_react.Search,
+						className: "absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2 text-muted-txt"
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_primitives_Input_index.Input, {
 						size: "sm",
 						className: "pl-8",
 						placeholder: searchPlaceholder,
@@ -151,7 +161,13 @@ function TreeNode({ node, depth, selectedId, onSelect, collapsedIds, onToggleCol
 					"aria-label": isCollapsed ? `Expand ${node.name}` : `Collapse ${node.name}`,
 					onClick: () => onToggleCollapse(node.id),
 					className: "shrink-0 text-muted-txt hover:text-primary-txt",
-					children: isCollapsed ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronRight, { className: "size-3.5" }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronDown, { className: "size-3.5" })
+					children: isCollapsed ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_Icon.Icon, {
+						as: lucide_react.ChevronRight,
+						className: "size-3.5"
+					}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_Icon.Icon, {
+						as: lucide_react.ChevronDown,
+						className: "size-3.5"
+					})
 				}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { className: "inline-block w-3.5 shrink-0" }),
 				node.isContextOnly ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 					className: "flex-1 text-left",
@@ -162,7 +178,10 @@ function TreeNode({ node, depth, selectedId, onSelect, collapsedIds, onToggleCol
 					className: "flex-1 text-left",
 					children: node.name
 				}),
-				isSelected && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Check, { className: "ml-auto size-3.5 shrink-0 text-primary" })
+				isSelected && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_Icon.Icon, {
+					as: lucide_react.Check,
+					className: "ml-auto size-3.5 shrink-0 text-primary"
+				})
 			]
 		}), !isCollapsed && hasChildren && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 			role: "group",
@@ -189,8 +208,8 @@ const DEFAULT_LABELS = {
 	profileMenuLabel: "Profile menu",
 	logoutLabel: "Logout"
 };
-//#endregion
-//#region src/patterns/Header/api.ts
+/** Hard cap on project pages fetched — guards against a runaway loop. */
+const PROJECTS_MAX_PAGES = 40;
 const PATHS = {
 	token: "/api/v1/studio-auth/sessions/token",
 	logout: "/api/v1/studio-auth/sessions/logout",
@@ -215,16 +234,77 @@ async function fetchToken(endpoints, fetcher) {
 	const { accessToken } = await res.json();
 	return accessToken;
 }
+/**
+* Return `url` with the `page` query param set to the given page (and `limit`
+* backfilled when absent). Pagination stays owned by the header: host-provided
+* endpoint URLs don't need — and can't break — the paging params. Handles
+* absolute and relative URLs.
+*/
+function withPageParam(url, page) {
+	const isAbsolute = /^[a-z][a-z0-9+.-]*:\/\//i.test(url);
+	try {
+		const u = new URL(url, isAbsolute ? void 0 : "http://relative.invalid");
+		u.searchParams.set("page", String(page));
+		if (!u.searchParams.has("limit")) u.searchParams.set("limit", String(50));
+		return isAbsolute ? u.toString() : `${u.pathname}${u.search}${u.hash}`;
+	} catch {
+		return url;
+	}
+}
+/** The `limit` query param already on a URL, else the default page size. */
+function readLimitParam(url) {
+	try {
+		const limit = Number(new URL(url, "http://relative.invalid").searchParams.get("limit"));
+		return Number.isInteger(limit) && limit > 0 ? limit : 50;
+	} catch {
+		return 50;
+	}
+}
+/** Total node count in a tree page (roots + descendants). */
+function countNodes(tree) {
+	return tree.reduce((sum, node) => sum + 1 + countNodes(node.children ?? []), 0);
+}
+/**
+* Merge a page's tree into the accumulated tree. Nodes repeated across pages
+* (e.g. a context-only ancestor whose children span a page boundary) are
+* merged by id instead of duplicated.
+*/
+function mergeTrees(into, page) {
+	for (const node of page) {
+		const existing = into.find((n) => n.id === node.id);
+		if (existing) mergeTrees(existing.children, node.children ?? []);
+		else into.push({
+			...node,
+			children: [...node.children ?? []]
+		});
+	}
+}
+/**
+* Fetch ALL pages of the paginated projects endpoint and merge them into a
+* single tree, so users with more projects than one page still see everything.
+* The response carries no pagination metadata, so the first page that comes
+* back with fewer than `limit` nodes is treated as the last one.
+*/
 async function fetchProjects(endpoints, clientId, accessToken, fetcher) {
-	const res = await fetcher(endpoints.projects(clientId), {
-		credentials: "include",
-		headers: { Authorization: `Bearer ${accessToken}` }
-	});
-	if (!res.ok) throw new Error(`projects request failed: ${res.status}`);
-	const data = await res.json();
+	const projectsTree = [];
+	let organizationName;
+	const baseUrl = endpoints.projects(clientId);
+	const pageLimit = readLimitParam(baseUrl);
+	for (let page = 1; page <= PROJECTS_MAX_PAGES; page++) {
+		const res = await fetcher(withPageParam(baseUrl, page), {
+			credentials: "include",
+			headers: { Authorization: `Bearer ${accessToken}` }
+		});
+		if (!res.ok) throw new Error(`projects request failed: ${res.status}`);
+		const body = await res.json();
+		const pageTree = body.response?.data?.projectsTree ?? [];
+		mergeTrees(projectsTree, pageTree);
+		organizationName ??= body.response?.data?.organization?.name;
+		if (countNodes(pageTree) < pageLimit) break;
+	}
 	return {
-		projectsTree: data.response?.data?.projectsTree ?? [],
-		organizationName: data.response?.data?.organization?.name
+		projectsTree,
+		organizationName
 	};
 }
 async function fetchCredits(endpoints, accessToken, fetcher) {
@@ -249,6 +329,7 @@ async function callLogout(endpoints, fetcher) {
 //#region src/patterns/Header/storage.ts
 const PROJECT_KEY = "ds-header-project";
 const LAST_PROJECT_KEY = "lastSelectedProject";
+const PROJECTS_CACHE_KEY = "ds-header-projects-cache";
 function getStoredProject() {
 	try {
 		const raw = sessionStorage.getItem(PROJECT_KEY);
@@ -281,6 +362,38 @@ function setLastSelectedProject(project) {
 		localStorage.setItem(LAST_PROJECT_KEY, JSON.stringify(project));
 	} catch {}
 }
+function projectsCacheKey(clientId, userId) {
+	return `${PROJECTS_CACHE_KEY}:${clientId}:${userId}`;
+}
+/** The session-cached projects result for this client + user, or null on miss. */
+function getCachedProjects(clientId, userId) {
+	try {
+		const raw = sessionStorage.getItem(projectsCacheKey(clientId, userId));
+		if (!raw) return null;
+		const cached = JSON.parse(raw);
+		if (!Array.isArray(cached.projectsTree)) return null;
+		return {
+			projectsTree: cached.projectsTree,
+			organizationName: cached.organizationName
+		};
+	} catch {
+		return null;
+	}
+}
+function setCachedProjects(clientId, userId, data) {
+	try {
+		sessionStorage.setItem(projectsCacheKey(clientId, userId), JSON.stringify(data));
+	} catch {}
+}
+/** Drop every cached projects entry (all clients/users) — used on logout. */
+function clearCachedProjects() {
+	try {
+		for (let i = sessionStorage.length - 1; i >= 0; i--) {
+			const key = sessionStorage.key(i);
+			if (key?.startsWith(PROJECTS_CACHE_KEY)) sessionStorage.removeItem(key);
+		}
+	} catch {}
+}
 //#endregion
 //#region src/patterns/Header/header-store.ts
 function initialState() {
@@ -464,7 +577,7 @@ function isSessionValid(environmentId) {
 const TOGGLE_PROJECT_DROPDOWN_EVENT = "toggle-project-dropdown";
 const DEFAULT_STALE_TIME = 5 * 6e4;
 const DEFAULT_GC_TIME = 10 * 6e4;
-function useGlobalHeader({ apiBaseUrl, environmentId, clientId, _dangerouslyInjectAccessToken: injectedToken, showProjectDropdown = false, showProfile = false, showOrg = false, showCredits = false, endpoints: endpointOverrides, fetcher: fetcherProp, staleTime = DEFAULT_STALE_TIME, gcTime = DEFAULT_GC_TIME, onProjectChange }) {
+function useGlobalHeader({ apiBaseUrl, environmentId, clientId, defaultProjectId, _dangerouslyInjectAccessToken: injectedToken, showProjectDropdown = false, showProfile = false, showOrg = false, showCredits = false, endpoints: endpointOverrides, fetcher: fetcherProp, staleTime = DEFAULT_STALE_TIME, gcTime = DEFAULT_GC_TIME, onProjectChange }) {
 	const fetcher = react$1.useMemo(() => fetcherProp ?? ((input, init) => fetch(input, init)), [fetcherProp]);
 	const endpoints = react$1.useMemo(() => buildEndpoints(apiBaseUrl, endpointOverrides), [apiBaseUrl, endpointOverrides]);
 	const isAuthenticated = isSessionValid(environmentId);
@@ -482,15 +595,25 @@ function useGlobalHeader({ apiBaseUrl, environmentId, clientId, _dangerouslyInje
 	});
 	const token = injectedToken ?? tokenQuery.data;
 	const effectiveClientId = clientId ?? claims?.clientId;
+	const wantsProjects = showProjectDropdown || showOrg;
+	const userId = claims?.userId ?? "";
 	const projectsQuery = (0, _tanstack_react_query.useQuery)({
 		queryKey: [
 			"ds-header",
 			"projects",
 			effectiveClientId,
+			userId,
 			token
 		],
-		queryFn: () => fetchProjects(endpoints, effectiveClientId, token, fetcher),
-		enabled: isAuthenticated && !!token && !!effectiveClientId && (showProjectDropdown || showOrg),
+		queryFn: async () => {
+			const id = effectiveClientId;
+			const cached = getCachedProjects(id, userId);
+			if (cached) return cached;
+			const fresh = await fetchProjects(endpoints, id, token, fetcher);
+			setCachedProjects(id, userId, fresh);
+			return fresh;
+		},
+		enabled: isAuthenticated && !!token && !!effectiveClientId && wantsProjects,
 		staleTime,
 		gcTime
 	});
@@ -535,6 +658,9 @@ function useGlobalHeader({ apiBaseUrl, environmentId, clientId, _dangerouslyInje
 			const fallback = last && nodeExistsInTree(tree, last.id) ? {
 				id: last.id,
 				name: findProjectName(tree, last.id) ?? last.name
+			} : defaultProjectId && nodeExistsInTree(tree, defaultProjectId) ? {
+				id: defaultProjectId,
+				name: findProjectName(tree, defaultProjectId) ?? ""
 			} : firstSelectableProject(tree);
 			if (fallback) {
 				headerStore.setProject(fallback.id, fallback.name, effectiveClientId, { remember: false });
@@ -542,7 +668,11 @@ function useGlobalHeader({ apiBaseUrl, environmentId, clientId, _dangerouslyInje
 			} else if (id) headerStore.clearProject();
 		}
 		headerStore.setOrganization(projectsQuery.data.organizationName, effectiveClientId);
-	}, [projectsQuery.data, effectiveClientId]);
+	}, [
+		projectsQuery.data,
+		effectiveClientId,
+		defaultProjectId
+	]);
 	react$1.useEffect(() => {
 		if (creditsQuery.data !== void 0) headerStore.setCredits(creditsQuery.data);
 	}, [creditsQuery.data]);
@@ -553,6 +683,7 @@ function useGlobalHeader({ apiBaseUrl, environmentId, clientId, _dangerouslyInje
 	};
 	const logout = () => {
 		headerStore.clearProject();
+		clearCachedProjects();
 		callLogout(endpoints, fetcher);
 	};
 	const [projectDropdownVisible, setProjectDropdownVisible] = react$1.useState(showProjectDropdown);