xtralab 0.9.0 → 0.11.0

package/README.md

@@ -34,6 +34,23 @@ from `main` are uploaded as workflow artifacts on the
 [CONTRIBUTING.md](./CONTRIBUTING.md) for the desktop app architecture and local
 build instructions.
 
+On macOS the build is not notarized yet (it has no Apple Developer ID), so
+Gatekeeper blocks it on first launch, and agent notifications fall back to
+`osascript`, appearing as "Script Editor". In the meantime you can self-sign it
+for free: this lets it launch and gives native notifications instead, branded as
+xtralab and clickable to jump to the terminal that fired them. Create a
+code-signing certificate once in Keychain Access (Certificate Assistant, Create
+a Certificate, with Identity Type "Self Signed Root" and Certificate Type "Code
+Signing") named `xtralab-selfsign`, then sign the app you copied out of the DMG:
+
+```bash
+codesign --force --deep --sign "xtralab-selfsign" --timestamp=none "/Applications/xtralab.app"
+xattr -dr com.apple.quarantine "/Applications/xtralab.app"
+```
+
+macOS prompts once to let `codesign` use the key; choose Always Allow. None of
+this will be needed once the app ships with a Developer ID signature.
+
 ## What's included
 
 xtralab builds on [`ajlab`](https://github.com/jtpio/ajlab), the agent-ready
@@ -90,13 +107,23 @@ See the [`jupyter-server-mcp` README][mcp] for other MCP clients.
 [mcp]: https://github.com/jupyter-ai-contrib/jupyter-server-mcp
 [mcp-spec]: https://modelcontextprotocol.io
 
-## Agent skill
+## Agent skills
+
+xtralab ships [Agent Skills][skills] at [`agent-skill/`](./agent-skill) that
+teach any coding agent how to work with the app:
+
+- **customize-jupyterlab** turns plain-English requests like "hide the status
+  bar", "change the theme", or "add a language server" into the right
+  config-file edits.
+- **guided-code-walkthrough** drives the running app over the MCP command
+  bridge (see the section above) to open files, jump to and highlight specific
+  lines (`xtralab:highlight-lines`), and build a read-only Walkthrough panel of
+  prose, snippets, diagrams, and clickable code links beside the editor
+  (`xtralab:walkthrough`, no notebook or kernel needed), so the agent can _show_
+  you something at your own pace instead of only describing it in chat.
 
-xtralab ships an [Agent Skills][skills] entry at [`agent-skill/`](./agent-skill)
-that teaches any coding agent how to customize JupyterLab from plain-English
-requests like "hide the status bar", "change the theme", or "add a language
-server". The same SKILL.md file works with Claude Code, Codex CLI, Gemini CLI,
-GitHub Copilot, and other tools that read the Agent Skills format.
+The same SKILL.md files work with Claude Code, Codex CLI, Gemini CLI, GitHub
+Copilot, and other tools that read the Agent Skills format.
 
 For Claude Code, this repository doubles as a one-plugin marketplace. Inside a
 Claude Code session:
@@ -107,12 +134,12 @@ Claude Code session:
 ```
 
 For agents that read from `~/.agents/skills/`, such as Codex CLI or Gemini CLI,
-clone and copy the skill directory:
+clone and copy the skill directories:
 
 ```bash
 git clone --depth=1 https://github.com/jtpio/xtralab.git /tmp/xtralab
 mkdir -p ~/.agents/skills
-cp -r /tmp/xtralab/agent-skill/skills/customize-jupyterlab ~/.agents/skills/
+cp -r /tmp/xtralab/agent-skill/skills/* ~/.agents/skills/
 ```
 
 See [`agent-skill/README.md`](./agent-skill/README.md) for additional install
@@ -167,7 +194,11 @@ See the [`jupyterlab-lsp` documentation][lsp-config] for the full spec.
 ## Customizing the launcher
 
 Open `Settings → Settings Editor → xtralab launcher` to override, hide, or add
-launcher entries. Both lists below merge with xtralab's defaults by `id`.
+launcher entries. The editor shows xtralab's full built-in list as the default
+for both the agents and editors settings, so you can read every shipped entry
+and copy one into your user preferences to tweak in place. Both lists merge with
+xtralab's defaults by `id`, so an override only needs the `id` plus the fields
+you want to change.
 
 ### Agents
 

package/lib/commandBar/index.d.ts

@@ -0,0 +1,14 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Add a centered, search-bar-styled command bar to the top area. Clicking it
+ * opens the omnibox — a launcher overlay that fuzzy-searches files and
+ * commands and routes a typed prompt to an agent (the leading sidebar toggle
+ * and the menu bar sit to its left, the trailing sidebar toggle to its right;
+ * the bar is centered over the whole panel as an overlay, so it stays put
+ * regardless of their widths).
+ *
+ * The bar is only added when the omnibox is available — the `IOmnibox` token
+ * is provided by `xtralab:omnibox` — so it never appears with nothing to open.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/commandBar/index.js

@@ -0,0 +1,114 @@
+import { ILabShell } from '@jupyterlab/application';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { searchIcon } from '@jupyterlab/ui-components';
+import { CommandRegistry } from '@lumino/commands';
+import { Widget } from '@lumino/widgets';
+import { IOmnibox, OMNIBOX_OPEN_COMMAND } from '../omnibox/tokens';
+const PLUGIN_ID = 'xtralab:command-bar';
+/**
+ * A search-bar-styled launcher for the `top` area. It holds no text input of
+ * its own: clicking the pill (or pressing Enter/Space while it is focused)
+ * runs `onActivate`, which opens the omnibox.
+ *
+ * The widget's root is a transparent, full-height wrapper centered as an
+ * overlay over the whole top panel (style/commandBar.css). The wrapper
+ * ignores pointer events so only the inner pill is clickable and the empty
+ * strips above and below it let clicks fall through to whatever sits beneath
+ * the overlay, such as the menu bar.
+ */
+class CommandBar extends Widget {
+    constructor(options) {
+        super({
+            node: CommandBar.createNode(options.label, options.caption, options.shortcut)
+        });
+        this.addClass('jp-xtralab-CommandBar');
+        this._onActivate = options.onActivate;
+    }
+    handleEvent(event) {
+        if (event.type === 'click') {
+            this._onActivate();
+        }
+    }
+    onAfterAttach() {
+        // The pill restores `pointer-events: auto`, so the click bubbles from it
+        // up to the root node listened on here; keyboard Enter/Space on the
+        // focused button raises the same synthetic click.
+        this.node.addEventListener('click', this);
+    }
+    onBeforeDetach() {
+        this.node.removeEventListener('click', this);
+    }
+}
+(function (CommandBar) {
+    function createNode(label, caption, shortcut) {
+        const wrapper = document.createElement('div');
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'jp-xtralab-CommandBar-button';
+        button.title = caption;
+        button.setAttribute('aria-label', caption);
+        const icon = searchIcon.element({
+            tag: 'span',
+            className: 'jp-xtralab-CommandBar-icon'
+        });
+        const text = document.createElement('span');
+        text.className = 'jp-xtralab-CommandBar-label';
+        text.textContent = label;
+        button.appendChild(icon);
+        button.appendChild(text);
+        if (shortcut) {
+            const hint = document.createElement('span');
+            hint.className = 'jp-xtralab-CommandBar-shortcut';
+            hint.textContent = shortcut;
+            // Decorative: the button's aria-label already names the action.
+            hint.setAttribute('aria-hidden', 'true');
+            button.appendChild(hint);
+        }
+        wrapper.appendChild(button);
+        return wrapper;
+    }
+    CommandBar.createNode = createNode;
+})(CommandBar || (CommandBar = {}));
+/**
+ * Add a centered, search-bar-styled command bar to the top area. Clicking it
+ * opens the omnibox — a launcher overlay that fuzzy-searches files and
+ * commands and routes a typed prompt to an agent (the leading sidebar toggle
+ * and the menu bar sit to its left, the trailing sidebar toggle to its right;
+ * the bar is centered over the whole panel as an overlay, so it stays put
+ * regardless of their widths).
+ *
+ * The bar is only added when the omnibox is available — the `IOmnibox` token
+ * is provided by `xtralab:omnibox` — so it never appears with nothing to open.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Add a centered command bar to the top area that opens the omnibox.',
+    autoStart: true,
+    requires: [ILabShell],
+    optional: [IOmnibox, ITranslator],
+    activate: (app, labShell, omnibox, translator) => {
+        if (!omnibox) {
+            return;
+        }
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        // Show the omnibox's keyboard shortcut as a hint in the pill, derived from
+        // the live binding (registered by xtralab:omnibox, which activates first as
+        // the IOmnibox provider) so it stays correct and uses the platform's
+        // modifier symbols. Empty when no binding is registered.
+        const binding = app.commands.keyBindings.find(keyBinding => keyBinding.command === OMNIBOX_OPEN_COMMAND);
+        const shortcut = binding
+            ? CommandRegistry.formatKeystroke(binding.keys)
+            : '';
+        const widget = new CommandBar({
+            label: trans.__('Search…'),
+            caption: trans.__('Search files and commands, or ask an agent'),
+            shortcut,
+            onActivate: () => {
+                omnibox.open();
+            }
+        });
+        widget.id = 'xtralab-command-bar';
+        labShell.add(widget, 'top', { rank: 500 });
+    }
+};
+export default plugin;

package/lib/fileBrowser/fileBrowser.js

@@ -64,6 +64,10 @@ const GIT_REPO_PATH = '';
  * resolution cost just for one string.
  */
 const FILE_TREE_TAG = 'file-tree-container';
+const FILE_TREE_UNSAFE_CSS = '[data-type="item"][data-item-selected="true"] ' +
+    '[data-item-section="spacing-item"] {' +
+    'border-left-color: transparent;' +
+    '}';
 /**
  * Renders a `@pierre/trees` file tree backed by the Jupyter contents API.
  *
@@ -80,7 +84,8 @@ export function FileBrowserComponent(props) {
         initialExpansion: 'closed',
         search: true,
         icons: FILE_BROWSER_ICONS,
-        itemHeight: 24
+        itemHeight: 24,
+        unsafeCSS: FILE_TREE_UNSAFE_CSS
     });
     React.useEffect(() => {
         const knownDirs = new Map();

package/lib/highlight/index.d.ts

@@ -0,0 +1,15 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Contribute `xtralab:highlight-lines` and `xtralab:clear-highlights`.
+ *
+ * The built-in command surface can open a file (`docmanager:open`) and move
+ * the cursor to a line (`fileeditor:go-to-line`), but it cannot persistently
+ * highlight a span of lines — `documentsearch:start` only marks text matches
+ * and hijacks the find box. This plugin fills that gap with a CodeMirror line
+ * decoration, so an agent can point at "lines 31–43 of src/index.ts" while it
+ * narrates a walkthrough. `xtralab:highlight-lines` opens the file when needed,
+ * scrolls the range into view, and replaces any previous highlight in that
+ * editor; `xtralab:clear-highlights` removes every highlight.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/highlight/index.js

@@ -0,0 +1,214 @@
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { CodeMirrorEditor } from '@jupyterlab/codemirror';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { StateEffect, StateField } from '@codemirror/state';
+import { Decoration, EditorView } from '@codemirror/view';
+const PLUGIN_ID = 'xtralab:highlight';
+/**
+ * Highlight a contiguous range of lines, or clear every highlight. These are
+ * the only two commands the plugin contributes; both are designed to be driven
+ * by a coding agent over the MCP command bridge to walk a user through code.
+ */
+const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
+const CLEAR_HIGHLIGHTS_COMMAND = 'xtralab:clear-highlights';
+/** CodeMirror line-decoration class; styled in style/highlight.css. */
+const HIGHLIGHT_LINE_CLASS = 'jp-xtralab-highlightLine';
+/**
+ * A CodeMirror effect carrying the 1-indexed, inclusive line range to
+ * highlight, or `null` to clear the editor's highlights.
+ */
+const setHighlight = StateEffect.define();
+/**
+ * Holds the highlight decorations for one editor. It is injected lazily (the
+ * first time an editor is highlighted) via `StateEffect.appendConfig`, so
+ * editors that are never highlighted pay nothing.
+ */
+const highlightField = StateField.define({
+    create: () => Decoration.none,
+    update(decorations, transaction) {
+        // Keep decorations anchored as the user edits around them.
+        decorations = decorations.map(transaction.changes);
+        for (const effect of transaction.effects) {
+            if (!effect.is(setHighlight)) {
+                continue;
+            }
+            if (effect.value === null) {
+                decorations = Decoration.none;
+                continue;
+            }
+            const { doc } = transaction.state;
+            const lineDecoration = Decoration.line({ class: HIGHLIGHT_LINE_CLASS });
+            const start = Math.max(1, Math.min(effect.value.start, doc.lines));
+            const end = Math.max(start, Math.min(effect.value.end, doc.lines));
+            const ranges = [];
+            for (let line = start; line <= end; line++) {
+                ranges.push(lineDecoration.range(doc.line(line).from));
+            }
+            decorations = Decoration.set(ranges);
+        }
+        return decorations;
+    },
+    provide: field => EditorView.decorations.from(field)
+});
+/**
+ * Return the CodeMirror view backing a widget's editor, or `null` when the
+ * widget is not a CodeMirror-based text editor (a notebook, a terminal, the
+ * settings editor, …). Duck-typed on `content.editor` so the plugin does not
+ * depend on `@jupyterlab/fileeditor`.
+ */
+function viewForWidget(widget) {
+    var _a;
+    const editor = (_a = widget === null || widget === void 0 ? void 0 : widget.content) === null || _a === void 0 ? void 0 : _a.editor;
+    return editor instanceof CodeMirrorEditor ? editor.editor : null;
+}
+/**
+ * Coerce a JSON command argument to a positive integer line number, falling
+ * back to `fallback` when it is missing or not a finite number.
+ */
+function toLine(value, fallback) {
+    const n = Math.trunc(Number(value));
+    return Number.isFinite(n) && n >= 1 ? n : fallback;
+}
+/**
+ * Contribute `xtralab:highlight-lines` and `xtralab:clear-highlights`.
+ *
+ * The built-in command surface can open a file (`docmanager:open`) and move
+ * the cursor to a line (`fileeditor:go-to-line`), but it cannot persistently
+ * highlight a span of lines — `documentsearch:start` only marks text matches
+ * and hijacks the find box. This plugin fills that gap with a CodeMirror line
+ * decoration, so an agent can point at "lines 31–43 of src/index.ts" while it
+ * narrates a walkthrough. `xtralab:highlight-lines` opens the file when needed,
+ * scrolls the range into view, and replaces any previous highlight in that
+ * editor; `xtralab:clear-highlights` removes every highlight.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Highlight line ranges in text editors to guide walkthroughs.',
+    autoStart: true,
+    requires: [IDocumentManager],
+    optional: [ICommandPalette, ITranslator],
+    activate: (app, docManager, palette, translator) => {
+        const { commands, shell } = app;
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        // Editors that currently carry a highlight, so a single clear can reach
+        // them all. Disposed editors are dropped on the next clear.
+        const highlighted = new Set();
+        const ensureField = (view) => {
+            if (view.state.field(highlightField, false) === undefined) {
+                view.dispatch({ effects: StateEffect.appendConfig.of(highlightField) });
+            }
+        };
+        commands.addCommand(HIGHLIGHT_LINES_COMMAND, {
+            label: trans.__('Highlight Lines'),
+            caption: trans.__('Highlight a range of lines in a text editor'),
+            // Advertise the argument shape so agents listing commands over the MCP
+            // bridge can see how to call it, the same way core commands do.
+            describedBy: {
+                args: {
+                    type: 'object',
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'Path of the file to highlight in, relative to the server root. Opened if needed; defaults to the active editor when omitted.'
+                        },
+                        line: {
+                            type: 'number',
+                            description: 'First line to highlight (1-indexed). Defaults to 1.'
+                        },
+                        endLine: {
+                            type: 'number',
+                            description: 'Last line to highlight (1-indexed, inclusive). Defaults to `line` for a single line.'
+                        },
+                        reveal: {
+                            type: 'boolean',
+                            description: 'Whether to scroll the highlighted range into view. Defaults to true.'
+                        }
+                    }
+                }
+            },
+            execute: async (args) => {
+                const line = toLine(args['line'], 1);
+                const endLine = toLine(args['endLine'], line);
+                const path = typeof args['path'] === 'string' ? args['path'] : undefined;
+                const reveal = args['reveal'] !== false;
+                // With a path, bind strictly to that document: never fall back to the
+                // active widget, or an explicit path could silently highlight an
+                // unrelated editor that happens to be focused.
+                let widget;
+                if (path) {
+                    // Fail fast on a missing path instead of opening a phantom widget
+                    // behind a blocking "file not found" dialog.
+                    try {
+                        await docManager.services.contents.get(path, { content: false });
+                    }
+                    catch (_a) {
+                        throw new Error(`xtralab: no file at "${path}"`);
+                    }
+                    const opened = docManager.openOrReveal(path);
+                    if (!opened) {
+                        throw new Error(`xtralab: could not open "${path}"`);
+                    }
+                    // Wait for the model and the editor view to be ready.
+                    await opened.context.ready;
+                    await opened.revealed;
+                    widget = opened;
+                }
+                else {
+                    widget = shell.currentWidget;
+                }
+                const view = viewForWidget(widget);
+                if (!view) {
+                    throw new Error(path
+                        ? `xtralab: "${path}" is not open in a text editor`
+                        : 'xtralab: the active widget is not a text editor');
+                }
+                const start = Math.min(line, endLine);
+                const end = Math.max(line, endLine);
+                ensureField(view);
+                const lineCount = view.state.doc.lines;
+                const anchor = view.state.doc.line(Math.max(1, Math.min(start, lineCount))).from;
+                const effects = [
+                    setHighlight.of({ start, end })
+                ];
+                if (reveal) {
+                    effects.push(EditorView.scrollIntoView(anchor, { y: 'center' }));
+                }
+                view.dispatch({ effects });
+                // Forget editors that have since been closed before tracking this one.
+                for (const tracked of highlighted) {
+                    if (!tracked.dom.isConnected) {
+                        highlighted.delete(tracked);
+                    }
+                }
+                highlighted.add(view);
+                return start === end
+                    ? trans.__('Highlighted line %1', start)
+                    : trans.__('Highlighted lines %1-%2', start, end);
+            }
+        });
+        commands.addCommand(CLEAR_HIGHLIGHTS_COMMAND, {
+            label: trans.__('Clear Highlights'),
+            caption: trans.__('Remove all xtralab line highlights'),
+            execute: () => {
+                for (const view of highlighted) {
+                    try {
+                        if (view.state.field(highlightField, false) !== undefined) {
+                            view.dispatch({ effects: setHighlight.of(null) });
+                        }
+                    }
+                    catch (_a) {
+                        // The editor was disposed; nothing to clear.
+                    }
+                }
+                highlighted.clear();
+            }
+        });
+        if (palette) {
+            const category = trans.__('Other');
+            palette.addItem({ command: HIGHLIGHT_LINES_COMMAND, category });
+            palette.addItem({ command: CLEAR_HIGHLIGHTS_COMMAND, category });
+        }
+    }
+};
+export default plugin;

package/lib/index.js

@@ -1,14 +1,21 @@
 import agentSessionsPlugin from './agentSessions';
+import commandBarPlugin from './commandBar';
 import fileBrowserPlugin from './fileBrowser';
 import fileTypeIconsPlugin from './fileTypeIcons';
 import editorBreadcrumbsPlugin from './editorBreadcrumbs';
 import editorIndentPlugin from './editorIndent';
 import gitPlugins from './git';
+import highlightPlugin from './highlight';
 import launcherPlugins from './launcher';
 import menusPlugin from './menus';
+import omniboxPlugin from './omnibox';
+import searchReplacePlugin from './searchReplace';
+import showOutputPlugin from './showOutput';
 import sidebarPlugin from './sidebar';
+import terminalNotificationsPlugin from './terminalNotifications';
 import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
+import walkthroughPlugin from './walkthrough';
 /**
  * Every plugin contributed by `xtralab`. The entry point of the
  * labextension is an array because the package bundles several independent
@@ -20,15 +27,22 @@ import topBarPlugin from './topBar';
  */
 const plugins = [
     agentSessionsPlugin,
+    commandBarPlugin,
     editorBreadcrumbsPlugin,
     editorIndentPlugin,
     fileBrowserPlugin,
     fileTypeIconsPlugin,
     ...gitPlugins,
+    highlightPlugin,
     ...launcherPlugins,
     menusPlugin,
+    omniboxPlugin,
+    searchReplacePlugin,
+    showOutputPlugin,
     sidebarPlugin,
+    terminalNotificationsPlugin,
     terminalsPlugin,
-    topBarPlugin
+    topBarPlugin,
+    walkthroughPlugin
 ];
 export default plugins;

package/lib/launcher/agents.d.ts

@@ -69,6 +69,13 @@ export interface IAgentSettings {
      */
     promptArgs?: string[] | null;
 }
+/**
+ * The built-in agents projected into the JSON settings shape
+ * ({@link IAgentSettings}), dropping the runtime-only {@link LabIcon}.
+ * {@link registerLauncherSchemaDefaults} injects this as the `agents` setting's
+ * schema default so the Settings Editor shows the shipped list.
+ */
+export declare function defaultAgentSettings(): IAgentSettings[];
 /**
  * Merge xtralab's defaults with the user's settings. Default entries keep
  * their built-in fields unless explicitly overridden; user-only entries are

package/lib/launcher/agents.js

@@ -103,6 +103,30 @@ const DEFAULTS = [
         promptArgs: []
     }
 ];
+/**
+ * The built-in agents projected into the JSON settings shape
+ * ({@link IAgentSettings}), dropping the runtime-only {@link LabIcon}.
+ * {@link registerLauncherSchemaDefaults} injects this as the `agents` setting's
+ * schema default so the Settings Editor shows the shipped list.
+ */
+export function defaultAgentSettings() {
+    return DEFAULTS.map(agent => {
+        const entry = {
+            id: agent.id,
+            label: agent.label,
+            caption: agent.caption,
+            command: agent.command,
+            rank: agent.rank,
+            requireAvailable: agent.requireAvailable
+        };
+        // Omit `promptArgs` for agents that don't take an inline prompt, so the
+        // default doesn't show a prompt form they lack.
+        if (agent.promptArgs !== undefined) {
+            entry.promptArgs = agent.promptArgs;
+        }
+        return entry;
+    });
+}
 function resolveIcon(id, iconSvg) {
     var _a;
     if (iconSvg) {

package/lib/launcher/editorRegistry.js

@@ -3,6 +3,7 @@ import { Token } from '@lumino/coreutils';
 import { Signal } from '@lumino/signaling';
 import { fetchAvailableCommands } from './availability';
 import { mergeEditors, resolveEditor } from './editors';
+import { LAUNCHER_PLUGIN_ID, registerLauncherSchemaDefaults } from './schemaDefaults';
 /**
  * DI token for {@link IEditorRegistry}. Provided by `xtralab:editor-registry`
  * and consumed — optionally — by `xtralab:launcher` (for its tile) and
@@ -35,8 +36,6 @@ class EditorRegistry {
         this._changed.emit();
     }
 }
-/** Schema id the `editors` setting lives under (shared with the launcher). */
-const LAUNCHER_SETTINGS_ID = 'xtralab:launcher';
 /**
  * Provides {@link IEditorRegistry}: merges xtralab's built-in editors with the
  * user's `editors` setting, probes the server's `$PATH` to resolve the launcher
@@ -69,8 +68,11 @@ export const editorRegistryPlugin = {
             return Array.isArray(raw) ? raw : [];
         };
         if (settingRegistry) {
+            // Must precede the first `load`: the schema defers loading until a
+            // transform is registered.
+            registerLauncherSchemaDefaults(settingRegistry);
             try {
-                const settings = await settingRegistry.load(LAUNCHER_SETTINGS_ID);
+                const settings = await settingRegistry.load(LAUNCHER_PLUGIN_ID);
                 await apply(readOverrides(settings));
                 settings.changed.connect(async () => {
                     try {

package/lib/launcher/editors.d.ts

@@ -56,6 +56,14 @@ export interface IEditorSettings {
     /** See {@link IEditor.requireAvailable}. */
     requireAvailable?: boolean;
 }
+/**
+ * The built-in editors projected into the JSON settings shape
+ * ({@link IEditorSettings}), dropping the runtime-only {@link LabIcon}. Mirrors
+ * {@link defaultAgentSettings}: {@link registerLauncherSchemaDefaults} injects
+ * this as the `editors` setting's schema default so the Settings Editor shows
+ * the shipped list.
+ */
+export declare function defaultEditorSettings(): IEditorSettings[];
 /**
  * Merge xtralab's built-in editors with the user's `editors` settings. Built-in
  * entries keep their fields unless explicitly overridden; user-only entries are

package/lib/launcher/editors.js

@@ -26,6 +26,23 @@ const DEFAULTS = [
         requireAvailable: true
     }
 ];
+/**
+ * The built-in editors projected into the JSON settings shape
+ * ({@link IEditorSettings}), dropping the runtime-only {@link LabIcon}. Mirrors
+ * {@link defaultAgentSettings}: {@link registerLauncherSchemaDefaults} injects
+ * this as the `editors` setting's schema default so the Settings Editor shows
+ * the shipped list.
+ */
+export function defaultEditorSettings() {
+    return DEFAULTS.map(editor => ({
+        id: editor.id,
+        label: editor.label,
+        caption: editor.caption,
+        command: editor.command,
+        rank: editor.rank,
+        requireAvailable: editor.requireAvailable
+    }));
+}
 function resolveEditorIcon(id, iconSvg) {
     var _a;
     if (iconSvg) {

package/lib/launcher/index.js

@@ -11,6 +11,7 @@ import { CREATE_LAUNCHER_COMMAND, registerAgentCommands } from './commands';
 import { LauncherDashboard } from './dashboard';
 import { editorRegistryPlugin, IEditorRegistry } from './editorRegistry';
 import { AgentRegistry } from './registry';
+import { registerLauncherSchemaDefaults } from './schemaDefaults';
 import { IAgentRegistry } from './tokens';
 const PLUGIN_ID = 'xtralab:launcher';
 /**
@@ -77,6 +78,9 @@ const plugin = {
             return Array.isArray(raw) ? raw : [];
         };
         if (settingRegistry) {
+            // Must precede the first `load`: the schema defers loading until a
+            // transform is registered.
+            registerLauncherSchemaDefaults(settingRegistry);
             try {
                 const settings = await settingRegistry.load(PLUGIN_ID);
                 await applyAgents(readOverrides(settings));

package/lib/launcher/schemaDefaults.d.ts

@@ -0,0 +1,15 @@
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+/** Schema id the launcher's `agents`/`editors` settings live under. */
+export declare const LAUNCHER_PLUGIN_ID = "xtralab:launcher";
+/**
+ * Register a `fetch` transform that injects xtralab's built-in agent and
+ * editor lists as the schema defaults for the `xtralab:launcher` settings, so
+ * the Settings Editor shows the shipped list.
+ *
+ * The schema declares `jupyter.lab.transform: true`, so the registry defers
+ * loading the plugin until a transform is registered: callers must invoke this
+ * before their first `settingRegistry.load(LAUNCHER_PLUGIN_ID)`. Idempotent, so
+ * the two plugins that load these settings can both call it regardless of
+ * activation order.
+ */
+export declare function registerLauncherSchemaDefaults(settingRegistry: ISettingRegistry): void;