thierryc/codex-screenshot-annotator/annotate-screenshot

Annotate Screenshot

Use the built-in in-app Browser and its native Annotation mode. Do not open the viewer in Chrome, use web search, create a custom annotation document, or translate Browser comments into another format.

Resolve one source mode

1. Confirm that the in-app Browser skill is available. If it is unavailable,

stop and tell the user to install Browser from the Plugins Directory. Do not substitute another browser.

1. Choose exactly one source mode:

• Use 1–12 local PNG, JPEG, or WebP paths when they are genuinely available

and belong to the requested review set. Preserve the user's requested or task-established order. Never invent attachment paths or add unrelated screenshots discovered in the workspace.

• When the user explicitly asks to capture an in-app Browser tab, follow the

Browser skill and resolve exactly one mentioned tab or an unambiguous controlled tab for the current task. Never guess between tabs, switch browsers, or capture an app window, desktop, or browser chrome.

• If neither source is usable, open the viewer without an image so the user

can choose, drop, or paste files.

1. If more than 12 local screenshots are requested, stop and ask the user to

select at most 12. Do not silently truncate the set.

Capture one Browser tab

1. Treat the user's explicit capture request as authorization for the resolved

tab. If the target is missing, stale, inaccessible, or ambiguous, stop and ask the user to mention the intended tab.

1. Capture page content with the Browser tab screenshot API. Capture the

visible viewport by default; use a full-page capture only when the user explicitly requests it.

1. While still in the Browser's Node session, import

scripts/write-capture.mjs from this skill directory and call its exported writeCapture(bytes, nodeRepl.tmpDir) helper. Browser screenshots are not guaranteed to use one encoding; the helper validates PNG, JPEG, or WebP bytes and writes a uniquely named file with the correct extension. Do not pass image bytes through shell output, write the capture into the workspace, or expose its path to the user.

1. Use that temporary path as the only local source below. If capture or saving

fails, report the specific error and do not fall back to another surface.

Launch the durable review

1. Start scripts/serve-review.mjs from this skill directory in a retained,

long-running terminal session. Repeat --image once per ordered local path:

``bash node <this-skill-directory>/scripts/serve-review.mjs \ --image <quoted-first-path> \ --image <quoted-second-path> ``

Omit every --image when no usable path exists. If the launcher fails with listen EPERM for 127.0.0.1, retry that exact local-only command with the required sandbox permission. If permission is denied, report the specific error and offer the manual picker; do not substitute another server.

1. Read and retain the exact REVIEW_URL= value and process handle. The server

validates the complete input set before listening and keeps every initial screenshot in memory, so reopening the URL reconstructs the ordered review.

1. For an agent-generated Browser capture, delete its temporary file after the

REVIEW_URL= line appears because the server has loaded it into memory.

Show and verify the review

1. Open the exact review URL in a new in-app Browser tab. Do not navigate a

captured source tab away.

1. Before claiming success, verify all of the following from current page state:

• the page title is Screenshot feedback;
• the numbered screen selector displays 0 / 0 for the empty viewer or

contains exactly one ordered option per supplied screenshot;

• every supplied screenshot basename appears in the expected order.

1. When codex_app__open_in_codex is available, explicitly mount the controlled

tab in the current task with a Browser target using its tab ID and right-side placement. An opened or queued result may continue to the visibility check; an error must stop the viewer and be reported.

1. Get the Browser visibility capability, call set(true), then call get().

Also confirm that tabs.selected() identifies the intended review tab. Treat a result other than true or a different selected tab as a failed handoff. Mounting the Codex panel before setting visibility is required because some desktop hosts queue the panel until visibility is requested.

1. Finalize the Browser tabs once, as the final Browser action, keeping the

review tab with status deliverable. Never finalize a completed review handoff as handoff.

1. Only after the page, screen set, visibility, panel opening, and deliverable

finalization succeed may you say that the review is open. Never infer user visibility from successful navigation alone.

1. Tell the user that the viewer can hold up to 12 screens. They can use + or

drag and drop to append local images, paste one image from the pasteboard, use the numbered dropdown to jump between screens, and use − to remove the active screen. Then tell them to turn on Annotation mode, click an element or drag over an area, save each comment, and send “Address these browser comments” in the current task.

Reopen the current review

When the user says “open it” or otherwise asks to show the prepared review, reuse the retained process and exact review URL. Claim an exact title-and-URL match when one exists; when several tabs match the same session URL, use the most recently opened exact match. If none exists, open a new in-app Browser tab at the same URL. Repeat the complete page-state, screen-count, visibility, panel-opening, and deliverable checks above. If the server expired or is no longer reachable, report that fact and start a new review only from genuinely available source paths. Never report that prior screens survived without DOM evidence.

Complete the handoff

When the user returns with Browser comments, stop the retained viewer process before addressing the feedback. Treat the native comments and their target context as the source of truth. Do not ask for a JSON export or recreate the comments in project files.

If the user has not yet saved or submitted the comments, keep the viewer alive and explain the missing step. If launch, verification, or panel handoff fails after the server starts, stop its process before reporting the error.

Fallbacks and boundaries

• If Node.js is unavailable, ask the user to manually open

assets/viewer.html from this skill directory as a file-backed page and use its picker. Do not try to automate a file:// navigation. If the host also blocks user-opened local pages, explain that Node.js is required.

• If the launcher rejects a missing, unsupported, empty, oversized, mixed, or

over-limit file set, report the exact error and offer the manual picker. Do not weaken validation or open only the valid subset.

• Automatic multi-screen preload applies only to genuine local screenshots.

Agent capture supports one in-app Browser page at a time; capturing multiple unrelated Browser tabs remains out of scope.

• The viewer has no upload endpoint or external network dependency. Submitting

Browser comments still sends those comments through the existing Codex task.