xtralab 0.1.2 → 0.3.0

package/README.md

@@ -2,70 +2,153 @@
 
 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.
+## Install
 
-## Approach
+```bash
+pip install xtralab
+```
 
-The package brings together:
+## Usage
 
-- 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`)
+### As a JupyterLab package
 
-These are installed as normal Python dependencies, so deployments can still
-override versions and Jupyter configuration in the usual ways.
+Run JupyterLab the usual way:
 
-## Bundled labextension
+```bash
+jupyter lab
+```
 
-`xtralab` ships its own prebuilt labextension that contributes:
+### As a desktop app
 
-- 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.
+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.
 
-## Default settings
+## What's included
 
-`xtralab` ships the following JupyterLab defaults:
+- [`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"
+      }
+    }
+  }
+}
+```
 
-- 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.
+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.
 
-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.
+## Customizing the launcher
 
-## Install
+Open `Settings → Settings Editor → xtralab launcher` and edit the `agents`
+array. Entries are merged with the defaults by `id`.
 
-```bash
-pip install xtralab
-```
+```jsonc
+{
+  "agents": [
+    // Hide an agent
+    { "id": "kiro", "enabled": false },
 
-## Development
+    // Override an agent's command (e.g. point Claude at a shell alias)
+    { "id": "claude", "command": "cl", "requireAvailable": false },
 
-```bash
-# Install dependencies and the package in editable mode
-uv pip install -e ".[dev]"
-jlpm
-jlpm build
+    // Add a new agent; promptArgs: [] appends the prompt as a positional arg
+    { "id": "aider", "label": "Aider", "command": "aider", "promptArgs": [] }
+  ]
+}
 ```
 
+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`.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, the
+Electron desktop app architecture, and the build pipeline.
+
 ## License
 
 BSD-3-Clause

package/lib/fileBrowser/commands.d.ts

@@ -1,7 +1,7 @@
 import { JupyterFrontEnd } from '@jupyterlab/application';
 import { IXtralabFileBrowser } from './widget';
 /**
- * Command identifiers exposed by the Xtralab browser. We deliberately namespace
+ * Command identifiers exposed by the xtralab browser. We deliberately namespace
  * these under `xtralab:` rather than reusing the `filebrowser:` ids
  * because the core `filebrowser:*` commands look up a `FileBrowser` instance
  * via `IFileBrowserFactory.tracker` — our widget is not a `FileBrowser`, so
@@ -31,7 +31,7 @@ export interface IRegisterCommandsOptions {
     browser: IXtralabFileBrowser;
 }
 /**
- * Register every Xtralab command on the application command registry, attach
+ * Register every xtralab command on the application command registry, attach
  * the items to the application context menu, and wire up the dynamic
  * "Open With" submenu populator.
  *

package/lib/fileBrowser/commands.js

@@ -3,7 +3,7 @@ import { PageConfig, PathExt } from '@jupyterlab/coreutils';
 import { addIcon, closeIcon, CommandToolbarButton, copyIcon, downloadIcon, editIcon, fileIcon, newFolderIcon, refreshIcon } from '@jupyterlab/ui-components';
 import { toCanonicalPath, toServerPath } from './contents';
 /**
- * Command identifiers exposed by the Xtralab browser. We deliberately namespace
+ * Command identifiers exposed by the xtralab browser. We deliberately namespace
  * these under `xtralab:` rather than reusing the `filebrowser:` ids
  * because the core `filebrowser:*` commands look up a `FileBrowser` instance
  * via `IFileBrowserFactory.tracker` — our widget is not a `FileBrowser`, so
@@ -136,7 +136,7 @@ function makeOpenWithUpdater(app, browser) {
     };
 }
 /**
- * Register every Xtralab command on the application command registry, attach
+ * Register every xtralab command on the application command registry, attach
  * the items to the application context menu, and wire up the dynamic
  * "Open With" submenu populator.
  *

package/lib/fileBrowser/fileBrowser.js

@@ -4,6 +4,7 @@ import { MimeData, PromiseDelegate } from '@lumino/coreutils';
 import { Drag } from '@lumino/dragdrop';
 import { FileTree, useFileTree } from '@pierre/trees/react';
 import { ROOT_LOAD_KEY, listDirectory, toServerPath } from './contents';
+import { buildIgnoredEntries, loadGitignoreMatcher } from './gitignore';
 import { FILE_BROWSER_ICONS } from './icons';
 /**
  * MIME types used by the dock panel and other JupyterLab drop targets.
@@ -11,7 +12,7 @@ import { FILE_BROWSER_ICONS } from './icons';
  * synchronous function that returns a Widget. The contents MIME types
  * mirror what the default file browser sends so other drop targets that
  * understand them (the file browser itself, custom drop zones) keep
- * working when the user drags out of Xtralab.
+ * working when the user drags out of xtralab.
  */
 const FACTORY_MIME = 'application/vnd.lumino.widget-factory';
 const CONTENTS_MIME = 'application/x-jupyter-icontents';
@@ -41,11 +42,54 @@ export function FileBrowserComponent(props) {
         paths: [],
         initialExpansion: 'closed',
         search: true,
-        icons: FILE_BROWSER_ICONS
+        icons: FILE_BROWSER_ICONS,
+        itemHeight: 24
     });
     React.useEffect(() => {
         const knownDirs = new Map();
+        // Mirror of the canonical paths currently loaded into the tree. Kept in
+        // sync with `model.resetPaths`/`model.batch`/`model.add` so we can
+        // re-test every loaded path against the gitignore matcher whenever
+        // either side changes — the model itself does not expose a
+        // path-iteration API.
+        const loadedPaths = new Set();
+        let gitignoreMatcher = null;
         let cancelled = false;
+        /**
+         * Recompute the `ignored` git status entries from the current
+         * gitignore matcher and the set of loaded paths, and push them into
+         * the tree. Safe to call at any time: when the matcher is `null`
+         * (no `.gitignore` or it failed to load) we send an empty list, which
+         * also clears any statuses that may have been applied previously.
+         */
+        const syncGitStatus = () => {
+            if (gitignoreMatcher === null) {
+                model.setGitStatus([]);
+                return;
+            }
+            const entries = buildIgnoredEntries(gitignoreMatcher, loadedPaths);
+            model.setGitStatus(entries);
+        };
+        /**
+         * Reload the workspace `.gitignore`, then re-apply the resulting
+         * ignored statuses. Called on initial mount and whenever the user
+         * triggers a refresh — the file may have been edited or created in
+         * between.
+         */
+        const refreshGitignoreMatcher = async () => {
+            let next = null;
+            try {
+                next = await loadGitignoreMatcher(contentsManager);
+            }
+            catch (err) {
+                console.error('xtralab: failed to load .gitignore', err);
+            }
+            if (cancelled) {
+                return;
+            }
+            gitignoreMatcher = next;
+            syncGitStatus();
+        };
         const fetchDirectory = async (canonicalPath) => {
             const current = knownDirs.get(canonicalPath);
             if (current === 'loading' || current === 'loaded') {
@@ -60,6 +104,10 @@ export function FileBrowserComponent(props) {
                 }
                 if (canonicalPath === ROOT_LOAD_KEY) {
                     model.resetPaths(paths);
+                    loadedPaths.clear();
+                    for (const path of paths) {
+                        loadedPaths.add(path);
+                    }
                 }
                 else {
                     // Filter out paths already in the model. The path-store throws
@@ -72,6 +120,14 @@ export function FileBrowserComponent(props) {
                     if (operations.length > 0) {
                         model.batch(operations);
                     }
+                    // Mirror every directory child into `loadedPaths` regardless of
+                    // whether it was just added or skipped above — paths skipped by
+                    // the filter are already in the model from a prior add and so
+                    // belong in the mirror too. `Set.add` is idempotent, so the
+                    // duplicate adds are a no-op.
+                    for (const path of paths) {
+                        loadedPaths.add(path);
+                    }
                 }
                 for (const subdir of subdirectories) {
                     if (!knownDirs.has(subdir)) {
@@ -79,6 +135,7 @@ export function FileBrowserComponent(props) {
                     }
                 }
                 knownDirs.set(canonicalPath, 'loaded');
+                syncGitStatus();
             }
             catch (err) {
                 console.error(`xtralab: failed to load directory "${canonicalPath}"`, err);
@@ -165,12 +222,22 @@ export function FileBrowserComponent(props) {
             // Reset the tree contents and restore the load-state map so future
             // expansions know which directories still need fetching.
             model.resetPaths(allPaths);
+            loadedPaths.clear();
+            for (const path of allPaths) {
+                loadedPaths.add(path);
+            }
             knownDirs.set(ROOT_LOAD_KEY, 'loaded');
             subdirsByParent.forEach(subdirs => {
                 for (const subdir of subdirs) {
                     knownDirs.set(subdir, expandedPaths.has(subdir) ? 'loaded' : 'unloaded');
                 }
             });
+            // Refresh the `.gitignore` matcher in case the file was edited
+            // since the last load, then re-apply the resulting statuses to the
+            // newly-loaded paths. The reload runs in parallel with the rest of
+            // the refresh — `refreshGitignoreMatcher` calls `syncGitStatus`
+            // itself when it completes.
+            void refreshGitignoreMatcher();
             // Re-expand the directories that were expanded before the refresh.
             // We have to do this after `resetPaths` because the reset starts
             // every directory in its initial collapsed state.
@@ -196,12 +263,14 @@ export function FileBrowserComponent(props) {
                     return;
                 }
             }
+            loadedPaths.add(canonicalPath);
             if (canonicalPath.endsWith('/') && !knownDirs.has(canonicalPath)) {
                 // The new directory has no children yet, so mark it as already
                 // loaded — there's nothing to fetch and we don't want a stale
                 // "unloaded" entry to trigger a fetch on the next expand.
                 knownDirs.set(canonicalPath, 'loaded');
             }
+            syncGitStatus();
             const parent = parentOf(canonicalPath);
             if (parent === ROOT_LOAD_KEY) {
                 return;
@@ -217,6 +286,7 @@ export function FileBrowserComponent(props) {
         };
         knownDirs.set(ROOT_LOAD_KEY, 'unloaded');
         void fetchDirectory(ROOT_LOAD_KEY);
+        void refreshGitignoreMatcher();
         const unsubscribe = model.subscribe(() => {
             knownDirs.forEach((state, canonicalPath) => {
                 if (state !== 'unloaded') {

package/lib/fileBrowser/gitignore.d.ts

@@ -0,0 +1,29 @@
+import type { Ignore } from 'ignore';
+import { Contents } from '@jupyterlab/services';
+import type { GitStatusEntry } from '@pierre/trees';
+/**
+ * Load the workspace `.gitignore` and return an `ignore` matcher built from
+ * its contents. Returns `null` when the file is missing, empty, or fails to
+ * load — callers should treat any of those as "no ignored entries".
+ */
+export declare function loadGitignoreMatcher(contentsManager: Contents.IManager): Promise<Ignore | null>;
+/**
+ * Build `GitStatusEntry`s for the canonical paths that match the given
+ * gitignore matcher.
+ *
+ * `@pierre/trees` propagates the `ignored` style from a directory entry
+ * down to every descendant via its internal `ignoredDirectoryPaths` set, so
+ * we only emit one entry per ignored subtree root: emitting descendants
+ * would also pollute the library's `directoriesWithChanges` set, causing
+ * parent directories of nested ignored items to render a "contains git
+ * status items" dot.
+ *
+ * Paths are sorted lexicographically so a directory always precedes its
+ * descendants, allowing a simple ancestor-suppression check via
+ * `path.startsWith(dir)`. The trailing slash on canonical directory paths
+ * (required by `@pierre/trees`, also recognized by `ignore` as the
+ * "directory" indicator) keeps the prefix check from accidentally matching
+ * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
+ * vs `node_modules/`).
+ */
+export declare function buildIgnoredEntries(matcher: Ignore, canonicalPaths: Iterable<string>): GitStatusEntry[];

package/lib/fileBrowser/gitignore.js

@@ -0,0 +1,74 @@
+import ignore from 'ignore';
+/**
+ * The path of the workspace `.gitignore` file. Loaded relative to the
+ * Jupyter contents root, which matches the directory the gitignore patterns
+ * are evaluated against — patterns and tested paths share the same base.
+ */
+const GITIGNORE_PATH = '.gitignore';
+/**
+ * Load the workspace `.gitignore` and return an `ignore` matcher built from
+ * its contents. Returns `null` when the file is missing, empty, or fails to
+ * load — callers should treat any of those as "no ignored entries".
+ */
+export async function loadGitignoreMatcher(contentsManager) {
+    let model;
+    try {
+        model = await contentsManager.get(GITIGNORE_PATH, {
+            content: true,
+            format: 'text',
+            type: 'file'
+        });
+    }
+    catch (_a) {
+        // The most common failure here is `.gitignore` simply not existing.
+        // Other transient errors (permission denied, server unreachable) are
+        // also treated as "no matcher" so the file browser still works.
+        return null;
+    }
+    if (model.type !== 'file' || typeof model.content !== 'string') {
+        return null;
+    }
+    if (model.content.length === 0) {
+        return null;
+    }
+    return ignore().add(model.content);
+}
+/**
+ * Build `GitStatusEntry`s for the canonical paths that match the given
+ * gitignore matcher.
+ *
+ * `@pierre/trees` propagates the `ignored` style from a directory entry
+ * down to every descendant via its internal `ignoredDirectoryPaths` set, so
+ * we only emit one entry per ignored subtree root: emitting descendants
+ * would also pollute the library's `directoriesWithChanges` set, causing
+ * parent directories of nested ignored items to render a "contains git
+ * status items" dot.
+ *
+ * Paths are sorted lexicographically so a directory always precedes its
+ * descendants, allowing a simple ancestor-suppression check via
+ * `path.startsWith(dir)`. The trailing slash on canonical directory paths
+ * (required by `@pierre/trees`, also recognized by `ignore` as the
+ * "directory" indicator) keeps the prefix check from accidentally matching
+ * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
+ * vs `node_modules/`).
+ */
+export function buildIgnoredEntries(matcher, canonicalPaths) {
+    const sorted = Array.from(canonicalPaths).sort();
+    const emittedIgnoredDirs = [];
+    const entries = [];
+    for (const path of sorted) {
+        if (path.length === 0) {
+            continue;
+        }
+        if (emittedIgnoredDirs.some(dir => path.startsWith(dir))) {
+            continue;
+        }
+        if (matcher.ignores(path)) {
+            entries.push({ path, status: 'ignored' });
+            if (path.endsWith('/')) {
+                emittedIgnoredDirs.push(path);
+            }
+        }
+    }
+    return entries;
+}

package/lib/fileBrowser/icons.d.ts

@@ -1,9 +1,9 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 import type { FileTreeIconConfig } from '@pierre/trees';
 /**
- * The glyph used as the Xtralab file browser's sidebar tab icon. Defined as a
+ * The glyph used as the xtralab file browser's sidebar tab icon. Defined as a
  * `LabIcon` (rather than the default `folderIcon` from
- * `@jupyterlab/ui-components`) so the Xtralab browser is visually distinguishable
+ * `@jupyterlab/ui-components`) so the xtralab browser is visually distinguishable
  * from JupyterLab's built-in file browser, which also lives in the left
  * sidebar.
  *
@@ -14,7 +14,7 @@ import type { FileTreeIconConfig } from '@pierre/trees';
  */
 export declare const xtralabFileBrowserIcon: LabIcon;
 /**
- * Icon configuration for the Xtralab file browser. Keeps the default `complete`
+ * Icon configuration for the xtralab file browser. Keeps the default `complete`
  * built-in icon set (the colored language icons) and layers a Jupyter notebook
  * symbol on top so `.ipynb` files render with the JupyterLab notebook glyph.
  *
@@ -24,7 +24,7 @@ export declare const xtralabFileBrowserIcon: LabIcon;
  */
 export declare const FILE_BROWSER_ICONS: FileTreeIconConfig;
 /**
- * Return a JupyterLab `LabIcon` matching the icon the Xtralab file tree would
+ * Return a JupyterLab `LabIcon` matching the icon the xtralab file tree would
  * render for the given file path. Used by other plugins (e.g. the git diff
  * viewer) that want their main-area widget tabs to display the same per-file
  * glyph the tree shows in the sidebar.

package/lib/fileBrowser/icons.js

@@ -2,9 +2,9 @@ var _a;
 import { LabIcon, fileIcon } from '@jupyterlab/ui-components';
 import { createFileTreeIconResolver, getBuiltInFileIconColor, getBuiltInSpriteSheet } from '@pierre/trees';
 /**
- * The glyph used as the Xtralab file browser's sidebar tab icon. Defined as a
+ * The glyph used as the xtralab file browser's sidebar tab icon. Defined as a
  * `LabIcon` (rather than the default `folderIcon` from
- * `@jupyterlab/ui-components`) so the Xtralab browser is visually distinguishable
+ * `@jupyterlab/ui-components`) so the xtralab browser is visually distinguishable
  * from JupyterLab's built-in file browser, which also lives in the left
  * sidebar.
  *
@@ -42,7 +42,7 @@ const JUPYTER_NOTEBOOK_SPRITE_SHEET = `<svg data-icon-sprite aria-hidden="true"
   </symbol>
 </svg>`;
 /**
- * Icon configuration for the Xtralab file browser. Keeps the default `complete`
+ * Icon configuration for the xtralab file browser. Keeps the default `complete`
  * built-in icon set (the colored language icons) and layers a Jupyter notebook
  * symbol on top so `.ipynb` files render with the JupyterLab notebook glyph.
  *
@@ -105,7 +105,7 @@ function extractSymbol(symbolId) {
     };
 }
 /**
- * Return a JupyterLab `LabIcon` matching the icon the Xtralab file tree would
+ * Return a JupyterLab `LabIcon` matching the icon the xtralab file tree would
  * render for the given file path. Used by other plugins (e.g. the git diff
  * viewer) that want their main-area widget tabs to display the same per-file
  * glyph the tree shows in the sidebar.

package/lib/fileBrowser/widget.d.ts

@@ -5,7 +5,7 @@ import { ISignal } from '@lumino/signaling';
 import { Widget } from '@lumino/widgets';
 export declare const FILE_BROWSER_ID = "xtralab:file-browser";
 /**
- * The CSS class added to the Xtralab file browser widget. The selectors that
+ * The CSS class added to the xtralab file browser widget. The selectors that
  * bind application context menu items hang off this class, so it must remain
  * specific enough not to clash with other browsers (such as the default
  * `jp-FileBrowser`).
@@ -17,7 +17,7 @@ export interface IXtralabFileBrowserOptions {
     onOpenFile?: (serverPath: string) => void;
 }
 /**
- * Public API of the Xtralab file browser used by command handlers and other
+ * Public API of the xtralab file browser used by command handlers and other
  * collaborators. Kept narrow on purpose so the React component stays free to
  * evolve the underlying tree integration.
  */

package/lib/fileBrowser/widget.js

@@ -6,7 +6,7 @@ import { FileBrowserComponent } from './fileBrowser';
 import { xtralabFileBrowserIcon } from './icons';
 export const FILE_BROWSER_ID = 'xtralab:file-browser';
 /**
- * The CSS class added to the Xtralab file browser widget. The selectors that
+ * The CSS class added to the xtralab file browser widget. The selectors that
  * bind application context menu items hang off this class, so it must remain
  * specific enough not to clash with other browsers (such as the default
  * `jp-FileBrowser`).
@@ -32,7 +32,7 @@ export class XtralabFileBrowser extends Widget {
         this._onOpenFile = options.onOpenFile;
         this.id = FILE_BROWSER_ID;
         this.title.icon = xtralabFileBrowserIcon;
-        this.title.caption = 'Xtralab File Browser';
+        this.title.caption = 'xtralab File Browser';
         this.addClass(FILE_BROWSER_CSS_CLASS);
         this._toolbar = new Toolbar();
         this._toolbar.addClass(TOOLBAR_CSS_CLASS);

package/lib/git/api.d.ts

@@ -28,6 +28,17 @@ export declare function reset(repoPath: string, filename: string): Promise<void>
 export declare function resetAll(repoPath: string): Promise<void>;
 /** Restore a single file to the version in the index (i.e. discard worktree changes). */
 export declare function checkout(repoPath: string, filename: string): Promise<void>;
+/**
+ * Expand the porcelain `files` array into one entry per logical change.
+ * A single porcelain row may map to two `IFileChange` rows (a file that's
+ * both staged and modified again in the worktree); callers that just want
+ * a flat list of all changes — without any staged-vs-unstaged grouping —
+ * can use this helper.
+ *
+ * Provided as a manual concat rather than `Array.prototype.flatMap` so we
+ * don't pin our `tsconfig.lib` to ES2019.
+ */
+export declare function expandStatusFiles(files: IGitStatusFile[]): IFileChange[];
 /**
  * Translate one entry in the porcelain `files` array into the panel's
  * preferred shape. A single porcelain entry may represent up to two changes

package/lib/git/api.js

@@ -103,6 +103,25 @@ export async function checkout(repoPath, filename) {
         filename
     });
 }
+/**
+ * Expand the porcelain `files` array into one entry per logical change.
+ * A single porcelain row may map to two `IFileChange` rows (a file that's
+ * both staged and modified again in the worktree); callers that just want
+ * a flat list of all changes — without any staged-vs-unstaged grouping —
+ * can use this helper.
+ *
+ * Provided as a manual concat rather than `Array.prototype.flatMap` so we
+ * don't pin our `tsconfig.lib` to ES2019.
+ */
+export function expandStatusFiles(files) {
+    const result = [];
+    for (const file of files) {
+        for (const change of porcelainToFileChanges(file)) {
+            result.push(change);
+        }
+    }
+    return result;
+}
 /**
  * Translate one entry in the porcelain `files` array into the panel's
  * preferred shape. A single porcelain entry may represent up to two changes

package/lib/git/commands.d.ts

@@ -24,6 +24,7 @@ export declare namespace CommandArguments {
     interface IOpenDiff {
         repoPath: string;
         change: IFileChange;
+        pin?: boolean;
     }
 }
 export interface IRegisterGitCommandsOptions {
@@ -58,7 +59,8 @@ export interface IRegisterGitCommandsOptions {
      * Look up an already-open diff widget for a given file change. Returns
      * `undefined` when none is open.
      */
-    findDiff(change: IFileChange): ReturnType<typeof createGitDiffWidget> | undefined;
+    findDiff(change: IFileChange, pin?: boolean): ReturnType<typeof createGitDiffWidget> | undefined;
+    onPinned(widget: ReturnType<typeof createGitDiffWidget>): void;
 }
 /**
  * Register the git commands on the application command registry. Returns