Agent files

Exact names

The emoji in file names are part of the names. Agents have to write them exactly.

How the playground reacts to changes

One FileSystemObserver watches the work folder. It looks into subfolders only while File Sync is on, and it acts only on top-level names, using the latest change per name:

While File Sync is on, *.crswap, *.swp and *.tmp files cause no toast. Every file that the playground reads or writes shows a small transfer toast, except 📄.sel, the 📍 files, reads of eval requests and the files of the diagnostics command. Writes while a share starts are silent too.

📄.html

📄.html holds the editor's text as UTF-8 with LF line endings. It is the file to change when you want to change the page.

• File Sync on (the default): the file is live in both directions. Every editor change is published to disk with its final newlines trimmed, so the file has no trailing newline. Changes on disk are applied to the editor as minimal edits between undo stops. Imports ignore final-newline differences; see File Sync.
• File Sync off: the text is written exactly. Disk to editor stays live. Editor to disk happens only at share start and when 💾 Save: 📄.html runs.

Two commands help while a folder is shared: 💾 Save: 📄.html (Alt+B / ⌥+B) and 💾 Load: 📄.html (Alt+L / ⌥+L), both while the editor has focus. See Saving and loading. When the agent and the editor both change the file between two syncs, a Files differ dialog opens.

File Sync reads the file with a decoder that keeps a UTF-8 byte-order mark, so a BOM would enter the editor as a U+FEFF character. Write UTF-8 without a BOM.

📄.sel

📄.sel is a read-only view of the editor's selections. The playground rewrites it on every selection change, whether a person or code made it, for example sel = … from io.eval.js. It also rewrites it after every content change once the output is ready, and at share start. Edits to the file, and its deletion, are reverted: whenever the disk text differs from the last snapshot, the playground writes it back.

• Selections are sorted by their start. Selections whose line ranges touch or overlap merge into runs, and runs are separated by one blank line.
• Each line reads <line number><two spaces><selected text on that line>. Line numbers are right-aligned within a run, padded to the digits of that run's largest number.
• Segments on one line that do not touch are joined with ⋯ (U+22EF). Touching or overlapping segments merge.
• In a multi-line selection, the first line starts at the start column, middle lines are whole, and the last line ends before the end column.
• A cursor without a selection still lists its line, with empty text: a lone cursor on line 2 gives 2 and two spaces.
• The file has no trailing newline.

Take the selections [1,4,1,9], [1,10,1,15], [3,3,4,15], a cursor at line 10 and [11,4,11,5]. In a document whose line 1 is <p>Hello world</p>, whose lines 3 and 4 are <li>One</li> and <li>Two</li>, and whose line 11 is abcxyz, they give:

1  Hello⋯world

3  <li>One</li>
4    <li>Two</li>

10
11  x

Lines 10 and 11 are one run, because the lines are adjacent, so both numbers are padded to two digits. Line 10 is the line of the empty cursor.

Reading the log

Share start empties 📜.json and opens it with an exclusive writer. Chromium keeps the live data of such a writer in a swap file, 📜.json.crswap, and 📜.json stays empty until Unshare closes the writer and commits the data. So read both:

cat 📜.json*

While a share is active, 📜.json.crswap also marks a live share: a second window that shares the same route finds it and asks you to unshare the other one. Do not delete the console files. console.clear() in the output, and the console panel's clear button, truncate the log. The log has no rotation and no size cap: it grows until you clear it, share again or reload.

Where lines come from

