@celestia-island/hikari 0.4.4 → 0.30.0

package/src/styles/theme/themes.scss

@@ -0,0 +1,25 @@
+// Vendored byte-identical from packages/theme/styles/themes.scss (hikari repo) so npm registry installs can resolve it — edit the upstream file, then re-copy; do not hand-edit here.
+// hikari-theme/styles/themes.scss
+// 主题变体（使用 hikari-palette）
+
+@use './variables.scss' as *;
+
+// ------
+// 响应式主题切换
+// ------
+
+@media (prefers-color-scheme: dark) {
+    :root:not([data-theme="fresh"]) {
+        --hi-color-background: #0F172A;
+        --hi-color-surface: #1E293B;
+        --hi-color-text-primary: rgba(255, 255, 255, 0.9);
+        --hi-color-text-secondary: rgba(255, 255, 255, 0.6);
+        --hi-color-text-on-primary: rgba(0, 0, 0, 0.9);
+        --hi-color-text-on-secondary: var(--hi-color-white-100);
+        --hi-color-text-on-ghost: rgba(255, 255, 255, 0.9);
+        --hi-color-text-on-danger: var(--hi-color-white-100);
+        --hi-color-text-on-success: rgba(0, 0, 0, 0.9);
+        --hi-color-text-on-warning: rgba(0, 0, 0, 0.9);
+        --hi-color-text-on-info: rgba(0, 0, 0, 0.9);
+    }
+}

package/src/styles/theme/variables.scss

@@ -0,0 +1,125 @@
+// Vendored byte-identical from packages/theme/styles/variables.scss (hikari repo) so npm registry installs can resolve it — edit the upstream file, then re-copy; do not hand-edit here.
+// hikari-theme/styles/variables.scss
+// CSS 变量（使用 hikari-palette）
+
+// ------
+// 1. Color System
+// ------
+// Colors are defined via CSS variables in the index.scss
+// and by the hikari-palette crate
+
+// ------
+// 2. Typography Variables
+// ------
+
+/* Apple-style stack + CJK UI tail — keep in sync with packages/vue/src/theme/fontContext.ts */
+$hikari-font-family-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
+$hikari-font-family-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", "Liberation Mono", "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", monospace;
+
+$hikari-font-size-xs: 0.75rem;
+$hikari-font-size-sm: 0.875rem;
+$hikari-font-size-base: 1rem;
+$hikari-font-size-lg: 1.125rem;
+$hikari-font-size-xl: 1.25rem;
+$hikari-font-size-2xl: 1.5rem;
+$hikari-font-size-3xl: 1.875rem;
+
+// ------
+// 间距变量
+// ------
+
+$hikari-spacing-xs: 0.25rem;
+$hikari-spacing-sm: 0.5rem;
+$hikari-spacing-md: 1rem;
+$hikari-spacing-lg: 1.5rem;
+$hikari-spacing-xl: 2rem;
+$hikari-spacing-2xl: 3rem;
+
+// ------
+// 圆角变量
+// ------
+
+$hikari-radius-sm: 0.25rem;
+$hikari-radius-md: 0.5rem;
+$hikari-radius-lg: 0.75rem;
+$hikari-radius-xl: 1rem;
+$hikari-radius-full: 9999px;
+
+// ------
+// 阴影变量
+// ------
+
+$hikari-shadow-sm: var(--hi-shadow-sm);
+$hikari-shadow-md: var(--hi-shadow-md);
+$hikari-shadow-lg: var(--hi-shadow-lg);
+$hikari-shadow-xl: var(--hi-shadow-xl);
+
+// ------
+// 过渡变量
+// ------
+
+$hikari-transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+$hikari-transition-base: 200ms cubic-bezier(0.4, 0, 0.2, 1);
+$hikari-transition-slow: 300ms cubic-bezier(0.4, 0, 0.2, 1);
+
+// ------
+// FUI 设计系统变量
+// ------
+
+// 亚克力效果参数
+$hikari-acrylic-blur: 20px;
+$hikari-acrylic-noise: 0.5;
+$hikari-acrylic-opacity: 0.85;
+
+// 发光效果参数
+$hikari-glow-sm: var(--hi-glow-sm);
+$hikari-glow-md: var(--hi-glow-md);
+$hikari-glow-lg: var(--hi-glow-lg);
+$hikari-glow-focus: var(--hi-glow-focus);
+
+// 强调色条参数
+$hikari-accent-bar-width: 3px;
+$hikari-accent-bar-position: left; // left, right, top, bottom
+
+// 细微圆角（FUI 风格）
+$hikari-radius-fui-sm: 4px;
+$hikari-radius-fui-md: 6px;
+$hikari-radius-fui-lg: 8px;
+
+// 边框发光
+$hikari-border-glow-color: var(--hi-border-glow);
+$hikari-border-glow-width: var(--hi-border-glow-width);
+
+// 动画缓动函数（GSAP 风格）
+$hikari-ease-smooth: cubic-bezier(0.25, 0.1, 0.25, 1);
+$hikari-ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
+$hikari-ease-elastic: cubic-bezier(0.5, 1.5, 0.5, 1);
+
+// 动画时长
+$hikari-duration-instant: 100ms;
+$hikari-duration-fast: 200ms;
+$hikari-duration-normal: 300ms;
+$hikari-duration-slow: 500ms;
+
+// 背景微动参数
+$hikari-ambient-duration: 8s;
+$hikari-ambient-easing: ease-in-out;
+
+// ------
+// Icon Button 尺寸变量
+// ------
+
+$hikari-icon-button-size-16: 16px;
+$hikari-icon-button-size-24: 24px;
+$hikari-icon-button-size-32: 32px;
+$hikari-icon-button-size-36: 36px;
+
+// ------
+// 常用图标尺寸变量
+// ------
+
+$hikari-icon-size-xs: 12px;
+$hikari-icon-size-sm: 14px;
+$hikari-icon-size-md: 16px;
+$hikari-icon-size-lg: 20px;
+$hikari-icon-size-xl: 24px;

