mbeditor 0.3.8 → 0.4.2

data/app/assets/javascripts/mbeditor/components/QuickOpenDialog.js

@@ -76,6 +76,35 @@ var QuickOpenDialog = function QuickOpenDialog(_ref) {
     if (inputRef.current) inputRef.current.focus();
   };
 
+  // Priority tier for a file path: lower = shown first.
+  // Order: controller > model > helper > concern > view > job > other > noise
+  function getFilePriority(path) {
+    var p = (path || '').toLowerCase();
+    if (p.indexOf('/controllers/') >= 0) return 1;
+    if (p.indexOf('/models/')      >= 0) return 2;
+    if (p.indexOf('/helpers/')     >= 0) return 3;
+    if (p.indexOf('/concerns/')    >= 0) return 4;
+    if (p.indexOf('/views/')       >= 0) return 5;
+    if (p.indexOf('/jobs/')        >= 0) return 6;
+    // Deprioritise: migrations, schema, compiled assets, vendor, lock files
+    if (p.indexOf('/migrate/')  >= 0 || p.indexOf('schema.rb') >= 0) return 90;
+    if (p.indexOf('/public/')   >= 0 || p.indexOf('/vendor/')   >= 0) return 91;
+    if (p.slice(-7)  === '.min.js' || p.slice(-8) === '.min.css' ||
+        p.slice(-4)  === '.map'    || p.slice(-5) === '.lock')        return 92;
+    return 50;
+  }
+
+  // Match relevance within a priority tier: exact basename > prefix > substring > other.
+  function getMatchRelevance(result, q) {
+    if (!q) return 3;
+    var name = (result.name || (result.path || '').split('/').pop() || '').toLowerCase();
+    var lq = q.toLowerCase();
+    if (name === lq)            return 0;
+    if (name.slice(0, lq.length) === lq) return 1;
+    if (name.indexOf(lq) >= 0)  return 2;
+    return 3;
+  }
+
   var getQuickOpenIcon = function getQuickOpenIcon(path, name, type) {
     if (type === 'dir') {
       return React.createElement('i', { className: 'fas fa-folder quick-open-result-icon quick-open-folder-icon', 'aria-hidden': 'true' });
@@ -99,7 +128,18 @@ var QuickOpenDialog = function QuickOpenDialog(_ref) {
     var res = SearchService.searchFiles(query);
     // Filter by type: always include files; include dirs only when showFolders is on
     var filtered = showFolders ? res : res.filter(function(r) { return r.type !== 'dir'; });
-    setResults(filtered.slice(0, 20));
+    // Sort: files always beat dirs; within the same tier exact basename > prefix > substring > other.
+    // JS sort is stable in modern engines so MiniSearch relevance score order is the tiebreaker
+    // when match relevance is equal.
+    filtered.sort(function(a, b) {
+      var aRelevance = getMatchRelevance(a, query);
+      var bRelevance = getMatchRelevance(b, query);
+      if (aRelevance !== bRelevance) return aRelevance - bRelevance;
+      var aPriority = getFilePriority(a.path) + (a.type === 'dir' ? 100 : 0);
+      var bPriority = getFilePriority(b.path) + (b.type === 'dir' ? 100 : 0);
+      return aPriority - bPriority;
+    });
+    setResults(filtered.slice(0, 200));
     setSelectedIndex(0);
   }, [query, showFolders]);
 

data/app/assets/javascripts/mbeditor/components/TabBar.js

@@ -18,6 +18,7 @@ var TabBar = function TabBar(_ref) {
   var onHardenTab = _ref.onHardenTab;
   var onShowHistory = _ref.onShowHistory;
   var onRevealInExplorer = _ref.onRevealInExplorer;
+  var tabDisplayMode = _ref.tabDisplayMode || 'scroll';
 
   var containerRef = useRef(null);
 
@@ -87,8 +88,8 @@ var TabBar = function TabBar(_ref) {
     null,
     React.createElement(
     'div',
-    { className: 'tab-bar', ref: containerRef, onWheel: function (e) {
-        if (containerRef.current) {
+    { className: 'tab-bar tab-bar-' + tabDisplayMode, ref: containerRef, onWheel: function (e) {
+        if (tabDisplayMode !== 'wrap' && containerRef.current) {
           containerRef.current.scrollLeft += e.deltaY;
         }
       } },

data/app/assets/javascripts/mbeditor/editor_plugins.js

@@ -31,6 +31,24 @@
     'or': true, not: true, require: true, include: true, extend: true
   };
 
+  // Ruby core / Kernel built-in methods that should never trigger a
+  // definition lookup — ctrl+click or F12 on these is a no-op.
+  var RUBY_CORE_METHODS = {
+    puts: true, print: true, p: true, pp: true, warn: true, printf: true,
+    fail: true, require_relative: true, prepend: true,
+    attr_accessor: true, attr_reader: true, attr_writer: true,
+    lambda: true, proc: true, 'loop': true, sleep: true,
+    exit: true, abort: true, rand: true, srand: true, gets: true,
+    sprintf: true, format: true, open: true,
+    Integer: true, Float: true, String: true, Array: true, Hash: true,
+    Rational: true, Complex: true,
+    readline: true, readlines: true,
+    system: true, exec: true, fork: true, spawn: true,
+    freeze: true, frozen: true, dup: true, clone: true, object_id: true,
+    respond_to: true, send: true, public_send: true, method: true,
+    tap: true, itself: true
+  };
+
   var globalsRegistered = false;
 
   function leadingWhitespace(line) {
@@ -287,6 +305,7 @@
         var wordInfo = model.getWordAtPosition(position);
         if (!wordInfo || !wordInfo.word || wordInfo.word.length < 2) return;
         if (RUBY_KEYWORDS[wordInfo.word]) return;
+        if (RUBY_CORE_METHODS[wordInfo.word]) return;
         if (typeof FileService === 'undefined' || !FileService.getDefinition) return;
 
         event.event.preventDefault();
@@ -315,6 +334,7 @@
           var wordInfo = model.getWordAtPosition(pos);
           if (!wordInfo || !wordInfo.word || wordInfo.word.length < 2) return;
           if (RUBY_KEYWORDS[wordInfo.word]) return;
+          if (RUBY_CORE_METHODS[wordInfo.word]) return;
           if (typeof FileService === 'undefined' || !FileService.getDefinition) return;
 
           FileService.getDefinition(wordInfo.word, 'ruby').then(function(data) {
@@ -707,6 +727,7 @@
         var word = wordInfo.word;
         if (!word || word.length < 2) return null;
         if (RUBY_KEYWORDS[word]) return null;
+        if (RUBY_CORE_METHODS[word]) return null;
         if (typeof FileService === 'undefined' || !FileService.getDefinition) return null;
 
         var currentFile = model._mbeditorPath || null;

data/app/assets/javascripts/mbeditor/editor_store.js

@@ -20,6 +20,7 @@ var EditorStore = (function () {
   };
 
   var _listeners = [];
+  var _statusTimer = null;
 
   function getState() { return _state; }
 
@@ -42,6 +43,9 @@ var EditorStore = (function () {
   // Subscribe to changes in a specific subset of state keys.
   // The listener is only called when at least one of the watched keys changes
   // by reference (===), preventing unnecessary re-renders for unrelated updates.
+  // IMPORTANT: all state updates MUST produce a new object reference for any
+  // nested value (use Object.assign / spread — never mutate in place), otherwise
+  // subscribeToSlice will not detect the change.
   function subscribeToSlice(keys, fn) {
     var prev = {};
     keys.forEach(function(k) { prev[k] = _state[k]; });
@@ -57,9 +61,13 @@ var EditorStore = (function () {
   function setStatus(text, kind) {
     kind = kind || "info";
     setState({ statusMessage: { text: text, kind: kind } });
-    // Auto-clear after 4s for non-error messages
+    if (_statusTimer !== null) {
+      clearTimeout(_statusTimer);
+      _statusTimer = null;
+    }
     if (kind !== "error") {
-      setTimeout(function () {
+      _statusTimer = setTimeout(function () {
+        _statusTimer = null;
         if (_state.statusMessage.text === text) {
           setState({ statusMessage: { text: "", kind: "info" } });
         }

data/app/assets/javascripts/mbeditor/file_service.js

@@ -2,6 +2,10 @@
 // The server uses this header to silence editor logs and guard non-GET requests.
 axios.defaults.headers.common['X-Mbeditor-Client'] = '1';
 
+// Cap all API calls at 30 s so a hung Rails server never blocks the UI forever.
+// The ping endpoint overrides this with a tighter 4 s timeout per-request.
+axios.defaults.timeout = 30000;
+
 // Surface pending-migration errors as a dismissible banner instead of silently failing.
 axios.interceptors.response.use(null, function(error) {
   if (error.response && error.response.data && error.response.data.pending_migration_error) {
@@ -28,16 +32,12 @@ axios.interceptors.response.use(null, function(error) {
 });
 
 var FileService = (function () {
-  function basePath() {
-    return (window.MBEDITOR_BASE_PATH || '/mbeditor').replace(/\/$/, '');
-  }
-
   function getWorkspace() {
-    return axios.get(basePath() + '/workspace').then(function(res) { return res.data; });
+    return axios.get(window.mbeditorBasePath() + '/workspace').then(function(res) { return res.data; });
   }
 
   function getTree() {
-    return axios.get(basePath() + '/files').then(function(res) { return res.data; });
+    return axios.get(window.mbeditorBasePath() + '/files').then(function(res) { return res.data; });
   }
 
   function getFile(path, options) {
@@ -45,72 +45,78 @@ var FileService = (function () {
     if (options && options.allowMissing) {
       params.allow_missing = '1';
     }
-    return axios.get(basePath() + '/file', { params: params }).then(function(res) { return res.data; });
+    return axios.get(window.mbeditorBasePath() + '/file', { params: params }).then(function(res) { return res.data; });
   }
 
   function saveFile(path, code) {
-    return axios.post(basePath() + '/file', { path: path, code: code }).then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/file', { path: path, code: code }).then(function(res) { return res.data; });
   }
 
   function createFile(path, code) {
-    return axios.post(basePath() + '/create_file', { path: path, code: code || '' }).then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/create_file', { path: path, code: code || '' }).then(function(res) { return res.data; });
   }
 
   function createDir(path) {
-    return axios.post(basePath() + '/create_dir', { path: path }).then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/create_dir', { path: path }).then(function(res) { return res.data; });
   }
 
   function renamePath(path, newPath) {
-    return axios.patch(basePath() + '/rename', { path: path, new_path: newPath }).then(function(res) { return res.data; });
+    return axios.patch(window.mbeditorBasePath() + '/rename', { path: path, new_path: newPath }).then(function(res) { return res.data; });
   }
 
   function deletePath(path) {
-    return axios.delete(basePath() + '/delete', { data: { path: path } }).then(function(res) { return res.data; });
+    return axios.delete(window.mbeditorBasePath() + '/delete', { data: { path: path } }).then(function(res) { return res.data; });
   }
 
   function lintFile(path, code) {
-    return axios.post(basePath() + '/lint', { path: path, code: code }).then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/lint', { path: path, code: code }).then(function(res) { return res.data; });
   }
 
   function quickFixOffense(path, code, copName) {
-    return axios.post(basePath() + '/quick_fix', { path: path, code: code, cop_name: copName }).then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/quick_fix', { path: path, code: code, cop_name: copName }).then(function(res) { return res.data; });
   }
 
   function formatFile(path, code) {
-    return axios.post(basePath() + '/format', { path: path, code: code }).then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/format', { path: path, code: code }).then(function(res) { return res.data; });
   }
 
   function runTests(path) {
-    return axios.post(basePath() + '/test', { path: path }).then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/test', { path: path }).then(function(res) { return res.data; });
   }
 
   function ping() {
-    return axios.get(basePath() + '/ping', { timeout: 4000 }).then(function(res) { return res.data; });
+    return axios.get(window.mbeditorBasePath() + '/ping', { timeout: 4000 }).then(function(res) { return res.data; });
   }
 
   function getState() {
-    return axios.get(basePath() + '/state').then(function(res) { return res.data; });
+    return axios.get(window.mbeditorBasePath() + '/state').then(function(res) { return res.data; });
   }
 
   function saveState(state) {
-    return axios.post(basePath() + '/state', { state: state }).then(function(res) { return res.data; });
+    if (WebSocketService.isConnected() && WebSocketService.perform('save_state', { state: state })) {
+      return Promise.resolve({ ok: true });
+    }
+    return axios.post(window.mbeditorBasePath() + '/state', { state: state }).then(function(res) { return res.data; });
   }
 
   function getBranchState(branch) {
-    return axios.get(basePath() + '/branch_state', { params: { branch: branch } }).then(function(res) { return res.data; });
+    return axios.get(window.mbeditorBasePath() + '/branch_state', { params: { branch: branch } }).then(function(res) { return res.data; });
   }
 
   function saveBranchState(branch, state) {
-    return axios.post(basePath() + '/branch_state', { branch: branch, state: state }).then(function(res) { return res.data; });
+    if (WebSocketService.isConnected() && WebSocketService.perform('save_branch_state', { branch: branch, state: state })) {
+      return Promise.resolve({ ok: true });
+    }
+    return axios.post(window.mbeditorBasePath() + '/branch_state', { branch: branch, state: state }).then(function(res) { return res.data; });
   }
 
   function pruneBranchStates() {
-    return axios.post(basePath() + '/prune_branch_states').then(function(res) { return res.data; });
+    return axios.post(window.mbeditorBasePath() + '/prune_branch_states').then(function(res) { return res.data; });
   }
 
   function getDefinition(symbol, language, extraOptions) {
     var config = Object.assign({ params: { symbol: symbol, language: language }, timeout: 5000 }, extraOptions || {});
-    return axios.get(basePath() + '/definition', config).then(function(res) { return res.data; });
+    return axios.get(window.mbeditorBasePath() + '/definition', config).then(function(res) { return res.data; });
   }
 
   return {

data/app/assets/javascripts/mbeditor/git_service.js

@@ -1,8 +1,4 @@
 var GitService = (function () {
-  function basePath() {
-    return (window.MBEDITOR_BASE_PATH || '/mbeditor').replace(/\/$/, '');
-  }
-
   function applyGitInfo(data) {
     var files = data.workingTree || data.files || [];
     EditorStore.setState({
@@ -14,7 +10,7 @@ var GitService = (function () {
   }
 
   function fetchInfo() {
-    return axios.get(basePath() + '/git_info')
+    return axios.get(window.mbeditorBasePath() + '/git_info')
       .then(function(res) {
         if (res.data && res.data.ok) {
           applyGitInfo(res.data);
@@ -33,7 +29,7 @@ var GitService = (function () {
     return fetchInfo().then(function(data) {
       if (data && data.ok) return data;
 
-      return axios.get(basePath() + '/git_status')
+      return axios.get(window.mbeditorBasePath() + '/git_status')
       .then(function(res) {
         if (res.data.ok) {
           EditorStore.setState({
@@ -63,31 +59,31 @@ var GitService = (function () {
     if (baseSha) query += '&base=' + encodeURIComponent(baseSha);
     if (headSha) query += '&head=' + encodeURIComponent(headSha);
     
-    return axios.get(basePath() + '/git/diff' + query).then(function(res) {
+    return axios.get(window.mbeditorBasePath() + '/git/diff' + query).then(function(res) {
       return res.data;
     });
   }
 
   function fetchBlame(path) {
-    return axios.get(basePath() + '/git/blame?file=' + encodeURIComponent(path)).then(function(res) {
+    return axios.get(window.mbeditorBasePath() + '/git/blame?file=' + encodeURIComponent(path)).then(function(res) {
       return res.data;
     });
   }
 
   function fetchFileHistory(path) {
-    return axios.get(basePath() + '/git/file_history?file=' + encodeURIComponent(path)).then(function(res) {
+    return axios.get(window.mbeditorBasePath() + '/git/file_history?file=' + encodeURIComponent(path)).then(function(res) {
       return res.data;
     });
   }
 
   function fetchCommitGraph() {
-    return axios.get(basePath() + '/git/commit_graph').then(function(res) {
+    return axios.get(window.mbeditorBasePath() + '/git/commit_graph').then(function(res) {
       return res.data;
     });
   }
 
   function fetchCommitDetail(sha) {
-    return axios.get(basePath() + '/git/commit_detail?sha=' + encodeURIComponent(sha)).then(function(res) {
+    return axios.get(window.mbeditorBasePath() + '/git/commit_detail?sha=' + encodeURIComponent(sha)).then(function(res) {
       return res.data;
     });
   }

data/app/assets/javascripts/mbeditor/search_service.js

@@ -1,15 +1,14 @@
 var SearchService = (function () {
   var SEARCH_PAGE_SIZE = 50;
 
-  function basePath() {
-    return (window.MBEDITOR_BASE_PATH || '/mbeditor').replace(/\/$/, '');
-  }
-
   var _miniSearch = new MiniSearch({
     fields: ['path', 'name'],           // indexed fields
     storeFields: ['path', 'name', 'type'] // returned fields (type: 'file'|'dir')
   });
 
+  // Flat doc list kept in sync with _miniSearch so we can do substring lookups.
+  var _allDocs = [];
+
   function buildIndex(treeData) {
     // Capture the tree data immediately so a subsequent refresh doesn't
     // clobber us before the idle callback fires.
@@ -32,31 +31,50 @@ var SearchService = (function () {
       }
 
       traverse(snapshot);
+      _allDocs = docs.slice();
       _miniSearch.removeAll();
       _miniSearch.addAll(docs);
     });
   }
 
   // Search files (and optionally folders) in the local MiniSearch index.
-  // Returns raw MiniSearch results; caller can filter by .type.
+  // Also performs a case-insensitive substring scan so that partial-word
+  // queries like "project" reliably find "projects_controller.rb".
+  // Returns merged results; MiniSearch scored entries come first.
   function searchFiles(query) {
     if (!query) return [];
-    return _miniSearch.search(query, { prefix: true, fuzzy: 0.2 });
+    var msResults = _miniSearch.search(query, { prefix: true, fuzzy: false, combineWith: 'AND' });
+    // Substring fallback — catch anything MiniSearch missed
+    var q = query.toLowerCase();
+    var msIds = new Set(msResults.map(function(r) { return r.id; }));
+    var subResults = _allDocs.filter(function(doc) {
+      if (msIds.has(doc.id)) return false;
+      return doc.path.toLowerCase().indexOf(q) >= 0 || doc.name.toLowerCase().indexOf(q) >= 0;
+    }).map(function(doc) {
+      return { id: doc.id, path: doc.path, name: doc.name, type: doc.type, score: 0 };
+    });
+    return msResults.concat(subResults);
   }
 
   // Fetch one page of project-wide full-text search results.
   // offset=0 replaces the EditorStore results list; offset>0 appends.
-  function projectSearch(query, offset, limit) {
-    if (!query) return Promise.resolve({ results: [], hasMore: false });
+  // The server includes total_count only on offset=0 (fast rg --count pass).
+  // options.regex=true enables regex mode on the server.
+  function projectSearch(query, offset, limit, options) {
+    if (!query) return Promise.resolve({ results: [], hasMore: false, totalCount: 0 });
     var off = (typeof offset === 'number') ? offset : 0;
     var lim = (typeof limit  === 'number') ? limit  : SEARCH_PAGE_SIZE;
+    var useRegex = !!(options && options.regex);
+    var matchCase = !!(options && options.matchCase);
+    var wholeWord = !!(options && options.wholeWord);
 
-    return axios.get(basePath() + '/search', {
-      params: { q: query, offset: off, limit: lim }
+    return axios.get(window.mbeditorBasePath() + '/search', {
+      params: { q: query, offset: off, limit: lim, regex: useRegex ? 'true' : 'false', match_case: matchCase ? 'true' : 'false', whole_word: wholeWord ? 'true' : 'false' }
     }).then(function(res) {
         var data = res.data;
-        var results = Array.isArray(data) ? data : (data && data.results || []);
-        var hasMore = !Array.isArray(data) && !!(data && data.has_more);
+        var results    = Array.isArray(data) ? data : (data && data.results || []);
+        var hasMore    = !Array.isArray(data) && !!(data && data.has_more);
+        var totalCount = (data && data.total_count != null) ? data.total_count : null;
 
         if (off === 0) {
           EditorStore.setState({ searchResults: results, searchHasMore: hasMore });
@@ -64,18 +82,37 @@ var SearchService = (function () {
           var prev = EditorStore.getState().searchResults || [];
           EditorStore.setState({ searchResults: prev.concat(results), searchHasMore: hasMore });
         }
-        return { results: results, hasMore: hasMore };
+        return { results: results, hasMore: hasMore, totalCount: totalCount };
       })
       .catch(function(err) {
         EditorStore.setStatus("Search failed: " + err.message, "error");
-        return { results: [], hasMore: false };
+        return { results: [], hasMore: false, totalCount: null };
       });
   }
 
+  // Fetch a specific page by index without touching EditorStore.
+  // Used by the random-access virtual scroll loader.
+  function fetchPage(query, pageIndex) {
+    if (!query) return Promise.resolve({ results: [], hasMore: false });
+    var offset = pageIndex * SEARCH_PAGE_SIZE;
+    return axios.get(basePath() + '/search', {
+      params: { q: query, offset: offset, limit: SEARCH_PAGE_SIZE }
+    }).then(function(res) {
+      var data = res.data;
+      var results = Array.isArray(data) ? data : (data && data.results || []);
+      var hasMore = !Array.isArray(data) && !!(data && data.has_more);
+      return { results: results, hasMore: hasMore };
+    }).catch(function(err) {
+      EditorStore.setStatus("Search failed: " + err.message, "error");
+      return { results: [], hasMore: false };
+    });
+  }
+
   return {
     buildIndex: buildIndex,
     searchFiles: searchFiles,
     projectSearch: projectSearch,
+    fetchPage: fetchPage,
     PAGE_SIZE: SEARCH_PAGE_SIZE
   };
 })();

data/app/assets/javascripts/mbeditor/tab_manager.js

@@ -257,11 +257,11 @@ var TabManager = (function () {
     });
     EditorStore.setState({ panes: newPanes, focusedPaneId: paneId, activeTabId: tabId });
 
-    var basePath = (window.MBEDITOR_BASE_PATH || '/mbeditor').replace(/\/$/, '');
-    axios.get(basePath + '/git/combined_diff', { params: { scope: scope || 'local' } })
+    axios.get(window.mbeditorBasePath() + '/git/combined_diff', { params: { scope: scope || 'local' } })
       .then(function(res) {
+        var data = res.data;
         _updateTab(paneId, tabId, {
-          combinedDiffText: typeof res.data === 'string' ? res.data : '',
+          combinedDiffText: typeof data === 'string' ? data : (data && data.diff) || '',
           combinedDiffLoaded: true
         });
       })

data/app/assets/javascripts/mbeditor/websocket_service.js

@@ -0,0 +1,126 @@
+// WebSocketService — wraps ActionCable when available.
+// Falls back gracefully when ActionCable is absent or the WebSocket connection
+// cannot be established (e.g. the host app does not mount /cable).
+//
+// The ping heartbeat is intentionally NOT routed through this service.
+// Polling keeps working as the authoritative "is the server reachable?" check
+// because WebSocket connections can survive DNS/network changes that would
+// otherwise prevent reconnection.
+var WebSocketService = (function () {
+  var _consumer = null;
+  var _subscription = null;
+  var _connected = false;
+  var _filesChangedCallbacks = [];
+
+  // ---------------------------------------------------------------------------
+  // Internal helpers
+  // ---------------------------------------------------------------------------
+
+  function _isActionCableAvailable() {
+    return typeof window.ActionCable !== 'undefined';
+  }
+
+  function _getConsumer() {
+    // Reuse an existing consumer the host app may have already created (App.cable
+    // is the Rails default).  Fall back to creating our own.
+    if (typeof window.App !== 'undefined' && window.App.cable) {
+      return window.App.cable;
+    }
+    var cableUrl = window.MBEDITOR_CABLE_URL || '/cable';
+    return window.ActionCable.createConsumer(cableUrl);
+  }
+
+  function _emitFilesChanged(data) {
+    _filesChangedCallbacks.forEach(function (fn) {
+      try { fn(data); } catch (e) { /* ignore */ }
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  // Call once after the workspace response is received.
+  // serverSupportsWs: boolean from workspace.actionCableEnabled
+  function connect(serverSupportsWs) {
+    if (!serverSupportsWs || !_isActionCableAvailable()) {
+      return; // polling remains the only refresh mechanism
+    }
+
+    try {
+      _consumer = _getConsumer();
+      _subscription = _consumer.subscriptions.create(
+        { channel: 'Mbeditor::EditorChannel' },
+        {
+          connected: function () {
+            _connected = true;
+          },
+          disconnected: function () {
+            _connected = false;
+          },
+          rejected: function () {
+            _connected = false;
+            // Channel was rejected — unsubscribe so we stop trying.
+            if (_subscription) {
+              _subscription.unsubscribe();
+              _subscription = null;
+            }
+          },
+          received: function (data) {
+            if (data && data.type === 'files_changed') {
+              _emitFilesChanged(data);
+            }
+          }
+        }
+      );
+    } catch (e) {
+      // Any setup error means we silently stay in polling-only mode.
+      _connected = false;
+      _subscription = null;
+    }
+  }
+
+  function disconnect() {
+    if (_subscription) {
+      _subscription.unsubscribe();
+      _subscription = null;
+    }
+    _connected = false;
+  }
+
+  // Returns true only when the WebSocket is currently live.
+  function isConnected() {
+    return _connected;
+  }
+
+  // Register a callback to be invoked when the server broadcasts files_changed.
+  function onFilesChanged(fn) {
+    _filesChangedCallbacks.push(fn);
+  }
+
+  // Remove a previously registered callback.
+  function offFilesChanged(fn) {
+    _filesChangedCallbacks = _filesChangedCallbacks.filter(function (f) { return f !== fn; });
+  }
+
+  // Send a server-side channel action (e.g. 'save_state').
+  // Returns true if the message was dispatched, false if not connected.
+  function perform(action, data) {
+    if (!_subscription || !_connected) return false;
+    try {
+      _subscription.perform(action, data);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  return {
+    connect: connect,
+    disconnect: disconnect,
+    isConnected: isConnected,
+    perform: perform,
+    onFilesChanged: onFilesChanged,
+    offFilesChanged: offFilesChanged
+  };
+})();