@usequark/quark-create-app 1.23.11

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

@@ -0,0 +1,168 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+const CHARS = " .:-=+*#%@";
+const W = 110;
+const H = 55;
+
+const CONF = {
+	zoom: 1.16,
+	speed: 1.7,
+	dashLength: 16,
+	dashThickness: 2.8,
+	dashDistFactor: 0.36,
+	ringGapMultiplier: 0.3,
+	angleLimit: 0.3,
+	yBounce: 1,
+	ringRadius: 13,
+	ringThickness: 2.6,
+	yScaleFactor: 1.05,
+	dashAngle: 0.8,
+};
+
+// Fixed brand palette - all three colors are part of the Quark logo identity.
+const CLASS_COLORS = { s: "#2d3436", b: "#377dff", c: "#ff4757" };
+
+export default function QuarkAnimation() {
+	const ref = useRef(null);
+
+	useEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+
+		let t = 0;
+		let raf;
+
+		function render() {
+			t += 0.01 * CONF.speed;
+
+			const rY = Math.sin(t) * CONF.angleLimit;
+			const yO = Math.sin(t * 1.5) * CONF.yBounce;
+			const cB = new Array(W * H).fill(" ");
+			const clB = new Array(W * H).fill("");
+			const zB = new Float32Array(W * H).fill(-1000);
+
+			const rR = CONF.ringRadius * CONF.zoom;
+			const rT = CONF.ringThickness * CONF.zoom;
+			const dL = CONF.dashLength * CONF.zoom;
+			const dT = CONF.dashThickness * CONF.zoom;
+			const dA = CONF.dashAngle;
+			const gap = (dT / rR) * 0.8 + CONF.ringGapMultiplier;
+
+			// Ring (torus)
+			for (let p = 0; p < Math.PI * 2; p += 0.12) {
+				for (let th = 0; th < Math.PI * 2; th += 0.04) {
+					let d = Math.abs(th - dA);
+					if (d > Math.PI) d = 2 * Math.PI - d;
+					if (d < gap) continue;
+
+					const rXx = Math.cos(th);
+					const rYy = Math.sin(th);
+					const x = (rR + rT * Math.cos(p)) * rXx;
+					const y = (rR + rT * Math.cos(p)) * rYy * CONF.yScaleFactor;
+					const z = rT * Math.sin(p);
+
+					const rx = x * Math.cos(rY) + z * Math.sin(rY);
+					const rz = -x * Math.sin(rY) + z * Math.cos(rY);
+					const ry = y + yO;
+
+					const xp = Math.floor(W / 2 + rx * 1.5);
+					const yp = Math.floor(H / 2 + ry);
+
+					if (xp >= 0 && xp < W && yp >= 0 && yp < H) {
+						const i = yp * W + xp;
+						if (rz > zB[i]) {
+							zB[i] = rz;
+							const nT = ((th % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2);
+							const nD = ((dA % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2);
+							clB[i] = rYy < 0 ? "s" : nT > nD ? "b" : "c";
+							cB[i] =
+								CHARS[
+									Math.floor(
+										Math.max(0, Math.min(1, (rz + rT) / (rT * 2) + 0.3)) *
+											(CHARS.length - 1),
+									)
+								];
+						}
+					}
+				}
+			}
+
+			// Dash (quark)
+			for (let l = 0; l < dL; l += 0.6) {
+				for (let p = 0; p < Math.PI * 2; p += 0.2) {
+					for (let rad = 0; rad < dT; rad += 0.6) {
+						const sR = rR * CONF.dashDistFactor;
+						const lx = rad * Math.cos(p);
+						const ly = rad * Math.sin(p);
+						const lz = l;
+
+						const tx =
+							sR * Math.cos(dA) + lz * Math.cos(dA) - lx * Math.sin(dA);
+						const ty =
+							(sR * Math.sin(dA) + lz * Math.sin(dA) + lx * Math.cos(dA)) *
+							CONF.yScaleFactor;
+						const tz = ly;
+
+						const rtx = tx * Math.cos(rY) + tz * Math.sin(rY);
+						const rtz = -tx * Math.sin(rY) + tz * Math.cos(rY);
+						const rty = ty + yO;
+
+						const xp = Math.floor(W / 2 + rtx * 1.5);
+						const yp = Math.floor(H / 2 + rty);
+
+						if (xp >= 0 && xp < W && yp >= 0 && yp < H) {
+							const i = yp * W + xp;
+							if (rtz > zB[i]) {
+								zB[i] = rtz;
+								clB[i] = "c";
+								cB[i] =
+									CHARS[
+										Math.floor(
+											Math.max(0, Math.min(1, (rtz + dT) / (dT * 2) + 0.3)) *
+												(CHARS.length - 1),
+										)
+									];
+							}
+						}
+					}
+				}
+			}
+
+			// Build HTML string - inline colors avoid global CSS pollution
+			let o = "";
+			for (let i = 0; i < cB.length; i++) {
+				if (i > 0 && i % W === 0) o += "\n";
+				const cls = clB[i];
+				if (cls) {
+					o += `<span style="color:${CLASS_COLORS[cls]}">${cB[i]}</span>`;
+				} else {
+					o += cB[i];
+				}
+			}
+
+			el.innerHTML = o;
+			raf = requestAnimationFrame(render);
+		}
+
+		render();
+		return () => cancelAnimationFrame(raf);
+	}, []);
+
+	return (
+		<div
+			ref={ref}
+			style={{
+				lineHeight: "0.82",
+				letterSpacing: "0",
+				whiteSpace: "pre",
+				textAlign: "center",
+				fontSize: "11px",
+				fontWeight: "bold",
+				fontFamily: "monospace",
+				color: "#e0e0e0",
+			}}
+		/>
+	);
+}

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

