staffa 0.1.0

package/src/components/tabs.ts

@@ -0,0 +1,144 @@
+import A from "aberdeen";
+import { type BaseOptions, type Bindable, type Content, type Slot, type Styling, drawSlot, uniqueId } from "../core.js";
+
+/** A single tab definition. */
+export interface Tab {
+	/** Stable id used as the selection value. Falls back to the array index. */
+	id?: string;
+	/** Tab label shown in the tab strip. */
+	label: Slot;
+	/** Optional leading icon. */
+	icon?: Slot;
+	/** Content rendered in the panel when this tab is active. */
+	content?: Content;
+	/** Disables selecting this tab. */
+	disabled?: boolean;
+}
+
+/** Options for {@link tabs}. */
+export interface TabsOptions extends BaseOptions {
+	/** The tabs to display. */
+	tabs: Tab[];
+	/**
+	 * Two-way binding for the selected tab's id. When omitted, the component keeps
+	 * its own internal selection, starting at the first tab.
+	 */
+	bind?: Bindable<string>;
+	/** Visual style of the tab strip. Defaults to `"underline"`. */
+	variant?: "underline" | "pills";
+	/** Aberdeen attr/style string applied to the active panel. */
+	inner?: Styling;
+}
+
+A.insertGlobalCss({
+	".S_tabs": {
+		"&": "display:flex flex-direction:column gap:$3",
+		".S_tablist": "display:flex gap:$1 align-items:stretch",
+		".S_tab":
+			"display:inline-flex align-items:center gap:$2 cursor:pointer background:transparent " +
+			"border:0 fg:$sFgMuted font-weight:600 padding: 0.6em 0.9em; " +
+			"transition: color 0.15s, background 0.15s, border-color 0.15s;",
+		".S_tab:hover:not(:disabled)": "fg:$sFg",
+		".S_tab:disabled": "opacity:0.5 cursor:not-allowed",
+		".S_tab:focus-visible": "outline:none box-shadow: 0 0 0 3px $sFocus; r:$sRadius",
+		// Underline variant.
+		"&.S_underline .S_tablist": "border-bottom: 1px solid $sBorder;",
+		"&.S_underline .S_tab": "border-bottom: 2px solid transparent; margin-bottom:-1px",
+		"&.S_underline .S_tab[aria-selected=true]": "fg:$sFg border-bottom-color:$sPrimary",
+		// Pills variant.
+		"&.S_pills .S_tab": "r:$sRadius",
+		"&.S_pills .S_tab[aria-selected=true]": "fg:$sPrimaryFg background:$sPrimary",
+		// The panel has no enclosing box, so no default padding — its content
+		// aligns flush with the tab strip. Callers add padding/flex via `inner`.
+		".S_tabpanel": "display:block",
+	},
+});
+
+/**
+ * A tabbed view. Renders an ARIA `tablist` of buttons and a single live panel
+ * for the selected tab. Supports keyboard navigation (left/right/home/end).
+ *
+ * @example
+ * ```ts
+ * S.tabs({ tabs: [
+ *   { label: "Overview", content: () => A("p#...") },
+ *   { label: "Settings", content: () => drawSettings() },
+ * ]});
+ * ```
+ */
+export function tabs(opts: TabsOptions): void {
+	const variant = opts.variant ?? "underline";
+	const groupId = uniqueId("tabs");
+
+	// Resolve a tab's selection key (its id, or its index as a string).
+	const keyOf = (tab: Tab, index: number) => tab.id ?? String(index);
+
+	// Selection state: caller-provided binding, or internal.
+	const $sel: Bindable<string> = opts.bind ?? A.proxy(keyOf(opts.tabs[0] ?? { label: "" }, 0));
+
+	const select = (tab: Tab, index: number) => {
+		if (tab.disabled) return;
+		$sel.value = keyOf(tab, index);
+	};
+
+	A(`div.S_tabs.S_${variant}`, opts.root, () => {
+		A("div.S_tablist role=tablist", () => {
+			opts.tabs.forEach((tab, index) => {
+				const key = keyOf(tab, index);
+				A("button.S_tab type=button role=tab", () => {
+					A(`id=${groupId}-tab-${key} aria-controls=${groupId}-panel-${key}`);
+					A(() => {
+						const selected = $sel.value === key;
+						A("aria-selected=", selected ? "true" : "false");
+						A("tabindex=", selected ? "0" : "-1");
+					});
+					if (tab.disabled) A("disabled=true");
+					A("click=", () => select(tab, index));
+					A("keydown=", (e: KeyboardEvent) => onKey(e, opts.tabs, index, select));
+					drawSlot(tab.icon);
+					drawSlot(tab.label);
+				});
+			});
+		});
+
+		A("div.S_tabpanel role=tabpanel", opts.inner, () => {
+			A(() => {
+				const selKey = $sel.value;
+				const index = opts.tabs.findIndex((t, i) => keyOf(t, i) === selKey);
+				const tab = opts.tabs[index] ?? opts.tabs[0];
+				if (!tab) return;
+				A(`id=${groupId}-panel-${keyOf(tab, index)} aria-labelledby=${groupId}-tab-${keyOf(tab, index)}`);
+				tab.content?.();
+			});
+		});
+	});
+}
+
+/** Roving-tabindex keyboard handling for the tab strip. */
+function onKey(
+	e: KeyboardEvent,
+	list: Tab[],
+	index: number,
+	select: (tab: Tab, index: number) => void,
+): void {
+	let next = index;
+	if (e.key === "ArrowRight" || e.key === "ArrowDown") next = (index + 1) % list.length;
+	else if (e.key === "ArrowLeft" || e.key === "ArrowUp") next = (index - 1 + list.length) % list.length;
+	else if (e.key === "Home") next = 0;
+	else if (e.key === "End") next = list.length - 1;
+	else return;
+	e.preventDefault();
+
+	// Skip disabled tabs in the chosen direction.
+	const dir = next >= index ? 1 : -1;
+	for (let i = 0; i < list.length; i++) {
+		const candidate = list[next];
+		if (candidate && !candidate.disabled) {
+			select(candidate, next);
+			const el = (e.currentTarget as HTMLElement)?.parentElement?.children[next] as HTMLElement | undefined;
+			el?.focus();
+			return;
+		}
+		next = (next + dir + list.length) % list.length;
+	}
+}

