@tryinget/pi-activity-strip 0.8.0 → 0.10.0

package/src/native/main.mjs

@@ -13,18 +13,30 @@ import { pruneClaudeEventRecords } from "../common/claude-events.mjs";
 import { ACTIVITY_STRIP_WORKSPACE_SYNC_MS } from "../common/constants.mjs";
 import { focusNiriSession, readNiriWindows, readNiriWorkspaces } from "../common/niri-focus.mjs";
 import { haveSameRecordMembership } from "../common/session-cards.mjs";
-import { resolveFocusedWorkspaceView } from "../common/workspace-view.mjs";
+import { resolveFocusedWorkspaceView, resolveWindowDirectory } from "../common/workspace-view.mjs";
 import { discoverAgentTabs } from "./agent-discovery.mjs";
 import { startAkTaskProjection } from "./ak-runtime.mjs";
 import { createHeightRepair } from "./height-repair.mjs";
+import { createHoverKeyboard } from "./hover-keyboard.mjs";
+import { createKeyboardEntry } from "./keyboard-entry.mjs";
 import { resolvePanelBinary } from "./panel-binary.mjs";
 import { createNativePanelProjection } from "./panel-projection.mjs";
+import { admitPanelEvent, PANEL_PROTOCOL } from "./panel-protocol.mjs";
+import { createPanelWindowJump } from "./panel-window-jump.mjs";
 import { createPlacementRuntime } from "./placement.mjs";
+import {
+  createRuntimeStatusReader,
+  recordNativeKeyboardObservation,
+} from "./runtime-diagnostics.mjs";
+import { resolveStripHotkey } from "./strip-hotkey.mjs";
 import { createThemeRuntime, THEME_POLL_INTERVAL_MS } from "./theme-runtime.mjs";
-import { createNiriWorkspaceEventWatcher } from "./workspace-events.mjs";
+import {
+  createNiriWorkspaceEventWatcher,
+  createWorkspaceProjectionHandlers,
+} from "./workspace-events.mjs";
 
 /** @typedef {import("../common/contracts.ts").ActivityStripRuntimeStatus} ActivityStripRuntimeStatus */
-/** @typedef {import("node:child_process").ChildProcessWithoutNullStreams & {_activityBuffer?: string; _readyTimer?: NodeJS.Timeout; _stableTimer?: NodeJS.Timeout}} PanelChild */
+/** @typedef {import("node:child_process").ChildProcessWithoutNullStreams & {_protocolError?: string; _activityBuffer?: string; _readyTimer?: NodeJS.Timeout; _stableTimer?: NodeJS.Timeout}} PanelChild */
 /** @typedef {{type: string; protocol?: number; revision?: number; visible?: boolean; sessions?: Array<Record<string, unknown>>; [key: string]: unknown}} PanelMessage */
 
 const execFileAsync = promisify(execFile);
@@ -80,8 +92,6 @@ function isNiriSession() {
   return Boolean(process.env.NIRI_SOCKET);
 }
 
