@tryinget/pi-activity-strip 0.5.0 → 0.7.0

package/src/common/surface-bindings.mjs

@@ -0,0 +1,234 @@
+// ---
+// summary: "remembers which Niri window last displayed each Ghostty terminal surface so hidden tabs stay placed"
+// read_when:
+//   - "changing hidden-tab placement memory, its persistence, or its invalidation rules"
+// ---
+
+import fs from "node:fs";
+import path from "node:path";
+import { appIdForGhosttyFamily, normalizeGhosttySurfaceId } from "./terminal-identity.mjs";
+
+export const SURFACE_BINDINGS_SCHEMA = "pi-activity-strip-surface-bindings.v1";
+const TITLE_BINDING = / · gs:(main|legacy):(\d+) · ([0-9a-f]{32})$/i;
+const SESSION_BINDING_PREFIX = "pi-session:";
+
+/**
+ * Ghostty surface ids are per-process handles that can drift from the value a long-lived Pi
+ * process captured at startup, while the 32-hex session token in the same title never does. Both
+ * keys are therefore remembered, and lookups prefer the more specific surface key.
+ * @param {unknown} sessionToken
+ */
+export function sessionBindingKey(sessionToken) {
+  const token = String(sessionToken ?? "")
+    .trim()
+    .toLowerCase();
+  return /^[0-9a-f]{32}$/.test(token) ? `${SESSION_BINDING_PREFIX}${token}` : "";
+}
+
+/** @typedef {{windowId: number; windowPid: number; appId: string; observedAt: number}} SurfaceBinding */
+/** @typedef {{instanceKey: string; filePath?: string; fs?: Pick<typeof fs, "readFileSync" | "writeFileSync" | "renameSync" | "mkdirSync" | "unlinkSync">; now?: () => number}} SurfaceBindingStoreOptions */
+
+/**
+ * A Ghostty window title only names its active tab. Parse that name into the bound terminal key so
+ * every observation of a visible title teaches which window currently owns the surface.
+ * @param {unknown} title
+ */
+export function parseTerminalTitleBinding(title) {
+  const match = String(title ?? "").match(TITLE_BINDING);
+  if (!match) return null;
+  const surfaceId = normalizeGhosttySurfaceId(match[2]);
+  if (!surfaceId) return null;
+  const family = String(match[1]).toLowerCase();
+  const sessionToken = String(match[3]).toLowerCase();
+  return {
+    family,
+    surfaceId,
+    sessionToken,
+    terminalKey: `ghostty:${family}:${surfaceId}`,
+    sessionKey: sessionBindingKey(sessionToken),
+  };
+}
+
+/**
+ * Every binding key a title or tab label teaches: the exact surface, and the logical session.
+ * @param {ReturnType<typeof parseTerminalTitleBinding>} parsed
+ */
+export function bindingKeysFor(parsed) {
+  return parsed ? [parsed.terminalKey, parsed.sessionKey].filter(Boolean) : [];
+}
+
+/**
+ * Bindings are memory, not proof: they are only consulted for windows that still exist, still
+ * belong to the same Ghostty process, and are still admitted by the terminal's own host process.
+ * Persisted memory is bound to one Niri instance because window ids restart with the compositor.
+ * @param {SurfaceBindingStoreOptions} options
+ */
+export function createSurfaceBindingStore({
+  instanceKey,
+  filePath = "",
+  fs: fsImpl = fs,
+  now = Date.now,
+}) {
+  /** @type {Map<string, SurfaceBinding>} */
+  const bindings = new Map();
+  let dirty = false;
+
+  function load() {
+    if (!filePath) return;
+    /** @type {any} */
+    let parsed;
+    try {
+      parsed = JSON.parse(fsImpl.readFileSync(filePath, "utf8"));
+    } catch {
+      return;
+    }
+    if (parsed?.schema !== SURFACE_BINDINGS_SCHEMA || parsed.instanceKey !== instanceKey) return;
+    const entries = /** @type {Array<[string, any]>} */ (Object.entries(parsed.bindings ?? {}));
+    for (const [terminalKey, value] of entries) {
+      if (
+        !Number.isInteger(value?.windowId) ||
+        !Number.isInteger(value?.windowPid) ||
+        typeof value?.appId !== "string"
+      ) {
+        continue;
+      }
+      bindings.set(terminalKey, {
+        windowId: value.windowId,
+        windowPid: value.windowPid,
+        appId: value.appId,
+        observedAt: Number(value.observedAt) || 0,
+      });
+    }
+  }
+
+  function persist() {
+    if (!filePath || !dirty) return false;
+    const temporaryPath = `${filePath}.tmp.${process.pid}`;
+    try {
+      fsImpl.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+      fsImpl.writeFileSync(
+        temporaryPath,
+        JSON.stringify({
+          schema: SURFACE_BINDINGS_SCHEMA,
+          instanceKey,
+          savedAt: now(),
+          bindings: Object.fromEntries(bindings),
+        }),
+        { mode: 0o600 },
+      );
+      fsImpl.renameSync(temporaryPath, filePath);
+      dirty = false;
+      return true;
+    } catch {
+      try {
+        fsImpl.unlinkSync(temporaryPath);
+      } catch {
+        // The temporary file never existed or is already gone.
+      }
+      return false;
+    }
+  }
+
+  /**
+   * Learn from every Ghostty window whose title carries a surface segment. Accepts a complete
+   * window list or a single window event. Returns the terminal keys whose binding changed.
+   * @param {Array<Record<string, unknown>>} windows
+   */
+  function observeWindows(windows) {
+    const changed = [];
+    for (const window of windows ?? []) {
+      if (!Number.isInteger(window?.id) || !Number.isInteger(window?.pid)) continue;
+      const parsed = parseTerminalTitleBinding(window.title);
+      if (!parsed) continue;
+      const appId = String(window.app_id ?? "");
+      if (appId !== appIdForGhosttyFamily(parsed.family)) continue;
+      for (const key of bindingKeysFor(parsed)) {
+        const previous = bindings.get(key);
+        if (previous?.windowId === window.id && previous?.windowPid === window.pid) continue;
+        bindings.set(key, {
+          windowId: Number(window.id),
+          windowPid: Number(window.pid),
+          appId,
+          observedAt: now(),
+        });
+        changed.push(key);
+        dirty = true;
+      }
+    }
+    return changed;
+  }
+
+  /**
+   * Adopt bindings established by an exact external inventory (for example AT-SPI tab labels
+   * already mapped onto windows). Returns the terminal keys whose binding changed.
+   * @param {Array<{bindingKey: string; windowId: number; windowPid: number; appId: string}>} observed
+   */
+  function observeBindings(observed) {
+    const changed = [];
+    for (const binding of observed ?? []) {
+      if (
+        typeof binding?.bindingKey !== "string" ||
+        !binding.bindingKey ||
+        !Number.isInteger(binding.windowId) ||
+        !Number.isInteger(binding.windowPid) ||
+        typeof binding.appId !== "string"
+      ) {
+        continue;
+      }
+      const previous = bindings.get(binding.bindingKey);
+      if (previous?.windowId === binding.windowId && previous?.windowPid === binding.windowPid) {
+        continue;
+      }
+      bindings.set(binding.bindingKey, {
+        windowId: binding.windowId,
+        windowPid: binding.windowPid,
+        appId: binding.appId,
+        observedAt: now(),
+      });
+      changed.push(binding.bindingKey);
+      dirty = true;
+    }
+    return changed;
+  }
+
+  /**
+   * Forget bindings whose window vanished or changed process identity. Only a complete window list
+   * may prune; an empty observation is indistinguishable from a failed read and is ignored.
+   * @param {Array<Record<string, unknown>>} windows
+   */
+  function prune(windows) {
+    if (!Array.isArray(windows) || windows.length === 0) return [];
+    const byId = new Map(
+      windows.filter((window) => Number.isInteger(window?.id)).map((window) => [window.id, window]),
+    );
+    const removed = [];
+    for (const [terminalKey, binding] of bindings) {
+      const window = byId.get(binding.windowId);
+      if (
+        window &&
+        window.pid === binding.windowPid &&
+        String(window.app_id ?? "") === binding.appId
+      ) {
+        continue;
+      }
+      bindings.delete(terminalKey);
+      removed.push(terminalKey);
+      dirty = true;
+    }
+    return removed;
+  }
+
+  load();
+  return {
+    observeWindows,
+    observeBindings,
+    prune,
+    persist,
+    /** @param {string} terminalKey */
+    lookup: (terminalKey) => bindings.get(terminalKey) ?? null,
+    entries: () => [...bindings.entries()],
+    get size() {
+      return bindings.size;
+    },
+  };
+}

