npm - @erdemtuna/doc-review - Versions diffs - 0.7.0 → 0.8.0 - Mend

@erdemtuna/doc-review 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/src/chrome.html CHANGED Viewed

@@ -8,6 +8,27 @@
 </head>
 <body data-session="__SESSION_ID__" data-token="__TOKEN__">
   <div class="app">
+    <header class="toolbar" aria-label="Review controls">
+      <div class="toolbar-product" aria-hidden="true"></div>
+      <div class="mode-control">
+        <button type="button" id="modeButton" class="toolbar-btn" aria-haspopup="menu" aria-expanded="false">
+          <span id="modeIcon"></span><span id="modeLabel">View</span><span id="modeChevron"></span>
+        </button>
+        <div id="modeMenu" class="mode-menu" role="menu" hidden>
+          <button type="button" role="menuitemradio" aria-checked="true" data-mode="view">
+            <span data-icon="eye"></span><span><strong>View</strong><small>Editing off, comments enabled</small></span><span class="menu-check"></span>
+          </button>
+          <button type="button" role="menuitemradio" aria-checked="false" data-mode="edit">
+            <span data-icon="pencil"></span><span><strong>Edit</strong><small>Direct editing on</small></span><span class="menu-check"></span>
+          </button>
+        </div>
+      </div>
+      <div class="toolbar-actions">
+        <button type="button" id="commentsButton" class="toolbar-btn" aria-controls="drawer" aria-label="Comments" aria-expanded="false">
+          <span data-icon="messages"></span><span class="toolbar-label">Comments</span><span id="toolbarCount" class="count-badge">0</span>
+        </button>
+      </div>
+    </header>
     <main class="stage">
       <iframe
         id="frame"
@@ -15,34 +36,50 @@
         sandbox="allow-scripts allow-forms allow-modals"></iframe>
     </main>
-    <button type="button" id="handle" class="handle" title="Hide comments panel" aria-label="Hide comments panel">›</button>
-    <aside class="rail" id="rail">
-      <div class="rail-scroll">
-        <div class="rail-head">
-          <span class="section">Feedback</span>
-          <span class="dim" id="count">0</span>
-          <button type="button" id="theme" class="icon-btn" title="Switch chrome to dark" aria-label="Switch chrome to dark">☾</button>
+    <section id="compose" class="contextual-compose" role="dialog" aria-modal="false" aria-labelledby="composeTitle" hidden>
+      <div class="compose-head">
+        <div>
+          <span class="chip" id="composeKind">Selection</span>
+          <strong id="composeTitle">Add comment</strong>
         </div>
+        <button type="button" id="composeClose" class="icon-btn" title="Cancel comment" aria-label="Cancel comment"></button>
+      </div>
+      <div id="composeDirection" class="compose-direction" hidden>
+        <span id="composeDirectionText"></span>
+        <button type="button" id="composeReveal" class="link-action">Back to selection</button>
+      </div>
+      <p class="quote" id="composeQuote"></p>
+      <textarea id="composeText" rows="3" placeholder="What should change?" aria-label="Comment" aria-describedby="composeHelp"></textarea>
+      <p id="composeHelp" class="compose-help"><span>Enter to comment</span><span>Shift+Enter for new line</span></p>
+      <p id="composeError" class="compose-error" role="alert" hidden></p>
+      <div class="compose-actions">
+        <button type="button" id="composeAdd" class="btn-primary"><span data-icon="messageSquarePlus"></span><span id="composeAddLabel">Comment</span></button>
+        <button type="button" id="composeCancel" class="btn-ghost">Cancel</button>
+      </div>
+    </section>
-        <div id="compose" hidden>
-          <div class="compose">
-            <div class="compose-head">
-              <span class="chip" id="composeKind">Selection</span>
-              <span class="dim">Click to write · Esc to dismiss</span>
-            </div>
-            <p class="quote" id="composeQuote"></p>
-            <textarea id="composeText" rows="3" placeholder="What should change?"></textarea>
-            <div class="compose-actions">
-              <button type="button" id="composeAdd" class="btn-primary">Add comment <span class="key">⏎</span></button>
-              <button type="button" id="composeCancel" class="btn-ghost">Cancel</button>
-            </div>
-          </div>
+    <article id="alignedCard" class="aligned-card" hidden></article>
+    <aside class="drawer" id="drawer" aria-label="Review feedback" aria-hidden="true">
+      <div class="drawer-head">
+        <div>
+          <span class="section">Review</span>
+          <h2 id="drawerTitle">Comments</h2>
         </div>