• Output documents produce lines without a prefix: all code outside workers, including o.eval.js.
• The output's service worker produces lines for <script type=worker> code. Their first array element is "🛎️⚙️", for example {"log":["🛎️⚙️","hi"]}. The prefix is left out for the group methods and when the first argument contains %c.
• io.eval.js runs in the playground window, and its console calls never reach 📜.json.
• Uncaught errors in the output are logged for you: {"error":["<stack>"]}, where the stack has the output-origin URL prefixes, (eval at …, fragments and the characters @ ( ) removed, or the message when there is no stack. An unhandled rejection gives {"error":["Unhandled rejection", <reason>]}.

How arguments are recorded

Arguments are structured-cloned and then JSON-encoded:

If any argument cannot be cloned, such as a function, a DOM node or a symbol, the whole argument list is replaced by one JSON string, in which special values are marked with _RT_Encoded and _RTType, for example {"log":"[\"hello\",{\"_RT_Encoded\":true,\"_RT_Content\":{\"_RTType\":\"Function\",…}}]"}. A line's value is therefore either an array, or a string that has to be parsed again. This code reads both:

const lines = text.split('\n').filter(Boolean).map(l => Object.entries(JSON.parse(l))[0]).map(([method, a]) => ({ method, worker: (typeof a === 'string' ? JSON.parse(a) : a)[0] === '🛎️⚙️', args: typeof a === 'string' ? JSON.parse(a) : a }))

The file

The top-level fields of each JSON file, in the order they are written:

This is an element pin captured at 1×, abridged. The numbers are illustrative.

{
  "version": 1,
  "type": "rtcode.pin",
  "source": "output",
  "route": "new",
  "work": "new",
  "pinSchema": 5,
  "url": "<output document URL>",
  "title": "",
  "updatedAt": "2026-10-04T12:00:00.000Z",
  "index": 0,
  "total": 1,
  "id": "pin_mutrqtc0_a1b2c3",
  "image": { "file": "📍.0.png", "capture": { "requestedScale": 1, "appliedScale": 1, "width": 52, "height": 26 } },
  "pin": {
    "id": "pin_mutrqtc0_a1b2c3", "kind": "element", "selector": "span#badge", "label": "new", "tag": "span",
    "domPath": "html > body > main > span#badge",
    "rootPath": [ { "selector": "html > body > main > span#badge" } ],
    "rect": { "x": 24, "y": 120, "width": 52, "height": 26 },
    "viewport": { "width": 698, "height": 848, "scrollX": 0, "scrollY": 0, "devicePixelRatio": 1 },
    "url": "<output document URL>", "title": "", "createdAt": "…", "timestamp": "…",
    "comment": "Make this pill smaller", "innerText": "new", "outerHTML": "<span id=\"badge\">new</span>",
    "computedStyles": { "display": "block", "border-radius": "16px", "…": "…" }, "cssRules": [ { "selector": "#badge", "css": "…" } ],
    "autoTrack": true, "autoCapture": false, "linked": true
  }
}

The pin object

The pin object holds only the keys below. autoTrack and autoCapture are always present, and linked is present on element pins. The other fields appear only when the pin has them.

The capture object inside image tells how the PNG was made. On the direct path it is { requestedScale, appliedScale: 1, reason?: 'region', width, height }. On the enhanced path it is { requestedScale, appliedScale, origin, lift, unclip, settle, unclipped, clippedBy: [selector…], translate?: [x, y], background?, backgroundMode?, width, height }. width and height are the pixel size of the PNG. The two paths are explained in Pins.

Lifecycle

• Every save of the pins rewrites all current JSON files, and writes the current PNGs under their current index, so deleting pin 0 renumbers the rest. It deletes every 📍.<N>.json numbered beyond the current count, every 📍.<N>.png that belongs to no current or pending image, and the legacy 📍.json and 📍.png.
• Stopping an Output capture while a folder is shared deletes all pin PNGs, and rewrites the JSON files with "image": null.
• The playground ignores your edits to the 📍 files while it runs. It reads them only when a share starts: pins are loaded from disk when Share ← Folder is on, or when the page has no pins in memory. Otherwise the pins in memory overwrite the files. Loading sorts by the stored index, then by file number, and skips entries without a pin.id.
• To change pins, use o.pins from io.eval.js; see Pins from code and PinList.

Files pasted into the playground

While a folder is shared, pasting files writes them into the work folder. This happens when the focus is outside the editor's text, or when the clipboard holds no image files.

• Each file is written at the root of the work folder under its original name. A file with the same name is overwritten without asking. A toast reports how many files were pasted.
• A clipboard file named exactly image.png, which is typical for screenshots, is renamed 📋.🖼️.<stamp>.png. The stamp is the current time as an ISO 8601 string in UTC, with each : replaced by · (U+00B7), for example 📋.🖼️.2026-10-04T12·34·56.789Z.png. A paste uses one stamp, so several image.png files in one paste overwrite each other. There is no <N> index and no second copy.
• Other files keep their names.
• Dropped files are never written to the folder. Without a share, nothing is written and the normal paste goes ahead.

Images pasted into the editor

A paste with the editor's text focused, or a drop of image files onto the input panel, never creates a file. Each image becomes <img src="data:<type>;base64,…"> in the source instead. This needs the same browser support as Agent 📂 Share™, but not an active share.

• The playground decodes each image, draws it at its natural size, encodes it as PNG and as WebP in parallel, and keeps the smaller result. A toast per image, Image i or Image i / n, lists the sizes of the original, the PNG and the WebP, and the picked format.
• The limits apply to the total encoded size of all images in one paste or drop, before base64:
  • 2 MiB or less: inserted directly.
  • Over 2 MiB: a confirmation, Paste N image(s) inline? (Drop … for drops), with the OK button labelled Paste or Drop.
  • Over 10 MiB: refused, with the danger toast Inline image paste too large: N image(s).
• The tags are joined with newlines and inserted at every selection as one undo step. The caret lands right after <img in each tag, ready for alt=.

To turn such an image into a file, see Binary images.