package/src/theme/_field.scss

@@ -0,0 +1,116 @@
+@mixin field-wrapper {
+  display: block;
+  width: 100%;
+}
+
+@mixin field-label {
+  display: block;
+  font-size: var(--text-base);
+  font-weight: 500;
+  margin-bottom: var(--space-6);
+  color: rgb(var(--color-text));
+}
+
+@mixin field-required {
+  margin-left: var(--space-2);
+  color: rgb(var(--color-error));
+}
+
+@mixin field-box {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--space-6);
+  padding: var(--space-8) var(--space-12);
+  min-height: 2.5rem;
+  background: color-mix(in srgb, rgb(var(--color-surface)) 55%, transparent);
+  border: 1px solid color-mix(in srgb, rgb(var(--color-text)) 14%, transparent);
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  transition: background-color, border-color, color, box-shadow, opacity, transform, filter var(--duration-normal) var(--ease-standard);
+  color: rgb(var(--color-text));
+}
+
+@mixin field-box-hover($disabled-selector) {
+  &:hover:not(#{$disabled-selector}) {
+    border-color: var(--c-primary-strong);
+  }
+}
+
+@mixin field-box-focused {
+  border-color: rgb(var(--color-focused-border));
+  box-shadow: var(--shadow-focus);
+  background: rgb(var(--color-surface));
+}
+
+@mixin field-box-error {
+  border-color: var(--c-error-strong);
+}
+
+@mixin field-box-error-focused {
+  border-color: rgb(var(--color-error));
+  box-shadow: var(--shadow-focus-error);
+}
+
+@mixin field-box-disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+@mixin field-placeholder {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+  user-select: none;
+  font-size: var(--text-base);
+  padding: var(--space-8) var(--space-12);
+  color: color-mix(in srgb, rgb(var(--color-muted)) 70%, rgb(var(--color-background)));
+}
+
+@mixin field-error-msg {
+  margin-top: var(--space-4);
+  font-size: var(--text-xs);
+  color: rgb(var(--color-error));
+}
+
+@mixin field-hint {
+  margin-top: var(--space-4);
+  font-size: var(--text-xs);
+  color: color-mix(in srgb, rgb(var(--color-muted)) 70%, rgb(var(--color-background)));
+}
+
+@mixin field-autofill-overrides($box-class) {
+  .#{$box-class} input,
+  .#{$box-class} textarea {
+    transition: color calc(infinity * 1s) step-end, background-color calc(infinity * 1s) step-end;
+  }
+
+  .#{$box-class} input:-webkit-autofill,
+  .#{$box-class} input:-webkit-autofill:hover,
+  .#{$box-class} input:-webkit-autofill:focus,
+  .#{$box-class} input:-webkit-autofill:active,
+  .#{$box-class} textarea:-webkit-autofill,
+  .#{$box-class} textarea:-webkit-autofill:hover,
+  .#{$box-class} textarea:-webkit-autofill:focus {
+    -webkit-text-fill-color: rgb(var(--color-text)) !important;
+    -webkit-box-shadow: 0 0 0 1000px rgb(var(--color-surface)) inset !important;
+    caret-color: rgb(var(--color-text));
+  }
+
+  .#{$box-class} input:-webkit-autofill::first-line,
+  .#{$box-class} textarea:-webkit-autofill::first-line {
+    font-size: inherit !important;
+    font-family: inherit !important;
+    color: rgb(var(--color-text));
+  }
+
+  .#{$box-class} input:-internal-autofill-previewed,
+  .#{$box-class} input:-internal-autofill-selected {
+    -webkit-text-fill-color: rgb(var(--color-text)) !important;
+    -webkit-box-shadow: 0 0 0 1000px rgb(var(--color-surface)) inset !important;
+    caret-color: rgb(var(--color-text));
+  }
+}