package/src/components/textarea.ts

@@ -0,0 +1,68 @@
+import A from "aberdeen";
+import type { Bindable } from "../core.js";
+import { type FieldOptions, applyControlAttrs, drawField } from "./field.js";
+
+/** Options for {@link textarea}. */
+export interface TextareaOptions extends FieldOptions {
+	/** Placeholder text. */
+	placeholder?: string;
+	/** Two-way binding target. */
+	bind?: Bindable<string>;
+	/** Static initial value. */
+	value?: string;
+	/** Visible number of text rows. Defaults to `4`. Ignored when `autoGrow` is enabled. */
+	rows?: number;
+	/** Whether the textarea may be resized by the user. Defaults to `"vertical"`. Ignored when `autoGrow` is enabled. */
+	resize?: "none" | "vertical" | "horizontal" | "both";
+	/** Auto-grow the textarea to fit its content. Defaults to `true`. */
+	autoGrow?: boolean;
+	/** Fired on every `input` event. */
+	input?: (event: Event) => void;
+	/** Fired on `change` (commit). */
+	change?: (event: Event) => void;
+}
+
+A.insertGlobalCss({
+	"textarea.S_input": "resize:vertical min-height:3em line-height:1.45",
+	"textarea.S_input.S_autoGrow": "resize:none min-height:2.5em overflow-y:hidden",
+});
+
+/**
+ * A multi-line text input. Shares the field chrome and styling of
+ * {@link textline}, adding `rows` and `resize` controls.
+ *
+ * @example
+ * ```ts
+ * S.textarea({ label: "Bio", rows: 6, bind: A.ref($user, "bio") });
+ * ```
+ */
+export function textarea(opts: TextareaOptions = {}): void {
+	const grow = opts.autoGrow !== false;
+
+	drawField(opts, (id, isInvalid) => {
+		const el = A("textarea.S_input", opts.control, () => {
+			if (grow) {
+				A(".S_autoGrow");
+				A("input=", (e: Event) => {
+					fitToContent(e.currentTarget as HTMLTextAreaElement);
+					if (opts.input) opts.input(e);
+				});
+			} else {
+				A("rows=", opts.rows ?? 4);
+				A("resize:", opts.resize ?? "vertical");
+				if (opts.input) A("input=", opts.input);
+			}
+			if (opts.placeholder != null) A("placeholder=", opts.placeholder);
+			if (opts.value != null && !opts.bind) A("value=", opts.value);
+			if (opts.change) A("change=", opts.change);
+			applyControlAttrs(opts, id, isInvalid, opts.bind);
+		}) as HTMLTextAreaElement;
+
+		if (grow) requestAnimationFrame(() => fitToContent(el));
+	});
+}
+
+function fitToContent(el: HTMLTextAreaElement): void {
+	el.style.height = "auto";
+	el.style.height = `${el.scrollHeight}px`;
+}