@@ -0,0 +1,212 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import AsciiPanel from "./AsciiPanel.js";
+
+const INNER_W = 34;
+const TYPING_MS = 2000;
+const HOLD_MS = 5000;
+const UNTYPING_MS = 1500;
+const NUM_PANELS = 3;
+
+const PHASE_INITIAL_TYPING = 0;
+const PHASE_HOLD = 1;
+const PHASE_UNTYPE_0 = 2;
+const PHASE_TYPE_0 = 3;
+const PHASE_HOLD_AFTER_0 = 4;
+const PHASE_UNTYPE_1 = 5;
+const PHASE_TYPE_1 = 6;
+const PHASE_HOLD_AFTER_1 = 7;
+const PHASE_UNTYPE_2 = 8;
+const PHASE_TYPE_2 = 9;
+const PHASE_HOLD_AFTER_2 = 10;
+
+function wrapText(text, maxLen) {
+	const words = text.split(" ");
+	const lines = [];
+	let current = "";
+	for (const word of words) {
+		if (current.length + (current ? 1 : 0) + word.length > maxLen) {
+			if (current) lines.push(current);
+			current = word.length > maxLen ? word.slice(0, maxLen) : word;
+		} else {
+			current = current ? `${current} ${word}` : word;
+		}
+	}
+	if (current) lines.push(current);
+	return lines.length ? lines : [""];
+}
+
+function getContentLines(panel) {
+	const t = wrapText(panel.title, INNER_W);
+	const d = wrapText(panel.description, INNER_W);
+	return [...t, "", ...d];
+}
+
+function getMaxDisplayLines(panels) {
+	return Math.max(...panels.map((panel) => getContentLines(panel).length));
+}
+
+function getTotalChars(panel) {
+	const t = wrapText(panel.title, INNER_W);
+	const d = wrapText(panel.description, INNER_W);
+	return t.join("").length + d.join("").length;
+}
+
+const PHASE_DURATION = {
+	[PHASE_INITIAL_TYPING]: TYPING_MS,
+	[PHASE_HOLD]: HOLD_MS,
+	[PHASE_UNTYPE_0]: UNTYPING_MS,
+	[PHASE_TYPE_0]: TYPING_MS,
+	[PHASE_HOLD_AFTER_0]: HOLD_MS,
+	[PHASE_UNTYPE_1]: UNTYPING_MS,
+	[PHASE_TYPE_1]: TYPING_MS,
+	[PHASE_HOLD_AFTER_1]: HOLD_MS,
+	[PHASE_UNTYPE_2]: UNTYPING_MS,
+	[PHASE_TYPE_2]: TYPING_MS,
+	[PHASE_HOLD_AFTER_2]: HOLD_MS,
+};
+
+const NEXT_PHASE = {
+	[PHASE_INITIAL_TYPING]: PHASE_HOLD,
+	[PHASE_HOLD]: PHASE_UNTYPE_0,
+	[PHASE_UNTYPE_0]: PHASE_TYPE_0,
+	[PHASE_TYPE_0]: PHASE_HOLD_AFTER_0,
+	[PHASE_HOLD_AFTER_0]: PHASE_UNTYPE_1,
+	[PHASE_UNTYPE_1]: PHASE_TYPE_1,
+	[PHASE_TYPE_1]: PHASE_HOLD_AFTER_1,
+	[PHASE_HOLD_AFTER_1]: PHASE_UNTYPE_2,
+	[PHASE_UNTYPE_2]: PHASE_TYPE_2,
+	[PHASE_TYPE_2]: PHASE_HOLD_AFTER_2,
+	[PHASE_HOLD_AFTER_2]: PHASE_UNTYPE_0,
+};
+
+export default function SyncedPanels({ panels }) {
+	const [renderTick, setRenderTick] = useState(0);
+	const [copiedIdx, setCopiedIdx] = useState(-1);
+	const rafRef = useRef(null);
+
+	const stateRef = useRef({
+		phase: PHASE_INITIAL_TYPING,
+		phaseStart: 0,
+		started: false,
+		promptIdxs: [0, 1, 2],
+		charCounts: [0, 0, 0],
+		queue: Array.from({ length: panels.length }, (_, i) => i).slice(NUM_PANELS),
+	});
+
+	const maxLines = getMaxDisplayLines(panels.slice(0, NUM_PANELS));
+	const maxCharsRef = useRef(panels.map(getTotalChars));
+
+	useEffect(() => {
+		maxCharsRef.current = panels.map(getTotalChars);
+	}, [panels]);
+
+	useEffect(() => {
+		let active = true;
+
+		function tick(ts) {
+			if (!active) return;
+
+			const st = stateRef.current;
+			if (!st.started) {
+				st.started = true;
+				st.phaseStart = ts;
+			}
+
+			const elapsed = ts - st.phaseStart;
+			const duration = PHASE_DURATION[st.phase];
+			const t = Math.min(elapsed / duration, 1);
+			const p = panels;
+
+			const isTyping =
+				st.phase === PHASE_INITIAL_TYPING ||
+				st.phase === PHASE_TYPE_0 ||
+				st.phase === PHASE_TYPE_1 ||
+				st.phase === PHASE_TYPE_2;
+			const isUntyping =
+				st.phase === PHASE_UNTYPE_0 ||
+				st.phase === PHASE_UNTYPE_1 ||
+				st.phase === PHASE_UNTYPE_2;
+
+			const changingPanel =
+				st.phase === PHASE_UNTYPE_0 || st.phase === PHASE_TYPE_0
+					? 0
+					: st.phase === PHASE_UNTYPE_1 || st.phase === PHASE_TYPE_1
+						? 1
+						: st.phase === PHASE_UNTYPE_2 || st.phase === PHASE_TYPE_2
+							? 2
+							: -1;
+
+			for (let i = 0; i < NUM_PANELS; i++) {
+				if (isTyping && changingPanel === i) {
+					const maxChars =
+						maxCharsRef.current[st.promptIdxs[i] % p.length] || 1;
+					st.charCounts[i] = Math.floor(t * maxChars);
+				} else if (isUntyping && changingPanel === i) {
+					const maxChars =
+						maxCharsRef.current[st.promptIdxs[i] % p.length] || 1;
+					st.charCounts[i] = Math.floor((1 - t) * maxChars);
+				} else if (isTyping && changingPanel === -1) {
+					const maxChars =
+						maxCharsRef.current[st.promptIdxs[i] % p.length] || 1;
+					st.charCounts[i] = Math.floor(t * maxChars);
+				}
+			}
+
+			if (t >= 1) {
+				if (isUntyping && changingPanel >= 0) {
+					if (st.queue.length === 0) {
+						st.queue = Array.from({ length: p.length }, (_, i) => i).filter(
+							(idx) => !st.promptIdxs.includes(idx),
+						);
+					}
+					st.promptIdxs[changingPanel] = st.queue.shift();
+					st.charCounts[changingPanel] = 0;
+				}
+				st.phase = NEXT_PHASE[st.phase];
+				st.phaseStart = ts;
+			}
+
+			setRenderTick((n) => n + 1);
+			rafRef.current = requestAnimationFrame(tick);
+		}
+
+		rafRef.current = requestAnimationFrame(tick);
+		return () => {
+			active = false;
+			if (rafRef.current) cancelAnimationFrame(rafRef.current);
+		};
+	}, [panels]);
+
+	void renderTick;
+
+	function handleCopy(text, idx) {
+		navigator.clipboard.writeText(text);
+		setCopiedIdx(idx);
+		setTimeout(() => setCopiedIdx(-1), 1500);
+	}
+
+	const st = stateRef.current;
+	const p = panels;
+
+	return (
+		<div className="quark-home-panels">
+			{[0, 1, 2].map((i) => {
+				const panel = p[st.promptIdxs[i] % p.length];
+				return (
+					<AsciiPanel
+						key={`panel-${i}`}
+						title={panel.title}
+						description={panel.description}
+						prompt={panel.prompt}
+						charCount={st.charCounts[i]}
+						copied={copiedIdx === i}
+						onCopy={() => handleCopy(panel.prompt, i)}
+						maxLines={maxLines}
+					/>
+				);
+			})}
+		</div>
+	);
+}

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

