@teamscala/service-boot 0.23.284

package/src/bind-page-handler.ts

@@ -0,0 +1,223 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Calls a createPageHandler() handler with the per-request extras the
+ * SSR pipeline needs: the resolved userId/orgId (from localhost-bypass
+ * or better-auth-cookie), and the htmlTemplate. Shared by the regions
+ * and page_slug shell variants.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { Context } from "hono";
+import { readHtmlTemplate } from "./read-html-template.ts";
+import {
+	PrimaryResourceMissingError,
+	buildResourceNotFoundResponse,
+	resolveErrorPageLogo,
+} from "./resource-not-found.ts";
+import { extractOrgIdFromCallbackPath } from "./resolvers/portal-route-paths.ts";
+
+type PageHandler = (
+	req: Request,
+	extras: Record<string, unknown>,
+) => Promise<{ body: unknown; status: number; headers: HeadersInit }>;
+
+export async function bindPageHandler(
+	c: Context,
+	handler: PageHandler,
+	authMode: string,
+	serviceSlug: string,
+	label: string,
+	resourceOrgId?: string,
+): Promise<Response> {
+	const log = getAppLogger();
+	try {
+		let userId: string | undefined;
+		let orgId: string | undefined;
+		let visitor: { id: string; name: string; email: string } | null = null;
+
+		// NO localhost super-admin bypass: identity comes ONLY from the session
+		// (the auth-gate already forces sign-in for authed services on every
+		// host, 127.0.0.1 included). The old `if (isLocalhost) userId="super-admin"`
+		// rendered authed pages as a privileged user on localhost regardless of
+		// who (if anyone) was signed in — so agent/tool verification on 127.0.0.1
+		// saw a view that diverged from the real signed-in user's. Tools that need
+		// an authed render sign in and carry the cookie (getSuperAdminSessionCookie).
+
+		// The .scala.business session cookie reaches EVERY app on the domain,
+		// so a signed-in platform user is identifiable at SSR regardless of
+		// this service's own auth mode. Resolving it per-request (never via
+		// the cross-request loader graph) lets identity-gated blocks
+		// (PublicGptBlock's SignInBlock gate) first-paint the real experience
+		// instead of a client-side "checking who you are" loading pass
+		// (ssr-then-live-handoff). authMode still governs AUTHORIZATION;
+		// this is read-only identity convenience.
+		const hasSessionCookie = /better-auth\.session_token=/.test(
+			c.req.header("cookie") ?? "",
+		);
+
+		if (authMode === "better-auth-cookie" || hasSessionCookie) {
+			// Visitor identity is an ENHANCEMENT: on auth:none services
+			// (scala-public et al.) no auth factory is registered, and a
+			// signed-in operator's domain-wide cookie reaches every
+			// *.scala.business site — getSession throwing "Auth factory not
+			// registered" 500'd every page for signed-in visitors
+			// (public-dev outage, 2026-06-11). Degrade to anonymous, never
+			// fail the render (block-and-provider-error-isolation).
+			try {
+				const { getSession } = await import("@teamscala/auth/get-session.ts");
+				const session = await getSession(c.req.raw.headers);
+				if (authMode === "better-auth-cookie") {
+					userId = session?.user?.id;
+					orgId = session?.session.activeOrganizationId ?? undefined;
+				}
+				if (session?.user?.email) {
+					visitor = {
+						id: session.user.id,
+						name: session.user.name ?? session.user.email,
+						email: session.user.email,
+					};
+				}
+			} catch (err) {
+				if (authMode === "better-auth-cookie") throw err;
+				// cookie-only enhancement path: anonymous render proceeds
+			}
+		}
+
+		// Anonymous dynamic routes (proposal/form/quiz/agent) resolve a
+		// resource whose owning org is known from the loader. That org owns
+		// the brand the block-level serverLoaders read — override the
+		// viewer's org (if any) so the SSR injects the resource owner's
+		// logo/colours, not the viewer's.
+		if (resourceOrgId) orgId = resourceOrgId;
+
+		// Unauthed /sign-in (no session, no resource) would otherwise resolve no
+		// org, and the brand resolver falls back to the super-admin org (GBG Indo)
+		// — so a link shared to org A (e.g. GMG APAC) previews as org B's brand on
+		// WhatsApp/crawlers, because the link 302→/sign-in for the unauthed crawler.
+		// The callbackURL carries the org the visitor is signing in to; derive orgId
+		// from it so the sign-in page's brand/title/og reflect the destination org.
+		// The canonical portal shape is /<websiteId>/<orgId>/<path> — the org is
+		// segment 1, NOT segment 0. Reading segment 0 (the website id) fed a website
+		// id into brand resolution, which resolved no org and fell back to the
+		// super-admin org — the exact cross-tenant mis-branding this block exists to
+		// fix, still live until 2026-07-21; violates portal-branding-resolves-page-org-first.
+		// scala-projects routes /<orgId>/… (single UUID) and proposal/form/quiz hosts
+		// route /<resourceId>/… (a non-org first segment) — both keep segment 0 via
+		// the helper's single-UUID fallback (resolves to no brand, falls back as
+		// before). The helper is the single authority shared with the route resolver.
+		if (!orgId) {
+			const cb = c.req.query("callbackURL") ?? "";
+			const resolved = extractOrgIdFromCallbackPath(cb);
+			if (resolved) orgId = resolved;
+		}
+
+		const nonce = c.get("nonce") as string | undefined;
+
+		const resp = await handler(c.req.raw, {
+			userId,
+			orgId,
+			visitor,
+			searchParams: c.req.query(),
+			htmlTemplate: await readHtmlTemplate(),
+			nonce,
+		});
+		// Per-page root.props.maxWidth (the canonical mechanism) centers any
+		// page at the chosen width via inline styles — already hydration-safe
+		// and page-scoped. Bind-page-handler MUST NOT inject unscoped CSS
+		// selectors: a global `.puck-root-slot { max-width }` rule shrinks
+		// every portal pane that hosts a Puck root (the 2026-06-17 dashboard
+		// sliver bug — `.puck-root-slot` matches every Puck page in every
+		// region, including the dashboard center pane). The `no-bind-page-handler-css-injection`
+		// guard enforces this; this comment is the load-bearing rationale.
+		// Live dashboards must never be served from a stale cache (intermediary,
+		// browser back-forward, mobile Safari aggressive caching). Force every
+		// SSR HTML response to be revalidated. Static assets (CSS/JS bundles)
+		// keep their hash-busted caching — those are content-addressed.
+		// no-transform: intermediaries must not mutate SSR HTML — Cloudflare's
+		// Email Address Obfuscation rewrites mailto: hrefs at the edge, which
+		// breaks the server-serializes-client-reads-verbatim hydration contract
+		// (React recoverable-error on every page with a mailto link). Per CF
+		// docs, Email Obfuscation does not apply when no-transform is present.
+		// NOTE: a shared-edge-caching (CDN max-age) variant shipped briefly on 2026-06-10
+		// and was REMOVED by operator ruling the same day ("the origin should
+		// be so fast we don't care") — the origin-speed work (SWR caches,
+		// wave-parallel loader, brotli) is the sanctioned path; re-adding
+		// shared-cache headers needs a fresh operator ruling.
+		const headers = new Headers(resp.headers as HeadersInit);
+		headers.set(
+			"Cache-Control",
+			"no-store, no-cache, no-transform, must-revalidate, max-age=0",
+		);
+		headers.set("Pragma", "no-cache");
+		headers.set("Expires", "0");
+		// Viewport-aware slot loading varies the response by these headers.
+		// Even with Cache-Control: no-store, browsers and intermediaries
+		// honour Vary on back/forward navigation and BFCache; Accept-CH
+		// asks the browser to send Sec-CH-UA-Mobile on subsequent
+		// navigations (Chromium-family auto-sends, others opt in).
+		headers.set("Vary", "Sec-CH-UA-Mobile, User-Agent");
+		headers.set("Accept-CH", "Sec-CH-UA-Mobile");
+		// Origin-side gzip. Cache-Control: no-transform (load-bearing above —
+		// it disables Cloudflare HTML rewrites that corrupt hydration) ALSO
+		// makes hono's compress() middleware skip this response, which shipped
+		// 1.2MB of raw SSR HTML per page load through the dev tunnel (~3s of
+		// pure transfer; the operator's tablet timed out — 2026-06-06).
+		// no-transform forbids INTERMEDIARY transforms; origin-applied
+		// content-coding is part of the representation (RFC 9110 §8.4.1), so
+		// compressing here honors both. Bun.gzipSync on ~1.2MB costs ~10ms.
+		const acceptEnc = c.req.header("Accept-Encoding") ?? "";
+		// Brotli preferred when offered (every modern browser): ~15-20%
+		// smaller than gzip on SSR HTML. Quality 4, NOT the library default
+		// 11 — q11 costs hundreds of ms on a ~1MB page (defeats the point);
+		// q4 compresses in single-digit ms and still beats gzip.
+		if (/\bbr\b/.test(acceptEnc) && resp.body) {
+			const { brotliCompressSync, constants } = await import("node:zlib");
+			const raw = new Uint8Array(await new Response(resp.body as never).arrayBuffer());
+			const br = brotliCompressSync(raw, {
+				params: { [constants.BROTLI_PARAM_QUALITY]: 4 },
+			});
+			headers.set("Content-Encoding", "br");
+			headers.delete("Content-Length");
+			return new Response(br as never, { status: resp.status, headers });
+		}
+		if (/\bgzip\b/.test(acceptEnc) && resp.body) {
+			const raw = new Uint8Array(await new Response(resp.body as never).arrayBuffer());
+			const gz = Bun.gzipSync(raw);
+			headers.set("Content-Encoding", "gzip");
+			headers.delete("Content-Length");
+			return new Response(gz as never, { status: resp.status, headers });
+		}
+		return new Response(resp.body as never, { status: resp.status, headers });
+	} catch (err) {
+		// Dead entity link (wrong id, deleted row) → the branded not-found
+		// page with a real 404 — never a 500, never default-content leakage.
+		if (err instanceof PrimaryResourceMissingError) {
+			log.warn(
+				`[scala-install:${serviceSlug}] 404 ${err.resourceType} not found (${label}) for ${new URL(c.req.url).pathname}`,
+			);
+			return buildResourceNotFoundResponse(
+				err.resourceType,
+				await resolveErrorPageLogo(serviceSlug),
+				err.httpStatus,
+				// "Take me home" → the host root (relative "/" resolves to the
+				// current site's home; the portal redirects / to its dashboard).
+				// empty → the page-row-exists-but-zero-blocks "This page is empty"
+				// surface, distinct from a dead link (operator ruling 2026-07-21).
+				{ homeUrl: "/", empty: err.empty },
+			);
+		}
+		log.error(
+			`[scala-install:${serviceSlug}] Render error (${label}) for ${new URL(c.req.url).pathname}:`,
+			err,
+		);
+		return new Response(
+			`Render error: ${err instanceof Error ? err.message : String(err)}`,
+			{
+				status: 500,
+			},
+		);
+	}
+}

