DEV Community

Cover image for File System Access API in a Chrome extension: 8 things that broke
Artyom Shimanski
Artyom Shimanski

Posted on

File System Access API in a Chrome extension: 8 things that broke

I built a Chrome extension that saves ChatGPT, Claude, Gemini and other AI chats as Markdown files in a folder on your computer. You pick a folder (often an Obsidian vault), and every chat becomes one .md file that stays up to date as you keep talking. It's called Chat to Markdown.

The idea fits in one sentence. Making a Manifest V3 extension write to a real folder, reliably, for weeks at a time, took most of the work. This is the list I wish I'd had at the start: what broke, why, and the code that fixed it.

Everything below is about the file side. It applies to any extension that writes to disk, whatever it saves.

Why files and not a database

I want my chats next to my notes, in a format that grep, git and Obsidian already understand, and that will still open in 20 years. chrome.storage or IndexedDB would have been easier, but they lock the data inside the extension. Uninstall it and the chats are gone.

The File System Access API makes the other choice possible. showDirectoryPicker() gives you a handle to a folder the user picked, and you can create, read and write files inside it. Chrome has it. Firefox and Safari don't, so the extension is Chrome only.

The short version:

  1. The service worker can't do the file work. An offscreen document does.
  2. A folder handle can't go in chrome.storage. It goes in IndexedDB.
  3. Permission can disappear after a restart, and only a click brings it back.
  4. The picker refuses some folders, and Brave turns it off.
  5. Chrome rejects file names your OS would accept.
  6. Users edit the files. Only rewrite the part you own.
  7. Obsidian reads more into your Markdown than you wrote.
  8. Version history doesn't need git.

1. Writing files from an MV3 service worker: use an offscreen document

In Manifest V3 the background is a service worker. It has no window, so no folder picker, and in my testing the permission methods on a stored handle weren't usable there either. But the service worker is exactly the part that runs the scheduled sync and needs to write files.

The fix is an offscreen document that acts as a small file server. The worker sends it messages, and it does the reading and writing.

const OFFSCREEN_PATH = 'src/offscreen/offscreen.html';
let creating = null;

async function ensureOffscreen() {
  const contexts = await chrome.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [chrome.runtime.getURL(OFFSCREEN_PATH)],
  });
  if (contexts.length) return;
  creating ??= chrome.offscreen
    .createDocument({
      url: OFFSCREEN_PATH,
      reasons: ['BLOBS'],
      justification: 'Write exported chats as Markdown files to the folder the user selected.',
    })
    .finally(() => { creating = null; });
  await creating;
}

const WRITE_TIMEOUT_MS = 90_000;

async function call(type, payload = {}) {
  await ensureOffscreen();
  let clock;
  const gaveUp = new Promise((resolve) => {
    clock = setTimeout(() => resolve(null), WRITE_TIMEOUT_MS);
  });
  const res = await Promise.race([
    chrome.runtime.sendMessage({ target: 'offscreen', type, ...payload }),
    gaveUp,
  ]).finally(() => clearTimeout(clock));
  if (!res) throw new FolderError('unavailable', 'Couldn’t write the file. Try again.');
  if (!res.ok) throw new FolderError(res.code ?? 'error', res.error);
  return res.result;
}
Enter fullscreen mode Exit fullscreen mode

Four details that each cost me a bug:

  • There's no "file system" reason in the offscreen API. BLOBS is the closest fit, and the Web Store accepted it with an honest justification.
  • Share the creation promise. Two saves starting at once would both call createDocument(), and the second one throws because the document already exists.
  • Time out every call. If the offscreen page dies in the middle of a write, sendMessage can just hang, and every save after it waits in line forever. After 90 seconds the call fails with a message a person can act on.
  • Messages are JSON. Images and files from a chat travel as base64, built in 32 KB chunks. Spreading a whole 5 MB Uint8Array into String.fromCharCode(...bytes) overflows the call stack.

The offscreen side is just a table of operations:

import * as fs from '../storage/fs-ops.js';

const operations = {
  check: () => fs.check(),
  read: ({ path }) => fs.read(path),
  write: ({ path, content }) => fs.write(path, content),
  writeBytes: ({ path, data }) => fs.writeBytes(path, data),
  exists: ({ path }) => fs.exists(path),
  remove: ({ path }) => fs.remove(path),
  list: ({ path }) => fs.list(path),
};

chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
  if (msg?.target !== 'offscreen') return false;
  const op = operations[msg.type];
  if (!op) return false;
  Promise.resolve()
    .then(() => op(msg))
    .then(
      (result) => sendResponse({ ok: true, result }),
      (err) => sendResponse({ ok: false, code: err.code ?? err.name, error: err.message }),
    );
  return true; // keeps the channel open for the async answer
});
Enter fullscreen mode Exit fullscreen mode

Extension pages (the reader, the import page) can use the handle directly, without the round trip. So there are two objects with the same shape, workerIo and pageIo, and the save code takes either one. The same function saves a chat from a background sync and from an import running in a tab.

2. Storing a FileSystemDirectoryHandle: IndexedDB, not chrome.storage

The user picks a folder once. You need that handle again tomorrow, in a different context, after the service worker has been killed and restarted a hundred times.

chrome.storage only holds JSON, and a handle isn't JSON. IndexedDB uses structured cloning, which handles support. Every page of an extension shares one origin (chrome-extension://<id>), so the welcome page that saves the handle and the offscreen document that uses it see the same database.

function openDb() {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open('chattomarkdown', 1);
    req.onupgradeneeded = () => req.result.createObjectStore('handles');
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

async function run(mode, op) {
  const db = await openDb();
  return new Promise((resolve, reject) => {
    const tx = db.transaction('handles', mode);
    const req = op(tx.objectStore('handles'));
    tx.oncomplete = () => { db.close(); resolve(req.result); };
    tx.onerror = () => { db.close(); reject(tx.error); };
  });
}

export const loadRootHandle = () => run('readonly', (s) => s.get('root'));
export const saveRootHandle = (h) => run('readwrite', (s) => s.put(h, 'root'));
Enter fullscreen mode Exit fullscreen mode

3. Keeping folder permission after a Chrome restart

For years, permission to a picked folder lasted only until the browser closed. Chrome 122 added persistent permissions: the prompt now offers Allow on every visit. If the user picks Allow this time instead, then after a restart queryPermission() returns 'prompt'.

The catch: requestPermission() needs a user gesture. A background sync at 3 a.m. can't ask. So I stopped treating lost permission as an error and gave it its own state:

  • Before each sync, check the permission. If it isn't 'granted', skip the sync instead of failing halfway.
  • Put a red ! on the toolbar icon so the user notices.
  • Show an Allow access button in the popup and in Settings. Its click handler is the gesture:
$('#reconnect').addEventListener('click', async () => {
  const handle = await loadRootHandle();
  if (handle && (await handle.requestPermission({ mode: 'readwrite' })) === 'granted') {
    toast('Access restored');
    syncNow();
  }
});
Enter fullscreen mode Exit fullscreen mode

The setup screen also tells people to choose Allow on every visit. That one line of text prevents most of these cases.

4. showDirectoryPicker errors: when the picker says no

Two cases left users looking at a button that did nothing.

Chrome refuses some folders. Documents, Desktop and Downloads themselves can't be picked ("contains system files"), only folders inside them. My picker opened in Documents, so that was the first thing people tried. Chrome shows its own dialog, and when the user closes it your code gets an AbortError, the same as a plain cancel. Now a cancel shows a note that explains this and suggests clicking New folder in the picker.

Brave ships with the API turned off. window.showDirectoryPicker is simply undefined, so the click threw "is not a function". Now the extension checks for it before showing the button and, in Brave, links to the flag that turns it on.

export const canPickFolder = () => typeof window.showDirectoryPicker === 'function';
const isBrave = () => Boolean(navigator.brave);

export async function pickFolder() {
  if (!canPickFolder()) throw Object.assign(new Error('Folder access is off'), { name: 'FolderUnsupported' });
  // `id` makes the picker remember where it was last time, per id.
  return window.showDirectoryPicker({ id: 'chattomarkdown', mode: 'readwrite', startIn: 'documents' });
}
Enter fullscreen mode Exit fullscreen mode

5. The "Name is not allowed" error

Chat titles become file names, and chat titles contain anything. Chrome's file system access is stricter than macOS or Windows, and it fails with Name is not allowed on names your OS would take. These all came from real chats:

  • Emoji built with a zero-width joiner, like 👨‍💻. The joiner is a format character (\p{Cf}), and Chrome rejects it.
  • A ~ anywhere in the name.
  • Half an emoji. Cut a title at 80 characters and you can split a surrogate pair.
  • Windows device names, like CON or nul.md. Chrome refuses them, and a vault made on a Mac often syncs to a Windows PC later anyway.
  • Attachments ending in .lnk or .local. These are saved as .bin now.
  • Long names in Chinese, Japanese or Korean. Most file systems allow 255 bytes, not 255 characters. 120 characters of Japanese is 360 bytes of UTF-8.
const ILLEGAL = /[\\/:*?"<>|#^[\]~\p{Cc}]/gu;
const INVISIBLE = /[\p{Cf}\p{Cs}\p{Noncharacter_Code_Point}]/gu;
const RESERVED = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9]|clock\$)(?:\.|$)|^(?:desktop\.ini|thumbs\.db)$/i;