@@ -0,0 +1,198 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useEffect, useEffectEvent, useRef } from "react";
+import { isUmamiStaff } from "../../lib/analytics/umami.js";
+import { getUmamiConfig } from "../../lib/analytics/umami-config.js";
+import {
+	buildReplayEndpoint,
+	createReplayBuffer,
+	getReplayMaskConfig,
+	postReplayBatch,
+	shouldSampleReplay,
+	UMAMI_REPLAY_DEFAULTS,
+	waitForUmamiSessionCache,
+} from "../../lib/analytics/umami-replay.js";
+
+const RRWEB_OPTIONS = {
+	inlineStylesheet: true,
+	slimDOMOptions: {
+		script: true,
+		comment: true,
+		headMetaDescKeywords: true,
+		headMetaSocial: true,
+		headMetaRobots: true,
+		headMetaHttpEquiv: true,
+		headMetaAuthorship: true,
+		headMetaVerification: true,
+	},
+	recordCanvas: false,
+	recordCrossOriginIframes: false,
+	checkoutEveryNms: 30000,
+};
+
+export default function UmamiReplayRecorder() {
+	const pathname = usePathname();
+	const previousPathnameRef = useRef(pathname);
+	const bufferRef = useRef(createReplayBuffer());
+	const cacheRef = useRef("");
+	const endpointRef = useRef("");
+	const websiteIdRef = useRef("");
+	const startedAtRef = useRef(0);
+	const isActiveRef = useRef(false);
+	const recordRef = useRef(null);
+	const stopRecordingRef = useRef(null);
+
+	const flushPendingEvents = useEffectEvent(
+		async ({ useKeepalive = false } = {}) => {
+			const events = bufferRef.current.drain();
+			if (!events.length) return false;
+
+			const sent = await postReplayBatch({
+				endpoint: endpointRef.current,
+				cache: cacheRef.current,
+				websiteId: websiteIdRef.current,
+				events,
+				useKeepalive,
+			});
+
+			if (!sent) {
+				bufferRef.current.restore(events);
+			}
+
+			return sent;
+		},
+	);
+
+	useEffect(() => {
+		const umamiConfig = getUmamiConfig();
+		if (!umamiConfig.replayEnabled || !shouldSampleReplay()) {
+			return undefined;
+		}
+
+		// Skip replay on admin pages and for any staff user (umami_user_role
+		// cookie set by admin layout via inline client script).
+		if (window.location.pathname.startsWith("/admin")) return undefined;
+		if (isUmamiStaff()) return undefined;
+
+		let cancelled = false;
+		const abortController = new AbortController();
+		let flushIntervalId = null;
+		let stopRecording = () => {};
+		let removeVisibilityListener = () => {};
+		let removePageHideListener = () => {};
+
+		async function setupReplay() {
+			const cache = await waitForUmamiSessionCache({
+				signal: abortController.signal,
+			});
+			if (cancelled || !cache) return;
+
+			const { record } = await import("rrweb");
+			if (cancelled) return;
+
+			cacheRef.current = cache;
+			endpointRef.current = buildReplayEndpoint(umamiConfig.url);
+			websiteIdRef.current = umamiConfig.websiteId;
+			startedAtRef.current = Date.now();
+
+			const stopRrweb = record({
+				emit(event) {
+					if (
+						Date.now() - startedAtRef.current >
+						UMAMI_REPLAY_DEFAULTS.maxDurationMs
+					) {
+						stopRecording();
+						return;
+					}
+
+					const eventCount = bufferRef.current.push(event);
+					if (eventCount >= UMAMI_REPLAY_DEFAULTS.flushEventCount) {
+						void flushPendingEvents();
+					}
+				},
+				...getReplayMaskConfig(),
+				...RRWEB_OPTIONS,
+				...(UMAMI_REPLAY_DEFAULTS.blockSelector
+					? { blockSelector: UMAMI_REPLAY_DEFAULTS.blockSelector }
+					: {}),
+			});
+
+			recordRef.current = record;
+			isActiveRef.current = true;
+			flushIntervalId = window.setInterval(() => {
+				void flushPendingEvents();
+			}, UMAMI_REPLAY_DEFAULTS.flushIntervalMs);
+
+			const handleVisibilityChange = () => {
+				if (document.visibilityState === "hidden") {
+					void flushPendingEvents({ useKeepalive: true });
+				}
+			};
+			const handlePageHide = () => {
+				void flushPendingEvents({ useKeepalive: true });
+			};
+
+			document.addEventListener("visibilitychange", handleVisibilityChange);
+			window.addEventListener("pagehide", handlePageHide);
+
+			removeVisibilityListener = () => {
+				document.removeEventListener(
+					"visibilitychange",
+					handleVisibilityChange,
+				);
+			};
+			removePageHideListener = () => {
+				window.removeEventListener("pagehide", handlePageHide);
+			};
+
+			const stopFn = ({ useKeepalive = false } = {}) => {
+				if (!isActiveRef.current) return;
+
+				isActiveRef.current = false;
+				if (flushIntervalId) {
+					clearInterval(flushIntervalId);
+					flushIntervalId = null;
+				}
+
+				removeVisibilityListener();
+				removePageHideListener();
+				stopRrweb();
+				recordRef.current = null;
+				void flushPendingEvents({ useKeepalive });
+			};
+			stopRecordingRef.current = stopFn;
+			stopRecording = stopFn;
+		}
+
+		void setupReplay();
+
+		return () => {
+			cancelled = true;
+			abortController.abort();
+			stopRecording({ useKeepalive: true });
+		};
+	}, []);
+
+	useEffect(() => {
+		if (previousPathnameRef.current === pathname) return;
+
+		previousPathnameRef.current = pathname;
+
+		// Stop recording if navigating into an admin page or if a staff
+		// cookie appears mid-session (e.g. after visiting /admin).
+		if (pathname.startsWith("/admin") || isUmamiStaff()) {
+			if (isActiveRef.current) {
+				stopRecordingRef.current?.({ useKeepalive: true });
+			}
+			return;
+		}
+
+		if (!isActiveRef.current || !recordRef.current) return;
+
+		void flushPendingEvents();
+		recordRef.current.takeFullSnapshot?.(true);
+	}, [pathname]);
+
+	return null;
+}

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