package/src/build-client-assets/input-hashing.ts

@@ -0,0 +1,206 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Input hashing for the client-asset build fingerprint.
+ *
+ * Split out of build-client-assets.ts, which had grown to 1221 lines holding
+ * six distinct concerns (lock + status, manifest, hydrate bundle, source maps,
+ * stylesheet/tailwind, and this). `single-purpose-file` did not catch it: that
+ * rule flags a file whose top-level exports share no common name root, which
+ * measures export-NAME cohesion rather than how many concerns a file holds — so
+ * a large file with few tidily-named exports stays invisible to it.
+ *
+ * This module owns ONE concern: turning the build's real inputs into a stable
+ * hash. `computeInputFingerprint` (still in the parent, and still the only
+ * exported entry point) composes the two functions exported here; everything
+ * else is module-private because nothing outside needs it.
+ *
+ * Byte-for-byte move — imports adjusted, nothing else. No renames, no type
+ * changes (`migrations-copy-not-rewrite`).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+// Resolve + hash the content of every `@import` in app.css's @teamscala/*
+// stylesheet chain — INCLUDING transitive @imports (generic-ui/styles.css
+// @imports blk-utilities/styles.css; hashing only the direct import left
+// blk-utilities changes undetected → stale bundle). Cycle-safe via `seen`.
+export async function hashResolvedPackageStylesheets(
+	cwd: string,
+	h: ReturnType<typeof createHash>,
+): Promise<void> {
+	let appCss: string;
+	try {
+		appCss = await Bun.file(join(cwd, "src", "app.css")).text();
+	} catch {
+		return; // no app.css → nothing to fold (the main loop already recorded <absent>)
+	}
+	const seen = new Set<string>();
+	const hashSpec = async (spec: string, base: string): Promise<void> => {
+		if (seen.has(spec)) return;
+		seen.add(spec);
+		try {
+			const resolved = await Bun.resolve(spec, base);
+			const content = await Bun.file(resolved).text();
+			h.update("pkgcss:").update(spec).update("\0").update(content).update("\0");
+			// Follow transitive @imports within this stylesheet (relative + @teamscala/*).
+			for (const child of [
+				...content.matchAll(/@import\s+["']([^"']+)["']/g),
+			].map((m) => m[1].trim())) {
+				if (child.startsWith("tailwindcss")) continue;
+				await hashSpec(child, dirname(resolved));
+			}
+		} catch {
+			h.update("pkgcss:").update(spec).update("\0<unresolved>\0");
+		}
+	};
+	for (const spec of [
+		...appCss.matchAll(/@import\s+["'](@teamgbg\/[^"']+)["']/g),
+	].map((m) => m[1].trim())) {
+		await hashSpec(spec, join(cwd, "src"));
+	}
+}
+
+// The JS twin of hashResolvedPackageStylesheets: resolve + hash the CONTENT of
+// every @teamscala/* JS/TS module reachable from the client entrypoints, so a
+// mid-install stale bake (bun.lock ahead of node_modules — see computeInputFingerprint)
+// is detected on the next boot and self-heals. Third-party modules are NOT walked
+// (their versions are pinned by bun.lock and they don't change on a @teamgbg
+// publish); only the @teamgbg surface — the publish-driven change graph — is folded.
+//
+// Determinism: per-file content hashes are collected into a map keyed on the
+// package-relative path, then folded into the aggregate hasher in SORTED path
+// order. The walk itself runs bounded-concurrent (no-serial-per-unit-work-on-hot-
+// paths — the @teamgbg graph is ~1k+ files for a large UI; a serial await-per-file
+// walk starves the boot path), but scheduling order never affects the result.
+const JS_IMPORT_SPEC_RE = /\b(?:from|import|export|require)\s*\(?["']([^"']+)["']/g;
+const JS_GRAPH_CONCURRENCY = 32;
+
+// Parse the package name (scoped `@scope/pkg` or unscoped `pkg`) from a
+// resolved node_modules path. lastIndexOf picks the INNERMOST package when
+// node_modules is nested (a -> node_modules/b), which is the package actually
+// imported. Returns null for a path not under node_modules.
+function nodeModulesPkgName(resolvedPath: string): string | null {
+	const idx = resolvedPath.lastIndexOf("/node_modules/");
+	if (idx < 0) return null;
+	const rest = resolvedPath.slice(idx + "/node_modules/".length);
+	const slash = rest.indexOf("/");
+	if (rest.startsWith("@")) {
+		if (slash < 0) return rest; // malformed scoped name with no slash
+		const secondSlash = rest.indexOf("/", slash + 1);
+		return secondSlash < 0 ? rest : rest.slice(0, secondSlash);
+	}
+	return slash < 0 ? rest : rest.slice(0, slash);
+}
+
+// Best-effort read of an installed package's declared version. Used at the
+// third-party closure boundary so a version bump of a closure dep (react, etc.)
+// invalidates the fingerprint without content-walking the (large, pinned)
+// package. Returns null on any failure — an ABSENT signal, not a masking
+// fallback (protective-layers-fail-explicitly): the caller omits the package,
+// so a later successful read folds in a real version and invalidates. Never
+// returns a non-null placeholder that would hide the failure.
+async function readInstalledPkgVersion(
+	resolvedPath: string,
+	pkgName: string,
+): Promise<string | null> {
+	const marker = "/node_modules/";
+	const idx = resolvedPath.lastIndexOf(marker);
+	const pkgRoot = join(resolvedPath.slice(0, idx + marker.length), pkgName);
+	try {
+		const pkg = JSON.parse(await Bun.file(join(pkgRoot, "package.json")).text());
+		return typeof pkg.version === "string" ? pkg.version : null;
+	} catch {
+		return null;
+	}
+}
+
+export async function hashTeamgbgJsGraph(
+	cwd: string,
+	h: ReturnType<typeof createHash>,
+): Promise<void> {
+	const roots = [
+		join(cwd, "src", "entry-client.ts"),
+		join(cwd, "src", "page-manifest.ts"),
+	].filter((p) => existsSync(p));
+	if (roots.length === 0) return; // backend service — no client bundle to guard
+
+	const seen = new Set<string>();
+	for (const r of roots) seen.add(r);
+	const fileHashes = new Map<string, string>(); // pkg-relative path → content hash
+	const thirdPartyVersions = new Map<string, string>(); // pkg name → installed version
+
+	let frontier: string[] = [...roots];
+	while (frontier.length > 0) {
+		const batch = frontier.splice(0, JS_GRAPH_CONCURRENCY);
+		const expanded = await Promise.all(
+			batch.map(async (file) => {
+				let text: string;
+				try {
+					text = await Bun.file(file).text();
+				} catch {
+					return [] as string[];
+				}
+				const nmIdx = file.indexOf("/node_modules/@teamscala/");
+				if (nmIdx >= 0) {
+					const rel = file.slice(nmIdx + "/node_modules/".length); // @teamscala/pkg/...
+					fileHashes.set(rel, createHash("sha256").update(text).digest("hex"));
+				}
+				const next: string[] = [];
+				for (const m of text.matchAll(JS_IMPORT_SPEC_RE)) {
+					let resolved: string;
+					try {
+						resolved = await Bun.resolve(m[1].trim(), dirname(file));
+					} catch {
+						continue;
+					}
+					const inNodeModules = resolved.includes("/node_modules/");
+					const isTeamgbg = resolved.includes("/node_modules/@teamscala/");
+					if (inNodeModules && !isTeamgbg) {
+						// Third-party closure boundary: stop the content walk (large,
+						// version-pinned packages) but record this dep's resolved VERSION
+						// so a closure version bump (react, …) still invalidates the
+						// fingerprint. The closure-scoped replacement for hashing all of
+						// bun.lock (`no-uncontrolled-repetition-or-cascade`). has()+set()
+						// straddle an await, so two concurrent imports of the same package
+						// can both read its version — idempotent (same value), so the
+						// folded result is deterministic regardless of scheduling.
+						const pkgName = nodeModulesPkgName(resolved);
+						if (pkgName && !thirdPartyVersions.has(pkgName)) {
+							const version = await readInstalledPkgVersion(resolved, pkgName);
+							// null = absent (unreadable package.json) — OMIT so a later
+							// successful read invalidates; never mask behind a placeholder
+							// (protective-layers-fail-explicitly). has() stays false → the
+							// read is re-attempted on the next import (cheap, bounded by
+							// closure size); a successful read sets + dedups.
+							if (version !== null) thirdPartyVersions.set(pkgName, version);
+						}
+						continue;
+					}
+					// Atomic dedup: check+add are synchronous (no await between), so on
+					// the single-threaded event loop only one task ever enqueues a path.
+					if (seen.has(resolved)) continue;
+					seen.add(resolved);
+					next.push(resolved);
+				}
+				return next;
+			}),
+		);
+		for (const arr of expanded) frontier.push(...arr);
+	}
+
+	for (const rel of [...fileHashes.keys()].sort()) {
+		h.update("tgjs:").update(rel).update("\0").update(fileHashes.get(rel) as string).update("\0");
+	}
+	// Fold the resolved versions of every third-party package at the closure
+	// boundary, sorted by name for determinism. This is the ONLY signal for
+	// third-party changes (their bodies are not content-walked); without it a
+	// react version bump in the closure would bake a stale bundle.
+	for (const name of [...thirdPartyVersions.keys()].sort()) {
+		h.update("tpv:").update(name).update("\0").update(thirdPartyVersions.get(name) as string).update("\0");
+	}
+}

package/src/build-client-assets/source-candidates.ts

@@ -0,0 +1,115 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Tailwind source-candidate scanning for the client CSS build.
+ *
+ * Split out of build-client-assets.ts (1221 lines, six concerns). Owns ONE
+ * concern: turning the resolved `@source` directories into the candidate token
+ * set Tailwind's `build()` consumes.
+ *
+ * Why it exists at all, preserved from the original: Tailwind v4's low-level
+ * `compile()` does NOT scan content, and @tailwindcss/oxide's native Scanner is
+ * not a dependency of the bare `tailwindcss` lib — only of the integration
+ * packages. So the tokens are extracted here. Over-extraction is safe, because
+ * `build()` ignores any token that is not a valid utility. Dropping this scan is
+ * what shipped an unstyled page to the operator's tablet on 2026-06-13; it is
+ * enforced by `css-build-scans-source-candidates`.
+ *
+ * Byte-for-byte move — imports adjusted, nothing else.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+// Tailwind v4's low-level `compile()` does NOT scan content — `compiler.build(
+// candidates)` only emits utilities for the candidate class names it is GIVEN.
+// `build([])` therefore emits ZERO content-driven utilities (only the static
+// theme/base + @utility/@layer + imported package CSS). The workspace's own
+// blocks mostly use inline styles + hand-written `blk-*` package classes
+// (no-tailwind-in-blocks / layout-properties-inline), so the missing utility
+// layer was invisible — until the Plate document editor (third-party shadcn
+// components using raw `flex`/`p-1`/`bg-background/95`) rendered completely
+// unstyled (operator's tablet, 2026-06-13). The CLI we replaced
+// (`b29e369` "in-process Bun compile") scanned content; the replacement dropped
+// the scan. This restores it: glob every resolved `@source` dir, extract
+// candidate tokens, and feed them to `build()`. @tailwindcss/oxide's native
+// Scanner is NOT a dependency of the bare `tailwindcss` lib (only of the
+// integration packages), so we tokenize ourselves — over-extraction is safe
+// (build() ignores any token that isn't a valid utility). Enforced by
+// `css-build-scans-source-candidates`.
+const SCAN_EXTS = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".html",
+	".md",
+	".mdx",
+]);
+// Class-name candidate chars: identifiers, variant `:`, opacity `/`, arbitrary
+// values `[]()`, decimals `.`, important `!`, plus `#%,&-` seen in arbitrary
+// values and modifiers. Deliberately broad — invalid tokens are dropped by build().
+const CANDIDATE_RE = /[A-Za-z0-9_:/[\].%#!,&-]+/g;
+
+export async function scanSourceCandidates(
+	sources: Array<{ base: string; pattern: string; negated?: boolean }>,
+	log: ReturnType<typeof getAppLogger>,
+): Promise<string[]> {
+	const candidates = new Set<string>();
+	for (const src of sources) {
+		if (src.negated) continue;
+		let root: string;
+		try {
+			root = resolve(src.base, src.pattern);
+		} catch {
+			continue;
+		}
+		// A resolved @source root absent on disk is benign: a published block
+		// package ships compiled output, not its src/ tree, so an `@source` into
+		// that package resolves to a non-existent dir. Skip silently rather than
+		// warn on every UI-service boot (the log-flood class — the ENOENT whose
+		// path rendered with a trailing null byte). Real errors below still warn.
+		if (!existsSync(root)) continue;
+		// A root INSIDE node_modules is an explicit `@source` into an installed
+		// block package (the app-css transform emits one per package) — scan it
+		// fully. A root OUTSIDE node_modules is the service's own tree — scan it
+		// but never descend into node_modules (the entire dependency graph).
+		const rootInNodeModules = root.includes("/node_modules/");
+		try {
+			const glob = new Bun.Glob("**/*");
+			for await (const file of glob.scan({
+				cwd: root,
+				absolute: true,
+				onlyFiles: true,
+			})) {
+				if (!rootInNodeModules && file.includes("/node_modules/")) continue;
+				if (file.includes("/dist/") || file.endsWith(".d.ts")) continue;
+				const dot = file.lastIndexOf(".");
+				if (dot < 0 || !SCAN_EXTS.has(file.slice(dot))) continue;
+				let text: string;
+				try {
+					text = await readFile(file, "utf-8");
+				} catch {
+					continue;
+				}
+				const matched = text.match(CANDIDATE_RE);
+				if (matched) for (const t of matched) candidates.add(t);
+			}
+		} catch (err) {
+			// A bad source dir never aborts the whole CSS build (the other
+			// sources still contribute their utilities).
+			log.warn(
+				`[build-client-assets] candidate scan skipped ${root}: ${
+					err instanceof Error ? err.message : String(err)
+				}`,
+			);
+		}
+	}
+	return [...candidates];
+}