codebay 0.0.1 → 0.2.1

package/src/routes.ts

@@ -0,0 +1,444 @@
+import {
+	Mochi,
+	apiError,
+	error,
+	fail,
+	json,
+	success,
+	type MochiApiEvent,
+	type MochiRouteValue
+} from 'mochi-framework';
+import { dockerArch, dockerAvailable, pruneBuildCache } from './lib/docker.server.ts';
+import { devcontainerCliAvailable } from './lib/devcontainer.server.ts';
+import { resolveInjections } from './lib/injections.server.ts';
+import {
+	DEFAULT_HAIKU_MODEL,
+	DEFAULT_MODEL,
+	DEFAULT_OPUS_MODEL,
+	DEFAULT_SMALL_FAST_MODEL,
+	DEFAULT_SONNET_MODEL
+} from './container-injections/claude-code-custom.ts';
+import { hostEnvVarPresence, parseHostEnvVarNames } from './container-injections/host-env-vars.ts';
+import { browse } from './lib/picker.server.ts';
+import { pickNamePrompt } from './avatars/name-prompts.ts';
+import {
+	addForwardedPort,
+	createInstance,
+	deleteAllInstances,
+	deleteDatabaseAndShutdown,
+	deleteInstance,
+	listInstances,
+	rebuildInstance,
+	rebuildRunningInstancesNoCache,
+	removeForwardedPort,
+	renameInstance,
+	sanitizeInstance,
+	startInstance,
+	stopInstance,
+	streamClose,
+	streamOpen,
+	subscribeLogs
+} from './lib/instances.server.ts';
+import {
+	deleteFolderHistory,
+	getInstance,
+	getOption,
+	listFolderHistory,
+	setOption
+} from './lib/db.server.ts';
+import { APP_VERSION, DEFAULT_COPY_IGNORE, DEFAULT_IMAGE } from './lib/config.server.ts';
+import { wsUpgradeAllowed } from './lib/auth.server.ts';
+import { clearAttention, setAttention } from './lib/bridge.server.ts';
+import { timingSafeEqualStr } from './lib/crypto.server.ts';
+import { proxyRoutes } from './lib/proxy.server.ts';
+
+async function preflight() {
+	const [docker, cli, auth] = await Promise.all([
+		dockerAvailable(),
+		devcontainerCliAvailable(),
+		// Driven off the registry, so adding an injection extends the setup UI for free.
+		Promise.all(
+			resolveInjections()
+				.filter((i) => i.auth)
+				.map(async (i) => {
+					const status = await i.auth!.status();
+					return {
+						id: i.id,
+						label: i.label,
+						available: status.available,
+						source: status.source,
+						hint: i.auth!.hint
+					};
+				})
+		)
+	]);
+	return { docker, cli, auth };
+}
+
+/** Lets a route handler just `throw` for both validation and business-logic failures. */
+async function mutate(fn: () => Promise<unknown> | unknown): Promise<Response> {
+	try {
+		return json(await fn());
+	} catch (err) {
+		return apiError(400, (err as Error).message);
+	}
+}
+
+/** Always answers 200 on success, so the one route needing a 201 is written out by hand. */
+function mutationRoute(
+	method: 'POST' | 'DELETE',
+	handler: (event: MochiApiEvent) => Promise<unknown> | unknown
+) {
+	return Mochi.api((event) => {
+		if (event.method !== method) return apiError(405, 'Method Not Allowed');
+		return mutate(() => handler(event));
+	});
+}
+
+function str(formData: FormData, key: string): string {
+	return String(formData.get(key) ?? '').trim();
+}
+
+/** An unchecked box is omitted from the form entirely, so presence is the only signal. */
+function onChecked(formData: FormData, key: string): boolean {
+	return formData.get(key) === 'on';
+}
+
+export const routes: Record<string, MochiRouteValue> = {
+	// Dashboard and IDE share one shell so navigating between them keeps the iframes mounted;
+	// `snapshot` seeds the live list so neither renders a loading flash first.
+	'/': Mochi.page('./src/pages/App.svelte', {
+		serverProps: async () => ({
+			preflight: await preflight(),
+			initialPath: '/',
+			snapshot: await listInstances()
+		})
+	}),
+
+	'/ide/:id': Mochi.page('./src/pages/App.svelte', {
+		serverProps: async (_req, params) => {
+			if (!params.id || !getInstance(params.id)) error(404, 'Instance not found');
+			return {
+				preflight: await preflight(),
+				initialPath: `/ide/${params.id}`,
+				snapshot: await listInstances()
+			};
+		}
+	}),
+
+	'/instances/:id': Mochi.page('./src/pages/Instance.svelte', {
+		serverProps: (_req, params) => {
+			// Only validates existence — the view hydrates its data from the stream.
+			if (!params.id || !getInstance(params.id)) error(404, 'Instance not found');
+			// Lets the health panel's skeleton render one row per real check before the first snapshot.
+			return { id: params.id, injectionChecks: resolveInjections().filter((i) => i.check).length };
+		},
+		actions: {
+			restart: ({ params }) => {
+				try {
+					rebuildInstance(params.id!);
+				} catch (err) {
+					return fail(400, { error: (err as Error).message });
+				}
+				return success({});
+			}
+		}
+	}),
+
+	// Reached from the settings page's coin. The name hint is rolled here rather than in
+	// the editor so hydration can't re-roll it and swap the word out mid-load.
+	'/avatars': Mochi.page('./src/pages/Avatars.svelte', {
+		serverProps: () => ({ namePlaceholder: pickNamePrompt() })
+	}),
+
+	// Settings mutations are Form actions rather than JSON routes, so each control
+	// still works without JS and `enhance` only upgrades it.
+	'/settings': Mochi.page('./src/pages/Settings.svelte', {
+		serverProps: async () => {
+			// Only names ever reach the client; presence is sent separately, values never.
+			const hostEnvVarNames = parseHostEnvVarNames(getOption('host_env_var_names'));
+			return {
+				defaultImage: getOption('default_image') ?? DEFAULT_IMAGE,
+				builtinImage: DEFAULT_IMAGE,
+				disableBuildCache: getOption('disable_build_cache') === '1',
+				// An explicit empty string (as opposed to unset) means "copy everything".
+				copyIgnorePatterns: getOption('copy_ignore_patterns') ?? DEFAULT_COPY_IGNORE,
+				builtinCopyIgnore: DEFAULT_COPY_IGNORE,
+				dockerArch: await dockerArch(),
+				// Only whether each token is set — the page renders a placeholder from that.
+				manualTokensEnabled: getOption('manual_tokens_enabled') === '1',
+				githubTokenSet: !!getOption('manual_github_token'),
+				claudeTokenSet: !!getOption('manual_claude_code_token'),
+				// Custom endpoint (LiteLLM / Bedrock): toggle state, base URL (non-secret),
+				// whether the token is set (never the secret value), and model IDs prefilled
+				// from the module defaults when not yet customised.
+				customEndpointEnabled: getOption('custom_endpoint_enabled') === '1',
+				customEndpointBaseUrl: getOption('custom_endpoint_base_url') ?? '',
+				customEndpointTokenSet: !!getOption('custom_endpoint_token')?.trim(),
+				customEndpointOpusModel: getOption('custom_endpoint_opus_model') ?? DEFAULT_OPUS_MODEL,
+				customEndpointSonnetModel:
+					getOption('custom_endpoint_sonnet_model') ?? DEFAULT_SONNET_MODEL,
+				customEndpointHaikuModel: getOption('custom_endpoint_haiku_model') ?? DEFAULT_HAIKU_MODEL,
+				customEndpointSmallFastModel:
+					getOption('custom_endpoint_small_fast_model') ?? DEFAULT_SMALL_FAST_MODEL,
+				customEndpointModel: getOption('custom_endpoint_model') ?? DEFAULT_MODEL,
+				hostEnvVarsEnabled: getOption('host_env_vars_enabled') === '1',
+				hostEnvVarNames,
+				hostEnvVarPresence: hostEnvVarPresence(hostEnvVarNames),
+				version: APP_VERSION
+			};
+		},
+		actions: {
+			// Persist the default container image used when a source folder ships no devcontainer.json.
+			defaultImage: ({ formData }) => {
+				const image = str(formData, 'image');
+				if (!image) return fail(400, { error: 'image is required' });
+				setOption('default_image', image);
+				return success({ image });
+			},
+
+			disableBuildCache: ({ formData }) => {
+				const enabled = onChecked(formData, 'enabled');
+				setOption('disable_build_cache', enabled ? '1' : '0');
+				return success({ enabled });
+			},
+
+			// Unlike defaultImage, an empty value is valid — it means "copy everything".
+			copyIgnorePatterns: ({ formData }) => {
+				const patterns = str(formData, 'patterns');
+				setOption('copy_ignore_patterns', patterns);
+				return success({ patterns });
+			},
+
+			// Tokens are stored plaintext in the options table and never sent back to the client.
+			manualTokensToggle: ({ formData }) => {
+				const enabled = onChecked(formData, 'enabled');
+				setOption('manual_tokens_enabled', enabled ? '1' : '0');
+				return success({ enabled });
+			},
+			githubToken: ({ formData }) => {
+				const value = str(formData, 'githubToken');
+				setOption('manual_github_token', value);
+				return success({ set: value.length > 0 });
+			},
+			claudeToken: ({ formData }) => {
+				const value = str(formData, 'claudeToken');
+				setOption('manual_claude_code_token', value);
+				return success({ set: value.length > 0 });
+			},
+
+			customEndpointToggle: ({ formData }) => {
+				const enabled = onChecked(formData, 'enabled');
+				setOption('custom_endpoint_enabled', enabled ? '1' : '0');
+				return success({ enabled });
+			},
+			customBaseUrl: ({ formData }) => {
+				const value = str(formData, 'baseUrl');
+				setOption('custom_endpoint_base_url', value);
+				return success({ set: value.length > 0 });
+			},
+			customToken: ({ formData }) => {
+				const value = str(formData, 'token');
+				setOption('custom_endpoint_token', value);
+				return success({ set: value.length > 0 });
+			},
+			customModels: ({ formData }) => {
+				setOption('custom_endpoint_opus_model', str(formData, 'opusModel'));
+				setOption('custom_endpoint_sonnet_model', str(formData, 'sonnetModel'));
+				setOption('custom_endpoint_haiku_model', str(formData, 'haikuModel'));
+				setOption('custom_endpoint_small_fast_model', str(formData, 'smallFastModel'));
+				setOption('custom_endpoint_model', str(formData, 'defaultModel'));
+				return success({});
+			},
+
+			// Only names are stored; a value is never persisted nor accepted from the client.
+			hostEnvVarsToggle: ({ formData }) => {
+				const enabled = onChecked(formData, 'enabled');
+				setOption('host_env_vars_enabled', enabled ? '1' : '0');
+				const names = parseHostEnvVarNames(getOption('host_env_var_names'));
+				return success({ enabled, presence: hostEnvVarPresence(names) });
+			},
+			// Replaces the whole list, so both the add and remove forms post every name they want kept.
+			hostEnvVarNames: ({ formData }) => {
+				const raw = formData.getAll('names').map(String);
+				const names = [...new Set(raw.map((n) => n.trim()))].filter(Boolean);
+				for (const name of names) {
+					if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+						return fail(400, { error: `invalid variable name: ${name}` });
+					}
+				}
+				setOption('host_env_var_names', JSON.stringify(names));
+				const saved = parseHostEnvVarNames(getOption('host_env_var_names'));
+				return success({ presence: hostEnvVarPresence(saved) });
+			},
+
+			clearBuildCache: async () => {
+				const { spaceReclaimed } = await pruneBuildCache();
+				return success({ spaceReclaimed: spaceReclaimed ?? 0 });
+			},
+
+			rebuildAllNoCache: () => success({ count: rebuildRunningInstancesNoCache() }),
+
+			// The process exits mid-flight, so the client may see success or a dropped
+			// connection; SettingsView treats both as "shutting down".
+			shutdown: async () => {
+				await deleteDatabaseAndShutdown();
+				return success({});
+			}
+		}
+	}),
+
+	'/api/browse': Mochi.api(async ({ url }) => {
+		try {
+			return json(await browse(url.searchParams.get('path') ?? undefined));
+		} catch (err) {
+			return apiError(400, (err as Error).message);
+		}
+	}),
+
+	'/api/stream': Mochi.ws({
+		// Mochi.ws routes bypass the global basicAuth handle, so enforce origin + auth here.
+		upgrade: (req) => (wsUpgradeAllowed(req) ? {} : false),
+		open: streamOpen,
+		message: () => {},
+		close: streamClose
+	}),
+
+	'/api/instances': Mochi.api(async ({ method, request }) => {
+		if (method === 'GET') return json({ instances: await listInstances() });
+		if (method === 'POST') {
+			const body = (await request.json().catch(() => null)) as {
+				sourcePath?: string;
+				name?: string;
+				branch?: string;
+			} | null;
+			if (!body?.sourcePath) return apiError(400, 'sourcePath is required');
+			try {
+				const instance = await createInstance(body.sourcePath, body.name, { branch: body.branch });
+				return json({ instance: sanitizeInstance(instance) }, { status: 201 });
+			} catch (err) {
+				return apiError(400, (err as Error).message);
+			}
+		}
+		return apiError(405, 'Method Not Allowed');
+	}),
+
+	'/api/history': Mochi.api(async ({ method, request }) => {
+		if (method === 'GET') return json({ history: listFolderHistory() });
+		if (method === 'DELETE') {
+			return mutate(async () => {
+				const body = (await request.json().catch(() => null)) as { sourcePath?: string } | null;
+				if (!body?.sourcePath) throw new Error('sourcePath is required');
+				deleteFolderHistory(body.sourcePath);
+				return { ok: true };
+			});
+		}
+		return apiError(405, 'Method Not Allowed');
+	}),
+
+	'/api/instances/delete-all': mutationRoute('POST', async () => {
+		await deleteAllInstances();
+		return { ok: true };
+	}),
+
+	'/api/instances/:id/rename': mutationRoute('POST', async ({ params, request }) => {
+		const body = (await request.json().catch(() => null)) as { name?: string } | null;
+		if (!body?.name) throw new Error('name is required');
+		return { instance: sanitizeInstance(renameInstance(params.id!, body.name)) };
+	}),
+
+	// Both port routes only mutate the persisted set; /rebuild is what applies it.
+	'/api/instances/:id/ports': mutationRoute('POST', async ({ params, request }) => {
+		const body = (await request.json().catch(() => null)) as { port?: number } | null;
+		if (typeof body?.port !== 'number') throw new Error('port (number) is required');
+		return { instance: sanitizeInstance(await addForwardedPort(params.id!, body.port)) };
+	}),
+
+	'/api/instances/:id/ports/:port': mutationRoute('DELETE', ({ params }) => {
+		const port = Number.parseInt(params.port!, 10);
+		if (!Number.isInteger(port)) throw new Error('Invalid port');
+		return { instance: sanitizeInstance(removeForwardedPort(params.id!, port)) };
+	}),
+
+	'/api/instances/:id/rebuild': mutationRoute('POST', ({ params }) => ({
+		instance: sanitizeInstance(rebuildInstance(params.id!))
+	})),
+
+	'/api/instances/:id/start': mutationRoute('POST', async ({ params }) => ({
+		instance: sanitizeInstance(await startInstance(params.id!))
+	})),
+
+	'/api/instances/:id/stop': mutationRoute('POST', async ({ params }) => ({
+		instance: sanitizeInstance(await stopInstance(params.id!))
+	})),
+
+	'/api/instances/:id/delete': mutationRoute('POST', async ({ params }) => {
+		await deleteInstance(params.id!);
+		return { ok: true };
+	}),
+
+	'/api/instances/:id/attention/clear': mutationRoute('POST', ({ params }) => {
+		clearAttention(params.id!);
+		return { ok: true };
+	}),
+
+	// Token-authed instead of Basic Auth (see auth.server.ts); the token rides in a
+	// header rather than the query string so it stays out of request logs.
+	'/api/bridge/attention': Mochi.api(async ({ method, url, request }) => {
+		if (method !== 'POST') return apiError(405, 'Method Not Allowed');
+		const id = url.searchParams.get('id');
+		const token = request.headers.get('X-Bridge-Token');
+		const state = url.searchParams.get('state');
+		console.log(
+			`[bridge] attention POST id=${id ?? '(none)'} state=${state ?? '(none)'} hasToken=${!!token}`
+		);
+		if (!id || !token) {
+			console.warn('[bridge] rejected: missing id or token');
+			return apiError(400, 'id and token are required');
+		}
+		const row = getInstance(id);
+		// One uniform 403, constant-time — otherwise an attacker could enumerate instance ids.
+		if (!row || !row.bridge_token || !timingSafeEqualStr(token, row.bridge_token)) {
+			console.warn(
+				`[bridge] rejected id=${id}: ${!row ? 'no such instance' : !row.bridge_token ? 'instance has no bridge_token' : 'token mismatch'}`
+			);
+			return apiError(403, 'Forbidden');
+		}
+		if (state === 'done') setAttention(id, 'done');
+		else if (state === 'waiting') setAttention(id, 'waiting');
+		else clearAttention(id); // 'busy' / anything else → Claude resumed, dismiss the pulse
+		console.log(
+			`[bridge] accepted id=${id} → attention=${state === 'done' || state === 'waiting' ? state : 'cleared'}`
+		);
+		return json({ ok: true });
+	}),
+
+	'/api/instances/:id/logs': Mochi.ws<{ id: string; unsub?: () => void }>({
+		upgrade: (req, params) =>
+			wsUpgradeAllowed(req) && params.id && getInstance(params.id) ? { id: params.id } : false,
+		open(ws) {
+			ws.data.user.unsub = subscribeLogs(ws.data.user.id, (chunk) => {
+				try {
+					ws.send(chunk);
+				} catch {
+					/* socket closed */
+				}
+			});
+		},
+		message: () => {},
+		close(ws) {
+			ws.data.user.unsub?.();
+		}
+	}),
+
+	...proxyRoutes,
+
+	...(process.env.MODE === 'development'
+		? {
+				'/debug': Mochi.page('./src/pages/UI.svelte', {
+					// Feed the showcase the real auth providers so CredMenu mirrors `/`.
+					serverProps: async () => ({ preflight: await preflight() })
+				})
+			}
+		: {})
+};

