mbeditor 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a664c7e61d20ca986be983f370ade96b639796633533373068221f45ffdbf9e
-  data.tar.gz: d9d6f92fa563330c47bc94f080432fa1e38aeddd4449b5b37f473d0555f513c5
+  metadata.gz: c8e586fb734529e92147e9fb6935782e79baeb9722c833e8df0a97cc2c86c637
+  data.tar.gz: 5da9242367bd195c715af433c8fb12fa440a610cacb5a1ff871cb8361c82233a
 SHA512:
-  metadata.gz: 0c5ed1f9375cb92b32b74fb86f76b0f98a10646e6498407b89be7b4a07f4ab4105d0bb207ce40746b33f3f34a9eaaf4ee3de16f1816a378d16b0d23f70adac04
-  data.tar.gz: 2813e2df0341112f437241f7c27537ad03f5e66da90fa756fba95647855ac6d0885421a219a0baf392e9aedcaa5c6c86e9fd4bcffacae5337ca4a8ee899e8ecb
+  metadata.gz: f403b63083bc139fc6546477c42fb476283213f0409a287ec3ffe46cc1a90cb10f197d6521216efce8121d910fdb8b2c94eefd8cd0abd8829725c852f043e57a
+  data.tar.gz: 219a64ac7ecf5e2ded2081058f64f0bb4b0ce8373eac4f3cdcd8f9ca87aacd887676e680c31f360848dbcc255cfcdd176eaf67389569c64143639bf2643538f6

data/CHANGELOG.md

@@ -5,6 +5,137 @@ 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

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,12 @@ 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
@@ -279,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
 
@@ -294,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);

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

