xtralab 0.2.0 → 0.4.0

package/README.md

@@ -2,153 +2,154 @@
 
 An opinionated JupyterLab meta-package.
 
-`xtralab` bundles a curated set of JupyterLab extensions, ships its own
-JupyterLab extension with a path-first file browser and a VS Code-style git
-changes panel, and applies a quieter default workspace configuration. The
-defaults are shipped under `etc/jupyter/labconfig` and the bundled
-labextension is shipped under `share/jupyter/labextensions/xtralab`.
+Bundles a curated set of extensions, a path-first file browser, a VS Code-style
+git changes panel, an agent-focused launcher, and a quieter default workspace.
 
-The goal is to keep the package easy to inspect: most behavior comes from the
-upstream Jupyter packages, while `xtralab` defines the default environment we
-want out of the box.
+![xtralab screenshot](./screenshot.png)
 
-## Approach
+## Install
 
-The package brings together:
+```bash
+pip install xtralab
+```
 
-- The `ajlab` meta-package (agent-ready JupyterLab — collaboration plumbing, MCP support, command tooling, and its own quieter defaults)
-- JupyterLab 4.6+
-- Git server integration (`jupyterlab-git` — backs the bundled changes panel)
-- Quick file opening (`jupyterlab-quickopen`)
-- Cursor styling helpers (`jupyterlab-cursor-light`, `jupyterlab-cursor-theme`)
-- Day and night themes (`jupyterlab-day`, `jupyterlab-night`)
-
-These are installed as normal Python dependencies, so deployments can still
-override versions and Jupyter configuration in the usual ways.
-
-## Bundled labextension
-
-`xtralab` ships its own prebuilt labextension that contributes:
-
-- A path-first file browser in the left sidebar, built on `@pierre/trees`.
-- A VS Code-style "Source Control" panel in the left sidebar, powered by the
-  `jupyterlab-git` server REST API and `@pierre/diffs`. The bundled
-  `@jupyterlab/git` frontend is disabled automatically so the two panels do
-  not coexist.
-- An agent-focused launcher that replaces the stock JupyterLab launcher.
-  The launcher tab shows an optional initial-prompt textarea, a row of
-  agent buttons (Claude, Codex, Gemini, Copilot, Goose, OpenCode, Kiro,
-  and Mistral Vibe), and a collapsible list of changed files (each
-  clickable into the diff viewer) below them. Clicking an agent opens a
-  fresh terminal and runs the agent's CLI; if the prompt textarea is
-  non-empty, the prompt is shell-quoted and spliced into the launch line
-  for agents that accept one. Agents are filtered by a `which`-based
-  availability check at activation, so only the ones actually installed
-  on the machine show up.
-
-### Customizing the launcher
-
-The launcher reads `xtralab:launcher` settings from the JupyterLab settings
-registry. Open the Settings Editor (`Settings → Settings Editor → xtralab
-launcher`) and edit the `agents` array; xtralab merges your entries with
-the defaults by `id`.
+## Usage
 