@@ -0,0 +1,39 @@
+"use client";
+
+import { useEffect } from "react";
+import { isUmamiStaff } from "../../lib/analytics/umami.js";
+import { getUmamiConfig } from "../../lib/analytics/umami-config.js";
+import { observeWebVitals } from "../../lib/analytics/umami-web-vitals.js";
+
+/**
+ * Client component that mounts the anonymous Core Web Vitals observer.
+ *
+ * Must be rendered inside the root layout's `<body>` so that
+ * `window` and `performance` APIs are available.
+ *
+ * Design:
+ *  - Noop when Umami analytics is not configured or when
+ *    the browser does not support PerformanceObserver.
+ *  - Observes LCP, FID, CLS, INP, and TTFB and dispatches
+ *    them as anonymous Umami custom events (event_type = 2).
+ *  - Zero PII — only metric name, value, rating, and sanitised
+ *    URL path are sent.
+ *  - Cleans up all observers on unmount.
+ */
+export default function UmamiWebVitals() {
+	useEffect(() => {
+		const config = getUmamiConfig();
+		if (!config.enabled) return;
+
+		// Skip web vitals dispatch for any staff user (identified by the
+		// umami_user_role cookie set by the admin layout).
+		if (isUmamiStaff()) return;
+
+		const stopObserving = observeWebVitals();
+		return () => {
+			stopObserving();
+		};
+	}, []);
+
+	return null;
+}

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

