mbeditor 0.11.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a664c7e61d20ca986be983f370ade96b639796633533373068221f45ffdbf9e
-  data.tar.gz: d9d6f92fa563330c47bc94f080432fa1e38aeddd4449b5b37f473d0555f513c5
+  metadata.gz: b6645751ebceaf2b9754d5aabb417549334518db35027e1bd6c08d9fede2d7a5
+  data.tar.gz: edb2a8a2696f5aac16fcdcd4bbbf728f5d05a7af14ffca326a59ec7c0d40b860
 SHA512:
-  metadata.gz: 0c5ed1f9375cb92b32b74fb86f76b0f98a10646e6498407b89be7b4a07f4ab4105d0bb207ce40746b33f3f34a9eaaf4ee3de16f1816a378d16b0d23f70adac04
-  data.tar.gz: 2813e2df0341112f437241f7c27537ad03f5e66da90fa756fba95647855ac6d0885421a219a0baf392e9aedcaa5c6c86e9fd4bcffacae5337ca4a8ee899e8ecb
+  metadata.gz: 5f9d7559b69d80a1d8d9d094d5513a69048ce62ea385630ca59811e0dafd50ca65afa988e1f560cc32d78fc7b71dceedb78b30f1ba190e00b465d1026e3554d5
+  data.tar.gz: a8a3de31439ff3a937db30a04dbfd631694f50ccbcce4c3fb3571dfa66cd798cf8df29b45855467a9ff783a919893829472b241523d7230468944a3accad04f9

data/CHANGELOG.md

@@ -5,6 +5,199 @@ 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.1] - 2026-08-03
+
+### Added
+- **The collaboration name now comes from the signed-in user automatically.**
+  Previously it required a `user_name_callback`; with none set the editor fell
+  straight through to a generated name like "Witty Operator" even on an
+  authenticated instance. When no callback is configured, the name is now read
+  off `current_user`, trying `name`, `full_name`, `display_name`, `username`,
+  `login` and `email` in order. New `config.user_name_methods` names your own
+  column instead — `%w[preferred_name]` — so the common case no longer needs a
+  callback at all. An explicit `user_name_callback` still wins.
+
+  This works when your auth library exposes `current_user` to an
+  `ActionController::Base` subclass, which Devise and Sorcery do. A
+  `current_user` written by hand on your own `ApplicationController` is **not**
+  reachable — the engine's controllers do not inherit from it — so that case
+  still needs a callback reading `session` directly.
+
+### Changed
+- **The model graph is laid out by dependency, not by traversal order.** It now
+  uses the Sugiyama layered method — break cycles, layer by longest path, cut
+  crossings with the median heuristic, then straighten — which is what Graphviz
+  `dot`, and so Rails ERD, uses for this picture. The previous radial layout
+  became one enormous circle on a real schema, fitted so far out that no box was
+  legible. A model's position now tells you something: depth reads left to
+  right, and each connected part of the schema is drawn as its own area.
+
+- **Your own presence chip only appears once someone else is connected.** Action
+  Cable is up in any normal dev setup, so it used to sit in the toolbar
+  permanently announcing a session of one.
+
+### Fixed
+- **The model graph was unusable on a large schema.** On 300 models and 513
+  associations a single zoom tick cost 27 ms; it is now 0.2 ms. Three causes,
+  all compounding: the entire layout ran on every render, the pan/zoom transform
+  sat in the render output so each tick rebuilt ~7,000 SVG elements, and the
+  wheel handler read `getBoundingClientRect()` per tick, forcing a synchronous
+  reflow of the whole scene.
+- **Fit-to-pane produced a zoom the controls refused to honour.** It clamped to
+  `min(1, ...)` but not to the minimum zoom, so a large graph fitted at ~0.04
+  against a 0.2 floor — and the first scroll snapped up to the floor, a fivefold
+  jump anchored on the cursor that looked like the diagram leaping somewhere
+  random. The floor is now low enough to frame a few hundred models, and the fit
+  clamps to the same range the wheel enforces. Opening the tab also no longer
+  leaves the graph unfitted when the pane has not been sized yet.
+- **Hovering a model now shows what its associations actually are** — macro,
+  name, direction and `through:` — and dims every unrelated edge, which is the
+  only way to follow one model's relationships among hundreds of lines.
+- **Clicking a model zooms to it** instead of opening its schema; the schema is
+  an explicit button in the model's header, so navigating no longer throws a
+  modal at you.
+- **The model-graph search field drew its text over a magnifier icon.** The icon
+  comes from the vendored Pico stylesheet, whose selector outranks a plain class
+  rule — disabling the browser's own `type="search"` decorations did not touch
+  it.
+- **A failing `user_name_callback` was swallowed silently.** Any exception
+  returned a bare `nil`, which made a broken callback indistinguishable from an
+  unconfigured one: you got the generated name and no clue why. The usual cause
+  is a `NameError` on a `current_user` the engine cannot see. It is now logged
+  as `[mbeditor] user name lookup failed: ...` and still never breaks the
+  request.
+
+## [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. Search centres the view on a model; hovering an edge
+  names the relation. (Released with a radial layout; replaced by a layered one
+  in the next version — see Unreleased.)
+
+  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

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:
 