package/src/components/textline.ts

@@ -0,0 +1,66 @@
+import A from "aberdeen";
+import type { Bindable } from "../core.js";
+import { type FieldOptions, applyControlAttrs, drawField } from "./field.js";
+
+/**
+ * The `<input>` types {@link textline} supports. Deliberately excludes types
+ * that need their own widget (`checkbox`, `radio`, `color`, `range`, `file`,
+ * `button`, ...) — use the dedicated components for those.
+ */
+export type TextlineType =
+	| "text"
+	| "password"
+	| "email"
+	| "number"
+	| "tel"
+	| "url"
+	| "search"
+	| "date"
+	| "time"
+	| "datetime-local"
+	| "month"
+	| "week";
+
+/** Options for {@link textline}. */
+export interface TextlineOptions extends FieldOptions {
+	/** Input type. Defaults to `"text"`. */
+	type?: TextlineType;
+	/** Placeholder text. */
+	placeholder?: string;
+	/** Two-way binding target (e.g. `A.ref($user, "name")`). */
+	bind?: Bindable<string | number>;
+	/** Static initial value (use {@link TextlineOptions.bind | bind} for reactivity). */
+	value?: string | number;
+	/** Autocomplete hint passed to the native `autocomplete` attribute. */
+	autocomplete?: string;
+	/** Fired on every `input` event with the native event. */
+	input?: (event: Event) => void;
+	/** Fired on `change` (commit) with the native event. */
+	change?: (event: Event) => void;
+}
+
+/**
+ * A single-line text input — covering text, passwords, numbers, email, dates and
+ * the other line-oriented `<input>` types.
+ *
+ * Renders inside the standard {@link drawField} chrome (label, control,
+ * help/error), so it aligns cleanly inside a {@link form}.
+ *
+ * @example
+ * ```ts
+ * S.textline({ label: "Email", type: "email", required: true, bind: A.ref($user, "email") });
+ * ```
+ */
+export function textline(opts: TextlineOptions = {}): void {
+	drawField(opts, (id, isInvalid) => {
+		A("input.S_input", opts.control, () => {
+			A("type=", opts.type ?? "text");
+			if (opts.placeholder != null) A("placeholder=", opts.placeholder);
+			if (opts.autocomplete != null) A("autocomplete=", opts.autocomplete);
+			if (opts.value != null && !opts.bind) A("value=", opts.value);
+			if (opts.input) A("input=", opts.input);
+			if (opts.change) A("change=", opts.change);
+			applyControlAttrs(opts, id, isInvalid, opts.bind);
+		});
+	});
+}

