File Sync

Turning File Sync on and off

✨ Agent: File Sync: Toggle in the command palette switches File Sync. A toast says File Sync enabled or File Sync disabled, and the change applies at once to a running share:

• Off stops the session and watches the folder without looking into subfolders.
• On prepares a session, honouring Share ← Folder. That may show the Files differ dialog. Then it starts and watches the folder recursively. Cancel in the dialog unshares. Any other error leaves the share running without File Sync and shows a warning; the stored preference stays on.

The File Sync module is loaded when File Sync starts: at share start, or when you toggle it on. If the module cannot load at share start, the share fails; turn File Sync off to share without it.

Example: exports and a worker

<style o:=.css>
  main { padding: 1rem }
</style>
<template o:=about.html>
  <h1>About</h1>
</template>
<img o:=dot.png src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==">
<main>Hi</main>
<script type=worker edge>
  export default { fetch: () => new Response('hi') }
</script>

With the route new, the work folder <root>/new/ gets these managed files, besides the agent files. A ⏎ marks the single final newline.

Editing .css on disk changes only the inner text of the <style>. Writing </style> into .css is refused, with textContent cannot be stored without changing the surrounding HTML. Writing </template> into about.html is refused in the same way, with innerHTML cannot be stored …. The src of the image must be quoted, because the base64 text contains =.

Rules

A file's name is the value of o:, relative to the work folder. A / in it creates subfolders: o:=css/site.css becomes css/site.css. The editor's hints, however, flag names that contain /, and names without a ., as invalid. Prefer flat names with a dot, such as site.css.

File Sync refuses a name, and shows the warning <name>: unsafe or reserved Share path ((unnamed export): … for an empty name), when it:

• is empty;
• contains \, a control character, :, *, ?, ", <, > or |;
• has an empty, . or .. path segment, so a leading /, a trailing / and // are refused;
• has a reserved name as its first path segment: 📄.html, 📄.sel, 📜.json, 📸.png, 📸.mp4, io.eval.js, io.eval.json, o.eval.js, o.eval.json, AGENTS.md or CLAUDE.md;
• is .agents or .claude, or lies inside them;
• has any path segment that begins with 📍.

If one declared name is a path prefix of another, such as lib and lib/x.js, both are skipped with <name>: a declared file conflicts with this directory path. Each diagnostic appears once per session, as a warning toast.

Name checks are case-sensitive: agents.md and Claude.md are accepted, and a.js and A.js are separate entries. Windows and default macOS volumes ignore case, so on them such names can collide with AGENTS.md or CLAUDE.md, or with each other. Choose names that differ by more than case.

Duplicate names

When several elements declare the same name, every occurrence gets a number after the full name, in document order: <name>.1, <name>.2 and so on. No unsuffixed file is written. Two <style o:=.css> give .css.1 and .css.2, and two workers give ⚙️.js.1 and ⚙️.js.2. Numbers that literal declarations already use are skipped: a.js, a.js and a.js.1 become a.js.2, a.js.3 and a.js.1.

<style o:=.css>h1 { color: red }</style>
<style o:=.css>h2 { color: blue }</style>

File Sync writes .css.1 (h1 { color: red }⏎) and .css.2 (h2 { color: blue }⏎). The output and RTEdge.net, by contrast, serve one /.css that joins both texts with a newline.

Final newlines and framing

A text file is the element's content plus exactly one final newline. File Sync normalizes the content to LF and hides the whitespace that frames it:

• A first line that holds only whitespace moves to a hidden prefix. A last line that holds only whitespace, after a newline, moves to a hidden suffix, together with the content's trailing newlines.
• Only one leading blank line is hidden. Extra blank lines stay in the file.
• When File Sync writes back, it puts the prefix and the suffix in place again, so the padding of the element and the indentation of its closing tag survive.
• A content that is only a newline frame gives a file with a single newline. Writing an empty file restores the original whitespace.

For example, the content "\n a { color: red }\n " gives the file " a { color: red }\n", and a file that holds " a { color: blue }\n\n\n" becomes the content "\n a { color: blue }\n ".

Comparisons ignore final newlines. Disk content is decoded as UTF-8, CRLF and CR become LF, and all trailing \r, \n, U+0085, U+2028 and U+2029 are trimmed before File Sync compares. Newline-only differences never import and never conflict. Trailing spaces and tabs are significant.

• 📄.html is written without a final newline, but it is not rewritten for newline-only differences, so a final newline that an agent adds may stay on disk. Text exports, including ⚙️.js, always get exactly one final newline. Binary image files hold the raw bytes.
• Each import into the editor is one undo step, and it leaves the input without final newlines. Typing and Undo are not trimmed.
• You cannot change an element's trailing newlines from an export file, because the end-of-file newline is not part of the content. Edit 📄.html for that.
• A UTF-8 byte-order mark is not stripped, so a BOM written by another editor would enter the element as a U+FEFF character. Write UTF-8 without a BOM.

Binary images

An <img> that has an o: name, no o:content and a src that starts with data: syncs as the raw decoded bytes, for base64 and for percent-encoded data URLs. Writing the file re-encodes the image as ;base64, and keeps the original media type: writing a JPEG into an image typed image/png keeps image/png. The bytes must read back unchanged, or the write fails with Binary value cannot be stored in this element. The other errors are Expected binary file contents and Invalid data URL, which may add escape or byte.