-```jsonc
-{
-  "agents": [
-    // Hide an agent you never want to see, even if it's installed:
-    { "id": "kiro", "enabled": false },
+### As a JupyterLab package
 
-    // Override an agent's command — e.g. point Claude at a shell alias.
-    // `requireAvailable: false` keeps the card visible even though
-    // `which cl` returns nothing (interactive shells expand the alias).
-    { "id": "claude", "command": "cl", "requireAvailable": false },
+Run JupyterLab the usual way:
 
-    // Add a brand-new agent. `iconSvg` is optional; without it the card
-    // falls back to a generic terminal icon. `promptArgs: []` means the
-    // launcher's prompt textarea is appended as a positional argument.
-    {
-      "id": "aider",
-      "label": "Aider",
-      "command": "aider",
-      "promptArgs": []
-    }
-  ]
-}
+```bash
+jupyter lab
 ```
 
-Field reference (every field except `id` is optional):
-
-| Field              | Effect                                                                                                                                                                                                                                                                                                                                             |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`               | Built-in id to override, or a new id to define a new card.                                                                                                                                                                                                                                                                                         |
-| `label`            | Card title.                                                                                                                                                                                                                                                                                                                                        |
-| `caption`          | Subtitle shown beneath the title.                                                                                                                                                                                                                                                                                                                  |
-| `command`          | Literal text typed into the new terminal.                                                                                                                                                                                                                                                                                                          |
-| `iconSvg`          | Inline SVG for the card icon (only needed for new agents).                                                                                                                                                                                                                                                                                         |
-| `rank`             | Sort order on the launcher; lower comes first.                                                                                                                                                                                                                                                                                                     |
-| `enabled`          | `false` hides the card from the launcher and palette.                                                                                                                                                                                                                                                                                              |
-| `requireAvailable` | `false` skips the `which` check (use for shell aliases that aren't on PATH but expand at runtime).                                                                                                                                                                                                                                                 |
-| `promptArgs`       | How to splice the launcher's optional prompt into the command. `[]` appends it as a positional argument (`<command> 'PROMPT'`); `["-i"]` or `["--prompt"]` puts it after a flag. Set to `null` to opt out — the agent button is dimmed when the prompt textarea is non-empty so a typed prompt is never silently dropped. Defaults vary per agent. |
-
-## Default settings
-
-`xtralab` ships the following JupyterLab defaults:
-
-- The announcements plugin is disabled, so JupyterLab does not prompt to fetch
-  news from the Jupyter news feed and does not check for application updates.
-- The Table of Contents, Debugger, and Notebook Tools panels are disabled so
-  they do not show up in the right sidebar by default.
-- `dockPanelPadding` is off, so the main dock area is flush with the
-  surrounding chrome.
-- The terminal `fontFamily` defaults to `MesloLGS NF, ui-monospace, monospace`
-  so Powerline / Nerd Font glyphs (used by Oh My Zsh themes such as
-  `powerlevel10k`) render correctly when the font is installed; the
-  `ui-monospace, monospace` fallback keeps things readable when it is not.
-
-The JupyterLab frontend defaults are shipped as `labconfig/*.d/00-xtralab.json`
-fragments so downstream meta-packages can add their own Lab configuration
-fragments without replacing `xtralab`'s files.
+### As a desktop app
 
-## Install
+A standalone Electron build (DMG on macOS, AppImage on Linux) ships with each
+tagged release — grab the installer for your platform from the
+[Releases page](https://github.com/jtpio/xtralab/releases/latest). Builds from
+the current `main` branch are also produced on every push as workflow
+artifacts under the repository's
+[Actions tab](https://github.com/jtpio/xtralab/actions). See
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the architecture and local build
+instructions.
 
-```bash
-pip install xtralab
-```
+## What's included
 
-## Run as a desktop app
+- [`ajlab`](https://github.com/jtpio/ajlab) — agent-ready JupyterLab base
+- JupyterLab 4.6+
+- `jupyterlab-git` — backs the bundled changes panel
+- `jupyterlab-lsp` + `ty` — Python LSP via Astral's `ty` (bundled); also
+  detects `typescript-language-server` on `PATH` for JS/TS
+- `jupyterlab-quickopen`
+- `jupyterlab-cursor-light`, `jupyterlab-cursor-dark`
+- `jupyterlab-day`, `jupyterlab-night` themes
+
+The bundled labextension adds:
+
+- A path-first file browser in the left sidebar.
+- A "Source Control" panel powered by `jupyterlab-git` and `@pierre/diffs`.
+- An agent launcher with a prompt textarea, a row of agent buttons (Claude,
+  Codex, Gemini, Copilot, Goose, OpenCode, Kiro, Mistral Vibe), and a
+  collapsible list of changed files. Buttons are filtered to agents installed
+  on the machine; a typed prompt is shell-quoted and spliced into the launch
+  command for agents that accept one.
+
+## Language servers
+
+xtralab ships with
+[`jupyterlab-lsp`](https://github.com/jupyter-lsp/jupyterlab-lsp) and
+pre-registers two language servers through
+`jupyter_server_config.d/xtralab-lsp.json`:
+
+- **Python — [`ty`](https://github.com/astral-sh/ty)** — installed as a
+  Python dependency. Works out of the box.
+- **TypeScript / JavaScript — `typescript-language-server`** — install
+  yourself:
+
+  ```bash
+  npm install -g typescript-language-server typescript
+  ```
+
+  Restart JupyterLab (or the desktop app) after installing.
+
+Specs use bare command names (`["ty", "server"]`), so binaries are resolved
+from `PATH` at spawn time.
+
+### Where binaries are discovered
+
+- **`pip install xtralab`** — anything on the JupyterLab process's `PATH`.
+- **Desktop app** — the supervisor augments `PATH` with common shim
+  locations (`~/.volta/bin`, `~/.npm-global/bin`, `~/.bun/bin`,
+  `~/.asdf/shims`, `~/.mise/shims`, `/opt/homebrew/bin`, `/usr/local/bin`,
+  …). Set `XTRALAB_EXTRA_PATH` (colon-separated) before launching the app
+  to add directories the defaults miss.
+
+### Adding more servers
+
+To enable another server (bash, yaml, json, dockerfile, pyright, …),
+install the binary then drop a JSON file into a `jupyter_server_config.d/`
+directory:
+
+- **`pip install xtralab`** — run `jupyter --paths` and pick a config dir
+  (typically `~/.jupyter/jupyter_server_config.d/`).
+- **Desktop app (macOS)** —
+  `~/Library/Application Support/xtralab/jupyter/config/jupyter_server_config.d/`
+  (or `xtralab dev` for local dev builds).
+- **Desktop app (Linux AppImage)** —
+  `~/.config/xtralab/jupyter/config/jupyter_server_config.d/`.
+
+Example (`bash-lsp.json`):
+
+```json
+{
+  "LanguageServerManager": {
+    "language_servers": {
+      "bash-language-server": {
+        "version": 2,
+        "argv": ["bash-language-server", "start"],
+        "languages": ["bash", "sh"],
+        "mime_types": ["text/x-sh", "application/x-sh"],
+        "display_name": "bash-language-server"
+      }
+    }
+  }
+}
+```
 
-`xtralab` ships a tiny launcher that opens JupyterLab in a dedicated Chrome
-window (via Chrome's `--app` mode), with an isolated user-data directory so it
-does not share cookies, extensions, or history with your normal browser.
+Pair with `npm install -g bash-language-server`. Reuse a bundled `key` to
+override it. See
+[jupyterlab-lsp's docs](https://jupyterlab-lsp.readthedocs.io/en/latest/Configuring.html)
+for the full spec schema.
 
-Requires Chrome or Chromium installed. macOS only for now; other platforms will be added later.
+## Customizing the launcher
 
-The simplest way, no install needed:
+Open `Settings → Settings Editor → xtralab launcher` and edit the `agents`
+array. Entries are merged with the defaults by `id`.
 
-```bash
-uvx xtralab
-```
+```jsonc
+{
+  "agents": [
+    // Hide an agent
+    { "id": "kiro", "enabled": false },
 
-Or, after `pip install xtralab` into an environment:
+    // Override an agent's command (e.g. point Claude at a shell alias)
+    { "id": "claude", "command": "cl", "requireAvailable": false },
 
-```bash
-xtralab
+    // Add a new agent; promptArgs: [] appends the prompt as a positional arg
+    { "id": "aider", "label": "Aider", "command": "aider", "promptArgs": [] }
+  ]
+}
 ```
 
-The launcher starts a local Jupyter server on a random port with a fresh
-token, waits for it to come up, opens the app window, and shuts the server
-down when you close the window. `Ctrl-C` in the launching terminal also
-shuts everything down cleanly.
+Fields: `id` (required), `label`, `caption`, `command`, `promptArgs` (how to
+splice the prompt — `[]` for positional, `["--flag"]` for flagged, `null` to
+opt out), `iconSvg`, `rank`, `enabled`, `requireAvailable`.
 
-## Development
+## Contributing
 
-```bash
-# Install dependencies and the package in editable mode
-uv pip install -e ".[dev]"
-jlpm
-jlpm build
-```
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, the
+Electron desktop app architecture, and the build pipeline.
 
 ## License
 

package/lib/editorBreadcrumbs/index.d.ts

@@ -0,0 +1,11 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Adds a VS Code-style path breadcrumb to text editor toolbars. Each
+ * segment is clickable: clicking dispatches `xtralab:reveal-path` so
+ * any plugin that listens (today, the file browser) can surface the
+ * underlying folder or file. The breadcrumbs plugin therefore does not
+ * import the file browser at all — the JupyterLab command registry is
+ * the only seam between them.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/editorBreadcrumbs/index.js

@@ -0,0 +1,41 @@
+import { DisposableDelegate } from '@lumino/disposable';
+import { EditorBreadcrumbs } from './widget';
+const PLUGIN_ID = 'xtralab:editor-breadcrumbs';
+const EDITOR_FACTORY = 'Editor';
+const TOOLBAR_ITEM_NAME = 'xtralab-editor-breadcrumbs';
+class EditorBreadcrumbsExtension {
+    constructor(commands) {
+        this._commands = commands;
+    }
+    createNew(widget, context) {
+        const breadcrumbs = new EditorBreadcrumbs({
+            context,
+            commands: this._commands
+        });
+        const added = widget.toolbar.insertItem(0, TOOLBAR_ITEM_NAME, breadcrumbs);
+        if (!added) {
+            breadcrumbs.dispose();
+            return;
+        }
+        return new DisposableDelegate(() => {
+            breadcrumbs.dispose();
+        });
+    }
+}
+/**
+ * Adds a VS Code-style path breadcrumb to text editor toolbars. Each
+ * segment is clickable: clicking dispatches `xtralab:reveal-path` so
+ * any plugin that listens (today, the file browser) can surface the
+ * underlying folder or file. The breadcrumbs plugin therefore does not
+ * import the file browser at all — the JupyterLab command registry is
+ * the only seam between them.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Display the active file path in text editor toolbars.',
+    autoStart: true,
+    activate: (app) => {
+        app.docRegistry.addWidgetExtension(EDITOR_FACTORY, new EditorBreadcrumbsExtension(app.commands));
+    }
+};
+export default plugin;

package/lib/editorBreadcrumbs/widget.d.ts

@@ -0,0 +1,34 @@
+import type { DocumentRegistry } from '@jupyterlab/docregistry';
+import type { CommandRegistry } from '@lumino/commands';
+import { Widget } from '@lumino/widgets';
+export interface IEditorBreadcrumbsOptions {
+    context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+    commands: CommandRegistry;
+}
+/**
+ * Read-only breadcrumb path for file editor toolbars.
+ *
+ * The upstream `@jupyterlab/filebrowser` BreadCrumbs widget is coupled to
+ * FileBrowserModel navigation, drag/drop, and path editing. If that code
+ * becomes reusable upstream, replace this local display-only renderer with
+ * the shared implementation.
+ */
+export declare class EditorBreadcrumbs extends Widget {
+    constructor(options: IEditorBreadcrumbsOptions);
+    dispose(): void;
+    private _onPathChanged;
+    private _render;
+    private _createRootCrumb;
+    /**
+     * Bind click and keyboard activation on a crumb element to the
+     * shared reveal command. Dispatch is best-effort: a failure to
+     * resolve or execute the command is logged but never thrown into
+     * the editor's toolbar.
+     */
+    private _attachReveal;
+    private _createSeparator;
+    private _context;
+    private _commands;
+    private _container;
+    private _content;
+}

package/lib/editorBreadcrumbs/widget.js

@@ -0,0 +1,131 @@
+import { PageConfig } from '@jupyterlab/coreutils';
+import { homeIcon as rootIcon } from '@jupyterlab/ui-components';
+import { Widget } from '@lumino/widgets';
+const EDITOR_BREADCRUMBS_CLASS = 'jp-xtralab-EditorBreadcrumbs';
+const BREADCRUMBS_CONTAINER_CLASS = 'jp-BreadCrumbs-container';
+const BREADCRUMBS_CONTENT_CLASS = 'jp-BreadCrumbs-content';
+const ROOT_CLASS = 'jp-BreadCrumbs-home';
+const ITEM_CLASS = 'jp-BreadCrumbs-item';
+const CURRENT_ITEM_CLASS = 'jp-mod-current';
+const SEPARATOR_CLASS = 'jp-BreadCrumbs-separator';
+/**
+ * Command dispatched when the user clicks a breadcrumb segment.
+ * Registered by the file browser plugin; the breadcrumbs only know
+ * the name so they stay decoupled from the file browser internals.
+ */
+const REVEAL_COMMAND = 'xtralab:reveal-path';
+/**
+ * Read-only breadcrumb path for file editor toolbars.
+ *
+ * The upstream `@jupyterlab/filebrowser` BreadCrumbs widget is coupled to
+ * FileBrowserModel navigation, drag/drop, and path editing. If that code
+ * becomes reusable upstream, replace this local display-only renderer with
+ * the shared implementation.
+ */
+export class EditorBreadcrumbs extends Widget {
+    constructor(options) {
+        super({ node: document.createElement('nav') });
+        this._context = options.context;
+        this._commands = options.commands;
+        this.addClass(EDITOR_BREADCRUMBS_CLASS);
+        this.node.setAttribute('aria-label', 'Editor file path');
+        this._container = document.createElement('span');
+        this._container.className = BREADCRUMBS_CONTAINER_CLASS;
+        this._content = document.createElement('span');
+        this._content.className = BREADCRUMBS_CONTENT_CLASS;
+        this._container.appendChild(this._content);
+        this.node.appendChild(this._container);
+        this._context.pathChanged.connect(this._onPathChanged, this);
+        this._render();
+    }
+    dispose() {
+        if (this.isDisposed) {
+            return;
+        }
+        this._context.pathChanged.disconnect(this._onPathChanged, this);
+        super.dispose();
+    }
+    _onPathChanged() {
+        this._render();
+    }
+    _render() {
+        const path = this._context.localPath || this._context.path;
+        const parts = path.split('/').filter(part => part.length > 0);
+        this.node.title = this._context.path;
+        this._content.textContent = '';
+        this._content.appendChild(this._createRootCrumb());
+        if (parts.length > 0) {
+            this._content.appendChild(this._createSeparator());
+        }
+        parts.forEach((part, index) => {
+            const isLast = index === parts.length - 1;
+            const subPath = parts.slice(0, index + 1).join('/');
+            // Canonical `@pierre/trees` paths: directories carry a trailing
+            // slash, files do not. Every part except the last names a folder
+            // along the way to the open file.
+            const canonical = isLast ? subPath : `${subPath}/`;
+            const item = document.createElement('span');
+            item.className = ITEM_CLASS;
+            item.textContent = part;
+            item.title = subPath;
+            item.tabIndex = 0;
+            item.setAttribute('role', 'button');
+            if (isLast) {
+                item.classList.add(CURRENT_ITEM_CLASS);
+                item.setAttribute('aria-current', 'page');
+            }
+            this._attachReveal(item, canonical);
+            this._content.appendChild(item);
+            if (!isLast) {
+                this._content.appendChild(this._createSeparator());
+            }
+        });
+    }
+    _createRootCrumb() {
+        const item = rootIcon.element({
+            className: ROOT_CLASS,
+            tag: 'span',
+            title: PageConfig.getOption('serverRoot') || 'Jupyter Server Root',
+            stylesheet: 'breadCrumb'
+        });
+        item.dataset.path = '/';
+        item.tabIndex = 0;
+        item.setAttribute('role', 'button');
+        // Empty canonical path: the reveal command treats this as the
+        // workspace-root gesture — surface the file browser, clear its
+        // selection, and scroll back to the top. The tree has no row for
+        // the workspace root itself.
+        this._attachReveal(item, '');
+        return item;
+    }
+    /**
+     * Bind click and keyboard activation on a crumb element to the
+     * shared reveal command. Dispatch is best-effort: a failure to
+     * resolve or execute the command is logged but never thrown into
+     * the editor's toolbar.
+     */
+    _attachReveal(element, canonicalPath) {
+        const fire = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            void this._commands
+                .execute(REVEAL_COMMAND, { path: canonicalPath })
+                .catch((err) => {
+                console.error(`xtralab: failed to reveal "${canonicalPath}"`, err);
+            });
+        };
+        element.addEventListener('click', fire);
+        element.addEventListener('keydown', event => {
+            if (event.key === 'Enter' || event.key === ' ') {
+                fire(event);
+            }
+        });
+    }
+    _createSeparator() {
+        const item = document.createElement('span');
+        item.className = SEPARATOR_CLASS;
+        item.setAttribute('aria-hidden', 'true');
+        item.textContent = '/';
+        return item;
+    }
+}

package/lib/editorIndent/index.d.ts

@@ -0,0 +1,17 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Sniff each opened document's leading whitespace and configure CodeMirror's
+ * `indentUnit` / `tabSize` to match. JupyterLab only exposes a single global
+ * indent setting, which means TypeScript files written with 4-space indent and
+ * Python files written with 2-space indent both look wrong in the same editor;
+ * detecting from the file's own content sidesteps that without forcing every
+ * project to share the same convention.
+ *
+ * Detection runs at editor-construction time and again on the first content
+ * change — that second pass exists because JupyterLab's collaborative document
+ * loader can settle the file body into the shared model after the editor view
+ * already exists, in which case the factory would otherwise have only seen an
+ * empty string.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/editorIndent/index.js

@@ -0,0 +1,142 @@
+import { EditorExtensionRegistry, IEditorExtensionRegistry } from '@jupyterlab/codemirror';
+import { indentUnit } from '@codemirror/language';
+import { Compartment, EditorState, Prec } from '@codemirror/state';
+import { ViewPlugin } from '@codemirror/view';
+import detectIndent from 'detect-indent';
+const PLUGIN_ID = 'xtralab:editor-indent';
+/**
+ * Mime types whose newly-created (or too-short-to-detect) files should default
+ * to a 2-space indent. Matches Prettier's defaults for web languages; mime
+ * types not listed here inherit whatever the user has set in JupyterLab.
+ * Covers .ts/.tsx/.jsx/.js variants registered by `@jupyterlab/codemirror`.
+ */
+const FALLBACK_INDENT_BY_MIME = {
+    'application/ecmascript': 2,
+    'application/javascript': 2,
+    'application/json': 2,
+    'application/typescript': 2,
+    'application/x-javascript': 2,
+    'application/x-json': 2,
+    'application/x-yaml': 2,
+    'text/css': 2,
+    'text/ecmascript': 2,
+    'text/html': 2,
+    'text/javascript': 2,
+    'text/jsx': 2,
+    'text/typescript-jsx': 2,
+    'text/x-markdown': 2,
+    'text/x-yaml': 2,
+    'text/yaml': 2
+};
+/**
+ * Run `detect-indent` against the file's content and convert its result into
+ * something we can hand to CodeMirror.
+ */
+function detectFromContent(text) {
+    if (text.length === 0) {
+        return null;
+    }
+    const result = detectIndent(text);
+    if (!result.type || result.amount <= 0) {
+        return null;
+    }
+    if (result.type === 'tab') {
+        // detect-indent returns `\t` for `indent` in tab mode; use a 4-column tab
+        // as the visual width, which is what most language servers assume.
+        return { unit: '\t', width: 4 };
+    }
+    return { unit: result.indent, width: result.amount };
+}
+function resolveIndent(text, mimeType) {
+    const detected = detectFromContent(text);
+    if (detected) {
+        return detected;
+    }
+    const fallback = FALLBACK_INDENT_BY_MIME[mimeType];
+    if (fallback === undefined) {
+        return null;
+    }
+    return { unit: ' '.repeat(fallback), width: fallback };
+}
+function buildExtension(resolved) {
+    // `Prec.highest` keeps these values first in their respective facets so
+    // they beat both `defaultConfig` and per-editor `editorConfig.indentUnit`,
+    // both of which JupyterLab registers at default precedence.
+    return Prec.highest([
+        indentUnit.of(resolved.unit),
+        EditorState.tabSize.of(resolved.width)
+    ]);
+}
+/**
+ * Sniff each opened document's leading whitespace and configure CodeMirror's
+ * `indentUnit` / `tabSize` to match. JupyterLab only exposes a single global
+ * indent setting, which means TypeScript files written with 4-space indent and
+ * Python files written with 2-space indent both look wrong in the same editor;
+ * detecting from the file's own content sidesteps that without forcing every
+ * project to share the same convention.
+ *
+ * Detection runs at editor-construction time and again on the first content
+ * change — that second pass exists because JupyterLab's collaborative document
+ * loader can settle the file body into the shared model after the editor view
+ * already exists, in which case the factory would otherwise have only seen an
+ * empty string.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Detect each file’s indentation style from its contents and configure CodeMirror to match; new files fall back to a language-based default.',
+    autoStart: true,
+    requires: [IEditorExtensionRegistry],
+    activate: (app, registry) => {
+        registry.addExtension({
+            name: 'xtralab:per-language-indent',
+            factory: options => {
+                const { model } = options;
+                const slot = new Compartment();
+                const initialResolved = resolveIndent(model.sharedModel.getSource(), model.mimeType);
+                const initial = initialResolved ? buildExtension(initialResolved) : [];
+                let settled = initialResolved !== null;
+                const refreshPlugin = ViewPlugin.fromClass(class {
+                    constructor(view) {
+                        this.view = view;
+                        this.disconnect = null;
+                        if (settled) {
+                            return;
+                        }
+                        const handler = () => {
+                            if (settled) {
+                                return;
+                            }
+                            const resolved = resolveIndent(model.sharedModel.getSource(), model.mimeType);
+                            if (!resolved) {
+                                return;
+                            }
+                            settled = true;
+                            view.dispatch({
+                                effects: slot.reconfigure(buildExtension(resolved))
+                            });
+                            if (this.disconnect) {
+                                this.disconnect();
+                                this.disconnect = null;
+                            }
+                        };
+                        model.sharedModel.changed.connect(handler);
+                        this.disconnect = () => {
+                            model.sharedModel.changed.disconnect(handler);
+                        };
+                    }
+                    destroy() {
+                        if (this.disconnect) {
+                            this.disconnect();
+                            this.disconnect = null;
+                        }
+                    }
+                });
+                return EditorExtensionRegistry.createImmutableExtension([
+                    slot.of(initial),
+                    refreshPlugin
+                ]);
+            }
+        });
+    }
+};
+export default plugin;