xtralab 0.4.0 → 0.6.0

package/lib/terminals/model.js

@@ -0,0 +1,418 @@
+import { Poll } from '@lumino/polling';
+import { Signal } from '@lumino/signaling';
+import { fetchRunningAgents } from './detection';
+/**
+ * How often to ask the server which agent (if any) is running in each
+ * terminal. Snappy enough that a manually-started agent's logo shows up
+ * within a few seconds, light enough that walking the shells' process trees
+ * stays negligible.
+ */
+const DETECT_POLL_INTERVAL_MS = 3000;
+/**
+ * Upper bound on the exponential backoff when detection fails repeatedly
+ * (e.g. the endpoint is missing on an older server). Matches the rest of the
+ * plugin's polls.
+ */
+const DETECT_POLL_MAX_MS = 300000;
+/**
+ * Grace window after a session first appears during which an optimistic
+ * launch tag outranks a `null` detection result. It covers the gap between
+ * issuing an agent's command and its process actually being spawnable, so the
+ * freshly-launched logo doesn't blink off if a detection poll lands in that
+ * sliver. Comfortably longer than a cold agent start; short enough that a tag
+ * for an agent that never really started clears quickly.
+ */
+const LAUNCH_GRACE_MS = 4000;
+/**
+ * Source-of-truth model for the running-terminals panel. Each running
+ * terminal session known to the server is one entry; the registry caches
+ * the last `widget.title.label` we observed so the agent name (or any
+ * xterm-published title) survives the user closing the tab while the
+ * session continues running on the backend.
+ *
+ * It also resolves *which agent is running* in each session, so the panel can
+ * badge rows with the agent's logo. Two inputs feed that, reconciled by
+ * {@link agentCommandFor}:
+ *   - an optimistic launch tag ({@link IAgentSessions}) written when we start
+ *     an agent ourselves — instant, but blind to the agent later exiting; and
+ *   - authoritative server-side process detection, polled here, which works
+ *     for hand-started agents too and clears once an agent exits.
+ *
+ * Upstream session signals:
+ *   - `serviceManager.terminals.runningChanged` is the authoritative
+ *     list of live sessions; everything not in it has been shut down
+ *     server-side and we must drop it.
+ *   - `tracker.widgetAdded` plus the per-widget `title.changed` /
+ *     `disposed` signals keep our label cache in sync with whatever
+ *     xterm/the launcher has set on the open tabs.
+ *
+ * `stateChanged` is emitted for every kind of update; the panel hooks it
+ * through a `UseSignal` so a single subscription re-renders the list on
+ * any change.
+ */
+export class SessionRegistry {
+    constructor(options) {
+        var _a, _b, _c, _d, _e, _f;
+        this._labels = new Map();
+        this._ranks = new Map();
+        this._firstSeen = new Map();
+        this._detected = new Map();
+        this._live = new Set();
+        this._currentName = null;
+        this._nextRank = 100;
+        this._isDisposed = false;
+        this._stateChanged = new Signal(this);
+        this._terminals = options.serviceManager.terminals;
+        this._tracker = options.tracker;
+        this._agentSessions = (_a = options.agentSessions) !== null && _a !== void 0 ? _a : null;
+        this._detectCommands = (_b = options.detectCommands) !== null && _b !== void 0 ? _b : (() => []);
+        this._shell = (_c = options.shell) !== null && _c !== void 0 ? _c : null;
+        this._terminals.runningChanged.connect(this._onRunningChanged, this);
+        this._tracker.widgetAdded.connect(this._onWidgetAdded, this);
+        this._tracker.forEach(widget => this._trackWidget(widget));
+        this._refreshLive();
+        // Track which terminal is the current widget in the main area so the panel
+        // can highlight its row — and highlight nothing while a notebook or any
+        // other non-terminal tab is current instead. `currentChanged` is optional
+        // on the shell interface (not every shell can switch focus), so guard it;
+        // when it is absent the highlight stays off.
+        (_e = (_d = this._shell) === null || _d === void 0 ? void 0 : _d.currentChanged) === null || _e === void 0 ? void 0 : _e.connect(this._onShellCurrentChanged, this);
+        this._updateCurrent();
+        // A freshly written launch tag should re-render the panel immediately
+        // (show the logo) and again once the grace window closes (so a tag for
+        // an agent that never started, or that detection later contradicts,
+        // doesn't linger).
+        (_f = this._agentSessions) === null || _f === void 0 ? void 0 : _f.changed.connect(this._onTagChanged, this);
+        this._poll = new Poll({
+            name: '@xtralab/terminals:runningAgents',
+            factory: () => this._refreshDetection(),
+            frequency: {
+                interval: DETECT_POLL_INTERVAL_MS,
+                backoff: true,
+                max: DETECT_POLL_MAX_MS
+            },
+            standby: 'when-hidden'
+        });
+    }
+    /**
+     * Emitted whenever the live session list, a cached label, or the detected
+     * running agent changes.
+     */
+    get stateChanged() {
+        return this._stateChanged;
+    }
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * Names of all live sessions, ordered by their stable rank so the
+     * rendered list keeps a consistent order (roughly creation order) as
+     * new sessions are added and old ones shut down.
+     */
+    sessionNames() {
+        const names = Array.from(this._live);
+        names.sort((a, b) => this.rankFor(a) - this.rankFor(b));
+        return names;
+    }
+    /**
+     * True iff the named session is still on the server. Used by the panel
+     * to skip a row during the brief window between the session's shutdown
+     * and the next `runningChanged` arriving.
+     */
+    has(name) {
+        return this._live.has(name);
+    }
+    /**
+     * Display name for the session. The cache wins because it only
+     * holds "real" labels (the launcher's agent name or an xterm escape
+     * sequence — see `_cacheLabel` for the filter); reading it first
+     * prevents the transient `Terminal {name}` an XTerm widget shows
+     * during reconnect from flickering into the panel. The live widget
+     * title is used when no cache exists, and the `Terminal {name}`
+     * fallback covers sessions we have never seen a widget for (e.g.
+     * surviving a lab reload).
+     */
+    labelFor(name) {
+        const cached = this._labels.get(name);
+        if (cached) {
+            return cached;
+        }
+        const widget = this.widgetFor(name);
+        if (widget && widget.title.label) {
+            return widget.title.label;
+        }
+        return `Terminal ${name}`;
+    }
+    /**
+     * The command of the agent running in the session, or `null` if none.
+     *
+     * Server-side detection is authoritative whenever it reports a running
+     * agent. A launch tag fills two gaps: the startup grace window right after
+     * we launch an agent (so its logo shows before its process is detectable),
+     * and any time detection is unavailable (older server, transient error).
+     * Once the grace window has passed and detection has reported the session
+     * as idle, the tag is ignored — that is how the badge clears when an agent
+     * exits.
+     */
+    agentCommandFor(name) {
+        var _a, _b, _c;
+        // `string` = detected running agent, `null` = polled and idle,
+        // `undefined` = not covered by a successful poll yet.
+        const detected = this._detected.has(name)
+            ? this._detected.get(name)
+            : undefined;
+        if (typeof detected === 'string') {
+            return detected;
+        }
+        const tagged = (_b = (_a = this._agentSessions) === null || _a === void 0 ? void 0 : _a.get(name)) !== null && _b !== void 0 ? _b : null;
+        if (tagged !== null) {
+            const seenAt = (_c = this._firstSeen.get(name)) !== null && _c !== void 0 ? _c : 0;
+            const inGrace = Date.now() - seenAt < LAUNCH_GRACE_MS;
+            if (inGrace || detected === undefined) {
+                return tagged;
+            }
+        }
+        return null;
+    }
+    /**
+     * Return the open widget for a session, if any. The panel uses this to
+     * switch behaviour between "activate existing tab" and "open a new tab
+     * connected to the live session".
+     */
+    widgetFor(name) {
+        var _a;
+        return ((_a = this._tracker.find(widget => widget.content.session.name === name)) !== null && _a !== void 0 ? _a : null);
+    }
+    /**
+     * Session name of the terminal that is currently the active widget in the
+     * shell's main area, or `null` when that widget is not a terminal (for
+     * example a notebook or text editor is current). The panel uses this to
+     * highlight the current terminal's row — mirroring how the file browser
+     * surfaces the open document — and to leave every row unhighlighted while a
+     * non-terminal tab is current.
+     */
+    currentSessionName() {
+        return this._currentName;
+    }
+    /**
+     * Stable per-session rank assigned in observation order. Used to keep
+     * the rendered list in a steady order so rows don't reshuffle as
+     * sessions come and go. Cleaned up when the session is shut down so the
+     * counter does not grow without bound across long sessions.
+     */
+    rankFor(name) {
+        let rank = this._ranks.get(name);
+        if (rank === undefined) {
+            rank = this._nextRank++;
+            this._ranks.set(name, rank);
+        }
+        return rank;
+    }
+    dispose() {
+        var _a, _b, _c;
+        if (this._isDisposed) {
+            return;
+        }
+        this._isDisposed = true;
+        this._poll.dispose();
+        this._terminals.runningChanged.disconnect(this._onRunningChanged, this);
+        this._tracker.widgetAdded.disconnect(this._onWidgetAdded, this);
+        (_a = this._agentSessions) === null || _a === void 0 ? void 0 : _a.changed.disconnect(this._onTagChanged, this);
+        (_c = (_b = this._shell) === null || _b === void 0 ? void 0 : _b.currentChanged) === null || _c === void 0 ? void 0 : _c.disconnect(this._onShellCurrentChanged, this);
+        this._tracker.forEach(widget => this._untrackWidget(widget));
+        Signal.clearData(this);
+    }
+    _refreshLive() {
+        const next = new Set();
+        for (const model of this._terminals.running()) {
+            next.add(model.name);
+        }
+        this._reconcileLive(next);
+    }
+    _onRunningChanged(_, sessions) {
+        this._reconcileLive(new Set(sessions.map(model => model.name)));
+        this._stateChanged.emit();
+    }
+    /**
+     * Adopt `next` as the live set and prune every per-session map for
+     * sessions that have gone away — labels, ranks, first-seen timestamps,
+     * detection results, and the shared launch tag. Without this the maps (and
+     * the rank counter) would grow without bound as terminals come and go.
+     */
+    _reconcileLive(next) {
+        var _a;
+        // Names we had already seen, captured before we prune below — the set of
+        // candidates whose launch tag may now need forgetting. (The tag map is
+        // not enumerable, so we drive the prune from the sessions we know about;
+        // `_firstSeen` has an entry for every session that has ever been live.)
+        const known = Array.from(this._firstSeen.keys());
+        for (const name of next) {
+            if (!this._firstSeen.has(name)) {
+                this._firstSeen.set(name, Date.now());
+            }
+        }
+        this._live = next;
+        for (const name of Array.from(this._labels.keys())) {
+            if (!next.has(name)) {
+                this._labels.delete(name);
+            }
+        }
+        for (const name of Array.from(this._ranks.keys())) {
+            if (!next.has(name)) {
+                this._ranks.delete(name);
+            }
+        }
+        for (const name of Array.from(this._firstSeen.keys())) {
+            if (!next.has(name)) {
+                this._firstSeen.delete(name);
+            }
+        }
+        for (const name of Array.from(this._detected.keys())) {
+            if (!next.has(name)) {
+                this._detected.delete(name);
+            }
+        }
+        // Forget launch tags for sessions that have gone away. This matters for
+        // correctness as well as bookkeeping: terminado reuses session names, so
+        // a stale tag could otherwise mislabel a brand-new terminal that happens
+        // to reuse a closed session's name.
+        for (const name of known) {
+            if (!next.has(name)) {
+                (_a = this._agentSessions) === null || _a === void 0 ? void 0 : _a.delete(name);
+            }
+        }
+    }
+    /**
+     * Poll body: ask the server which agent runs in each terminal and update
+     * the detection map. On failure we keep the previous results rather than
+     * clearing them, so a transient error doesn't strip every badge.
+     */
+    async _refreshDetection() {
+        const commands = this._detectCommands();
+        if (commands.length === 0) {
+            if (this._detected.size > 0) {
+                this._detected = new Map();
+                this._stateChanged.emit();
+            }
+            return;
+        }
+        const result = await fetchRunningAgents(commands);
+        if (result === null) {
+            return;
+        }
+        const next = new Map();
+        for (const [name, command] of Object.entries(result)) {
+            if (this._live.has(name)) {
+                next.set(name, command);
+            }
+        }
+        if (!Private.detectedEqual(this._detected, next)) {
+            this._detected = next;
+            this._stateChanged.emit();
+        }
+    }
+    _onTagChanged() {
+        this._stateChanged.emit();
+        // Re-render once the grace window closes so a tag that detection never
+        // confirmed (or has since contradicted) stops being shown.
+        setTimeout(() => {
+            if (!this._isDisposed) {
+                this._stateChanged.emit();
+            }
+        }, LAUNCH_GRACE_MS + 100);
+    }
+    _onWidgetAdded(_, widget) {
+        this._trackWidget(widget);
+        this._stateChanged.emit();
+    }
+    _onShellCurrentChanged() {
+        this._updateCurrent();
+    }
+    /**
+     * Recompute which terminal (if any) is the active main-area widget and emit
+     * only when it changes. The terminal tracker tells us whether the shell's
+     * current widget is one of our terminals; anything else — a notebook, an
+     * editor, or nothing — clears the highlight.
+     */
+    _updateCurrent() {
+        var _a, _b;
+        const current = (_b = (_a = this._shell) === null || _a === void 0 ? void 0 : _a.currentWidget) !== null && _b !== void 0 ? _b : null;
+        const name = current && this._tracker.has(current)
+            ? current.content.session.name
+            : null;
+        if (name !== this._currentName) {
+            this._currentName = name;
+            this._stateChanged.emit();
+        }
+    }
+    _trackWidget(widget) {
+        const name = widget.content.session.name;
+        this._cacheLabel(name, widget.title.label);
+        widget.title.changed.connect(this._onTitleChanged, this);
+        widget.disposed.connect(this._onWidgetDisposed, this);
+    }
+    _untrackWidget(widget) {
+        widget.title.changed.disconnect(this._onTitleChanged, this);
+        widget.disposed.disconnect(this._onWidgetDisposed, this);
+    }
+    _onTitleChanged(title) {
+        var _a;
+        const owner = title.owner;
+        const session = (_a = owner.content) === null || _a === void 0 ? void 0 : _a.session;
+        if (!session) {
+            return;
+        }
+        this._cacheLabel(session.name, title.label);
+        this._stateChanged.emit();
+    }
+    /**
+     * Update the cached label for a session, but only when the new
+     * label is "real" — non-empty and not one of the transient defaults
+     * the XTerm widget cycles through during reconnect (`'...'` while
+     * the websocket is opening, `'Terminal {name}'` once
+     * `_initialConnection` fires). Without the filter, briefly
+     * reopening a tab while an agent has yet to re-emit its xterm
+     * title escape sequence would clobber the cached agent name with
+     * `Terminal 1`, which is exactly the regression we are guarding
+     * against. Live widget titles still display whatever the widget
+     * currently holds because `labelFor` consults the widget first;
+     * the filter only affects what survives a tab close.
+     */
+    _cacheLabel(name, label) {
+        if (!label) {
+            return;
+        }
+        if (label === '...' || label === `Terminal ${name}`) {
+            return;
+        }
+        this._labels.set(name, label);
+    }
+    _onWidgetDisposed(widget) {
+        // The widget is gone but the session may still be running on the
+        // server — keep the cached label so the panel keeps the agent's name
+        // when the user reopens the tab. We only clean up our subscriptions
+        // here; the cache is purged by `runningChanged` once the session
+        // itself goes away.
+        this._untrackWidget(widget);
+        this._stateChanged.emit();
+    }
+}
+var Private;
+(function (Private) {
+    /**
+     * Value-equality for two detection maps, so a poll that changes nothing
+     * doesn't trigger a re-render.
+     */
+    function detectedEqual(a, b) {
+        if (a.size !== b.size) {
+            return false;
+        }
+        for (const [name, command] of a) {
+            if (!b.has(name) || b.get(name) !== command) {
+                return false;
+            }
+        }
+        return true;
+    }
+    Private.detectedEqual = detectedEqual;
+})(Private || (Private = {}));

