Auto Foreground

1"use client";
2 
3import * as React from "react";
4import {
5  formatOklch,
6  glassSolidSurface,
7  HARMONIC_OFFSETS,
8  type HarmonicName,
9  harmonicHue,
10  pickInBand,
11  READABLE_USAGE,
12  readableForeground,
13  type ThemeForegroundOptions,
14  themeForeground,
15} from "@/lib/oklch-utils";
16 
17const FG_STORAGE_KEY = "sistine-fg";
18const RAMP_KEY = "sistine-ramp";
19const FG_EVENT = "sistine-fg";
20 
21// Dev instrumentation: set localStorage["sistine-fg-debug"] = "1" (then reload) to log each update()'s
22// wall-time and how far it nudges --foreground off the CSS baseline (the "marginal bump"). Off by default.
23const fgDebug = () => {
24  try {
25    return typeof localStorage !== "undefined" && localStorage.getItem("sistine-fg-debug") === "1";
26  } catch {
27    return false;
28  }
29};
30 
31export type FgPalette = ThemeForegroundOptions["palette"];
32export interface FgConfig {
33  palette: FgPalette;
34  /** Icon foreground hue for `--foreground-ui`: a number (0–360) pins a hue; a harmonic name
35   * ("complement" | "triad-1" | "split-2" | … — a color-wheel relationship rotated off --harmony-h,
36   * tracked live); null → icons follow the theme/text color. Always contrast-solved (APCA/ARC). */
37  iconHue: number | HarmonicName | null;
38  /** Heading/large-text hue for `--foreground-soft` — same semantics as iconHue (number pins, a harmonic
39   * name rotates off the theme live, null → follow the chosen palette ramp). */
40  softHue: number | HarmonicName | null;
41  /** Fine/small-text hue for `--foreground-strong` — same semantics (null → follow the palette ramp). */
42  strongHue: number | HarmonicName | null;
43}
44/** The /colors ramp generator's base color + step count, shared with the foreground. */
45export interface RampConfig {
46  l: number;
47  c: number;
48  h: number;
49  count: number;
50}
51 
52const FG_PALETTES: FgPalette[] = [
53  "tonal",
54  "lightness",
55  "hue",
56  "chroma",
57];
58const DEFAULT_FG: FgConfig = {
59  palette: "lightness", // linear ramp — holds the theme's chroma, so high-contrast text reads as a soft tinted white, not gray
60  iconHue: null,
61  softHue: null,
62  strongHue: null,
63};
64const DEFAULT_RAMP: RampConfig = {
65  l: 60,
66  c: 0.15,
67  h: 255,
68  count: 12, // finest ramp (12 steps/side) — the most cohesive foreground set in practice
69};
70 
71/** Normalize a stored hue choice: a harmonic relationship name, a pinned number, else null. */
72const hueChoice = (v: unknown): number | HarmonicName | null =>
73// … truncated