Route oversized JSON .sldd to read-only view; refresh on save

A JSON .sldd larger than VS Code's 50 MB TextDocument sync limit
(_MODEL_SYNC_LIMIT) cannot open in the editable table view: the ext
host can't mirror an over-limit document and throws "Unable to
retrieve document from URI" before any extension code runs.

Gate the editable routing on exceedsTextSyncLimit() at both call sites
(extension.ts, BinaryEditorProvider redirect) so such files fall through
to the read-only byte-backed view, which reads bytes directly and opens
them fine. Surface a persistent #dex-notice banner explaining the
read-only downgrade — shown only for the size case, not for
expected-read-only binary/zip .sldd.

Because the ext host holds no mirror of an over-limit document,
onDidChangeTextDocument never fires for it, so the read-only view's
live-sync was dead. Replace it with a file-scoped FileSystemWatcher that
observes the disk directly (independent of document syncing), so the
view refreshes when text-view edits are saved at any file size. The
banner sets that expectation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ww-mw

src/extension.ts

@@ -6,7 +6,7 @@ import { BinaryEditorProvider } from './host/BinaryEditorProvider.js';
 import { SlddTextEditorProvider } from './host/SlddTextEditorProvider.js';
 import { HealthDecorationProvider } from './host/HealthDecorationProvider.js';
 import { invalidate, findNode } from './host/SlddModel.js';
-import { isEditableJsonSlddBytes } from './host/slddFormat.js';
+import { isEditableJsonSlddBytes, exceedsTextSyncLimit } from './host/slddFormat.js';
 import { handleNavigate } from './host/navigate.js';
 import { invalidateUsageGraph } from './host/usageGraph.js';
 
@@ -19,10 +19,17 @@ function isSlddUri(uri: vscode.Uri | undefined): boolean {
 // True if the .sldd at `uri` is editable JSON (not zip/binary). Editable JSON
 // opens in the CustomTextEditorProvider (native undo/redo); binary/zip .sldd and
 // all other formats open in the read-only BinaryEditorProvider.
+//
+// A JSON .sldd larger than VS Code's TextDocument sync limit is NOT treated as
+// editable: the CustomTextEditorProvider can't resolve it (the ext host can't
+// mirror an over-limit document — it throws "Unable to retrieve document from
+// URI"), so it falls through to the read-only byte-backed view, which opens it
+// fine. See exceedsTextSyncLimit in slddFormat.ts.
 async function isEditableJsonSldd(uri: vscode.Uri): Promise<boolean> {
   if (!uri.path.endsWith('.sldd')) return false;
   try {
-    return isEditableJsonSlddBytes(await vscode.workspace.fs.readFile(uri));
+    const bytes = await vscode.workspace.fs.readFile(uri);
+    return isEditableJsonSlddBytes(bytes) && !exceedsTextSyncLimit(bytes);
   } catch {
     return false;
   }

src/host/BinaryEditorProvider.ts

@@ -11,7 +11,7 @@ import {
 } from './rowBuilder.js';
 import { buildMatRows } from './matRowBuilder.js';
 import { readProjectStore } from './projectStore.js';
-import { isEditableJsonSlddBytes } from './slddFormat.js';
+import { isEditableJsonSlddBytes, exceedsTextSyncLimit } from './slddFormat.js';
 import { annotateDataRows, annotateModelRows } from './usageGraph.js';
 import { onNavigateSelect, consumePendingSelect } from './navigate.js';
 
@@ -65,6 +65,12 @@ export class BinaryEditorProvider implements vscode.CustomReadonlyEditorProvider
     const uriString = document.uri.toString();
     const name = document.uri.path.split('/').pop() ?? 'document';
 
+    // A read-only banner shown above the table. Set only for the surprising case:
+    // a JSON .sldd that WOULD be editable but is over VS Code's TextDocument sync
+    // limit (see below). Binary/zip .sldd — expected read-only — leave this unset
+    // so no banner appears. Passed to the webview in the setRows payload.
+    let notice: string | undefined;
+
     // This byte-backed editor is the DEFAULT for *.sldd because it can open any
     // bytes (binary/zip .sldd fail to load as a TextDocument, so the text-backed
     // tableView can't be the default). But editable JSON .sldd should open in the
@@ -74,7 +80,12 @@ export class BinaryEditorProvider implements vscode.CustomReadonlyEditorProvider
     if (name.endsWith('.sldd')) {
       try {
         const bytes = await vscode.workspace.fs.readFile(document.uri);
-        if (isEditableJsonSlddBytes(bytes)) {
+        // Editable JSON .sldd redirects to the text-backed table view — BUT only
+        // when VS Code can actually mirror it as a TextDocument. Over the sync
+        // limit, the tableView provider can't resolve (the ext host throws
+        // "Unable to retrieve document from URI"), so keep such files here and
+        // render them read-only. See exceedsTextSyncLimit in slddFormat.ts.
+        if (isEditableJsonSlddBytes(bytes) && !exceedsTextSyncLimit(bytes)) {
           // Carry the incoming tab's preview state through the redirect: an
           // Explorer single-click opens this binary tab as a PREVIEW tab, and the
           // table it redirects to should stay a preview tab too (not pin). VS
@@ -92,6 +103,17 @@ export class BinaryEditorProvider implements vscode.CustomReadonlyEditorProvider
           webviewPanel.dispose();
           return;
         }
+        // A JSON .sldd that stayed here (not redirected) did so ONLY because it's
+        // over the sync limit — otherwise it would be editable. That's surprising
+        // (a JSON dictionary the user expects to edit), so explain the read-only
+        // downgrade. Binary/zip .sldd skips this (isEditableJsonSlddBytes false).
+        if (isEditableJsonSlddBytes(bytes)) {
+          const mb = Math.round(bytes.byteLength / (1024 * 1024));
+          notice =
+            `Read-only: this dictionary is ${mb} MB, above VS Code's 50 MB editing limit. ` +
+            `To edit the JSON directly, use "Reopen Editor With… → Text Editor"; ` +
+            `this view refreshes when you save.`;
+        }
       } catch {
         // Unreadable → fall through and let the read-only render report the error.
       }
@@ -161,6 +183,7 @@ export class BinaryEditorProvider implements vscode.CustomReadonlyEditorProvider
           columns: COLUMNS,
           columnLabels: COLUMN_LABELS,
           editable: false,
+          notice,
         });
         drainNavSelect();
       } catch (err) {
@@ -194,19 +217,32 @@ export class BinaryEditorProvider implements vscode.CustomReadonlyEditorProvider
       webview.postMessage({ type: 'selectByName', name: e.name });
     });
 