+        <button type="button" id="theme" class="icon-btn" title="Switch chrome to dark" aria-label="Switch chrome to dark"></button>
+        <button type="button" id="drawerClose" class="icon-btn" title="Close review drawer" aria-label="Close review drawer"></button>
+      </div>
+      <div id="commentsSection" class="drawer-inventory" tabindex="-1" aria-labelledby="inventoryHeading">
+        <section>
+          <div class="rail-head">
+            <span class="section" id="inventoryHeading">Comments</span>
+            <span class="dim" id="count">0</span>
+          </div>
-        <div id="cards" class="cards"></div>
+          <div id="cards" class="cards"></div>
-        <div id="empty" class="empty">Select text or click an element to comment on it</div>
+          <div id="empty" class="empty">Select text or focus an element, then use the comment button</div>
+        </section>
         <section id="othersBox" hidden>
           <div class="rail-head tight">
@@ -61,21 +98,30 @@
           <div class="save-line" id="saveLine"><span class="dot"></span><span id="saveText"></span></div>
           <div class="edit-list" id="editList"></div>
         </section>
-      </div>
-      <div class="rail-foot">
-        <textarea id="note" rows="2" placeholder="Overall note…"></textarea>
-        <button type="button" id="send" class="send" disabled>Nothing to send yet</button>
-        <div class="agent-line" id="agentLine" hidden><span class="dot amber"></span><span id="agentText"></span></div>
-        <div class="handoff" id="handoff" hidden>
-          <p class="handoff-title">Sent — but no agent is listening yet.</p>
-          <p class="handoff-body">Paste this into your agent — Claude Code, Codex, or Cursor:</p>
-          <div class="handoff-cmd"><code id="handoffCmd"></code></div>
-          <button type="button" id="handoffCopy" class="btn-ghost">Copy prompt</button>
-        </div>
-        <button type="button" id="endReview" class="end-review" title="Stop this review and release the waiting agent">End review</button>
       </div>
+      <footer id="sendSection" class="drawer-footer send-section" tabindex="-1" aria-label="Send feedback">
+        <div class="send-primary">
+          <div class="rail-head tight">
+            <span class="section">Send feedback</span>
+          </div>
+          <textarea id="note" rows="2" placeholder="Overall note…"></textarea>
+          <button type="button" id="send" class="send" disabled>Nothing to send yet</button>
+          <div class="agent-line" id="agentLine" hidden><span class="dot amber"></span><span id="agentText"></span></div>
+        </div>
+        <div class="send-secondary">
+          <div class="handoff" id="handoff" hidden>
+            <p class="handoff-title">Sent — but no agent is listening yet.</p>
+            <p class="handoff-body">Paste this into your agent — Claude Code, Codex, or Cursor:</p>
+            <div class="handoff-cmd"><code id="handoffCmd"></code></div>
+            <button type="button" id="handoffCopy" class="btn-ghost">Copy prompt</button>
+          </div>
+          <button type="button" id="endReview" class="end-review" title="Stop this review and release the waiting agent">End review</button>
+        </div>
+      </footer>
     </aside>
+    <div id="drawerBackdrop" class="drawer-backdrop" hidden></div>
+    <div id="liveRegion" class="sr-only" role="status" aria-live="polite"></div>
   </div>
   <script type="module" src="/chrome.js"></script>

package/src/cli.js CHANGED Viewed

