@tryinget/pi-activity-strip 0.5.0 → 0.6.0

package/src/native/placement.mjs

@@ -0,0 +1,225 @@
+// ---
+// summary: "owns hidden-tab placement state: window memory, host resolution, and the bounded AT-SPI tab inventory"
+// read_when:
+//   - "changing hidden-tab placement inputs, inventory cadence, or placement runtime counters"
+// ---
+
+import path from "node:path";
+import { ACTIVITY_STRIP_SOCKET_DIR } from "../common/constants.mjs";
+import { resolvePiSessionIdentity, resolveSessionWindow } from "../common/niri-focus.mjs";
+import {
+  createSurfaceBindingStore,
+  parseTerminalTitleBinding,
+} from "../common/surface-bindings.mjs";
+import {
+  canonicalGhosttyTerminalKey,
+  resolveTerminalHostPid,
+} from "../common/terminal-identity.mjs";
+import { mapTabInventoryToBindings, probeGhosttyTabInventory } from "./tab-inventory.mjs";
+
+// The AT-SPI tab inventory is the only exact source for tabs that have never been shown while the
+// strip ran. It is read-only, bounded, never concurrent, and backs off once the host reports it
+// unavailable. Placement itself never depends on it: it only supplies more window memory.
+export const TAB_INVENTORY_INTERVAL_MS = 10_000;
+export const TAB_INVENTORY_URGENT_INTERVAL_MS = 3000;
+export const TAB_INVENTORY_FAILURE_BACKOFF_MS = 30_000;
+export const TAB_INVENTORY_UNAVAILABLE_RETRY_MS = 10 * 60_000;
+
+/** @typedef {import("../common/contracts.ts").ActivityStripRuntimeStatus} ActivityStripRuntimeStatus */
+/** @typedef {Record<string, unknown>} NiriWindow */
+
+/**
+ * @param {{
+ *   env?: NodeJS.ProcessEnv;
+ *   runtimeStatus: ActivityStripRuntimeStatus;
+ *   execFileAsync: (file: string, args: string[], options: object) => Promise<{stdout?: string}>;
+ *   onBindingsLearned: () => void;
+ *   now?: () => number;
+ *   probeInventory?: typeof probeGhosttyTabInventory;
+ *   bindingsFilePath?: string;
+ * }} options
+ */
+export function createPlacementRuntime({
+  env = process.env,
+  runtimeStatus,
+  execFileAsync,
+  onBindingsLearned,
+  now = Date.now,
+  probeInventory = probeGhosttyTabInventory,
+  bindingsFilePath,
+}) {
+  const isNiri = Boolean(env.NIRI_SOCKET);
+  // Window ids restart with the compositor, so persisted memory is bound to one Niri instance.
+  const bindings = createSurfaceBindingStore({
+    instanceKey: String(env.NIRI_SOCKET ?? ""),
+    filePath:
+      bindingsFilePath ??
+      (isNiri ? path.join(ACTIVITY_STRIP_SOCKET_DIR, "surface-bindings.json") : ""),
+    now,
+  });
+  /** @type {Map<string, number>} */
+  const hostPidCache = new Map();
+  /** @type {Map<unknown, string>} */
+  const windowSignatures = new Map();
+  let inventoryInFlight = false;
+  let inventoryNextAt = 0;
+
+  const options = {
+    env,
+    /** @param {Record<string, unknown>} session */
+    resolveHostPid: (session) => resolveTerminalHostPid(session, { cache: hostPidCache }),
+    /** @param {string} bindingKey */
+    lookupBinding: (bindingKey) => bindings.lookup(bindingKey),
+  };
+
+  /** Workspace plus visible surface: everything about a window that can move a card. */
+  /** @param {NiriWindow} window */
+  function signatureOf(window) {
+    return `${window.workspace_id}|${parseTerminalTitleBinding(window.title)?.terminalKey ?? ""}`;
+  }
+
+  /**
+   * Bound surfaces that resolve to no window at all: hidden tabs inside a multi-window Ghostty
+   * process whose window has not been observed or inventoried yet.
+   * @param {NiriWindow[]} windows
+   * @param {Array<Record<string, unknown>>} sessions
+   */
+  function countUnplaced(windows, sessions) {
+    let unplaced = 0;
+    for (const session of sessions) {
+      if (!canonicalGhosttyTerminalKey(session)) continue;
+      const sessionId = resolvePiSessionIdentity(session, options);
+      if (!sessionId) continue;
+      if (!resolveSessionWindow(windows, sessionId, session, options)) unplaced += 1;
+    }
+    return unplaced;
+  }
+
+  /** @param {NiriWindow[]} windows */
+  function observeWindowList(windows) {
+    if (windows.length === 0) return;
+    bindings.observeWindows(windows);
+    bindings.prune(windows);
+    bindings.persist();
+    windowSignatures.clear();
+    for (const window of windows) {
+      if (Number.isInteger(window?.id)) windowSignatures.set(window.id, signatureOf(window));
+    }
+  }
+
+  /**
+   * A single window event. Returns true when the change can move or reveal a card.
+   * @param {NiriWindow} window
+   */
+  function observeWindowEvent(window) {
+    if (!Number.isInteger(window?.id)) return false;
+    const learned = bindings.observeWindows([window]);
+    const signature = signatureOf(window);
+    const changed = windowSignatures.get(window.id) !== signature;
+    windowSignatures.set(window.id, signature);
+    return learned.length > 0 || changed;
+  }
+
+  /**
+   * A card placed by a visible title proves which window holds that terminal. Remember it so the
+   * same tab stays placed once it is hidden behind another tab.
+   * @param {Array<Record<string, unknown>>} cards
+   * @param {NiriWindow[]} windows
+   */
+  function learnFromPlacements(cards, windows) {
+    const byId = new Map(
+      windows.filter((window) => Number.isInteger(window?.id)).map((window) => [window.id, window]),
+    );
+    const observed = [];
+    for (const card of cards ?? []) {
+      if (card?.placement !== "title") continue;
+      const cardId = String(card.cardId ?? "");
+      if (!cardId.startsWith("terminal:")) continue;
+      const window = byId.get(card.windowId);
+      if (!window || !Number.isInteger(window.pid)) continue;
+      observed.push({
+        bindingKey: cardId.slice("terminal:".length),
+        windowId: Number(window.id),
+        windowPid: Number(window.pid),
+        appId: String(window.app_id ?? ""),
+      });
+    }
+    if (observed.length > 0 && bindings.observeBindings(observed).length > 0) bindings.persist();
+  }
+
+  /** @param {number} windowId */
+  function forgetWindow(windowId) {
+    return windowSignatures.delete(windowId);
+  }
+
+  /** @param {NiriWindow[]} windows */
+  function ghosttyPidsOf(windows) {
+    return [
+      ...new Set(
+        windows
+          .filter(
+            (window) =>
+              Number.isInteger(window?.pid) && /ghostty/i.test(String(window?.app_id ?? "")),
+          )
+          .map((window) => Number(window.pid)),
+      ),
+    ];
+  }
+
+  /** @param {NiriWindow[]} windows */
+  function scheduleInventory(windows) {
+    if (runtimeStatus.tabInventoryState === "disabled" || inventoryInFlight) return;
+    if (now() < inventoryNextAt) return;
+    const pids = ghosttyPidsOf(windows);
+    if (pids.length === 0) return;
+    inventoryInFlight = true;
+    return probeInventory({ execFileAsync, env, pids })
+      .then((result) => {
+        runtimeStatus.tabInventoryProbedAt = now();
+        if (!result.ok) {
+          runtimeStatus.tabInventoryState = result.unavailable ? "unavailable" : "failed";
+          runtimeStatus.tabInventoryDetail = result.error;
+          inventoryNextAt =
+            now() +
+            (result.unavailable
+              ? TAB_INVENTORY_UNAVAILABLE_RETRY_MS
+              : TAB_INVENTORY_FAILURE_BACKOFF_MS);
+          return;
+        }
+        runtimeStatus.tabInventoryState = "ready";
+        runtimeStatus.tabInventoryDetail = null;
+        runtimeStatus.tabInventoryFrameCount = result.frames.length;
+        runtimeStatus.tabInventoryTabCount = result.frames.reduce(
+          (total, frame) => total + frame.tabs.length,
+          0,
+        );
+        const learned = bindings.observeBindings(mapTabInventoryToBindings(result.frames, windows));
+        // The shorter cadence is for catching up, so it only holds while the probe is still
+        // learning. A surface the inventory cannot see would otherwise pin it there forever.
+        const catchingUp = learned.length > 0 && (runtimeStatus.unplacedSurfaceCount ?? 0) > 0;
+        inventoryNextAt =
+          now() + (catchingUp ? TAB_INVENTORY_URGENT_INTERVAL_MS : TAB_INVENTORY_INTERVAL_MS);
+        if (learned.length > 0) {
+          bindings.persist();
+          onBindingsLearned();
+        }
+      })
+      .finally(() => {
+        inventoryInFlight = false;
+      });
+  }
+
+  return {
+    options,
+    observeWindowList,
+    observeWindowEvent,
+    learnFromPlacements,
+    forgetWindow,
+    countUnplaced,
+    scheduleInventory,
+    persist: () => bindings.persist(),
+    get bindingCount() {
+      return bindings.size;
+    },
+  };
+}