package/lib/terminals/widget.d.ts

@@ -0,0 +1,72 @@
+import { type TranslationBundle } from '@jupyterlab/translation';
+import { LabIcon, ReactWidget } from '@jupyterlab/ui-components';
+import * as React from 'react';
+import { SessionRegistry } from './model';
+/**
+ * Id of the panel widget. Used for layout restoration and as the handle
+ * the sidebar visibility toggle would target.
+ */
+export declare const RUNNING_TERMINALS_ID = "xtralab-running-terminals";
+/**
+ * Left-sidebar panel listing every running terminal session. It is the
+ * sidebar counterpart of the launcher's terminal tiles: where the
+ * launcher *starts* sessions, this panel surfaces the ones already
+ * running so the user can jump back to a backgrounded agent — including
+ * sessions whose tab has been closed but which are still alive on the
+ * server.
+ *
+ * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
+ * whenever the registry emits `stateChanged`, so it tracks
+ * `runningChanged` and the agent-title cache without any local state.
+ * Click behaviour (activate vs. reopen, shutdown, new terminal) is
+ * delegated to plugin-supplied callbacks so the widget never imports
+ * `app`.
+ */
+export declare class RunningTerminals extends ReactWidget {
+    constructor(options: RunningTerminals.IOptions);
+    dispose(): void;
+    protected render(): React.ReactElement;
+    private _registry;
+    private _trans;
+    private _iconForCommand;
+    private _onActivate;
+    private _onShutdown;
+    private _onShutdownAll;
+    private _onCreate;
+}
+export declare namespace RunningTerminals {
+    interface IOptions {
+        registry: SessionRegistry;
+        trans?: TranslationBundle;
+        /**
+         * Resolve the running-agent command for a row (from
+         * `registry.agentCommandFor`) to the icon to show before its label —
+         * the agent's logo, or the plain terminal icon. Supplied by the plugin
+         * so the widget never imports the agent list.
+         */
+        iconForCommand: (command: string | null) => LabIcon;
+        /**
+         * Activate the named session's open tab, or reopen it in a fresh
+         * terminal widget if no tab is currently attached.
+         */
+        onActivate: (sessionName: string) => void;
+        /** Shut the named session down on the server. */
+        onShutdown: (sessionName: string) => void;
+        /**
+         * Shut down every running terminal at once. The plugin is expected to
+         * confirm with the user first, since it tears down all live sessions.
+         */
+        onShutdownAll: () => void;
+        /**
+         * Activate the "+" button, anchored at the given viewport coordinates
+         * (the bottom-left of the button). The plugin decides what to show
+         * there — a menu of agents plus a plain terminal, or just a new
+         * terminal when no agents are available — so the panel only reports
+         * where the button is and never imports the command/menu machinery.
+         */
+        onCreate: (anchor: {
+            x: number;
+            y: number;
+        }) => void;
+    }
+}