package/src/theme/fontContext.test.ts

@@ -0,0 +1,179 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// The module keeps singleton state (initialized flag + refs), so every
+// test gets a fresh module instance via vi.resetModules + dynamic import.
+type FontContextModule = typeof import("./fontContext");
+
+describe("fontContext", () => {
+  let fc: FontContextModule;
+
+  const el = () => document.documentElement;
+  const applied = (name: string) => el().style.getPropertyValue(name);
+
+  beforeEach(async () => {
+    vi.resetModules();
+    localStorage.clear();
+    el().style.cssText = "";
+    el().removeAttribute("data-font-context");
+    fc = await import("./fontContext");
+  });
+
+  it("init applies the default stacks as inline vars and sets data-font-context", () => {
+    fc.initFontContext();
+    expect(applied("--font-sans")).toBe(fc.HIKARI_FONT_SANS);
+    expect(applied("--font-mono")).toBe(fc.HIKARI_FONT_MONO);
+    expect(applied("--font-reading")).toBe(fc.HIKARI_FONT_READING);
+    expect(el().getAttribute("data-font-context")).toBe("on");
+  });
+
+  it("is idempotent: a repeated bare init does not fall back to defaults", () => {
+    localStorage.setItem(
+      "hikari-font-context",
+      JSON.stringify({ sans: '"Stored Sans", sans-serif' }),
+    );
+    fc.initFontContext();
+    fc.initFontContext();
+    fc.initFontContext();
+    expect(applied("--font-sans")).toBe('"Stored Sans", sans-serif');
+  });
+
+  it("applies localStorage overrides", () => {
+    localStorage.setItem(
+      "hikari-font-context",
+      JSON.stringify({
+        sans: '"A Sans", sans-serif',
+        mono: '"A Mono", monospace',
+        reading: '"A Reading", serif',
+      }),
+    );
+    fc.initFontContext();
+    expect(applied("--font-sans")).toBe('"A Sans", sans-serif');
+    expect(applied("--font-mono")).toBe('"A Mono", monospace');
+    expect(applied("--font-reading")).toBe('"A Reading", serif');
+  });
+
+  it("explicit options beat stored overrides on first init", () => {
+    localStorage.setItem(
+      "hikari-font-context",
+      JSON.stringify({ sans: '"Stored Sans", sans-serif' }),
+    );
+    fc.initFontContext({ sans: '"Explicit Sans", sans-serif' });
+    expect(applied("--font-sans")).toBe('"Explicit Sans", sans-serif');
+  });
+
+  it("merges explicit options from a repeated init", () => {
+    fc.initFontContext();
+    fc.initFontContext({ mono: '"Later Mono", monospace' });
+    expect(applied("--font-mono")).toBe('"Later Mono", monospace');
+    expect(applied("--font-sans")).toBe(fc.HIKARI_FONT_SANS);
+  });
+
+  it("rejects injection-shaped values and falls back to the next source", () => {
+    localStorage.setItem(
+      "hikari-font-context",
+      JSON.stringify({
+        sans: 'evil; } { --',
+        mono: "",
+        reading: "x".repeat(501),
+      }),
+    );
+    fc.initFontContext({ sans: '"Also; Evil", sans-serif' });
+    // sans: explicit rejected → stored rejected → default.
+    expect(applied("--font-sans")).toBe(fc.HIKARI_FONT_SANS);
+    // mono/reading: stored rejected → default.
+    expect(applied("--font-mono")).toBe(fc.HIKARI_FONT_MONO);
+    expect(applied("--font-reading")).toBe(fc.HIKARI_FONT_READING);
+  });
+
+  it("explicit options rejected by sanitization fall through to the stored override", () => {
+    localStorage.setItem(
+      "hikari-font-context",
+      JSON.stringify({ sans: '"Good Sans", sans-serif' }),
+    );
+    fc.initFontContext({ sans: '"Bad; Sans"' });
+    expect(applied("--font-sans")).toBe('"Good Sans", sans-serif');
+  });
+
+  it("ignores malformed stored JSON", () => {
+    localStorage.setItem("hikari-font-context", "{not json");
+    fc.initFontContext();
+    expect(applied("--font-sans")).toBe(fc.HIKARI_FONT_SANS);
+  });
+
+  it("exposes refs whose setters persist and re-apply", () => {
+    fc.initFontContext();
+    const ctx = fc.useFontContext();
+    ctx.setSans('"My Sans", sans-serif');
+    expect(ctx.sans.value).toBe('"My Sans", sans-serif');
+    expect(applied("--font-sans")).toBe('"My Sans", sans-serif');
+    const stored = JSON.parse(localStorage.getItem("hikari-font-context") ?? "{}");
+    expect(stored.sans).toBe('"My Sans", sans-serif');
+  });
+
+  it("setter rejects unsanitizable values without persisting", () => {
+    fc.initFontContext();
+    const ctx = fc.useFontContext();
+    ctx.setSans('"Bad; Sans"');
+    expect(ctx.sans.value).toBe(fc.HIKARI_FONT_SANS);
+    expect(applied("--font-sans")).toBe(fc.HIKARI_FONT_SANS);
+    expect(localStorage.getItem("hikari-font-context")).toBeNull();
+  });
+
+  it("reset clears storage and restores the built-in defaults", () => {
+    fc.initFontContext();
+    const ctx = fc.useFontContext();
+    ctx.setMono('"My Mono", monospace');
+    expect(applied("--font-mono")).toBe('"My Mono", monospace');
+    ctx.reset();
+    expect(localStorage.getItem("hikari-font-context")).toBeNull();
+    expect(applied("--font-mono")).toBe(fc.HIKARI_FONT_MONO);
+    expect(ctx.mono.value).toBe(fc.HIKARI_FONT_MONO);
+    expect(el().getAttribute("data-font-context")).toBe("on");
+  });
+
+  it("applyFontContext re-applies the current state over DOM mutations", () => {
+    fc.initFontContext();
+    el().style.setProperty("--font-sans", "junk");
+    fc.applyFontContext();
+    expect(applied("--font-sans")).toBe(fc.HIKARI_FONT_SANS);
+  });
+
+  it("is a safe no-op in non-browser environments", () => {
+    vi.stubGlobal("document", undefined);
+    try {
+      expect(() => fc.initFontContext({ sans: '"X", sans-serif' })).not.toThrow();
+      expect(() => fc.applyFontContext()).not.toThrow();
+      expect(() => fc.resetFontContext()).not.toThrow();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("default stacks lead with the Apple-style system heads", () => {
+    expect(fc.HIKARI_FONT_SANS.startsWith("-apple-system, BlinkMacSystemFont")).toBe(true);
+    expect(fc.HIKARI_FONT_MONO.startsWith(`ui-monospace, "SF Mono"`)).toBe(true);
+  });
+
+  it("default stacks carry the required CJK UI faces", () => {
+    const required = ["PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC"];
+    for (const stack of [fc.HIKARI_FONT_SANS, fc.HIKARI_FONT_MONO]) {
+      for (const face of required) {
+        expect(stack.toLowerCase()).toContain(face.toLowerCase());
+      }
+    }
+  });
+
+  it("default stacks never name a kai or serif face", () => {
+    const banned = ["KaiTi", "STKaiti", "Kaiti SC", "SimSun", "Songti", "Noto Serif", "Source Han Serif"];
+    for (const stack of [fc.HIKARI_FONT_SANS, fc.HIKARI_FONT_MONO, fc.HIKARI_FONT_READING]) {
+      for (const face of banned) {
+        // Assert absence of the whole quoted family name, case-insensitively.
+        expect(stack.toLowerCase()).not.toContain(`"${face.toLowerCase()}"`);
+      }
+    }
+  });
+
+  it("reading defaults to the UI sans stack", () => {
+    expect(fc.HIKARI_FONT_READING).toBe(fc.HIKARI_FONT_SANS);
+  });
+});

package/src/theme/fontContext.ts

@@ -0,0 +1,169 @@
+import { ref, type Ref } from "vue";
+
+// fontContext.ts — bootstrap-level font facility, distributed like the
+// startup hooks (initTheme / applyViewportPolicy): every webui calls
+// initFontContext() once at bootstrap and the canonical stacks land as
+// inline CSS vars on document.documentElement, so no app has to restate
+// font-family literals.
+
+// Apple-style system stack; the CJK tail keeps non-Apple platforms off kai-style last-resort fallbacks.
+// Kai/serif faces are deliberately never listed.
+export const HIKARI_FONT_SANS = `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif`;
+export const HIKARI_FONT_MONO = `ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", "Liberation Mono", "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", monospace`;
+export const HIKARI_FONT_READING = HIKARI_FONT_SANS;
+
+export interface FontContextOverrides {
+  sans?: string;
+  mono?: string;
+  reading?: string;
+}
+
+const STORAGE_KEY = "hikari-font-context";
+const MAX_VALUE_LENGTH = 500;
+// CSS-injection guard: font-family lists never need these characters.
+const FORBIDDEN_CHARS = /[;{}]/;
+
+type FontSlot = keyof FontContextOverrides;
+
+const FONT_VAR: Record<FontSlot, string> = {
+  sans: "--font-sans",
+  mono: "--font-mono",
+  reading: "--font-reading",
+};
+
+// Shared singleton state (mirrors useTheme's module-level refs): every
+// useFontContext() call in the app sees the same stacks.
+const sansRef = ref<string>(HIKARI_FONT_SANS);
+const monoRef = ref<string>(HIKARI_FONT_MONO);
+const readingRef = ref<string>(HIKARI_FONT_READING);
+
+function slotRef(slot: FontSlot): Ref<string> {
+  return slot === "sans" ? sansRef : slot === "mono" ? monoRef : readingRef;
+}
+
+function isBrowser(): boolean {
+  return typeof document !== "undefined";
+}
+
+// Sanitize a candidate value: empty, over-long, or injection-shaped
+// values are rejected (the caller falls back to the next source).
+function sanitizeFontValue(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > MAX_VALUE_LENGTH) return null;
+  if (FORBIDDEN_CHARS.test(trimmed)) return null;
+  return trimmed;
+}
+
+function readStoredOverrides(): FontContextOverrides {
+  if (!isBrowser() || typeof localStorage === "undefined") return {};
+  let raw: string | null;
+  try {
+    raw = localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return {};
+  }
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // Malformed JSON: ignore it; the next setter overwrites the key.
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+  const record = parsed as Record<string, unknown>;
+  const out: FontContextOverrides = {};
+  for (const slot of Object.keys(FONT_VAR) as FontSlot[]) {
+    const value = sanitizeFontValue(record[slot]);
+    if (value) out[slot] = value;
+  }
+  return out;
+}
+
+function persistOverrides(overrides: FontContextOverrides): void {
+  if (!isBrowser() || typeof localStorage === "undefined") return;
+  const merged: FontContextOverrides = { ...readStoredOverrides(), ...overrides };
+  const hasAny = (Object.keys(FONT_VAR) as FontSlot[]).some((slot) => merged[slot]);
+  try {
+    if (hasAny) localStorage.setItem(STORAGE_KEY, JSON.stringify(merged));
+    else localStorage.removeItem(STORAGE_KEY);
+  } catch {
+    // Storage unavailable (private mode etc.): vars still apply inline.
+  }
+}
+
+// Re-apply the current state as inline CSS vars. Safe to call any time.
+export function applyFontContext(): void {
+  if (!isBrowser()) return;
+  const el = document.documentElement;
+  el.style.setProperty(FONT_VAR.sans, sansRef.value);
+  el.style.setProperty(FONT_VAR.mono, monoRef.value);
+  el.style.setProperty(FONT_VAR.reading, readingRef.value);
+  el.setAttribute("data-font-context", "on");
+}
+
+let initialized = false;
+
+// Bootstrap hook. Idempotent via a module-level flag like initTheme, BUT
+// explicit options on any call (including repeated ones) always win: they
+// are merged into the current state and re-applied. Explicit options are
+// not persisted — persistence belongs to the useFontContext setters.
+export function initFontContext(options?: FontContextOverrides): void {
+  if (!isBrowser()) return;
+  const explicit: FontContextOverrides = {};
+  if (options) {
+    for (const slot of Object.keys(FONT_VAR) as FontSlot[]) {
+      const value = sanitizeFontValue(options[slot]);
+      if (value) explicit[slot] = value;
+    }
+  }
+  if (!initialized) {
+    initialized = true;
+    const stored = readStoredOverrides();
+    sansRef.value = explicit.sans ?? stored.sans ?? HIKARI_FONT_SANS;
+    monoRef.value = explicit.mono ?? stored.mono ?? HIKARI_FONT_MONO;
+    readingRef.value = explicit.reading ?? stored.reading ?? HIKARI_FONT_READING;
+  } else {
+    // Repeated call: merge the explicit options over the current state.
+    if (explicit.sans) sansRef.value = explicit.sans;
+    if (explicit.mono) monoRef.value = explicit.mono;
+    if (explicit.reading) readingRef.value = explicit.reading;
+  }
+  applyFontContext();
+}
+
+// Clear the persisted override and restore the built-in defaults.
+export function resetFontContext(): void {
+  sansRef.value = HIKARI_FONT_SANS;
+  monoRef.value = HIKARI_FONT_MONO;
+  readingRef.value = HIKARI_FONT_READING;
+  if (isBrowser() && typeof localStorage !== "undefined") {
+    try {
+      localStorage.removeItem(STORAGE_KEY);
+    } catch {
+      // ignore
+    }
+  }
+  applyFontContext();
+}
+
+export function useFontContext() {
+  function setSlot(slot: FontSlot, value: string): void {
+    const clean = sanitizeFontValue(value);
+    if (!clean) return; // rejected: don't persist, don't apply
+    slotRef(slot).value = clean;
+    persistOverrides({ [slot]: clean });
+    applyFontContext();
+  }
+
+  return {
+    sans: sansRef,
+    mono: monoRef,
+    reading: readingRef,
+    setSans: (value: string) => setSlot("sans", value),
+    setMono: (value: string) => setSlot("mono", value),
+    setReading: (value: string) => setSlot("reading", value),
+    reset: resetFontContext,
+  };
+}

package/src/theme/index.ts

@@ -1,5 +1,22 @@
 export { initTheme, useTheme } from "./useTheme";
+export { initFontContext, applyFontContext, resetFontContext, useFontContext, HIKARI_FONT_SANS, HIKARI_FONT_MONO, HIKARI_FONT_READING } from "./fontContext";
+export type { FontContextOverrides } from "./fontContext";
 export { themePresets, tokensToCSSVars, getThemeTokens, loadCustomThemes, saveCustomThemes, addCustomTheme, removeCustomTheme } from "./presets";
-export type { ThemeTokenRGB, ThemeSchemeTokens, ThemePreset, CustomThemePreset, ThemeId, ThemeMode } from "./presets";
-export { getTimePeriod, getGeolocation, solarAltitude, DEFAULT_GEO_LOCATION } from "./useSolarTime";
+export type { ThemeTokenRGB, ThemeSchemeTokens, ThemePreset, CustomThemePreset, ThemeId, ThemeMode, ThemeTokenGroupValues, ThemeTokenGroupModes } from "./presets";
+export type { ThemeTokens } from "./presets";
+export {
+  registerTokenGroup, getTokenGroups, resolveGroupTokens, clampToSlot,
+  clampRgbToBands, clampHue, hueDelta, groupTokensToCSSVars, rgbToHsl, hslToRgb, wrapHue,
+  tokenGroupsVersion, setTokenGroupsReapply,
+  allGroupSlots, resolveLocalizedText, parseTokenGroupConfig, registerTokenGroupConfig,
+} from "./tokenGroups";
+export type {
+  TokenGroupDefinition, TokenGroupSlot, TokenGroupSection, HueClamp,
+  ResolvedGroupTokens, ColorHSL, TokenGroupsReapplyFn,
+  LocalizedText, ParseTokenGroupResult,
+} from "./tokenGroups";
+export { getTimePeriod, getGeolocation, solarAltitude, DEFAULT_GEO_LOCATION, timezoneFallback, setGeolocationProvider } from "./useSolarTime";
+export type { GeoLocation, GeoLocationProvider } from "./useSolarTime";
+export { refreshThemeClock, stopThemeClock } from "./useTheme";
+export { startLuminanceSampler, stopLuminanceSampler, sampleLuminanceNow, invalidateLuminanceCache } from "./useBackgroundLuminance";
 export type { TimePeriod } from "./useSolarTime";