Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

12.5 KB
Raw Blame
/**
 * Theme attributes on <html>, applied twice: once before the first paint by {@link BOOT_SCRIPT}
 * (inlined into the app's index.html), and from then on by the app's theme provider through
 * {@link applyThemeAttributes}.
 *
 * The pre-paint pass is what keeps a dark or non-default-theme page from flashing the light
 * default while the bundle loads, keeps the first frame from rendering at the browser's 16px
 * root and reflowing once React applies the stored text size, and keeps a chosen font pairing
 * from swapping in after the first paint.
 *
 * The inline copy in index.html must equal {@link BOOT_SCRIPT} byte for byte; a test asserts it.
 * Change the constants here, then paste the regenerated string there.
 */
import { DEFAULT_THEME_ID, THEME_ID_PATTERN } from "./tokens";
import type { AccentPreset, ThemeId } from "./tokens";

/**
 * localStorage keys. `penguin.theme` predates themes and stores the MODE (light / dark / system).
 * `penguin.fontScale` is the key of the retired three-step size: {@link readTextSize} reads it
 * once, maps it and removes it; nothing writes it. Drop it with the next minor version.
 */
export const THEME_STORAGE_KEYS = {
  mode: "penguin.theme",
  themeId: "penguin.themeId",
  accent: "penguin.accent",
  textSize: "penguin.textSize",
  fontLatin: "penguin.fontLatin",
  fontCjk: "penguin.fontCjk",
  fontScale: "penguin.fontScale",
} as const;

/** What the readers need of `localStorage`; a test passes a Map-backed stand-in. */
export type PreferenceStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;

// ---------------------------------------------------------------------------
// Text size
// ---------------------------------------------------------------------------

/** The five text sizes, smallest first: 特小 · 小 · 中 · 大 · 特大. */
export const TEXT_SIZES = ["xs", "s", "m", "l", "xl"] as const;
export type TextSize = (typeof TEXT_SIZES)[number];

/** Text size → root font-size. Every type and density token is rem, so this scales them all. */
export const TEXT_SIZE_PX: Readonly<Record<TextSize, string>> = {
  xs: "14px",
  s: "15px",
  m: "16px",
  l: "18px",
  xl: "20px",
};

/** 16px — what the retired scale called its small step (user decision, 2026-09-29). */
export const DEFAULT_TEXT_SIZE: TextSize = "m";

/** The retired three-step scale and, by index, the size with the same pixels: 16 / 18 / 20px. */
const LEGACY_FONT_SCALES = ["sm", "md", "lg"] as const;
const LEGACY_FONT_SCALE_SIZES: readonly TextSize[] = ["m", "l", "xl"];

export function isTextSize(value: unknown): value is TextSize {
  return (TEXT_SIZES as readonly unknown[]).includes(value);
}

/**
 * The stored text size, or the default. A store that still holds the retired three-step scale
 * and no text size is migrated on this read: the step is mapped by its pixels, written under the
 * new key and the old key removed (an unrecognised old value is removed without a write), so the
 * next read is a plain lookup. The pre-paint script does the same before the first frame.
 */
export function readTextSize(storage: PreferenceStorage): TextSize {
  const stored = storage.getItem(THEME_STORAGE_KEYS.textSize);
  if (isTextSize(stored)) return stored;
  const legacy = storage.getItem(THEME_STORAGE_KEYS.fontScale);
  if (legacy === null) return DEFAULT_TEXT_SIZE;
  const size = LEGACY_FONT_SCALE_SIZES[(LEGACY_FONT_SCALES as readonly string[]).indexOf(legacy)];
  if (size !== undefined) storage.setItem(THEME_STORAGE_KEYS.textSize, size);
  storage.removeItem(THEME_STORAGE_KEYS.fontScale);
  return size ?? DEFAULT_TEXT_SIZE;
}

// ---------------------------------------------------------------------------
// Font pairing
// ---------------------------------------------------------------------------

/**
 * One face a user may pair: its id (the `data-font-latin` / `data-font-cjk` value, and what is
 * stored) and its display label — a proper name, the same in both languages. `theme` (the
 * theme's own face, no attribute) and `system` (the platform's face) are not names: a consumer
 * words those two from its own dictionary and shows the label of every other entry as it is.
 */
export interface FontOption {
  readonly id: string;
  readonly label: string;
}

/**
 * The Latin faces, only those the app already bundles (`fonts/*.css`). They replace the reading
 * and chrome sans (`--ui-font-sans`, which every theme's `--ui-font-ui` follows); a theme's mono
 * face is never replaced — code and the marks a theme sets in mono keep it.
 */
