Skip to content

feat: add an agent skill for terminal screenshots 📸 - #3

Open
zirkelc wants to merge 3 commits into
colinhacks:mainfrom
zirkelc:feat/agent-skill
Open

zirkelc wants to merge 3 commits into
colinhacks:mainfrom
zirkelc:feat/agent-skill

Conversation

@zirkelc

@zirkelc zirkelc commented Sep 28, 2026 •

Copy link
Copy Markdown

What

A skill in skills/boron/ that lets any coding agent (Claude Code, Codex, Cursor, …) make a Boron image from terminal output or code, save it as PNG/SVG/JPEG/WebP, and hand back a link that reopens the picture in the editor.

It is agent-agnostic (plain SKILL.md, no tool-specific calls) and needs no npm install: only Node 22+ and whatever browser tool the agent already has (a Chrome extension or DevTools MCP server, Playwright, Puppeteer, …). It needs no change to the app.

How it works

File Does
SKILL.md The workflow: get colored output (FORCE_COLOR, script), use the defaults unless the user says otherwise and tell them which were used, make the link, save, report file + link
scripts/link.mjs Reads ANSI on stdin, writes a v1 share link (content=u<base64url> plus the named params). Moves to the fragment past 8000 chars, like buildShareUrl. Omitted settings resolve through V1_DEFAULTS. --columns defaults to auto: the longest visible line (escape codes stripped, tabs expanded, one cell per code point like wrapRenderLines), clamped to 80–400
scripts/capture.js One function expression evaluated in the page. Waits until the Save button is enabled (fonts + layout ready), catches the Blob that renderBlob hands to URL.createObjectURL, suppresses the anchor click, returns { dataUrl, link }

The agent's browser tool opens the link, evaluates capture.js and decodes the data URL into the file. If the agent has no browser tool, the skill hands the user the link and tells them to click Save.

One finding: syntax in a link does not color the content

A link's content is taken literally, and syntax=typescript only decides what the next paste does. So a link made from plain code arrives uncolored. capture.js takes a language option and drives the Syntax select (auto first, then the language, so a link that already names it still recolors). The address bar is then rewritten with the colored ANSI, and that is the link the skill reports. Might be worth deciding whether a link naming a language should highlight on open.

Why not html-to-image (the ray.so approach)

The ray.so skill injects html-to-image and rasterizes the preview DOM. That is correct for ray.so, whose DOM is the image. For Boron it is the wrong source:

  1. It captures the preview, which is the one renderer allowed to drift. Per wiki/architecture.md, the live contenteditable flows glyphs with the browser instead of placing them at measured x, and its frame, chrome, traffic lights and shadow are a second description of what paint.ts emits. The Save button's output is what users get, so that is what an agent should get.
  2. Fonts would silently fall back. Boron Mono is loaded through the FontFace API, not stylesheet @font-face. html-to-image only embeds fonts it finds in stylesheets, and the foreignObject image cannot see document fonts, so the output would be in a generic mono unless the skill rebuilt fontEmbedCSS itself.
  3. The node needs surgery first. .frame carries transform: scale(previewScale), and contains the resize handles, the caret/selection and the box-selection overlay. Each would have to be undone or filtered out, and each is a new coupling to the DOM.
  4. SVG would not be the real SVG. html-to-image's SVG is HTML wrapped in foreignObject, not the vector export from svg.ts with embedded, subset fonts. WebP/JPEG need an extra canvas pass.
  5. A third-party script from a CDN at capture time, with its own version drift and a network dependency.

Clicking the real button avoids all five: the pixels come from renderBlob, exactly as a person would get them.

Suggestion: a small export hook (would make this robust)

The current capture couples to three UI details: the Save … button text, the split-button class names, and the Syntax highlighting select label. Scale is fixed at 2×. A tiny, documented hook would remove all of it:

// e.g. in App.tsx, once `scene` exists
window.boron = {
  /** Resolves once fonts and layout are ready. */
  ready: Promise<void>,
  /** Same pixels as the Save button. */
  export(options?: { format?: ImageFormat; scale?: number; language?: LanguageId }): Promise<Blob>,
};
  • capture.js shrinks to await window.boron.ready; return window.boron.export({ format }), and falls back to the button click on older builds.
  • Arbitrary scale (1×, 3×, 4×) for free, since renderBlob already takes it.
  • It is also the natural seam for the server-side card in wiki/og-images.md.

Happy to follow up with that as a separate PR if you want it.

Tested

Against live boron.sh, headless Chrome on macOS, with capture.js evaluated through Playwright and through agent-browser:

  • PNG, default settings, colored git log --graph output
  • PNG with language: "typescript" and --aspect og (syntax colors present)
  • WebP from the returned link (colors survive the round trip)
  • JPEG with --backdrop none --title-bar off
  • A fresh agent with no prior context, given only SKILL.md, produced a correct git log --graph image on the first try
  • An unknown format fails with an error that lists the valid values

skills/boron lets any coding agent turn terminal output or code into a
Boron image without a person at the keyboard:

- link.mjs writes a share link from ANSI on stdin (wire v1, `u` content)
- capture.js runs in the page, clicks the real Save button and returns
  the exported Blob plus a link to the picture as exported
- save.mjs drives an installed Chromium-based browser over the DevTools
  protocol with Node built-ins, so nothing has to be installed
@vercel

vercel Bot commented Sep 28, 2026

Copy link
Copy Markdown

@zirkelc is attempting to deploy a commit to the colinhacks Team on Vercel.

A member of the Team first needs to authorize it.

@zirkelc
zirkelc marked this pull request as ready for review September 28, 2026 16:12
colinhacks added a commit that referenced this pull request Nov 16, 2026
The wiki still said `highlight` was the one field no link carries and that
`fromWire` returns `ansi`. Neither has been true since `syntax` joined the v1
wire format. It travels, it paints nothing, and a link never re-colours on
open — which a hand-written link trips on (#3 did), so the
reason is written down beside the behaviour.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant