fix(deepnote): prevent endless save loop and backslash accumulation in text blocks (#413)

Saving a .deepnote notebook containing text blocks (text-cell-*) entered an
endless save loop and progressively added backslashes to the text. Two
independent defects combined — one caused the corruption, the other made it
self-perpetuating.

Part 1 — Idempotent text round-trip (textBlockConverter.ts):
On open, text blocks render to markdown via createMarkdown, which
backslash-escapes a character class (including `\` itself). On save,
stripMarkdown removed the type prefix and trimmed but never unescaped, so each
save grew backslashes without bound. Add a module-scope unescapeMarkdown — the
exact inverse of the library's escapeMarkdown — applied after stripMarkdown at
the single choke point, restoring the round-trip invariant.

Part 2 — Self-write suppression in the file watcher (deepnoteFileChangeWatcher.ts):
Notebooks opened from the Deepnote sidebar carry a ?notebook=<id> query in their
URI, but fs events deliver the bare file URI, so the self-write markers (keyed on
the raw URI) never matched and the watcher's own saves re-entered the reload
pipeline. Add selfWriteKey(uri) (strips query + fragment) used by every
mark/consume/snapshot path, and replace the per-URI counter Map with a one-shot
Set so coalesced writes cannot leave stale residue that swallows a genuine
external change.

Tests: round-trip suite through the real @deepnote/blocks library (incl. a
literal-backslash tripwire, double-round-trip stability, todo checked, bullet
indent_level, whitespace trim); text-cell round-trip in the data converter; and
watcher query-URI consumption, coalesced-event and duplicate-event safety.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: tkislan

src/notebooks/deepnote/blocks.md

@@ -231,6 +231,12 @@ Simple: just moves the content between block and cell.
 Text blocks (headings, bullets, todos, etc.) use the `@deepnote/blocks` package to convert between plain text and markdown:
 
 ```typescript
+// Exact inverse of escapeMarkdown in @deepnote/blocks (identical character class),
+// since stripMarkdown only removes the type prefix and trims — it does not unescape.
+function unescapeMarkdown(text: string): string {
+    return text.replace(/\\([\\`*_{}[\]()#+\-.!|>])/g, '$1');
+}
+
 export class TextBlockConverter implements BlockConverter {
     protected static readonly textBlockTypes = [
         'text-cell-h1', 'text-cell-h2', 'text-cell-h3',
@@ -245,9 +251,10 @@ export class TextBlockConverter implements BlockConverter {
     }
 
     applyChangesToBlock(block: DeepnoteBlock, cell: NotebookCellData): void {
-        // Convert markdown back to plain text for Deepnote
+        // Convert markdown back to plain text for Deepnote.
+        // Reverse the escaping createMarkdown applied so the round-trip is idempotent.
         block.content = cell.value || '';
-        const textValue = stripMarkdown(block);
+        const textValue = unescapeMarkdown(stripMarkdown(block));
         block.content = textValue;
     }
 }

src/notebooks/deepnote/converters/textBlockConverter.ts

@@ -3,6 +3,14 @@ import { NotebookCellData, NotebookCellKind } from 'vscode';
 
 import type { BlockConverter } from './blockConverter';
 
+// Must remain the exact inverse of escapeMarkdown in @deepnote/blocks@4.3.0
+// (identical character class). If a future library version unescapes inside
+// stripMarkdown itself, this wrapper must be deleted — the round-trip unit
+// tests fail loudly (double-unescape) in that case.
+function unescapeMarkdown(text: string): string {
+    return text.replace(/\\([\\`*_{}[\]()#+\-.!|>])/g, '$1');
+}
+
 export class TextBlockConverter implements BlockConverter {
     protected static readonly textBlockTypes = [
         'text-cell-h1',
@@ -27,7 +35,7 @@ export class TextBlockConverter implements BlockConverter {
         block.content = cell.value || '';
 
         // Then strip the markdown formatting to get plain text
-        const textValue = stripMarkdown(block);
+        const textValue = unescapeMarkdown(stripMarkdown(block));
 
         block.content = textValue;
     }

src/notebooks/deepnote/converters/textBlockConverter.unit.test.ts

@@ -463,4 +463,156 @@ suite('TextBlockConverter', () => {
             assert.strictEqual(block.content, '');
         });
     });
+
+    suite('round trip through real @deepnote/blocks library', () => {
+        type TextBlockType = Extract<
+            DeepnoteBlock,
+            {
+                type:
+                    | 'text-cell-h1'
+                    | 'text-cell-h2'
+                    | 'text-cell-h3'
+                    | 'text-cell-p'
+                    | 'text-cell-bullet'
+                    | 'text-cell-todo'
+                    | 'text-cell-callout';
+            }
+        >;
+
+        function assertRoundTrip(fixture: Pick<TextBlockType, 'type' | 'content' | 'metadata'>): DeepnoteBlock {
+            // Constant identity fields; the fixture supplies the correlated type/content/metadata.
+            const base = { blockGroup: 'group-123', id: 'block-123', sortingKey: 'a0' };
+
+            const block: DeepnoteBlock = { ...base, ...fixture };
+
+            const cell = converter.convertToCell(block);
+
+            // A separate object for applyChangesToBlock to mutate, so the assertion
+            // compares the stripped result against the original fixture content.
+            const clone: DeepnoteBlock = { ...base, ...fixture };
+
+            converter.applyChangesToBlock(clone, cell);
+
+            assert.strictEqual(clone.content, fixture.content, `content must round-trip for ${fixture.type}`);
+
+            return clone;
+        }
+
+        const specialContents = ['a_b * c', 'price: $5 (USD).', 'has `code` and #hash', 'Revenue grew 20% (great!).'];
+
+        for (const content of specialContents) {
+            test(`text-cell-h1 round-trips special content ${JSON.stringify(content)}`, () => {
+                assertRoundTrip({ type: 'text-cell-h1', content, metadata: {} });
+            });
+
+            test(`text-cell-h2 round-trips special content ${JSON.stringify(content)}`, () => {
+                assertRoundTrip({ type: 'text-cell-h2', content, metadata: {} });
+            });
+
+            test(`text-cell-h3 round-trips special content ${JSON.stringify(content)}`, () => {
+                assertRoundTrip({ type: 'text-cell-h3', content, metadata: {} });
+            });
+
+            test(`text-cell-p round-trips special content ${JSON.stringify(content)}`, () => {
+                assertRoundTrip({ type: 'text-cell-p', content, metadata: {} });
+            });
+
+            test(`text-cell-bullet round-trips special content ${JSON.stringify(content)}`, () => {
+                assertRoundTrip({ type: 'text-cell-bullet', content, metadata: {} });
+            });
+
+            test(`text-cell-todo round-trips special content ${JSON.stringify(content)}`, () => {
+                assertRoundTrip({ type: 'text-cell-todo', content, metadata: {} });
+            });
+
+            test(`text-cell-callout round-trips special content ${JSON.stringify(content)}`, () => {
+                assertRoundTrip({ type: 'text-cell-callout', content, metadata: {} });
+            });
+        }
+
+        test('literal backslash content round-trips exactly (tripwire)', () => {
+            // Content contains a literal backslash followed by an underscore.
+            // createMarkdown escapes both: `a\_b` -> `a\\\_b`. unescapeMarkdown must
+            // consume exactly those pairs back to `a\_b`. If a future @deepnote/blocks
+            // ever unescapes inside stripMarkdown while this wrapper is still present,
+            // the content would be double-unescaped to `a_b` and this fails loudly.
+            const content = String.raw`a\_b`;
+
+            assertRoundTrip({ type: 'text-cell-p', content, metadata: {} });
+            assertRoundTrip({ type: 'text-cell-h1', content, metadata: {} });
+            assertRoundTrip({ type: 'text-cell-bullet', content, metadata: {} });
+        });
+
+        test('double round trip is stable (content is a fixed point)', () => {
+            // Applying create -> strip twice must equal applying it once.
+            const content = 'has `code` and #hash';
+            const block: DeepnoteBlock = {
+                blockGroup: 'group-123',
+                content,
+                id: 'block-123',
+                metadata: {},
+                sortingKey: 'a0',
+                type: 'text-cell-p'
+            };
+
+            const cellOnce = converter.convertToCell(block);
+            const afterOnce: DeepnoteBlock = { ...block, content: 'overwrite' };
+            converter.applyChangesToBlock(afterOnce, cellOnce);
+
+            const cellTwice = converter.convertToCell(afterOnce);
+            const afterTwice: DeepnoteBlock = { ...afterOnce, content: 'overwrite' };
+            converter.applyChangesToBlock(afterTwice, cellTwice);
+
+            assert.strictEqual(afterOnce.content, content, 'first round-trip restores content');
+            assert.strictEqual(afterTwice.content, afterOnce.content, 'second round-trip is a no-op (fixed point)');
+        });
+
+        test('text-cell-todo round-trips with metadata.checked: true', () => {
+            assertRoundTrip({ type: 'text-cell-todo', content: 'a_b * c', metadata: { checked: true } });
+        });
+
+        test('text-cell-todo round-trips with metadata.checked: false', () => {
+            assertRoundTrip({ type: 'text-cell-todo', content: 'a_b * c', metadata: { checked: false } });
+        });
+
+        test('text-cell-bullet round-trips with metadata.indent_level: 1 (renders flat on 4.3.0)', () => {
+            // indent_level travels through metadata, not content. On 4.3.0 the bullet
+            // renders flat (no leading indentation), and the content must still round-trip.
+            const cell = converter.convertToCell({
+                blockGroup: 'group-123',
+                content: 'a_b * c',
+                id: 'block-123',
+                metadata: { indent_level: 1 },
+                sortingKey: 'a0',
+                type: 'text-cell-bullet'
+            });
+
+            // Documents the flat (un-indented) rendering on 4.3.0.
+            assert.strictEqual(cell.value, '- a\\_b \\* c');
+
+            assertRoundTrip({ type: 'text-cell-bullet', content: 'a_b * c', metadata: { indent_level: 1 } });
+        });
+
+        test('leading/trailing whitespace is trimmed and then stable (pre-existing trim)', () => {
+            const block: DeepnoteBlock = {
+                blockGroup: 'group-123',
+                content: '  a_b  ',
+                id: 'block-123',
+                metadata: {},
+                sortingKey: 'a0',
+                type: 'text-cell-p'
+            };
+
+            const cell = converter.convertToCell(block);
+            const stripped: DeepnoteBlock = { ...block, content: 'overwrite' };
+            converter.applyChangesToBlock(stripped, cell);
+
+            // Pre-existing trim: surrounding whitespace is removed by stripMarkdown's trim.
+            assert.strictEqual(stripped.content, 'a_b', 'leading/trailing whitespace is trimmed');
+
+            // Once trimmed, the content is stable across further round-trips.
+            const trimmedRoundTrip = assertRoundTrip({ type: 'text-cell-p', content: 'a_b', metadata: {} });
+            assert.strictEqual(trimmedRoundTrip.content, 'a_b');
+        });
+    });
 });

src/notebooks/deepnote/deepnoteDataConverter.unit.test.ts

@@ -627,6 +627,73 @@ suite('DeepnoteDataConverter', () => {
             assert.deepStrictEqual(roundTripBlocks, originalBlocks);
         });
 
+        test('text-cell blocks with special characters round-trip without backslash accumulation', () => {
+            // These contents contain characters from the markdown escape class
+            // (_ * ( ) . ! ` #). Without the unescape inverse in TextBlockConverter,
+            // each round-trip would accumulate backslashes; the round-trip must be a no-op.
+            const originalBlocks: DeepnoteBlock[] = [
+                {
+                    blockGroup: 'group-1',
+                    id: 'b1',
+                    type: 'text-cell-h1',
+                    content: 'Revenue grew 20% (great!).',
+                    sortingKey: 'a0',
+                    metadata: {}
+                },
+                {
+                    blockGroup: 'group-2',
+                    id: 'b2',
+                    type: 'text-cell-h2',
+                    content: 'has `code` and #hash',
+                    sortingKey: 'a1',
+                    metadata: {}
+                },
+                {
+                    blockGroup: 'group-3',
+                    id: 'b3',
+                    type: 'text-cell-p',
+                    content: 'a_b * c',
+                    sortingKey: 'a2',
+                    metadata: {}
+                },
+                {
+                    blockGroup: 'group-4',
+                    id: 'b4',
+                    type: 'text-cell-bullet',
+                    content: 'price: $5 (USD).',
+                    sortingKey: 'a3',
+                    metadata: {}
+                },
+                {
+                    blockGroup: 'group-5',
+                    id: 'b5',
+                    type: 'text-cell-todo',
+                    content: 'buy milk (2%) & eggs.',
+                    sortingKey: 'a4',
+                    metadata: { checked: true }
+                },
+                {
+                    blockGroup: 'group-6',
+                    id: 'b6',
+                    type: 'text-cell-callout',
+                    content: 'note: see [docs] for details.',
+                    sortingKey: 'a5',
+                    metadata: {}
+                }
+            ];
+
+            const cells = converter.convertBlocksToCells(originalBlocks);
+            const roundTripBlocks = converter.convertCellsToBlocks(cells);
+
+            assert.deepStrictEqual(roundTripBlocks, originalBlocks);
+
+            // Applying the round-trip a second time must remain a no-op (fixed point).
+            const cellsAgain = converter.convertBlocksToCells(roundTripBlocks);
+            const roundTripBlocksAgain = converter.convertCellsToBlocks(cellsAgain);
+
+            assert.deepStrictEqual(roundTripBlocksAgain, originalBlocks);
+        });
+
         test('SQL metadata output round-trips correctly', () => {
             const sqlMetadata = {
                 status: 'read_from_cache_success',
@@ -736,8 +803,7 @@ suite('DeepnoteDataConverter', () => {
 
         test('real deepnote notebook round-trips without losing data', () => {
             // Inline test data representing a real Deepnote notebook with various block types
-            // blockGroup is an optional field not in the DeepnoteBlock interface, so we cast as any
-            const originalBlocks = [
+            const originalBlocks: DeepnoteBlock[] = [
                 {
                     blockGroup: '1a4224497bcd499ba180e5795990aaa8',
                     content: '# Data Exploration\n\nThis notebook demonstrates basic data exploration.',
@@ -801,7 +867,7 @@ suite('DeepnoteDataConverter', () => {
                     sortingKey: 'yj',
                     type: 'code'
                 }
-            ] as unknown as DeepnoteBlock[];
+            ];
 
             // Convert blocks -> cells -> blocks
             const cells = converter.convertBlocksToCells(originalBlocks);