-    // Live-sync when the underlying document changes: covers external /
-    // text-view edits to the file. Re-parse and repaint the read-only view.
-    const changeSub = vscode.workspace.onDidChangeTextDocument((e) => {
-      if (e.document.uri.toString() === uriString) {
-        invalidate(uriString);
-        void post();
-      }
-    });
+    // Live-sync when the file on disk changes: covers external edits AND edits
+    // made in the plain-text view once saved. We watch the DISK, not the
+    // TextDocument, on purpose: a JSON .sldd routed here is over VS Code's 50 MB
+    // sync limit, so the ext host holds no mirror of it and
+    // onDidChangeTextDocument NEVER fires for it (the same limit that forced the
+    // read-only downgrade — see slddFormat.ts). A FileSystemWatcher observes the
+    // disk directly, independent of document syncing, so it fires on save at any
+    // size. Because this view always reads bytes from disk, unsaved edits can't
+    // be reflected anyway — refresh-on-save is the achievable contract, and the
+    // banner tells the user so.
+    const watcher = vscode.workspace.createFileSystemWatcher(
+      new vscode.RelativePattern(vscode.Uri.joinPath(document.uri, '..'), name),
+    );
+    const onDiskChange = () => {
+      invalidate(uriString);
+      void post();
+    };
+    const changeSub = watcher.onDidChange(onDiskChange);
+    const createSub = watcher.onDidCreate(onDiskChange);
 
     webview.html = this.getHtml(webview, distRoot);
     webviewPanel.onDidDispose(() => {
       sub.dispose();
+      watcher.dispose();
       changeSub.dispose();
+      createSub.dispose();
       navSub.dispose();
     });
   }