package/src/common/terminal-identity.mjs

@@ -10,9 +10,11 @@ import path from "node:path";
 const UINT64_MAX = 18_446_744_073_709_551_615n;
 const GHOSTTY_MAIN_APP_ID = "com.mitchellh.ghostty";
 const GHOSTTY_LEGACY_APP_ID = "com.tryinget.ghosttysidequest";
+const HOST_PID_CACHE_LIMIT = 1024;
 
 /** @typedef {{terminalKind: "ghostty-surface" | "unbound"; terminalKey: string; terminalFamily: string; terminalSurfaceId: string}} TerminalIdentity */
 /** @typedef {{env?: NodeJS.ProcessEnv; hasUI?: boolean; stdinIsTTY?: boolean; ttyPath?: string; processId?: number; ancestorExecutable?: string}} TerminalIdentityOptions */
+/** @typedef {{readFile: (filePath: string) => string; readLink: (filePath: string) => string}} ProcfsReader */
 
 /** @param {string} filePath */
 function safeReadFile(filePath) {
@@ -32,19 +34,37 @@ function safeReadLink(filePath) {
   }
 }
 
-/** @param {number} pid */
-function readParentPid(pid) {
-  const value = safeReadFile(path.join("/proc", String(pid), "stat"));
+/** @type {ProcfsReader} */
+const defaultProcfs = { readFile: safeReadFile, readLink: safeReadLink };
+
+/**
+ * Fields after the parenthesized command name in /proc/<pid>/stat: index 1 is the parent pid and
+ * index 19 is the process start time in clock ticks since boot.
+ * @param {number} pid
+ * @param {ProcfsReader} procfs
+ */
+function readStatFields(pid, procfs) {
+  const value = procfs.readFile(path.join("/proc", String(pid), "stat"));
   const lastParen = value.lastIndexOf(")");
-  if (lastParen < 0) return 0;
-  const fields = value
+  if (lastParen < 0) return [];
+  return value
     .slice(lastParen + 2)
     .trim()
     .split(/\s+/);
-  const parentPid = Number.parseInt(fields[1] ?? "", 10);
+}
+
+/** @param {number} pid @param {ProcfsReader} [procfs] */
+function readParentPid(pid, procfs = defaultProcfs) {
+  const parentPid = Number.parseInt(readStatFields(pid, procfs)[1] ?? "", 10);
   return Number.isInteger(parentPid) && parentPid > 0 ? parentPid : 0;
 }
 
+/** @param {number} pid @param {ProcfsReader} [procfs] */
+export function readProcessStartTime(pid, procfs = defaultProcfs) {
+  const startTime = readStatFields(pid, procfs)[19] ?? "";
+  return /^\d+$/.test(startTime) ? startTime : "";
+}
+
 /** @param {unknown} value */
 export function normalizeGhosttySurfaceId(value) {
   try {
@@ -72,18 +92,61 @@ export function appIdForGhosttyFamily(family) {
   return "";
 }
 
-/** @param {number} [processId] */
-export function findGhosttyAncestorExecutable(processId = process.pid) {
+/**
+ * Walk the parent chain to the nearest live Ghostty process. That process owns every Wayland window
+ * a tab of this terminal can live in, which makes it the placement authority for hidden tabs.
+ * @param {number} [processId]
+ * @param {ProcfsReader} [procfs]
+ * @returns {{pid: number; executable: string} | null}
+ */
+export function findGhosttyAncestor(processId = process.pid, procfs = defaultProcfs) {
   let pid = Number(processId) || 0;
   for (let depth = 0; depth < 12 && pid > 0; depth += 1) {
-    pid = readParentPid(pid);
+    pid = readParentPid(pid, procfs);
     if (pid <= 0) break;
-    const command = safeReadFile(path.join("/proc", String(pid), "comm"))
+    const command = procfs
+      .readFile(path.join("/proc", String(pid), "comm"))
       .trim()
       .toLowerCase();
-    if (command === "ghostty") return safeReadLink(path.join("/proc", String(pid), "exe"));
+    if (command === "ghostty") {
+      return { pid, executable: procfs.readLink(path.join("/proc", String(pid), "exe")) };
+    }
   }
-  return "";
+  return null;
+}
+
+/** @param {number} [processId] @param {ProcfsReader} [procfs] */
+export function findGhosttyAncestorExecutable(processId = process.pid, procfs = defaultProcfs) {
+  return findGhosttyAncestor(processId, procfs)?.executable ?? "";
+}
+
+/**
+ * Resolve the live Ghostty process hosting a bound terminal surface. The publisher process must
+ * still exist and its Ghostty ancestor must belong to the admitted executable family; anything else
+ * fails closed to 0. Results are cached per process start time so pid reuse cannot leak a stale host.
+ * @param {Record<string, unknown>} session
+ * @param {{procfs?: ProcfsReader; cache?: Map<string, number>}} [options]
+ */
+export function resolveTerminalHostPid(session, options = {}) {
+  if (!canonicalGhosttyTerminalKey(session)) return 0;
+  const processId = Number(session.processId ?? 0);
+  if (!Number.isInteger(processId) || processId <= 0) return 0;
+  const procfs = options.procfs ?? defaultProcfs;
+  const startTime = readProcessStartTime(processId, procfs);
+  if (!startTime) return 0;
+  const cacheKey = `${processId}:${startTime}`;
+  const cached = options.cache?.get(cacheKey);
+  if (cached !== undefined) return cached;
+  const ancestor = findGhosttyAncestor(processId, procfs);
+  const hostPid =
+    ancestor && classifyGhosttyFamily(ancestor.executable) === session.terminalFamily
+      ? ancestor.pid
+      : 0;
+  if (options.cache) {
+    if (options.cache.size >= HOST_PID_CACHE_LIMIT) options.cache.clear();
+    options.cache.set(cacheKey, hostPid);
+  }
+  return hostPid;
 }
 
 /** @returns {TerminalIdentity} */

package/src/common/window-placement.mjs

@@ -0,0 +1,59 @@
+// ---
+// summary: "places bound Pi terminal surfaces onto Niri windows, including tabs hidden behind another tab"
+// read_when:
+//   - "changing how hidden Ghostty tabs are attributed to windows, workspaces, or activation targets"
+// ---
+
+import { sessionBindingKey } from "./surface-bindings.mjs";
+import { appIdForGhosttyFamily, canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
+
+/** @typedef {"title" | "host" | "binding"} SurfacePlacement */
+/** @typedef {{window: Record<string, unknown>; placement: SurfacePlacement}} WindowPlacement */
+/**
+ * @typedef {{
+ *   resolveHostPid?: (session: Record<string, unknown>) => number;
+ *   lookupBinding?: (bindingKey: string) => {windowId: number; windowPid: number} | null;
+ * }} PlacementOptions
+ */
+
+/**
+ * Place a bound surface whose title is not visible in any window. A surface can only live inside
+ * a window of its own Ghostty process, so a single host window is an exact placement. Several host
+ * windows require the window that last displayed this surface; without that memory the surface
+ * stays unplaced rather than guessed.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Record<string, unknown>} session
+ * @param {PlacementOptions & {sessionToken?: string}} [options]
+ * @returns {WindowPlacement | null}
+ */
+export function resolveHiddenSurfaceWindow(windows, session, options = {}) {
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  if (!terminalKey) return null;
+  const hostPid = Number(options.resolveHostPid?.(session) ?? 0);
+  if (!Number.isInteger(hostPid) || hostPid <= 0) return null;
+  const appId = appIdForGhosttyFamily(String(session.terminalFamily ?? ""));
+  const hostWindows = windows.filter(
+    (window) =>
+      Number.isInteger(window?.id) &&
+      window.pid === hostPid &&
+      String(window.app_id ?? "") === appId,
+  );
+  if (hostWindows.length === 1) return { window: hostWindows[0], placement: "host" };
+  if (hostWindows.length === 0) return null;
+  for (const key of [terminalKey, sessionBindingKey(options.sessionToken)].filter(Boolean)) {
+    const binding = options.lookupBinding?.(key);
+    if (!binding) continue;
+    const remembered = hostWindows.find(
+      (window) => window.id === binding.windowId && window.pid === binding.windowPid,
+    );
+    if (remembered) return { window: remembered, placement: "binding" };
+  }
+  return null;
+}
+
+/** @param {SurfacePlacement | undefined} placement */
+export function describePlacement(placement) {
+  if (placement === "host") return "hidden tab inside its Ghostty process's only window";
+  if (placement === "binding") return "hidden tab in the window that last displayed it";
+  return "visible tab";
+}

package/src/common/workspace-view.mjs

@@ -0,0 +1,161 @@
+// ---
+// summary: "projects tracked sessions onto one Niri workspace as cards with known visibility"
+// read_when:
+//   - "changing workspace card membership, card visibility, or focused-card selection"
+// ---
+
+import { canVerifyTabVisibility, placeSessionWindow } from "./niri-focus.mjs";
+import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
+import { parseTerminalTitleBinding } from "./surface-bindings.mjs";
+import { canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
+
+/** @typedef {import("./window-placement.mjs").PlacementOptions} PlacementOptions */
+/**
+ * @typedef {PlacementOptions & {
+ *   env?: NodeJS.ProcessEnv;
+ *   readFileSync?: typeof import("node:fs").readFileSync;
+ *   existsSync?: typeof import("node:fs").existsSync;
+ * }} ResolveOptions
+ */
+
+/**
+ * Decide whether a placed tab is the one its window is currently showing. A window title naming a
+ * different terminal surface, or missing a title this session is known to set, is proof the tab is
+ * hidden. Without either signal visibility is unknown, and an unknown tab is never marked hidden:
+ * an agent that sets no recognizable title would otherwise look permanently buried.
+ * @param {Record<string, unknown>} window
+ * @param {Record<string, unknown>} session
+ * @param {string} placement
+ * @param {ResolveOptions} [options]
+ * @returns {"visible" | "hidden" | "unknown"}
+ */
+export function resolveSurfaceVisibility(window, session, placement, options = {}) {
+  if (placement === "title") return "visible";
+  // A session that writes its own identity into the terminal title was already matched against
+  // every window title. Reaching here means no title matched, so this tab is not the one shown.
+  if (canVerifyTabVisibility(session, options)) return "hidden";
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  const titled = parseTerminalTitleBinding(window?.title);
+  if (titled && terminalKey && titled.terminalKey !== terminalKey) return "hidden";
+  return "unknown";
+}
+
+/**
+ * Project the global broker snapshot onto one exact Niri workspace. Membership requires an exact
+ * window placement: a visible title, or a hidden tab attributed through its Ghostty host process.
+ * Multiple publisher streams bound to the same terminal are aggregated into one stable card; a
+ * window may carry several terminal cards because each tab is its own surface, but a card claimed
+ * by distinct windows still fails closed. Only a visible tab in the focused window is "current".
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Record<string, unknown>} workspace
+ * @param {Array<Record<string, unknown>>} sessions
+ * @param {ResolveOptions} [options]
+ */
+export function resolveWorkspaceView(windows, workspace, sessions, options = {}) {
+  if (!Number.isInteger(workspace?.id)) return null;
+  /** @type {Array<{cardId: string; session: Record<string, unknown>; window: Record<string, unknown>; placement: string}>} */
+  const candidates = [];
+  for (const session of sessions) {
+    const placed = placeSessionWindow(windows, session, options);
+    if (!placed || placed.window.workspace_id !== workspace.id) continue;
+    const cardId = sessionCardId(session);
+    if (!cardId) continue;
+    candidates.push({
+      cardId,
+      session: { ...session, cardId },
+      window: placed.window,
+      placement: placed.placement,
+    });
+  }
+
+  /** @type {Map<unknown, Set<string>>} */
+  const cardIdsByWindow = new Map();
+  for (const candidate of candidates) {
+    const ids = cardIdsByWindow.get(candidate.window.id) ?? new Set();
+    ids.add(candidate.cardId);
+    cardIdsByWindow.set(candidate.window.id, ids);
+  }
+  /** @type {Map<unknown, Set<string>>} */
+  const allowedCardsByWindow = new Map();
+  for (const [windowId, ids] of cardIdsByWindow) {
+    const terminalIds = [...ids].filter((cardId) => cardId.startsWith("terminal:"));
+    if (terminalIds.length > 0) allowedCardsByWindow.set(windowId, new Set(terminalIds));
+    else if (ids.size === 1) allowedCardsByWindow.set(windowId, ids);
+  }
+
+  /** @type {Map<string, Array<{session: Record<string, unknown>; window: Record<string, unknown>; placement: string}>>} */
+  const groups = new Map();
+  for (const candidate of candidates) {
+    if (!allowedCardsByWindow.get(candidate.window.id)?.has(candidate.cardId)) continue;
+    const group = groups.get(candidate.cardId) ?? [];
+    group.push(candidate);
+    groups.set(candidate.cardId, group);
+  }
+
+  // The number the operator sees in the workspace list, not Niri's internal workspace id.
+  const workspaceIdx = Number.isInteger(workspace.idx) ? Number(workspace.idx) : null;
+  const projectedSessions = [];
+  for (const [cardId, group] of groups) {
+    const windowIds = new Set(group.map((candidate) => candidate.window.id));
+    if (windowIds.size !== 1) continue;
+    const [card] = projectSessionCards(group.map((candidate) => candidate.session));
+    if (!card) continue;
+    const window = group[0]?.window;
+    const placement = group.some((candidate) => candidate.placement === "title")
+      ? "title"
+      : (group[0]?.placement ?? "title");
+    const visibility = resolveSurfaceVisibility(
+      window,
+      group[0]?.session ?? card,
+      placement,
+      options,
+    );
+    projectedSessions.push({
+      ...card,
+      cardId,
+      // A hidden tab has no window of its own, so this is the window hosting it.
+      windowId: window?.id,
+      workspaceIdx,
+      placement,
+      // Only a tab proven to sit behind another one is marked hidden.
+      surfaceVisible: visibility !== "hidden",
+    });
+  }
+  // The focused window shows exactly one tab. Several candidates mean the compositor cannot tell
+  // us which, so nothing is marked current rather than marking the wrong one.
+  const focusedCandidates = projectedSessions.filter(
+    (session) =>
+      session.surfaceVisible &&
+      windows.some((window) => window?.id === session.windowId && window?.is_focused === true),
+  );
+  const focusedCard = focusedCandidates.length === 1 ? focusedCandidates[0] : null;
+  return {
+    workspace,
+    sessions: projectedSessions,
+    focusedSessionId: focusedCard ? String(focusedCard.sessionId ?? "") || null : null,
+    focusedCardId: focusedCard ? String(focusedCard.cardId ?? "") || null : null,
+  };
+}
+
+/**
+ * Project the global broker snapshot onto the one focused Niri workspace.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Array<Record<string, unknown>>} workspaces
+ * @param {Array<Record<string, unknown>>} sessions
+ * @param {ResolveOptions} [options]
+ */
+export function resolveFocusedWorkspaceView(windows, workspaces, sessions, options = {}) {
+  const workspace = resolveFocusedNiriWorkspace(workspaces);
+  return workspace ? resolveWorkspaceView(windows, workspace, sessions, options) : null;
+}
+
+/** @param {Array<Record<string, unknown>>} workspaces */
+export function resolveFocusedNiriWorkspace(workspaces) {
+  const matches = workspaces.filter(
+    (workspace) =>
+      workspace?.is_focused === true &&
+      Number.isInteger(workspace?.id) &&
+      (typeof workspace?.name === "string" || Number.isInteger(workspace?.idx)),
+  );
+  return matches.length === 1 ? matches[0] : null;
+}