xtralab 0.3.0 → 0.5.0

package/README.md

@@ -2,8 +2,11 @@
 
 An opinionated JupyterLab meta-package.
 
-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.
+Bundles a curated set of extensions, a path-first file browser, the
+`jupyterlab-git` panel with its text, notebook and image diffs rendered by
+xtralab, an agent-focused launcher, and a quieter default workspace.
+
+![xtralab screenshot](./screenshot.png)
 
 ## Install
 
@@ -36,7 +39,8 @@ instructions.
 
 - [`ajlab`](https://github.com/jtpio/ajlab) — agent-ready JupyterLab base
 - JupyterLab 4.6+
-- `jupyterlab-git` — backs the bundled changes panel
+- `jupyterlab-git` — provides the git panel; xtralab swaps its text,
+  notebook and image diff rendering for its own
 - `jupyterlab-lsp` + `ty` — Python LSP via Astral's `ty` (bundled); also
   detects `typescript-language-server` on `PATH` for JS/TS
 - `jupyterlab-quickopen`
@@ -46,7 +50,10 @@ instructions.
 The bundled labextension adds:
 
 - A path-first file browser in the left sidebar.
-- A "Source Control" panel powered by `jupyterlab-git` and `@pierre/diffs`.
+- xtralab-rendered diffs registered as `jupyterlab-git`'s diff providers
+  (its own notebook/plain-text/image diff plugins are disabled) so the
+  upstream git panel shows xtralab's diffs: `@pierre/diffs` for text and
+  notebooks, and an `<img>`-based 2-up/swipe/onion-skin view for images.
 - 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

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;

package/lib/fileBrowser/commands.d.ts

@@ -16,8 +16,10 @@ export declare namespace CommandIDs {
     const copyPath = "xtralab:copy-path";
     const download = "xtralab:download";
     const refresh = "xtralab:refresh";
+    const collapseAll = "xtralab:collapse-all";
     const createNewDirectory = "xtralab:create-new-directory";
     const newLauncher = "xtralab:new-launcher";
+    const revealPath = "xtralab:reveal-path";
 }
 /**
  * Submenu id used to host the dynamically populated "Open With" entries.
@@ -49,6 +51,7 @@ export declare namespace ToolbarNames {
     const newLauncher = "new-launcher";
     const newDirectory = "new-directory";
     const refresh = "refresh";
+    const collapseAll = "collapse-all";
 }
 /**
  * Populate the file browser's toolbar with the buttons that mirror the

package/lib/fileBrowser/commands.js

@@ -1,7 +1,8 @@
 import { Clipboard, Dialog, InputDialog, showDialog, showErrorMessage } from '@jupyterlab/apputils';
 import { PageConfig, PathExt } from '@jupyterlab/coreutils';
-import { addIcon, closeIcon, CommandToolbarButton, copyIcon, downloadIcon, editIcon, fileIcon, newFolderIcon, refreshIcon } from '@jupyterlab/ui-components';
+import { addIcon, closeIcon, collapseAllIcon, CommandToolbarButton, copyIcon, downloadIcon, editIcon, fileIcon, newFolderIcon, refreshIcon } from '@jupyterlab/ui-components';
 import { toCanonicalPath, toServerPath } from './contents';
+import { FILE_BROWSER_ID } from './widget';
 /**
  * Command identifiers exposed by the xtralab browser. We deliberately namespace
  * these under `xtralab:` rather than reusing the `filebrowser:` ids
@@ -19,8 +20,10 @@ export var CommandIDs;
     CommandIDs.copyPath = 'xtralab:copy-path';
     CommandIDs.download = 'xtralab:download';
     CommandIDs.refresh = 'xtralab:refresh';
+    CommandIDs.collapseAll = 'xtralab:collapse-all';
     CommandIDs.createNewDirectory = 'xtralab:create-new-directory';
     CommandIDs.newLauncher = 'xtralab:new-launcher';
+    CommandIDs.revealPath = 'xtralab:reveal-path';
 })(CommandIDs || (CommandIDs = {}));
 /**
  * Submenu id used to host the dynamically populated "Open With" entries.
@@ -331,6 +334,36 @@ export function registerCommands(opts) {
             browser.refresh();
         }
     });
+    commands.addCommand(CommandIDs.collapseAll, {
+        label: 'Collapse All Folders',
+        caption: 'Collapse all folders in the file browser',
+        icon: collapseAllIcon.bindprops({ stylesheet: 'menuItem' }),
+        execute: () => {
+            browser.collapseAll();
+        }
+    });
+    // Public reveal seam. Other plugins (editor breadcrumbs, future
+    // "reveal in tree" actions) call this command rather than depending
+    // on the file browser widget directly. Activating the sidebar is part
+    // of the contract: the tree is hidden behind a tab and a reveal that
+    // does not surface the panel would silently no-op from the user's
+    // point of view. An empty path is the "workspace root" gesture —
+    // there is no tree row for the root itself, so the browser is asked
+    // to scroll back to the top and clear its selection instead.
+    commands.addCommand(CommandIDs.revealPath, {
+        label: 'Reveal in File Browser',
+        execute: (args) => {
+            var _a;
+            const path = (_a = args.path) !== null && _a !== void 0 ? _a : '';
+            app.shell.activateById(FILE_BROWSER_ID);
+            if (path.length === 0) {
+                browser.scrollToRoot();
+            }
+            else {
+                browser.reveal(path);
+            }
+        }
+    });
     commands.addCommand(CommandIDs.createNewDirectory, {
         label: 'New Folder',
         caption: 'Create a new folder',
@@ -390,6 +423,7 @@ export var ToolbarNames;
     ToolbarNames.newLauncher = 'new-launcher';
     ToolbarNames.newDirectory = 'new-directory';
     ToolbarNames.refresh = 'refresh';
+    ToolbarNames.collapseAll = 'collapse-all';
 })(ToolbarNames || (ToolbarNames = {}));
 /**
  * Populate the file browser's toolbar with the buttons that mirror the
@@ -415,4 +449,9 @@ export function populateToolbar(opts) {
         id: CommandIDs.refresh,
         label: ''
     }));
+    browser.toolbar.addItem(ToolbarNames.collapseAll, new CommandToolbarButton({
+        commands,
+        id: CommandIDs.collapseAll,
+        label: ''
+    }));
 }