@timmo001/groundwork-tokens 0.9.31 → 0.9.33

package/README.md

@@ -31,5 +31,16 @@ their own:
 import { parseTheme, runtimeTheme } from "@timmo001/groundwork-tokens/runtime";
 ```
 
+The `omarchy-current` export reads and watches the Omarchy theme a machine
+is using, for apps outside a browser, such as a desktop app's main process or
+a terminal UI. `pageTheme`'s `setOmarchyTheme` offers it in the view:
+
+```ts
+import {
+  readOmarchyTheme,
+  watchOmarchyTheme,
+} from "@timmo001/groundwork-tokens/omarchy-current";
+```
+
 The themes, their roles and contrast targets are documented at
 [groundwork.timmo.dev/themes](https://groundwork.timmo.dev/themes).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/groundwork-tokens",
-  "version": "0.9.31",
+  "version": "0.9.33",
   "description": "Groundwork's design tokens: the theme schema, the OKLCH solver and every theme as CSS and JSON",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,7 @@
     "./runtime": "./src/runtime.ts",
     "./page": "./src/page.ts",
     "./webmcp": "./src/webmcp.ts",
+    "./omarchy-current": "./src/omarchy-current.ts",
     "./opentui": "./generated/opentui.ts",
     "./themes.css": "./generated/themes.css",
     "./themes.json": "./generated/themes.json",
@@ -47,10 +48,10 @@
   "dependencies": {
     "@types/culori": "4.0.1",
     "culori": "4.0.2",
-    "effect": "4.1.1"
+    "effect": "4.1.2"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.1.1",
+    "@effect/platform-node": "4.1.2",
     "@oxlint/plugins": "1.90.0",
     "@timmo001/oxlint-rules": "0.6.3",
     "@types/bun": "1.4.4",

package/src/generate.ts

@@ -554,7 +554,8 @@ const hexRoles = (roles: Roles) =>
     Object.entries(roles).map(([role, color]) => [role, toHex(color)]),
   );
 
-const hexModes = (theme: ResolvedTheme) =>
+/** A solved theme's roles as hex in each mode it has, as terminals take them. */
+export const hexModes = (theme: ResolvedTheme) =>
   Object.fromEntries(
     modes.flatMap((mode) => {
       const roles = theme.modes[mode];

package/src/omarchy-current.ts

@@ -0,0 +1,110 @@
+/**
+ * The Omarchy theme a machine is using, for apps that run outside a browser,
+ * such as a desktop app's main process or a terminal UI. It reads the theme's
+ * name and `colors.toml` from Omarchy's state folder and watches for a
+ * switch. It needs a file system, so it's an entry of its own; map the colors
+ * with `omarchyTheme` from the runtime entry.
+ *
+ * @module
+ */
+import { watch, type FSWatcher } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { OmarchyCurrentTheme } from "./omarchy.ts";
+
+export type { OmarchyCurrentTheme } from "./omarchy.ts";
+
+/** Omarchy's `current` folder, in `$XDG_STATE_HOME`, by default `~/.local/state`. */
+export const omarchyCurrentPath = () =>
+  join(
+    process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"),
+    "omarchy",
+    "current",
+  );
+
+// `tokyo-night` reads as `Tokyo Night`, as `omarchy theme current` shows it
+const displayName = (slug: string) =>
+  slug
+    .trim()
+    .split("-")
+    .filter((word) => word !== "")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+
+/** The Omarchy theme in use, or `null` where there's no Omarchy. */
+export const readOmarchyTheme =
+  async (): Promise<OmarchyCurrentTheme | null> => {
+    const current = omarchyCurrentPath();
+
+    try {
+      const colors = await readFile(
+        join(current, "theme", "colors.toml"),
+        "utf8",
+      );
+
+      const slug = await readFile(join(current, "theme.name"), "utf8").catch(
+        () => "",
+      );
+
+      return { name: displayName(slug) || "Omarchy", colors };
+    } catch {
+      return null;
+    }
+  };
+
+const watchFolder = (path: string, onEvent: () => void) => {
+  try {
+    return watch(path, onEvent).on("error", () => undefined);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Calls `onChange` with the theme each time Omarchy switches it, or with
+ * `null` when it goes. Returns a function that stops watching.
+ */
+export const watchOmarchyTheme = (
+  onChange: (theme: OmarchyCurrentTheme | null) => void,
+): (() => void) => {
+  const current = omarchyCurrentPath();
+  let last: string | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let themeWatcher: FSWatcher | undefined;
+
+  void readOmarchyTheme().then((theme) => {
+    last ??= JSON.stringify(theme);
+  });
+
+  // A switch replaces the theme folder, so its watcher is armed again each time
+  const armTheme = () => {
+    themeWatcher?.close();
+    themeWatcher = watchFolder(join(current, "theme"), changed);
+  };
+
+  // A switch writes several files; read once they've settled
+  function changed() {
+    clearTimeout(timer);
+    timer = setTimeout(async () => {
+      armTheme();
+      const theme = await readOmarchyTheme();
+      const key = JSON.stringify(theme);
+
+      if (key === last) return;
+      last = key;
+      onChange(theme);
+    }, 250);
+  }
+
+  const currentWatcher = watchFolder(current, changed);
+
+  armTheme();
+
+  return () => {
+    clearTimeout(timer);
+    currentWatcher?.close();
+    themeWatcher?.close();
+  };
+};

package/src/omarchy.ts

@@ -8,6 +8,15 @@
 import { Schema } from "effect";
 import { MappedTheme } from "./schema.ts";
 
+/**
+ * The Omarchy theme a machine is using: its name, such as `Tokyo Night`,
+ * and the text of its `colors.toml`.
+ */
+export interface OmarchyCurrentTheme {
+  readonly name: string;
+  readonly colors: string;
+}
+
 /** The `key = "value"` pairs of a flat TOML file, ignoring comments. */
 const readPairs = (text: string): ReadonlyMap<string, string> => {
   const pairs = new Map<string, string>();

package/src/page.ts

@@ -15,6 +15,7 @@ import glazing from "../themes/glazing.json" with { type: "json" };
 import slate from "../themes/slate.json" with { type: "json" };
 import snag from "../themes/snag.json" with { type: "json" };
 import survey from "../themes/survey.json" with { type: "json" };
+import type { OmarchyCurrentTheme } from "./omarchy.ts";
 import type { ThemeStore } from "./runtime.ts";
 import type { Theme } from "./schema.ts";
 // Only for `document.modelContext`'s type; the tools themselves load lazily
@@ -29,6 +30,12 @@ export const customThemeId = "custom";
 /** The id of the `<style>` holding a custom theme's CSS. */
 export const customThemeStyleId = "gw-custom-theme";
 
+/** The theme id the desktop's Omarchy theme is solved under. */
+export const omarchyThemeId = "omarchy";
+
+/** The id of the `<style>` holding the Omarchy theme's CSS. */
+export const omarchyThemeStyleId = "gw-omarchy-theme";
+
 const modes: readonly ThemeMode[] = ["auto", "light", "dark", "darker"];
 
 /** Light or dark: the side of a mode a theme has to cover. Darker is dark. */
@@ -42,6 +49,8 @@ export interface PageThemeState {
   readonly theme: string;
   /** The visitor's own theme's name, when they've imported one. */
   readonly custom: string | null;
+  /** The desktop's Omarchy theme as a choice, when the app passed one. */
+  readonly omarchy: ThemeChoice | null;
 }
 
 /** What `importTheme` reports: the theme's name and any contrast misses, or why it failed. */
@@ -117,6 +126,15 @@ export interface PageTheme {
   readonly importTheme: (text: string) => Promise<ImportResult>;
   /** Drops the visitor's own theme and goes back to the defaults. */
   readonly reset: () => void;
+  /**
+   * Offers the Omarchy theme the app runs under, or drops it with `null`.
+   * It's used for its scheme until the visitor picks another, and a theme
+   * switch on the desktop follows through while it's picked. Apps that can
+   * read it, such as desktop apps, pass it on start and on every switch.
+   */
+  readonly setOmarchyTheme: (
+    theme: OmarchyCurrentTheme | null,
+  ) => Promise<void>;
   /** Calls `listener` on every change; returns a function that stops it. */
   readonly subscribe: (listener: (state: PageThemeState) => void) => () => void;
 }
@@ -130,6 +148,13 @@ const keys = (key: string) => ({
   name: `${key}:custom-name`,
 });
 
+/** The Omarchy theme's cache, kept apart so a reset doesn't drop it. */
+const omarchyKeys = (key: string) => ({
+  css: `${key}:omarchy-css`,
+  name: `${key}:omarchy-name`,
+  mode: `${key}:omarchy-mode`,
+});
+
 const read = (key: string) => {
   try {
     return localStorage.getItem(key);
@@ -148,24 +173,26 @@ const write = (key: string, value: string | null) => {
 };
 
 /**
- * An inline script that applies the stored mode, theme and any custom theme's
- * cached CSS before the first paint. Takes the same key and defaults as
- * `pageTheme`.
+ * An inline script that applies the stored mode, theme and any custom or
+ * Omarchy theme's cached CSS before the first paint. Takes the same key and
+ * defaults as `pageTheme`.
  */
 export const themeBootScript = (
   options: Pick<PageThemeOptions, "key" | "defaultTheme" | "defaultMode">,
 ) => {
-  const stored = keys(options.key);
-
   const config = JSON.stringify({
-    keys: stored,
+    keys: keys(options.key),
+    omarchy: omarchyKeys(options.key),
     theme: options.defaultTheme,
     mode: options.defaultMode ?? "auto",
     custom: customThemeId,
     style: customThemeStyleId,
+    omarchyId: omarchyThemeId,
+    omarchyStyle: omarchyThemeStyleId,
   });
 
-  return `(()=>{const c=${config};let s;try{s=localStorage}catch{}const g=(k)=>{try{return s?.getItem(k)??null}catch{return null}};const r=document.documentElement;const m=g(c.keys.mode)??c.mode;const d=m==="dark"||m==="darker"||(m==="auto"&&matchMedia("(prefers-color-scheme: dark)").matches);let t=(d?g(c.keys.dark):null)??g(c.keys.theme)??c.theme;if(t===c.custom){const css=g(c.keys.css);if(css){const e=document.createElement("style");e.id=c.style;e.textContent=css;document.head.append(e)}else t=c.theme}r.setAttribute("data-gw-theme",t);if(m==="auto")r.removeAttribute("data-gw-mode");else r.setAttribute("data-gw-mode",m)})();`;
+  // With nothing picked, a cached Omarchy theme for the scheme is the default
+  return `(()=>{const c=${config};let s;try{s=localStorage}catch{}const g=(k)=>{try{return s?.getItem(k)??null}catch{return null}};const r=document.documentElement;const a=(id,css)=>{const e=document.createElement("style");e.id=id;e.textContent=css;document.head.append(e)};const m=g(c.keys.mode)??c.mode;const d=m==="dark"||m==="darker"||(m==="auto"&&matchMedia("(prefers-color-scheme: dark)").matches);const o=g(c.omarchy.css);let t=(d?g(c.keys.dark):null)??g(c.keys.theme)??(o&&g(c.omarchy.mode)===(d?"dark":"light")?c.omarchyId:c.theme);if(t===c.custom){const css=g(c.keys.css);if(css)a(c.style,css);else t=c.theme}else if(t===c.omarchyId){if(o)a(c.omarchyStyle,o);else t=c.theme}r.setAttribute("data-gw-theme",t);if(m==="auto")r.removeAttribute("data-gw-mode");else r.setAttribute("data-gw-mode",m)})();`;
 };
 
 /** Reads a theme from JSON text or an Omarchy `colors.toml`. */
@@ -187,6 +214,7 @@ const readTheme = async (text: string) => {
  */
 export const pageTheme = (options: PageThemeOptions): PageTheme => {
   const stored = keys(options.key);
+  const storedOmarchy = omarchyKeys(options.key);
   const root = options.root ?? document.documentElement;
   const defaultMode = options.defaultMode ?? "auto";
   const listeners = new Set<(state: PageThemeState) => void>();
@@ -197,6 +225,49 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
   const customName = read(stored.name);
   const customCss = read(stored.css);
 
+  const setStyle = (id: string, css: string | null) => {
+    let style = document.getElementById(id);
+
+    if (css === null) {
+      style?.remove();
+
+      return;
+    }
+
+    if (style === null) {
+      style = document.createElement("style");
+      style.id = id;
+      document.head.append(style);
+    }
+
+    style.textContent = css;
+  };
+
+  /** The Omarchy theme as a choice, from the last one the app passed. */
+  let omarchy: ThemeChoice | null = null;
+
+  {
+    const css = read(storedOmarchy.css);
+    const name = read(storedOmarchy.name);
+    const mode = read(storedOmarchy.mode);
+
+    if (
+      css !== null &&
+      name !== null &&
+      (mode === "light" || mode === "dark")
+    ) {
+      omarchy = { id: omarchyThemeId, name, mode };
+
+      // The boot script may have put it on already
+      if (document.getElementById(omarchyThemeStyleId) === null) {
+        setStyle(omarchyThemeStyleId, css);
+      }
+    }
+  }
+
+  const choices = () =>
+    omarchy === null ? options.themes : [...options.themes, omarchy];
+
   const system = matchMedia("(prefers-color-scheme: dark)");
 
   const schemeOf = (mode: ThemeMode): ThemeScheme =>
@@ -210,18 +281,20 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
   const fits = (id: string | null, scheme: ThemeScheme, custom: boolean) =>
     id !== null &&
     ((id === customThemeId && custom) ||
-      options.themes.some(
-        (theme) => theme.id === id && themeCovers(theme, scheme),
-      ));
+      choices().some((theme) => theme.id === id && themeCovers(theme, scheme)));
 
+  // The Omarchy theme comes first where it covers the scheme, so the app
+  // matches the desktop until the visitor picks another
   const fallback = (scheme: ThemeScheme) =>
-    options.themes.some(
-      (theme) =>
-        theme.id === options.defaultTheme && themeCovers(theme, scheme),
-    )
-      ? options.defaultTheme
-      : (options.themes.find((theme) => themeCovers(theme, scheme))?.id ??
-        options.defaultTheme);
+    omarchy !== null && themeCovers(omarchy, scheme)
+      ? omarchy.id
+      : options.themes.some(
+            (theme) =>
+              theme.id === options.defaultTheme && themeCovers(theme, scheme),
+          )
+        ? options.defaultTheme
+        : (options.themes.find((theme) => themeCovers(theme, scheme))?.id ??
+          options.defaultTheme);
 
   const storedLight = read(stored.theme);
   const storedDark = read(stored.dark) ?? storedLight;
@@ -244,7 +317,7 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
   const resolve = (mode: ThemeMode, custom: string | null): PageThemeState => {
     const scheme = schemeOf(mode);
 
-    return { mode, scheme, theme: picks[scheme], custom };
+    return { mode, scheme, theme: picks[scheme], custom, omarchy };
   };
 
   let state: PageThemeState = resolve(
@@ -252,24 +325,6 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
     customCss === null ? null : customName,
   );
 
-  const setStyle = (css: string | null) => {
-    let style = document.getElementById(customThemeStyleId);
-
-    if (css === null) {
-      style?.remove();
-
-      return;
-    }
-
-    if (style === null) {
-      style = document.createElement("style");
-      style.id = customThemeStyleId;
-      document.head.append(style);
-    }
-
-    style.textContent = css;
-  };
-
   const commit = (next: PageThemeState) => {
     state = next;
     root.setAttribute("data-gw-theme", state.theme);
@@ -290,7 +345,7 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
         ? runtime.css
         : `${runtime.css}\n\n${appTonesCss(options.tones, runtime.theme)}`;
 
-    setStyle(css);
+    setStyle(customThemeStyleId, css);
     write(stored.document, text);
     write(stored.css, css);
     write(stored.name, document.name);
@@ -314,7 +369,7 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
 
       picks = { light: id, dark: id };
     } else {
-      const choice = options.themes.find((theme) => theme.id === id);
+      const choice = choices().find((theme) => theme.id === id);
 
       if (choice === undefined) return;
 
@@ -365,7 +420,7 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
       return { ok: true, name: parsed.success.name, misses };
     },
     reset: () => {
-      setStyle(null);
+      setStyle(customThemeStyleId, null);
 
       for (const key of Object.values(stored)) write(key, null);
 
@@ -373,6 +428,72 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
       commit(resolve(defaultMode, null));
       void options.store?.clear().catch(() => undefined);
     },
+    setOmarchyTheme: async (theme) => {
+      // Stored as well as in use, so it's picked again when it comes back
+      const followed = [
+        picks.light,
+        picks.dark,
+        read(stored.theme),
+        read(stored.dark),
+      ].includes(omarchyThemeId);
+
+      const unpicked = read(stored.theme) === null;
+      let mode: ThemeScheme | undefined;
+
+      if (theme !== null) {
+        const { Result } = await import("effect");
+
+        const { appTonesCss, omarchyTheme, runtimeTheme } =
+          await import("./runtime.ts");
+
+        const name = `Omarchy (${theme.name})`;
+        const parsed = omarchyTheme(theme.colors, name, omarchyThemeId);
+
+        if (Result.isSuccess(parsed)) {
+          const runtime = runtimeTheme(parsed.success);
+
+          const css =
+            options.tones === undefined
+              ? runtime.css
+              : `${runtime.css}\n\n${appTonesCss(options.tones, runtime.theme)}`;
+
+          mode = parsed.success.mode;
+          setStyle(omarchyThemeStyleId, css);
+          write(storedOmarchy.css, css);
+          write(storedOmarchy.name, name);
+          write(storedOmarchy.mode, mode);
+          omarchy = { id: omarchyThemeId, name, mode };
+        }
+      }
+
+      if (mode === undefined) {
+        // Gone, or a colors.toml that doesn't map: back off it, keeping the
+        // pick so it comes back with the theme
+        setStyle(omarchyThemeStyleId, null);
+
+        for (const key of Object.values(storedOmarchy)) write(key, null);
+
+        omarchy = null;
+        picks = {
+          light:
+            picks.light === omarchyThemeId ? fallback("light") : picks.light,
+          dark: picks.dark === omarchyThemeId ? fallback("dark") : picks.dark,
+        };
+      } else if (followed || unpicked) {
+        // A switch between a light and a dark Omarchy theme moves it across
+        const keep = (scheme: ThemeScheme) =>
+          picks[scheme] === omarchyThemeId ? fallback(scheme) : picks[scheme];
+
+        picks =
+          mode === "dark"
+            ? { light: keep("light"), dark: omarchyThemeId }
+            : { light: omarchyThemeId, dark: keep("dark") };
+
+        if (!unpicked) savePicks();
+      }
+
+      commit(resolve(state.mode, state.custom));
+    },
     subscribe: (listener) => {
       listeners.add(listener);
 
@@ -393,7 +514,7 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
         if (text === read(stored.document)) return;
 
         if (text === null) {
-          setStyle(null);
+          setStyle(customThemeStyleId, null);
 
           for (const key of [stored.document, stored.css, stored.name]) {
             write(key, null);

package/src/runtime.ts

@@ -12,7 +12,9 @@ import { SolvedTheme, Theme } from "./schema.ts";
 import { check, resolve, type Check, type ResolvedTheme } from "./solve.ts";
 import { appTonesCss, type AppTones } from "./tones.ts";
 
-export { omarchyTheme } from "./omarchy.ts";
+export { omarchyTheme, type OmarchyCurrentTheme } from "./omarchy.ts";
+
+export { hexModes } from "./generate.ts";
 
 export { appTonesCss, type AppTones } from "./tones.ts";