@tryinget/pi-activity-strip 0.3.0 → 0.5.0

package/src/common/status-report.mjs

@@ -14,6 +14,7 @@ export function formatBrokerRuntimeStatus(result) {
 
   const lines = [
     runtime.state === "ready" ? "running (ready)" : `running (${runtime.state})`,
+    `backend: ${runtime.backend || "unknown"}`,
     `display: ${runtime.displayServer || "unknown"}`,
     `window manager: ${runtime.windowManager || "unknown"}`,
     `alignment: ${runtime.alignmentMode || "unknown"}`,
@@ -23,7 +24,7 @@ export function formatBrokerRuntimeStatus(result) {
     lines.push(`displays: ${runtime.displayCount}`);
   }
   if (typeof runtime.windowVisible === "boolean") {
-    lines.push(`window visible: ${runtime.windowVisible ? "yes" : "no"}`);
+    lines.push(`surface visible: ${runtime.windowVisible ? "yes" : "no"}`);
   }
   if (runtime.error) {
     lines.push(`error: ${runtime.error}`);

package/src/common/telemetry.mjs

@@ -67,16 +67,25 @@ export function createSessionId() {
   return `${os.hostname()}-${process.pid}-${Date.now()}-${randomUUID().slice(0, 6)}`;
 }
 
-/** @param {{ cwd?: string; sessionName?: string; sessionId?: string }} [options] @returns {SessionSnapshot} */
+/** @param {{ cwd?: string; sessionName?: string; sessionId?: string; publisherId?: string; terminalIdentity?: {terminalKind?: string; terminalKey?: string; terminalFamily?: string; terminalSurfaceId?: string} }} [options] @returns {SessionSnapshot} */
 export function createInitialSnapshot({
   cwd = process.cwd(),
   sessionName = "",
   sessionId = "",
+  publisherId = "",
+  terminalIdentity = {},
 } = {}) {
   const now = Date.now();
   return {
     sessionId: sessionId.trim() || createSessionId(),
+    publisherId: publisherId.trim() || randomUUID(),
+    publisherSequence: 0,
     processId: process.pid,
+    terminalKind:
+      terminalIdentity.terminalKind === "ghostty-surface" ? "ghostty-surface" : "unbound",
+    terminalKey: String(terminalIdentity.terminalKey ?? ""),
+    terminalFamily: String(terminalIdentity.terminalFamily ?? ""),
+    terminalSurfaceId: String(terminalIdentity.terminalSurfaceId ?? ""),
     cwd,
     repoLabel: formatRepoLabel(cwd, sessionName),
     sessionName: compactWhitespace(sessionName),
@@ -88,6 +97,7 @@ export function createInitialSnapshot({
     state: "idle",
     turnIndex: 0,
     updatedAt: now,
+    lastEventAt: now,
     startedAt: now,
     agentStartedAt: null,
     agentActive: false,

package/src/common/terminal-identity.mjs

@@ -0,0 +1,149 @@
+// ---
+// summary: "derives bounded terminal-surface identities for activity-strip publisher and focus contracts"
+// read_when:
+//   - "changing terminal card identity, Ghostty surface admission, or title matching"
+// ---
+
+import fs from "node:fs";
+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";
+
+/** @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 */
+
+/** @param {string} filePath */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** @param {string} filePath */
+function safeReadLink(filePath) {
+  try {
+    return fs.readlinkSync(filePath);
+  } catch {
+    return "";
+  }
+}
+
+/** @param {number} pid */
+function readParentPid(pid) {
+  const value = safeReadFile(path.join("/proc", String(pid), "stat"));
+  const lastParen = value.lastIndexOf(")");
+  if (lastParen < 0) return 0;
+  const fields = value
+    .slice(lastParen + 2)
+    .trim()
+    .split(/\s+/);
+  const parentPid = Number.parseInt(fields[1] ?? "", 10);
+  return Number.isInteger(parentPid) && parentPid > 0 ? parentPid : 0;
+}
+
+/** @param {unknown} value */
+export function normalizeGhosttySurfaceId(value) {
+  try {
+    const normalized = BigInt(String(value ?? "").trim());
+    return normalized >= 0n && normalized <= UINT64_MAX ? normalized.toString(10) : "";
+  } catch {
+    return "";
+  }
+}
+
+/** @param {unknown} executable */
+export function classifyGhosttyFamily(executable) {
+  const normalized = String(executable ?? "").toLowerCase();
+  if (!normalized) return "";
+  if (normalized.includes("ghostty-sidequest")) return "legacy";
+  if (path.basename(normalized) === "ghostty" || normalized.includes("ghostty-origin"))
+    return "main";
+  return "";
+}
+
+/** @param {unknown} family */
+export function appIdForGhosttyFamily(family) {
+  if (family === "main") return GHOSTTY_MAIN_APP_ID;
+  if (family === "legacy") return GHOSTTY_LEGACY_APP_ID;
+  return "";
+}
+
+/** @param {number} [processId] */
+export function findGhosttyAncestorExecutable(processId = process.pid) {
+  let pid = Number(processId) || 0;
+  for (let depth = 0; depth < 12 && pid > 0; depth += 1) {
+    pid = readParentPid(pid);
+    if (pid <= 0) break;
+    const command = safeReadFile(path.join("/proc", String(pid), "comm"))
+      .trim()
+      .toLowerCase();
+    if (command === "ghostty") return safeReadLink(path.join("/proc", String(pid), "exe"));
+  }
+  return "";
+}
+
+/** @returns {TerminalIdentity} */
+export function unboundTerminalIdentity() {
+  return {
+    terminalKind: "unbound",
+    terminalKey: "",
+    terminalFamily: "",
+    terminalSurfaceId: "",
+  };
+}
+
+/**
+ * Admit a terminal binding only for an interactive TUI attached to a real TTY and a recognized
+ * Ghostty process family. Headless descendants commonly inherit Ghostty environment variables, so
+ * GHOSTTY_SURFACE_ID alone is not evidence of an operator-visible terminal.
+ * @param {TerminalIdentityOptions} [options]
+ * @returns {TerminalIdentity}
+ */
+export function resolveTerminalIdentity({
+  env = process.env,
+  hasUI = false,
+  stdinIsTTY = Boolean(process.stdin.isTTY),
+  ttyPath = safeReadLink("/proc/self/fd/0"),
+  processId = process.pid,
+  ancestorExecutable,
+} = {}) {
+  if (
+    !hasUI ||
+    !stdinIsTTY ||
+    !ttyPath.startsWith("/dev/") ||
+    String(env.TERM_PROGRAM ?? "").toLowerCase() !== "ghostty"
+  ) {
+    return unboundTerminalIdentity();
+  }
+  const surfaceId = normalizeGhosttySurfaceId(env.GHOSTTY_SURFACE_ID);
+  const executable = ancestorExecutable ?? findGhosttyAncestorExecutable(processId);
+  const family = classifyGhosttyFamily(executable);
+  if (!surfaceId || !family) return unboundTerminalIdentity();
+  return {
+    terminalKind: "ghostty-surface",
+    terminalKey: `ghostty:${family}:${surfaceId}`,
+    terminalFamily: family,
+    terminalSurfaceId: surfaceId,
+  };
+}
+
+/** @param {Partial<TerminalIdentity> | Record<string, unknown>} identity */
+export function canonicalGhosttyTerminalKey(identity) {
+  if (identity?.terminalKind !== "ghostty-surface") return "";
+  const family = String(identity.terminalFamily ?? "");
+  if (family !== "main" && family !== "legacy") return "";
+  const surfaceId = normalizeGhosttySurfaceId(identity.terminalSurfaceId);
+  if (!surfaceId) return "";
+  const expectedKey = `ghostty:${family}:${surfaceId}`;
+  return String(identity.terminalKey ?? "") === expectedKey ? expectedKey : "";
+}
+
+/** @param {Partial<TerminalIdentity> | Record<string, unknown>} identity */
+export function terminalTitleSegment(identity) {
+  if (!canonicalGhosttyTerminalKey(identity)) return "";
+  return `gs:${identity.terminalFamily}:${normalizeGhosttySurfaceId(identity.terminalSurfaceId)}`;
+}

package/src/native/main.mjs

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+// ---
+// summary: "runs the broker and workspace projection for the native GTK layer-shell panel"
+// read_when:
+//   - "changing native activity-strip supervision or panel protocol"
+// ---
+
+import { execFile, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { createActivityStripBroker } from "../broker/server.mjs";
+import { createLatestOnlyRunner } from "../common/alignment-controller.mjs";
+import { ACTIVITY_STRIP_WORKSPACE_SYNC_MS } from "../common/constants.mjs";
+import {
+  focusNiriSession,
+  readNiriWindows,
+  readNiriWorkspaces,
+  resolveFocusedWorkspaceView,
+} from "../common/niri-focus.mjs";
+import { haveSameRecordMembership } from "../common/session-cards.mjs";
+import { createNativePanelProjection } from "./panel-projection.mjs";
+import { createNiriWorkspaceEventWatcher } 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 {{type: string; protocol?: number; revision?: number; visible?: boolean; sessions?: Array<Record<string, unknown>>; [key: string]: unknown}} PanelMessage */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..", "..");
+const execFileAsync = promisify(execFile);
+
+/** @type {import("../broker/server.mjs").ActivityStripBroker | null} */
+let broker = null;
+/** @type {PanelChild | null} */
+let panel = null;
+/** @type {{stop: () => void} | null} */
+let watcher = null;
+let panelReady = false;
+let panelWriteReady = true;
+/** @type {PanelMessage | null} */
+let pendingView = null;
+let shuttingDown = false;
+let panelStderr = "";
+let panelRestartCount = 0;
+
+/** @type {ActivityStripRuntimeStatus} */
+const runtimeStatus = {
+  state: "starting",
+  backend: "native-layer-shell",
+  displayServer: process.env.WAYLAND_DISPLAY ? "wayland" : "unknown",
+  windowManager: isNiriSession() ? "niri" : null,
+  alignmentMode: "layer-shell",
+  startedAt: Date.now(),
+  readyAt: null,
+  controllerPid: process.pid,
+  panelPid: null,
+  windowVisible: false,
+  panelExpanded: false,
+  clickThrough: process.env.PI_ACTIVITY_STRIP_CLICK_THROUGH === "1",
+  panelMoveCount: 0,
+  panelActivationCount: 0,
+  panelRestartCount: 0,
+  lastMovedCardId: null,
+  rendererCardCount: 0,
+  rendererCardIds: [],
+  warnings: [],
+  error: null,
+};
+
+function isNiriSession() {
+  return Boolean(process.env.NIRI_SOCKET);
+}
+
+function panelBinaryPath() {
+  const override = process.env.PI_ACTIVITY_STRIP_NATIVE_PANEL_BIN?.trim();
+  const allowUnverified = process.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);
+  const binary = candidates.find((candidate) => {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  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}.`);
+  }
+  const artifactPath = path.join(path.dirname(binary), "artifact.json");
+  let artifact;
+  try {
+    artifact = JSON.parse(fs.readFileSync(artifactPath, "utf8"));
+  } catch {
+    throw new Error(`Native panel receipt is unavailable: ${artifactPath}`);
+  }
+  const digest = createHash("sha256").update(fs.readFileSync(binary)).digest("hex");
+  if (
+    artifact.schema !== "pi-activity-strip-native-artifact.v1" ||
+    artifact.target !== "x86_64-unknown-linux-gnu" ||
+    artifact.sha256 !== digest
+  ) {
+    throw new Error("Native panel binary does not match its reviewed artifact receipt.");
+  }
+  return binary;
+}
+
+/** @param {PanelMessage} message */
+function writePanel(message) {
+  if (!panelReady || !panelWriteReady || !panel?.stdin?.writable) {
+    if (message?.type === "view") pendingView = message;
+    return false;
+  }
+  try {
+    const accepted = panel.stdin.write(`${JSON.stringify(message)}\n`);
+    if (!accepted) {
+      panelWriteReady = false;
+      const child = panel;
+      child.stdin.once("drain", () => {
+        if (panel !== child) return;
+        panelWriteReady = true;
+        if (pendingView) {
+          const view = pendingView;
+          pendingView = null;
+          writePanel(view);
+        }
+      });
+    }
+    return true;
+  } catch {
+    if (message?.type === "view") pendingView = message;
+    return false;
+  }
+}
+
+const projection = createNativePanelProjection({
+  isNiriSession,
+  publish(view) {
+    runtimeStatus.rendererCardCount = view.sessions.length;
+    runtimeStatus.rendererCardIds = view.sessions.map((session) => String(session.cardId ?? ""));
+    writePanel(view);
+  },
+});
+
+/** @param {string} targetId @returns {Promise<{ok: boolean; error?: string; windowId?: number}>} */
+async function focusSession(targetId) {
+  const session = projection.resolveTarget(targetId);
+  if (!session) {
+    return { ok: false, error: "Session is no longer present or is ambiguous; focus did nothing." };
+  }
+  const rawResult = await focusNiriSession(session, execFileAsync, process.env);
+  const result = {
+    ok: rawResult.ok === true,
+    ...(typeof rawResult.error === "string" ? { error: rawResult.error } : {}),
+    ...(Number.isInteger(rawResult.windowId) ? { windowId: Number(rawResult.windowId) } : {}),
+  };
+  if (result.ok) {
+    projection.setFocused(session);
+    reconcileRunner.request();
+  }
+  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." };
+}
+
+/** @param {PanelChild} child @param {unknown} chunk */
+function consumePanelEvents(child, chunk) {
+  if (panel !== child) return;
+  child._activityBuffer = `${child._activityBuffer ?? ""}${String(chunk ?? "")}`;
+  let newline = child._activityBuffer.indexOf("\n");
+  while (newline >= 0) {
+    const line = child._activityBuffer.slice(0, newline).trim();
+    child._activityBuffer = child._activityBuffer.slice(newline + 1);
+    if (line) {
+      try {
+        const event = JSON.parse(line);
+        if (event.protocol !== 1) throw new Error("unsupported native panel protocol");
+        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.error = null;
+          clearTimeout(child._stableTimer);
+          child._stableTimer = setTimeout(() => {
+            if (panel === child && panelReady) {
+              panelRestartCount = 0;
+              runtimeStatus.panelRestartCount = 0;
+            }
+          }, 30_000);
+          child._stableTimer.unref?.();
+          if (pendingView) {
+            const view = pendingView;
+            pendingView = null;
+            writePanel(view);
+          } else {
+            projection.send();
+          }
+        } else if (event.type === "visibility-applied") {
+          runtimeStatus.windowVisible = event.visible === true;
+        } else if (event.type === "expanded") {
+          runtimeStatus.panelExpanded = event.expanded === true;
+        } else if (event.type === "activate") {
+          runtimeStatus.panelActivationCount = (runtimeStatus.panelActivationCount ?? 0) + 1;
+          const cardId = String(event.cardId ?? "");
+          void focusSession(cardId).then((result) =>
+            writePanel({
+              type: "activation-result",
+              cardId,
+              ok: result.ok === true,
+              message: result.ok
+                ? "Focused Ghostty window."
+                : result.error || "Focus failed; nothing moved.",
+            }),
+          );
+        } else if (event.type === "moved") {
+          runtimeStatus.panelMoveCount = (runtimeStatus.panelMoveCount ?? 0) + 1;
+          runtimeStatus.lastMovedCardId = String(event.cardId ?? "") || null;
+        } else if (event.type === "error") {
+          runtimeStatus.warnings = [String(event.message ?? "Native panel reported an error.")];
+        }
+      } catch (error) {
+        runtimeStatus.warnings = [
+          `Ignored malformed native panel event: ${error instanceof Error ? error.message : String(error)}`,
+        ];
+      }
+    }
+    newline = child._activityBuffer.indexOf("\n");
+  }
+}
+
+function startPanel() {
+  if (shuttingDown) return;
+  const binary = panelBinaryPath();
+  /** @type {PanelChild} */
+  const child = spawn(binary, [], {
+    env: process.env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  panel = child;
+  panelReady = false;
+  panelWriteReady = true;
+  panelStderr = "";
+  runtimeStatus.panelPid = child.pid ?? null;
+  runtimeStatus.state = "starting";
+  child.stdout.setEncoding("utf8");
+  child.stdin.on("error", () => {
+    // Exit supervision below owns recovery from a closed panel pipe.
+  });
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => consumePanelEvents(child, chunk));
+  child.stderr.on("data", (chunk) => {
+    if (panel === child) panelStderr = `${panelStderr}${chunk}`.slice(-4000);
+  });
+  child._readyTimer = setTimeout(() => {
+    if (panel === child && !panelReady) child.kill("SIGKILL");
+  }, 5000);
+  child._readyTimer.unref?.();
+  child.on("error", (error) => {
+    if (panel === child) runtimeStatus.error = error.message;
+  });
+  child.on("exit", (code, signal) => {
+    clearTimeout(child._readyTimer);
+    clearTimeout(child._stableTimer);
+    if (panel !== child) return;
+    panelReady = false;
+    runtimeStatus.windowVisible = false;
+    runtimeStatus.panelPid = null;
+    if (shuttingDown) return;
+    if (panelRestartCount < 3) {
+      panelRestartCount += 1;
+      runtimeStatus.panelRestartCount = panelRestartCount;
+      runtimeStatus.state = "starting";
+      runtimeStatus.error = null;
+      const timer = setTimeout(startPanel, 250 * 2 ** (panelRestartCount - 1));
+      timer.unref?.();
+      return;
+    }
+    runtimeStatus.state = "error";
+    runtimeStatus.error =
+      `Native panel exited (${signal ?? code ?? "unknown"}). ${panelStderr}`.trim();
+  });
+}
+
+const getNiriWindows = () =>
+  readNiriWindows(execFileAsync, process.env, ACTIVITY_STRIP_WORKSPACE_SYNC_MS);
+const getNiriWorkspaces = () =>
+  readNiriWorkspaces(execFileAsync, process.env, ACTIVITY_STRIP_WORKSPACE_SYNC_MS);
+
+const reconcileRunner = createLatestOnlyRunner(async ({ isCurrent }) => {
+  if (!isNiriSession()) {
+    projection.send();
+    return;
+  }
+  const [windows, workspaces] = await Promise.all([getNiriWindows(), getNiriWorkspaces()]);
+  if (!isCurrent()) return;
+  const view = resolveFocusedWorkspaceView(windows, workspaces, projection.getRawSessions(), {
+    env: process.env,
+  });
+  projection.publishWorkspaceView(
+    view ?? { workspace: null, sessions: [], focusedSessionId: null, focusedCardId: null },
+  );
+});
+
+async function shutdown(exitCode = 0) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  watcher?.stop();
+  writePanel({
+    protocol: 1,
+    type: "view",
+    revision: Number.MAX_SAFE_INTEGER,
+    visible: false,
+    sessions: [],
+  });
+  panel?.stdin?.end();
+  await new Promise((resolve) => setTimeout(resolve, 80));
+  panel?.kill("SIGTERM");
+  await broker?.stop();
+  process.exitCode = exitCode;
+}
+
+async function main() {
+  if (process.env.PI_ACTIVITY_STRIP_RUNTIME_LOCK_HELD !== "1") {
+    throw new Error("Native runtime must be launched through the flock-guarded CLI.");
+  }
+  broker = await createActivityStripBroker({
+    focusSession,
+    focusStrip,
+    getRuntimeStatus: () => ({
+      ...runtimeStatus,
+      warnings: [...(runtimeStatus.warnings ?? [])],
+    }),
+  });
+  broker.on("snapshot", (snapshot) => {
+    const membershipChanged = !haveSameRecordMembership(
+      projection.getRawSessions(),
+      snapshot.sessions,
+    );
+    projection.updateSnapshot(snapshot);
+    if (isNiriSession() && membershipChanged) reconcileRunner.request();
+  });
+  broker.on("shutdown-requested", () => void shutdown(0));
+
+  startPanel();
+  if (isNiriSession()) {
+    reconcileRunner.request();
+    watcher = createNiriWorkspaceEventWatcher({
+      spawn,
+      env: process.env,
+      onFocusedWorkspace: () => reconcileRunner.request(),
+      onFallback: () => reconcileRunner.request(),
+      fallbackMs: ACTIVITY_STRIP_WORKSPACE_SYNC_MS,
+    });
+  }
+
+  process.once("SIGINT", () => void shutdown(0));
+  process.once("SIGTERM", () => void shutdown(0));
+}
+
+main().catch(async (error) => {
+  runtimeStatus.state = "error";
+  runtimeStatus.error = error instanceof Error ? error.message : String(error);
+  console.error(error?.stack ?? error);
+  try {
+    await shutdown(1);
+  } catch {
+    process.exitCode = 1;
+  }
+});

package/src/native/panel-projection.mjs

@@ -0,0 +1,99 @@
+// ---
+// summary: "projects broker snapshots into presentation-ready native-panel views"
+// read_when:
+//   - "changing native panel card membership, focus, or transport revisions"
+// ---
+
+import { resolveSnapshotSession } from "../common/niri-focus.mjs";
+import { projectSessionCards, sessionRecordKey } from "../common/session-cards.mjs";
+
+/** @typedef {Record<string, unknown>} SessionRecord */
+/** @typedef {{generatedAt: number; sessions: SessionRecord[]}} Snapshot */
+/** @typedef {{workspace: Record<string, unknown> | null; sessions: SessionRecord[]; focusedSessionId: string | null; focusedCardId?: string | null}} WorkspaceView */
+/** @typedef {{isNiriSession: () => boolean; publish: (view: Record<string, unknown> & {type: string; sessions: SessionRecord[]}) => void}} NativePanelProjectionOptions */
+
+/** @param {NativePanelProjectionOptions} options */
+export function createNativePanelProjection({ isNiriSession, publish }) {
+  /** @type {Snapshot} */
+  let snapshot = { generatedAt: Date.now(), sessions: [] };
+  /** @type {string | null} */
+  let focusedSessionId = null;
+  /** @type {string | null} */
+  let focusedCardId = null;
+  /** @type {Record<string, unknown> | null} */
+  let workspace = null;
+  /** @type {Set<string>} */
+  let workspaceCardIds = new Set();
+  /** @type {Set<string>} */
+  let workspaceRecordKeys = new Set();
+  let revision = 0;
+
+  function getDisplaySessions() {
+    const sessions = isNiriSession()
+      ? snapshot.sessions.filter((session) => workspaceRecordKeys.has(sessionRecordKey(session)))
+      : snapshot.sessions;
+    return projectSessionCards(sessions, isNiriSession() ? workspaceCardIds : null);
+  }
+
+  function currentView() {
+    revision += 1;
+    const sessions = getDisplaySessions();
+    return {
+      protocol: 1,
+      type: "view",
+      revision,
+      visible: isNiriSession() ? Boolean(workspace?.is_focused && sessions.length > 0) : true,
+      focusedSessionId,
+      focusedCardId,
+      generatedAt: snapshot.generatedAt,
+      sessions,
+    };
+  }
+
+  function send() {
+    publish(currentView());
+  }
+
+  function retainValidFocus() {
+    const targetId = focusedCardId ?? focusedSessionId;
+    if (!targetId || !resolveSnapshotSession(getDisplaySessions(), targetId)) {
+      focusedSessionId = null;
+      focusedCardId = null;
+    }
+  }
+
+  return {
+    getDisplaySessions,
+    getRawSessions: () => snapshot.sessions,
+    /** @param {string} targetId */
+    resolveTarget: (targetId) => resolveSnapshotSession(getDisplaySessions(), targetId),
+    /** @param {WorkspaceView} view */
+    publishWorkspaceView(view) {
+      workspace = view.workspace ?? null;
+      workspaceCardIds = new Set(view.sessions.map((session) => String(session.cardId ?? "")));
+      workspaceRecordKeys = new Set(
+        view.sessions.flatMap((session) =>
+          Array.isArray(session.publisherRecordKeys)
+            ? session.publisherRecordKeys.map(String)
+            : [sessionRecordKey(session)],
+        ),
+      );
+      focusedSessionId = view.focusedSessionId;
+      focusedCardId = view.focusedCardId ?? null;
+      send();
+    },
+    send,
+    /** @param {SessionRecord} session */
+    setFocused(session) {
+      focusedSessionId = String(session.sessionId ?? "") || null;
+      focusedCardId = String(session.cardId ?? "") || null;
+      send();
+    },
+    /** @param {Snapshot} nextSnapshot */
+    updateSnapshot(nextSnapshot) {
+      snapshot = nextSnapshot;
+      retainValidFocus();
+      send();
+    },
+  };
+}