relay-companion 0.1.76 → 0.1.77

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,34 @@
+# Third-party notices
+
+The Relay preview preload embeds the following open-source software in
+`overlay/preview-preload.cjs`.
+
+## markdown-it 14.3.0
+
+Copyright (c) 2014 Vitaly Puzrin, Alex Kocharin.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## DOMPurify 3.4.13
+
+Copyright (c) Cure53 and other contributors.
+
+DOMPurify is distributed under the Apache License 2.0 or the Mozilla Public
+License 2.0. Relay distributes its embedded copy under the Apache License 2.0.
+The complete terms are included in [`licenses/Apache-2.0.txt`](licenses/Apache-2.0.txt).

package/licenses/Apache-2.0.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/overlay/inbox.html

@@ -903,6 +903,9 @@
   }
   function playTink() {
     if (REDUCED) return;
+    // A test overlay must never make noise on the developer's machine — the
+    // sound is indistinguishable from the real pill's and lands mid-work.
+    if (window.relay && window.relay.isTestOverlay) return;
     if (!actx) initAudio();
     if (!actx) return;
     if (actx.state === "suspended") actx.resume();
@@ -1602,15 +1605,20 @@
     }
   }
 
-  // The two open actions, as one small text-first menu: primary hands the
-  // relay to the live session, secondary starts a fresh one. Labels carry all
-  // the meaning; data attributes stay stable for wiring and tests.
-  function openActionsHtml(id, { thread } = {}) {
+  // Preview plus the two host-open actions, as one small text-first menu.
+  // Preview is the primary, non-navigation path; the other actions hand the
+  // relay to a current or fresh host session.
+  function openActionsHtml(id, { thread, previewable = true } = {}) {
+    const preview = thread ? `data-thread-preview="${esc(id)}"` : `data-preview="${esc(id)}"`;
     const cur = thread ? `data-thread-open-current="${esc(id)}"` : `data-open-current="${esc(id)}"`;
     const fresh = thread ? `data-thread-open-fresh="${esc(id)}"` : `data-open-fresh="${esc(id)}"`;
+    const previewItem = previewable
+      ? `<button class="oa-item oa-primary" type="button" role="menuitem" ${preview}>${thread ? "Preview Latest Received Relay" : "Preview"}</button><div class="oa-sep" role="separator"></div>`
+      : "";
     return `
       <div class="open-actions row-open-card" data-stop="1" role="menu">
-        <button class="oa-item oa-primary" type="button" role="menuitem" ${cur}>${thread ? "Open Thread in Current Chat" : "Open in Current Chat"}</button>
+        ${previewItem}
+        <button class="oa-item${previewable ? "" : " oa-primary"}" type="button" role="menuitem" ${cur}>${thread ? "Open Thread in Current Chat" : "Open in Current Chat"}</button>
         <div class="oa-sep" role="separator"></div>
         <button class="oa-item" type="button" role="menuitem" ${fresh}>${thread ? "Open Thread in New Chat" : "Open in New Chat"}</button>
       </div>`;
@@ -1808,8 +1816,18 @@
         openRelayFromUI(id);
       });
     }