@@ -231,6 +267,7 @@ export class BinaryEditorProvider implements vscode.CustomReadonlyEditorProvider
       scriptFile: 'table.js',
       title: 'Data Explorer',
       body: `    <div id="dex-error" role="alert" style="display:none;color:var(--vscode-errorForeground,#f14c4c);padding:8px;font-family:var(--vscode-font-family,sans-serif);"></div>
+    <div id="dex-notice" role="status" style="display:none;position:absolute;top:0;left:0;right:0;z-index:2;box-sizing:border-box;padding:6px 10px;font-family:var(--vscode-font-family,sans-serif);font-size:12px;color:var(--vscode-inputValidation-infoForeground,var(--vscode-foreground));background:var(--vscode-inputValidation-infoBackground,rgba(100,148,237,0.12));border-bottom:1px solid var(--vscode-inputValidation-infoBorder,#4084d0);"></div>
     <dex-tree-table style="position:absolute;inset:0;"></dex-tree-table>
     <dex-context-menu></dex-context-menu>`,
     });

src/host/slddFormat.ts

@@ -28,3 +28,22 @@ export function isEditableJsonSlddBytes(bytes: Uint8Array): boolean {
     return false;
   }
 }
+
+// VS Code refuses to mirror a TextDocument larger than TextModel._MODEL_SYNC_LIMIT
+// (50 MB) into the extension host. Our editable JSON .sldd table is a
+// CustomTextEditorProvider, which depends on that mirror — so past this size,
+// resolving it throws "Unable to retrieve document from URI" in the ext host
+// before our provider code ever runs, and the table fails to open. Such files
+// are routed to the read-only byte-backed view instead (it reads bytes directly
+// via workspace.fs, so it isn't subject to the sync limit). Editing is
+// impossible above the limit regardless, since VS Code won't sync the document.
+//
+// VS Code measures the model in UTF-16 code units; we gate on byte length, which
+// is always >= the UTF-16 length for UTF-8. So any file kept on the editable path
+// (byte length <= limit) is guaranteed to sync — no false downgrades.
+export const TEXT_SYNC_LIMIT = 50 * 1024 * 1024;
+
+/** True if `bytes` is too large for VS Code to sync as an editable TextDocument. */
+export function exceedsTextSyncLimit(bytes: Uint8Array): boolean {
+  return bytes.length > TEXT_SYNC_LIMIT;
+}

src/webview/table-main.ts

@@ -62,10 +62,37 @@ function clearError(): void {
   if (el) { el.textContent = ''; el.style.display = 'none'; }
 }
 