@@ -0,0 +1,7 @@
+import { handlers } from "@/lib/auth";
+import { normalizeAuthRequest } from "@/lib/normalize-auth-request";
+
+export const GET = (req, context) =>
+	handlers.GET(normalizeAuthRequest(req), context);
+export const POST = (req, context) =>
+	handlers.POST(normalizeAuthRequest(req), context);

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

@@ -0,0 +1,82 @@
+import { validateBody } from "@techstream/quark-core";
+import { user } from "@techstream/quark-db";
+import { importJWK, jwtVerify } from "jose";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { issueTokenPair } from "../../../../lib/jwt";
+import { handleError } from "../../error-handler";
+
+const appleAuthSchema = z.object({
+	identityToken: z.string().min(1),
+	nonce: z.string().optional(),
+});
+
+const APPLE_KEYS_URL = "https://appleid.apple.com/auth/keys";
+
+/**
+ * POST /api/auth/apple
+ * Verify Apple identity token and issue a custom JWT.
+ */
+export async function POST(request) {
+	try {
+		const { identityToken } = await validateBody(request, appleAuthSchema);
+
+		// Decode the JWT header to get the kid
+		const [headerB64] = identityToken.split(".");
+		const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
+
+		// Fetch Apple's public keys
+		const keysResponse = await fetch(APPLE_KEYS_URL);
+		const { keys } = await keysResponse.json();
+
+		// Find the matching key
+		const matchingKey = keys.find((k) => k.kid === header.kid);
+		if (!matchingKey) {
+			return NextResponse.json(
+				{ message: "Invalid Apple token: no matching key" },
+				{ status: 401 },
+			);
+		}
+
+		// Verify the token using Apple's public key
+		const publicKey = await importJWK(matchingKey, "RS256");
+
+		let payload;
+		try {
+			const result = await jwtVerify(identityToken, publicKey, {
+				issuer: "https://appleid.apple.com",
+			});
+			payload = result.payload;
+		} catch {
+			return NextResponse.json(
+				{ message: "Invalid Apple token" },
+				{ status: 401 },
+			);
+		}
+
+		const appleEmail = payload.email;
+		if (!appleEmail) {
+			return NextResponse.json(
+				{ message: "Apple token does not contain an email" },
+				{ status: 400 },
+			);
+		}
+
+		// Find or create user
+		let existingUser = await user.findByEmail(appleEmail);
+		if (!existingUser) {
+			existingUser = await user.create({
+				email: appleEmail,
+				name: payload.name
+					? `${payload.name.firstName || ""} ${payload.name.lastName || ""}`.trim()
+					: null,
+			});
+		}
+
+		const { token, refreshToken, expiresAt } =
+			await issueTokenPair(existingUser);
+		return NextResponse.json({ token, refreshToken, expiresAt });
+	} catch (error) {
+		return handleError(error);
+	}
+}