package/lib/terminals/widget.js

@@ -0,0 +1,93 @@
+import { nullTranslator } from '@jupyterlab/translation';
+import { addIcon, closeIcon, ReactWidget, stopIcon, terminalIcon, UseSignal } from '@jupyterlab/ui-components';
+import * as React from 'react';
+/**
+ * Id of the panel widget. Used for layout restoration and as the handle
+ * the sidebar visibility toggle would target.
+ */
+export const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
+/**
+ * Left-sidebar panel listing every running terminal session. It is the
+ * sidebar counterpart of the launcher's terminal tiles: where the
+ * launcher *starts* sessions, this panel surfaces the ones already
+ * running so the user can jump back to a backgrounded agent — including
+ * sessions whose tab has been closed but which are still alive on the
+ * server.
+ *
+ * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
+ * whenever the registry emits `stateChanged`, so it tracks
+ * `runningChanged` and the agent-title cache without any local state.
+ * Click behaviour (activate vs. reopen, shutdown, new terminal) is
+ * delegated to plugin-supplied callbacks so the widget never imports
+ * `app`.
+ */
+export class RunningTerminals extends ReactWidget {
+    constructor(options) {
+        var _a;
+        super();
+        this._registry = options.registry;
+        this._trans = (_a = options.trans) !== null && _a !== void 0 ? _a : nullTranslator.load('jupyterlab');
+        this._iconForCommand = options.iconForCommand;
+        this._onActivate = options.onActivate;
+        this._onShutdown = options.onShutdown;
+        this._onShutdownAll = options.onShutdownAll;
+        this._onCreate = options.onCreate;
+        this.id = RUNNING_TERMINALS_ID;
+        this.title.icon = terminalIcon;
+        this.title.caption = this._trans.__('Running Terminals');
+        this.addClass('jp-xtralab-Terminals');
+    }
+    dispose() {
+        if (this.isDisposed) {
+            return;
+        }
+        // The panel owns the registry, so tear down its upstream
+        // subscriptions before the React tree goes away.
+        this._registry.dispose();
+        super.dispose();
+    }
+    render() {
+        return (React.createElement(UseSignal, { signal: this._registry.stateChanged }, () => (React.createElement(RunningTerminalsComponent, { registry: this._registry, trans: this._trans, iconForCommand: this._iconForCommand, onActivate: this._onActivate, onShutdown: this._onShutdown, onShutdownAll: this._onShutdownAll, onCreate: this._onCreate }))));
+    }
+}
+function RunningTerminalsComponent(props) {
+    const { registry, trans, iconForCommand, onActivate, onShutdown, onShutdownAll, onCreate } = props;
+    const names = registry.sessionNames();
+    // The session whose terminal is the current widget in the main area, so its
+    // row can be highlighted. `null` when the current tab is a notebook or any
+    // other non-terminal widget.
+    const currentName = registry.currentSessionName();
+    return (React.createElement("div", { className: "jp-xtralab-Terminals-body" },
+        React.createElement("div", { className: "jp-xtralab-Terminals-header" },
+            React.createElement("h2", { className: "jp-xtralab-Terminals-title" }, trans.__('Terminals')),
+            React.createElement("div", { className: "jp-xtralab-Terminals-actions" },
+                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-action jp-xtralab-Terminals-shutdown-all", onClick: onShutdownAll, disabled: names.length === 0, title: trans.__('Shut Down All Terminals'), "aria-label": trans.__('Shut Down All Terminals') },
+                    React.createElement(stopIcon.react, { tag: "span", verticalAlign: "middle" })),
+                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-action jp-xtralab-Terminals-new", onClick: event => {
+                        // Anchor whatever the plugin shows (usually an agent menu) to
+                        // the button's bottom-left, in viewport coordinates — what
+                        // `Menu.open(x, y)` expects.
+                        const rect = event.currentTarget.getBoundingClientRect();
+                        onCreate({ x: rect.left, y: rect.bottom });
+                    }, title: trans.__('New Terminal'), "aria-label": trans.__('New Terminal'), "aria-haspopup": "menu" },
+                    React.createElement(addIcon.react, { tag: "span", verticalAlign: "middle" })))),
+        names.length === 0 ? (React.createElement("p", { className: "jp-xtralab-Terminals-empty" }, trans.__('No running terminals.'))) : (React.createElement("ul", { className: "jp-xtralab-Terminals-list" }, names.map(name => {
+            const label = registry.labelFor(name);
+            const hasWidget = registry.widgetFor(name) !== null;
+            const tooltip = hasWidget
+                ? trans.__('Activate %1', label)
+                : trans.__('Reopen %1', label);
+            // The running agent's logo (e.g. Claude), or the plain terminal
+            // icon when nothing recognised is running in the session.
+            const RowIcon = iconForCommand(registry.agentCommandFor(name)).react;
+            const isCurrent = name === currentName;
+            return (React.createElement("li", { key: name, className: isCurrent
+                    ? 'jp-xtralab-Terminals-item jp-mod-current'
+                    : 'jp-xtralab-Terminals-item' },
+                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-activate", onClick: () => onActivate(name), title: tooltip, "aria-label": tooltip, "aria-current": isCurrent || undefined },
+                    React.createElement(RowIcon, { tag: "span", verticalAlign: "middle" }),
+                    React.createElement("span", { className: "jp-xtralab-Terminals-item-label" }, label)),
+                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-close", onClick: () => onShutdown(name), title: trans.__('Shut down %1', label), "aria-label": trans.__('Shut down %1', label) },
+                    React.createElement(closeIcon.react, { tag: "span", verticalAlign: "middle" }))));
+        })))));
+}