export const FONT_LATIN_OPTIONS = [
  { id: "theme", label: "Theme default" },
  { id: "system", label: "System" },
  { id: "mona-sans", label: "Mona Sans" },
  { id: "ibm-plex-sans", label: "IBM Plex Sans" },
  { id: "misans", label: "MiSans" },
] as const satisfies readonly FontOption[];
export type FontLatin = (typeof FONT_LATIN_OPTIONS)[number]["id"];

/** The CJK faces, likewise; they replace `--ui-font-cjk`, which every theme's stacks read. */
export const FONT_CJK_OPTIONS = [
  { id: "theme", label: "Theme default" },
  { id: "system", label: "System" },
  { id: "noto-sans-sc", label: "Noto Sans SC" },
  { id: "misans", label: "MiSans" },
] as const satisfies readonly FontOption[];
export type FontCjk = (typeof FONT_CJK_OPTIONS)[number]["id"];

const optionIds = (options: readonly FontOption[]) => options.map((option) => option.id);

export function isFontLatin(value: unknown): value is FontLatin {
  return (optionIds(FONT_LATIN_OPTIONS) as readonly unknown[]).includes(value);
}

export function isFontCjk(value: unknown): value is FontCjk {
  return (optionIds(FONT_CJK_OPTIONS) as readonly unknown[]).includes(value);
}

// ---------------------------------------------------------------------------
// The themes' own faces
// ---------------------------------------------------------------------------

/**
 * The display name of every bundled family → the family its `@font-face` declares
 * (`fonts/*.css`). The pairing options and the themes' own faces are named by the display
 * names, which is also what the credits and the Fonts page print.
 */
export const BUNDLED_FONT_FAMILIES = {
  "Mona Sans": "Mona Sans Variable",
  "IBM Plex Sans": "IBM Plex Sans Variable",
  MiSans: "MiSans",
  "Noto Sans SC": "Noto Sans SC Variable",
  "JetBrains Mono": "JetBrains Mono Variable",
} as const;
export type BundledFontName = keyof typeof BUNDLED_FONT_FAMILIES;

/** A theme that names no bundled face names the platform's own; a consumer words this. */
export const SYSTEM_FONT = "System";
export type ThemeFontName = BundledFontName | typeof SYSTEM_FONT;

export interface ThemeFonts {
  /** The reading and chrome sans (`--ui-font-sans`, which `--ui-font-ui` follows). */
  readonly latin: ThemeFontName;
  /** `--ui-font-cjk`. */
  readonly cjk: ThemeFontName;
  /** `--ui-font-mono`. */
  readonly mono: ThemeFontName;
}

/**
 * Each theme's own faces, as display names — what the Fonts page states as a theme's defaults
 * beside the user's choice. A test holds every entry to the family its theme file's stack names
 * first (`System` = a stack that names no bundled family).
 */
export const THEME_FONTS: Readonly<Record<ThemeId, ThemeFonts>> = {
  github: { latin: "Mona Sans", cjk: "Noto Sans SC", mono: "JetBrains Mono" },
  modern: { latin: "MiSans", cjk: "MiSans", mono: "JetBrains Mono" },
  geek: { latin: "IBM Plex Sans", cjk: "Noto Sans SC", mono: "JetBrains Mono" },
};

// ---------------------------------------------------------------------------
// Applying the attributes
// ---------------------------------------------------------------------------

/**
 * `neutral` is the stored value for "no preset": the theme's own accent, no `data-accent`. Any
 * other well-formed id is written to the root as it is, whichever theme is active: a theme's
 * preset rules match only their own theme, so an id the active theme does not list paints nothing
 * (the theme's own accent shows) and takes effect again when the user returns to a theme that
 * lists it. The resolution lives in the CSS, and `resolveAccent` (tokens.ts) only mirrors it for a
 * picker. The id space is open — an imported theme brings presets of its own — so this is a
 * string with the shipped ids documented rather than a closed union.
 */
export type AccentChoice = AccentPreset | "neutral" | (string & {});

export interface ThemeAttributes {
  /** The resolved mode (a `system` preference already resolved against the media query). */
  dark: boolean;
  /** A shipped theme's id or an imported one's (tokens.ts, `THEME_ID_PATTERN`). */
  themeId: string;
  accent: AccentChoice;
  textSize: TextSize;
  /** `theme` is the theme's own face and writes no attribute, like `neutral` for the accent. */
  fontLatin: FontLatin;
  fontCjk: FontCjk;
}

