Troubleshoot copy and handoff warnings

Pinar first uses the browser clipboard API through an offscreen document and falls back to a hidden text selection when permission or focus blocks it. If every copy mechanism fails, the overlay is restored so your pins and comments remain editable.

screenshot_missing means the image could not be persisted. helper_unavailable means the local service was not reached. viewer_unavailable means no viewer URL was produced. Continue from the comment, DOM path, selector, pin coordinates, captureId, and pinId, then retry only the missing layer.

Copy requires a saved comment and at least one pin. The toolbar shows “Saving the session…”, hides overlays, captures the shot, then asks the offscreen document to write text/html and text/plain. Offscreen tries navigator.clipboard.write first and falls back to a copy event plus execCommand. If that write is not ok, the content script still attempts writePlainText on the returned plain payload: clipboard.writeText, then a hidden textarea selection.

When every copy path fails, the page sends overlays:hidden with hidden false, flashes “Copy failed”, and leaves pins editable. A successful copy shows “Copied successfully!”, or “Copied successfully!” plus “no screenshot”, “helper unavailable”, or “no viewer”, then ends the session. Those suffixes map to screenshot_missing, helper_unavailable, and viewer_unavailable. screenshot_inline is not one of the degraded handoff warnings. A paste without a closed pinar-visual-context fence cannot be parsed as JSON.

• If the toolbar says “Write a comment first” or “Add a pin first”, finish that pin and press Command+Enter / Alt+Enter again.
• If “Copy failed” appears, confirm the pins are still on the page, grant clipboard permission if prompted, and retry the copy.
• Read the “Copied successfully!” suffix: “no screenshot”, “helper unavailable”, and “no viewer” name the missing layer to retry without discarding comments.

When finishing fails because the final screenshot cannot be captured, the toolbar shows one of these messages instead of a generic error, and the session stays on the page for a retry. Each message names the cause and the fix:

• “A pin is outside the visible area · bring it into view and try again” — scroll until the pinned element is visible, then finish the session again.
• “The page changed during capture · stay on the page and try again” — finish again from the annotated page without leaving it.
• “The annotated tab was not active · switch back to it and try again” — switch to the annotated tab and finish again.
• “Screenshot not captured · return to the annotated page and try again” — return to the annotated page and finish again.