package/lib/topBar/icons.d.ts

@@ -0,0 +1,13 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * Mirror-symmetric "toggle sidebar" marks for the top-bar buttons, in the
+ * same visual language as the macOS / VS Code / svgrepo sidebar icons
+ * (https://www.svgrepo.com/vectors/sidebar/): a rounded window outline split
+ * by a divider, with the controlled side shaded so left vs. right reads at a
+ * glance. The artwork is hand-authored from basic geometry (rounded rect +
+ * divider + a shaded panel) so there is no third-party licensing to track,
+ * and every stroke/fill uses `currentColor` so the icons inherit the top
+ * bar's text color across the light and dark themes.
+ */
+export declare const leftSidebarIcon: LabIcon;
+export declare const rightSidebarIcon: LabIcon;

package/lib/topBar/icons.js

@@ -0,0 +1,27 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * Mirror-symmetric "toggle sidebar" marks for the top-bar buttons, in the
+ * same visual language as the macOS / VS Code / svgrepo sidebar icons
+ * (https://www.svgrepo.com/vectors/sidebar/): a rounded window outline split
+ * by a divider, with the controlled side shaded so left vs. right reads at a
+ * glance. The artwork is hand-authored from basic geometry (rounded rect +
+ * divider + a shaded panel) so there is no third-party licensing to track,
+ * and every stroke/fill uses `currentColor` so the icons inherit the top
+ * bar's text color across the light and dark themes.
+ */
+export const leftSidebarIcon = new LabIcon({
+    name: 'xtralab:sidebar-left',
+    svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M9 3H5.5A2.5 2.5 0 0 0 3 5.5V18.5A2.5 2.5 0 0 0 5.5 21H9Z" fill="currentColor" fill-opacity="0.3"/>
+  <rect x="3" y="3" width="18" height="18" rx="2.5" stroke="currentColor" stroke-width="1.7"/>
+  <line x1="9" y1="3" x2="9" y2="21" stroke="currentColor" stroke-width="1.7"/>
+</svg>`
+});
+export const rightSidebarIcon = new LabIcon({
+    name: 'xtralab:sidebar-right',
+    svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M15 3H18.5A2.5 2.5 0 0 1 21 5.5V18.5A2.5 2.5 0 0 1 18.5 21H15Z" fill="currentColor" fill-opacity="0.3"/>
+  <rect x="3" y="3" width="18" height="18" rx="2.5" stroke="currentColor" stroke-width="1.7"/>
+  <line x1="15" y1="3" x2="15" y2="21" stroke="currentColor" stroke-width="1.7"/>
+</svg>`
+});

package/lib/topBar/index.d.ts

@@ -0,0 +1,16 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Add two icon buttons to the top bar that toggle the left and right side
+ * areas, mirroring the macOS-style sidebar buttons: a left-sidebar button at
+ * the leading edge and a right-sidebar button at the far edge.
+ *
+ * Each is a `CommandToolbarButton` wrapping an existing
+ * `application:toggle-{left,right}-area` command, so clicking it runs the
+ * same toggle as the View menu and the button reflects the command's state —
+ * pressed while the matching sidebar is open, and disabled when the area is
+ * empty. Note xtralab ships nothing in the right area by default (the
+ * property inspector, table of contents and debugger are all disabled), so
+ * the right button stays disabled until a widget is moved or added there.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;