@tryinget/pi-activity-strip 0.9.0 → 0.10.0

package/src/native/strip-hotkey-kdl.mjs

@@ -0,0 +1,252 @@
+// ---
+// summary: "reads active Niri binding/action nodes with the KDL v1 grammar niri itself parses"
+// read_when:
+//   - "changing the conservative focus-strip hotkey discovery grammar"
+// ---
+
+// KDL v1 (what niri 26.04 parses): newlines terminate nodes; these spaces only separate entries.
+const NEWLINE = /^(?:\r\n|[\n\r\f\u{85}\u{2028}\u{2029}])/u;
+const SPACE = /^[\t \u{A0}\u{1680}\u{2000}-\u{200A}\u{202F}\u{205F}\u{3000}\u{FEFF}]+/u;
+// A bare word: no control, space or newline character and none of KDL's `\/(){}<>;[]=,"`.
+const WORD =
+  /^[^\0-\x20\x7F-\x9F\u{A0}\u{1680}\u{2000}-\u{200A}\u{202F}\u{205F}\u{3000}\u{FEFF}\u{2028}\u{2029}\\/(){}<>;[\]=,"]+/u;
+const NUMBER =
+  /^[+-]?(?:[0-9][0-9_]*(?:\.[0-9][0-9_]*)?(?:[eE][+-]?[0-9][0-9_]*)?|0x[0-9a-fA-F][0-9a-fA-F_]*|0o[0-7][0-7_]*|0b[01][01_]*)$/;
+const KEYWORDS = new Set(["true", "false", "null"]);
+/** @type {Record<string, string>} */
+const ESCAPES = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+
+/** @typedef {{kind: string; value: string; spaced: boolean}} Token */
+
+/** @param {string} text @param {number} i @returns {number} index just past the comment */
+function skipBlockComment(text, i) {
+  let depth = 0;
+  do {
+    if (text.startsWith("/*", i)) {
+      depth++;
+      i += 2;
+    } else if (text.startsWith("*/", i)) {
+      depth--;
+      i += 2;
+    } else if (i < text.length) i++;
+    else throw new Error("unterminated comment");
+  } while (depth);
+  return i;
+}
+
+/** @param {string} text @param {number} i @returns {number} index of the line's newline or end */
+function skipLineComment(text, i) {
+  while (i < text.length && !NEWLINE.test(text.slice(i, i + 1))) i++;
+  return i;
+}
+
+/** `\` ws* (single-line comment | newline): joins a node's entries across lines.
+ * @param {string} text @param {number} i @returns {number} */
+function skipEscline(text, i) {
+  i++;
+  for (;;) {
+    const space = text.slice(i).match(SPACE);
+    if (space) i += space[0].length;
+    else if (text.startsWith("/*", i)) i = skipBlockComment(text, i);
+    else break;
+  }
+  if (text.startsWith("//", i)) i = skipLineComment(text, i);
+  else if (!NEWLINE.test(text.slice(i))) throw new Error("unsupported continuation");
+  return i + (text.slice(i).match(NEWLINE)?.[0].length ?? 0);
+}
+
+/** An escaped string with exactly KDL v1's escapes; literal newlines and tabs are content.
+ * @param {string} text @param {number} i @returns {[string, number]} */
+function readString(text, i) {
+  let value = "";
+  for (i++; ; ) {
+    const c = text[i];
+    if (c === undefined) throw new Error("unterminated string");
+    if (c === '"') return [value, i + 1];
+    if (c !== "\\") {
+      value += c;
+      i++;
+      continue;
+    }
+    const unicode = text.slice(i).match(/^\\u\{([0-9a-fA-F]{1,6})\}/);
+    const code = unicode ? Number.parseInt(unicode[1], 16) : -1;
+    if (unicode && code <= 0x10ffff && (code < 0xd800 || code > 0xdfff)) {
+      value += String.fromCodePoint(code);
+      i += unicode[0].length;
+    } else if (Object.hasOwn(ESCAPES, text[i + 1])) {
+      value += ESCAPES[text[i + 1]];
+      i += 2;
+    } else throw new Error("invalid string escape");
+  }
+}
+
+/** Unsupported or malformed input yields no hint, never a guessed shortcut; nothing is evaluated.
+ * @param {string} text @returns {Token[]} */
+function tokenize(text) {
+  if (text.length > 512 * 1024) throw new Error("config too large");
+  /** @type {Token[]} */
+  const tokens = [];
+  let spaced = false;
+  /** @param {string} kind @param {string} [value] */
+  const push = (kind, value = kind) => {
+    tokens.push({ kind, value, spaced });
+    spaced = kind === "escline";
+  };
+  let i = 0;
+  while (i < text.length) {
+    const rest = text.slice(i);
+    const space = rest.match(SPACE);
+    const newline = rest.match(NEWLINE);
+    const raw = rest.match(/^r(#*)"/);
+    const word = rest.match(WORD);
+    if (space) {
+      i += space[0].length;
+      spaced = true;
+    } else if (newline) {
+      i += newline[0].length;
+      push("newline");
+    } else if (rest.startsWith("/*")) {
+      i = skipBlockComment(text, i);
+      spaced = true;
+    } else if (rest.startsWith("//")) {
+      i = skipLineComment(text, i);
+    } else if (rest.startsWith("/-")) {
+      i += 2;
+      push("slashdash");
+    } else if (rest[0] === "\\") {
+      i = skipEscline(text, i);
+      push("escline");
+    } else if ("{};=".includes(rest[0])) {
+      push(rest[0]);
+      i++;
+    } else if (raw) {
+      const close = `"${raw[1]}`;
+      const end = text.indexOf(close, i + raw[0].length);
+      if (end < 0) throw new Error("unterminated raw string");
+      push("raw", text.slice(i + raw[0].length, end));
+      i = end + close.length;
+    } else if (rest[0] === '"') {
+      const [value, end] = readString(text, i);
+      push("string", value);
+      i = end;
+    } else if (word) {
+      // niri takes `!` only as a word's first character (after an optional sign). It joins a
+      // byte-order mark to a preceding identifier; after a number or keyword the mark would be
+      // whitespace, so refusing it there too only costs a hint.
+      if (!/^[+-]?!?[^!]*$/.test(word[0]) || text[i + word[0].length] === "\u{FEFF}")
+        throw new Error("unsupported KDL word");
+      push("word", word[0]);
+      i += word[0].length;
+    } else throw new Error("unsupported KDL character");
+  }
+  push("eof");
+  return tokens;
+}
+
+/** @typedef {{name: string; args: (string | null)[]; children: KdlNode[]}} KdlNode */
+/** Active nodes of a config niri's KDL v1 parser accepts; any grammar error yields none.
+ * Arguments keep string values; numbers and keywords become null and never match a command.
+ * @param {string} text @returns {KdlNode[]} */
+export function activeKdlNodes(text) {
+  try {
+    const tokens = tokenize(text);
+    let i = 0;
+    const peek = () => tokens[i];
+    /** Node-space may hold line continuations; a node's own entries may span lines with them. */
+    const skipEsclines = () => {
+      while (peek().kind === "escline") i++;
+    };
+    /** niri takes raw strings as property keys but never as node names. */
+    const identifier = (rawAllowed = false) => {
+      const token = tokens[i++];
+      if (token.kind === "string" || (rawAllowed && token.kind === "raw")) return token.value;
+      const bare =
+        token.kind === "word" && !KEYWORDS.has(token.value) && !/^[+-]?[0-9]/.test(token.value);
+      if (!bare) throw new Error("expected KDL identifier");
+      return token.value;
+    };
+    /** Bare identifiers are not values in KDL v1. */
+    const value = () => {
+      const token = tokens[i++];
+      if (token.kind === "string" || token.kind === "raw") return token.value;
+      if (token.kind === "word" && (KEYWORDS.has(token.value) || NUMBER.test(token.value)))
+        return null;
+      throw new Error("expected KDL value");
+    };
+    /** After a node only node-space, then `;`, a newline or the end; `}` is not a terminator. */
+    const terminate = () => {
+      skipEsclines();
+      const end = peek().kind;
+      if (end === "newline" || end === ";") i++;
+      else if (end !== "eof") throw new Error("missing node terminator");
+    };
+    /** @param {number} depth @returns {KdlNode | null} */
+    const node = (depth) => {
+      const disabled = peek().kind === "slashdash";
+      if (disabled) {
+        i++;
+        skipEsclines();
+      }
+      /** @type {KdlNode} */
+      const result = { name: identifier(), args: [], children: [] };
+      for (;;) {
+        skipEsclines();
+        const token = peek();
+        if (["newline", ";", "eof", "}"].includes(token.kind)) break;
+        const omit = token.kind === "slashdash";
+        let ahead = i + (omit ? 1 : 0);
+        while (tokens[ahead].kind === "escline") ahead++;
+        if (tokens[ahead].kind === "{") {
+          i = ahead + 1;
+          const children = nodes(true, depth + 1);
+          if (!omit) result.children = children;
+          break;
+        }
+        if (!token.spaced) throw new Error("missing entry separator");
+        if (omit) {
+          i++;
+          skipEsclines();
+        }
+        if (tokens[i + 1].kind === "=") {
+          identifier(true);
+          if (peek().spaced || tokens[i + 1].spaced) throw new Error("spaced property");
+          i++;
+          value();
+        } else {
+          const argument = value();
+          if (!omit) result.args.push(argument);
+        }
+      }
+      terminate();
+      return disabled ? null : result;
+    };
+    /** @param {boolean} nested @param {number} depth @returns {KdlNode[]} */
+    const nodes = (nested, depth) => {
+      if (depth > 64) throw new Error("config too deep");
+      /** @type {KdlNode[]} */
+      const result = [];
+      for (;;) {
+        const { kind } = peek();
+        if (kind === "newline") i++;
+        else if (kind === "eof" || kind === "}") {
+          if (nested !== (kind === "}")) throw new Error("unbalanced braces");
+          i++;
+          return result;
+        } else {
+          const parsed = node(depth);
+          if (parsed) result.push(parsed);
+        }
+      }
+    };
+    return nodes(false, 0);
+  } catch {
+    return [];
+  }
+}
+
+/** @param {KdlNode} action */
+export function isFocusStripAction(action) {
+  if (action.name !== "spawn") return false;
+  const args = /(?:^|\/)node$/.test(action.args[0] ?? "") ? action.args.slice(1) : action.args;
+  return /(?:^|\/)pi-activity-strip(?:\.mjs)?$/.test(args[0] ?? "") && args[1] === "focus-strip";
+}

package/src/native/strip-hotkey.mjs

@@ -0,0 +1,62 @@
+// ---
+// summary: "finds the compositor shortcut that enters the strip's keyboard mode, for the panel's hints"
+// read_when:
+//   - "changing how the strip learns or shows its keyboard-entry shortcut"
+// ---
+
+import { readFileSync as nodeReadFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { activeKdlNodes, isFocusStripAction } from "./strip-hotkey-kdl.mjs";
+
+/**
+ * The bind whose action runs this package's `focus-strip` command. Niri binds are KDL nodes named
+ * by their chord, `Mod+Shift+A repeat=false { spawn "node" ".../pi-activity-strip.mjs" "focus-strip"; }`,
+ * so discover it from active direct children of `binds` with an actual matching spawn action.
+ * Comments, disabled subtrees and quoted command lookalikes never count.
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function findFocusStripChord(text) {
+  for (const group of activeKdlNodes(String(text ?? ""))) {
+    if (group.name !== "binds") continue;
+    for (const bind of group.children) {
+      if (bind.children.some(isFocusStripAction)) return bind.name;
+    }
+  }
+  return null;
+}
+
+/** Niri's `Mod` is Super in a normal session; spell the chord the way a keyboard does.
+ * @param {string} chord */
+export function humanizeChord(chord) {
+  return chord
+    .split("+")
+    .map((part) => (part === "Mod" ? "Super" : part === "Mod5" ? "AltGr" : part))
+    .join("+");
+}
+
+/**
+ * `PI_ACTIVITY_STRIP_HOTKEY` names the shortcut directly (`none` hides it); otherwise the Niri
+ * config is read once at startup. A missing or unreadable config shows no shortcut rather than a
+ * guessed one: the hint must be the key the operator's compositor actually binds.
+ * @param {{env?: NodeJS.ProcessEnv; readFileSync?: typeof nodeReadFileSync; homeDir?: string}} [options]
+ * @returns {string | null}
+ */
+export function resolveStripHotkey({
+  env = process.env,
+  readFileSync = nodeReadFileSync,
+  homeDir = os.homedir(),
+} = {}) {
+  const override = String(env.PI_ACTIVITY_STRIP_HOTKEY ?? "").trim();
+  if (override) return override.toLowerCase() === "none" ? null : override;
+  const configHome = String(env.XDG_CONFIG_HOME ?? "").trim() || path.join(homeDir, ".config");
+  const configPath =
+    String(env.NIRI_CONFIG ?? "").trim() || path.join(configHome, "niri", "config.kdl");
+  try {
+    const chord = findFocusStripChord(readFileSync(configPath, "utf8"));
+    return chord ? humanizeChord(chord) : null;
+  } catch {
+    return null;
+  }
+}

package/src/native/tab-inventory.mjs

@@ -4,6 +4,7 @@
 //   - "changing hidden-tab discovery, its cadence, or its capability gating"
 // ---
 
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { bindingKeysFor, parseTerminalTitleBinding } from "../common/surface-bindings.mjs";
@@ -18,6 +19,22 @@ 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";
+// Signal names are a fixed OS vocabulary; anything else is reported as unknown.
+const FAILURE_SIGNALS = new Set(Object.keys(os.constants.signals));
+const FAILURE_STAGES = new Set([
+  "import",
+  "desktop-lookup",
+  "desktop-count",
+  "desktop-index",
+  "application-count",
+  "application-index",
+]);
+const FAILURE_REASONS = new Set([
+  "bindings-unavailable",
+  "desktop-unavailable",
+  "enumeration-failed",
+  "access-denied",
+]);
 
 /** @typedef {{pid: number; name: string; tabs: string[]}} TabInventoryFrame */
 /** @typedef {{bindingKey: string; windowId: number; windowPid: number; appId: string}} TabBinding */
@@ -113,20 +130,54 @@ export async function probeGhosttyTabInventory({
     });
     stdout = String(result.stdout ?? "");
   } catch (error) {
-    const failure = /** @type {{code?: unknown; killed?: unknown; stdout?: unknown}} */ (
-      error && typeof error === "object" ? error : {}
-    );
+    const failure =
+      /** @type {{code?: unknown; signal?: 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";
+    const code = Number.isSafeInteger(failure.code) ? failure.code : "unknown";
+    const signal =
+      typeof failure.signal === "string" && FAILURE_SIGNALS.has(failure.signal)
+        ? failure.signal
+        : "unknown";
+    // execFile marks only its own deadline kill as `killed`; output limits and aborts reject with
+    // a string code instead. The child's exit after that kill (signal or status) is kept as is.
+    let reason = "unknown";
+    switch (failure.code) {
+      case "ENOENT":
+        reason = "missing-interpreter";
+        break;
+      case TAB_INVENTORY_UNAVAILABLE_EXIT_CODE:
+        reason = "import-unavailable";
+        break;
+      case "EACCES":
+      case "EPERM":
+        reason = "access-denied";
+        break;
+      case "ERR_CHILD_PROCESS_STDIO_MAXBUFFER":
+        reason = "output-limit";
+        break;
+      default:
+        if (failure.killed === true && typeof failure.code !== "string") reason = "timeout";
+        else if (signal !== "unknown") reason = "signal";
+        else if (code !== "unknown") reason = "exit-status";
+        else if (failure.killed === true) reason = "terminated-unknown";
+    }
+    let stage = "unknown";
+    let helperReason = "unknown";
     try {
-      const parsed = JSON.parse(String(failure.stdout ?? ""));
-      if (typeof parsed?.error === "string") detail = parsed.error;
+      const parsed = JSON.parse(typeof failure.stdout === "string" ? failure.stdout : "");
+      if (FAILURE_STAGES.has(parsed?.stage)) stage = parsed.stage;
+      if (FAILURE_REASONS.has(parsed?.reason)) helperReason = parsed.reason;
     } catch {
-      if (failure.code === "ENOENT") detail = `${pythonBin} is not installed`;
-      else if (failure.killed) detail = "the tab inventory helper timed out";
+      /* Transport metadata is independent of helper JSON. */
     }
-    return { ok: false, unavailable, error: detail };
+    return {
+      ok: false,
+      unavailable,
+      error: `the tab inventory helper failed (reason=${reason}, code=${code}, signal=${signal}, stage=${stage}, helperReason=${helperReason})`,
+    };
   }
   try {
     const parsed = JSON.parse(stdout);
@@ -181,8 +232,8 @@ export async function detectTabInventorySupport({
       available: false,
       detail:
         code === "ENOENT"
-          ? `${pythonBin} is not installed`
-          : `${pythonBin} gi.repository.Atspi (python-gobject + at-spi2-core) is unavailable`,
+          ? "the tab inventory interpreter is not installed"
+          : "AT-SPI bindings (python-gobject + at-spi2-core) are unavailable",
     };
   }
 }

package/src/native/window-jump.mjs

@@ -0,0 +1,43 @@
+/** Numeric hover jumps remain bounded by the admitted directory, rechecked AFTER the IPC read.
+ * Explicit/manual ownership alone may request an existing unlisted window.
+ * @param {{
+ * isNiriSession: () => boolean;
+ * readWindows: () => Promise<Record<string, unknown>[]>;
+ * isAdmittedWindow: (id: number, windows: Record<string, unknown>[]) => boolean;
+ * focusWindow: (id: number) => Promise<unknown>;
+ * reconcile: () => void;
+ * }} options
+ */
+export function createWindowJump({
+  isNiriSession,
+  readWindows,
+  isAdmittedWindow,
+  focusWindow,
+  reconcile,
+}) {
+  /** @param {number} windowId @param {boolean} [allowUnlisted] @param {(windows: Record<string, unknown>[]) => boolean} [isCurrent] */
+  return async function jumpToWindow(windowId, allowUnlisted = false, isCurrent = () => true) {
+    if (!isNiriSession()) return { ok: false, error: "Niri is not available; nothing moved." };
+    if (!Number.isInteger(windowId) || windowId < 0)
+      return { ok: false, error: "Not a window number; nothing moved." };
+    let windows;
+    try {
+      windows = await readWindows();
+    } catch {
+      return { ok: false, error: "Could not read Niri windows; nothing moved." };
+    }
+    if (!isCurrent(windows))
+      return { ok: false, error: "Keyboard context was revoked; nothing moved." };
+    if (!allowUnlisted && !isAdmittedWindow(windowId, windows))
+      return { ok: false, error: "Window is not in the admitted agent directory; nothing moved." };
+    if (!windows.some((window) => window?.id === windowId))
+      return { ok: false, error: `No window #${windowId}; nothing moved.` };
+    try {
+      await focusWindow(windowId);
+    } catch {
+      return { ok: false, error: `Niri refused to focus #${windowId}; nothing moved.` };
+    }
+    reconcile();
+    return { ok: true };
+  };
+}

package/src/native/workspace-events.mjs

@@ -18,8 +18,11 @@
  *   onFallback: () => void;
  *   onWindowChanged?: (window: Record<string, unknown>) => void;
  *   onWindowClosed?: (windowId: number) => void;
+ *   onWindowsChanged?: (windows: Record<string, unknown>[]) => void;
  *   onWindowFocusChanged?: (windowId: number | null) => void;
+ *   onWorkspaceActiveWindowChanged?: (workspaceId: number, windowId: number | null) => void;
  *   onWorkspacesChanged?: () => void;
+ *   onFocusInvalidated?: () => void;
  *   fallbackMs: number;
  *   setIntervalFn?: typeof setInterval;
  *   clearIntervalFn?: typeof clearInterval;
@@ -40,6 +43,22 @@ export function createNiriWorkspaceEventWatcher(options) {
   }, options.fallbackMs);
   fallbackTimer.unref?.();
 
+  /** Selection is a contradiction signal, never a substitute for keyboard focus.
+   * @param {unknown} workspaceId @param {unknown} windowId */
+  function selection(workspaceId, windowId) {
+    if (
+      !Number.isSafeInteger(workspaceId) ||
+      Number(workspaceId) <= 0 ||
+      (windowId !== null && (!Number.isSafeInteger(windowId) || Number(windowId) <= 0))
+    )
+      options.onFocusInvalidated?.();
+    else
+      options.onWorkspaceActiveWindowChanged?.(
+        Number(workspaceId),
+        windowId === null ? null : Number(windowId),
+      );
+  }
+
   /** @param {unknown} chunk */
   function consume(chunk) {
     if (stopped) return;
@@ -61,8 +80,45 @@ export function createNiriWorkspaceEventWatcher(options) {
             options.onFocusedWorkspace(activation.id);
           }
           if (event && typeof event === "object" && "WorkspacesChanged" in event) {
+            const workspaces = event.WorkspacesChanged?.workspaces;
+            const valid =
+              Array.isArray(workspaces) &&
+              workspaces.every(
+                (workspace) =>
+                  Number.isInteger(workspace?.id) && typeof workspace?.is_focused === "boolean",
+              );
+            const focused = valid
+              ? workspaces.filter((workspace) => workspace.is_focused === true)
+              : [];
+            if (focused.length !== 1 || !Number.isInteger(focused[0].id))
+              options.onFocusInvalidated?.();
+            else if (focused[0].id !== lastFocusedWorkspaceId) {
+              lastFocusedWorkspaceId = focused[0].id;
+              options.onFocusedWorkspace(focused[0].id);
+            }
+            if (focused.length === 1 && Object.hasOwn(focused[0], "active_window_id"))
+              selection(focused[0].id, focused[0].active_window_id);
             options.onWorkspacesChanged?.();
           }
+          if (event && typeof event === "object" && "WindowsChanged" in event) {
+            const windows = event.WindowsChanged?.windows;
+            const valid =
+              Array.isArray(windows) &&
+              windows.every(
+                (window) => Number.isInteger(window?.id) && typeof window?.is_focused === "boolean",
+              );
+            if (valid) options.onWindowsChanged?.(windows);
+            const focused = valid ? windows.filter((window) => window.is_focused === true) : null;
+            if (focused?.length === 1 && Number.isInteger(focused[0].id))
+              options.onWindowFocusChanged?.(focused[0].id);
+            else if (focused?.length === 0 && windows.length > 0)
+              options.onWindowFocusChanged?.(null);
+            else options.onFocusInvalidated?.();
+          }
+          if (event && typeof event === "object" && "WorkspaceActiveWindowChanged" in event) {
+            const changed = event.WorkspaceActiveWindowChanged;
+            selection(changed?.workspace_id, changed?.active_window_id);
+          }
           const changedWindow = event?.WindowOpenedOrChanged?.window;
           if (changedWindow && typeof changedWindow === "object") {
             options.onWindowChanged?.(changedWindow);
@@ -71,7 +127,9 @@ export function createNiriWorkspaceEventWatcher(options) {
           if (Number.isInteger(closedId)) options.onWindowClosed?.(closedId);
           if (event && typeof event === "object" && "WindowFocusChanged" in event) {
             const focusedId = event.WindowFocusChanged?.id;
-            options.onWindowFocusChanged?.(Number.isInteger(focusedId) ? focusedId : null);
+            if (focusedId === null || Number.isInteger(focusedId))
+              options.onWindowFocusChanged?.(focusedId);
+            else options.onFocusInvalidated?.();
           }
         } catch {
           // A malformed event is ignored; the fallback poll remains authoritative.
@@ -87,8 +145,14 @@ export function createNiriWorkspaceEventWatcher(options) {
       stdio: ["ignore", "pipe", "ignore"],
     });
     child.stdout?.on?.("data", consume);
-    child.on?.("error", () => {});
+    child.on?.("error", () => {
+      if (!stopped) options.onFocusInvalidated?.();
+    });
+    child.on?.("close", () => {
+      if (!stopped) options.onFocusInvalidated?.();
+    });
   } catch {
+    options.onFocusInvalidated?.();
     child = null;
   }
 
@@ -103,3 +167,60 @@ export function createNiriWorkspaceEventWatcher(options) {
 
   return { stop };
 }
+
+/** Keep focus admission on the compositor event path; slow fallback reads must not queue a
+ * keyboard grab or override a newer known non-agent event.
+ * @param {{
+ *   projection: ReturnType<typeof import("./panel-projection.mjs").createNativePanelProjection>;
+ *   placement: Pick<ReturnType<typeof import("./placement.mjs").createPlacementRuntime>, "observeWindowEvent" | "observeWindowList" | "forgetWindow" | "resolveCachedWorkspaceView">;
+ *   reconcile: () => unknown;
+ * }} options
+ */
+export function createWorkspaceProjectionHandlers({ projection, placement, reconcile }) {
+  const invalidate = () => {
+    projection.invalidateFocus();
+    reconcile();
+  };
+  return {
+    onFocusedWorkspace: invalidate,
+    onFallback: reconcile,
+    onFocusInvalidated: invalidate,
+    /** @param {Record<string, unknown>} window */
+    onWindowChanged(window) {
+      const changed = placement.observeWindowEvent(window);
+      if (changed) projection.invalidateWindowFocus(Number(window.id));
+      // Correctness does not depend on the work-scheduling signature or on which window changed.
+      const valid = projection.revalidateWindowFocus(placement.resolveCachedWorkspaceView);
+      if (changed || !valid) reconcile();
+    },
+    /** @param {number} windowId */
+    onWindowClosed(windowId) {
+      projection.invalidateWindowFocus(windowId);
+      placement.forgetWindow(windowId);
+      projection.revalidateWindowFocus(placement.resolveCachedWorkspaceView);
+      reconcile();
+    },
+    /** @param {Record<string, unknown>[]} windows */
+    onWindowsChanged(windows) {
+      placement.observeWindowList(windows);
+      projection.revalidateWindowFocus(placement.resolveCachedWorkspaceView);
+      reconcile();
+    },
+    /** @param {number | null} windowId */
+    onWindowFocusChanged(windowId) {
+      projection.publishWindowFocus(windowId, placement.resolveCachedWorkspaceView);
+      reconcile();
+    },
+    /** @param {number} workspaceId @param {number | null} windowId */
+    onWorkspaceActiveWindowChanged(workspaceId, windowId) {
+      projection.observeWorkspaceSelection(
+        workspaceId,
+        windowId,
+        placement.resolveCachedWorkspaceView,
+      );
+      projection.revalidateWindowFocus(placement.resolveCachedWorkspaceView);
+      reconcile();
+    },
+    onWorkspacesChanged: reconcile,
+  };
+}