package/src/native/tab-inventory.mjs

@@ -0,0 +1,188 @@
+// ---
+// summary: "maps AT-SPI Ghostty tab labels onto exact Niri windows to place tabs that were never shown"
+// read_when:
+//   - "changing hidden-tab discovery, its cadence, or its capability gating"
+// ---
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { bindingKeysFor, parseTerminalTitleBinding } from "../common/surface-bindings.mjs";
+import { appIdForGhosttyFamily } from "../common/terminal-identity.mjs";
+
+const GHOSTTY_APP_IDS = new Set(["com.mitchellh.ghostty", "com.tryinget.ghosttysidequest"]);
+export const TAB_INVENTORY_SCRIPT = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "ghostty-tab-inventory.py",
+);
+export const TAB_INVENTORY_TIMEOUT_MS = 4000;
+export const TAB_INVENTORY_UNAVAILABLE_EXIT_CODE = 3;
+const ATSPI_IMPORT_PROBE =
+  "import gi; gi.require_version('Atspi', '2.0'); from gi.repository import Atspi";
+
+/** @typedef {{pid: number; name: string; tabs: string[]}} TabInventoryFrame */
+/** @typedef {{bindingKey: string; windowId: number; windowPid: number; appId: string}} TabBinding */
+/** @typedef {{ok: true; frames: TabInventoryFrame[]} | {ok: false; unavailable: boolean; error: string}} TabInventoryResult */
+/** @typedef {(file: string, args: string[], options: object) => Promise<{stdout?: string}>} ExecFileAsync */
+
+/** @param {NodeJS.ProcessEnv} env */
+function pythonBinaryFor(env) {
+  return env.PI_ACTIVITY_STRIP_PYTHON?.trim() || "python3";
+}
+
+/**
+ * A frame maps to exactly one Niri window of the same process with the same title; every other
+ * frame is skipped. Each tab label that carries a surface segment then binds that surface to the
+ * window. A surface claimed by two windows is dropped as ambiguous.
+ * @param {TabInventoryFrame[]} frames
+ * @param {Array<Record<string, unknown>>} windows
+ * @returns {TabBinding[]}
+ */
+export function mapTabInventoryToBindings(frames, windows) {
+  /** @type {Map<string, Array<Record<string, unknown>>>} */
+  const byTitle = new Map();
+  for (const window of windows) {
+    if (!Number.isInteger(window?.id) || !Number.isInteger(window?.pid)) continue;
+    if (!GHOSTTY_APP_IDS.has(String(window.app_id ?? ""))) continue;
+    const key = `${window.pid} ${String(window.title ?? "")}`;
+    const list = byTitle.get(key) ?? [];
+    list.push(window);
+    byTitle.set(key, list);
+  }
+
+  /** @type {Map<string, TabBinding[]>} */
+  const candidates = new Map();
+  for (const frame of frames) {
+    if (!Array.isArray(frame?.tabs) || frame.tabs.length === 0) continue;
+    const matches = byTitle.get(`${frame.pid} ${String(frame.name ?? "")}`) ?? [];
+    if (matches.length !== 1) continue;
+    const window = matches[0];
+    const appId = String(window.app_id ?? "");
+    for (const label of frame.tabs) {
+      const parsed = parseTerminalTitleBinding(label);
+      if (!parsed || appIdForGhosttyFamily(parsed.family) !== appId) continue;
+      for (const bindingKey of bindingKeysFor(parsed)) {
+        const list = candidates.get(bindingKey) ?? [];
+        list.push({
+          bindingKey,
+          windowId: Number(window.id),
+          windowPid: Number(window.pid),
+          appId,
+        });
+        candidates.set(bindingKey, list);
+      }
+    }
+  }
+
+  const bindings = [];
+  for (const list of candidates.values()) {
+    const windowIds = new Set(list.map((binding) => binding.windowId));
+    if (windowIds.size === 1) bindings.push(list[0]);
+  }
+  return bindings;
+}
+
+/**
+ * Run the read-only AT-SPI helper for the given Ghostty process ids. Absent Python bindings are
+ * reported as `unavailable` so the caller can stop probing; every other failure is transient.
+ * @param {{
+ *   execFileAsync: ExecFileAsync;
+ *   env?: NodeJS.ProcessEnv;
+ *   pids: number[];
+ *   pythonBin?: string;
+ *   scriptPath?: string;
+ *   timeout?: number;
+ * }} options
+ * @returns {Promise<TabInventoryResult>}
+ */
+export async function probeGhosttyTabInventory({
+  execFileAsync,
+  env = process.env,
+  pids,
+  pythonBin = pythonBinaryFor(env),
+  scriptPath = TAB_INVENTORY_SCRIPT,
+  timeout = TAB_INVENTORY_TIMEOUT_MS,
+}) {
+  const uniquePids = [...new Set(pids.filter((pid) => Number.isInteger(pid) && pid > 0))];
+  if (uniquePids.length === 0) return { ok: true, frames: [] };
+  let stdout = "";
+  try {
+    const result = await execFileAsync(pythonBin, [scriptPath, ...uniquePids.map(String)], {
+      env,
+      timeout,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    stdout = String(result.stdout ?? "");
+  } catch (error) {
+    const failure = /** @type {{code?: unknown; killed?: unknown; stdout?: unknown}} */ (
+      error && typeof error === "object" ? error : {}
+    );
+    const unavailable =
+      failure.code === TAB_INVENTORY_UNAVAILABLE_EXIT_CODE || failure.code === "ENOENT";
+    let detail = "the tab inventory helper failed";
+    try {
+      const parsed = JSON.parse(String(failure.stdout ?? ""));
+      if (typeof parsed?.error === "string") detail = parsed.error;
+    } catch {
+      if (failure.code === "ENOENT") detail = `${pythonBin} is not installed`;
+      else if (failure.killed) detail = "the tab inventory helper timed out";
+    }
+    return { ok: false, unavailable, error: detail };
+  }
+  try {
+    const parsed = JSON.parse(stdout);
+    if (parsed?.ok !== true || !Array.isArray(parsed.frames)) {
+      return {
+        ok: false,
+        unavailable: false,
+        error: "the tab inventory helper returned no frames",
+      };
+    }
+    return {
+      ok: true,
+      frames: parsed.frames
+        .filter(
+          /** @param {any} frame */ (frame) =>
+            Number.isInteger(frame?.pid) && Array.isArray(frame?.tabs),
+        )
+        .map(
+          /** @param {any} frame */ (frame) => ({
+            pid: Number(frame.pid),
+            name: String(frame.name ?? ""),
+            tabs: frame.tabs.map(String),
+          }),
+        ),
+    };
+  } catch {
+    return { ok: false, unavailable: false, error: "the tab inventory helper produced no JSON" };
+  }
+}
+
+/**
+ * Doctor-time capability probe. Importing the bindings touches no window.
+ * @param {{execFileAsync: ExecFileAsync; env?: NodeJS.ProcessEnv; timeout?: number}} options
+ * @returns {Promise<{available: boolean; detail: string}>}
+ */
+export async function detectTabInventorySupport({
+  execFileAsync,
+  env = process.env,
+  timeout = TAB_INVENTORY_TIMEOUT_MS,
+}) {
+  if (env.PI_ACTIVITY_STRIP_TAB_INVENTORY === "0") {
+    return { available: false, detail: "disabled by PI_ACTIVITY_STRIP_TAB_INVENTORY=0" };
+  }
+  const pythonBin = pythonBinaryFor(env);
+  try {
+    await execFileAsync(pythonBin, ["-c", ATSPI_IMPORT_PROBE], { env, timeout });
+    return { available: true, detail: `AT-SPI via ${pythonBin} gi.repository.Atspi` };
+  } catch (error) {
+    const code = /** @type {{code?: unknown}} */ (error && typeof error === "object" ? error : {})
+      .code;
+    return {
+      available: false,
+      detail:
+        code === "ENOENT"
+          ? `${pythonBin} is not installed`
+          : `${pythonBin} gi.repository.Atspi (python-gobject + at-spi2-core) is unavailable`,
+    };
+  }
+}

package/src/native/theme-runtime.mjs

@@ -0,0 +1,72 @@
+// ---
+// summary: "keeps the panel's colours in step with Ghostty's theme and the desktop's light/dark switch"
+// read_when:
+//   - "changing how often the ribbon re-reads the terminal theme"
+// ---
+
+import { paletteDefinitions } from "../common/ghostty-theme.mjs";
+import { detectColorScheme, resolveRibbonTheme, themeSourceFingerprint } from "./theme-source.mjs";
+
+/** A theme change is rare and never urgent, so it is polled on a calm clock. */
+export const THEME_POLL_INTERVAL_MS = 20_000;
+
+/**
+ * @param {{
+ *   execFileAsync: (file: string, args: string[], options: object) => Promise<{stdout?: string}>;
+ *   env?: NodeJS.ProcessEnv;
+ *   runtimeStatus: import("../common/contracts.ts").ActivityStripRuntimeStatus;
+ *   publish: (definitions: string) => void;
+ *   resolveTheme?: typeof resolveRibbonTheme;
+ *   detectScheme?: typeof detectColorScheme;
+ *   fingerprint?: typeof themeSourceFingerprint;
+ * }} options
+ */
+export function createThemeRuntime({
+  execFileAsync,
+  env = process.env,
+  runtimeStatus,
+  publish,
+  resolveTheme = resolveRibbonTheme,
+  detectScheme = detectColorScheme,
+  fingerprint = themeSourceFingerprint,
+}) {
+  let lastDefinitions = "";
+  let inFlight = false;
+
+  /**
+   * Resolve the current theme and hand it to the panel when anything about it changed. `force`
+   * republishes unchanged colours, which is what a freshly started panel needs.
+   * @param {{force?: boolean}} [options]
+   */
+  async function refresh({ force = false } = {}) {
+    if (inFlight) return false;
+    inFlight = true;
+    try {
+      const scheme = await detectScheme({ execFileAsync, env });
+      const resolved = resolveTheme({ scheme, env });
+      const definitions = paletteDefinitions(resolved.palette);
+      runtimeStatus.themeScheme = scheme;
+      runtimeStatus.themeName = resolved.themeName || null;
+      runtimeStatus.themeSource = resolved.themePath || resolved.configPath || null;
+      runtimeStatus.themeFingerprint = fingerprint(resolved);
+      if (!force && definitions === lastDefinitions) return false;
+      lastDefinitions = definitions;
+      publish(definitions);
+      return true;
+    } catch (error) {
+      runtimeStatus.themeError = error instanceof Error ? error.message : String(error);
+      return false;
+    } finally {
+      inFlight = false;
+    }
+  }
+
+  return {
+    refresh,
+    /** Re-send the colours the panel already had, after it restarts with none. */
+    republish: () => (lastDefinitions ? publish(lastDefinitions) : void refresh({ force: true })),
+    get definitions() {
+      return lastDefinitions;
+    },
+  };
+}

package/src/native/theme-source.mjs

@@ -0,0 +1,197 @@
+// ---
+// summary: "finds Ghostty's config and theme files and tracks the desktop's light/dark preference"
+// read_when:
+//   - "changing Ghostty theme discovery, colour-scheme detection, or the ribbon's theme refresh"
+// ---
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  buildRibbonPalette,
+  parseGhosttyConfig,
+  parseGhosttyTheme,
+  parseThemeSetting,
+} from "../common/ghostty-theme.mjs";
+
+export const COLOR_SCHEME_TIMEOUT_MS = 2000;
+/** The desktop portal's `color-scheme`: 1 asks for dark, 2 for light, 0 expresses no preference. */
+const PORTAL_ARGS = [
+  "call",
+  "--session",
+  "--dest",
+  "org.freedesktop.portal.Desktop",
+  "--object-path",
+  "/org/freedesktop/portal/desktop",
+  "--method",
+  "org.freedesktop.portal.Settings.ReadOne",
+  "org.freedesktop.appearance",
+  "color-scheme",
+];
+
+/** @typedef {{readFile: (p: string) => string; exists: (p: string) => boolean; mtime: (p: string) => number}} ThemeFs */
+
+/** @type {ThemeFs} */
+export const nodeThemeFs = {
+  readFile(filePath) {
+    try {
+      return fs.readFileSync(filePath, "utf8");
+    } catch {
+      return "";
+    }
+  },
+  exists(filePath) {
+    try {
+      return fs.existsSync(filePath);
+    } catch {
+      return false;
+    }
+  },
+  mtime(filePath) {
+    try {
+      return fs.statSync(filePath).mtimeMs;
+    } catch {
+      return 0;
+    }
+  },
+};
+
+/**
+ * Where Ghostty looks for its configuration, in the order it reads them.
+ * @param {{env?: NodeJS.ProcessEnv; homeDir?: string}} [options]
+ */
+export function ghosttyConfigPaths({ env = process.env, homeDir = os.homedir() } = {}) {
+  const explicit = String(env.GHOSTTY_CONFIG_PATH ?? "").trim();
+  const configHome = String(env.XDG_CONFIG_HOME ?? "").trim() || path.join(homeDir, ".config");
+  return [
+    ...(explicit ? [explicit] : []),
+    path.join(configHome, "ghostty", "config"),
+    path.join(homeDir, ".config", "ghostty", "config"),
+  ];
+}
+
+/**
+ * Directories that can hold a named theme. A user theme wins, as it does in Ghostty itself, and
+ * installed builds are searched because the current release may ship without the theme set.
+ * @param {{env?: NodeJS.ProcessEnv; homeDir?: string; fs?: ThemeFs}} [options]
+ */
+export function themeDirectories({
+  env = process.env,
+  homeDir = os.homedir(),
+  fs: fsImpl = nodeThemeFs,
+} = {}) {
+  const configHome = String(env.XDG_CONFIG_HOME ?? "").trim() || path.join(homeDir, ".config");
+  const resources = String(env.GHOSTTY_RESOURCES_DIR ?? "").trim();
+  const candidates = [
+    path.join(configHome, "ghostty", "themes"),
+    ...(resources ? [path.join(resources, "themes")] : []),
+    path.join(homeDir, ".local", "share", "ghostty", "themes"),
+    "/usr/share/ghostty/themes",
+    "/usr/local/share/ghostty/themes",
+  ];
+  // Installed builds keep their own resources; the newest that actually carries themes wins.
+  const optRoot = path.join(homeDir, ".local", "opt");
+  try {
+    for (const entry of fs.readdirSync(optRoot)) {
+      if (!entry.startsWith("ghostty")) continue;
+      for (const release of fs.readdirSync(path.join(optRoot, entry))) {
+        candidates.push(path.join(optRoot, entry, release, "share", "ghostty", "themes"));
+      }
+    }
+  } catch {
+    // No local installs to search.
+  }
+  return candidates.filter((directory) => fsImpl.exists(directory));
+}
+
+/**
+ * Ask the desktop which colour scheme it wants. An unavailable portal is not an error: the ribbon
+ * then follows whichever single theme the config names.
+ * @param {{execFileAsync: (file: string, args: string[], options: object) => Promise<{stdout?: string}>; env?: NodeJS.ProcessEnv; timeout?: number}} options
+ * @returns {Promise<"dark" | "light" | "unknown">}
+ */
+export async function detectColorScheme({
+  execFileAsync,
+  env = process.env,
+  timeout = COLOR_SCHEME_TIMEOUT_MS,
+}) {
+  // An explicit choice pins the ribbon to one scheme, for a desktop with no portal and for
+  // checking how the other scheme looks without changing the whole session.
+  const pinned = String(env.PI_ACTIVITY_STRIP_COLOR_SCHEME ?? "")
+    .trim()
+    .toLowerCase();
+  if (pinned === "dark" || pinned === "light") return pinned;
+  try {
+    const { stdout } = await execFileAsync("gdbus", PORTAL_ARGS, { env, timeout });
+    const match = String(stdout ?? "").match(/uint32\s+(\d+)/);
+    if (!match) return "unknown";
+    if (match[1] === "1") return "dark";
+    if (match[1] === "2") return "light";
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Resolve the palette Ghostty is presenting right now: the configured theme for the active colour
+ * scheme, read from the same files the terminal reads. Colours defined directly in the config take
+ * precedence over the theme, matching Ghostty's own layering.
+ * @param {{scheme?: "dark" | "light" | "unknown"; env?: NodeJS.ProcessEnv; homeDir?: string; fs?: ThemeFs}} [options]
+ */
+export function resolveRibbonTheme({
+  scheme = "unknown",
+  env = process.env,
+  homeDir = os.homedir(),
+  fs: fsImpl = nodeThemeFs,
+} = {}) {
+  const configPath = ghosttyConfigPaths({ env, homeDir }).find((candidate) =>
+    fsImpl.exists(candidate),
+  );
+  const configText = configPath ? fsImpl.readFile(configPath) : "";
+  const config = parseGhosttyConfig(configText);
+  const setting = parseThemeSetting((config.get("theme") ?? []).at(-1) ?? "");
+  const themeName =
+    scheme === "light" ? setting.light || setting.dark : setting.dark || setting.light;
+
+  let themeText = "";
+  let themePath = "";
+  if (themeName) {
+    for (const directory of themeDirectories({ env, homeDir, fs: fsImpl })) {
+      const candidate = path.join(directory, themeName);
+      if (!fsImpl.exists(candidate)) continue;
+      themePath = candidate;
+      themeText = fsImpl.readFile(candidate);
+      if (themeText) break;
+    }
+  }
+
+  const theme = parseGhosttyTheme(themeText);
+  const inline = parseGhosttyTheme(configText);
+  const merged = {
+    background: inline.background || theme.background,
+    foreground: inline.foreground || theme.foreground,
+    cursor: inline.cursor || theme.cursor,
+    selectionBackground: inline.selectionBackground || theme.selectionBackground,
+    palette: theme.palette.map((color, index) => inline.palette[index] || color),
+  };
+  return {
+    scheme,
+    themeName,
+    configPath: configPath ?? "",
+    themePath,
+    palette: buildRibbonPalette(merged),
+  };
+}
+
+/**
+ * Files whose modification should retrigger a resolve.
+ * @param {{configPath?: string; themePath?: string} | null} resolved
+ * @param {ThemeFs} [fsImpl]
+ */
+export function themeSourceFingerprint(resolved, fsImpl = nodeThemeFs) {
+  return [resolved?.configPath, resolved?.themePath]
+    .filter(Boolean)
+    .map((filePath) => `${filePath}:${fsImpl.mtime(String(filePath))}`)
+    .join("|");
+}