@jay-framework/aiditor 0.17.1 → 0.17.2

package/dist/index.client.js

@@ -1,5 +1,5 @@
 import { makeJayStackComponent } from "@jay-framework/fullstack-component";
-import { createSignal, createMemo } from "@jay-framework/component";
+import { createSignal, createMemo, createEffect } from "@jay-framework/component";
 import { createStreamCaller, createActionCaller, setActionCallerOptions } from "@jay-framework/stack-client-runtime";
 const submitTaskAction = createStreamCaller("aiditor.submitTask", { acceptsFiles: true });
 const visualModeToForm = {
@@ -7919,6 +7919,93 @@ var parseBackgroundColor = function(context, element, backgroundColorOverride) {
   var defaultBackgroundColor = typeof backgroundColorOverride === "string" ? parseColor(context, backgroundColorOverride) : backgroundColorOverride === null ? COLORS.TRANSPARENT : 4294967295;
   return element === ownerDocument.documentElement ? isTransparent(documentBackgroundColor) ? isTransparent(bodyBackgroundColor) ? defaultBackgroundColor : bodyBackgroundColor : documentBackgroundColor : defaultBackgroundColor;
 };
+const TRANSIENT_PSEUDOCLASSES = [
+  ":hover",
+  ":focus",
+  ":focus-within",
+  ":focus-visible"
+];
+const FREEZE_PROPS = [
+  "background",
+  "background-color",
+  "background-image",
+  "color",
+  "opacity",
+  "transform",
+  "box-shadow",
+  "border",
+  "border-color",
+  "border-width",
+  "border-style",
+  "border-radius",
+  "outline",
+  "outline-color",
+  "outline-width",
+  "outline-offset",
+  "text-decoration",
+  "text-decoration-color",
+  "text-shadow",
+  "filter",
+  "visibility",
+  "display",
+  "scale",
+  "cursor",
+  "width",
+  "height",
+  "max-width",
+  "max-height",
+  "min-width",
+  "min-height",
+  "padding",
+  "margin",
+  "top",
+  "left",
+  "right",
+  "bottom",
+  "z-index",
+  "overflow",
+  "clip-path",
+  "backdrop-filter"
+];
+function freezeTransientStyles(iframeEl) {
+  const doc = iframeEl.contentDocument;
+  const win = iframeEl.contentWindow;
+  if (!doc || !win) return () => {
+  };
+  const seen = /* @__PURE__ */ new Set();
+  for (const pseudo of TRANSIENT_PSEUDOCLASSES) {
+    try {
+      for (const el of doc.querySelectorAll(pseudo)) seen.add(el);
+    } catch {
+    }
+  }
+  if (seen.size === 0) return () => {
+  };
+  const saved = [];
+  for (const el of seen) {
+    if (!("setAttribute" in el) || !("getAttribute" in el)) continue;
+    let computed;
+    try {
+      computed = win.getComputedStyle(el);
+    } catch {
+      continue;
+    }
+    const prev = el.getAttribute("style");
+    let inline = prev ?? "";
+    for (const p of FREEZE_PROPS) {
+      const v = computed.getPropertyValue(p);
+      if (v) inline += `; ${p}: ${v} !important`;
+    }
+    saved.push({ el, prev });
+    el.setAttribute("style", inline);
+  }
+  return () => {
+    for (const { el, prev } of saved) {
+      if (prev !== null) el.setAttribute("style", prev);
+      else el.removeAttribute("style");
+    }
+  };
+}
 function getIframeViewportScrollForHtml2Canvas(win, doc) {
   let sx = win.pageXOffset;
   let sy = win.pageYOffset;
@@ -8283,6 +8370,123 @@ async function capturePreviewForVideoFrame(rootEl, videoEl, mode = "full") {
   if (mode === "full" && popoversEl) await drawLayer(popoversEl);
   return canvasToPng(canvas);
 }
+async function compositeMarkersOntoScreenshot(cleanBlob, annotations) {
+  const img = await blobToImage(cleanBlob);
+  const canvas = document.createElement("canvas");
+  canvas.width = img.naturalWidth;
+  canvas.height = img.naturalHeight;
+  const ctx = canvas.getContext("2d");
+  ctx.drawImage(img, 0, 0);
+  const w = canvas.width;
+  const h = canvas.height;
+  const markerColor = "#c586ff";
+  const markerBorder = "#ffffff";
+  const fontSize2 = Math.max(12, Math.round(Math.min(w, h) * 0.018));
+  for (const a2 of annotations) {
+    const g = a2.geometry;
+    if (g.kind === "point") {
+      const px = g.x * w;
+      const py = g.y * h;
+      const r = Math.max(7, Math.round(Math.min(w, h) * 8e-3));
+      ctx.beginPath();
+      ctx.arc(px, py, r, 0, Math.PI * 2);
+      ctx.fillStyle = markerColor;
+      ctx.fill();
+      ctx.lineWidth = 2;
+      ctx.strokeStyle = markerBorder;
+      ctx.stroke();
+      drawMarkerLabel(ctx, a2.id, px + r + 2, py - r, fontSize2, markerColor);
+    } else if (g.kind === "area") {
+      const ax = g.x * w;
+      const ay = g.y * h;
+      const aw = g.w * w;
+      const ah = g.h * h;
+      ctx.strokeStyle = markerColor;
+      ctx.lineWidth = 2;
+      ctx.setLineDash([6, 4]);
+      ctx.strokeRect(ax, ay, aw, ah);
+      ctx.setLineDash([]);
+      ctx.fillStyle = "rgba(197, 134, 255, 0.12)";
+      ctx.fillRect(ax, ay, aw, ah);
+      drawMarkerLabel(ctx, a2.id, ax + 4, ay + 4, fontSize2, markerColor);
+    } else if (g.kind === "arrow") {
+      const x1 = g.x1 * w;
+      const y1 = g.y1 * h;
+      const x2 = g.x2 * w;
+      const y2 = g.y2 * h;
+      ctx.strokeStyle = markerColor;
+      ctx.lineWidth = 2;
+      ctx.setLineDash([]);
+      ctx.beginPath();
+      ctx.moveTo(x1, y1);
+      ctx.lineTo(x2, y2);
+      ctx.stroke();
+      drawArrowhead(ctx, x1, y1, x2, y2, 10, markerColor);
+      const pinR = Math.max(11, Math.round(Math.min(w, h) * 0.014));
+      ctx.beginPath();
+      ctx.arc(x2, y2, pinR, 0, Math.PI * 2);
+      ctx.fillStyle = markerColor;
+      ctx.fill();
+      ctx.lineWidth = 2;
+      ctx.strokeStyle = markerBorder;
+      ctx.stroke();
+      ctx.fillStyle = "#1e1e1e";
+      ctx.font = `bold ${Math.round(fontSize2 * 0.9)}px sans-serif`;
+      ctx.textAlign = "center";
+      ctx.textBaseline = "middle";
+      ctx.fillText(a2.id, x2, y2);
+    }
+  }
+  return canvasToPng(canvas);
+}
+function drawMarkerLabel(ctx, label, x, y, fontSize2, bgColor) {
+  ctx.font = `bold ${fontSize2}px sans-serif`;
+  const tm = ctx.measureText(label);
+  const pad = 4;
+  const lh = fontSize2 + 4;
+  const lw = Math.max(tm.width + pad * 2, lh);
+  const rx = x;
+  const ry = y;
+  ctx.fillStyle = bgColor;
+  ctx.beginPath();
+  ctx.roundRect(rx, ry, lw, lh, 4);
+  ctx.fill();
+  ctx.fillStyle = "#1e1e1e";
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  ctx.fillText(label, rx + lw / 2, ry + lh / 2);
+}
+function drawArrowhead(ctx, x1, y1, x2, y2, size, color2) {
+  const angle2 = Math.atan2(y2 - y1, x2 - x1);
+  ctx.fillStyle = color2;
+  ctx.beginPath();
+  ctx.moveTo(x2, y2);
+  ctx.lineTo(
+    x2 - size * Math.cos(angle2 - Math.PI / 6),
+    y2 - size * Math.sin(angle2 - Math.PI / 6)
+  );
+  ctx.lineTo(
+    x2 - size * Math.cos(angle2 + Math.PI / 6),
+    y2 - size * Math.sin(angle2 + Math.PI / 6)
+  );
+  ctx.closePath();
+  ctx.fill();
+}
+function blobToImage(blob) {
+  return new Promise((resolve, reject) => {
+    const url = URL.createObjectURL(blob);
+    const img = new Image();
+    img.onload = () => {
+      URL.revokeObjectURL(url);
+      resolve(img);
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error("Failed to load screenshot image for compositing"));
+    };
+    img.src = url;
+  });
+}
 async function captureVideoInstantDual(rootEl, videoEl) {
   const clean = await capturePreviewForVideoFrame(rootEl, videoEl, "clean");
   const markersOnly = await capturePreviewForVideoFrame(
@@ -8774,6 +8978,20 @@ function aiditorConstructor(_props, refs) {
   const [videoRecordingNavLog, setVideoRecordingNavLog] = createSignal([]);
   const [recordingDraftAnnotation, setRecordingDraftAnnotation] = createSignal(null);
   const [videoPinsStagedDuringRecording, setVideoPinsStagedDuringRecording] = createSignal([]);
+  const [showSnapshotModal, setShowSnapshotModal] = createSignal(false);
+  const [snapshotCapture, setSnapshotCapture] = createSignal(null);
+  const [snapshotAnnotations, setSnapshotAnnotations] = createSignal([]);
+  const [snapshotTool, setSnapshotTool] = createSignal("point");
+  const [snapshotAreaDraft, setSnapshotAreaDraft] = createSignal(null);
+  const [snapshotDiscardConfirm, setSnapshotDiscardConfirm] = createSignal({
+    visible: false
+  });
+  const [snapshotArrowPending, setSnapshotArrowPending] = createSignal(null);
+  const [snapshotSubmitError, setSnapshotSubmitError] = createSignal("");
+  let snapshotAreaDragActive = false;
+  let snapshotAreaStartNorm = { x: 0, y: 0 };
+  let snapshotAreaListeners = null;
+  let snapshotAttachTargetPinId = null;
   let areaDragActive = false;
   let areaStartNorm = { x: 0, y: 0 };
   let areaListeners = null;
@@ -8790,6 +9008,7 @@ function aiditorConstructor(_props, refs) {
   let recordingStartedAt = 0;
   let recordingPreviewNavLog = [];
   let previewProbeTimer = null;
+  let iframeShortcutDoc = null;
   let attachVideoTargetPinId = null;
   let nextVideoPinSeq = 1;
   let recordingArrowCarryFromDraft = null;
@@ -9210,6 +9429,126 @@ function aiditorConstructor(_props, refs) {
       return false;
     return list.some((a2) => a2.instruction.trim().length === 0);
   });
+  const snapshotImageSrc = createMemo(() => snapshotCapture()?.imageUrl ?? "");
+  const snapshotCanSubmit = createMemo(() => snapshotAnnotations().length > 0 && !isRunning());
+  const snapshotShowDiscardConfirm = createMemo(() => snapshotDiscardConfirm().visible);
+  const snapshotToolNoneOn = createMemo(() => snapshotTool() === "none");
+  const snapshotToolPointOn = createMemo(() => snapshotTool() === "point");
+  const snapshotToolAreaOn = createMemo(() => snapshotTool() === "area");
+  const snapshotToolArrowOn = createMemo(() => snapshotTool() === "arrow");
+  const snapshotOverlayPointerNone = createMemo(() => snapshotTool() === "none");
+  const snapshotPointDisplayItems = createMemo(() => {
+    const list = snapshotAnnotations();
+    let pin = 0;
+    const out = [];
+    for (const a2 of list) {
+      pin += 1;
+      if (a2.kind === "point") {
+        out.push({
+          id: a2.id,
+          leftPct: a2.x * 100,
+          topPct: a2.y * 100,
+          indexLabel: String(pin)
+        });
+      }
+    }
+    return out;
+  });
+  const snapshotAreaDisplayItems = createMemo(() => {
+    const list = snapshotAnnotations();
+    let pin = 0;
+    const out = [];
+    for (const a2 of list) {
+      pin += 1;
+      if (a2.kind === "area") {
+        out.push({
+          id: a2.id,
+          leftPct: a2.x * 100,
+          topPct: a2.y * 100,
+          widthPct: a2.w * 100,
+          heightPct: a2.h * 100,
+          indexLabel: String(pin)
+        });
+      }
+    }
+    return out;
+  });
+  const snapshotArrowDisplayItems = createMemo(() => {
+    const list = snapshotAnnotations();
+    const out = [];
+    for (const a2 of list) {
+      if (a2.kind === "arrow") {
+        out.push({
+          id: a2.id,
+          x1Pct: a2.x1 * 100,
+          y1Pct: a2.y1 * 100,
+          x2Pct: a2.x2 * 100,
+          y2Pct: a2.y2 * 100
+        });
+      }
+    }
+    return out;
+  });
+  const snapshotArrowPinItems = createMemo(() => {
+    const list = snapshotAnnotations();
+    let pin = 0;
+    const out = [];
+    for (const a2 of list) {
+      pin += 1;
+      if (a2.kind === "arrow") {
+        out.push({
+          id: a2.id,
+          leftPct: a2.x2 * 100,
+          topPct: a2.y2 * 100,
+          indexLabel: String(pin)
+        });
+      }
+    }
+    return out;
+  });
+  const hasSnapshotArrowLines = createMemo(() => snapshotArrowDisplayItems().length > 0);
+  const showSnapshotArrowPending = createMemo(() => snapshotArrowPending() !== null);
+  const snapshotArrowPendingLeftPct = createMemo(() => (snapshotArrowPending()?.x ?? 0) * 100);
+  const snapshotArrowPendingTopPct = createMemo(() => (snapshotArrowPending()?.y ?? 0) * 100);
+  const snapshotAreaDraftNorm = createMemo(() => {
+    const d = snapshotAreaDraft();
+    if (!d)
+      return null;
+    return normalizeAreaRect(d.startX, d.startY, d.currentX, d.currentY);
+  });
+  const showSnapshotAreaDraft = createMemo(() => snapshotAreaDraftNorm() !== null);
+  const snapshotAreaDraftLeftPct = createMemo(() => (snapshotAreaDraftNorm()?.x ?? 0) * 100);
+  const snapshotAreaDraftTopPct = createMemo(() => (snapshotAreaDraftNorm()?.y ?? 0) * 100);
+  const snapshotAreaDraftWidthPct = createMemo(() => (snapshotAreaDraftNorm()?.w ?? 0) * 100);
+  const snapshotAreaDraftHeightPct = createMemo(() => (snapshotAreaDraftNorm()?.h ?? 0) * 100);
+  const snapshotAnnotationItems = createMemo(() => snapshotAnnotations().map((a2) => {
+    const { nx, ny } = bubbleAnchorNorm(a2);
+    const leftPct = nx * 100;
+    const topPct = ny * 100;
+    const { flipX, flipY } = popoverFlipFromPct(leftPct, topPct);
+    const attachmentChips = a2.attachments.map((at) => ({
+      key: at.id,
+      name: at.file.name,
+      thumbUrl: at.previewUrl && at.file.type.startsWith("image/") ? at.previewUrl : "",
+      annotationId: a2.id
+    }));
+    return {
+      id: a2.id,
+      indexLabel: a2.id,
+      kindLabel: `${a2.id} — ${kindLabel(a2.kind)}`,
+      instruction: a2.instruction,
+      kind: a2.kind,
+      leftPct,
+      topPct,
+      popoverFlipX: flipX,
+      popoverFlipY: flipY,
+      attachmentChips
+    };
+  }));
+  const showSnapshotAnnotationsPanel = createMemo(() => snapshotAnnotations().length > 0);
+  const showSnapshotSubmitError = createMemo(() => snapshotSubmitError().trim().length > 0);
+  const showSnapshotPointMarkers = createMemo(() => snapshotPointDisplayItems().length > 0);
+  const showSnapshotAreaItems = createMemo(() => snapshotAreaDisplayItems().length > 0);
   const chunkItems = createMemo(() => chunks());
   const hasChunks = createMemo(() => chunks().length > 0);
   const outputEmpty = createMemo(() => chunks().length === 0 && !isRunning());
@@ -9267,6 +9606,8 @@ function aiditorConstructor(_props, refs) {
       mediaRecorder?.stop();
     }
     tearDownVideoReviewModal();
+    if (showSnapshotModal())
+      tearDownSnapshotModal();
     cancelRecordingDraftAndClear();
     setVideoPinsStagedDuringRecording([]);
     lastRecordingWallDurationSec = 0;
@@ -9287,6 +9628,152 @@ function aiditorConstructor(_props, refs) {
     cancelAreaDragListeners();
     setVisualTool(next);
   }
+  function cancelSnapshotAreaDragListeners() {
+    snapshotAreaDragActive = false;
+    if (snapshotAreaListeners) {
+      snapshotAreaListeners();
+      snapshotAreaListeners = null;
+    }
+  }
+  function tearDownSnapshotModal() {
+    cancelSnapshotAreaDragListeners();
+    revokeAttachmentUrls(snapshotAnnotations());
+    const cap = snapshotCapture();
+    if (cap?.imageUrl)
+      URL.revokeObjectURL(cap.imageUrl);
+    setSnapshotCapture(null);
+    setSnapshotAnnotations([]);
+    setSnapshotTool("point");
+    setSnapshotAreaDraft(null);
+    setSnapshotArrowPending(null);
+    setSnapshotDiscardConfirm({ visible: false });
+    setSnapshotSubmitError("");
+    setShowSnapshotModal(false);
+  }
+  function onSelectSnapshotTool(next) {
+    setSnapshotArrowPending(null);
+    setSnapshotAreaDraft(null);
+    setSnapshotSubmitError("");
+    cancelSnapshotAreaDragListeners();
+    setSnapshotTool(next);
+  }
+  function setSnapshotAnnotationInstruction(id, instruction) {
+    setSnapshotAnnotations((prev) => prev.map((a2) => a2.id === id ? { ...a2, instruction } : a2));
+    setSnapshotSubmitError("");
+  }
+  function removeSnapshotAnnotation(id) {
+    setSnapshotAnnotations((prev) => {
+      const victim = prev.find((a2) => a2.id === id);
+      if (victim)
+        revokeAttachmentUrls([victim]);
+      return renumberAnnotations(prev.filter((a2) => a2.id !== id));
+    });
+    setSnapshotSubmitError("");
+  }
+  function snapshotUndo() {
+    setSnapshotAnnotations((prev) => {
+      if (prev.length === 0)
+        return prev;
+      const victim = prev[prev.length - 1];
+      revokeAttachmentUrls([victim]);
+      return renumberAnnotations(prev.slice(0, -1));
+    });
+  }
+  function snapshotClearAll() {
+    revokeAttachmentUrls(snapshotAnnotations());
+    setSnapshotAnnotations([]);
+    setSnapshotArrowPending(null);
+    setSnapshotAreaDraft(null);
+    cancelSnapshotAreaDragListeners();
+  }
+  function tryDismissSnapshotModal() {
+    if (snapshotAnnotations().length > 0) {
+      setSnapshotDiscardConfirm({ visible: true });
+    } else {
+      tearDownSnapshotModal();
+    }
+  }
+  function addFilesToSnapshotAnnotation(annotationId, files) {
+    setSnapshotAnnotations((prev) => {
+      const ix = prev.findIndex((a2) => a2.id === annotationId);
+      if (ix < 0)
+        return prev;
+      const ann = prev[ix];
+      let nextAtt = [...ann.attachments];
+      let byteSum = nextAtt.reduce((s, x) => s + x.file.size, 0);
+      for (const file of files) {
+        if (nextAtt.length >= MAX_ATTACHMENTS_PER_PIN) {
+          setSnapshotSubmitError(`Each pin allows at most ${MAX_ATTACHMENTS_PER_PIN} files.`);
+          break;
+        }
+        if (byteSum + file.size > MAX_ATTACHMENT_BYTES_PER_PIN) {
+          setSnapshotSubmitError(`File "${file.name}" is ${mbLabel(file.size)}; max per pin is ${mbLabel(MAX_ATTACHMENT_BYTES_PER_PIN)}.`);
+          break;
+        }
+        const id = newLocalAttachmentId();
+        const loc = { id, file };
+        if (file.type.startsWith("image/")) {
+          loc.previewUrl = URL.createObjectURL(file);
+        }
+        nextAtt = [...nextAtt, loc];
+        byteSum += file.size;
+      }
+      const nextAnn = { ...ann, attachments: nextAtt };
+      const copy = [...prev];
+      copy[ix] = nextAnn;
+      return copy;
+    });
+  }
+  function removeSnapshotAttachmentFile(annotationId, attachmentId) {
+    setSnapshotAnnotations((prev) => {
+      const ix = prev.findIndex((a2) => a2.id === annotationId);
+      if (ix < 0)
+        return prev;
+      const ann = prev[ix];
+      const victim = ann.attachments.find((x) => x.id === attachmentId);
+      if (victim?.previewUrl)
+        URL.revokeObjectURL(victim.previewUrl);
+      const nextAtt = ann.attachments.filter((x) => x.id !== attachmentId);
+      const nextAnn = { ...ann, attachments: nextAtt };
+      const copy = [...prev];
+      copy[ix] = nextAnn;
+      return copy;
+    });
+  }
+  function snapshotNormFromEvent(overlayEl, imgEl, e2) {
+    const imgRect = imgEl.getBoundingClientRect();
+    const imgNaturalAspect = imgEl.naturalWidth / imgEl.naturalHeight;
+    const containerAspect = imgRect.width / imgRect.height;
+    let renderedW, renderedH, offsetX, offsetY;
+    if (imgNaturalAspect > containerAspect) {
+      renderedW = imgRect.width;
+      renderedH = imgRect.width / imgNaturalAspect;
+      offsetX = 0;
+      offsetY = (imgRect.height - renderedH) / 2;
+    } else {
+      renderedH = imgRect.height;
+      renderedW = imgRect.height * imgNaturalAspect;
+      offsetX = (imgRect.width - renderedW) / 2;
+      offsetY = 0;
+    }
+    const imgContentLeft = imgRect.left + offsetX;
+    const imgContentTop = imgRect.top + offsetY;
+    const x = (e2.clientX - imgContentLeft) / renderedW;
+    const y = (e2.clientY - imgContentTop) / renderedH;
+    if (x < 0 || x > 1 || y < 0 || y > 1)
+      return null;
+    return { x, y };
+  }
+  function focusLastSnapshotAnnotationTextarea() {
+    requestAnimationFrame(() => {
+      tryJayRefExec(refs.snapshotBackdrop, (backdrop) => {
+        const textareas = backdrop.querySelectorAll("textarea.visual-annotation-instruction");
+        const last = textareas[textareas.length - 1];
+        if (last)
+          last.focus();
+      });
+    });
+  }
   function validateVisualAnnotationsForSubmit() {
     const list = visualAnnotations();
     if (list.length === 0)
@@ -9593,6 +10080,24 @@ function aiditorConstructor(_props, refs) {
   }
   runBootstrap();
   ensurePreviewProbePoll();
+  function handleSnapshotShortcut() {
+    if (visualTool() !== "none" || !showPreviewIframe() || showSnapshotModal() || showVideoReviewModal() || isVideoRecording())
+      return;
+    void triggerSnapshotCapture();
+  }
+  if (typeof document !== "undefined") {
+    document.addEventListener("keydown", (e2) => {
+      if ((e2.key === "s" || e2.key === "S") && (e2.metaKey || e2.ctrlKey) && e2.shiftKey && !e2.altKey) {
+        e2.preventDefault();
+        handleSnapshotShortcut();
+      }
+    }, true);
+  }
+  if (typeof window !== "undefined") {
+    window.addEventListener("aiditor:snapshot-shortcut", () => {
+      handleSnapshotShortcut();
+    });
+  }
   if (typeof window !== "undefined") {
     window.addEventListener("message", (e2) => {
       if (e2.data?.type === "jay:freeze") {
@@ -9931,6 +10436,98 @@ function aiditorConstructor(_props, refs) {
       setIsRunning(false);
     }
   }
+  async function runSnapshotSubmit() {
+    const list = snapshotAnnotations();
+    if (list.length === 0) {
+      setSnapshotSubmitError("Add at least one marker on the screenshot.");
+      return;
+    }
+    const cap = snapshotCapture();
+    if (!cap) {
+      setSnapshotSubmitError("Screenshot data is missing.");
+      return;
+    }
+    const notesJson = serializeAiditorNotes(toNotesPayload(list, previewBreakpoint()));
+    try {
+      setIsRunning(true);
+      setSnapshotSubmitError("");
+      const markerGeometries = list.map((a2) => ({
+        id: a2.id,
+        geometry: serializeGeometry(a2)
+      }));
+      const markersBlob = await compositeMarkersOntoScreenshot(cap.cleanBlob, markerGeometries);
+      const attachmentsByAnnotationId = /* @__PURE__ */ new Map();
+      for (const a2 of list) {
+        if (a2.attachments.length > 0) {
+          attachmentsByAnnotationId.set(a2.id, a2.attachments.map((x) => x.file));
+        }
+      }
+      const dual = { clean: cap.cleanBlob, markersOnly: markersBlob };
+      const route = cap.routePattern;
+      const rendered = cap.renderedUrl;
+      tearDownSnapshotModal();
+      clearVisualSession();
+      startAgentStream(notesJson, {
+        mode: "multi",
+        pageRoute: route,
+        renderedUrl: rendered,
+        dual,
+        attachmentsByAnnotationId: attachmentsByAnnotationId.size > 0 ? attachmentsByAnnotationId : void 0
+      });
+    } catch (err) {
+      console.error("snapshot submit:", err);
+      setSnapshotSubmitError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setIsRunning(false);
+    }
+  }
+  async function triggerSnapshotCapture() {
+    if (showSnapshotModal() || isRunning())
+      return;
+    const route = selectedPageUrl();
+    const rendered = previewUrlBar().trim();
+    if (!route || !rendered)
+      return;
+    if (!previewIsSameOriginForCapture(previewSrc()))
+      return;
+    let rootEl = null;
+    tryJayRefExec(refs.previewCaptureRoot, (el) => {
+      rootEl = el;
+    });
+    if (!rootEl)
+      return;
+    let iframeEl = null;
+    tryJayRefExec(refs.previewIframe, (el) => {
+      iframeEl = el;
+    });
+    try {
+      const unfreeze = iframeEl ? freezeTransientStyles(iframeEl) : () => {
+      };
+      let cleanBlob;
+      try {
+        cleanBlob = await capturePreviewForTask(rootEl, "clean");
+      } finally {
+        unfreeze();
+      }
+      const imageUrl = URL.createObjectURL(cleanBlob);
+      setSnapshotCapture({
+        cleanBlob,
+        imageUrl,
+        previewUrl: rendered,
+        routePattern: route,
+        renderedUrl: rendered
+      });
+      setSnapshotAnnotations([]);
+      setSnapshotTool("point");
+      setSnapshotAreaDraft(null);
+      setSnapshotArrowPending(null);
+      setSnapshotDiscardConfirm({ visible: false });
+      setSnapshotSubmitError("");
+      setShowSnapshotModal(true);
+    } catch (err) {
+      console.error("[aiditor] snapshot capture failed:", err);
+    }
+  }
   function formatClock(sec) {
     if (!Number.isFinite(sec))
       return "0:00";
@@ -9987,6 +10584,26 @@ function aiditorConstructor(_props, refs) {
       }
     }
   }
+  function ensureIframeShortcutForwarder() {
+    tryJayRefExec(refs.previewIframe, (fr) => {
+      const iframe = fr;
+      try {
+        const doc = iframe.contentDocument;
+        if (!doc)
+          return;
+        if (iframeShortcutDoc?.deref() === doc)
+          return;
+        iframeShortcutDoc = new WeakRef(doc);
+        doc.addEventListener("keydown", (e2) => {
+          if ((e2.key === "s" || e2.key === "S") && (e2.metaKey || e2.ctrlKey) && e2.shiftKey && !e2.altKey) {
+            e2.preventDefault();
+            window.dispatchEvent(new CustomEvent("aiditor:snapshot-shortcut"));
+          }
+        }, true);
+      } catch {
+      }
+    });
+  }
   function tickPreviewIframeProbe() {
     if (!isPreviewMode() || previewLoading())
       return;
@@ -9995,6 +10612,7 @@ function aiditorConstructor(_props, refs) {
     const src = previewSrc();
     if (!src || !previewIsSameOriginForCapture(src))
       return;
+    ensureIframeShortcutForwarder();
     tryJayRefExec(refs.previewIframe, (fr) => {
       const iframe = fr;
       try {
@@ -10798,9 +11416,236 @@ function aiditorConstructor(_props, refs) {
       tryJayRefExec(refs.videoReviewCloseBtn, (b) => b.click());
     }
   });
+  refs.snapshotToolPointBtn.onclick(() => onSelectSnapshotTool("point"));
+  refs.snapshotToolAreaBtn.onclick(() => onSelectSnapshotTool("area"));
+  refs.snapshotToolArrowBtn.onclick(() => onSelectSnapshotTool("arrow"));
+  refs.snapshotToolNoneBtn.onclick(() => onSelectSnapshotTool("none"));
+  refs.snapshotUndoBtn.onclick(() => snapshotUndo());
+  refs.snapshotClearBtn.onclick(() => {
+    if (snapshotAnnotations().length > 2) {
+      if (!window.confirm("Clear all markers?"))
+        return;
+    }
+    snapshotClearAll();
+  });
+  refs.snapshotCloseBtn.onclick(() => tryDismissSnapshotModal());
+  refs.snapshotCancelBtn.onclick(() => tryDismissSnapshotModal());
+  refs.snapshotDiscardBtn.onclick(() => tearDownSnapshotModal());
+  refs.snapshotKeepEditingBtn.onclick(() => setSnapshotDiscardConfirm({ visible: false }));
+  refs.snapshotSendBtn.onclick(() => {
+    void runSnapshotSubmit();
+  });
+  refs.snapshotBackdrop.onkeydown(({ event }) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      tryDismissSnapshotModal();
+      return;
+    }
+    if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+      event.preventDefault();
+      if (snapshotCanSubmit())
+        void runSnapshotSubmit();
+      return;
+    }
+  });
+  refs.snapshotOverlay.onmousedown(({ event }) => {
+    const mode = snapshotTool();
+    if (mode !== "area")
+      return;
+    const el = event.currentTarget;
+    let imgEl = null;
+    tryJayRefExec(refs.snapshotImg, (img) => {
+      imgEl = img;
+    });
+    if (!imgEl)
+      return;
+    const n = snapshotNormFromEvent(el, imgEl, event);
+    if (!n)
+      return;
+    event.preventDefault();
+    snapshotAreaDragActive = true;
+    snapshotAreaStartNorm = { x: n.x, y: n.y };
+    setSnapshotAreaDraft({
+      startX: n.x,
+      startY: n.y,
+      currentX: n.x,
+      currentY: n.y
+    });
+    const move = (ev) => {
+      if (!snapshotAreaDragActive || !imgEl)
+        return;
+      const cur = snapshotNormFromEvent(el, imgEl, ev);
+      if (!cur)
+        return;
+      setSnapshotAreaDraft({
+        startX: snapshotAreaStartNorm.x,
+        startY: snapshotAreaStartNorm.y,
+        currentX: cur.x,
+        currentY: cur.y
+      });
+    };
+    const up = (ev) => {
+      if (!snapshotAreaDragActive || !imgEl)
+        return;
+      snapshotAreaDragActive = false;
+      document.removeEventListener("mousemove", move);
+      document.removeEventListener("mouseup", up);
+      snapshotAreaListeners = null;
+      const cur = snapshotNormFromEvent(el, imgEl, ev);
+      if (cur) {
+        const r = normalizeAreaRect(snapshotAreaStartNorm.x, snapshotAreaStartNorm.y, cur.x, cur.y);
+        if (r.w > 8e-3 && r.h > 8e-3) {
+          setSnapshotAnnotations((prev) => renumberAnnotations([
+            ...prev,
+            {
+              id: "_",
+              kind: "area",
+              ...r,
+              instruction: "",
+              attachments: []
+            }
+          ]));
+          setSnapshotSubmitError("");
+          focusLastSnapshotAnnotationTextarea();
+        }
+      }
+      setSnapshotAreaDraft(null);
+    };
+    document.addEventListener("mousemove", move);
+    document.addEventListener("mouseup", up);
+    snapshotAreaListeners = () => {
+      document.removeEventListener("mousemove", move);
+      document.removeEventListener("mouseup", up);
+    };
+  });
+  refs.snapshotOverlay.onclick(({ event }) => {
+    const mode = snapshotTool();
+    if (mode === "area")
+      return;
+    const el = event.currentTarget;
+    let imgEl = null;
+    tryJayRefExec(refs.snapshotImg, (img) => {
+      imgEl = img;
+    });
+    if (!imgEl)
+      return;
+    const n = snapshotNormFromEvent(el, imgEl, event);
+    if (!n)
+      return;
+    if (mode === "point") {
+      setSnapshotAnnotations((prev) => renumberAnnotations([
+        ...prev,
+        {
+          id: "_",
+          kind: "point",
+          x: n.x,
+          y: n.y,
+          instruction: "",
+          attachments: []
+        }
+      ]));
+      setSnapshotSubmitError("");
+      focusLastSnapshotAnnotationTextarea();
+    } else if (mode === "arrow") {
+      const pending = snapshotArrowPending();
+      if (!pending) {
+        setSnapshotArrowPending(n);
+      } else {
+        const ln = { x1: pending.x, y1: pending.y, x2: n.x, y2: n.y };
+        setSnapshotArrowPending(null);
+        setSnapshotAnnotations((prev) => renumberAnnotations([
+          ...prev,
+          {
+            id: "_",
+            kind: "arrow",
+            ...ln,
+            instruction: "",
+            attachments: []
+          }
+        ]));
+        setSnapshotSubmitError("");
+        focusLastSnapshotAnnotationTextarea();
+      }
+    }
+  });
+  refs.snapshotAnnotationItems.snapshotAnnotationRow.oninput(({ event }) => {
+    const t = event.target;
+    if (t.tagName !== "TEXTAREA" || !t.classList.contains("visual-annotation-instruction"))
+      return;
+    const id = t.dataset.annotationId;
+    if (!id)
+      return;
+    setSnapshotAnnotationInstruction(id, t.value);
+  });
+  refs.snapshotAnnotationItems.snapshotAnnotationRow.onkeydown(({ event }) => {
+    const t = event.target;
+    if (t.tagName !== "TEXTAREA" || !t.classList.contains("visual-annotation-instruction"))
+      return;
+    if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+      event.preventDefault();
+      if (snapshotCanSubmit())
+        void runSnapshotSubmit();
+    } else if (event.key === "Escape") {
+      event.preventDefault();
+      const id = t.dataset.annotationId;
+      if (id)
+        removeSnapshotAnnotation(id);
+    }
+  });
+  refs.snapshotAnnotationItems.snapshotAnnotationRow.onclick(({ event }) => {
+    const btn = event.target.closest("button");
+    if (!btn)
+      return;
+    if (btn.classList.contains("snapshot-annotation-remove")) {
+      event.preventDefault();
+      const card = btn.closest("[data-annotation-id]");
+      const id = card?.getAttribute("data-annotation-id");
+      if (id)
+        removeSnapshotAnnotation(id);
+      return;
+    }
+    if (btn.classList.contains("snapshot-annotation-attach")) {
+      event.preventDefault();
+      const id = btn.dataset.annotationId;
+      if (!id)
+        return;
+      snapshotAttachTargetPinId = id;
+      tryJayRefExec(refs.snapshotAttachFileInput, (inp) => inp.click());
+      return;
+    }
+    if (btn.classList.contains("visual-attachment-remove-file")) {
+      event.preventDefault();
+      const aid = btn.dataset.annotationId;
+      const key = btn.dataset.attKey;
+      if (aid && key)
+        removeSnapshotAttachmentFile(aid, key);
+      return;
+    }
+  });
+  refs.snapshotAttachFileInput.onchange(({ event }) => {
+    const inp = event.target;
+    const files = inp.files;
+    const pin = snapshotAttachTargetPinId;
+    snapshotAttachTargetPinId = null;
+    if (!pin || !files?.length)
+      return;
+    addFilesToSnapshotAnnotation(pin, Array.from(files));
+    inp.value = "";
+  });
+  createEffect(() => {
+    if (showSnapshotModal()) {
+      requestAnimationFrame(() => {
+        tryJayRefExec(refs.snapshotBackdrop, (el) => el.focus());
+      });
+    }
+  });
   function routePastedFilesToAnnotationField(id, ta, files) {
     if (files.length === 0)
       return;
+    if (ta.closest(".snapshot-panel")) {
+      addFilesToSnapshotAnnotation(id, files);
+      return;
+    }
     if (ta.closest(".video-review-capture-root")) {
       addFilesToVideoAnnotation(id, files);
       return;
@@ -11039,7 +11884,35 @@ function aiditorConstructor(_props, refs) {
       videoPlayPauseGlyph,
       breakpointDesktopOn,
       breakpointTabletOn,
-      breakpointMobileOn
+      breakpointMobileOn,
+      showSnapshotModal,
+      snapshotImageSrc,
+      snapshotToolNoneOn,
+      snapshotToolPointOn,
+      snapshotToolAreaOn,
+      snapshotToolArrowOn,
+      snapshotCanSubmit,
+      snapshotShowDiscardConfirm,
+      snapshotOverlayPointerNone,
+      snapshotPointDisplayItems,
+      showSnapshotPointMarkers,
+      snapshotAreaDisplayItems,
+      showSnapshotAreaItems,
+      snapshotAreaDraftLeftPct,
+      snapshotAreaDraftTopPct,
+      snapshotAreaDraftWidthPct,
+      snapshotAreaDraftHeightPct,
+      showSnapshotAreaDraft,
+      snapshotArrowDisplayItems,
+      snapshotArrowPinItems,
+      hasSnapshotArrowLines,
+      showSnapshotArrowPending,
+      snapshotArrowPendingLeftPct,
+      snapshotArrowPendingTopPct,
+      snapshotAnnotationItems,
+      showSnapshotAnnotationsPanel,
+      showSnapshotSubmitError,
+      snapshotSubmitError
     })
   };
 }

package/dist/index.d.ts

@@ -152,6 +152,57 @@ interface VideoTimelineMarkerOfPageViewState {
   label: string
 }
 
+interface SnapshotPointDisplayItemOfPageViewState {
+  id: string,
+  leftPct: number,
+  topPct: number,
+  indexLabel: string
+}
+
+interface SnapshotAreaDisplayItemOfPageViewState {
+  id: string,
+  leftPct: number,
+  topPct: number,
+  widthPct: number,
+  heightPct: number,
+  indexLabel: string
+}
+
+interface SnapshotArrowDisplayItemOfPageViewState {
+  id: string,
+  x1Pct: number,
+  y1Pct: number,
+  x2Pct: number,
+  y2Pct: number
+}
+
+interface SnapshotArrowPinItemOfPageViewState {
+  id: string,
+  leftPct: number,
+  topPct: number,
+  indexLabel: string
+}
+
+interface AttachmentChipOfSnapshotAnnotationItemOfPageViewState {
+  key: string,
+  name: string,
+  thumbUrl: string,
+  annotationId: string
+}
+
+interface SnapshotAnnotationItemOfPageViewState {
+  id: string,
+  indexLabel: string,
+  kindLabel: string,
+  instruction: string,
+  kind: string,
+  leftPct: number,
+  topPct: number,
+  popoverFlipX: boolean,
+  popoverFlipY: boolean,
+  attachmentChips: Array<AttachmentChipOfSnapshotAnnotationItemOfPageViewState>
+}
+
 interface PageViewState {
   isBootstrapping: boolean,
   showBootstrapError: boolean,
@@ -262,7 +313,35 @@ interface PageViewState {
   videoPlayPauseGlyph: string,
   breakpointDesktopOn: boolean,
   breakpointTabletOn: boolean,
-  breakpointMobileOn: boolean
+  breakpointMobileOn: boolean,
+  showSnapshotModal: boolean,
+  snapshotImageSrc: string,
+  snapshotToolNoneOn: boolean,
+  snapshotToolPointOn: boolean,
+  snapshotToolAreaOn: boolean,
+  snapshotToolArrowOn: boolean,
+  snapshotCanSubmit: boolean,
+  snapshotShowDiscardConfirm: boolean,
+  snapshotOverlayPointerNone: boolean,
+  snapshotPointDisplayItems: Array<SnapshotPointDisplayItemOfPageViewState>,
+  showSnapshotPointMarkers: boolean,
+  snapshotAreaDisplayItems: Array<SnapshotAreaDisplayItemOfPageViewState>,
+  showSnapshotAreaItems: boolean,
+  snapshotAreaDraftLeftPct: number,
+  snapshotAreaDraftTopPct: number,
+  snapshotAreaDraftWidthPct: number,
+  snapshotAreaDraftHeightPct: number,
+  showSnapshotAreaDraft: boolean,
+  snapshotArrowDisplayItems: Array<SnapshotArrowDisplayItemOfPageViewState>,
+  snapshotArrowPinItems: Array<SnapshotArrowPinItemOfPageViewState>,
+  hasSnapshotArrowLines: boolean,
+  showSnapshotArrowPending: boolean,
+  snapshotArrowPendingLeftPct: number,
+  snapshotArrowPendingTopPct: number,
+  snapshotAnnotationItems: Array<SnapshotAnnotationItemOfPageViewState>,
+  showSnapshotAnnotationsPanel: boolean,
+  showSnapshotSubmitError: boolean,
+  snapshotSubmitError: string
 }
 
 
@@ -306,11 +385,29 @@ interface PageElementRefs {
   videoReviewDiscardBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
   videoReviewSendBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
   videoReviewBackdrop: HTMLElementProxy<PageViewState, HTMLDivElement>,
+  snapshotCloseBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotToolPointBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotToolAreaBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotToolArrowBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotToolNoneBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotUndoBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotClearBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotAttachFileInput: HTMLElementProxy<PageViewState, HTMLInputElement>,
+  snapshotImg: HTMLElementProxy<PageViewState, HTMLImageElement>,
+  snapshotOverlay: HTMLElementProxy<PageViewState, HTMLDivElement>,
+  snapshotDiscardBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotKeepEditingBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotCancelBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotSendBtn: HTMLElementProxy<PageViewState, HTMLButtonElement>,
+  snapshotBackdrop: HTMLElementProxy<PageViewState, HTMLDivElement>,
   visualAnnotationRows: {
     annotationRow: HTMLElementCollectionProxy<VisualAnnotationRowOfPageViewState, HTMLDivElement>
   },
   videoAnnotationRows: {
     videoAnnotationRow: HTMLElementCollectionProxy<VideoAnnotationRowOfPageViewState, HTMLDivElement>
+  },
+  snapshotAnnotationItems: {
+    snapshotAnnotationRow: HTMLElementCollectionProxy<SnapshotAnnotationItemOfPageViewState, HTMLDivElement>
   }
 }
 

package/dist/pages/aiditor/page.jay-html

@@ -146,6 +146,34 @@
     .video-review-primary { background: #0e639c; color: #fff; border: none; border-radius: 6px; padding: 8px 18px; font-size: 13px; cursor: pointer; }
     .video-review-primary:hover { background: #1177bb; }
     .video-review-primary:disabled { opacity: 0.45; cursor: not-allowed; }
+    .snapshot-overlay { position: fixed; inset: 0; z-index: 200; background: rgba(0,0,0,0.78); display: flex; align-items: center; justify-content: center; padding: 20px; box-sizing: border-box; }
+    .snapshot-panel { background: #252526; border: 1px solid #3e3e3e; border-radius: 10px; width: min(1200px, 96vw); max-height: 94vh; display: flex; flex-direction: column; gap: 10px; padding: 14px 16px; overflow: hidden; }
+    .snapshot-header { display: flex; justify-content: space-between; align-items: center; gap: 12px; flex-shrink: 0; }
+    .snapshot-title { font-size: 15px; font-weight: 600; color: #9cdcfe; margin: 0; }
+    .snapshot-close { background: none; border: none; color: #888; font-size: 18px; cursor: pointer; padding: 0 4px; line-height: 1; }
+    .snapshot-close:hover { color: #fff; }
+    .snapshot-tools { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; flex-shrink: 0; }
+    .snapshot-body { display: flex; gap: 14px; flex: 1; min-height: 0; overflow: hidden; }
+    .snapshot-capture-area { flex: 2; min-width: 0; position: relative; display: flex; align-items: center; justify-content: center; background: #1e1e1e; border-radius: 8px; overflow: hidden; }
+    .snapshot-img { max-width: 100%; max-height: 100%; object-fit: contain; display: block; user-select: none; -webkit-user-drag: none; }
+    .snapshot-img-overlay { position: absolute; inset: 0; z-index: 2; }
+    .snapshot-img-overlay-none { pointer-events: none; }
+    .snapshot-annotations-panel { flex: 1; min-width: 220px; max-width: 340px; display: flex; flex-direction: column; gap: 8px; overflow-y: auto; }
+    .snapshot-annotation-card { background: #1e1e1e; border: 1px solid #3e3e3e; border-radius: 8px; padding: 10px 12px; display: flex; flex-direction: column; gap: 6px; }
+    .snapshot-annotation-card-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+    .snapshot-annotation-kind { font-size: 11px; color: #9cdcfe; font-weight: 600; }
+    .snapshot-annotation-remove { background: transparent; color: #888; border: 1px solid #3e3e3e; border-radius: 4px; padding: 4px 8px; font-size: 11px; cursor: pointer; }
+    .snapshot-annotation-remove:hover { color: #f48771; border-color: #f48771; }
+    .snapshot-empty-hint { color: #888; font-size: 12px; font-style: italic; padding: 8px 0; }
+    .snapshot-footer { display: flex; gap: 10px; justify-content: flex-end; align-items: center; flex-wrap: wrap; flex-shrink: 0; margin-top: 4px; }
+    .snapshot-secondary { background: #3c3c3c; color: #ddd; border: 1px solid #555; border-radius: 6px; padding: 8px 16px; font-size: 13px; cursor: pointer; }
+    .snapshot-secondary:hover { background: #4a4a4a; }
+    .snapshot-primary { background: #0e639c; color: #fff; border: none; border-radius: 6px; padding: 8px 18px; font-size: 13px; cursor: pointer; }
+    .snapshot-primary:hover { background: #1177bb; }
+    .snapshot-primary:disabled { opacity: 0.45; cursor: not-allowed; }
+    .snapshot-discard-confirm { display: flex; align-items: center; gap: 10px; font-size: 13px; color: #f48771; }
+    .snapshot-discard-confirm-msg { flex: 1; }
+    .snapshot-overlay .arrow-svg line { marker-end: url(#aiditor-snapshot-arrowhead); }
   </style>
   <script type="application/jay-data">
 data:
@@ -350,6 +378,67 @@ data:
     breakpointDesktopOn: boolean
     breakpointTabletOn: boolean
     breakpointMobileOn: boolean
+    showSnapshotModal: boolean
+    snapshotImageSrc: string
+    snapshotToolNoneOn: boolean
+    snapshotToolPointOn: boolean
+    snapshotToolAreaOn: boolean
+    snapshotToolArrowOn: boolean
+    snapshotCanSubmit: boolean
+    snapshotShowDiscardConfirm: boolean
+    snapshotOverlayPointerNone: boolean
+    snapshotPointDisplayItems:
+    - id: string
+      leftPct: number
+      topPct: number
+      indexLabel: string
+    showSnapshotPointMarkers: boolean
+    snapshotAreaDisplayItems:
+    - id: string
+      leftPct: number
+      topPct: number
+      widthPct: number
+      heightPct: number
+      indexLabel: string
+    showSnapshotAreaItems: boolean
+    snapshotAreaDraftLeftPct: number
+    snapshotAreaDraftTopPct: number
+    snapshotAreaDraftWidthPct: number
+    snapshotAreaDraftHeightPct: number
+    showSnapshotAreaDraft: boolean
+    snapshotArrowDisplayItems:
+    - id: string
+      x1Pct: number
+      y1Pct: number
+      x2Pct: number
+      y2Pct: number
+    snapshotArrowPinItems:
+    - id: string
+      leftPct: number
+      topPct: number
+      indexLabel: string
+    hasSnapshotArrowLines: boolean
+    showSnapshotArrowPending: boolean
+    snapshotArrowPendingLeftPct: number
+    snapshotArrowPendingTopPct: number
+    snapshotAnnotationItems:
+    - id: string
+      indexLabel: string
+      kindLabel: string
+      instruction: string
+      kind: string
+      leftPct: number
+      topPct: number
+      popoverFlipX: boolean
+      popoverFlipY: boolean
+      attachmentChips:
+      - key: string
+        name: string
+        thumbUrl: string
+        annotationId: string
+    showSnapshotAnnotationsPanel: boolean
+    showSnapshotSubmitError: boolean
+    snapshotSubmitError: string
   </script>
 </head>
 <body>
@@ -754,6 +843,128 @@ data:
   </div>
 </div>
 
+<div class="snapshot-overlay" if="showSnapshotModal" ref="snapshotBackdrop" tabindex="-1" role="dialog" aria-modal="true" aria-label="Snapshot annotation">
+  <div class="snapshot-panel">
+    <div class="snapshot-header">
+      <h2 class="snapshot-title">Snapshot Annotation</h2>
+      <button type="button" class="snapshot-close" ref="snapshotCloseBtn" aria-label="Close">✕</button>
+    </div>
+    <div class="snapshot-tools">
+      <button type="button" class="{snapshotToolPointOn ? visual-tool-on} visual-tool-btn" ref="snapshotToolPointBtn" title="Point" aria-label="Point tool">⊙</button>
+      <button type="button" class="{snapshotToolAreaOn ? visual-tool-on} visual-tool-btn" ref="snapshotToolAreaBtn" title="Area" aria-label="Area tool">▢</button>
+      <button type="button" class="{snapshotToolArrowOn ? visual-tool-on} visual-tool-btn" ref="snapshotToolArrowBtn" title="Arrow" aria-label="Arrow tool">↗</button>
+      <button type="button" class="{snapshotToolNoneOn ? visual-tool-on} visual-tool-btn" ref="snapshotToolNoneBtn" title="Select" aria-label="Select tool">⤢</button>
+      <span class="tool-group-sep"></span>
+      <button type="button" class="visual-tool-btn" ref="snapshotUndoBtn" title="Undo last marker" aria-label="Undo">↩</button>
+      <button type="button" class="visual-tool-btn" ref="snapshotClearBtn" title="Clear all markers" aria-label="Clear all">✕ Clear</button>
+    </div>
+    <input type="file" class="file-input-hidden" ref="snapshotAttachFileInput" multiple />
+    <div class="snapshot-body">
+      <div class="snapshot-capture-area">
+        <img class="snapshot-img" ref="snapshotImg" src="{snapshotImageSrc}" alt="Captured snapshot" draggable="false" />
+        <div class="{snapshotOverlayPointerNone ? snapshot-img-overlay-none} snapshot-img-overlay" ref="snapshotOverlay">
+          <div
+            class="point-marker"
+            forEach="snapshotPointDisplayItems"
+            trackBy="id"
+            style="left: {leftPct}%; top: {topPct}%;"
+          >
+            <span class="point-marker-idx">{indexLabel}</span>
+          </div>
+          <div
+            class="area-rect"
+            forEach="snapshotAreaDisplayItems"
+            trackBy="id"
+            style="left: {leftPct}%; top: {topPct}%; width: {widthPct}%; height: {heightPct}%;"
+          ><span class="area-marker-idx">{indexLabel}</span></div>
+          <div
+            class="area-rect area-rect-draft"
+            if="showSnapshotAreaDraft"
+            style="left: {snapshotAreaDraftLeftPct}%; top: {snapshotAreaDraftTopPct}%; width: {snapshotAreaDraftWidthPct}%; height: {snapshotAreaDraftHeightPct}%;"
+          ></div>
+          <div
+            class="arrow-pending-dot"
+            if="showSnapshotArrowPending"
+            style="left: {snapshotArrowPendingLeftPct}%; top: {snapshotArrowPendingTopPct}%;"
+          ></div>
+          <svg class="arrow-svg" if="hasSnapshotArrowLines" viewBox="0 0 100 100" preserveAspectRatio="none">
+            <defs>
+              <marker id="aiditor-snapshot-arrowhead" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+                <polygon points="0 0, 8 4, 0 8" fill="#c586ff" />
+              </marker>
+            </defs>
+            <line
+              forEach="snapshotArrowDisplayItems"
+              trackBy="id"
+              x1="{x1Pct}"
+              y1="{y1Pct}"
+              x2="{x2Pct}"
+              y2="{y2Pct}"
+            />
+          </svg>
+          <div
+            class="arrow-end-pin"
+            forEach="snapshotArrowPinItems"
+            trackBy="id"
+            style="left: {leftPct}%; top: {topPct}%;"
+          >{indexLabel}</div>
+        </div>
+      </div>
+      <div class="snapshot-annotations-panel">
+        <p class="snapshot-empty-hint" if="!showSnapshotAnnotationsPanel">Click the screenshot to place a marker, or select a tool from the toolbar.</p>
+        <div
+          class="snapshot-annotation-card"
+          forEach="snapshotAnnotationItems"
+          trackBy="id"
+          ref="snapshotAnnotationRow"
+          data-annotation-id="{id}"
+        >
+          <div class="snapshot-annotation-card-head">
+            <span class="snapshot-annotation-kind">{kindLabel}</span>
+            <button type="button" class="snapshot-annotation-remove" title="Remove annotation" aria-label="Remove annotation">×</button>
+          </div>
+          <textarea
+            class="visual-annotation-instruction"
+            placeholder="Instruction for this annotation…"
+            data-annotation-id="{id}"
+            value="{instruction}"
+          ></textarea>
+          <div class="visual-annotation-files">
+            <div class="visual-attach-row">
+              <button type="button" class="visual-attach-btn snapshot-annotation-attach" data-annotation-id="{id}">
+                Attach file
+              </button>
+            </div>
+            <div class="visual-attachment-chips" forEach="attachmentChips" trackBy="key">
+              <div class="visual-attachment-chip">
+                <img if="thumbUrl" class="visual-attachment-thumb" src="{thumbUrl}" alt="" />
+                <span class="visual-attachment-name">{name}</span>
+                <button
+                  type="button"
+                  class="visual-attachment-remove-file"
+                  data-annotation-id="{annotationId}"
+                  data-att-key="{key}"
+                  aria-label="Remove attachment"
+                >×</button>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <p class="visual-submit-error" if="showSnapshotSubmitError">{snapshotSubmitError}</p>
+    <div class="snapshot-footer">
+      <div class="snapshot-discard-confirm" if="snapshotShowDiscardConfirm">
+        <span class="snapshot-discard-confirm-msg">Discard annotations?</span>
+        <button type="button" class="snapshot-secondary" ref="snapshotDiscardBtn">Discard</button>
+        <button type="button" class="snapshot-secondary" ref="snapshotKeepEditingBtn">Keep editing</button>
+      </div>
+      <button type="button" class="snapshot-secondary" ref="snapshotCancelBtn" if="!snapshotShowDiscardConfirm">Cancel</button>
+      <button type="button" class="snapshot-primary" ref="snapshotSendBtn" disabled="!snapshotCanSubmit" if="!snapshotShowDiscardConfirm">Send to Agent</button>
+    </div>
+  </div>
+</div>
+
 </div>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/aiditor",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "type": "module",
   "description": "AIditor — visual AI-driven code editor plugin for Jay Framework",
   "main": "dist/index.js",
@@ -42,16 +42,16 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.119",
-    "@jay-framework/fullstack-component": "^0.17.1",
-    "@jay-framework/stack-client-runtime": "^0.17.1",
-    "@jay-framework/stack-server-runtime": "^0.17.1",
+    "@jay-framework/fullstack-component": "^0.17.2",
+    "@jay-framework/stack-client-runtime": "^0.17.2",
+    "@jay-framework/stack-server-runtime": "^0.17.2",
     "busboy": "^1.6.0",
     "html2canvas": "^1.4.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.17.1",
-    "@jay-framework/jay-cli": "^0.17.1",
+    "@jay-framework/compiler-jay-stack": "^0.17.2",
+    "@jay-framework/jay-cli": "^0.17.2",
     "@types/busboy": "^1",
     "rimraf": "^5.0.5",
     "tsup": "^8.5.1",