+// Persistent, informational read-only banner (e.g. a JSON .sldd too large to
+// edit). Distinct from the transient red #dex-error. The table fills the panel
+// (position:absolute;inset:0), so when the banner is shown we offset the table's
+// top by the banner's measured height — measured, not hardcoded, so it stays
+// correct when the message wraps at narrow widths. Only the read-only binary
+// view renders #dex-notice; in the editable table view it's absent and this
+// no-ops.
+function setNotice(message: string | undefined): void {
+  const el = document.getElementById('dex-notice');
+  if (!el) return;
+  if (message) {
+    el.textContent = message;
+    el.style.display = 'block';
+    // Offset after layout so offsetHeight reflects the (possibly wrapped) banner.
+    requestAnimationFrame(() => {
+      table.style.top = el.offsetHeight + 'px';
+    });
+  } else {
+    el.textContent = '';
+    el.style.display = 'none';
+    table.style.top = '';
+  }
+}
+
 window.addEventListener('message', (event: MessageEvent) => {
   const msg = event.data;
   if (msg.type === 'setRows') {
     clearError();
+    // Persistent read-only notice (size-limited JSON .sldd). Undefined for the
+    // editable table view and for expected-read-only binary .sldd, so it hides.
+    setNotice(typeof msg.notice === 'string' ? msg.notice : undefined);
     const rows = msg.rows ?? [];
     editable = !!msg.editable;
     table.columns = msg.columns ?? null;

test/readonlyNotice.test.ts

@@ -0,0 +1,62 @@
+// Copyright 2026 The MathWorks, Inc.
+// @vitest-environment happy-dom
+import { describe, it, expect, beforeEach } from 'vitest';
+
+// The read-only binary view shows a PERSISTENT informational banner (#dex-notice)
+// when a JSON .sldd is too large to edit, and offsets the full-bleed table below
+// it. table-main.ts can't be imported in isolation (top-level acquireVsCodeApi()
+// + DOM wiring), so — as with readonlyEditorGate.test.ts — we mirror setNotice's
+// contract against the same DOM shape the host's getHtml() renders.
+
+function setNotice(table: HTMLElement, message: string | undefined): void {
+  const el = document.getElementById('dex-notice');
+  if (!el) return;
+  if (message) {
+    el.textContent = message;
+    el.style.display = 'block';
+    // Real code defers the offset to rAF so offsetHeight reflects wrapping;
+    // happy-dom reports 0 height, so set it synchronously here — the assertions
+    // below check the show/hide + offset-cleared contract, not the pixel value.
+    table.style.top = el.offsetHeight + 'px';
+  } else {
+    el.textContent = '';
+    el.style.display = 'none';
+    table.style.top = '';
+  }
+}
+
+describe('read-only notice banner (#dex-notice)', () => {
+  let table: HTMLElement;
+
+  beforeEach(() => {
+    document.body.innerHTML =
+      '<div id="dex-notice" style="display:none;"></div>' +
+      '<div id="table" style="position:absolute;inset:0;"></div>';
+    table = document.getElementById('table')!;
+  });
+
+  it('shows the banner and offsets the table when a notice is present', () => {
+    setNotice(table, 'Read-only: this dictionary is 138 MB, above VS Code’s 50 MB editing limit.');
+    const el = document.getElementById('dex-notice')!;
+    expect(el.style.display).toBe('block');
+    expect(el.textContent).toContain('138 MB');
+    // The table is pushed down (top set), not left overlapping the banner.
+    expect(table.style.top).not.toBe('');
+  });
+
+  it('hides the banner and clears the offset when there is no notice', () => {
+    setNotice(table, 'something'); // show first
+    setNotice(table, undefined); // then clear
+    const el = document.getElementById('dex-notice')!;
+    expect(el.style.display).toBe('none');
+    expect(el.textContent).toBe('');
+    expect(table.style.top).toBe('');
+  });
+
+  it('is a no-op when the notice element is absent (editable table view)', () => {
+    document.body.innerHTML = '<div id="table"></div>'; // no #dex-notice
+    const t = document.getElementById('table')!;
+    expect(() => setNotice(t, 'x')).not.toThrow();
+    expect(t.style.top).toBe('');
+  });
+});

test/slddFormat.test.ts

@@ -4,7 +4,12 @@
 import { describe, it, expect } from 'vitest';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { isZipBytes, isEditableJsonSlddBytes } from '../src/host/slddFormat.js';
+import {
+  isZipBytes,
+  isEditableJsonSlddBytes,
+  exceedsTextSyncLimit,
+  TEXT_SYNC_LIMIT,
+} from '../src/host/slddFormat.js';
 
 function bytesOf(relPath: string): Uint8Array {
   return new Uint8Array(readFileSync(fileURLToPath(new URL(relPath, import.meta.url))));
@@ -34,3 +39,24 @@ describe('slddFormat routing detection', () => {
     expect(isZipBytes(new Uint8Array([0x50, 0x4b]))).toBe(false); // too short
   });
 });
+
+describe('exceedsTextSyncLimit (large-file routing guard)', () => {
+  it('is false for a small file (opens in the editable table view)', () => {
+    expect(exceedsTextSyncLimit(new TextEncoder().encode('{}'))).toBe(false);
+  });
+
+  it('is false exactly at the limit (boundary: <= limit stays editable)', () => {
+    // A real allocation this large is wasteful; fake the length VS Code measures.
+    expect(exceedsTextSyncLimit({ length: TEXT_SYNC_LIMIT } as Uint8Array)).toBe(false);
+  });
+
+  it('is true one byte past the limit (routes to the read-only view)', () => {
+    expect(exceedsTextSyncLimit({ length: TEXT_SYNC_LIMIT + 1 } as Uint8Array)).toBe(true);
+  });
+
+  it('matches VS Code TextModel._MODEL_SYNC_LIMIT (50 MB)', () => {
+    // If VS Code ever changes this constant, this test flags that our routing
+    // threshold has drifted from it. See slddFormat.ts for why they must agree.
+    expect(TEXT_SYNC_LIMIT).toBe(50 * 1024 * 1024);
+  });
+});