@@ -97,21 +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
@@ -147,6 +158,13 @@ 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. Only needed when the automatic lookup can't reach your user — see `user_name_methods` below. Executed via `instance_exec` inside the engine's controller (like `authenticate_with`), so it can read `session`, `cookies`, `params`, and anything your auth library exposes to an `ActionController::Base` subclass — e.g. `proc { User.find_by(id: session[:user_id])&.name }`. **It cannot see helper methods defined on your own `ApplicationController`**, because the engine's controllers do not inherit from it; a hand-rolled `current_user` living there will raise `NameError`, which is logged as `[mbeditor] user name lookup failed` and falls back to the generated name. |
+| `user_name_methods` | `%w[name full_name display_name username login email]` | Attributes tried on `current_user`, in order, when no `user_name_callback` is set — the first non-blank one becomes your collaboration display name. This is what makes an authenticated editor show real names with no extra wiring, provided your auth library exposes `current_user` to `ActionController::Base` (Devise and Sorcery do; a `current_user` you wrote yourself on `ApplicationController` does not). Set it to your own column instead of writing a callback, e.g. `%w[preferred_name]`. |
+
 ## JavaScript intelligence
 
 Under Sprockets every JS file shares one global scope, with no imports. The
@@ -279,6 +297,149 @@ 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.
+
+#### Showing real usernames
+
+Each participant's caret and presence chip are labelled. With no configuration
+the label is a generated name like *Witty Operator*, persisted per browser and
+editable by clicking your own chip.
+
+**If your auth library exposes `current_user` to controllers** — Devise and
+Sorcery both do, because they include their helpers into `ActionController::Base`
+— it already works with no configuration at all. mbeditor reads the first
+non-blank of `name`, `full_name`, `display_name`, `username`, `login`, `email`.
+
+To point it at a different column:
+
+```ruby
+Mbeditor.configure do |c|
+  c.user_name_methods = %w[preferred_name email]
+end
+```
+
+**If `current_user` is your own method on `ApplicationController`**, mbeditor
+cannot see it — the engine's controllers inherit from `ActionController::Base`,
+not from your `ApplicationController`. Resolve the user yourself instead; the
+proc runs in the engine's controller, so `session`, `cookies` and `params` are
+all available:
+
+```ruby
+Mbeditor.configure do |c|
+  c.user_name_callback = proc { User.find_by(id: session[:user_id])&.name }
+end
+```
+
+An explicit `user_name_callback` always wins over the automatic lookup. If it
+raises or returns blank you get the generated name, and the reason is logged as
+`[mbeditor] user name lookup failed: …` rather than silently swallowed.
+
+## 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
 
@@ -294,6 +455,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);