package/src/settings.ts

@@ -0,0 +1,14 @@
+// SSR-safe: every function no-ops when localStorage is absent.
+
+const SOUND_KEY = 'codebay.sound';
+
+/** Defaults to on — only an explicit 'off' disables it. */
+export function soundEnabled(): boolean {
+	if (typeof localStorage === 'undefined') return true;
+	return localStorage.getItem(SOUND_KEY) !== 'off';
+}
+
+export function setSoundEnabled(on: boolean): void {
+	if (typeof localStorage === 'undefined') return;
+	localStorage.setItem(SOUND_KEY, on ? 'on' : 'off');
+}

package/src/shell.html

@@ -0,0 +1,100 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>Codebay</title>
+		<style>
+			/* Each themed variable is defined once as light-dark(light, dark). With no
+	       data-theme attribute (the "auto" mode) `color-scheme: light dark` lets the
+	       browser preference pick the value; an explicit choice pins color-scheme
+	       below, which forces every light-dark() to that side. */
+			:root {
+				color-scheme: light dark;
+				--bg: light-dark(#d7d8d2, #1b1c15);
+				--bg-card: light-dark(#e7e8e2, #24261c);
+				--ink: light-dark(#14150f, #e8e9df);
+				--ink-soft: light-dark(#45463e, #b7b8a9);
+				--ink-faint: light-dark(#7d7e74, #85867a);
+				--rule: light-dark(#20211a, #46473a);
+				--rule-soft: light-dark(#b9bab2, #34352a);
+				--warn-bg: light-dark(#e4d98f, #4a3d12);
+				--warn-line: light-dark(#9c8729, #c9a83a);
+				--warn-ink: light-dark(#463b08, #f3e3a0);
+				--ok-bg: light-dark(#8fbf6e, #23421a);
+				--ok-line: light-dark(#4c7a2e, #6fa84a);
+				--ok-ink: light-dark(#1c3110, #cdeab8);
+				--danger: light-dark(#b23a2e, #e2564a);
+				--danger-soft: light-dark(#e3c6c1, #4a231e);
+				--screen-bg: #0d0e0a;
+				--screen-ink: #d8d9cf;
+				--screen-line: rgba(255, 255, 255, 0.04);
+				--attn-done: #22c55e;
+				--attn-waiting: #f59e0b;
+				--info: #388bfd;
+				--grid-line: light-dark(rgba(0, 0, 0, 0.035), rgba(255, 255, 255, 0.035));
+				/* --attn-done at reduced opacity — reads correctly on both themes' track color. */
+				--switch-on-bg: rgba(34, 197, 94, 0.32);
+				--font-display: 'Doto Variable', 'JetBrains Mono Variable', monospace;
+				--font-mono:
+					'JetBrains Mono Variable', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+				--font-serif: var(--font-display);
+				--font-sans: var(--font-mono);
+			}
+			:root[data-theme='light'] {
+				color-scheme: light;
+			}
+			:root[data-theme='dark'] {
+				color-scheme: dark;
+			}
+			* {
+				box-sizing: border-box;
+			}
+			/* The whole theme is square — enforce it globally (covers third-party
+         widgets like the toaster too). Intentional, not a workaround.
+         Exclude Mochi's dev-only debug bar so it keeps its own styling. */
+			*:not(#mochi-dev-toolbar):not(#mochi-dev-toolbar *) {
+				border-radius: 0 !important;
+			}
+			/* Shared "panel" chrome — the bordered, drop-shadowed card look used
+         throughout the app (health box, ports/log boxes, instance cards,
+         dropdowns, modals, the UI showcase). A component can still override
+         `box-shadow`/`border` locally (e.g. the folder-picker modal's bigger
+         8px shadow) — Svelte's auto-scoping class gives any same-component
+         rule higher specificity than this global one, so local overrides
+         always win regardless of source order. */
+			.panel {
+				border: 1px solid var(--ink);
+				box-shadow: 4px 4px 0 var(--ink);
+			}
+			/* Shared dark header bar — the inverted label strip at the top of a panel. */
+			.panel-bar {
+				padding: 9px 14px;
+				background: var(--ink);
+				color: var(--bg);
+				font-family: var(--font-display);
+				font-weight: 700;
+				font-size: 12px;
+				text-transform: uppercase;
+				letter-spacing: 0.12em;
+			}
+			body {
+				margin: 0;
+				font-family: var(--font-sans);
+				/* Pale LCD panel with a faint pixel-grid matrix overlay. */
+				background:
+					repeating-linear-gradient(0deg, var(--grid-line) 0 1px, transparent 1px 3px),
+					repeating-linear-gradient(90deg, var(--grid-line) 0 1px, transparent 1px 3px), var(--bg);
+				color: var(--ink);
+				font-size: 14px;
+				line-height: 1.55;
+				min-height: 100vh;
+				-webkit-font-smoothing: antialiased;
+			}
+		</style>
+		{{mochi.head}} {{mochi.css}}
+	</head>
+	<body>
+		{{mochi.body}} {{mochi.script}}
+	</body>
+</html>

package/src/sound.ts

@@ -0,0 +1,69 @@
+import { soundEnabled } from './settings.ts';
+
+/** Regenerate these WAVs with `bun run gen:chimes`. */
+const SOUNDS = {
+	done: '/sounds/done.wav', // brighter ascending pair
+	waiting: '/sounds/waiting.wav' // lower, more insistent
+} as const;
+
+type Chime = keyof typeof SOUNDS;
+
+const elements: Partial<Record<Chime, HTMLAudioElement>> = {};
+let unlocked = false;
+
+function element(name: Chime): HTMLAudioElement | null {
+	if (typeof window === 'undefined') return null;
+	let el = elements[name];
+	if (!el) {
+		el = new Audio(SOUNDS[name]);
+		el.preload = 'auto';
+		elements[name] = el;
+	}
+	return el;
+}
+
+/** Must be called from a user-gesture handler — a silent play/pause is what satisfies the browser. */
+export function unlockAudio(): void {
+	if (unlocked || typeof window === 'undefined') return;
+	unlocked = true;
+	for (const name of Object.keys(SOUNDS) as Chime[]) {
+		const el = element(name);
+		if (!el) continue;
+		const { volume } = el;
+		el.volume = 0;
+		void el
+			.play()
+			.then(() => {
+				el.pause();
+				el.currentTime = 0;
+				el.volume = volume;
+			})
+			.catch(() => {
+				el.volume = volume;
+			});
+	}
+}
+
+export function playChime(state: Chime): void {
+	if (!soundEnabled()) {
+		console.log(`[chime] playChime(${state}) — skipped (sound disabled in settings)`);
+		return;
+	}
+	const el = element(state);
+	if (!el) {
+		console.log(`[chime] playChime(${state}) — no audio element (SSR/no window?)`);
+		return;
+	}
+	if (!unlocked) {
+		console.warn(
+			`[chime] playChime(${state}) — audio not yet unlocked; browser may block until the page is interacted with`
+		);
+	}
+	el.currentTime = 0;
+	void el
+		.play()
+		.then(() => console.log(`[chime] playChime(${state}) — playing`))
+		.catch((err) =>
+			console.warn(`[chime] playChime(${state}) — play rejected:`, err?.message ?? err)
+		);
+}

package/src/theme.ts

@@ -0,0 +1,24 @@
+/**
+ * Importable only from the Svelte build graph — `cookies` resolves through Mochi's
+ * isomorphic virtual module. Server entry files use `getRequestContext().cookies` instead.
+ */
+import { cookies } from 'mochi-framework';
+
+export type Theme = 'light' | 'dark' | 'auto';
+
+const THEME_KEY = 'theme';
+
+export function getTheme(): Theme {
+	const value = cookies.get(THEME_KEY);
+	return value === 'dark' || value === 'light' ? value : 'auto';
+}
+
+export function setTheme(theme: Theme): void {
+	cookies.set(THEME_KEY, theme, { expires: 400, path: '/' });
+}
+
+/** Auto removes the attribute entirely, letting `light-dark()` follow the browser preference. */
+export function applyTheme(theme: Theme): void {
+	if (theme === 'auto') delete document.documentElement.dataset.theme;
+	else document.documentElement.dataset.theme = theme;
+}