@usequark/quark-create-app 1.25.0 → 1.25.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.25.0",
+  "version": "1.25.2",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",

package/src/index.js

@@ -1530,6 +1530,10 @@ STORAGE_PROVIDER=local
 				__QUARK_SCOPE__: scope,
 				__QUARK_PROJECT_NAME__: projectName,
 				__QUARK_SCAFFOLD_DATE__: scaffoldDate,
+				// The web port is resolved in Step 9 (findAvailablePort), so the
+				// docs can point at the port the app will actually bind rather
+				// than always claiming 3000.
+				__QUARK_WEB_PORT__: String(webPort),
 				__QUARK_OPTIONAL_APPS__: optionalAppLines,
 				__QUARK_OPTIONAL_PACKAGES__: optionalBlock,
 				__QUARK_FEATURE_ROWS__: featureRows,

package/templates/base-project/MAIN.md

@@ -6,8 +6,7 @@
 
 1. `CLAUDE.md` - project rules and conventions (keep this updated)
 2. `docs/` - guides and walkthroughs
-3. `openapi.yaml` - API contract
-4. `.opencode/skills/` - embedded skills (how to build bookings, CRM, CMS, AI, and more on this project)
+3. `.opencode/skills/` - embedded skills (how to build bookings, CRM, CMS, AI, and more on this project)
 
 ## Quick start
 
@@ -18,4 +17,4 @@ pnpm db:migrate        # Apply migrations
 pnpm dev               # Start the app (and worker, if included)
 ```
 
-Open [http://localhost:3000](http://localhost:3000).
+Open [http://localhost:__QUARK_WEB_PORT__](http://localhost:__QUARK_WEB_PORT__).

package/templates/base-project/README.md

@@ -19,7 +19,7 @@ pnpm db:seed           # Seed the database (admin user + sample data)
 pnpm dev               # Start the app (and worker, if included)
 ```
 