-// Hidden Ghostty tabs are placed by their own runtime: host-process containment plus the window
-// memory learned from visible titles and the bounded AT-SPI tab inventory.
 const placement = createPlacementRuntime({
   env: process.env,
   runtimeStatus,
@@ -96,7 +106,9 @@ function writePanel(message) {
     return false;
   }
   try {
-    const accepted = panel.stdin.write(`${JSON.stringify(message)}\n`);
+    const accepted = panel.stdin.write(
+      `${JSON.stringify({ ...message, protocol: PANEL_PROTOCOL })}\n`,
+    );
     if (!accepted) {
       panelWriteReady = false;
       const child = panel;
@@ -119,6 +131,11 @@ function writePanel(message) {
 
 const projection = createNativePanelProjection({
   isNiriSession,
+  // Presence ("neutral") focus needs the focused window's app id from the event cache.
+  getWindowFacts: (id) => placement.getObservedWindow(id),
+  env: process.env,
+  // Read once: the panel's progressive hints name the shortcut the compositor really binds.
+  hotkey: resolveStripHotkey({ env: process.env }),
   publish(view) {
     runtimeStatus.rendererCardCount = view.sessions.length;
     runtimeStatus.rendererCardIds = view.sessions.map((session) => String(session.cardId ?? ""));
@@ -133,8 +150,7 @@ const projection = createNativePanelProjection({
   },
 });
 
-// AK task references are a read-only projection of claims held by live sessions; the strip
-// never writes AK state and renders nothing when the read fails.
+// Read-only AK task projection: never writes AK state or invents tasks on read failure.
 startAkTaskProjection({ execFileAsync, env: process.env, runtimeStatus, projection });
 
 /** @param {string} targetId @returns {Promise<{ok: boolean; error?: string; windowId?: number; presented?: boolean; verified?: boolean}>} */
@@ -158,17 +174,27 @@ async function focusSession(targetId) {
   return result;
 }
 
-async function focusStrip() {
-  if (runtimeStatus.clickThrough) {
-    return { ok: false, error: "Keyboard entry is disabled in click-through mode." };
-  }
-  if (!runtimeStatus.windowVisible || runtimeStatus.rendererCardCount === 0) {
-    return { ok: false, error: "No visible native strip exists on this workspace." };
-  }
-  return writePanel({ type: "focus-strip" })
-    ? { ok: true }
-    : { ok: false, error: "Native panel is not ready for keyboard entry." };
-}
+const requestWindowJump = createPanelWindowJump({
+  projection,
+  placementOptions: placement.options,
+  getWindowFacts: placement.getObservedWindow,
+  isNiriSession,
+  readWindows: () => getNiriWindows(),
+  readWorkspaces: () => getNiriWorkspaces(),
+  focusWindow: (id) =>
+    execFileAsync("niri", ["msg", "action", "focus-window", "--id", String(id)], {
+      env: process.env,
+    }),
+  reconcile: () => reconcileRunner.request(),
+});
+
+const requestKeyboardEntry = createKeyboardEntry({
+  projection,
+  runtimeStatus,
+  writePanel,
+});
+const focusStrip = async () => requestKeyboardEntry();
+let hoverKeyboard = createHoverKeyboard({ projection, runtimeStatus, writePanel });
 
 /** @param {PanelChild} child @param {unknown} chunk */
 function consumePanelEvents(child, chunk) {
@@ -181,13 +207,14 @@ function consumePanelEvents(child, chunk) {
     if (line) {
       try {
         const event = JSON.parse(line);
-        if (event.protocol !== 1) throw new Error("unsupported native panel protocol");
+        if (!admitPanelEvent(child, event, runtimeStatus, () => projection.cancelKeyboard()))
+          return;
         if (event.type === "ready") {
           clearTimeout(child._readyTimer);
           panelReady = true;
           runtimeStatus.state = "ready";
           runtimeStatus.readyAt = Date.now();
-          runtimeStatus.panelPid = Number(event.pid) || child.pid || null;
+          runtimeStatus.panelPid = child.pid ?? null; // Supervised child, never a reported PID.
           runtimeStatus.error = null;
           clearTimeout(child._stableTimer);
           child._stableTimer = setTimeout(() => {
@@ -209,9 +236,20 @@ function consumePanelEvents(child, chunk) {
           const visible = event.visible === true;
           const changed = runtimeStatus.windowVisible !== visible;
           runtimeStatus.windowVisible = visible;
-          // Showing or hiding the surface is the only moment the exclusive zone changes, so it is
-          // the only moment a tiled window can be left at the previous working area's height.
+          // Zone changes can leave tiled window heights stale.
           if (changed) void heightRepair.repairAfterZoneChange();
+        } else if (event.type === "hover-request") {
+          hoverKeyboard.request(Number(event.token), Number(event.epoch));
+        } else if (event.type === "hover-cancel") {
+          if (hoverKeyboard.cancel(Number(event.token))) reconcileRunner.request();
+        } else if (event.type === "keyboard-observation") {
+          recordNativeKeyboardObservation(runtimeStatus, event, child.pid);
+        } else if (event.type === "keyboard-active") {
+          const accepted = projection.keyboardChanged(
+            Number(event.revision),
+            event.active === true,
+          );
+          if (accepted && event.active !== true) reconcileRunner.request();
         } else if (event.type === "expanded") {
           runtimeStatus.panelExpanded = event.expanded === true;
         } else if (event.type === "activate") {
@@ -231,6 +269,17 @@ function consumePanelEvents(child, chunk) {
                 : result.error || "Focus failed; nothing moved.",
             }),
           );
+        } else if (event.type === "jump") {
+          runtimeStatus.panelJumpCount = (runtimeStatus.panelJumpCount ?? 0) + 1;
+          const windowId = Number(event.windowId);
+          void requestWindowJump(event).then((result) =>
+            writePanel({
+              type: "jump-result",
+              windowId,
+              ok: result.ok === true,
+              message: result.ok ? `Jumped to #${windowId}.` : result.error || "Nothing moved.",
+            }),
+          );
         } else if (event.type === "moved") {
           runtimeStatus.panelMoveCount = (runtimeStatus.panelMoveCount ?? 0) + 1;
           runtimeStatus.lastMovedCardId = String(event.cardId ?? "") || null;
@@ -255,10 +304,12 @@ function startPanel() {
     stdio: ["pipe", "pipe", "pipe"],
   });
   panel = child;
+  hoverKeyboard = createHoverKeyboard({ projection, runtimeStatus, writePanel });
   panelReady = false;
   panelWriteReady = true;
   panelStderr = "";
   runtimeStatus.panelPid = child.pid ?? null;
+  runtimeStatus.nativeKeyboardObservation = null; // New supervised child, new native clock domain.
   runtimeStatus.state = "starting";
   child.stdout.setEncoding("utf8");
   child.stdin.on("error", () => {
@@ -281,9 +332,15 @@ function startPanel() {
     clearTimeout(child._stableTimer);
     if (panel !== child) return;
     panelReady = false;
+    projection.cancelKeyboard();
     runtimeStatus.windowVisible = false;
     runtimeStatus.panelPid = null;
     if (shuttingDown) return;
+    if (child._protocolError) {
+      runtimeStatus.state = "error";
+      runtimeStatus.error = child._protocolError;
+      return;
+    }
     if (panelRestartCount < 3) {
       panelRestartCount += 1;
       runtimeStatus.panelRestartCount = panelRestartCount;
@@ -337,7 +394,7 @@ const theme = createThemeRuntime({
   execFileAsync,
   env: process.env,
   runtimeStatus,
-  publish: (definitions) => writePanel({ protocol: 1, type: "theme", definitions }),
+  publish: (definitions) => writePanel({ protocol: PANEL_PROTOCOL, type: "theme", definitions }),
 });
 
 const heightRepair = createHeightRepair({
@@ -361,7 +418,8 @@ const reconcileRunner = createLatestOnlyRunner(async ({ isCurrent }) => {
   const sessions = projection.getRawSessions();
   runtimeStatus.unplacedSurfaceCount = placement.countUnplaced(windows, sessions);
   const view = resolveFocusedWorkspaceView(windows, workspaces, sessions, placement.options);
-  if (view) placement.learnFromPlacements(view.sessions, windows);
+  placement.learnFromPlacements(view?.sessions ?? [], windows, sessions);
+  projection.setDirectory(resolveWindowDirectory(windows, workspaces, sessions, placement.options));
   projection.publishWorkspaceView(
     view ?? { workspace: null, sessions: [], focusedSessionId: null, focusedCardId: null },
   );
@@ -374,7 +432,7 @@ async function shutdown(exitCode = 0) {
   watcher?.stop();
   placement.persist();
   writePanel({
-    protocol: 1,
+    protocol: PANEL_PROTOCOL,
     type: "view",
     revision: Number.MAX_SAFE_INTEGER,
     visible: false,
@@ -394,14 +452,10 @@ async function main() {
   broker = await createActivityStripBroker({
     focusSession,
     focusStrip,
-    getRuntimeStatus: () => ({
-      ...runtimeStatus,
-      warnings: [...(runtimeStatus.warnings ?? [])],
-    }),
+    getRuntimeStatus: createRuntimeStatusReader({ runtimeStatus, projection }),
   });
   broker.on("snapshot", (snapshot) => {
-    // Compare like with like: the raw set also holds discovered agent tabs, which the broker
-    // never publishes, so comparing it to a broker snapshot would always differ and reconcile.
+    // Compare broker-only membership; discovered agent tabs must not force reconciliation.
     const membershipChanged = !haveSameRecordMembership(
       projection.getBrokerSessions(),
       snapshot.sessions,
@@ -417,16 +471,11 @@ async function main() {
     watcher = createNiriWorkspaceEventWatcher({
       spawn,
       env: process.env,
-      onFocusedWorkspace: () => reconcileRunner.request(),
-      onFallback: () => reconcileRunner.request(),
-      onWindowChanged: (window) => {
-        if (placement.observeWindowEvent(window)) reconcileRunner.request();
-      },
-      onWindowClosed: (windowId) => {
-        if (placement.forgetWindow(windowId)) reconcileRunner.request();
-      },
-      onWindowFocusChanged: () => reconcileRunner.request(),
-      onWorkspacesChanged: () => reconcileRunner.request(),
+      ...createWorkspaceProjectionHandlers({
+        projection,
+        placement,
+        reconcile: () => reconcileRunner.request(),
+      }),
       fallbackMs: ACTIVITY_STRIP_WORKSPACE_SYNC_MS,
     });
   }

package/src/native/panel-binary.mjs

@@ -8,6 +8,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { PANEL_PROTOCOL } from "./panel-protocol.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
@@ -15,13 +16,24 @@ const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "
 export function resolvePanelBinary(env) {
   const override = env.PI_ACTIVITY_STRIP_NATIVE_PANEL_BIN?.trim();
   const allowUnverified = env.PI_ACTIVITY_STRIP_ALLOW_UNVERIFIED_PANEL === "1";
-  const candidates = [
-    ...(override ? [override] : []),
-    path.join(packageRoot, "native", "bin", "linux-x64-gnu", "pi-activity-strip-panel"),
-    ...(allowUnverified
-      ? [path.join(packageRoot, "native", "panel", "target", "release", "pi-activity-strip-panel")]
-      : []),
-  ].filter(Boolean);
+  // An explicit selection is binding: losing it must not silently choose another build.
+  const candidates = override
+    ? [override]
+    : [
+        path.join(packageRoot, "native", "bin", "linux-x64-gnu", "pi-activity-strip-panel"),
+        ...(allowUnverified
+          ? [
+              path.join(
+                packageRoot,
+                "native",
+                "panel",
+                "target",
+                "release",
+                "pi-activity-strip-panel",
+              ),
+            ]
+          : []),
+      ];
   const binary = candidates.find((candidate) => {
     try {
       fs.accessSync(candidate, fs.constants.X_OK);
@@ -33,7 +45,6 @@ export function resolvePanelBinary(env) {
   if (!binary) {
     throw new Error(`Native panel binary is unavailable. Checked: ${candidates.join(", ")}`);
   }
-  if (allowUnverified) return binary;
   if (process.platform !== "linux" || process.arch !== "x64") {
     throw new Error(`Native panel requires Linux x64, got ${process.platform} ${process.arch}.`);
   }
@@ -44,6 +55,12 @@ export function resolvePanelBinary(env) {
   } catch {
     throw new Error(`Native panel receipt is unavailable: ${artifactPath}`);
   }
+  if (artifact.panelProtocol !== PANEL_PROTOCOL) {
+    throw new Error(
+      `Native panel private protocol mismatch in receipt: expected ${PANEL_PROTOCOL}, received ${String(artifact.panelProtocol)} (${artifactPath}). Rebuild/use a matching panel.`,
+    );
+  }
+  if (allowUnverified) return binary;
   const digest = createHash("sha256").update(fs.readFileSync(binary)).digest("hex");
   if (
     artifact.schema !== "pi-activity-strip-native-artifact.v1" ||

package/src/native/panel-neutral-source.mjs

@@ -0,0 +1,53 @@
+// ---
+// summary: "pins and rechecks the exact presence-app window behind neutral keyboard authorization"
+// read_when:
+//   - "changing neutral-source lifetime across panel NULL focus or delayed jumps"
+// ---
+
+import { classifyAdmittedWindowFocus } from "../common/workspace-view.mjs";
+import { sourceIdentity } from "./interaction-context.mjs";
+
+/** A presence app is a source window, not a card. Copy its process/app facts at admission so a
+ * fallback refresh cannot silently transfer an existing grant to a reused or relocated window.
+ * Niri reports `pid: null` for a client whose process it does not know; that null is pinned like a
+ * number, so the window keeps its presence and a pid that later differs still revokes it.
+ * @param {(id: number) => Record<string, unknown> | null} getWindowFacts
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function createNeutralSource(getWindowFacts, env) {
+  /** @type {Record<string, unknown> | null} */
+  let source = null;
+  return {
+    /** @param {Record<string, unknown> | null} facts */
+    admit(facts) {
+      source = facts ? { ...facts } : null;
+    },
+    clear() {
+      source = null;
+    },
+    /** @param {unknown} workspaceId @param {number | null} windowId
+     * @param {Record<string, unknown>[]} sessions */
+    holds(workspaceId, windowId, sessions) {
+      if (!source || windowId === null) return false;
+      const current = getWindowFacts(windowId);
+      return (
+        source.id === windowId &&
+        source.workspace_id === workspaceId &&
+        (source.pid === null || Number.isInteger(source.pid)) &&
+        current?.id === windowId &&
+        current.workspace_id === workspaceId &&
+        current.pid === source.pid &&
+        current.app_id === source.app_id &&
+        classifyAdmittedWindowFocus(windowId, sessions, current, env) === "neutral"
+      );
+    },
+    /** @param {unknown} workspaceId @param {number | null} windowId */
+    context(workspaceId, windowId) {
+      return JSON.stringify([
+        sourceIdentity(workspaceId, windowId, undefined),
+        source?.pid,
+        source?.app_id,
+      ]);
+    },
+  };
+}

package/src/native/panel-presentation.mjs

@@ -0,0 +1,137 @@
+// ---
+// summary: "keeps an already-visible ribbon mapped across a proven eligible handoff, without input authority"
+// read_when:
+//   - "Changing passive presentation during selected-window / seat-focus event ordering."
+// ---
+import { projectSessionCards } from "../common/session-cards.mjs";
+import { classifyAdmittedWindowFocus } from "../common/workspace-view.mjs";
+import {
+  publisherSet,
+  selectionContradictsSource,
+  sourceIdentity,
+  visibleCardsForWindow,
+} from "./interaction-context.mjs";
+
+/** Presentation only: no request, epoch, source admission, or keyboard eligibility is stored here.
+ * Both ends must retain exact complete-window admission and process/publisher identities.
+ * @param {{getWindowFacts: (id: number) => Record<string, unknown> | null;
+ * getCards: () => Record<string, unknown>[]; getRawSessions: () => Record<string, unknown>[];
+ * env: NodeJS.ProcessEnv}} options
+ */
+export function createPanelPresentation({ getWindowFacts, getCards, getRawSessions, env }) {
+  /** @type {ReturnType<typeof proof>} */
+  let source = null;
+  /** @type {{source: NonNullable<ReturnType<typeof proof>>; target: NonNullable<ReturnType<typeof proof>>} | null} */
+  let handoff = null;
+  /** @type {((workspace: Record<string, unknown>) => {sessions: Record<string, unknown>[]; focusKind?: string} | null) | null} */
+  let resolveView = null;
+
+  /** @param {Record<string, unknown> | null} workspace @param {number | null} id
+   * @param {Record<string, unknown>[]} cards */
+  function proof(workspace, id, cards) {
+    if (workspace?.is_focused !== true || id === null) return null;
+    const facts = getWindowFacts(id);
+    if (
+      facts?.id !== id ||
+      facts.workspace_id !== workspace.id ||
+      !(facts.pid === null || Number.isInteger(facts.pid)) ||
+      typeof facts.app_id !== "string"
+    )
+      return null;
+    const kind = classifyAdmittedWindowFocus(id, cards, facts, env);
+    if (kind !== "agent" && kind !== "neutral") return null;
+    const owner = visibleCardsForWindow(cards, id)[0];
+    if (kind === "agent") {
+      // A complete admission result, not an arbitrary legacy display card, is required to bridge.
+      if (owner?.surfaceVisible !== true || typeof owner.placement !== "string") return null;
+      const raw = projectSessionCards(getRawSessions(), null).find(
+        (card) => card.cardId === owner.cardId,
+      );
+      if (JSON.stringify(publisherSet(owner)) !== JSON.stringify(publisherSet(raw))) return null;
+    }
+    return {
+      id,
+      workspaceId: workspace.id,
+      pid: facts.pid,
+      appId: facts.app_id,
+      kind,
+      identity: sourceIdentity(workspace.id, id, owner),
+    };
+  }
+
+  function clear() {
+    source = null;
+    handoff = null;
+    resolveView = null;
+  }
+
+  /** @param {Record<string, unknown> | null} workspace
+   * @param {NonNullable<typeof resolveView>} [resolver] */
+  function holds(workspace, resolver) {
+    if (resolver) resolveView = resolver;
+    if (!handoff) return true;
+    if (
+      Object.hasOwn(workspace ?? {}, "active_window_id") &&
+      ![handoff.source.id, handoff.target.id].some((id) => id === workspace?.active_window_id)
+    )
+      return false;
+    const cached = workspace && resolveView?.(workspace);
+    if (!cached || !["agent", "neutral", "none"].includes(cached.focusKind ?? "unknown"))
+      return false;
+    return [handoff.source, handoff.target].every((pinned) =>
+      [getCards(), cached.sessions].every(
+        (cards) => JSON.stringify(proof(workspace, pinned.id, cards)) === JSON.stringify(pinned),
+      ),
+    );
+  }
+
+  /** A selection can keep an existing surface, never create a surface or input grant.
+   * @param {Record<string, unknown> | null} workspace @param {number | null} id
+   * @param {NonNullable<typeof resolveView>} resolver */
+  function prepare(workspace, id, resolver) {
+    resolveView = resolver;
+    if (source?.id === id) return;
+    const cached = workspace && resolver(workspace);
+    const target = cached ? proof(workspace, id, cached.sessions) : null;
+    if (!source || !target) {
+      clear();
+      return;
+    }
+    handoff = { source, target };
+    if (!holds(workspace)) clear();
+  }
+
+  return {
+    clear,
+    holds,
+    prepare,
+    /** Full reads can interleave the same way as incremental focus/selection events.
+     * @param {{workspace: Record<string, unknown> | null; sessions: Record<string, unknown>[]; focusKind?: string}} view
+     * @param {number | null} sourceId */
+    prepareView(view, sourceId) {
+      if (!["agent", "neutral", "none"].includes(view.focusKind ?? "unknown")) clear();
+      else if (selectionContradictsSource(view.workspace, sourceId))
+        prepare(
+          view.workspace,
+          Number.isSafeInteger(view.workspace?.active_window_id)
+            ? Number(view.workspace?.active_window_id)
+            : null,
+          () => view,
+        );
+    },
+    /** @param {number} id */
+    involves: (id) => handoff?.source.id === id || handoff?.target.id === id,
+    /** @param {boolean} eligible @param {Record<string, unknown> | null} workspace
+     * @param {number | null} id */
+    visible(eligible, workspace, id) {
+      if (eligible) {
+        source = proof(workspace, id, getCards());
+        handoff = null;
+        return true;
+      }
+      if (handoff && holds(workspace)) return true;
+      clear();
+      return false;
+    },
+  };
+}