package/src/core.ts

@@ -0,0 +1,88 @@
+import A from "aberdeen";
+
+/**
+ * Shared building blocks for the Staffa component library.
+ *
+ * Every component in Staffa is "just an Aberdeen draw function": a plain function
+ * that takes a single, strongly typed options object and emits DOM through
+ * Aberdeen's {@link A} function. This module defines the option-type hierarchy
+ * that all components build on, plus a couple of tiny helpers.
+ */
+
+/**
+ * An Aberdeen attribute/style/class string, e.g. `"display:flex gap:$3 .my-class"`.
+ *
+ * These strings are passed straight through to {@link A} as positional
+ * arguments, so they accept the full Aberdeen shorthand syntax: CSS shortcuts
+ * (`p`, `mt`, `bg`, `r`, ...), spacing variables (`$1`..`$12`), CSS custom
+ * properties (`$sPrimary`), classes (`.foo`) and attributes (`aria-label=Hi`).
+ *
+ * Note: because Aberdeen interprets a leading bare word as an element name, write
+ * `display:flex` rather than just `flex`.
+ */
+export type Styling = string;
+
+/** A reactive "value box", such as the result of `A.proxy(x)` or `A.ref(obj, key)`. */
+export type Bindable<T> = { value: T };
+
+/** A content function. It runs inside the relevant element's reactive scope. */
+export type Content = () => void;
+
+/**
+ * Something that renders a small piece of content: either a plain string (drawn
+ * as a text node) or a draw function (for icons, badges, custom markup, ...).
+ */
+export type Slot = string | Content;
+
+/**
+ * Options shared by *every* Staffa component.
+ *
+ * The {@link BaseOptions.root | root} string is applied to the outermost element
+ * of the widget, letting callers tweak layout, spacing or add classes without
+ * forking the component.
+ */
+export interface BaseOptions {
+	/**
+	 * Aberdeen attr/style string applied to the widget's root element.
+	 *
+	 * It is passed as a positional argument to {@link A}, so a *change* to it on a
+	 * proxied options object re-runs the caller's scope (recreating the widget).
+	 * That's fine for `root` — it rarely changes at runtime.
+	 */
+	root?: Styling;
+}
+
+/**
+ * Options for components that wrap a single block of caller-provided content.
+ *
+ * Such components render an *inner* element (the one that actually holds the
+ * children) which is given sensible default padding and `gap` in CSS. Override
+ * those via {@link ContentOptions.inner | inner}, whose declarations win because
+ * they're applied as inline styles.
+ */
+export interface ContentOptions extends BaseOptions {
+	/** Draws the children of this component. */
+	content?: Content;
+	/**
+	 * Aberdeen attr/style string applied to the inner (content-holding) element.
+	 * Add `display:flex` here if you want the children laid out as a flex
+	 * row/column.
+	 */
+	inner?: Styling;
+}
+
+let idCounter = 0;
+/** Generates a process-unique id, used to wire `<label for>` to its control. */
+export function uniqueId(prefix = "s"): string {
+	return `${prefix}-${++idCounter}`;
+}
+
+/**
+ * Draw a {@link Slot} into the current element: call it if it's a function,
+ * otherwise emit it as a text node.
+ */
+export function drawSlot(slot: Slot | undefined): void {
+	if (slot == null) return;
+	if (typeof slot === "function") slot();
+	else A("#", slot);
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * Staffa — a small, opinionated component library for the
+ * {@link https://aberdeenjs.org | Aberdeen} reactive UI library.
+ *
+ * Import the default `S` object and call its component functions:
+ *
+ * ```ts
+ * import S from "staffa";
+ *
+ * S.main({
+ *   title: "Hello",
+ *   maxWidth: "48rem",
+ *   content: () => {
+ *     S.box({ header: "Login", content: () => {
+ *       S.form({
+ *         content: () => {
+ *           S.textline({ label: "Email", type: "email", bind: A.ref($u, "email") });
+ *           S.checkbox({ label: "Remember me", bind: A.ref($u, "remember") });
+ *         },
+ *         actions: () => S.button({ text: "Sign in", type: "submit" }),
+ *       });
+ *     }});
+ *   },
+ * });
+ * ```
+ *
+ * Every component takes a single typed options object (see each function's
+ * docs). The options object — or parts of it — may be an Aberdeen proxy, in
+ * which case the component re-renders the affected parts in place when you
+ * mutate it. See `AGENTS.md` for the design philosophy.
+ */
+// Importing the theme module installs spacing vars, the reactive theme and the
+// base stylesheet. Customise by mutating S.darkTheme / S.lightTheme.
+import { darkTheme, lightTheme, setDarkMode, getDarkMode } from "./theme.js";
+
+import { autocomplete } from "./components/autocomplete.js";
+import { box } from "./components/box.js";
+import { button } from "./components/button.js";
+import { buttonGroup } from "./components/buttonGroup.js";
+import { checkbox } from "./components/checkbox.js";
+import { form } from "./components/form.js";
+import { main } from "./components/main.js";
+import { dialog, alert, confirm, prompt } from "./components/dialog.js";
+import { select } from "./components/select.js";
+import { tabs } from "./components/tabs.js";
+import { textarea } from "./components/textarea.js";
+import { textline } from "./components/textline.js";
+
+/** The Staffa component namespace. */
+export const S = {
+	main,
+	box,
+	dialog,
+	alert,
+	confirm,
+	prompt,
+	form,
+	textline,
+	textarea,
+	checkbox,
+	tabs,
+	button,
+	buttonGroup,
+	autocomplete,
+	select,
+	darkTheme,
+	lightTheme,
+	setDarkMode,
+	getDarkMode,
+};
+
+export default S;
+
+// Re-export theming and shared types for advanced use.
+export { type Theme, darkTheme, lightTheme, setDarkMode, getDarkMode } from "./theme.js";
+export type {
+	BaseOptions,
+	ContentOptions,
+	Bindable,
+	Content,
+	Slot,
+	Styling,
+} from "./core.js";
+export { drawSlot, uniqueId } from "./core.js";
+
+export type { FieldOptions } from "./components/field.js";
+export type { MainOptions } from "./components/main.js";
+export type { BoxOptions } from "./components/box.js";
+export type { FormOptions } from "./components/form.js";
+export type { TextlineOptions, TextlineType } from "./components/textline.js";
+export type { TextareaOptions } from "./components/textarea.js";
+export type { CheckboxOptions } from "./components/checkbox.js";
+export type { Tab, TabsOptions } from "./components/tabs.js";
+export type { ButtonOptions, ButtonVariant, ButtonColor } from "./components/button.js";
+export type { ButtonGroupOptions } from "./components/buttonGroup.js";
+export type { AutocompleteOptions, AutocompleteOptionInput } from "./components/autocomplete.js";
+export type { SelectOptions, SelectOptionInput } from "./components/select.js";
+export type { DialogOptions } from "./components/dialog.js";

package/src/theme.ts

@@ -0,0 +1,195 @@
+import A from "aberdeen";
+
+/**
+ * Theming and global base styles for Staffa.
+ *
+ * Staffa is themed entirely through CSS custom properties (via Aberdeen's
+ * {@link A.cssVars}). Components reference these with `var(--sPrimary)` etc., so
+ * changing a single variable restyles the whole app — at runtime, reactively.
+ *
+ * Unlike typical Aberdeen apps (which use component-local `insertCss`), Staffa uses
+ * **global** CSS (`insertGlobalCss`) with class names prefixed `S_`. This is a
+ * deliberate trade-off: it lets application authors override any Staffa style from
+ * their own stylesheet without fighting scoped class names.
+ */
+
+/**
+ * The set of CSS custom properties Staffa understands. All are plain CSS color /
+ * length strings. Override any subset by mutating {@link darkTheme} /
+ * {@link lightTheme}.
+ */
+export interface Theme {
+	/** Page background — the darkest surface. */
+	sBg: string;
+	/** Default surface for cards, inputs, menus. */
+	sSurface: string;
+	/** Raised surface for headers, footers, chips, hover states. */
+	sSurfaceHi: string;
+	/** Primary foreground / text color. */
+	sFg: string;
+	/** Muted text (help text, subtitles). */
+	sFgMuted: string;
+	/** Faint text (placeholders, disabled). */
+	sFgFaint: string;
+	/** Default border color. */
+	sBorder: string;
+	/** Stronger border / neutral control color. */
+	sBorderStrong: string;
+	/** Brand / accent color. */
+	sPrimary: string;
+	/** Brand color, hover/brighter. */
+	sPrimaryHover: string;
+	/** Text drawn on top of {@link Theme.sPrimary}. */
+	sPrimaryFg: string;
+	/** Destructive / error color. */
+	sDanger: string;
+	/** Positive / success color. */
+	sSuccess: string;
+	/** Caution color. */
+	sWarning: string;
+	/** Focus-ring color (usually a translucent primary). */
+	sFocus: string;
+	/** Default corner radius. */
+	sRadius: string;
+	/** Larger corner radius (e.g. the {@link import("./components/main").main} sheet). */
+	sRadiusLg: string;
+	/** Elevation shadow for menus, dialogs, the framed content sheet. */
+	sShadow: string;
+}
+
+/**
+ * The default dark Staffa theme: modern and intentionally a little vivid so it
+ * stands out of the box.
+ *
+ * This is a live Aberdeen proxy — mutate it (e.g. `darkTheme.sPrimary = "..."`)
+ * and, while dark mode is active, the change flows straight into the CSS
+ * variables. Use this to retheme dark and {@link lightTheme} independently.
+ */
+export const darkTheme: Theme = A.proxy<Theme>({
+	sBg: "#0e1015",
+	sSurface: "#181b22",
+	sSurfaceHi: "#222632",
+	sFg: "#e8eaf0",
+	sFgMuted: "#a6acba",
+	sFgFaint: "#6b7280",
+	sBorder: "#2c313c",
+	sBorderStrong: "#3c4352",
+	sPrimary: "#8b7bff",
+	sPrimaryHover: "#a99dff",
+	sPrimaryFg: "#0c0a1a",
+	sDanger: "#ff6b6b",
+	sSuccess: "#46d39a",
+	sWarning: "#fbbf24",
+	sFocus: "rgba(139, 123, 255, 0.45)",
+	sRadius: "10px",
+	sRadiusLg: "16px",
+	sShadow: "0 8px 30px rgba(0, 0, 0, 0.45)",
+});
+
+/**
+ * The light Staffa theme — the same lavender brand, retuned for a bright,
+ * modern surface: white cards on a soft grey page, a deeper primary so it
+ * reads well on light backgrounds, and a softer elevation shadow.
+ *
+ * Like {@link darkTheme}, a live proxy: mutate it to retheme light mode.
+ */
+export const lightTheme: Theme = A.proxy<Theme>({
+	sBg: "#f3f4f8",
+	sSurface: "#ffffff",
+	sSurfaceHi: "#eceef4",
+	sFg: "#1b1e27",
+	sFgMuted: "#5b6273",
+	sFgFaint: "#9aa1b2",
+	sBorder: "#e2e5ee",
+	sBorderStrong: "#c7ccda",
+	sPrimary: "#6c5ce7",
+	sPrimaryHover: "#5847d4",
+	sPrimaryFg: "#ffffff",
+	sDanger: "#e23b3b",
+	sSuccess: "#1f9d6b",
+	sWarning: "#d97706",
+	sFocus: "rgba(108, 92, 231, 0.35)",
+	sRadius: "10px",
+	sRadiusLg: "16px",
+	sShadow: "0 6px 24px rgba(20, 24, 40, 0.12)",
+});
+
+const STORAGE_KEY = "staffa:darkMode";
+
+/**
+ * The explicit dark-mode choice — `true` (force dark), `false` (force light) or
+ * `undefined` (follow the OS via {@link A.darkMode}). A reactive proxy, seeded
+ * from localStorage so the persisted preference applies on the first paint.
+ */
+const $override = A.proxy<{ value: boolean | undefined }>({ value: readStoredOverride() });
+
+/** Read the persisted dark-mode override from localStorage (defensively). */
+function readStoredOverride(): boolean | undefined {
+	try {
+		const v = localStorage.getItem(STORAGE_KEY);
+		if (v === "dark") return true;
+		if (v === "light") return false;
+	} catch {
+		// localStorage may be unavailable (SSR, privacy mode) — ignore.
+	}
+	return undefined;
+}
+
+/**
+ * Force dark mode (`true`), light mode (`false`), or follow the OS preference
+ * (`undefined`). Takes effect immediately and is persisted to localStorage, so
+ * the choice survives reloads.
+ */
+export function setDarkMode(value: boolean | undefined): void {
+	$override.value = value;
+	try {
+		if (value === undefined) localStorage.removeItem(STORAGE_KEY);
+		else localStorage.setItem(STORAGE_KEY, value ? "dark" : "light");
+	} catch {
+		// Persistence is best-effort; ignore storage failures.
+	}
+}
+
+/**
+ * Whether dark mode is currently active. Reactive — read it inside a scope to
+ * re-run on changes.
+ *
+ * @param allowAuto - When `true`, returns `undefined` (rather than resolving to
+ *   a boolean) if the user is following the OS preference, so a dark/light/auto
+ *   control can tell the three states apart.
+ */
+export function getDarkMode(allowAuto = false): boolean | undefined {
+	const v = $override.value;
+	return v === undefined && !allowAuto ? A.darkMode() : v;
+}
+
+// Set up everything as this module loads. Spacing scale first ($1 = 0.25rem,
+// $2 = 0.5rem, $3 = 1rem, ...), then reactively merge the active theme into the
+// CSS variables. This scope runs synchronously now — before the first paint —
+// so the correct colors are in place immediately (no flash), and A.merge
+// subscribes to the theme it reads, so toggling the mode or mutating
+// darkTheme / lightTheme re-applies automatically.
+A.setSpacingCssVars();
+A(() => {
+	A.merge(A.cssVars as Partial<Theme>, getDarkMode() ? darkTheme : lightTheme);
+});
+
+// A deliberately light reset. It sets box-sizing and sensible colors/fonts, but
+// does NOT strip margins from headings/paragraphs/lists, so rendered rich
+// content (e.g. markdown-to-HTML) keeps reasonable default rhythm.
+A.insertGlobalCss({
+	"*, *::before, *::after": "box-sizing:border-box",
+	html: "text-size-adjust:100%",
+	body: "m:0 bg:$sBg fg:$sFg line-height:1.5 font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; -webkit-font-smoothing:antialiased",
+	a: "fg:$sPrimary text-decoration:underline text-underline-offset:2px",
+	"a:hover": "fg:$sPrimaryHover",
+	"input, button, textarea, select": "font:inherit color:inherit",
+	"code, kbd, samp, pre": "font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;",
+	code: "bg:$sSurfaceHi padding: 0.12em 0.34em; r:4px font-size:0.9em",
+	pre: "bg:$sSurface p:$3 r:$sRadius overflow:auto",
+	"pre code": "bg:transparent p:0",
+	"img, svg, video, canvas": "max-width:100% h:auto",
+	hr: "border:0 border-top: 1px solid $sBorder; margin: $3 0;",
+	"::placeholder": "fg:$sFgFaint opacity:1",
+	":focus-visible": "outline: 2px solid $sFocus; outline-offset:2px",
+});