DevMark — Page Annotator

DevMark is a dependency-free Chromium extension for responsive development and turning visual UI feedback into useful developer context. It includes current-tab Device Preview, visual annotations, screenshots, and an optional Arc MCP bridge.

Start an annotation session, hover-highlight a page element, click it, and save a note with:

• a cropped screenshot of the visible part of the element;
• a best-effort CSS selector and DOM breadcrumb;
• a sanitized DOM snippet;
• a small computed-style snapshot; and
• the page path and element coordinates.

You can collect multiple annotations, review them in the page, retry interrupted screenshot saves, copy a Markdown report, or download the whole session as JSON. Confirming an annotation automatically saves its screenshot under Downloads/DevMark/<page-host>/, and the resolved absolute device path is included in the Markdown and JSON reports.

DevMark targets Chromium 125 or newer. The optional MCP bridge currently targets Arc on macOS.

Install locally

1. Open the browser's extensions page (chrome://extensions, or edge://extensions in Edge).
2. Turn on Developer mode.
3. Click Load unpacked.
4. Select the chrome-extensions/devmark folder—the folder containing manifest.json.
5. Pin DevMark to the browser toolbar if you want quick access.

For a local file:// page, open DevMark's extension details and enable Allow access to file URLs.

The extension now declares debugger, nativeMessaging, and tabs permissions for its optional MCP mode. Arc will show the corresponding elevated permission and debugging notices. Annotation itself still activates only for the tab where you select Start annotating.

Use

1. Open a normal website, localhost app, or enabled local file.
2. Click DevMark and choose Start annotating.
3. Hover until the wanted element is outlined, then click it.
4. Add the annotation text and select Save annotation.
5. Repeat for as many elements as needed.
6. Select Review or press Escape to review the collection.
7. Drag the toolbar from its dotted grip or empty space, and drag the annotation panel from its header when either one covers the page.
8. Use Clear in the review header to reset the current annotations and numbering. Screenshot files already saved to the device remain in place.

Device Preview

Open the popup's Device Preview section to test the current HTTP(S) page at 4K Display, Full HD Desktop, Laptop L, Laptop S, iPad, iPhone, or Pixel dimensions, or enter a custom width, height, DPR, and desktop/mobile profile. The recommended 4K Display profile uses a readable 1920×1080 CSS viewport at 2x DPR while still producing 3840×2160 output, and selects Fill so ordinary Arc windows do not show an unused strip. 3840px CSS (Advanced) is available at the end of the preset list for true 3840px CSS breakpoint testing, switches back to Entire viewport, warns before use, and requires an explicit Apply because it will look tiny in a normal Arc window. The compact in-page toolbar remains available after the popup closes, defaults to the bottom-right, collapses after applying, can be dragged or expanded, rotates the viewport, and supports Entire viewport (Contain), Fill, and fixed 25/50/75/100 percent fit modes.

Manual Device Preview is independent from MCP and only attaches the current tab you explicitly open. If MCP Browser Control is later enabled, both features share that tab's debugger connection. Entire viewport keeps the complete live viewport visible and can leave unused space in Arc when the aspect ratios differ. Fill covers the available Arc surface while scaling down, cropping overflow from the right or bottom as necessary; it is capped at 100%, so smaller previews are not enlarged. Fit changes only the live presentation: screenshots always capture the complete viewport at its native emulated pixel dimensions.

Named phone and tablet presets emulate device identity by default; desktop and laptop presets plus custom desktop and custom-mobile profiles keep native Arc identity. Pass "emulateDeviceIdentity": false with a named mobile preset to test mobile dimensions and touch without an identity override. A custom-mobile profile remains native and layout-only unless "emulateDeviceIdentity": true; the UI exposes this opt-in as Mobile + identity.

Pixel identity matches current Chromium DevTools data for Android 13 and supplies both UA and UA-CH. Apple phone and tablet identities match current Chromium DevTools data for iOS/iPadOS 18.5, sending a Safari-style UA plus userAgentMetadata platform, model, and mobile values. Moving between native and emulated identity reloads the page exactly once. Clearing Device Preview restores native Arc identity and reloads once when needed. Because chrome.debugger cannot call Browser.getVersion, DevMark derives the Chromium version from a one-time isolated native navigator.userAgent snapshot. These overrides affect the identity visible to sites; Arc's underlying rendering engine remains Chromium.

Keyboard shortcuts:

• Escape: cancel the current selection or finish selecting.
• Command + Enter / Control + Enter: save the current annotation.

Copy report uses the modern Clipboard API and reports when copying is unavailable on an insecure or browser-policy-restricted page. DevMark requests Chromium's downloads permission so it can save each confirmed screenshot and query the final device path after Chromium finishes the download. It uses session-only extension storage for a short-lived digest and one-time save authorization; screenshot bytes are not placed in extension storage. Chromium download settings or policies can still prompt for, rename, redirect, or block a file. A failed save keeps the annotation and exposes Retry image save in Review. Report actions remain disabled until every available screenshot has a resolved path. JSON report downloads can also be blocked by a page sandbox, and JSON reports omit embedded screenshot data in favor of the saved image path.

Optional Arc MCP browser control

The local companion exposes DevMark to Codex or another stdio MCP client. It can inspect DOM/accessibility trees, console logs, network traffic and bodies, cookies and page storage, screenshots, and saved annotations. It can also click, type, press keys, scroll, manage tabs, navigate, wait for page state, and evaluate JavaScript.