A pasted image becomes an exported file like this. After you paste a screenshot into the editor, it holds <img src="data:image/webp;base64,…">. Add a name whose extension matches the chosen format:

<img o:=logo.webp src="data:image/webp;base64,UklGR…" alt=Logo>

The share then contains logo.webp as raw bytes. Replacing the file writes a new base64 data URL into src, with the original media type and the existing quote style. Keep src quoted: base64 often ends in = padding, and an unquoted value that contains = is quoted on write-back anyway. See Pasted files for how pasting works.

The o:content property

• textContent on an element other than a script or style: the file holds the decoded text, and writing escapes & and <. On <template>, textContent is read-only (template.textContent has no persistent serialized content).
• value on a <textarea>: the file is the current value. Writing escapes the text, and keeps or adds the leading newline that HTML drops after <textarea>.
• value on an <input>: the file is the value. Writing edits the value attribute, and adds value="…" when it is missing. A quoted value keeps its quotes. An unquoted value stays unquoted when that is safe: non-empty, with no whitespace, quotes, backtick, =, < or >.
• Any other property is writable only when it is a scalar (string, number or boolean) with a setter somewhere on its prototype chain, and when the new value persists in HTML. Otherwise the file is read-only, with <prop> is not a persistent scalar property or <prop> is read-only or has no persistent setter. Writes can fail with <prop> does not persist in HTML, <prop> cannot represent that value or, for a boolean, Expected true or false.

<textarea o:=notes.txt o:content=value>
Remember the milk
</textarea>
<input o:=status.txt o:content=value value=draft>
<p o:=quote.txt o:content=textContent>a &lt; b</p>

The files are notes.txt = Remember the milk⏎, status.txt = draft⏎ and quote.txt = a < b⏎. Writing final to status.txt turns the attribute into value=final. Writing x & y to quote.txt stores x & y.

Element files and protected attributes

A file that holds an element's own source (outerHTML, the default for most elements) contains the exact authored source. The version that is served is a DOM serialization with the platform attributes (o:, io:, edge:, h:, worker:) removed, so file and served body can differ in formatting and content. When File Sync writes such a file back:

• The file must contain exactly one element. Whitespace-only text around it is allowed, comments are not. Otherwise the error is outerHTML requires one element.
• Protected attributes are forced back to their original values: added ones are removed, and changed or removed ones are restored. Only then is the element serialized by the DOM. Without such changes, the text you wrote is used verbatim.

Protected attributes are all attributes whose names start with o:, h:, worker: or io:. Worker scripts also protect type, edge and fetch. Other attributes, such as edge:redact, edge:remove, copy:redact, i: and class, are not protected.

Declarations are frozen while you edit files. After every import, the set of [o:] elements and workers, their o: values and their protected attributes must be unchanged. Otherwise the import fails with Content edits must preserve export and worker declarations. Writing a nested <span o:=x.txt> into an outerHTML export is refused for this reason. To add, remove or rename an export or a worker, edit 📄.html.

Messages

At share start

With File Sync on, Share ← Folder off and the folder not emptied, a share compares the folder with the editor. These are conflicts:

• 📄.html, listed first, if it exists on disk and differs from the editor, ignoring final newlines;
• every declared file that exists on disk and differs.

Files that are missing on disk are not conflicts: File Sync generates them. How an existing 📄.html is treated depends on two settings:

With Shift (Empty) and Share ← Folder off, the folder is emptied first and File Sync skips the comparison, so no dialog appears. Share ← Folder lasts only until the page reloads.

The Files differ dialog

The dialog lists each conflicting file with a Compare button. Its footer has three buttons:

Write (primary)

Keeps the playground and overwrites the folder.

Read

Takes the folder: the disk 📄.html, if it exists, and the disk exports.

Cancel (focused by default)

Esc and the close button do the same. Cancel during startup cancels the share. Cancel during a running share unshares.

If the editor or the disk changes while the dialog is open, the check runs again.

Compare opens a read-only diff in a popup at diff.rt.ht, with the disk text labelled Disk and the playground text labelled Playground. Binary files, and files that are not valid UTF-8, appear as hex lines (an 8-digit offset and 16 bytes). Nothing goes into a URL and nothing is written back. If the popup is blocked, the message is The comparison popup was blocked. Allow popups and try Compare again. If it has not loaded after 30 seconds, it is The comparison did not finish loading. Try Compare again.

During a running share

• Editor-only changes are written to disk. Disk-only changes are imported.
• A file that changed on disk whose element also changed in the editor since the last sync is a conflict, and so is a 📄.html that changed on both sides. Both open Files differ. Read imports only the files that changed externally, and the disk 📄.html if it changed. Write keeps the editor and overwrites those files.
• If 📄.html and export files change on disk together while the editor is unchanged, the disk 📄.html is applied first and projected again. An export file whose element that change did not touch is then imported on top. An export file whose element it also changed becomes a conflict.
• Two files that map to overlapping source and are edited at the same time fail with Export edits overlap; edit one owning file at a time. During a share they are conflicts. Under Share ← Folder they stop startup.
• Adding an o: export in the editor whose file already exists on disk with different content opens Files differ.