@ultimat3/ui 22.15.0 → 24.0.0

package/src/components/relative-time-view.ts

@@ -27,16 +27,23 @@ const THRESHOLDS: readonly Threshold[] = [
   { unit: 'second', ms: 1000 },
 ];
 
+const unitMs = (index: number): number => (THRESHOLDS[index] as Threshold).ms;
+const roundIn = (delta: number, index: number): number => Math.round(delta / unitMs(index));
+
 export function relativeTimeText(options: RelativeTimeOptions): string {
   const target = toDate(options.value).getTime();
   const base = options.now === undefined ? Date.now() : toDate(options.now).getTime();
   const delta = target - base;
   const magnitude = Math.abs(delta);
 
-  const threshold =
-    THRESHOLDS.find((candidate) => magnitude >= candidate.ms) ??
-    (THRESHOLDS[THRESHOLDS.length - 1] as Threshold);
-  const value = Math.round(delta / threshold.ms);
+  let index = THRESHOLDS.findIndex((candidate) => magnitude >= candidate.ms);
+  if (index < 0) index = THRESHOLDS.length - 1;
+  // Promote AFTER rounding: 59.6 minutes rounds to 60, and "60 minutes ago" is "1 hour ago".
+  while (index > 0 && Math.abs(roundIn(delta, index)) * unitMs(index) >= unitMs(index - 1)) {
+    index -= 1;
+  }
+  const threshold = THRESHOLDS[index] as Threshold;
+  const value = roundIn(delta, index);
 
   const formatter = new Intl.RelativeTimeFormat(options.locale, {
     numeric: options.numeric ?? 'auto',

package/src/form/form-binding.ts

@@ -148,15 +148,16 @@ export function createFormBinding<TValues, TResult>(
     // has already changed, on the one screen where the user is watching for exactly that.
     publish({ status: 'submitting', ...NO_FORM_ERRORS, result: undefined, issues: [] });
 
-    const schema = options.schema;
-    if (schema !== undefined) {
-      // The result's `value` is read by nothing. Deliberately: the parse below is the browser's
-      // opinion, and the only thing this file wants from it is which paths to complain about.
-      const local = issuesFromValidation(await schema['~standard'].validate(values));
-      if (local.length > 0) return failed(local);
-    }
-
     try {
+      // Inside the `try`: a validate that throws or rejects is a failed submit, never a `submit()`
+      // that rejects with the state left at `submitting` and the control refusing every retry.
+      const schema = options.schema;
+      if (schema !== undefined) {
+        // The result's `value` is read by nothing. Deliberately: the parse below is the browser's
+        // opinion, and the only thing this file wants from it is which paths to complain about.
+        const local = issuesFromValidation(await schema['~standard'].validate(values));
+        if (local.length > 0) return failed(local);
+      }
       const result = await options.submit(values);
       // The server accepted what the form held, so there is nothing left to lose. `touched` stays:
       // the user has still visited those fields, and a hint that vanishes on save is a flicker.

package/src/icons/build-icons.ts

@@ -11,7 +11,17 @@ import { invalidIconDataError, runtimeMissingError } from '../errors';
 /** Pinned: a floating version would silently redraw icons under an app that never asked. */
 export const LUCIDE_VERSION = '1.31.0';
 
-export const LUCIDE_ICON_NODES_URL = `https://cdn.jsdelivr.net/npm/lucide-static@${LUCIDE_VERSION}/icon-nodes.json`;
+/** Where one pinned version's node table lives. */
+export const iconNodesUrl = (version: string): string =>
+  `https://cdn.jsdelivr.net/npm/lucide-static@${version}/icon-nodes.json`;
+
+export const LUCIDE_ICON_NODES_URL = iconNodesUrl(LUCIDE_VERSION);
+
+/** The registry's answer for the newest published `lucide-static` — what `--bump` pins to. */
+export const LUCIDE_LATEST_URL = 'https://registry.npmjs.org/lucide-static/latest';
+
+/** The tail of every cause about data the PIN published: why re-running alone cannot help. */
+const PIN_REPEATS = `lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this; \`--bump\` raises LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts to the latest release and regenerates`;
 
 export const GLYPHS_DIR = new URL('./glyphs/', import.meta.url).pathname;
 
@@ -27,7 +37,7 @@ export function identifierFor(name: string): string {
  * the network, so its shape is an assumption until it is checked.
  */
 export function parseIconNodes(text: string): ReadonlyMap<string, IconGlyph> {
-  const parsed: unknown = JSON.parse(text);
+  const parsed = parseJson(text);
   // `typeof [] === 'object'`, and an array of icons is a different upstream format, not this one.
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     throw invalidIconDataError(
@@ -42,8 +52,8 @@ export function parseIconNodes(text: string): ReadonlyMap<string, IconGlyph> {
     // writes, so `../../index` is a delete plus an overwrite of a hand-written module.
     if (!SAFE_ICON_NAME.test(name)) {
       throw invalidIconDataError(
-        `carries ${renderCauseValue(name)} as an icon name, which is not the kebab-case shape every Lucide icon uses; the name becomes a file path and an exported identifier, so it cannot be escaped. lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this`,
-        'bun run --filter @ultimat3/ui icons   # after raising LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts',
+        `carries ${renderCauseValue(name)} as an icon name, which is not the kebab-case shape every Lucide icon uses; the name becomes a file path and an exported identifier, so it cannot be escaped. ${PIN_REPEATS}`,
+        'bun run --filter @ultimat3/ui icons --bump',
       );
     }
     out.set(name, toGlyph(name, value));
@@ -51,6 +61,29 @@ export function parseIconNodes(text: string): ReadonlyMap<string, IconGlyph> {
   return out;
 }
 
+/** The body as JSON, or the same coded refusal a wrong shape gets — never a bare `SyntaxError`. */
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw invalidIconDataError(
+      `is not JSON (${renderCauseValue(text.slice(0, 80))}…); ${LUCIDE_ICON_NODES_URL} served an error page or a truncated body`,
+      'bun run --filter @ultimat3/ui icons',
+    );
+  }
+}
+
+/** A node that is not `[tag, attrs?]` with an object for attrs — refused, never skipped. */
+function malformedNode(name: string, node: unknown): ReturnType<typeof invalidIconDataError> {
+  return invalidIconDataError(
+    `for the icon "${name}" carries ${renderCauseValue(node)} where a [tag, attributes] node belongs; skipping it would write a partial glyph. ${PIN_REPEATS}`,
+    'bun run --filter @ultimat3/ui icons --bump',
+  );
+}
+
+const isAttrs = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
 /**
  * An icon name, as characters: lowercase kebab-case, no leading, trailing or doubled hyphen. The
  * same allowlist-over-a-sink shape as `SAFE_ATTR_VALUE`, one layer up — the name is interpolated
@@ -68,10 +101,13 @@ export const SAFE_ATTR_VALUE = /^[\w\s.,+-]*$/;
 
 function toGlyph(name: string, value: unknown): IconGlyph {
   const glyph: (readonly [string, Readonly<Record<string, string>>])[] = [];
-  for (const node of Array.isArray(value) ? (value as unknown[]) : []) {
-    if (!Array.isArray(node) || typeof node[0] !== 'string') continue;
+  if (!Array.isArray(value)) throw malformedNode(name, value);
+  for (const node of value as unknown[]) {
+    if (!Array.isArray(node) || typeof node[0] !== 'string') throw malformedNode(name, node);
+    const rawAttrs: unknown = node[1] ?? {};
+    if (!isAttrs(rawAttrs)) throw malformedNode(name, node);
     const attrs: Record<string, string> = {};
-    for (const [key, item] of Object.entries((node[1] ?? {}) as Record<string, unknown>)) {
+    for (const [key, item] of Object.entries(rawAttrs)) {
       // Upstream keys an element for its diff tooling; it is not an SVG attribute.
       if (key === 'key') continue;
       const text = String(item);
@@ -82,8 +118,8 @@ function toGlyph(name: string, value: unknown): IconGlyph {
       // no legitimate Lucide artwork.
       if (!SAFE_ATTR_VALUE.test(text)) {
         throw invalidIconDataError(
-          `for the icon "${name}" carries ${renderCauseValue(text)} as "${key}", which is not glyph geometry; lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this`,
-          'bun run --filter @ultimat3/ui icons   # after raising LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts',
+          `for the icon "${name}" carries ${renderCauseValue(text)} as "${key}", which is not glyph geometry; ${PIN_REPEATS}`,
+          'bun run --filter @ultimat3/ui icons --bump',
         );
       }
       attrs[key] = text;
@@ -95,8 +131,8 @@ function toGlyph(name: string, value: unknown): IconGlyph {
   iconElements(glyph);
   if (glyph.length === 0) {
     throw invalidIconDataError(
-      `for the icon "${name}" carries no renderable node data; lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this`,
-      'bun run --filter @ultimat3/ui icons   # after raising LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts',
+      `for the icon "${name}" carries no renderable node data; ${PIN_REPEATS}`,
+      'bun run --filter @ultimat3/ui icons --bump',
     );
   }
   return glyph;
@@ -136,23 +172,24 @@ export function moduleSource(name: string, glyph: IconGlyph): string {
 async function format(): Promise<void> {
   const biome = new URL('../../../../node_modules/.bin/biome', import.meta.url).pathname;
   if (!(await Bun.file(biome).exists())) {
-    throw runtimeMissingError('the biome binary', 'bun install, then re-run this generator');
+    throw runtimeMissingError('the biome binary', 'bun install');
   }
-  const result = Bun.spawnSync([biome, 'format', '--write', GLYPHS_DIR]);
+  // A formatter over one directory of generated files; a wedged one is the refusal below.
+  const result = Bun.spawnSync([biome, 'format', '--write', GLYPHS_DIR], { timeout: 60_000 });
   if (result.exitCode !== 0) {
     throw runtimeMissingError(
       'a successful `biome format` over the generated glyphs',
-      `run: ${biome} format --write ${GLYPHS_DIR}`,
+      'bunx biome format --write packages/ui/src/icons/glyphs',
     );
   }
 }
 
-export async function buildIcons(): Promise<number> {
-  const response = await fetch(LUCIDE_ICON_NODES_URL);
+export async function buildIcons(version: string = LUCIDE_VERSION): Promise<number> {
+  const response = await fetch(iconNodesUrl(version));
   if (!response.ok) {
     throw runtimeMissingError(
-      `lucide-static@${LUCIDE_VERSION} icon data (HTTP ${response.status})`,
-      `check network access to ${LUCIDE_ICON_NODES_URL}, then re-run: bun run --filter @ultimat3/ui icons`,
+      `lucide-static@${version} icon data (HTTP ${response.status} from ${iconNodesUrl(version)})`,
+      'bun run --filter @ultimat3/ui icons',
     );
   }
   const glyphs = parseIconNodes(await response.text());
@@ -165,8 +202,47 @@ export async function buildIcons(): Promise<number> {
   return glyphs.size;
 }
 
+/** A plain `major.minor.patch` — the only shape allowed into a TypeScript string literal here. */
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+/** `source` with its `LUCIDE_VERSION` line moved to `version`. Pure; refuses rather than guesses. */
+export function withPin(source: string, version: string): string {
+  if (!SEMVER.test(version)) {
+    throw invalidIconDataError(
+      `answered ${renderCauseValue(version)} as the latest lucide-static version, which is not plain semver; ${LUCIDE_LATEST_URL} served something else`,
+      'bun run --filter @ultimat3/ui icons --bump',
+    );
+  }
+  const pin = /^export const LUCIDE_VERSION = '[^']*';$/m;
+  if (!pin.test(source)) {
+    throw invalidIconDataError(
+      'has no `export const LUCIDE_VERSION = …` line in packages/ui/src/icons/build-icons.ts to move',
+      'git checkout -- packages/ui/src/icons/build-icons.ts',
+    );
+  }
+  return source.replace(pin, `export const LUCIDE_VERSION = '${version}';`);
+}
+
+/** Moves the pin to the registry's latest release, in this very file, and answers the version. */
+async function bumpPin(): Promise<string> {
+  const response = await fetch(LUCIDE_LATEST_URL);
+  if (!response.ok) {
+    throw runtimeMissingError(
+      `the latest lucide-static version (HTTP ${response.status} from ${LUCIDE_LATEST_URL})`,
+      'bun run --filter @ultimat3/ui icons --bump',
+    );
+  }
+  const body: unknown = await response.json();
+  const version =
+    typeof body === 'object' && body !== null && 'version' in body ? String(body.version) : '';
+  const file = new URL(import.meta.url).pathname;
+  await Bun.write(file, withPin(await Bun.file(file).text(), version));
+  return version;
+}
+
 if (import.meta.main) {
-  const count = await buildIcons();
-  const json = { ok: true, icons: count, lucide: LUCIDE_VERSION, dir: GLYPHS_DIR };
+  const version = Bun.argv.includes('--bump') ? await bumpPin() : LUCIDE_VERSION;
+  const count = await buildIcons(version);
+  const json = { ok: true, icons: count, lucide: version, dir: GLYPHS_DIR };
   console.log(Bun.argv.includes('--json') ? JSON.stringify(json) : `${count} icon modules written`);
 }

package/src/index.ts

@@ -89,7 +89,12 @@ export {
   settleActive,
   stepActive,
 } from './components/command-palette-view';
-export type { Column, DataTableProps } from './components/DataTable';
+export type {
+  Column,
+  DataTableCallbackProps,
+  DataTableLinkProps,
+  DataTableProps,
+} from './components/DataTable';
 export { DataTable } from './components/DataTable';
 export type { DateTimeProps } from './components/DateTime';
 export { DateTime } from './components/DateTime';
@@ -160,7 +165,7 @@ export { boxFor, reservedRatio, sourceSetsFor, srcsetFor } from './components/im
 export type { LoadMoreInput, LoadMoreState } from './components/infinite-scroll-view';
 export type { KbdProps } from './components/Kbd';
 export { Kbd } from './components/Kbd';
-export type { LinkProps } from './components/Link';
+export type { ButtonLinkProps, LinkProps, TextLinkProps } from './components/Link';
 export { Link } from './components/Link';
 export type { LocaleSwitcherProps } from './components/LocaleSwitcher';
 export { LocaleSwitcher, localeLabel } from './components/LocaleSwitcher';
@@ -176,7 +181,11 @@ export type { MoneyFormatter, MoneyInput, MoneyViewOptions } from './components/
 export { moneyText, toMoney } from './components/money-view';
 export type { PageHeaderProps } from './components/PageHeader';
 export { PageHeader } from './components/PageHeader';
-export type { PaginationProps } from './components/Pagination';
+export type {
+  PaginationCallbackProps,
+  PaginationLinkProps,
+  PaginationProps,
+} from './components/Pagination';
 export { Pagination } from './components/Pagination';
 export type { Placement, PopoverProps } from './components/Popover';
 export { Popover } from './components/Popover';
@@ -303,12 +312,6 @@ export {
   useUi,
 } from './theme/context';
 export { INERT_SOLID_RUNTIME } from './theme/inert-runtime';
-export {
-  THEME_INLINE_SCRIPT,
-  themeInlineScriptCspSource,
-  themeInlineScriptHash,
-  themeInlineScriptTag,
-} from './theme/inline-script';
 export type { UiProviderProps } from './theme/provider';
 export { UiProvider } from './theme/provider';
 // The slot is its own module so that registering a runtime does not drag `errors.ts` — and with it
@@ -321,6 +324,7 @@ export type { ThemeEnv } from './theme/theme';
 export {
   browserThemeEnv,
   clearTheme,
+  defaultTheme,
   initTheme,
   isTheme,
   osTheme,
@@ -328,6 +332,7 @@ export {
   setTheme,
   storedTheme,
   THEME_ATTRIBUTE,
+  THEME_DEFAULT_ATTRIBUTE,
   THEME_MEDIA_QUERY,
   THEME_STORAGE_KEY,
   toggleTheme,
@@ -378,5 +383,6 @@ export {
   radiusTokens,
   shadowTokens,
   spaceTokens,
+  strokeTokens,
   zTokens,
 } from './tokens/tokens';

package/src/sass-probe.ts

@@ -0,0 +1,55 @@
+// TEST-ONLY. Compiles a stylesheet with the compiler an app's build uses, so a test can read what
+// Sass EMITS — a media query, a `clamp()`, the class list a mixin generates, an `@error` — instead
+// of the source it was written as. Never exported from `index.ts`, like `jsx-probe.ts`.
+
+/** The two members of Sass's API this file calls; the package itself is not a dependency of `ui`. */
+interface SassApi {
+  compileString(source: string, options: { readonly url: URL }): { readonly css: string };
+}
+
+let loading: Promise<SassApi> | undefined;
+
+/**
+ * `sass` is `@ultimat3/render`'s dependency — the package that compiles an app's sheets — and `ui`
+ * may not import `render` (tier 4, both). Resolved FROM render's directory, so a test compiles with
+ * the one compiler at the one version the lockfile pins and `ui` declares no second copy. Only a
+ * specifier is read from render; no module of it loads. Lazy, so importing this file has no effect.
+ */
+function sassCompiler(): Promise<SassApi> {
+  loading ??= import(
+    Bun.resolveSync('sass', new URL('../../render', import.meta.url).pathname)
+  ) as Promise<SassApi>;
+  return loading;
+}
+
+/** Compile `source` as though it were the file at `path`, so its relative `@use`s resolve. */
+export async function compileScss(source: string, path: string): Promise<string> {
+  const sass = await sassCompiler();
+  return sass.compileString(source, { url: new URL(`file://${path}`) }).css;
+}
+
+/** Compile a stylesheet that exists on disk. */
+export async function compileScssFile(path: string): Promise<string> {
+  return compileScss(await Bun.file(path).text(), path);
+}
+
+/**
+ * The `@error` text Sass refused `source` with, or `undefined` when it compiled. A refusal that is
+ * not Sass's own — the compiler failing to load — is rethrown: it is not an answer about `source`.
+ */
+export async function scssRefusal(source: string, path: string): Promise<string | undefined> {
+  try {
+    await compileScss(source, path);
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'sassMessage' in error) {
+      return String(error.sassMessage);
+    }
+    throw error;
+  }
+  return undefined;
+}
+
+/** Every class a compiled stylesheet declares. */
+export function declaredClasses(css: string): ReadonlySet<string> {
+  return new Set([...css.matchAll(/\.([A-Za-z][\w-]*)/g)].map((match) => match[1] as string));
+}

package/src/theme/brand.ts

@@ -72,10 +72,11 @@ export function defineTheme(input: BrandInput): Brand {
   // `html[data-theme]`. A brand that only wrote `:root` would lose to those attribute rules on
   // specificity, so every level it emits is answered here, in the same order.
   if (light.length > 0) blocks.push(rule("html[data-theme='light']", light));
-  if (dark.length > 0) {
-    blocks.push(`@media (prefers-color-scheme: dark) {\n${indent(rule(':root', dark))}\n}`);
-    blocks.push(rule("html[data-theme='dark']", dark));
+  const media = darkMediaDeclarations(input.colors);
+  if (media.length > 0) {
+    blocks.push(`@media (prefers-color-scheme: dark) {\n${indent(rule(':root', media))}\n}`);
   }
+  if (dark.length > 0) blocks.push(rule("html[data-theme='dark']", dark));
 
   return Object.freeze({ css: blocks.join('\n\n') });
 }
@@ -111,6 +112,24 @@ function indent(block: string): string {
     .join('\n');
 }
 
+/**
+ * The dark media `:root` must answer every role the brand's own `:root` touched. That `:root`
+ * (light) comes after `theme.scss`'s dark media `:root` at equal specificity, so a role overridden
+ * in light only would otherwise reach an OS-dark document with no `data-theme` — scripting off, or
+ * storage throwing in the boot script — on the dark palette it was never measured against. Such a
+ * role is answered with the SHIPPED dark channels. Called after both scopes were validated.
+ */
+function darkMediaDeclarations(colors: BrandInput['colors']): string[] {
+  const out: string[] = [];
+  for (const role of COLOR_ROLES) {
+    const value =
+      colors?.dark?.[role] ??
+      (colors?.light?.[role] === undefined ? undefined : colorTokens.dark[role]);
+    if (value !== undefined) out.push(`--color-${role}: ${value};`);
+  }
+  return out;
+}
+
 /**
  * Ordered by the canonical role list, not by the caller's object — a brand file rendered twice
  * must be byte-identical, or every consumer's CSP hash and diff churns for nothing.

package/src/theme/theme.ts

@@ -1,6 +1,6 @@
-// Theme resolution. One rule: an explicit choice in storage wins, otherwise the
-// OS decides. Every side effect goes through an injected `ThemeEnv`, so this is
-// testable without a DOM and reusable on the server.
+// Theme resolution. One rule: an explicit choice in storage wins, then the theme the boot script
+// already stamped on the document, then the app's `theme.defaultMode` (the OS for `'system'`). Every side effect
+// goes through an injected `ThemeEnv`, so this is testable without a DOM and reusable on the server.
 
 import { invalidThemeError, runtimeMissingError } from '../errors';
 import type { Theme } from '../tokens/tokens';
@@ -9,11 +9,18 @@ export type { Theme };
 
 export const THEME_STORAGE_KEY = 'ultimate.theme';
 export const THEME_ATTRIBUTE = 'data-theme';
+/** Where the boot script records `theme.defaultMode` itself — `'light'`, `'dark'` or `'system'`.
+ *  `@ultimat3/render`'s `themeScriptBody` writes `${attribute}-default`; this is that name. */
+export const THEME_DEFAULT_ATTRIBUTE = `${THEME_ATTRIBUTE}-default`;
 export const THEME_MEDIA_QUERY = '(prefers-color-scheme: dark)';
 
 /** The host capabilities theme control needs. Injected so tests need no DOM. */
 export interface ThemeEnv {
   read(): string | null;
+  /** The theme the document carries right now — what the boot script stamped, or the last apply. */
+  current(): string | null;
+  /** The app's `theme.defaultMode` as the boot stamped it, or `null` when no boot ran. */
+  appDefault(): string | null;
   write(value: string): void;
   remove(): void;
   prefersDark(): boolean;
@@ -40,9 +47,25 @@ export function osTheme(env: ThemeEnv): Theme {
   return env.prefersDark() ? 'dark' : 'light';
 }
 
-/** Resolution order: explicit stored choice -> OS preference. */
+/**
+ * What "no explicit choice" means for this app: its fixed `theme.defaultMode` when it has one, the
+ * OS when it is `'system'` or unknown. Clearing a choice and following the OS both answer this, so
+ * an app that opens dark is never flipped light by an OS change or a "system" pick.
+ */
+export function defaultTheme(env: ThemeEnv): Theme {
+  const fixed = env.appDefault();
+  return isTheme(fixed) ? fixed : osTheme(env);
+}
+
+/**
+ * Resolution order: explicit stored choice -> the theme on the document -> OS preference. The
+ * middle step is the app's default: with `theme.defaultMode: 'dark'` the boot script stamps dark
+ * on a light-OS machine, and answering the OS here made the first toggle write the theme already
+ * on screen — a click that did nothing.
+ */
 export function resolveTheme(env: ThemeEnv): Theme {
-  return storedTheme(env) ?? osTheme(env);
+  const current = env.current();
+  return storedTheme(env) ?? (isTheme(current) ? current : defaultTheme(env));
 }
 
 /** Run once on load. Idempotent — safe after the inline head script. */
@@ -60,10 +83,10 @@ export function setTheme(theme: Theme, env: ThemeEnv = browserThemeEnv()): Theme
   return theme;
 }
 
-/** Forget the explicit choice and follow the OS again. */
+/** Forget the explicit choice and return to the app's default (the OS, for `'system'`). */
 export function clearTheme(env: ThemeEnv = browserThemeEnv()): Theme {
   env.remove();
-  const theme = osTheme(env);
+  const theme = defaultTheme(env);
   env.apply(theme);
   return theme;
 }
@@ -74,12 +97,12 @@ export function toggleTheme(env: ThemeEnv = browserThemeEnv()): Theme {
 }
 
 /**
- * Follow the OS live — but only while the user has made no explicit choice.
- * Returns an unsubscribe so a component can drop it on cleanup.
+ * Follow the OS live — but only while the user has made no explicit choice AND the app's default
+ * is the OS. Returns an unsubscribe so a component can drop it on cleanup.
  */
 export function watchOsTheme(env: ThemeEnv = browserThemeEnv()): () => void {
   return env.observeOs(() => {
-    if (storedTheme(env) === null) env.apply(osTheme(env));
+    if (storedTheme(env) === null && !isTheme(env.appDefault())) env.apply(osTheme(env));
   });
 }
 
@@ -94,6 +117,8 @@ export function browserThemeEnv(): ThemeEnv {
   const media = window.matchMedia(THEME_MEDIA_QUERY);
   return {
     read: () => safeStorage(() => window.localStorage.getItem(THEME_STORAGE_KEY), null),
+    current: () => document.documentElement.getAttribute(THEME_ATTRIBUTE),
+    appDefault: () => document.documentElement.getAttribute(THEME_DEFAULT_ATTRIBUTE),
     write: (value) => safeStorage(() => window.localStorage.setItem(THEME_STORAGE_KEY, value)),
     remove: () => safeStorage(() => window.localStorage.removeItem(THEME_STORAGE_KEY)),
     prefersDark: () => media.matches,

package/src/tokens/_index.scss

@@ -1,5 +1,5 @@
 // Single entry point for authors: `@use '../tokens' as t;` then `t.role('bg')`,
-// `t.space(4)`, `@include t.focus-ring`. Forwards maps, functions, and mixins —
+// `t.space(4)`, `t.rem(24px)`, `@include t.focus-ring`. Forwards maps, functions, and mixins —
 // emits no CSS. Global custom properties come from `theme.scss`.
 
 @forward 'breakpoints';
@@ -8,6 +8,8 @@
 @forward 'radius' hide emit;
 @forward 'shadow' hide emit, levels;
 @forward 'space' hide emit;
+@forward 'stroke' hide emit;
 @forward 'typography' hide emit;
+@forward 'units';
 @forward 'z' hide emit;
 @forward 'mixins';

package/src/tokens/_mixins.scss

@@ -4,15 +4,22 @@
 
 @use 'sass:list';
 @use 'sass:map';
+@use 'sass:string';
 @use 'breakpoints';
 @use 'colors';
 @use 'motion';
 @use 'radius';
 @use 'space';
+@use 'stroke';
 @use 'typography';
+@use 'units';
 
 /// Keyboard-only focus, drawn from the accent role so it themes automatically.
-@mixin focus-ring($role: 'accent', $width: 2px, $offset: 2px) {
+@mixin focus-ring(
+  $role: 'accent',
+  $width: stroke.stroke(thick),
+  $offset: stroke.stroke(thick)
+) {
   &:focus-visible {
     outline: $width solid colors.role($role);
     outline-offset: $offset;
@@ -81,13 +88,54 @@
   container-name: $name;
 }
 
-/// Viewport breakpoint, min-width only. Named rungs, never a raw px value.
+// --- Viewport breakpoints ----------------------------------------------------
+// Three intents over ONE map, so a rung is defined in one place: at and above (`respond-to`),
+// below (`respond-down`), and from one rung up to the next (`respond-between`). Prefer a container
+// query to any of them — reach here only when the layout depends on the viewport itself.
+
+/// What a max-width arm stops short of its rung by. `max-width: 768px` and `min-width: 768px` both
+/// match at exactly 768px, which is how one rule ends up applying in two ranges at once; 0.02px is
+/// below any width a browser reports and above the rounding that would collapse it.
+$-under: 0.02px;
+
+/// A rung's width. Compared as TEXT as well as by value: `2xl` in a map is the number 2 with the
+/// unit `xl`, so the string `'2xl'` every stylesheet writes is a different key to `map.get`.
+@function -rung($bp, $mixin) {
+  @each $name, $width in breakpoints.$breakpoints {
+    @if '#{$name}' == '#{$bp}' {
+      @return $width;
+    }
+  }
+  @error string.unquote('X_TOKEN_UNKNOWN: #{$mixin}("#{$bp}") — that breakpoint is not in $breakpoints. fix: use one of #{map.keys(breakpoints.$breakpoints)}');
+}
+
+/// At a rung and wider. Named rungs, never a raw px value.
 @mixin respond-to($bp) {
-  @if not map.has-key(breakpoints.$breakpoints, $bp) {
-    @error 'X_TOKEN_UNKNOWN: breakpoint "#{$bp}" is not in $breakpoints. fix: add it to src/tokens/_breakpoints.scss';
+  @media (min-width: -rung($bp, 'respond-to')) {
+    @content;
+  }
+}
+
+/// Narrower than a rung — the complement of `respond-to` on the same rung, with no shared pixel.
+@mixin respond-down($bp) {
+  @media (max-width: (-rung($bp, 'respond-down') - $-under)) {
+    @content;
+  }
+}
+
+/// From `$from` up to, and not including, `$to`.
+@mixin respond-between($from, $to) {
+  $min: -rung($from, 'respond-between');
+  $max: -rung($to, 'respond-between');
+
+  @if $min == $max {
+    @error string.unquote('X_UI_INVALID_VALUE: respond-between("#{$from}", "#{$to}") is an empty range — both ends are #{$min}. fix: write respond-to("#{$from}"), or name a higher rung as $to');
+  }
+  @if $min > $max {
+    @error string.unquote('X_UI_INVALID_VALUE: respond-between("#{$from}", "#{$to}") is reversed — #{$min} is not below #{$max}. fix: write respond-between("#{$to}", "#{$from}")');
   }
 
-  @media (min-width: map.get(breakpoints.$breakpoints, $bp)) {
+  @media (min-width: $min) and (max-width: ($max - $-under)) {
     @content;
   }
 }
@@ -156,8 +204,8 @@
   scrollbar-color: colors.role($thumb) colors.role($track);
 
   &::-webkit-scrollbar {
-    width: 10px;
-    height: 10px;
+    width: units.rem(10px);
+    height: units.rem(10px);
   }
 
   &::-webkit-scrollbar-track {
@@ -165,7 +213,7 @@
   }
 
   &::-webkit-scrollbar-thumb {
-    border: 2px solid transparent;
+    border: stroke.stroke(thick) solid transparent;
     border-radius: radius.radius(pill);
     background: colors.role($thumb);
     background-clip: content-box;

package/src/tokens/_motion.scss

@@ -16,6 +16,10 @@ $easing: (
   spring: cubic-bezier(0.34, 1.56, 0.64, 1),
 );
 
+/// What reduced motion collapses every duration to. Never `0`: an animation that takes no time
+/// fires no `animationend`, and a component waiting on that event waits forever.
+$still: 0.01ms;
+
 @mixin emit {
   :root {
     @each $name, $value in $duration {

package/src/tokens/_stroke.scss

@@ -0,0 +1,20 @@
+// Line weights: a border, an outline, a focus ring, an indicator. px on purpose — a line that
+// grew with the reader's text size would be a different design at 200% zoom, not a bigger one.
+
+$stroke: (
+  hairline: 1px,
+  thick: 2px,
+  heavy: 3px,
+);
+
+@mixin emit {
+  :root {
+    @each $name, $value in $stroke {
+      --stroke-#{$name}: #{$value};
+    }
+  }
+}
+
+@function stroke($name) {
+  @return var(--stroke-#{$name});
+}