/**
 * The three `data-*` attributes share one rule: the value that means "the theme's own" (the
 * default theme, no preset, the theme's face) is the ABSENCE of the attribute, so a theme file's
 * plain selectors match it and nothing has to name a default.
 */
function setOrDrop(root: HTMLElement, key: string, value: string, own: string): void {
  if (value === own) delete root.dataset[key];
  else root.dataset[key] = value;
}

/**
 * Writes the given attributes onto `root`. Each field is optional so a provider can reconcile one
 * preference per effect; an absent field is left as it is.
 */
export function applyThemeAttributes(root: HTMLElement, attrs: Partial<ThemeAttributes>): void {
  if (attrs.dark !== undefined) root.classList.toggle("dark", attrs.dark);
  if (attrs.themeId !== undefined) setOrDrop(root, "theme", attrs.themeId, DEFAULT_THEME_ID);
  if (attrs.accent !== undefined) setOrDrop(root, "accent", attrs.accent, "neutral");
  if (attrs.fontLatin !== undefined) setOrDrop(root, "fontLatin", attrs.fontLatin, "theme");
  if (attrs.fontCjk !== undefined) setOrDrop(root, "fontCjk", attrs.fontCjk, "theme");
  if (attrs.textSize !== undefined) root.style.fontSize = TEXT_SIZE_PX[attrs.textSize];
}

// ---------------------------------------------------------------------------
// The pre-paint script
// ---------------------------------------------------------------------------

/** The ids that write an attribute: every option but `theme`, which is the attribute's absence. */
const chosenFaces = (options: readonly FontOption[]) =>
  optionIds(options).filter((id) => id !== "theme");
const j = JSON.stringify;
const K = THEME_STORAGE_KEYS;

/**
 * The pre-paint script: a classic, dependency-free IIFE (no globals leak) that mirrors
 * {@link applyThemeAttributes} and {@link readTextSize} for the stored preferences. It validates
 * every stored value the way the provider's initializers do, so an unknown value renders exactly
 * as the provider will, and it swallows everything — storage can throw (disabled cookies,
 * sandboxed frames) and the page must still render. The text-size migration writes storage last
 * and in its own try, so a store that reads but refuses writes still paints the migrated size.
 *
 * The theme and the accent are validated by PATTERN rather than by list: an installation can
 * import themes (and themes bring presets), so the ids cannot be enumerated here. The pattern is
 * tried against a STRING only — a store that holds no value gives null, and `RegExp.test` would
 * read that as the four-letter id "null". A well-formed id that names nothing simply paints
 * nothing — an id the active theme does not list is already how a preset outlives its theme (see
 * AccentChoice) — so the worst a stale value costs is a hairline the running app corrects a frame
 * later.
 */
export const BOOT_SCRIPT =
  "(function(){try{" +
  `var d=document.documentElement,s=localStorage,T=new RegExp(${j(THEME_ID_PATTERN.source)}),m=s.getItem(${j(K.mode)});` +
  'if(m==="dark"||(m!=="light"&&matchMedia("(prefers-color-scheme: dark)").matches))d.classList.add("dark");' +
  `var t=s.getItem(${j(K.themeId)});if(typeof t==="string"&&t!==${j(DEFAULT_THEME_ID)}&&T.test(t))d.dataset.theme=t;` +
  `var a=s.getItem(${j(K.accent)});if(typeof a==="string"&&a!=="neutral"&&T.test(a))d.dataset.accent=a;` +
  `var l=s.getItem(${j(K.fontLatin)});if(${j(chosenFaces(FONT_LATIN_OPTIONS))}.indexOf(l)>=0)d.dataset.fontLatin=l;` +
  `var c=s.getItem(${j(K.fontCjk)});if(${j(chosenFaces(FONT_CJK_OPTIONS))}.indexOf(c)>=0)d.dataset.fontCjk=c;` +
  `var z=s.getItem(${j(K.textSize)}),g=null,o=-1;` +
  `if(${j(TEXT_SIZES)}.indexOf(z)<0){g=s.getItem(${j(K.fontScale)});o=${j(LEGACY_FONT_SCALES)}.indexOf(g);z=o<0?${j(DEFAULT_TEXT_SIZE)}:${j(LEGACY_FONT_SCALE_SIZES)}[o]}` +
  `d.style.fontSize=${j(TEXT_SIZE_PX)}[z];` +
  `if(g!==null){try{if(o>=0)s.setItem(${j(K.textSize)},z);s.removeItem(${j(K.fontScale)})}catch(e){}}` +
  "}catch(e){}})()";