@@ -4,7 +4,15 @@ import http from "node:http";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { canonicalTarget, ensureStateDir, SERVER_PROTOCOL, serverPath, statePath, targetKey } from "./paths.js";
+import {
+  canonicalTarget,
+  ensureStateDir,
+  SERVER_PROTOCOL,
+  serverPath,
+  serverProtocolMatches,
+  statePath,
+  targetKey,
+} from "./paths.js";
 import { readServerLock } from "./server-lock.js";
 import { installSkills, shellQuote } from "./setup.js";
@@ -69,7 +77,7 @@ async function alive(server) {
     if (res.status !== 200) return false;
     const health = JSON.parse(res.raw);
     return (
-      health.protocol === SERVER_PROTOCOL &&
+      serverProtocolMatches(health.protocol) &&
       health.pid === server.pid &&
       health.instance_id === server.instance_id
     );
@@ -82,7 +90,7 @@ async function ensureServer() {
   ensureStateDir();
   for (let launch = 0; launch < 3; launch += 1) {
     const saved = readServerRecord();
-    if (saved?.protocol === SERVER_PROTOCOL && saved.port && saved.instance_id && (await alive(saved))) return saved;
+    if (serverProtocolMatches(saved?.protocol) && saved.port && saved.instance_id && (await alive(saved))) return saved;
     const child = spawn(process.execPath, [path.join(here, "server-entry.js")], {
       detached: true,
@@ -95,7 +103,7 @@ async function ensureServer() {
       const record = readServerRecord();
       // Same protocol gate as above: a still-running server from an older
       // version answers /health too, and must not be adopted here.
-      if (record?.protocol === SERVER_PROTOCOL && record.port && record.instance_id && (await alive(record))) return record;
+      if (serverProtocolMatches(record?.protocol) && record.port && record.instance_id && (await alive(record))) return record;
       if (child.exitCode !== null && !readServerLock()) break;
     }
   }
@@ -239,7 +247,7 @@ async function pollCommand(input, { ackId = "", timeoutSecs = 0 } = {}) {
 async function statusCommand(input) {
   const target = canonicalTarget(input).value;
   const saved = readServerRecord();
-  if (saved?.protocol === SERVER_PROTOCOL && saved.port && saved.instance_id && (await alive(saved))) {
+  if (serverProtocolMatches(saved?.protocol) && saved.port && saved.instance_id && (await alive(saved))) {
     const res = await request(saved, { method: "GET", path: `/api/status?target=${encodeURIComponent(target)}` });
     if (res.status === 200) {
       process.stdout.write(`${JSON.stringify(JSON.parse(res.raw), null, 2)}\n`);

package/src/comment-anchor.js ADDED Viewed

@@ -0,0 +1,22 @@
+const text = (value, limit) => typeof value === "string" ? value.slice(0, limit) : "";
+export function normalizeCommentAnchor(kind, anchor) {
+  if (!anchor || typeof anchor !== "object" || Array.isArray(anchor)) return null;
+  if (kind === "element") {
+    const selector = text(anchor.selector, 2000);
+    if (!selector) return null;
+    return {
+      selector,
+      ...(text(anchor.label, 500) ? { label: text(anchor.label, 500) } : {}),
+    };
+  }
+  const quote = text(anchor.quote, 4000);
+  if (!quote) return null;
+  return {
+    quote,
+    ...(text(anchor.prefix, 1000) ? { prefix: text(anchor.prefix, 1000) } : {}),
+    ...(text(anchor.suffix, 1000) ? { suffix: text(anchor.suffix, 1000) } : {}),
+    ...(text(anchor.selector, 2000) ? { selector: text(anchor.selector, 2000) } : {}),
+  };
+}

package/src/comment-target.js ADDED Viewed

@@ -0,0 +1,77 @@
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+export function sanitizeRect(rect) {
+  if (!rect) return null;
+  const values = ["left", "top", "right", "bottom", "width", "height"];
+  if (!values.every((key) => finite(rect[key]))) return null;
+  if (rect.width < 0 || rect.height < 0 || rect.right < rect.left || rect.bottom < rect.top) return null;
+  return {
+    left: rect.left,
+    top: rect.top,
+    right: rect.right,
+    bottom: rect.bottom,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+export function sanitizeClientRect(rect, viewport) {
+  const safe = sanitizeRect(rect);
+  if (!safe || !viewport || !finite(viewport.width) || !finite(viewport.height)) return null;
+  const { left: rawLeft, top: rawTop, right: rawRight, bottom: rawBottom } = safe;
+  if (rawRight <= 0 || rawBottom <= 0 || rawLeft >= viewport.width || rawTop >= viewport.height) return null;
+  const left = Math.max(0, Math.min(viewport.width, rawLeft));
+  const top = Math.max(0, Math.min(viewport.height, rawTop));
+  const right = Math.max(left, Math.min(viewport.width, rawRight));
+  const bottom = Math.max(top, Math.min(viewport.height, rawBottom));
+  return { left, top, right, bottom, width: right - left, height: bottom - top };
+}
+export function sanitizeClientRects(rects, viewport, limit = 64) {
+  if (!Array.isArray(rects)) return [];
+  return rects.slice(0, limit).map((rect) => sanitizeClientRect(rect, viewport)).filter(Boolean);
+}
+export function sanitizeClipRect(rect, viewport) {
+  const safe = sanitizeClientRect(rect, viewport);
+  return safe && safe.width > 0 && safe.height > 0 ? safe : null;
+}
+export function sanitizeRelation(value) {
+  return ["visible", "above", "below", "unavailable"].includes(value) ? value : "unavailable";
+}
+export function targetMessage(
+  { kind, quote, anchor, rects, generation, relation, clip, horizontal },
+  viewport
+) {
+  const safeRects = sanitizeClientRects(rects, viewport);
+  const safeClip = sanitizeClipRect(clip, viewport);
+  if (!Number.isSafeInteger(generation) || generation < 1) return null;
+  const safeRelation = sanitizeRelation(relation);
+  if (!safeClip || (safeRelation === "visible" && !safeRects.length)) return null;
+  return {
+    kind: kind === "element" ? "element" : "selection",
+    quote: String(quote || ""),
+    anchor: anchor || null,
+    rects: safeRects,
+    generation,
+    relation: safeRelation,
+    clip: safeClip,
+    horizontal: finite(horizontal) ? Math.max(safeClip.left, Math.min(safeClip.right, horizontal)) : null,
+  };
+}
+export function acceptsTargetGeometry(currentGeneration, incoming) {
+  return !!incoming && Number.isSafeInteger(incoming.generation) && incoming.generation === currentGeneration;
+}
+export function acceptedOpenGeneration(
+  { pendingGeneration = null, retargetGeneration = null },
+  { accepted, requestedGeneration }
+) {
+  if (!accepted) return pendingGeneration;
+  if (requestedGeneration === retargetGeneration) return retargetGeneration;
+  if (requestedGeneration === pendingGeneration) return pendingGeneration;
+  return null;
+}

package/src/icons.js ADDED Viewed

@@ -0,0 +1,251 @@
+// Generated by scripts/generate-icons.js from lucide-static. Do not edit.
+export const ICON_NODES = Object.freeze({
+  "eye": [
+    [
+      "path",
+      {
+        "d": "M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"
+      }
+    ],
+    [
+      "circle",
+      {
+        "cx": "12",
+        "cy": "12",
+        "r": "3"
+      }
+    ]
+  ],
+  "pencil": [
+    [
+      "path",
+      {
+        "d": "M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m15 5 4 4"
+      }
+    ]
+  ],
+  "chevronDown": [
+    [
+      "path",
+      {
+        "d": "m6 9 6 6 6-6"
+      }
+    ]
+  ],
+  "messageSquarePlus": [
+    [
+      "path",
+      {
+        "d": "M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M12 8v6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M9 11h6"
+      }
+    ]
+  ],
+  "messages": [
+    [
+      "path",
+      {
+        "d": "M16 10a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 14.286V4a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M20 9a2 2 0 0 1 2 2v10.286a.71.71 0 0 1-1.212.502l-2.202-2.202A2 2 0 0 0 17.172 19H10a2 2 0 0 1-2-2v-1"
+      }
+    ]
+  ],
+  "send": [
+    [
+      "path",
+      {
+        "d": "M14.536 21.686a.5.5 0 0 0 .937-.024l6.5-19a.496.496 0 0 0-.635-.635l-19 6.5a.5.5 0 0 0-.024.937l7.93 3.18a2 2 0 0 1 1.112 1.11z"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m21.854 2.147-10.94 10.939"
+      }
+    ]
+  ],
+  "trash": [
+    [
+      "path",
+      {
+        "d": "M10 11v6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M14 11v6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M3 6h18"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"
+      }
+    ]
+  ],
+  "moreHorizontal": [
+    [
+      "circle",
+      {
+        "cx": "12",
+        "cy": "12",
+        "r": "1"
+      }
+    ],
+    [
+      "circle",
+      {
+        "cx": "19",
+        "cy": "12",
+        "r": "1"
+      }
+    ],
+    [
+      "circle",
+      {
+        "cx": "5",
+        "cy": "12",
+        "r": "1"
+      }
+    ]
+  ],
+  "x": [
+    [
+      "path",
+      {
+        "d": "M18 6 6 18"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m6 6 12 12"
+      }
+    ]
+  ],
+  "check": [
+    [
+      "path",
+      {
+        "d": "M20 6 9 17l-5-5"
+      }
+    ]
+  ],
+  "sun": [
+    [
+      "circle",
+      {
+        "cx": "12",
+        "cy": "12",
+        "r": "4"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M12 2v2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M12 20v2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m4.93 4.93 1.41 1.41"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m17.66 17.66 1.41 1.41"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M2 12h2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M20 12h2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m6.34 17.66-1.41 1.41"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m19.07 4.93-1.41 1.41"
+      }
+    ]
+  ],
+  "moon": [
+    [
+      "path",
+      {
+        "d": "M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401"
+      }
+    ]
+  ]
+});
+const escape = (value) => String(value).replace(/[&<>"]/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[char]);
+export function iconMarkup(name, { title = "", className = "icon", size = 16 } = {}) {
+  const nodes = ICON_NODES[name];
+  if (!nodes) throw new Error(`Unknown icon: ${name}`);
+  const body = nodes.map(([tag, attrs]) => `<${tag} ${Object.entries(attrs).map(([key, value]) => `${key}="${escape(value)}"`).join(" ")}></${tag}>`).join("");
+  const label = title ? ` role="img" aria-label="${escape(title)}"` : ' aria-hidden="true"';
+  return `<svg class="${escape(className)}" width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${label}>${body}</svg>`;
+}
+export function createIcon(name, options = {}) {
+  const template = document.createElement("template");
+  template.innerHTML = iconMarkup(name, options);
+  return template.content.firstElementChild;
+}

package/src/paths.js CHANGED Viewed

@@ -5,7 +5,11 @@ import fs from "node:fs";
 // Bump this when the CLI and detached server no longer share the same request
 // contract. A new CLI must not silently reuse an older background server.
-export const SERVER_PROTOCOL = 11;
+export const SERVER_PROTOCOL = 12;
+export function serverProtocolMatches(protocol) {
+  return Number(protocol) === SERVER_PROTOCOL;
+}
 export function stateDir() {
   const override = process.env.DOC_REVIEW_STATE_DIR;

package/src/positioning.js ADDED Viewed

@@ -0,0 +1,107 @@
+const GAP = 12;
+export function visibleViewport(win = window) {
+  const viewport = win.visualViewport;
+  return viewport
+    ? { left: viewport.offsetLeft, top: viewport.offsetTop, width: viewport.width, height: viewport.height }
+    : { left: 0, top: 0, width: win.innerWidth, height: win.innerHeight };
+}
+export function lastVisibleRect(rects) {
+  if (!Array.isArray(rects)) return null;
+  for (let index = rects.length - 1; index >= 0; index -= 1) {
+    const rect = rects[index];
+    if (rect && rect.width >= 0 && rect.height >= 0) return rect;
+  }
+  return null;
+}
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+function frameRectToChrome(rect, frameRect) {
+  return {
+    left: frameRect.left + rect.left,
+    right: frameRect.left + rect.right,
+    top: frameRect.top + rect.top,
+    bottom: frameRect.top + rect.bottom,
+  };
+}
+export function placeContextualSurface(geometry, options) {
+  const {
+    frameRect,
+    viewport,
+    surfaceWidth = 340,
+    surfaceHeight = 220,
+    narrow = false,
+    toolbarHeight = 48,
+  } = options;
+  const bottomSheet = () => ({
+    kind: "sheet",
+    left: viewport.left,
+    top: viewport.top + viewport.height - Math.min(surfaceHeight, viewport.height),
+    width: viewport.width,
+  });
+  if (!geometry || geometry.relation === "unavailable" || !geometry.clip) return { kind: "hidden" };
+  if (narrow) return bottomSheet();
+  const clip = frameRectToChrome(geometry.clip, frameRect);
+  const minLeft = viewport.left + GAP;
+  const maxLeft = viewport.left + viewport.width - surfaceWidth - GAP;
+  const viewportMinTop = viewport.top + toolbarHeight + GAP;
+  const minTop = Math.max(viewportMinTop, clip.top + GAP);
+  const maxTop = viewport.top + viewport.height - surfaceHeight - GAP;
+  const clipBottomTop = clip.bottom - surfaceHeight - GAP;
+  const horizontal = Number.isFinite(geometry.horizontal)
+    ? frameRect.left + geometry.horizontal
+    : clip.left;
+  const edgeLeft = clamp(horizontal + GAP, minLeft, maxLeft);
+  if (geometry.relation === "above") {
+    return { kind: "edge-top", left: edgeLeft, top: minTop, width: surfaceWidth };
+  }
+  if (geometry.relation === "below") {
+    return {
+      kind: "edge-bottom",
+      left: edgeLeft,
+      top: Math.max(viewportMinTop, Math.min(maxTop, clipBottomTop)),
+      width: surfaceWidth,
+    };
+  }
+  const target = lastVisibleRect(geometry.rects);
+  if (!target) return { kind: "hidden" };
+  const rect = frameRectToChrome(target, frameRect);
+  const attachedMaxTop = Math.min(maxTop, clipBottomTop);
+  const clampTop = (top) => clamp(top, minTop, Math.max(minTop, attachedMaxTop));
+  const candidates = [
+    { left: rect.right + GAP, top: clampTop(rect.bottom - surfaceHeight) },
+    { left: rect.left - surfaceWidth - GAP, top: clampTop(rect.bottom - surfaceHeight) },
+    { left: clamp(rect.left, minLeft, maxLeft), top: rect.bottom + GAP },
+    { left: clamp(rect.left, minLeft, maxLeft), top: rect.top - surfaceHeight - GAP },
+  ];
+  const fit = candidates.find((candidate) =>
+    candidate.left >= minLeft &&
+    candidate.left <= maxLeft &&
+    candidate.top >= minTop &&
+    candidate.top <= attachedMaxTop &&
+    candidate.left + surfaceWidth <= Math.min(viewport.left + viewport.width - GAP, clip.right) &&
+    candidate.top + surfaceHeight <= clip.bottom
+  );
+  const fallback = fit || {
+    left: clamp(rect.right + GAP, minLeft, maxLeft),
+    top: clampTop(rect.top),
+  };
+  return { kind: "attached", ...fallback, width: surfaceWidth };
+}
+export function alignedCardPosition(rects, { frameRect, viewport, width = 300, height = 180 }) {
+  const target = lastVisibleRect(rects);
+  if (!target) return null;
+  const top = frameRect.top + target.top;
+  const right = frameRect.left + target.right;
+  if (top < frameRect.top || top > frameRect.bottom || right < frameRect.left || right > frameRect.right) return null;
+  return {
+    left: Math.max(viewport.left + 12, Math.min(viewport.left + viewport.width - width - 12, right + 12)),
+    top: Math.max(viewport.top + 12, Math.min(viewport.top + viewport.height - height - 12, top)),
+  };
+}