mbeditor 0.10.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47a8199a082957d396dce3cfa9de010ece11a11b2b938cf0cf81adfa6dd171f1
-  data.tar.gz: 30dfee949bc6d06245c6bd1ba5b682431b36b064e0ad510b0dac44b320c5a287
+  metadata.gz: c8e586fb734529e92147e9fb6935782e79baeb9722c833e8df0a97cc2c86c637
+  data.tar.gz: 5da9242367bd195c715af433c8fb12fa440a610cacb5a1ff871cb8361c82233a
 SHA512:
-  metadata.gz: 81c342ce0dc3f80c44259ae3a130710013dcb81f45052d4cc4488d2a7dc112f7decc6b5d67f3f6aaa81cbcd7ef391d82136ee1adccdd369b369c7cfcd4d6afa7
-  data.tar.gz: b201dda9b9fe55e9f44981725788b1587bc052f940652e8eb7d86a8dcc3d17c45bb0984f71cd3bbbd9f3a001b3b0125ac09a9e53eedd3e580eab96a445be6a17
+  metadata.gz: f403b63083bc139fc6546477c42fb476283213f0409a287ec3ffe46cc1a90cb10f197d6521216efce8121d910fdb8b2c94eefd8cd0abd8829725c852f043e57a
+  data.tar.gz: 219a64ac7ecf5e2ded2081058f64f0bb4b0ce8373eac4f3cdcd8f9ca87aacd887676e680c31f360848dbcc255cfcdd176eaf67389569c64143639bf2643538f6

data/CHANGELOG.md