export function cleanText(value) {
  return String(value ?? '')
    .replace(INVISIBLE, '')
    .replace(ILLEGAL, ' ')
    .replace(/\s+/g, ' ')
    .trim()
    .replace(/^\.+/, '')
    .replace(/[. ]+$/, '');
}

const utf8 = new TextEncoder();

// At most `max` UTF-16 units (never half an emoji) and `maxBytes` of UTF-8.
export function clip(text, max, maxBytes = 240) {
  let out = text.length <= max ? text : text.slice(0, max).replace(/[\uD800-\uDBFF]$/, '');
  if (utf8.encode(out).length > maxBytes) {
    const chars = [...out];
    while (chars.length && utf8.encode(chars.join('')).length > maxBytes) chars.pop();
    out = chars.join('');
  }
  return out === text ? text : out.replace(/[. ]+$/, '');
}
Enter fullscreen mode Exit fullscreen mode

#, ^, [ and ] are in that list for a different reason: they break Obsidian links. Every bad title I find goes into the unit tests as a fixture.

6. People edit the files: only rewrite what you own

Once a chat is a note, people treat it like one. They add a summary at the top, a status: read property, a link to a project note. Then they continue the chat, and the next sync must update the file without wiping any of that.

The generated part of each file sits between two HTML comments. They're invisible in Obsidian's reading view and in most Markdown previews:

---
title: "Lisbon food trip"
source: "ChatGPT"
tags: [ai-chat, chatgpt]
status: read
---

My summary: Day 2 is the one to book ahead.

<!-- chattomarkdown:start · updated automatically on sync; write your own notes above or below this block -->
# Lisbon food trip

## You

Plan 3 days of eating in Lisbon.

## ChatGPT

Day 1 starts at Time Out Market.
<!-- chattomarkdown:end -->
Enter fullscreen mode Exit fullscreen mode

On every sync, only the text between the markers is replaced. The frontmatter is merged key by key: keys the extension owns (title, url, updated and so on) are rewritten, tags is written only when the file is created, and keys the user added are never touched. If someone deletes the markers, the file is theirs, and the extension never writes to it again.

export function mergeDocument(existing, { fields, body }) {
  const block = buildBlock(body);
  if (existing == null) {
    return { status: 'created', content: `${serializeFrontmatter(fields)}\n${block}\n` };
  }
  const text = existing.replace(/\r\n/g, '\n');
  const { entries, rest } = parseFrontmatter(text);
  const start = rest.indexOf(START_MARK);
  const end = rest.indexOf(END_MARK);
  if (start === -1 || end === -1 || end < start) return { status: 'detached', content: null };

  const content =
    mergeFrontmatter(entries, fields) + rest.slice(0, start) + block + rest.slice(end + END_MARK.length);
  return { status: content === text ? 'unchanged' : 'updated', content };
}
Enter fullscreen mode Exit fullscreen mode

The bug I didn't see coming: someone pasted a saved note into a new chat. Now the chat text itself contained the markers. On the next sync, indexOf found the pasted end marker first, the block ended early, and the file grew on every sync. The fix is a zero-width space inside any marker that appears in the chat text, so it still reads the same but never matches:

const MARK_IN_BODY = /<!--(\s*chattomarkdown:(?:start|end))/g;
const buildBlock = (body) =>
  `${START_COMMENT}\n${body.trim().replace(MARK_IN_BODY, '<!--\u200b$1')}\n${END_MARK}`;
Enter fullscreen mode Exit fullscreen mode

7. Obsidian reads more into your Markdown than you wrote

Valid Markdown isn't enough. I copied a real vault with 677 saved chats and opened it in Obsidian 1.15. Here's what I found:

  • 136 tags came from chat text. #fyp from a drafted social post, #0B1017 from a stylesheet. Obsidian turns any #word into a tag, so the tag pane filled with junk. Now #word is saved as \#word, except in code, links and HTML. A heading like "Learning C#" keeps its #.
  • 965 headings in answers sat at the same level as the speakers. A ## Summary inside a reply looked like a new turn in the outline. Now every heading in a message is pushed down so it starts at ###, and ## You and ## ChatGPT are the only level-2 headings. The outline follows the chat turn by turn.
  • Dollar signs became math. A question about nginx with $host$request_uri rendered as a formula. In the user's own messages, dollars that would pair up into a formula are escaped unless they hold one.
  • Dates were plain text. created and updated didn't sort or filter as dates, because Obsidian reads property types from .obsidian/types.json.

That last fix needs care, because types.json is the user's file too. The extension adds only the types that are missing, never changes one that's already set, and leaves a file it can't parse alone:

const types = data.types ?? {};
const missing = keys.filter((key) => !Object.hasOwn(types, key));
if (!missing.length) return 'unchanged';
const next = { ...data, types: { ...types, ...Object.fromEntries(missing.map((k) => [k, 'datetime'])) } };
await io.write('.obsidian/types.json', JSON.stringify(next, null, 2)); // two spaces, as Obsidian writes it
Enter fullscreen mode Exit fullscreen mode

If you write Markdown for Obsidian users, test in a real vault with real, messy data. Sample files hide all of these.

8. Version history without git

Chats change. People continue them, regenerate answers, rename them, delete them on the site. I wanted a git-style log for each chat without asking anyone to install git.

Each chat gets one JSON file in a hidden folder: .chattomarkdown/history/<service>/<id>.json. Obsidian and Finder don't show dot folders, and keying by chat id means renaming or moving the note doesn't break its history.

The file holds the newest text in full, plus, for each older version, a patch that turns it back into the version before. That's the same trick as RCS's reverse deltas. It's cheap here because a continued chat only changes at the end:

  • The diff is Myers' O(ND) algorithm, run only on the middle part after the common start and end are set aside. For a continued chat that middle part is tiny.
  • Lines are mapped to small integers first, so comparing them is cheap.
  • History stops at 100 versions or 4 million characters, whichever comes first.
  • If the user edited the file between two syncs, their edit is kept as its own "edited" version, so the next sync can't silently erase it from history.

One rule above all the others: history must never stop a chat from saving. The function that records a change catches everything. A broken history file costs you a log entry. A failed save costs you a chat.

What I'd tell someone starting an extension that writes files

  • Decide early which part of each file you own, and never touch the rest.
  • Treat permission as a state that can change at any time, with UI for each state, not an error path.
  • Keep the worst file names you can find as test fixtures. Emoji, CJK, Windows device names, a lone ~.
  • Test against the app people will open the files in, with a copy of real data.
  • Put a timeout on anything that crosses a process boundary.

If you want your own AI chats as files, Chat to Markdown is free for 10 chats, with no account. The full file format is documented line by line, and I wrote up how I organise hundreds of AI chats in Obsidian with properties and Dataview.

How do you keep your AI chats today? Exports, copy and paste, or not at all? And if you've shipped an extension that writes to disk, I'd like to hear what broke for you. I'll answer questions about the offscreen setup in the comments.

Top comments (2)

Collapse
 
yana_shimanskaya profile image
Yana Shimanskaya •

Great article, saved it!

Collapse
 
ashimanski profile image
Artyom Shimanski •

Thanks Yana!