Requirements:

• macOS with Arc;
• Node.js 22 or newer; and
• Codex CLI when automatic Codex MCP registration is wanted.

Install the companion after DevMark is already loaded unpacked in Arc:

cd companion
npm install
npm run install:arc

The installer discovers the unpacked DevMark extension ID from Arc's profiles, writes exact-origin Native Messaging manifests at Arc's active and compatibility lookup paths, creates an owner-only local configuration and random authentication secret, and registers the devmark-arc MCP server with Codex. If automatic discovery cannot distinguish multiple installations, rerun it with:

npm run install:arc -- --extension-id YOUR_EXTENSION_ID

Reload DevMark in arc://extensions, then open its popup. MCP access remains off until you acknowledge the visible sensitive-capabilities warning and select Enable MCP bridge. A red MCP badge remains visible while normal tabs are attached. Select Stop to detach every tab and clear volatile captured data. Start a new Codex session after installation so it loads the registered MCP server.

Remove only the local bridge with:

cd companion
npm run uninstall:arc

Use Stop in the popup and close Arc before uninstalling. The installer and uninstaller refuse to replace or remove a socket owned by a live DevMark host. Uninstalling does not remove the extension or delete saved annotation screenshots. See MCP.md for the interface, security model, limits, and expected debugger interruptions. See PRIVACY.md before enabling raw browser access.

MVP boundaries

• Captures only the visible portion of an element. It does not stitch off-screen content.
• Provides rendered DOM context, not original React/Vue component filenames or source-map locations.
• Selects the top-level rendered element only. Iframe and Shadow DOM internals are outside the MVP; their host element can still be selected.
• Does not run on protected pages such as chrome://, browser extension stores, or some built-in viewers.
• Keeps the session in tab memory. Reloading or navigating the page clears it.
• Masks form controls in screenshot crops, but you should still review captures before sharing them.

These boundaries describe annotation mode. MCP mode is intentionally more powerful and can inspect frames/workers through Chromium debugging, but it still cannot control Arc's native sidebar, Spaces, command bar, protected pages, or activity that occurred before debugger attachment.

See PRIVACY.md for the local-data and sanitization behavior.

Manual browser checklist

After loading the unpacked extension:

1. Open a normal HTTPS or localhost page, start Device Preview, and verify Laptop L, Laptop S, 4K, a phone preset, custom dimensions, rotation, Entire viewport, Fill, and fixed fit values update the live presentation while preserving the responsive layout.
2. Drag and collapse the Device Preview toolbar, close the popup, and verify preview remains active; then exit and verify the normal viewport returns.
3. Confirm Start annotating closes the popup and shows the DevMark toolbar.
4. Move across nested elements and confirm the purple outline and selector label follow the hovered element.
5. Select a link or button and confirm the underlying page action does not run on pointer down, pointer up, or click.
6. Confirm the composer shows a cropped screenshot without either DevMark toolbar, plus the selected selector.
7. Save two notes and confirm each screenshot appears under Downloads/DevMark/<page-host>/, numbered markers appear, and two review cards are shown.
8. Expand JSON exported context and inspect the image device path, page path, selector, sanitized DOM snippet, styles, and coordinates.
9. Select an area containing an input with a typed value and confirm the screenshot paints an opaque privacy mask over it and the exported context omits the value.
10. Confirm Copy report contains an Image path for every saved screenshot, then verify Download JSON contains the same path but not an embedded screenshot data URL.
11. Drag the compact toolbar and the annotation panel to different corners, resize the window, and confirm both remain inside the viewport.
12. Choose Clear, confirm the warning, and verify the cards, markers, badge count, and next annotation number reset while previously downloaded images remain on disk.
13. Press Escape while selecting and confirm normal page interaction returns; then choose Annotate to resume.
14. Try DevMark on chrome://extensions and confirm it reports that protected browser pages cannot be annotated or emulated.

Manual MCP checklist

After installing the companion and reloading DevMark:

1. Confirm browser_status reports the bridge offline before the popup grants access; MCP cannot enable access itself.
2. Enable MCP from the popup and confirm the red badge, Arc debugging warning, bridge status, and attached-tab count.
3. Open another normal tab and confirm it receives an attached sessionId without another prompt.
4. Capture a DOM/accessibility snapshot, a console message and exception, request metadata/body, cookies/storage, and viewport/full-page/node screenshots.
5. Apply browser_device_set with 4K and phone presets, confirm native screenshot dimensions and device metadata, then use browser_device_clear and confirm reset.verified is true. A non-100% page zoom can conservatively produce verified: false with surfaceMatched: false; reset page zoom before treating that metadata as a failed metrics reset.
6. Exercise click, hover, type, key press, scroll, wait, reload, navigation, and JavaScript evaluation on a disposable development page.
7. Confirm iframe/worker activity appears and that a new top-level navigation invalidates old node references.
8. Open DevTools and confirm DevMark reports debugger detachment instead of silently repeating a mutating action.
9. Confirm incognito and protected browser pages are rejected.
10. Select Stop and confirm attachments, buffers, and temporary artifacts disappear while saved annotation images remain.
11. Restart Arc and confirm MCP access is disabled again.

Companion unit tests are available with cd companion && npm test. They are not run automatically by the installer.