-Open [http://localhost:3000](http://localhost:3000)
+Open [http://localhost:__QUARK_WEB_PORT__](http://localhost:__QUARK_WEB_PORT__)
 
 ## UI References
 

package/templates/base-project/apps/web/src/app/api/files/[id]/route.js

@@ -5,6 +5,8 @@
  */
 
 import {
+	ConflictError,
+	createLogger,
 	createStorage,
 	ForbiddenError,
 	NotFoundError,
@@ -15,16 +17,30 @@ import { NextResponse } from "next/server";
 import { requireAuth } from "@/lib/auth-middleware";
 import { handleError } from "../../error-handler";
 
+const logger = createLogger("files");
+
 /**
  * GET /api/files/[id]
- * Serve / download a file by its database ID.
- * Public endpoint (no auth required) - access control is by knowledge of ID.
+ * Serve / download a file by its database ID or its storage key.
+ * Public endpoint (no auth required) - access control is by knowledge of the
+ * identifier.
+ *
+ * Both identifier forms are accepted because `getAssetUrl()` in
+ * `@usequark/quark-core` builds `/api/files/<key>` from a storage key, and
+ * nothing in this app ever called it with anything else. Serving only by id
+ * made every URL that function produces a 404.
  */
 export async function GET(_request, { params }) {
 	try {
 		const { id } = await params;
 
-		const record = await file.findById(id);
+		// The two forms are disjoint: a cuid never contains "/", and a storage key
+		// always does (`<prefix>/<year>/<month>/<id>-<name>`). An id lookup that
+		// misses is followed by a key lookup, so the id path costs no extra query.
+		let record = await file.findById(id);
+		if (!record && id.includes("/")) {
+			record = await file.findByStorageKey(id);
+		}
 		if (!record) {
 			throw new NotFoundError("File not found");
 		}
@@ -35,7 +51,13 @@ export async function GET(_request, { params }) {
 		const headers = new Headers();
 		headers.set("Content-Type", contentType || record.mimeType);
 		headers.set("Content-Length", String(body.length));
-		headers.set("Cache-Control", "public, max-age=31536000, immutable");
+		// Bounded, not `immutable`. The URL carries no version segment and nothing
+		// in the path is content-addressed, so `immutable` (never revalidate for a
+		// year) was a promise this route cannot keep: any code path that reuses an
+		// identifier — admin tooling, a seed, a restore from backup — would leave
+		// every browser and CDN holding the old bytes indefinitely. A bounded
+		// max-age bounds that window instead.
+		headers.set("Cache-Control", "public, max-age=3600");
 
 		// Inline display for images; attachment download for everything else
 		const isImage = record.mimeType.startsWith("image/");
@@ -57,6 +79,20 @@ export async function GET(_request, { params }) {
 /**
  * DELETE /api/files/[id]
  * Delete a file. Only the uploader or an admin can delete.
+ *
+ * Order matters: the database row goes first, the storage object second.
+ *
+ * `File` has no incoming relations today, so nothing can make the row delete
+ * fail on a foreign key — but a future incoming relation with a restrictive
+ * `onDelete` will, and at that point this ordering is what keeps the storage
+ * object intact. The old order (storage, then row) destroyed the bytes first,
+ * so a refused row delete left a row pointing at a blob that no longer existed:
+ * unrecoverable, because the bytes are the only copy and they are already gone.
+ *
+ * `deleteIfPresent` also closes the concurrent-delete race. Two overlapping
+ * requests both pass the ownership check above; the row delete reports how many
+ * rows it removed, so only the request that actually removed the row goes on to
+ * delete the storage object. The loser returns 404 without touching storage.
  */
 export const DELETE = withCsrfProtection(async (_request, { params }) => {
 	try {
@@ -75,12 +111,42 @@ export const DELETE = withCsrfProtection(async (_request, { params }) => {
 			throw new ForbiddenError("You can only delete your own files");
 		}
 
-		// Remove from storage
-		const storage = createStorage();
-		await storage.delete(record.storageKey);
+		// Remove the database record first. This is the reversible step: if the
+		// storage delete below fails, we have an orphaned blob, which is junk but
+		// harmless. The reverse order risks a row whose bytes are already gone.
+		let deleted;
+		try {
+			({ count: deleted } = await file.deleteIfPresent(record.id));
+		} catch (error) {
+			// P2003: a foreign key still references this row. Reachable once File
+			// gains incoming relations; the storage object is untouched at this point.
+			if (error?.code === "P2003") {
+				throw new ConflictError("File is referenced and cannot be deleted");
+			}
+			throw error;
+		}
 
-		// Remove database record
-		await file.delete(record.id);
+		// count === 0 means a concurrent request already removed the row. It owns
+		// the storage cleanup; touching it here would race that request's delete.
+		if (deleted === 0) {
+			throw new NotFoundError("File not found");
+		}
+
+		// Row is gone, so the blob is now unreferenced. This is the irreversible
+		// step and deliberately last.
+		const storage = createStorage();
+		try {
+			await storage.delete(record.storageKey);
+		} catch (error) {
+			// The row is already deleted, so the delete as a whole succeeded from the
+			// caller's point of view. Reporting an error would be a lie the client
+			// cannot act on, and the leftover blob is recoverable via the existing
+			// orphaned-file cleanup job. Log it rather than swallow it.
+			logger.error("Failed to remove file from storage", {
+				fileId: record.id,
+				error: error?.message ?? String(error),
+			});
+		}
 
 		return NextResponse.json({ message: "File deleted" });
 	} catch (error) {

package/templates/base-project/apps/web/src/app/api/health/route.js

@@ -10,37 +10,39 @@
  * connection and produces a fresh connection storm on the dependency that was
  * already struggling. That turns a transient blip into a restart loop.
  * Callers that need a hard verdict should read `status`, not the status code.
+ *
+ * The probing itself lives in `@usequark/quark-core/health`. This route is the
+ * thin HTTP shell around it: it wires the app's probes in and renders the
+ * report. Projects hand-rolled their own copy of this orchestration, which is
+ * what the core module replaces.
  */
 
 import {
+	checkQueues,
+	checkStorage,
 	createLogger,
-	createStorage,
 	getRegisteredQueues,
 	pingRedis,
+	runHealthChecks,
 } from "@usequark/quark-core";
 import { pingDatabase } from "@usequark/quark-db";
 import { NextResponse } from "next/server";
 
 const logger = createLogger("health");
 
-/** Ceiling for the whole check (ms). */
-const HEALTH_CHECK_TIMEOUT = 5000;
-
-/** Ceiling for one dependency probe (ms). Clamped to the overall budget, so a
- * single probe can never outlive the request. */
-const PROBE_TIMEOUT = 3000;
-
-/** Message returned in place of a real error when NODE_ENV is production. */
-const GENERIC_MESSAGES = {
-	database: "Database unavailable",
-	redis: "Redis unavailable",
-	storage: "Storage unavailable",
-	queue: "Queue unavailable",
-};
-
 export async function GET() {
 	try {
-		const result = await runHealthChecks();
+		// `pingDatabase` is passed in rather than imported by the core module:
+		// `@usequark/quark-db` depends on `@usequark/quark-core`, so core cannot
+		// import it back without a cycle.
+		const result = await runHealthChecks({
+			probes: {
+				database: pingDatabase,
+				redis: pingRedis,
+				storage: checkStorage,
+				queues: () => checkQueues(getRegisteredQueues),
+			},
+		});
 
 		// Always 200 — see the module comment. An orchestrator restarting this
 		// service is what turns a dependency blip into an outage.
@@ -67,197 +69,3 @@ export async function GET() {
 		);
 	}
 }
-
-/**
- * Runs every dependency probe concurrently and aggregates the results.
- *
- * Concurrency matters as much as the deadlines: run sequentially, a 3s database
- * timeout plus a 3s Redis timeout exhausts the 5s budget before storage is even
- * attempted, and the whole request falls through to the give-up path.
- *
- * @returns {Promise<{ status: string, timestamp: string, durationMs: number, checks: Record<string, object> }>}
- */
-async function runHealthChecks() {
-	const startedAt = performance.now();
-
-	// Every probe is wrapped in settleProbe(), so this Promise.all cannot reject
-	// and cannot outlast the deadline.
-	const [database, redis, storage, queues] = await Promise.all([
-		settleProbe("database", () => pingDatabase()),
-		settleProbe("redis", () => pingRedis()),
-		// `provider` rides along on the error result so a failure still names the
-		// provider that failed — settleProbe owns the message redaction.
-		settleProbe("storage", checkStorage, {
-			provider: process.env.STORAGE_PROVIDER || "local",
-		}),
-		settleProbe("queues", checkQueues),
-	]);
-
-	const checks = { database, redis, storage };
-	if (queues) checks.queues = queues;
-
-	return {
-		// "degraded" means at least one dependency failed. Both this and "ok"
-		// answer 200 — see the module comment.
-		status: Object.values(checks).some(isFailing) ? "degraded" : "ok",
-		timestamp: new Date().toISOString(),
-		durationMs: Math.round(performance.now() - startedAt),
-		checks,
-	};
-}
-
-/**
- * Reports whether a check entry counts as a failure. Handles both a flat probe
- * result (`{ status: "error" }`) and the nested queue map, where the verdict
- * lives on each queue rather than on the map itself.
- *
- * @param {unknown} check
- * @returns {boolean}
- */
-function isFailing(check) {
-	if (!check || typeof check !== "object") return false;
-
-	// A flat probe result carries its own `status`. The nested queue map does
-	// not, so fall through to its entries.
-	if (typeof (/** @type {any} */ (check).status) === "string") {
-		return /** @type {any} */ (check).status === "error";
-	}
-
-	return Object.values(/** @type {Record<string, any>} */ (check)).some(
-		(entry) => entry?.status === "error",
-	);
-}
-
-/**
- * Runs one dependency probe with its own deadline and normalises every failure
- * mode — rejection, timeout, or a probe that never settles — into a result
- * object. Never throws, so callers can rely on `Promise.all` resolving.
- *
- * @param {string} name - Probe name, also the key under `checks`.
- * @param {() => Promise<object>} probe
- * @param {object} [context] - Fields to merge into the error result.
- * @returns {Promise<{ status: string } & Record<string, unknown>>}
- */
-async function settleProbe(name, probe, context = {}) {
-	// A probe that hangs must not hold up the aggregate, and must never outlive
-	// the overall budget. The timer is always cleared, so it never leaks.
-	let timer;
-	const deadline = new Promise((resolve) => {
-		timer = setTimeout(
-			() => resolve({ status: "error", message: `${name} check timed out` }),
-			Math.min(PROBE_TIMEOUT, HEALTH_CHECK_TIMEOUT),
-		);
-	});
-
-	try {
-		return withSafeMessage(name, await Promise.race([probe(), deadline]));
-	} catch (/** @type {any} */ error) {
-		return withSafeMessage(name, {
-			...context,
-			status: "error",
-			message: error?.message,
-		});
-	} finally {
-		clearTimeout(timer);
-	}
-}
-
-/**
- * Returns a check result whose message is safe to serve publicly.
- *
- * A probe can signal failure two ways — by rejecting, or by *resolving* with
- * `{ status: "error", message }`. Both are routed through here so neither can
- * bypass the redaction: `pingRedis` returned `{ status: "error" }` carrying the
- * raw `REDIS_URL`, so a normaliser that only handled rejections would have let
- * the password straight through.
- *
- * @param {string} name - Probe name.
- * @param {object} [result]
- * @returns {object}
- */
-function withSafeMessage(name, result) {
-	if (result?.status !== "error") return result;
-
-	const { message, ...rest } = result;
-	return { ...rest, status: "error", message: safeMessage(name, message) };
-}
-
-/**
- * Reduces a failure to a message safe to return from an unauthenticated route.
- *
- * Driver errors carry the connection string they failed on, so the raw text is
- * only echoed outside production. `pingRedis`/`pingDatabase` redact at the
- * source regardless; this is the second layer.
- *
- * @param {string} name - Probe name.
- * @param {string|Error} [source] - The failure message or the error itself.
- * @returns {string}
- */
-function safeMessage(name, source) {
-	if (process.env.NODE_ENV === "production") {
-		return GENERIC_MESSAGES[name] ?? "Check unavailable";
-	}
-
-	return source?.message ?? source ?? "Unknown error";
-}
-
-/**
- * Verifies storage is reachable and writable by writing then deleting a
- * small sentinel object. Uses whichever provider is configured via
- * STORAGE_PROVIDER (defaults to "local" when unset).
- * @returns {Promise<{ status: string, provider: string }>}
- */
-async function checkStorage() {
-	const provider = process.env.STORAGE_PROVIDER || "local";
-	const storage = createStorage();
-	const sentinelKey = ".health-check-sentinel";
-
-	await storage.put(sentinelKey, Buffer.from("ok"), {
-		contentType: "text/plain",
-	});
-	await storage.delete(sentinelKey);
-
-	return { status: "ok", provider };
-}
-
-/**
- * Reports queue depths. Only meaningful in a process that registered the
- * queues — the web app registers none, so this resolves to null and the key is
- * omitted from the response rather than reported as a false pass.
- *
- * @returns {Promise<Record<string, { status: string, waiting?: number, active?: number, failed?: number, message?: string }> | null>}
- */
-async function checkQueues() {
-	const registeredQueues = getRegisteredQueues();
-	if (registeredQueues.size === 0) return null;
-
-	const entries = [...registeredQueues.entries()];
-	const results = await Promise.allSettled(
-		entries.map(([, queue]) =>
-			Promise.all([
-				queue.getWaitingCount(),
-				queue.getActiveCount(),
-				queue.getFailedCount(),
-			]),
-		),
-	);
-
-	const queueChecks = {};
-
-	for (let i = 0; i < entries.length; i++) {
-		const [name] = entries[i];
-		const result = results[i];
-
-		if (result.status === "fulfilled") {
-			const [waiting, active, failed] = result.value;
-			queueChecks[name] = { status: "ok", waiting, active, failed };
-		} else {
-			queueChecks[name] = withSafeMessage("queue", {
-				status: "error",
-				message: result.reason?.message,
-			});
-		}
-	}
-
-	return queueChecks;
-}

package/templates/base-project/apps/web/src/app/layout.js

@@ -1,4 +1,5 @@
 import "./globals.css";
+import { ThemeProvider } from "@usequark/quark-ui";
 import {
 	THEME_ATTR,
 	THEME_STORAGE_KEY,
@@ -48,7 +49,11 @@ export default function RootLayout({ children }) {
 				) : null}
 			</head>
 			<body>
-				{children}
+				{/* ThemeProvider renders no markup. It publishes theme state to
+				    React consumers (useTheme/ThemeToggle) and syncs data-theme
+				    after hydration via useLayoutEffect, which is why it must
+				    coexist with the blocking script above rather than replace it. */}
+				<ThemeProvider>{children}</ThemeProvider>
 				{umamiConfig.enabled ? <UmamiWebVitals /> : null}
 				{umamiConfig.replayEnabled ? <UmamiReplayRecorder /> : null}
 			</body>

package/templates/base-project/packages/db/src/queries.js

@@ -283,6 +283,23 @@ export const file = {
 	delete: (id) => {
 		return prisma.file.delete({ where: { id } });
 	},
+	/**
+	 * Deletes a File row and reports whether this call was the one that removed
+	 * it.
+	 *
+	 * `delete()` throws P2025 when the row is already gone, which is the normal
+	 * outcome of two concurrent DELETEs of the same file and is not an error
+	 * worth surfacing. This returns `{ count }` instead so the caller can tell
+	 * "I deleted it" from "someone beat me to it" and skip the destructive
+	 * follow-up (removing the storage object) in the second case.
+	 *
+	 * A count of 1 means the caller owns the cleanup. Any incoming relation
+	 * added later still surfaces here as a P2003 foreign-key error, before the
+	 * storage object has been touched.
+	 */
+	deleteIfPresent: (id) => {
+		return prisma.file.deleteMany({ where: { id } });
+	},
 	deleteMany: (ids) => {
 		return prisma.file.deleteMany({ where: { id: { in: ids } } });
 	},

package/templates/base-project/scripts/run-tests.mjs

@@ -31,7 +31,18 @@ function collectTests(targetPath) {
 				continue;
 			}
 
-			if (!entry.isFile() || !entry.name.endsWith(".test.js")) {
+			// `*.integration-test.js` renders components through jsdom + react-dom,
+			// so it must be collected too. It was previously skipped, which meant
+			// those suites never ran in CI - a real gap, not a naming preference:
+			// every one of them passed locally but was invisible to the pipeline.
+			// Note the file suffix is `-integration-test.js`, so
+			// `*.integration.test.js` (a different, separately-excluded name) is
+			// still only picked up by the plain `.test.js` rule below.
+			if (
+				!entry.isFile() ||
+				(!entry.name.endsWith(".test.js") &&
+					!entry.name.endsWith(".integration-test.js"))
+			) {
 				continue;
 			}
 
@@ -49,6 +60,35 @@ function collectTests(targetPath) {
 
 const files = roots.flatMap((rootPath) => collectTests(path.resolve(rootPath)));
 
+/**
+ * Escapes glob metacharacters so `node --test` treats the path as a literal
+ * path rather than a pattern.
+ *
+ * Next.js dynamic route segments are directories of the form `[id]` and
+ * `[...slug]`, and `node --test` matches its file arguments as globs. An
+ * unescaped `[id]` is read as a character class matching a single `i` or `d`,
+ * so the path matches nothing. The failure is silent — the runner reports
+ * zero tests and exits 0 — which meant every test co-located in a dynamic
+ * segment (`api/files/[id]/route.test.js`, and `users/[id]` and
+ * `[...nextauth]` which have none) was collected here and then silently
+ * dropped at the `node --test` boundary.
+ *
+ * Only `[` and `]` need escaping: a literal `*`, `?`, `{`, `}`, `+`, `@` or
+ * `!` in a directory name is resolved as itself once no glob metacharacter
+ * remains to give it meaning. `[[]` and `[]]` are the character-class escapes
+ * for the literal characters; a backslash is *not* honoured here, so it
+ * silently fails to escape anything.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+function escapeGlobChars(filePath) {
+	// Single pass. Two `replaceAll` calls in sequence do not work: the `[` of
+	// `[[]` introduces a `]` that the second call then escapes again, yielding
+	// `[[[]]` for one literal `[`.
+	return filePath.replace(/[[\]]/g, (char) => (char === "[" ? "[[]" : "[]]"));
+}
+
 if (files.length === 0) {
 	// An empty suite is not a failure. `node --test` exits 0 when it matches no
 	// files, so exiting 1 here made a freshly scaffolded project fail its own
@@ -64,7 +104,7 @@ const result = spawnSync(
 		"tsx/esm",
 		"--experimental-test-module-mocks",
 		"--test",
-		...files,
+		...files.map(escapeGlobChars),
 	],
 	{
 		stdio: "inherit",

package/templates/ui/src/form-field.integration-test.js

@@ -57,7 +57,8 @@ test("FormField - renders label and input", async () => {
 	assert.ok(input, "should render an input");
 	assert.strictEqual(label.textContent, "Name");
 	assert.strictEqual(input.getAttribute("name"), "name");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - connects label to input via htmlFor/id", async () => {
@@ -76,7 +77,8 @@ test("FormField - connects label to input via htmlFor/id", async () => {
 	const input = container.querySelector("input");
 	assert.strictEqual(label.getAttribute("for"), "custom-id");
 	assert.strictEqual(input.getAttribute("id"), "custom-id");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - renders error message with role alert", async () => {
@@ -94,7 +96,8 @@ test("FormField - renders error message with role alert", async () => {
 	const errorEl = container.querySelector("[role='alert']");
 	assert.ok(errorEl, "should render an error element with role alert");
 	assert.strictEqual(errorEl.textContent, "Required");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - sets aria-invalid and aria-describedby when error present", async () => {
@@ -110,13 +113,127 @@ test("FormField - sets aria-invalid and aria-describedby when error present", as
 			}),
 		),
 	);
-	const wrapper = container.querySelector('[aria-invalid="true"]');
-	assert.ok(wrapper, "should set aria-invalid on wrapper");
-	const errorId = wrapper.getAttribute("aria-describedby");
-	assert.ok(errorId, "should set aria-describedby");
+	const input = container.querySelector("input");
+	assert.ok(input, "should render an input");
+	assert.strictEqual(
+		input.getAttribute("aria-invalid"),
+		"true",
+		"aria-invalid must be on the focusable control",
+	);
+	assert.ok(
+		!container.querySelector("div[aria-invalid]"),
+		"aria-invalid on a non-interactive wrapper has no effect",
+	);
+	const errorId = input.getAttribute("aria-describedby");
+	assert.ok(errorId, "should set aria-describedby on the input");
+	assert.strictEqual(errorId, "email-field-error");
 	const errorEl = container.querySelector(`#${errorId}`);
 	assert.ok(errorEl, "aria-describedby should point to existing error element");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - applies className to the control, not the wrapper", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(FormField, {
+				label: "Name",
+				name: "name",
+				className: "w-72",
+			}),
+		),
+	);
+	const input = container.querySelector("input");
+	assert.match(input.getAttribute("class"), /\bw-72\b/);
+	assert.doesNotMatch(
+		container.firstElementChild.getAttribute("class"),
+		/\bw-72\b/,
+		"className targets the control; the wrapper is layout-only",
+	);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - wrapperClassName styles the layout container", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(FormField, {
+				label: "Name",
+				name: "name",
+				wrapperClassName: "sm:col-span-2",
+			}),
+		),
+	);
+	assert.match(
+		container.firstElementChild.getAttribute("class"),
+		/\bsm:col-span-2\b/,
+	);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - forwards error ARIA to a custom child control", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(
+				FormField,
+				{ label: "Bio", name: "bio", error: "Too short", id: "bio" },
+				createElement("textarea", { id: "bio", "data-testid": "custom" }),
+			),
+		),
+	);
+	const textarea = container.querySelector("textarea");
+	assert.strictEqual(textarea.getAttribute("aria-invalid"), "true");
+	assert.strictEqual(textarea.getAttribute("aria-describedby"), "bio-error");
+	assert.ok(
+		container.querySelector("#bio-error"),
+		"describedby target must exist",
+	);
+	assert.strictEqual(
+		textarea.getAttribute("name"),
+		"bio",
+		"name should be forwarded to the custom control",
+	);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - preserves a custom child's own className", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(
+				FormField,
+				{ label: "Bio", name: "bio", className: "h-40" },
+				createElement("textarea", { className: "resize-y" }),
+			),
+		),
+	);
+	const cls = container.querySelector("textarea").getAttribute("class");
+	assert.match(cls, /\bresize-y\b/);
+	assert.match(cls, /\bh-40\b/);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - leaves aria-invalid off when there is no error", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(createElement(FormField, { label: "Name", name: "name" })),
+	);
+	const input = container.querySelector("input");
+	assert.strictEqual(input.getAttribute("aria-invalid"), null);
+	assert.strictEqual(input.getAttribute("aria-describedby"), null);
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - renders children instead of default input", async () => {
@@ -138,5 +255,6 @@ test("FormField - renders children instead of default input", async () => {
 		null,
 		"should not render default input",
 	);
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });

package/templates/ui/src/form-field.js

@@ -3,12 +3,33 @@ import React, { useId } from "react";
 import { Input } from "./input.js";
 import { Label } from "./label.js";
 
+/**
+ * Label + control + error message, wired together for accessibility.
+ *
+ * `className` is applied to the control, matching every other component in this
+ * package (`Input`, `Textarea`, `Select`, `Card`, …), where it extends the
+ * component's own root element. Use `wrapperClassName` to style the layout
+ * container instead.
+ *
+ * The error association (`aria-invalid` / `aria-describedby`) always lands on
+ * the focusable control, never on a wrapper element, so a screen reader that is
+ * sitting on the control actually announces it.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} [props.label]
+ * @param {string} [props.name]
+ * @param {string} [props.error]
+ * @param {React.ReactNode} [props.children] custom control, e.g. a <Textarea>
+ * @param {string} [props.className] classes for the control
+ * @param {string} [props.wrapperClassName] classes for the layout container
+ */
 export function FormField({
 	label,
 	name,
 	error,
 	children,
 	className = "",
+	wrapperClassName = "",
 	...props
 }) {
 	const generatedId = useId();
@@ -16,25 +37,44 @@ export function FormField({
 
 	const errorId = `${fieldId}-error`;
 
-	const inputProps = { id: fieldId, name, ...props };
-	if (error) {
-		inputProps["aria-invalid"] = true;
-		inputProps["aria-describedby"] = errorId;
-	}
+	const ariaProps = error
+		? { "aria-invalid": true, "aria-describedby": errorId }
+		: {};
 
-	const childrenWrapperProps = {};
-	if (error) {
-		childrenWrapperProps["aria-invalid"] = true;
-		childrenWrapperProps["aria-describedby"] = errorId;
-	}
+	const control = children
+		? // A caller-supplied control already owns its own markup; forward the
+			// accessibility wiring to it so the attributes land on the element
+			// that can receive focus. Explicit props on the child win, so a
+			// caller can still override them.
+			React.Children.map(children, (child) => {
+				if (!React.isValidElement(child)) return child;
+				const merged = [child.props.className, className]
+					.filter(Boolean)
+					.join(" ");
+				return React.cloneElement(child, {
+					id: child.props.id ?? fieldId,
+					name: child.props.name ?? name,
+					// Omitted entirely when empty so a bare child is not given a
+					// meaningless class="" attribute.
+					...(merged ? { className: merged } : {}),
+					...ariaProps,
+				});
+			})
+		: React.createElement(Input, {
+				id: fieldId,
+				name,
+				className,
+				...ariaProps,
+				...props,
+			});
 
 	return React.createElement(
 		"div",
-		{ className: `min-w-0 space-y-1.5 ${className}`.trim() },
+		{
+			className: `min-w-0 space-y-1.5 ${wrapperClassName}`.trim(),
+		},
 		label ? React.createElement(Label, { htmlFor: fieldId }, label) : null,
-		children
-			? React.createElement("div", childrenWrapperProps, children)
-			: React.createElement(Input, inputProps),
+		control,
 		error
 			? React.createElement(
 					"p",

package/templates/ui/src/lightbox.integration-test.js

@@ -56,7 +56,8 @@ test("Lightbox - renders nothing when closed", async () => {
 	const root = createRoot(container);
 	await act(() => root.render(createElement(Lightbox, { open: false })));
 	assert.strictEqual(container.innerHTML, "");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - renders overlay when open", async () => {
@@ -76,7 +77,8 @@ test("Lightbox - renders overlay when open", async () => {
 	assert.ok(img, "should render an img element");
 	assert.strictEqual(img.getAttribute("src"), "/test.jpg");
 	assert.strictEqual(img.getAttribute("alt"), "Test image");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - calls onClose when close button clicked", async () => {
@@ -100,7 +102,8 @@ test("Lightbox - calls onClose when close button clicked", async () => {
 	assert.ok(closeBtn, "should have a close button");
 	await act(() => closeBtn.click());
 	assert.ok(closed, "onClose should be called");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - shows prev/next buttons and counter", async () => {
@@ -127,7 +130,8 @@ test("Lightbox - shows prev/next buttons and counter", async () => {
 	);
 	assert.ok(container.textContent.includes("Next"), "should show Next button");
 	assert.ok(container.textContent.includes("2 / 5"), "should show counter");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - calls onPrevious and onNext on button clicks", async () => {
@@ -163,5 +167,6 @@ test("Lightbox - calls onPrevious and onNext on button clicks", async () => {
 	assert.ok(prev, "onPrevious should be called");
 	await act(() => nextBtn.click());
 	assert.ok(next, "onNext should be called");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });

package/templates/ui/src/theme.js

@@ -13,7 +13,11 @@ import {
 	THEME_STORAGE_KEY,
 } from "./theme-constants.js";
 
-const ThemeCtx = createContext({ theme: "dark", setTheme: () => {} });
+// `undefined` means "no ThemeProvider above this consumer". It must not be a
+// usable default: a plausible-looking default ({ theme, setTheme: noop }) turns a
+// missing provider into a silently broken toggle that still renders and still
+// reports a theme. See useTheme().
+const ThemeCtx = createContext(undefined);
 
 /**
  * Wraps a subtree with a shared theme value.
@@ -90,18 +94,29 @@ export function ThemeProvider({ defaultTheme, children }) {
 
 /**
  * Returns the current theme and a setter from the nearest ThemeProvider.
- * Falls back to `{ theme: 'dark' }` when used outside a provider.
+ *
+ * Throws when there is no ThemeProvider above the caller. A missing provider is
+ * a wiring bug, not a state to default: `ThemeToggle` renders a labelled,
+ * focusable button either way, so a silent fallback yields a control that looks
+ * real, reports the wrong theme, and does nothing when clicked.
  *
  * @returns {{ theme: 'light' | 'dark', setTheme: (t: string) => void }}
+ * @throws {Error} if called outside a ThemeProvider
  */
 export function useTheme() {
-	return useContext(ThemeCtx);
+	const ctx = useContext(ThemeCtx);
+	if (ctx === undefined) {
+		throw new Error(
+			"useTheme() must be used within a ThemeProvider. Wrap your app in <ThemeProvider> (import it from @scope/ui) around the tree containing this component.",
+		);
+	}
+	return ctx;
 }
 
 /**
  * Labeled pill button that shows the current theme and switches on click.
  * Displays "🌙 Dark Mode" when dark, "☀ Light Mode" when light.
- * Must be rendered inside a ThemeProvider.
+ * Must be rendered inside a ThemeProvider — outside one, `useTheme()` throws.
  */
 export function ThemeToggle({ className = "" }) {
 	const { theme, setTheme } = useTheme();

package/templates/worker/src/handlers/files.js

@@ -37,8 +37,16 @@ export async function handleCleanupOrphanedFiles(bullJob, logger) {
 
 	for (const record of orphaned) {
 		try {
+			// Row first, storage second — same ordering as DELETE /api/files/[id].
+			// Storage-first means a failed row delete leaves a row pointing at bytes
+			// that are already gone, which cannot be recovered: the blob was the only
+			// copy. A failed storage delete here leaves an orphaned blob instead, and
+			// this very job is what sweeps those up on a later pass.
+			const { count } = await file.deleteIfPresent(record.id);
+			// A concurrent request (or an earlier pass of this job) already took it.
+			if (count === 0) continue;
+
 			await storage.delete(record.storageKey);
-			await file.delete(record.id);
 			deleted++;
 		} catch (err) {
 			errors.push({ id: record.id, error: err.message });