fix(studio): safe markdown-folder persistence that follows outside edits

[tomasz-zajac-oss]

Makes models stored as a folder of Markdown files safe to use alongside other editors and git. Before this, Studio could silently lose descriptions, delete files it didn't write, and overwrite edits made outside it.

Data-loss fixes

• Descriptions lost after a rename or move. Descriptions of folder models load lazily. An element never opened in the panel lost its description on the second save after a rename, a move, or its first child, because its body path went stale. Body paths now follow each write.
• Deleting files Studio didn't write. Pruning removed every top-level .json (e.g. package.json) and anything under nodes/ (e.g. a hand-written README.md). Now only the manifest, the known sidecars and node files with id/type frontmatter are ever pruned. "Save as folder…" asks before writing into a folder that has other files but no model.
• Overlapping saves. Two saves overlapping (slow disk, large model) each pruned the other's files, so a renamed element could lose both its old and its new file. Disk saves now run one at a time per document and collapse into the newest state. localStorage saves stay synchronous, so the page-hide flush still works.
• Load landing in the wrong document. A slow load that finished after a document switch landed in the new document, and autosave then overwrote it. Loads are now sequenced. An edit still in the 400 ms debounce is saved to the document being left.

Outside edits

• MdFolderSession (packages/common/src/formats/mdFolderSync.ts, platform-free) remembers each model file's content and stamp (mtime + size) as last read or written:
  • it writes only files that changed;
  • it refuses to write if the folder changed on disk since the last read;
  • poll() reports such changes.
• Electron: one session per folder in the main process, polled every second, same as the existing --file watcher, because native fs events are unreliable on external volumes. New watchFolder / onFolderChanged host capabilities.
• Web: one session per directory handle, polled every 2 s.
• Autosave: watches the active folder document and reloads it on an outside edit, keeping the open view and selection. The disk wins: an in-app edit not yet saved is dropped by the reload.
• Only model files are read, so a folder inside a repo no longer walks node_modules. Folder writes can't leave the model folder.

Tests

• Unit: session behaviour, including on a real temp directory; the regressions above; watching and reload. 6 of the 8 regression tests in mdFolderSafety.test.ts fail on the old code; the other 2 exercise logic in @radical/common that wasn't reverted.
• E2E (apps/e2e/tests/studio/folders.spec.ts), 6 scenarios. The directory picker returns an OPFS directory that the test also edits directly, standing in for another editor. Turning off the rename fix or the watcher fails exactly the matching scenario.
• These specs run in a persistent browser profile. Chromium crashes the whole browser when an off-the-record page (Playwright's default) reads a stored directory handle back from IndexedDB.

npm test, npm run typecheck and the full e2e suite pass locally (e2e: 51 passed; the 4 known-issues tests are test.fail as before). The Electron build bundles the new main-process code. Not tried by hand in the desktop app.

Still open

Listed in docs/IMPROVEMENTS.md under "Markdown-folder persistence (review 2026-09-30)", among them:

• opening a folder still rewrites it (normalisation);
• no atomic writes or flush on quit;
• save failures are silent;
• disk-wins with no merge;
• a folder or file model reloads onto the full canvas, ignoring the view in a deep link;
• possible Chrome Incognito crash in folder mode (not checked).

🤖 Generated with Claude Code