@@ -0,0 +1,234 @@
+// CollaborationIdentity — zero-config participant identity for live collaboration
+// (slice 5/9, #56).
+//
+// Every browser gets a friendly display name and a stable colour with no setup:
+// generated once, persisted in localStorage, and editable by the user. The host
+// app can override the name through the `user_name_callback` config option — that
+// resolved value arrives via /client_config and is applied with setServerName().
+// Precedence for the effective name is: server name > user/stored name > generated.
+//
+// The colour is derived deterministically from the effective name against a fixed
+// palette, so the same name always renders in the same colour and two peers get
+// visibly distinct carets.
+var CollaborationIdentity = (function () {
+  var STORAGE_KEY = 'mbeditor.collab.identity';
+
+  // Fixed palette — distinct, saturated hues that read against the dark editor
+  // background. Index chosen deterministically from the name (see _colorFor).
+  var PALETTE = [
+    '#e06c75', '#98c379', '#e5c07b', '#61afef', '#c678dd',
+    '#56b6c2', '#d19a66', '#be5046', '#7e9cff', '#3fb950'
+  ];
+
+  var ADJECTIVES = [
+    'Swift', 'Calm', 'Bright', 'Bold', 'Quiet', 'Clever', 'Brave', 'Lucky',
+    'Sunny', 'Witty', 'Nimble', 'Mellow', 'Eager', 'Jolly', 'Keen', 'Spry'
+  ];
+  var ROLES = [
+    'Developer', 'Designer', 'Architect', 'Engineer', 'Coder', 'Hacker', 'Builder', 'Debugger',
+    'Tester', 'Analyst', 'Maker', 'Pioneer', 'Wizard', 'Operator', 'Scripter', 'Tinkerer'
+  ];
+
+  var _serverName = null;        // set by setServerName() from /client_config
+  var _stored = _load();         // { name, installId } persisted in the browser
+  var _listeners = [];           // notified when the effective identity changes
+
+  // A presence participant is one tab/cable connection, so the client id is minted
+  // once per page load (NOT persisted — two tabs of the same profile are two
+  // distinct participants). Used to key the status-bar presence roster.
+  var _clientId = _mintClientId();
+
+  function _mintId() {
+    try {
+      if (window.crypto && window.crypto.randomUUID) return window.crypto.randomUUID();
+    } catch (e) { /* fall through to Math.random */ }
+    return 'c-' + Math.random().toString(36).slice(2) + Date.now().toString(36);
+  }
+
+  function _mintClientId() {
+    return _mintId();
+  }
+
+  function _load() {
+    var obj = null;
+    try {
+      var raw = window.localStorage.getItem(STORAGE_KEY);
+      if (raw) {
+        var parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.name === 'string' && parsed.name) obj = parsed;
+      }
+    } catch (e) { /* storage unavailable / corrupt — fall through */ }
+
+    obj = obj || { name: _generateName() };
+    // Persistent per-browser id, distinct from the per-load client id. The colour
+    // is seeded from this so it survives a reload: seeding it from the client id
+    // meant every refresh handed you a new colour, and your peers watched your
+    // caret change hue for no reason. Backfilled for identities stored before
+    // this existed.
+    if (typeof obj.installId !== 'string' || !obj.installId) {
+      obj.installId = _mintId();
+    }
+    _persist(obj);
+    return obj;
+  }
+
+  function _persist(obj) {
+    try { window.localStorage.setItem(STORAGE_KEY, JSON.stringify(obj)); }
+    catch (e) { /* private mode / quota — identity still works in-memory */ }
+  }
+
+  function _generateName() {
+    var a = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    var n = ROLES[Math.floor(Math.random() * ROLES.length)];
+    return a + ' ' + n;
+  }
+
+  // Stable string hash (djb2) → palette index.
+  //
+  // Seeded on the persisted install id — not the name, and not the per-load client
+  // id. Both of those were tried and both were wrong in opposite directions:
+  // hashing the name gave two participants sharing a display name the same colour,
+  // making their carets indistinguishable exactly when you most need to tell them
+  // apart (and the generated name is one of only 128 adjective+role pairs, a host
+  // app's user_name_callback can legitimately return the same name twice, and two
+  // tabs of one browser share the stored name outright); hashing the client id
+  // fixed that but re-rolled the colour on every page load, so a reload changed
+  // your caret's hue in front of everyone you were pairing with.
+  // A peer's colour arrives from another machine and is interpolated into a
+  // stylesheet to draw their caret, so it is a trust boundary: without this,
+  // a colour of `red;} html{display:none} .x{` closes the rule and injects
+  // arbitrary CSS into your editor. Accept a hex literal or nothing.
+  var HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+  var FALLBACK_COLOR = '#888888';
+
+  function safeColor(value) {
+    return HEX_COLOR.test(String(value || '')) ? String(value) : FALLBACK_COLOR;
+  }
+
+  function _hash(seed) {
+    var h = 5381;
+    for (var i = 0; i < seed.length; i++) h = ((h << 5) + h + seed.charCodeAt(i)) | 0;
+    return Math.abs(h);
+  }
+
+  function _colorFor(seed) {
+    return PALETTE[_hash(seed) % PALETTE.length];
+  }
+
+  function _effectiveName() {
+    if (_serverName) return _serverName;
+    return _stored.name;
+  }
+
+  var _color = _colorFor(_stored.installId);
+  // Published so a colour clash resolves the same way on both sides *and* the same
+  // way after a reload. Deriving it from the install id rather than sending the id
+  // itself keeps a persistent browser identifier off the wire; all the tie-break
+  // needs is a stable number to compare.
+  var _seed = _hash(_stored.installId);
+
+  function get() {
+    return { clientId: _clientId, name: _effectiveName(), color: _color, seed: _seed };
+  }
+
+  // Hashing alone still collides: 10 palette entries and 5 participants is a ~70%
+  // chance some pair matches. The colour has to be picked *against* the roster,
+  // which only exists after connecting — so mint from the hash, then reconcile
+  // here whenever the roster changes.
+  //
+  // Called by every client on the same roster, so the rule has to be one both
+  // sides of a clash compute identically or they swap forever: on a collision the
+  // higher seed yields and the lower keeps its colour. Two yielders can briefly
+  // grab the same free slot; the next roster change re-runs this and the same
+  // tie-break settles it, so it converges rather than oscillating.
+  //
+  // Ordered on the persisted seed, falling back to the per-load client id only
+  // when seeds match (two tabs of one browser, which share stored identity). Using
+  // the client id as the primary key would decide the yielder afresh on every
+  // reload, so a clashing pair swapped colours each time either of them refreshed
+  // — the same churn that seeding the colour per-load caused.
+  //
+  // peers: [{ clientId, color, seed }] — the current roster, excluding us.
+  function _yieldsTo(peer) {
+    var mine = _seed;
+    var theirs = typeof peer.seed === 'number' ? peer.seed : -1;
+    if (theirs !== mine) return theirs < mine;
+    return String(peer.clientId) < _clientId;
+  }
+
+  function reconcileColor(peers) {
+    if (!peers || !peers.length) return;
+
+    var clash = peers.some(function (p) {
+      return p.color === _color && _yieldsTo(p);
+    });
+    if (!clash) return;
+
+    var taken = {};
+    peers.forEach(function (p) { if (p.color) taken[p.color] = true; });
+    var free = PALETTE.filter(function (c) { return !taken[c]; });
+    // More participants than colours — a duplicate is unavoidable, so keep ours
+    // rather than churn. The hover card names who is who.
+    if (!free.length) return;
+
+    var next = free[_seed % free.length];
+    if (next === _color) return;
+    _color = next;
+    _notify();
+  }
+
+  function _notify() {
+    var id = get();
+    _listeners.forEach(function (cb) {
+      try { cb(id); } catch (e) { /* a bad listener must not break the others */ }
+    });
+  }
+
+  // Host-app override (from user_name_callback via /client_config). A blank value
+  // clears the override and falls back to the stored/generated name.
+  function setServerName(name) {
+    var next = (typeof name === 'string' && name.trim()) ? name.trim() : null;
+    if (next === _serverName) return;
+    _serverName = next;
+    _notify();
+  }
+
+  // User edit of their own display name. Persisted; clears any server override so
+  // the user's explicit choice wins for the rest of the session.
+  function setName(name) {
+    var clean = (typeof name === 'string') ? name.trim() : '';
+    if (!clean) return;
+    _stored = { name: clean };
+    _persist(_stored);
+    _serverName = null;
+    _notify();
+  }
+
+  // Prompt-based editor wired to the status-bar presence chip. Returns nothing;
+  // listeners pick up the change and push it onto live awareness.
+  function editName() {
+    var current = get().name;
+    var next = window.prompt('Your collaboration name', current);
+    if (next != null) setName(next);
+  }
+
+  // Subscribe to identity changes (name or colour). Returns an unsubscribe fn.
+  function onChange(cb) {
+    if (typeof cb !== 'function') return function () {};
+    _listeners.push(cb);
+    return function () {
+      var i = _listeners.indexOf(cb);
+      if (i !== -1) _listeners.splice(i, 1);
+    };
+  }
+
+  return {
+    get: get,
+    safeColor: safeColor,
+    setName: setName,
+    setServerName: setServerName,
+    reconcileColor: reconcileColor,
+    editName: editName,
+    onChange: onChange
+  };
+})();