-    // Expand-card actions. Both mark the relay read exactly like a normal open
-    // (main acks on completion) and ride the existing opening spinner.
+    // Preview opens an independent, focusable render window. Main marks the
+    // relay read only after that renderer confirms a successful body paint.
+    for (const btn of relaysListEl.querySelectorAll("[data-preview]")) {
+      const id = btn.getAttribute("data-preview");
+      btn.addEventListener("click", () => {
+        expandedRelayId = null;
+        window.relay.preview(id);
+        renderRelays();
+      });
+    }
+    // Host-open actions mark the relay read exactly like a normal open (main
+    // acks on completion) and ride the existing opening spinner.
     for (const btn of relaysListEl.querySelectorAll("[data-open-current]")) {
       const id = btn.getAttribute("data-open-current");
       btn.addEventListener("click", () => {
@@ -2643,8 +2661,11 @@
     // Thread-level opens act on the newest inbound message (falling back to the
     // newest message overall): "current" injects with the threadId so the agent
     // fetches the whole exchange; "new chat" seeds the full transcript.
-    const newestInbound = [...thread.msgs].reverse().find((m) => m.direction === "in") || thread.msgs[thread.msgs.length - 1];
-    const threadActions = newestInbound ? openActionsHtml(newestInbound.id, { thread: true }) : "";
+    const newestInbound = [...thread.msgs].reverse().find((m) => m.direction === "in") || null;
+    const threadOpenTarget = newestInbound || thread.msgs[thread.msgs.length - 1];
+    const threadActions = threadOpenTarget
+      ? openActionsHtml(threadOpenTarget.id, { thread: true, previewable: Boolean(newestInbound) })
+      : "";
     thHistoryEl.innerHTML = threadActions + thread.msgs.map((m) => `
       <button class="th-msg${m.unread ? " unread" : ""}" type="button" data-msg="${esc(m.id)}" data-dir="${m.direction}">
         <span class="th-msg-top">
@@ -2664,6 +2685,8 @@
     if (curBtn) curBtn.addEventListener("click", () => openRelayFromUI(curBtn.getAttribute("data-thread-open-current"), "relay", "current"));
     const freshBtn = thHistoryEl.querySelector("[data-thread-open-fresh]");
     if (freshBtn) freshBtn.addEventListener("click", () => openRelayFromUI(freshBtn.getAttribute("data-thread-open-fresh"), "relay", "fresh"));
+    const previewBtn = thHistoryEl.querySelector("[data-thread-preview]");
+    if (previewBtn) previewBtn.addEventListener("click", () => window.relay.preview(previewBtn.getAttribute("data-thread-preview")));
   }
   thBackEl.addEventListener("click", () => {
     threadDetailId = null;

package/overlay/main.cjs

@@ -91,10 +91,17 @@ const RELAY_CLI = path.resolve(__dirname, "..", "bin", "relay.js");
 
 // Fixed transparent canvas, large enough to contain the inbox sheet + spring/shadow room.
 const WIN = { width: 520, height: 840 };
+const PREVIEW_WIN = { width: 720, height: 760, minWidth: 480, minHeight: 480 };
 const MARGIN = 8;
 const DEFAULT_WEB_BASE = "https://sendrelays.com";
 
 let win = null;
+let previewWin = null;
+let previewPayload = null;
+let previewRendererReady = false;
+let previewRenderedRelayId = null;
+let previewPayloadVersion = 0;
+let previewSentVersion = -1;
 let tray = null;
 let trayAvailable = false;
 let hostRunning = false; // Claude or Codex desktop app is running (either)
@@ -1270,6 +1277,24 @@ function rowById(packetId) {
   return row ? { id: packetId, ...row } : null;
 }
 
+// Preview is deliberately an allowlisted, human-facing projection of a staged
+// relay. Never pass the recipient-session briefing, local content paths, signed
+// attachment URLs, or arbitrary packet fields into the renderer.
+function previewPayloadForPacket(packetId) {
+  const id = String(packetId || "");
+  if (!id) return null;
+  const row = rowById(id);
+  if (!row || row.direction !== "inbound" || RELAY_HIDDEN_KINDS.has(row.relayNotificationKind)) return null;
+  return {
+    relayId: id,
+    title: String(row.title || row.displayTitle || "Relay"),
+    bodyMarkdown: String(row.bodyMarkdown || ""),
+    senderName: String(row.senderName || "Relay"),
+    createdAt: String(row.createdAt || ""),
+    unread: row.state !== "read",
+  };
+}
+
 // Find an approvalId for a share_approval row. The staged row may not carry it,
 // in which case the renderer routes to the web detail page (Review) instead.
 function approvalIdForRow(row) {
@@ -2360,8 +2385,14 @@ function startHitTest() {
 }
 
 function createWindow() {
+  // Harness overlays share the user's screen with the real pill and are visually
+  // identical — four "Relays" on screen at once reads as the product spazzing
+  // out. Make sandbox runs unmistakable and unobtrusive: half-transparent and
+  // never above the user's real windows. Production is untouched.
+  const isHarness = process.env.RELAY_OVERLAY_TEST === "1" || process.env.RELAY_OVERLAY_PERF === "1";
   win = new BrowserWindow({
     ...anchorTopRight(),
+    ...(isHarness ? { opacity: 0.55 } : {}),
     frame: false,
     transparent: true,
     backgroundColor: "#00000000",
@@ -2395,7 +2426,8 @@ function createWindow() {
   // Windows strips WS_EX_TOPMOST from a scheduled-task-launched overlay that only asks
   // politely ("floating"); "screen-saver" is the level that survives. The periodic
   // re-assert that recovers from later demotions lives in space-presence.cjs.
-  win.setAlwaysOnTop(true, process.platform === "win32" ? "screen-saver" : "floating");
+  // Harness windows stay behind the user's work; only the real pill floats.
+  if (!isHarness) win.setAlwaysOnTop(true, process.platform === "win32" ? "screen-saver" : "floating");
   win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
   // Empty canvas is click-through; startHitTest() below owns this from here on.
   win.setIgnoreMouseEvents(true, { forward: true });
@@ -2513,6 +2545,163 @@ function createWindow() {
   setTimeout(hostLoop, hostPollDelayMs({ testMode, engaged: true }));
 }
 
+function previewWindowExists() {
+  return Boolean(previewWin && !previewWin.isDestroyed());
+}
+
+function showPreviewWindow() {
+  if (!previewWindowExists()) return;
+  try {
+    if (previewWin.isMinimized()) previewWin.restore();
+    previewWin.show();
+    previewWin.focus();
+  } catch (error) {
+    console.error("[preview] show failed:", error && error.message);
+  }
+}
+
+function sendPreviewPayload() {
+  if (!previewWindowExists() || !previewRendererReady || !previewPayload) return false;
+  if (previewSentVersion === previewPayloadVersion) return true;
+  previewWin.webContents.send("relay:preview:content", previewPayload);
+  previewSentVersion = previewPayloadVersion;
+  return true;
+}
+
+function previewWindowPosition() {
+  try {
+    let point = screen.getCursorScreenPoint();
+    if (win && !win.isDestroyed()) {
+      const bounds = win.getBounds();
+      point = {
+        x: Math.round(bounds.x + bounds.width / 2),
+        y: Math.round(bounds.y + bounds.height / 2),
+      };
+    }
+    const workArea = screen.getDisplayNearestPoint(point).workArea;
+    return {
+      x: Math.round(workArea.x + Math.max(0, (workArea.width - PREVIEW_WIN.width) / 2)),
+      y: Math.round(workArea.y + Math.max(0, (workArea.height - PREVIEW_WIN.height) / 2)),
+    };
+  } catch {
+    return {};
+  }
+}
+
+function createPreviewWindow() {
+  previewRendererReady = false;
+  previewRenderedRelayId = null;
+  previewSentVersion = -1;
+  previewWin = new BrowserWindow({
+    width: PREVIEW_WIN.width,
+    height: PREVIEW_WIN.height,
+    minWidth: PREVIEW_WIN.minWidth,
+    minHeight: PREVIEW_WIN.minHeight,
+    ...previewWindowPosition(),
+    show: false,
+    frame: false,
+    transparent: false,
+    backgroundColor: "#f5f1e9",
+    resizable: true,
+    movable: true,
+    minimizable: true,
+    maximizable: true,
+    fullscreenable: false,
+    skipTaskbar: false,
+    hasShadow: true,
+    acceptFirstMouse: true,
+    autoHideMenuBar: true,
+    title: "Relay Preview",
+    webPreferences: {
+      preload: path.join(__dirname, "preview-preload.cjs"),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+    },
+  });
+
+  previewWin.setMenuBarVisibility(false);
+  previewWin.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
+  previewWin.webContents.on("will-navigate", (event, url) => {
+    const previewUrl = pathToFileURL(path.join(__dirname, "preview.html")).href;
+    if (url !== previewUrl && event && typeof event.preventDefault === "function") event.preventDefault();
+  });
+  previewWin.webContents.on("console-message", (...args) => {
+    const message = args[1] && typeof args[1] === "object" ? args[1].message : args[2];
+    if (message) console.error("[preview-renderer]", message);
+  });
+  previewWin.webContents.on("preload-error", (_event, preloadPath, error) => {
+    console.error("[preview-preload-error]", preloadPath, error && error.message);
+  });
+  let renderGoneAt = 0;
+  previewWin.webContents.on("render-process-gone", (_event, details) => {
+    console.error("[preview-render-gone]", JSON.stringify(details));
+    previewRendererReady = false;
+    previewSentVersion = -1;
+    const crashedWindow = previewWin;
+    const delay = Date.now() - renderGoneAt < 30000 ? 5000 : 250;
+    renderGoneAt = Date.now();
+    setTimeout(() => {
+      if (!crashedWindow || crashedWindow !== previewWin || crashedWindow.isDestroyed()) return;
+      crashedWindow.webContents.reload();
+    }, delay);
+  });
+  previewWin.webContents.on("did-finish-load", () => resetWindowZoom(previewWin));
+  previewWin.webContents.on("zoom-changed", (event) => {
+    if (event && typeof event.preventDefault === "function") event.preventDefault();
+    resetWindowZoom(previewWin);
+  });
+  previewWin.webContents.on("before-input-event", (event, input = {}) => {
+    const key = String(input.key || "").toLowerCase();
+    if ((input.meta || input.control) && (key === "+" || key === "=" || key === "-" || key === "_" || key === "0")) {
+      if (event && typeof event.preventDefault === "function") event.preventDefault();
+      resetWindowZoom(previewWin);
+    }
+  });
+  previewWin.once("ready-to-show", () => {
+    sendPreviewPayload();
+    showPreviewWindow();
+  });
+  previewWin.on("closed", () => {
+    previewWin = null;
+    previewPayload = null;
+    previewRendererReady = false;
+    previewRenderedRelayId = null;
+    previewSentVersion = -1;
+  });
+  previewWin.loadFile(path.join(__dirname, "preview.html"));
+}
+
+function openPreview(packetId) {
+  const nextPayload = previewPayloadForPacket(packetId);
+  if (!nextPayload) return false;
+  previewPayload = nextPayload;
+  previewRenderedRelayId = null;
+  previewPayloadVersion += 1;
+  if (!previewWindowExists()) {
+    createPreviewWindow();
+  } else {
+    sendPreviewPayload();
+    showPreviewWindow();
+  }
+  return true;
+}
+
+function openPreviewExternal(url) {
+  try {
+    const parsed = new URL(String(url || ""));
+    if (!new Set(["http:", "https:", "mailto:"]).has(parsed.protocol)) return false;
+    shell.openExternal(parsed.href).catch((error) => console.error("[preview] external link failed:", error && error.message));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isPreviewEvent(event) {
+  return Boolean(previewWindowExists() && event && event.sender === previewWin.webContents);
+}
+
 function installActiveSpaceWatcher() {
   if (process.platform !== "darwin") return;
   subscribeActiveSpaceChanges(
@@ -2697,9 +2886,16 @@ function createTray() {
   tray.on("click", toggleFromTray);
   tray.on("right-click", () => {
     try {
+      const previewItem = previewWindowExists()
+        ? [{
+            label: previewWin.isMinimized() ? "Restore Relay Preview" : "Focus Relay Preview",
+            click: showPreviewWindow,
+          }]
+        : [];
       tray.popUpContextMenu(
         Menu.buildFromTemplate([
           { label: pillIsOnScreen() ? "Hide Relay" : "Show Relay", click: toggleFromTray },
+          ...previewItem,
           { type: "separator" },
           { label: "Quit Relay", click: quitRelayCompletely },
         ]),
@@ -2727,6 +2923,36 @@ ipcMain.on("relay:openFresh", (_e, id) => {
 ipcMain.on("relay:openInCurrent", (_e, id) => {
   openPacketInCurrent(id).catch((error) => console.error("[overlay] open-in-current failed:", error && error.message));
 });
+ipcMain.on("relay:preview", (event, id) => {
+  if (win && !win.isDestroyed() && event && event.sender !== win.webContents) return;
+  if (!openPreview(id)) console.error("[preview] relay not found:", id);
+});
+ipcMain.on("relay:preview:ready", (event) => {
+  if (!isPreviewEvent(event)) return;
+  if (!previewRendererReady) previewSentVersion = -1;
+  previewRendererReady = true;
+  sendPreviewPayload();
+  showPreviewWindow();
+});
+ipcMain.on("relay:preview:rendered", (event, relayId) => {
+  if (!isPreviewEvent(event) || !previewPayload) return;
+  const id = String(relayId || "");
+  if (!id || id !== previewPayload.relayId || id === previewRenderedRelayId) return;
+  previewRenderedRelayId = id;
+  if (previewPayload.unread) {
+    previewPayload.unread = false;
+    ackPacket(id);
+  }
+});
+ipcMain.on("relay:preview:minimize", (event) => {
+  if (isPreviewEvent(event)) previewWin.minimize();
+});
+ipcMain.on("relay:preview:close", (event) => {
+  if (isPreviewEvent(event)) previewWin.close();
+});
+ipcMain.on("relay:preview:openExternal", (event, url) => {
+  if (isPreviewEvent(event)) openPreviewExternal(url);
+});
 ipcMain.on("relay:openTask", (_e, taskId) => openTaskDetail(taskId));
 ipcMain.on("relay:openUrl", (_e, url) => openUrlTarget(url));
 ipcMain.on("relay:ack", (_e, id) => ackPacket(id));
@@ -2960,6 +3186,21 @@ if (!gotSingleInstanceLock) {
           return pushInbox(true);
         },
         getWin: () => win,
+        getPreviewWin: () => previewWin,
+        openPreview,
+        movePillAwayFromCursor: () => {
+          if (!win || win.isDestroyed()) return null;
+          const point = screen.getCursorScreenPoint();
+          const workArea = screen.getDisplayNearestPoint(point).workArea;
+          const x = point.x < workArea.x + workArea.width / 2
+            ? workArea.x + Math.max(0, workArea.width - WIN.width)
+            : workArea.x;
+          const y = point.y < workArea.y + workArea.height / 2
+            ? workArea.y + Math.max(0, workArea.height - WIN.height)
+            : workArea.y;
+          win.setPosition(Math.round(x), Math.round(y));
+          return { point, bounds: win.getBounds() };
+        },
         confirmCurrentShow: () => {
           // Harness shortcut: acknowledge the on-stage card exactly as the
           // renderer would after an interacted dwell.
@@ -2985,6 +3226,13 @@ if (!gotSingleInstanceLock) {
           burstShown,
           rendererListening,
           visible: win && !win.isDestroyed() ? win.isVisible() : null,
+          preview: previewWindowExists()
+            ? {
+                relayId: previewPayload && previewPayload.relayId,
+                visible: previewWin.isVisible(),
+                minimized: previewWin.isMinimized(),
+              }
+            : null,
         }),
       };
     }

package/overlay/preload.cjs

@@ -1,6 +1,9 @@
 const { contextBridge, ipcRenderer } = require("electron");
 
 contextBridge.exposeInMainWorld("relay", {
+  // Sandboxed harness overlays share the user's screen and speakers. The
+  // renderer needs to know it is one so it can stay silent.
+  isTestOverlay: process.env.RELAY_OVERLAY_TEST === "1" || process.env.RELAY_OVERLAY_PERF === "1",
   // streams from main -> renderer
   onInbox: (cb) => ipcRenderer.on("inbox", (_e, payload) => cb(payload)),
   onNewRelay: (cb) => ipcRenderer.on("newRelay", (_e, relay, opts) => cb(relay, opts || {})),
@@ -21,6 +24,7 @@ contextBridge.exposeInMainWorld("relay", {
   open: (id) => ipcRenderer.send("relay:open", id),
   openSent: (id) => ipcRenderer.send("relay:openSent", id),
   // expand-card actions: inject into the live Claude session / force a fresh one
+  preview: (id) => ipcRenderer.send("relay:preview", id),
   openInCurrent: (id) => ipcRenderer.send("relay:openInCurrent", id),
   openFresh: (id) => ipcRenderer.send("relay:openFresh", id),
   ack: (id) => ipcRenderer.send("relay:ack", id),