@@ -5,6 +5,197 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.12.0] - 2026-07-31
+
+### Added
+- **Realtime collaborative editing (pair programming).** When Action Cable is
+  available, two or more people can open the same file and edit it together —
+  content converges through a Yjs CRDT, with live remote carets, selections and
+  a coloured name label per participant. Undo is scoped to your own edits, so
+  Ctrl+Z can never revert your partner's work. Joining late is safe: the shared
+  document wins over the copy on disk, and one save on any side settles the file
+  for everyone.
+
+  Participants appear as chips in the toolbar. A solid dot means they are in the
+  file you are looking at, a hollow ring means they are elsewhere (with their
+  filename beside it, when the toolbar is showing labels). Hovering gives their
+  name, current file and measured cable latency; clicking follows them, so their
+  file and scroll position track yours. Past three participants the chips
+  collapse to colour dots so the toolbar cannot overflow. Colours are assigned
+  against the live roster rather than hashed from the name, so two people never
+  share one while a free colour exists.
+
+  Collaboration only activates once someone else is actually connected — on your
+  own, the editor behaves exactly as before, keeping persistent undo history and
+  external-change detection.
+
+  **This is the one feature intended to be reached from another machine**, so it
+  is a deliberate exception to mbeditor's localhost-only posture. Read the
+  [Collaborative pairing](README.md#collaborative-pairing-optional) section
+  before exposing it: put it behind a trusted tunnel, set `authenticate_with`
+  (now also evaluated on the WebSocket handshake, fail-closed), restrict
+  `action_cable.allowed_request_origins`, and run a single web process. New
+  `user_name_callback` config resolves the display name from your host app.
+
+- **Drag files and folders from your desktop straight into the explorer.**
+  Drop onto a folder row to import there, or onto the empty space below the
+  tree to import into the workspace root. Folders are imported recursively.
+  Any file type works — binary content round-trips byte for byte. When a
+  target path already exists, a dialog offers Overwrite all, Keep both (which
+  writes `name 2.ext` beside the original), or Skip. Imports are capped at 100
+  files and 50 MB per drop, and 5 MB per file, and every target path goes
+  through the same sandbox checks as every other file operation.
+
+- **A model graph — an entity diagram of the host app's ActiveRecord models.**
+  The activity-bar button opens it as a full-width editor tab, drawing each
+  model with its fields and laying them out radially around whichever model has
+  the most associations. Search centres the view on a model; hovering an edge
+  names the relation.
+
+  Associations are read by **reflection, not by parsing model files**. mbeditor
+  runs inside the host app, so `reflect_on_all_associations` is right there and
+  resolves `class_name:`, `through:`, polymorphic and inverse sides correctly —
+  all of which regex or AST parsing of `has_many` lines silently gets wrong.
+  The graph never touches the database connection, so it works against a
+  database that isn't running or migrated. It is built only when the tab is
+  opened (it eager-loads the host app) and cached on a fingerprint of
+  `app/models` and `db/migrate`, so saving a model invalidates it. It also
+  writes `tmp/mbeditor_model_graph.mmd`, a Mermaid `erDiagram` that GitHub and
+  VS Code render natively.
+
+- **Ruby navigation through real Monaco providers.** Go-to-definition was
+  hand-wired per editor with an `onMouseDown` and an `addAction`, so Monaco
+  never knew Ruby had definitions and peek-definition, Ctrl+hover previews and
+  the references widget all did nothing. Definition, references, document
+  symbols, folding, highlights, rename, formatting, signature help and
+  selection ranges are now registered providers, fed by a raw ruby-lsp
+  passthrough instead of a bespoke translator per method.
+
+  - **F2 renames a Ruby constant across the workspace.** Open files get their
+    edits back for Monaco to apply, so the change is undoable and marks the tab
+    dirty; closed files are written server-side. That split is what keeps
+    unsaved work safe — anything dirty is by definition open.
+  - **Shift+Alt+F and format-on-save now work for Ruby.**
+  - **RuboCop fixes apply straight from the diagnostic.** The edits are already
+    in the diagnostics response, so the lightbulb no longer makes a second
+    request or spawns a `rubocop -A` over the buffer on every click. "Disable
+    <cop> for this line" comes from the same payload.
+  - **Diagnostics are graded Error / Warning / Info / Hint** instead of
+    everything non-error being one yellow warning, and unnecessary code is
+    faded rather than squiggled. A status-bar chip shows ruby-lsp health.
+
+- **Host-app exceptions appear in the Problems panel.** A failed request used to
+  show up only in the log. Controller exceptions are now listed with clickable
+  backtrace frames and pushed live over the existing cable channel. Backtraces
+  are filtered to frames under the workspace root and capped, since absolute
+  host paths are both a leak and unopenable. Development only, and
+  `config.exception_capture = false` disables it.
+
+- **PageUp/PageDown cycle between the cursor and the last jump origin.**
+  Opening a file at a line — go-to-definition, a search result, a hover link —
+  snapshots where you came from, and PageUp/PageDown swap between the two.
+  Replaces the default page-scroll binding.
+
+### Changed
+- **Search is dramatically faster on host apps without ripgrep**, where it was
+  effectively unusable. Three separate causes, all on the `git grep` tier:
+  the exclusion list was computed and then never put on the command line, so
+  git walked `node_modules` in full and the results were discarded afterwards;
+  `search_respect_gitignore` defaulted to `false`, which asks git to search
+  every ignored tree the app has; and `LC_ALL=C` was set, measured neutral for
+  the default and 2.2× *slower* for regex. Measured 3714 files walked → 253.
+  `search_respect_gitignore` now defaults to `true`, matching VS Code and
+  ripgrep. `GET /workspace` reports `searchBackend` so the live tier is visible,
+  and `ripgrep_command` now resolves the usual install prefixes as well as
+  `PATH` — a server started from launchd, systemd or an IDE has a stripped
+  `PATH`, which silently dropped search to the 10–30× slower tier.
+
+- **Assignments to undeclared variables are reported as errors.** `foo = 1`
+  with no declaration anywhere is an implicit global the host's Babel pipeline
+  rejects, so it keeps Error severity with an explanatory hint. Read-side
+  unknowns still downgrade to a warning, since those are usually host globals
+  the language service cannot see.
+
+### Fixed
+- **The bottom drawers covered the code instead of making room for it.** The
+  log and problems drawers were absolutely positioned, so they sat on top of
+  what you were reading. They are now ordinary flow siblings of the split
+  panes, so opening one shrinks the editor.
+- **"Changes in Branch" showed nothing on a branch well ahead of the base.**
+  With no base branch resolved it fell back to diffing against the branch's
+  upstream — which for a feature branch is its own remote copy, reliably empty.
+  Every layer then degraded to empty rather than erroring, so it looked like
+  there were no changes.
+- **The What's New tab was wiped by the session restore** when it opened on a
+  version change.
+- **An idle editor no longer re-renders.** Polls that found nothing changed were
+  still writing fresh objects into state — the file tree every 10 s and the
+  ruby-lsp health chip every 10 s — each costing a full reconciliation of a
+  tree that had not changed. Verified by counting React renders over an idle
+  minute: now zero.
+
+## [0.11.0] - 2026-07-29
+
+### Added
+- **Real types for your own JavaScript, from your own JavaScript.** The
+  workspace's JS source is now loaded into Monaco's TypeScript program instead
+  of being grepped for names and declared as ambient `any`. Under Sprockets a
+  JS file with no `import`/`export` is a TypeScript *script*, so its top-level
+  declarations land in the global scope — which is exactly the Sprockets model.
+  Cross-file references now get inferred signatures, member completion, and
+  argument-count checking, and genuine unknowns still report `Cannot find
+  name`:
+
+  ```jsx
+  var c = <Card title="x" />;   // Card: (props: any) => JSX.Element
+  var s = formatCents(500);     // formatCents(value: any): string
+  var t = formatCents(1, 2);    // Expected 0-1 arguments, but got 2
+  ```
+
+  Two new options: `config.js_program` (default `true`) and
+  `config.js_program_exclude` (default `%w[vendor]`, added on top of
+  `excluded_paths`). Measured at ~93 ms/MB to build and ~30 ms per file
+  afterwards, so a ~10 MB tree costs under a second, once; only changed files
+  are re-sent after that.
+
+  Ambient declarations are still used for what a program cannot express.
+  TypeScript only sees *lexical* declarations: `window.Foo = ...` is not a
+  declaration to it, and UMD-wrapped libraries assign their global inside a
+  closure — `factory(global.React = {})` — which it cannot follow statically.
+  Their source contributes nothing, which is why vendored code is excluded by
+  default and React stays typed by a bundled stub. Point
+  `js_program_exclude` at any other third-party or generated JS.
+- **A whitespace toggle in the status bar** (¶), showing tabs, spaces and
+  hidden characters in the active editor.
+
+### Fixed
+- **The editor became very slow on JSX files with many unresolved names.**
+  Opening such a file fired one `/js_definition` request per unknown symbol,
+  in parallel — each spawning an `rg` process — and called `addExtraLib` once
+  per resolution, re-validating every open model each time. A file with a
+  thousand warnings meant a thousand greps saturating the dev server and a
+  thousand full TypeScript re-validations. That starved the file-tree poll,
+  git status, and saves behind it. Lookups are now serialized and capped, and
+  the declaration updates are coalesced into a single flush.
+- **Minified bundles crowded out the workspace's real globals.** A minified
+  file is one enormous line that usually opens with `var a,b,c,…` running to
+  thousands of declarators; split on commas, that single line exhausted the
+  3000-symbol cap before the scan reached your own components, so every
+  reference to them showed "Cannot find name". Declaring `a`/`n`/`t` as
+  ambient `any` also silenced real diagnostics for those names everywhere.
+  Minified files are now skipped by filename and by shape, and the endpoint
+  reports `truncated` so a workspace that outgrows the cap is diagnosable
+  instead of silently incomplete.
+- **"File was edited externally" appeared for files nothing had touched.** The
+  check compared the file on disk against the editor buffer — which differ for
+  every unsaved tab by definition — so saving one file broadcast a change that
+  flagged every *other* dirty tab. It now compares disk against the last disk
+  content seen, so only a real on-disk change raises the banner.
+
+---
+
 ## [0.10.1] - 2026-07-27
 
 ### Removed

data/README.md

@@ -25,6 +25,14 @@ Mbeditor exposes read and write access to your Rails application directory over
 - Always keep it in the development group in your Gemfile.
 - The engine enforces environment restrictions at runtime, and Gemfile scoping is a second line of defense that keeps the gem out of deploy builds.
 
+> **Pairing crosses the localhost-only boundary by design.** Realtime collaborative
+> editing (see [Collaborative pairing](#collaborative-pairing-optional)) is meant to
+> be reached by a second person, so it necessarily exposes the editor beyond your own
+> machine. Treat that as an explicit, deliberate exception to the rules above — confine
+> exposure to a trusted tunnel or LAN, set an authentication hook, and tear it down when
+> you finish pairing. It does not change the core rule: mbeditor is development-only and
+> must never be reachable by untrusted users.
+
 ## Installation
 1. Add the gem to the host app Gemfile in development only:
 
@@ -77,6 +85,10 @@ Mbeditor.configure do |config|
   # config.ruby_def_include_dirs = %w[app/models app/controllers app/helpers app/concerns]
   # config.related_files_custom_paths = %w[app/assets/javascripts/app app/policies]
 
+  # JavaScript intelligence (see the "JavaScript intelligence" section below)
+  # config.js_program = false                                        # disable the source program entirely
+  # config.js_program_exclude = %w[vendor app/assets/javascripts/react]  # third-party/generated JS
+
   # Resilient routing (see the "Resilient Routing" section below)
   # config.mount_path = "/mbeditor"   # explicit prefix override; auto-detected when nil
   # config.resilient_routing = false  # escape hatch; true keeps the editor up when host routes break
@@ -93,19 +105,24 @@ end
 | `rubocop_command` | `"rubocop"` | Command used for inline Ruby linting and formatting. |
 | `git_timeout` | `10` | Seconds each git subprocess may run; a timed-out call degrades its own field of the git panel instead of failing the request. `nil` disables the bound. |
 | `search_timeout` | `15` | Wall-clock bound on project-search subprocesses; a tripped deadline returns the partial results collected so far. `nil` disables. |
-| `search_respect_gitignore` | `false` | When `true`, project search and definition lookups skip files ignored by `.gitignore`. The default searches them, matching the editor's "show me everything on disk" behaviour. |
+| `search_respect_gitignore` | `true` | Project search and definition lookups skip files ignored by `.gitignore`, matching VS Code and ripgrep. Set to `false` to search ignored files too — expect it to be slow without ripgrep installed, since git then has to walk `node_modules`, `public/packs`, build output and caches. |
+| `ripgrep_command` | `nil` | Path to the `rg` binary. `nil` auto-resolves: `PATH` first, then the usual install prefixes (`/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, linuxbrew, cargo). Set this if ripgrep lives somewhere unusual. See [Search performance](#search-performance). |
 | `js_global_identifiers` | `[]` | Extra JS names declared as ambient globals in the editor — for runtime-only globals the static workspace scan can't see (e.g. `%w[Routes I18n]`). |
+| `js_program` | `true` | Load the workspace's own JS source into Monaco's TypeScript program, so cross-file references get real inferred types instead of ambient `any`. See [JavaScript intelligence](#javascript-intelligence). `false` falls back to ambient declarations alone. |
+| `js_program_exclude` | `%w[vendor]` | Directories excluded from that program, on top of `excluded_paths`. Point this at any third-party or generated JS — vendored libraries are UMD-wrapped, so their source costs parse time and contributes no globals. |
 | `js_syntax_check` | `:auto` | Save-time babel parse check for JS/JSX using the host's `mini_racer` + babel-standalone (auto-detected; no-op when either is absent). `false` disables. |
 | `babel_standalone_path` | `nil` | Explicit path to the babel-standalone bundle for the syntax check; `nil` looks up `babel.min.js`/`babel.js` in the host's asset pipeline. |
-| `ruby_lsp` | `:auto` | Use the host's [ruby-lsp](https://github.com/Shopify/ruby-lsp) for Ruby go-to-definition, hover, completion, and diagnostics when it's installed (a persistent process is managed per workspace). `false` disables. Without ruby-lsp everything degrades to the built-in grep/Ripper services — no behavior change. |
+| `ruby_lsp` | `:auto` | Use the host's [ruby-lsp](https://github.com/Shopify/ruby-lsp) for Ruby go-to-definition (with peek), find-references, hover, completion, diagnostics, document symbols, folding, formatting, signature help, smart-select, and constant rename when it's installed (a persistent process is managed per workspace). `false` disables. Without ruby-lsp everything degrades to the built-in grep/Ripper services — no behavior change. Adding `ruby-lsp-rails` to your Gemfile needs no configuration here: ruby-lsp loads it as an addon and its Rails-aware results come through automatically. |
 | `ruby_lsp_command` | `nil` | Override the ruby-lsp launch command (String or Array). `nil` auto-resolves `bin/ruby-lsp` → installed gem → `bundle exec ruby-lsp`. |
 | `ruby_lsp_timeout` | `3` | Seconds per LSP request; on timeout (e.g. during initial indexing) the editor falls back to the built-in services for that request. |
+| `model_graph` | *(no setting)* | The Models sidebar tab draws an entity diagram of your ActiveRecord models and their associations, read by reflection when the tab is opened. Pan by dragging, zoom by scrolling, click a model for its schema. Also writes `tmp/mbeditor_model_graph.mmd`, a Mermaid ER diagram that GitHub and VS Code render natively. Needs no configuration; apps without ActiveRecord simply see a message. |
+| `exception_capture` | `:auto` | Record exceptions raised by your controllers and list them in the Problems panel, with clickable backtrace frames. Development only; backtraces are trimmed to frames inside the workspace. `false` disables. Note exception messages can include request params — the same exposure the log panel already has. |
 
 ### Authentication
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `authenticate_with` | `nil` | Proc run as a `before_action` in all engine controllers. Executed via `instance_exec` inside the controller, so it has access to `session`, `cookies`, `redirect_to`, and auth-library class methods (e.g. Authlogic's `UserSession.find`) — but not helper methods from the host's `ApplicationController`. |
+| `authenticate_with` | `nil` | Proc run as a `before_action` in all engine controllers. Executed via `instance_exec` inside the controller, so it has access to `session`, `cookies`, `redirect_to`, and auth-library class methods (e.g. Authlogic's `UserSession.find`) — but not helper methods from the host's `ApplicationController`. The same hook is also evaluated when the collaboration / editor **WebSocket** subscribes (see [Collaborative pairing](#collaborative-pairing-optional)); if it halts or raises, that subscription is rejected (fail-closed). Over the cable the proc runs against a request-derived probe, so request-scoped state may be narrower than over HTTP. |
 | `authentication_cache_ttl` | `0` | Seconds to cache the auth result in the session (`0` = no caching). Set e.g. `300` to avoid calling `authenticate_with` on every request when the proc is expensive. Trade-off: after host logout, mbeditor stays accessible for up to TTL seconds. |
 
 ### Test runner
@@ -141,6 +158,79 @@ See [Resilient Routing](#resilient-routing) for details.
 | `mount_path` | `nil` | Explicit URL prefix to serve resilient routing from. When `nil`, auto-detected from your `mount Mbeditor::Engine, at: "..."` line on every healthy boot. Set only to override detection. |
 | `resilient_routing` | `true` | Keeps mbeditor reachable when the host's `config/routes.rb` is broken, by serving its traffic from middleware that dispatches to a private route set. Set to `false` as an escape hatch: no middleware is inserted and the private set is never built. |
 
+### Collaboration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `user_name_callback` | `nil` | Proc resolving the display name shown on your caret during realtime collaboration. Executed via `instance_exec` inside the controller (like `authenticate_with`), so it can read `session`, `cookies`, `current_user`, etc. — e.g. `proc { current_user&.name }`. When `nil` or it returns a blank value, each browser falls back to a generated, locally-persisted, user-editable name. Collaboration activates once another participant actually connects, not merely when Action Cable is up (see [Collaborative pairing](#collaborative-pairing-optional)). |
+
+## JavaScript intelligence
+
+Under Sprockets every JS file shares one global scope, with no imports. The
+editor models that in two layers.
+
+**1. The source program.** Your workspace's own JS is loaded into Monaco's
+TypeScript program. A JS file with no `import`/`export` is a TypeScript
+*script*, so its top-level declarations land in the global scope — which is
+exactly the Sprockets model. You get real inferred types across files:
+
+```jsx
+// app/assets/javascripts/ux/Card.jsx
+var Card = function (props) { return <div>{props.title}</div>; };
+function formatCents(value) { return "$" + (value / 100).toFixed(2); }
+```
+
+```jsx
+// somewhere else — no import needed
+var c = <Card title="x" />;      // Card: (props: any) => JSX.Element
+var s = formatCents(500);        // formatCents(value: any): string
+var t = formatCents(1, 2);       // Expected 0-1 arguments, but got 2
+```
+
+Unknown names still report `Cannot find name` — this adds type information, it
+doesn't silence errors.
+
+**2. Ambient declarations**, for names the program can't supply.
+
+Both layers are needed, because TypeScript only sees *lexical* declarations:
+
+- `window.Foo = ...` is a runtime global TypeScript does not treat as a
+  declaration at all.
+- UMD-wrapped libraries — React, lodash, axios — assign their global inside a
+  closure, `factory(global.React = {})`, which TypeScript cannot follow
+  statically. **Loading their source gets you nothing**, which is why
+  `js_program_exclude` defaults to `vendor` and why React is typed by a
+  bundled stub instead.
+
+So point `js_program_exclude` at directories of third-party or generated JS,
+and leave your own application code in:
+
+```ruby
+config.js_program_exclude = %w[vendor app/assets/javascripts/react]
+```
+
+### Cost
+
+Measured against the Monaco TypeScript worker:
+
+| program size | build | per file opened after |
+|---|---|---|
+| 1 MB | 210 ms | 9 ms |
+| 3 MB | 378 ms | 11 ms |
+| 5.5 MB | 443 ms | 23 ms |
+| 9.4 MB | 872 ms | 32 ms |
+
+Roughly 93 ms/MB, paid once per session. JS gzips about 4.5:1, so a 10 MB tree
+is ~2.2 MB over the wire — worth knowing if your app runs on a remote host.
+After the initial load only changed files are re-sent, never the whole tree.
+
+Nothing is truncated silently: the browser console logs the file count, total
+size, and every skipped file with a reason (minified, oversized, unreadable).
+Minified bundles are skipped by filename and by shape, since they cost parse
+time and declare only one-letter names inside a closure.
+
+Set `config.js_program = false` to disable the layer entirely.
+
 ## Test Runner
 
 The Test button appears in the editor toolbar for any `.rb` file when a `test/` or `spec/` directory exists in the workspace root. Clicking it:
@@ -206,6 +296,113 @@ The gem keeps host/tooling responsibilities in the host app:
 
 All lint and test tools are auto-detected at runtime. The engine gracefully disables features if the tools are not available. Neither `rubocop`, `haml_lint`, nor any test framework are runtime dependencies of the gem itself — they are discovered from the host app's environment.
 
+### Realtime via Action Cable (Optional)
+
+Mbeditor works without Action Cable. If Action Cable is unavailable, unreachable, or returns transient errors, the editor automatically falls back to polling.
+
+To enable realtime features in a host app:
+
+1. Ensure Action Cable is enabled in the host app (for apps that do not load it by default, add the framework/gem explicitly).
+2. Mount cable in host routes:
+
+```ruby
+mount ActionCable.server => '/cable'
+```
+
+3. Make Action Cable JavaScript available to the page (for asset-pipeline apps, `actioncable.js` is typically sufficient).
+
+If any of these are missing, mbeditor still runs in polling mode.
+
+### Collaborative pairing (Optional)
+
+When Action Cable is available, mbeditor supports **realtime collaborative editing** —
+live cursors and content sync over a WebSocket, so a second person can join the same
+files. This is the one feature intended to be reached from another machine, so exposing
+it is a **deliberate exception** to the localhost-only [Security Warning](#security-warning)
+above. Expose it narrowly and only while you are actively pairing.
+
+Collaboration activates only once **another participant is actually connected**, not
+merely because Action Cable is up. On your own the editor behaves exactly as it does
+without cable — persistent undo history and external-change detection stay in force,
+both of which defer to the shared document while a session is live.
+
+**1. Restrict the network exposure to a trusted path.**
+Put the editor behind a **trusted tunnel** (e.g. an authenticated `ngrok`/Tailscale/
+Cloudflare tunnel, or SSH port-forward) or keep it on a **trusted LAN**. Never bind it to
+a public interface or an untrusted network. The person you pair with is the only one who
+should be able to reach the port.
+
+**2. Set an authentication hook — it runs on the WebSocket handshake.**
+Configure `authenticate_with` (see the [Authentication](#authentication) options).
+The same hook that gates the HTTP editor is now also evaluated when the collaboration /
+editor WebSocket subscribes: if it halts (e.g. `redirect_to`/`render`/`head`) — or raises —
+the socket subscription is **rejected (fail-closed)**, so pairing cannot bypass your auth.
+
+```ruby
+Mbeditor.configure do |c|
+  # Runs as a controller before_action AND on the cable subscribe.
+  c.authenticate_with = proc { head :forbidden unless UserSession.find }
+end
+```
+
+Because the cable mount can bypass parts of the host middleware stack, a hook that leans on
+request-scoped state (full `session`, encrypted `cookies`) may see less over the WebSocket
+than it does over HTTP. For defence in depth, also authenticate at your host app's
+`ApplicationCable::Connection` (the standard `identified_by` / `reject_unauthorized_connection`
+pattern) — mbeditor's hook is an additional gate, not a replacement for securing the cable
+connection itself.
+
+**3. Configure Action Cable allowed request origins.**
+Action Cable rejects cross-origin WebSocket connections. When you reach the editor through a
+tunnel or LAN host, that origin must be allowed, or the socket silently fails and pairing
+falls back to single-user mode. Allow exactly the origin(s) you pair through — never `/.*/`:
+
+```ruby
+# config/environments/development.rb
+config.action_cable.allowed_request_origins = [
+  "https://your-pairing-tunnel.example.com",
+  %r{https://.*\.trusted-lan\.local}
+]
+```
+
+When you finish pairing, close the tunnel / stop the forward so the editor is local-only again.
+
+**4. Run a single web process.**
+The shared document buffer is held in process memory and relayed over Action Cable's
+default in-process (`async`) adapter, so collaboration state is **per-process**. If your
+server runs multiple workers (e.g. Puma with `workers > 0` / `WEB_CONCURRENCY`), two
+browsers can land on different workers and each see an empty or stale document — the most
+common cause of *"the other person's edits never show up."* For pairing, run a single
+worker (`WEB_CONCURRENCY=0`, or `bundle exec rails server` which is single-process by
+default). A multi-worker setup would additionally need a cross-process cable adapter, but
+the in-memory buffer still would not be shared — single-process is the supported mode.
+## Search performance
+
+Project search and JS definition lookups pick a backend per call:
+**ripgrep → `git grep` → `grep`**. ripgrep is 10–30× faster than the fallbacks,
+so installing it is the single biggest thing you can do for search speed:
+
+```bash
+brew install ripgrep      # macOS
+apt install ripgrep       # Debian/Ubuntu
+```
+
+`GET /mbeditor/workspace` reports `searchBackend` (`"rg"`, `"git"` or `"grep"`)
+so you can check which tier is actually in use. Two things commonly make it
+`"git"` when you expected `"rg"`:
+
+- **ripgrep isn't on the server process's `PATH`.** A Rails server started from
+  launchd, systemd, foreman or an IDE inherits a stripped `PATH` that often
+  omits `/opt/homebrew/bin`. Mbeditor probes the usual install prefixes as well
+  as `PATH`; if yours is elsewhere, set `config.ripgrep_command`.
+- **ripgrep genuinely isn't installed.** The `git grep` tier is then used. It
+  honours `excluded_paths` and `.gitignore`, so it stays usable — but it is
+  still far slower than ripgrep on a large workspace.
+
+If search is slow, check `searchBackend` first, then confirm your build output
+(`public/packs`, `app/assets/builds`, bundler/npm caches) is either gitignored
+or listed in `excluded_paths`. Setting `search_respect_gitignore = false` makes
+git walk every ignored tree and will be slow without ripgrep.
 
 ## Asset Pipeline
 
@@ -221,6 +418,32 @@ cd test/dummy && rails server
 
 Then visit http://localhost:3000/mbeditor.
 
+### Vendored JavaScript (no consumer build step)
+
+All third-party JS is **prebuilt and committed** under `vendor/assets/javascripts/`
+and served as-is by Sprockets. Installing the gem needs **zero JS tooling** — no
+Node, npm, or bundler — which is the contract recorded in
+[ADR-0001](docs/adr/0001-no-frontend-build-step.md). `package.json` exists only as
+a dependency manifest for `npm audit`.
+
+Most vendored libs are committed verbatim from npm. The one exception is the
+collaborative-editing bundle, `vendor/assets/javascripts/yjs-collab.js`, which
+combines Yjs + y-monaco + y-protocols (awareness) into a single IIFE exposing
+`window.Y`, `window.MonacoBinding`, and `window.awarenessProtocol`. It is produced
+by a **maintainer-only** build script. Monaco itself is not bundled — the binding
+forwards to the page's runtime `window.monaco`.
+
+To regenerate it after bumping any of those pinned versions in `package.json`:
+
+```bash
+npm install          # installs yjs / y-monaco / y-protocols + esbuild (maintainer-only)
+npm run build:yjs    # === node script/build-yjs-bundle.mjs
+```
+
+then commit the regenerated `vendor/assets/javascripts/yjs-collab.js`. The build is
+deterministic: rebuilding from the same pinned versions reproduces identical bytes.
+This step is for maintainers only; it never runs on a consumer's machine.
+
 ## Testing
 
 The test suite uses Minitest via the dummy Rails app. Run all tests from the project root:

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

@@ -2,6 +2,7 @@
 //= require mbeditor/editor_store
 //= require mbeditor/file_icon
 //= require mbeditor/file_service
+//= require mbeditor/file_import
 //= require mbeditor/history_service
 //= require mbeditor/websocket_service
 //= require mbeditor/git_service
@@ -9,6 +10,8 @@
 //= require mbeditor/conflict_parser
 //= require mbeditor/search_service
 //= require mbeditor/tab_manager
+//= require mbeditor/collaboration_identity
+//= require mbeditor/collaboration_service
 //= require mbeditor/color_provider
 //= require mbeditor/editor_plugins
 //= require mbeditor/ruby_outline
@@ -18,6 +21,7 @@
 //= require mbeditor/components/DiffViewer
 //= require mbeditor/components/CombinedDiffViewer
 //= require mbeditor/components/CommitGraph
+//= require mbeditor/components/ModelGraph
 //= require mbeditor/components/ChangelogView
 //= require mbeditor/components/FileHistoryPanel
 //= require mbeditor/components/TestResultsPanel
@@ -31,3 +35,4 @@
 //= require mbeditor/components/TabBar
 //= require mbeditor/components/MbeditorApp
 //= require mbeditor/application_iife_tail
+//= require mbeditor/components/ImportConflictModal

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

@@ -1,4 +1,10 @@
 window.SearchService = SearchService;
 window.GitService = GitService;
 window.FileService = FileService;
+// Exposed for system tests to observe collaboration state and drive store updates
+// (same test-seam convention as the services above).
+window.EditorStore = EditorStore;
+window.CollaborationService = CollaborationService;
+window.CollaborationIdentity = CollaborationIdentity;
+window.WebSocketService = WebSocketService;
 })(window.MbeditorRuntime.React, window.MbeditorRuntime.ReactDOM);