@oceanum/oceanumlab 4.7.0 → 4.7.1

package/README.md

@@ -19,6 +19,62 @@ To install the extension, execute:
 pip install oceanumlab
 ```
 
+## Oceanum.io sign-in
+
+A **Sign in to Oceanum.io** control sits in the top bar. Signing in gives the Notebooks tab
+your stored notebooks and lets Oceanum AI act as you, with no Datamesh token to paste.
+
+It uses the OAuth **device grant**, run by oceanumlab's Jupyter server extension: click
+**Sign in**, open the link it shows, check the code matches, and sign in on Oceanum.io as
+usual. The dialog closes by itself when you are done. It works with no configuration, and
+from any address — `localhost` on any port, a JupyterHub, a remote server.
+
+That last point is why it works this way. A browser sign-in (a popup, a redirect, the
+Oceanum widget) has to tell Auth0 which page to return to, Auth0 only accepts addresses
+registered in advance, and it cannot wildcard a port or an arbitrary host. A JupyterLab's
+address is not knowable ahead of time, so on anything but Oceanum's own sites a browser
+sign-in fails with "Callback URL mismatch". The device grant has no callback.
+
+The refresh token stays in the Jupyter server's memory and never reaches the page or the
+disk, so restarting the server signs you out.
+
+### Configuration
+
+Sign-in is server configuration, not a frontend setting: which Auth0 tenant a notebook signs
+in to, and which services its tokens are sent to, is the deployment's decision, and a
+user-editable setting could be pointed at someone else's. In `jupyter_server_config.py` —
+`~/.jupyter/` for one user, or `etc/jupyter/` under the environment prefix for everyone
+using it; `jupyter --paths` lists both:
+
+```python
+c.OceanumLab.sign_in = "off"        # "device" is the default
+```
+
+To sign in to a deployment other than Oceanum production, replace the environment whole:
+
+```python
+c.OceanumLab.device_environment = {
+    "auth0Domain": "auth.example.org",
+    "clientId": "<an Auth0 Native application with the Device Code grant>",
+    "audience": "",
+    "oceanumDomain": "example.org",
+    "urls": {
+        "datamesh": "https://datamesh.example.org",
+        "specs": "https://specs.example.org",
+        "manage": "https://manage.example.org",
+    },
+}
+```
+
+**This file is Python, not JSON** — `True`, not `true`. A syntax error there is quiet and
+expensive: traitlets logs it once at startup and then skips the **whole** file, so the
+setting silently does not apply. Check the server's startup log for
+`oceanumlab: Oceanum.io sign-in by device code`.
+
+notebook.oceanum.io is a JupyterLite site with no Jupyter server, so none of this applies
+there. It signs in with the Oceanum widget, from its own extension, and lists
+`@oceanum/oceanumlab:device-auth` under `disabledExtensions`.
+
 ## Uninstall
 
 To remove the extension, execute:
@@ -31,27 +87,59 @@ pip uninstall oceanumlab
 
 ### Development install
 
-Note: You will need NodeJS 22.12 or later (or 20.19+) to build the extension package.
+The extension is built with [jupyter-builder](https://github.com/jupyterlab/jupyter-builder),
+which bundles it with rspack. You will need:
+
+- Python 3.10 or later
+- Node.js 22.12 or later (or 20.19+), which rspack requires
 
-The `jlpm` command is JupyterLab's pinned version of
-[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
-`yarn` or `npm` in lieu of `jlpm` below.
+The `jlpm` command is a pinned version of [yarn](https://yarnpkg.com/) that is
+installed with jupyter-builder. You may use `yarn` or `npm` in lieu of `jlpm` below.
+
+Create an environment, either with conda, which also installs Node.js and jupyter-builder:
 
 ```bash
 # Clone the repo to your local environment
 # Change directory to the oceanumlab directory
-# Install package in development mode, with jupyter-builder for building the extension
-pip install -e ".[dev]"
+conda env create -f environment.yml
+conda activate oceanumlab
+```
+
+or with a virtual environment, using your own Node.js:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Then install the extension in development mode:
+
+```bash
+# Install the package in development mode. The dev extra installs jupyter-builder
+# and the test extra installs the server test dependencies. This also enables the
+# server extension.
+pip install -e ".[dev,test]"
 # Link your development version of the extension with JupyterLab
 jupyter-builder develop . --overwrite
-# Rebuild extension Typescript source after making changes
+# Rebuild the extension after making changes
+# Unlike the steps above, which you only do once, do this every time you make a change
 jlpm build
 ```
 
+Every `pip install -e` puts a copy of the built extension back in place of the link,
+so run `jupyter-builder develop . --overwrite` again after reinstalling.
+
+The main build commands are:
+
+- `jlpm build`: development build, with source maps
+- `jlpm build:prod`: production build, as used for releases
+- `jlpm clean:all`: remove the built TypeScript, the built extension and the lint caches
+
 You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
 
 ```bash
 # Watch the source directory in one terminal, automatically rebuilding when needed
+# (runs tsc and jupyter-builder in watch mode)
 jlpm watch
 # Run JupyterLab in another terminal
 jupyter lab
@@ -71,9 +159,9 @@ jupyter lab build --minimize=False
 pip uninstall oceanumlab
 ```
 
-In development mode, you will also need to remove the symlink created by `jupyter-builder develop`
+In development mode, you will also need to remove the symlink created by the `jupyter-builder develop`
 command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions`
-folder is located. Then you can remove the symlink named `oceanumlab` within that folder.
+folder is located. Then you can remove the symlink named `@oceanum/oceanumlab` within that folder.
 
 ### Testing the extension
 
@@ -81,10 +169,13 @@ folder is located. Then you can remove the symlink named `oceanumlab` within tha
 
 This extension is using [Pytest](https://docs.pytest.org/) for Python code testing.
 
-Install test dependencies (needed only once):
+The test dependencies are installed by `pip install -e ".[dev,test]"` above. If you
+installed without the test extra, install them (needed only once) and restore the
+front-end extension link:
 
 ```sh
-pip install -e ".[test]"
+pip install -e ".[dev,test]"
+jupyter-builder develop . --overwrite
 ```
 
 To execute them, run:

package/lib/DatameshUI.d.ts

@@ -2,13 +2,8 @@ import React from 'react';
 import { ReactWidget } from '@jupyterlab/apputils';
 export declare class DatameshUI extends ReactWidget {
     private _url;
-    /** `url` is the `datameshUiUrl` setting. */
+    /** `url` is the deployment's Datamesh UI address (the sign-in environment's). */
     constructor(_url: string);
-    /**
-     * Point the panel at the `datameshUiUrl` setting's new value. The iframe
-     * reloads only if its address actually changes.
-     */
-    set url(url: string);
     /** The iframe's window, for telling its messages apart; `null` if none. */
     get frame(): Window | null;
     render(): React.ReactElement;

package/lib/DatameshUI.js

@@ -2,19 +2,11 @@ import React from 'react';
 import { ReactWidget } from '@jupyterlab/apputils';
 import { datameshUiSrc } from './datameshUiUrl';
 export class DatameshUI extends ReactWidget {
-    /** `url` is the `datameshUiUrl` setting. */
+    /** `url` is the deployment's Datamesh UI address (the sign-in environment's). */
     constructor(_url) {
         super();
         this._url = _url;
     }
-    /**
-     * Point the panel at the `datameshUiUrl` setting's new value. The iframe
-     * reloads only if its address actually changes.
-     */
-    set url(url) {
-        this._url = url;
-        this.update();
-    }
     /** The iframe's window, for telling its messages apart; `null` if none. */
     get frame() {
         var _a, _b;

package/lib/DatameshWidget.d.ts

@@ -5,6 +5,7 @@ import { CommandRegistry } from '@lumino/commands';
 import { ISignal, Signal } from '@lumino/signaling';
 import { Widget } from '@lumino/widgets';
 import React from 'react';
+import { IOceanumAuth } from './auth/tokens';
 export interface IDatasource {
     id: string;
     label: string;
@@ -40,18 +41,22 @@ export interface IDatameshWidgetProps {
     name: string;
     icon: LabIcon;
     openDatameshUI: any;
-    /** The `datameshUiUrl` setting. */
+    /** The deployment's Datamesh UI address. */
     datameshUiUrl: () => string;
     /** The Datamesh UI panel's iframe window; `null` when the panel is closed. */
     datameshUiFrame: () => Window | null;
     /** The `datameshToken` setting. */
     datameshToken: () => string;
-    /** The `aiBackendUrl` setting. */
+    /** The deployment's Oceanum AI address. */
     aiBackendUrl: () => string;
     /** Emitted when the settings change. */
     settingsChanged: ISignal<unknown, void>;
     commands: CommandRegistry;
     getCurrentWidget: () => Widget;
+    /** Oceanum.io sign-in, or null on a host with no Oceanum environment. */
+    auth?: IOceanumAuth | null;
+    /** Open a stored notebook by spec store id. */
+    openStoredNotebook?: (id: string) => void;
 }
 /**
  * A widget for Datamesh Connections.
@@ -65,5 +70,16 @@ export declare class DatameshConnectWidget extends ReactWidget {
     constructor(props: IDatameshWidgetProps);
     receiveIFrameMessage(event: MessageEvent): void;
     renderDisplay(datameshWorkspace: IWorkspaceSpec): React.ReactElement;
+    /** The Datamesh workspace tab: what this panel showed above the divider. */
+    renderDatamesh(): React.ReactElement;
     render(): React.ReactElement;
+    /**
+     * The visible tab. The widget only holds it and announces changes through
+     * `tabChanged`; the plugin persists it in IStateDB, because the layout restorer
+     * restores a widget's place in the shell rather than fields on it.
+     */
+    get selectedTab(): string;
+    selectTab(id: string): void;
+    readonly tabChanged: Signal<this, string>;
+    private _selectedTab;
 }

package/lib/DatameshWidget.js

@@ -9,6 +9,8 @@ import { Signal } from '@lumino/signaling';
 import React from 'react';
 import { marked } from 'marked';
 import { DatasourceItem } from './DatasourceItem';
+import { StoredNotebooks } from './StoredNotebooks';
+import { Tabs } from './Tabs';
 import { SIGN_IN_COMMAND, aiBackendUrl, aiCredentialSource, canSignIn, pastedToken, resolveAiCredential, signInToken } from './aiBackend';
 import { isDatameshUiMessage } from './datameshUiUrl';
 import { describeProgress, onProgress } from './progress';
@@ -342,9 +344,11 @@ function TokenConfigMessage({ commands, settings }) {
             "."));
     }
     return (React.createElement("div", { className: "oceanum-token-config" },
-        "Set your ",
-        React.createElement("a", { onClick: openSettings }, "Datamesh token"),
-        " to enable Oceanum.io services",
+        "Set your",
+        ' ',
+        React.createElement("a", { onClick: () => commands.execute('settingeditor:open', { query: 'Oceanum' }) }, "Datamesh token"),
+        ' ',
+        "to enable Oceanum.io services",
         ' ',
         React.createElement("a", { href: "https://home.oceanum.io/account", target: "_blank", rel: "noopener noreferrer" }, "Get token here")));
 }
@@ -596,6 +600,37 @@ function AIChatPanel({ commands, settings }) {
                     ? commands.execute('oceanum-ai:stop')
                     : handleSubmit()), disabled: !loading && !input.trim(), title: loading ? 'Stop the current response' : undefined }, loading ? 'Stop' : 'Send'))));
 }
+/**
+ * The panel's tabs.
+ *
+ * A component rather than a list built in `render`, because whether Oceanum AI is
+ * reachable is not static: `useAiAccess` re-reads it when the settings change and when
+ * the host signals a sign-in or sign-out. An AI tab is only offered when the chat has a
+ * credential to work with — otherwise it would open on the same nothing the panel
+ * rendered before there were tabs, except now with a label promising otherwise.
+ */
+function PanelTabs({ auth, commands, settings, renderDatamesh, selected, onSelect }) {
+    const access = useAiAccess(commands, settings);
+    const tabs = [
+        {
+            id: 'notebooks',
+            label: 'Notebooks',
+            render: () => 
+            // An auth with no environment is a provider that has nothing to sign in to (the
+            // server has sign-in turned off). Asking the user to sign in would be a dead end.
+            (auth === null || auth === void 0 ? void 0 : auth.environment) ? (React.createElement(StoredNotebooks, { auth: auth })) : (React.createElement("div", { className: "oceanum-text-empty" }, "Oceanum.io sign-in is not configured for this host."))
+        },
+        { id: 'datamesh', label: 'Datamesh', render: renderDatamesh }
+    ];
+    if (access.source) {
+        tabs.push({
+            id: 'ai',
+            label: 'Oceanum AI',
+            render: () => React.createElement(AIChatPanel, { commands: commands, settings: settings })
+        });
+    }
+    return React.createElement(Tabs, { tabs: tabs, selected: selected, onSelect: onSelect });
+}
 /**
  * A widget for Datamesh Connections.
  */
@@ -603,6 +638,10 @@ export class DatameshConnectWidget extends ReactWidget {
     constructor(props) {
         super();
         this.datameshWorkspaceSpec = null;
+        this.tabChanged = new Signal(this);
+        // Notebooks first: on notebook.oceanum.io this panel is how a user reaches their
+        // work, so it opens there rather than on Datamesh.
+        this._selectedTab = 'notebooks';
         this.props = props;
         this.renderSignal = new Signal(this);
         this.renderDisplay = this.renderDisplay.bind(this);
@@ -628,18 +667,38 @@ export class DatameshConnectWidget extends ReactWidget {
             React.createElement("a", { onClick: this.props.openDatameshUI }, "Open"),
             " the Oceanum Datamesh UI to add datasources."))));
     }
-    render() {
-        return (React.createElement("div", { className: "datamesh-connect" },
-            React.createElement("header", { className: "oceanum-sidebar-header" },
-                React.createElement(this.props.icon.react, { tag: "span", width: "auto", height: "20px", verticalAlign: "middle" }),
-                React.createElement("span", { className: "oceanum-sidebar-title" }, "Oceanum.io")),
+    /** The Datamesh workspace tab: what this panel showed above the divider. */
+    renderDatamesh() {
+        return (React.createElement(React.Fragment, null,
             React.createElement("div", { className: "datamesh-workspace-header" },
                 React.createElement("span", null, "Datamesh Workspace"),
                 React.createElement("div", { className: "open-datamesh-ui", onClick: this.props.openDatameshUI, title: "Open Datamesh UI" }, React.createElement(addIcon.react, { height: "20px", verticalAlign: "middle" }))),
             React.createElement("div", { className: "datamesh-connect-workspace" },
                 React.createElement(UseSignal, { signal: this.renderSignal, initialArgs: null }, (_, datameshWorkspace) => this.renderDisplay(datameshWorkspace)),
-                React.createElement(TokenConfigMessage, { commands: this.props.commands, settings: this.props })),
-            React.createElement("div", { className: "datamesh-connect-divider" }),
-            React.createElement(AIChatPanel, { commands: this.props.commands, settings: this.props })));
+                React.createElement(TokenConfigMessage, { commands: this.props.commands, settings: this.props }))));
+    }
+    render() {
+        return (React.createElement("div", { className: "datamesh-connect" },
+            React.createElement("header", { className: "oceanum-sidebar-header" },
+                React.createElement(this.props.icon.react, { tag: "span", width: "auto", height: "20px", verticalAlign: "middle" }),
+                React.createElement("span", { className: "oceanum-sidebar-title" }, "Oceanum.io")),
+            React.createElement(UseSignal, { signal: this.tabChanged, initialArgs: this.selectedTab }, () => {
+                var _a;
+                return (React.createElement(PanelTabs, { auth: (_a = this.props.auth) !== null && _a !== void 0 ? _a : null, commands: this.props.commands, settings: this.props, renderDatamesh: () => this.renderDatamesh(), selected: this.selectedTab, onSelect: id => this.selectTab(id) }));
+            })));
+    }
+    /**
+     * The visible tab. The widget only holds it and announces changes through
+     * `tabChanged`; the plugin persists it in IStateDB, because the layout restorer
+     * restores a widget's place in the shell rather than fields on it.
+     */
+    get selectedTab() {
+        return this._selectedTab;
+    }
+    selectTab(id) {
+        if (id !== this._selectedTab) {
+            this._selectedTab = id;
+            this.tabChanged.emit(id);
+        }
     }
 }

package/lib/StoredNotebooks.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { IOceanumAuth } from './auth/tokens';
+import { ISpecSummary } from './specStore';
+export interface IStoredNotebooksProps {
+    auth: IOceanumAuth;
+    /**
+     * Open a stored notebook, when this host can. Undefined where nothing has registered
+     * a way to open one — today that is native JupyterLab, which has no spec store drive
+     * until OCE-182. The list then reads rather than offering an action that does nothing.
+     */
+    onOpen?: (item: ISpecSummary) => void;
+}
+/**
+ * The notebooks this user has stored on Oceanum.io, theirs and those shared with them.
+ */
+export declare function StoredNotebooks({ auth, onOpen }: IStoredNotebooksProps): React.ReactElement;

package/lib/StoredNotebooks.js

@@ -0,0 +1,84 @@
+import * as React from 'react';
+import { listNotebooks, partitionNotebooks } from './specStore';
+function Section({ title, items, empty, onOpen }) {
+    return (React.createElement("div", { className: "oceanum-notebooks-section" },
+        React.createElement("div", { className: "oceanum-notebooks-heading" },
+            title,
+            React.createElement("span", { className: "oceanum-notebooks-count" }, items.length)),
+        items.length === 0 ? (React.createElement("div", { className: "oceanum-text-empty" }, empty)) : (React.createElement("ul", { className: "oceanum-notebooks-list" }, items.map(item => {
+            var _a, _b;
+            return (React.createElement("li", { key: item.id }, onOpen ? (React.createElement("button", { type: "button", className: "oceanum-notebooks-item", onClick: () => onOpen(item), title: (_a = item.description) !== null && _a !== void 0 ? _a : undefined },
+                React.createElement("span", { className: "oceanum-notebooks-name" }, item.name || 'Untitled'))) : (React.createElement("div", { className: "oceanum-notebooks-item oceanum-notebooks-item-static", title: (_b = item.description) !== null && _b !== void 0 ? _b : undefined },
+                React.createElement("span", { className: "oceanum-notebooks-name" }, item.name || 'Untitled')))));
+        })))));
+}
+/**
+ * The notebooks this user has stored on Oceanum.io, theirs and those shared with them.
+ */
+export function StoredNotebooks({ auth, onOpen }) {
+    const [load, setLoad] = React.useState({ state: 'loading' });
+    const [user, setUser] = React.useState(auth.user);
+    // Reload whenever the signed-in user changes, so signing in or out does not leave a
+    // stale list from the previous session on screen.
+    React.useEffect(() => {
+        const onUser = () => setUser(auth.user);
+        auth.userChanged.connect(onUser);
+        return () => {
+            auth.userChanged.disconnect(onUser);
+        };
+    }, [auth]);
+    React.useEffect(() => {
+        var _a, _b;
+        let cancelled = false;
+        const specs = (_b = (_a = auth.urls) === null || _a === void 0 ? void 0 : _a.specs) !== null && _b !== void 0 ? _b : null;
+        if (!user || !specs) {
+            setLoad({ state: 'ready', items: [] });
+            return;
+        }
+        setLoad({ state: 'loading' });
+        void (async () => {
+            try {
+                const token = await auth.getAccessToken();
+                if (cancelled) {
+                    return;
+                }
+                if (!token) {
+                    setLoad({ state: 'ready', items: [] });
+                    return;
+                }
+                const items = await listNotebooks(specs, token);
+                if (!cancelled) {
+                    setLoad({ state: 'ready', items });
+                }
+            }
+            catch (error) {
+                if (!cancelled) {
+                    setLoad({
+                        state: 'error',
+                        message: error instanceof Error
+                            ? error.message
+                            : 'Could not reach Oceanum.io.'
+                    });
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [auth, user]);
+    if (!user) {
+        return (React.createElement("div", { className: "oceanum-text-empty" }, "Sign in to Oceanum.io to see your notebooks."));
+    }
+    if (load.state === 'loading') {
+        return React.createElement("div", { className: "oceanum-text-empty" }, "Loading\u2026");
+    }
+    if (load.state === 'error') {
+        // Never render the sections alongside an error: their empty messages would claim
+        // the account has no notebooks when the load simply failed.
+        return React.createElement("div", { className: "oceanum-text-error" }, load.message);
+    }
+    const { mine, shared } = partitionNotebooks(load.items, user.email);
+    return (React.createElement("div", { className: "oceanum-notebooks" },
+        React.createElement(Section, { title: "My notebooks", items: mine, empty: "You have not saved any notebooks yet.", onOpen: onOpen }),
+        React.createElement(Section, { title: "Shared with me", items: shared, empty: "No notebooks have been shared with you.", onOpen: onOpen })));
+}

package/lib/Tabs.d.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+export interface ITab {
+    /** Stable key, also used as the restored selection value. */
+    id: string;
+    label: string;
+    render: () => React.ReactElement;
+}
+export interface ITabsProps {
+    tabs: readonly ITab[];
+    /** Selected tab id. Falls back to the first tab when it names no tab. */
+    selected: string;
+    onSelect: (id: string) => void;
+}
+/**
+ * A tab strip over a single visible pane.
+ *
+ * JupyterLab users work from the keyboard, so the strip follows the WAI-ARIA tabs
+ * pattern: one tab stop for the whole strip, arrows to move between tabs, Home and End
+ * to reach the ends.
+ *
+ * Every pane stays mounted and the inactive ones are hidden. Unmounting would be
+ * cheaper, but the AI pane holds the conversation in component state and the Datamesh
+ * pane holds a workspace subscription, so switching tabs would silently discard a chat
+ * the user is in the middle of.
+ */
+export declare function Tabs({ tabs, selected, onSelect }: ITabsProps): React.ReactElement;

package/lib/Tabs.js

@@ -0,0 +1,45 @@
+import * as React from 'react';
+/**
+ * A tab strip over a single visible pane.
+ *
+ * JupyterLab users work from the keyboard, so the strip follows the WAI-ARIA tabs
+ * pattern: one tab stop for the whole strip, arrows to move between tabs, Home and End
+ * to reach the ends.
+ *
+ * Every pane stays mounted and the inactive ones are hidden. Unmounting would be
+ * cheaper, but the AI pane holds the conversation in component state and the Datamesh
+ * pane holds a workspace subscription, so switching tabs would silently discard a chat
+ * the user is in the middle of.
+ */
+export function Tabs({ tabs, selected, onSelect }) {
+    const index = Math.max(0, tabs.findIndex(tab => tab.id === selected));
+    const active = tabs[index];
+    const onKeyDown = (event) => {
+        const last = tabs.length - 1;
+        let next = null;
+        if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+            next = index === last ? 0 : index + 1;
+        }
+        else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+            next = index === 0 ? last : index - 1;
+        }
+        else if (event.key === 'Home') {
+            next = 0;
+        }
+        else if (event.key === 'End') {
+            next = last;
+        }
+        if (next === null) {
+            return;
+        }
+        // Otherwise the arrow keys also scroll the panel.
+        event.preventDefault();
+        onSelect(tabs[next].id);
+    };
+    return (React.createElement("div", { className: "oceanum-tabs" },
+        React.createElement("div", { className: "oceanum-tabs-strip", role: "tablist", "aria-label": "Oceanum.io" }, tabs.map((tab, i) => (React.createElement("button", { key: tab.id, id: `oceanum-tab-${tab.id}`, className: i === index ? 'oceanum-tab oceanum-tab-selected' : 'oceanum-tab', role: "tab", type: "button", "aria-selected": i === index, "aria-controls": `oceanum-tabpanel-${tab.id}`, 
+            // Only the selected tab is in the tab order, so Tab moves past the strip
+            // rather than through every tab in it.
+            tabIndex: i === index ? 0 : -1, onClick: () => onSelect(tab.id), onKeyDown: onKeyDown }, tab.label)))),
+        tabs.map(tab => (React.createElement("div", { key: tab.id, className: "oceanum-tabpanel", id: `oceanum-tabpanel-${tab.id}`, role: "tabpanel", "aria-labelledby": `oceanum-tab-${tab.id}`, hidden: tab.id !== active.id }, tab.render())))));
+}

package/lib/aiBackend.d.ts

@@ -35,7 +35,7 @@ export interface IAiCredential {
     headers: Record<string, string>;
 }
 /**
- * The backend address for an `aiBackendUrl` setting value, without a trailing
+ * The backend address for a configured value, without a trailing
  * slash so a path can be appended. An invalid value falls back to the default.
  */
 export declare function aiBackendUrl(value: string | null | undefined): string;

package/lib/aiBackend.js

@@ -14,7 +14,7 @@ export const SIGN_IN_COMMAND = 'oceanum-auth:sign-in';
 /** The host's command that signs out. Visible only while signed in. */
 export const SIGN_OUT_COMMAND = 'oceanum-auth:sign-out';
 /**
- * The backend address for an `aiBackendUrl` setting value, without a trailing
+ * The backend address for a configured value, without a trailing
  * slash so a path can be appended. An invalid value falls back to the default.
  */
 export function aiBackendUrl(value) {

package/lib/auth/accountWidget.d.ts

@@ -0,0 +1,35 @@
+import { CommandRegistry } from '@lumino/commands';
+import { Widget } from '@lumino/widgets';
+import { IPendingSignIn, ServerAuth } from './serverAuth';
+export declare const CommandIDs: {
+    readonly signIn: "oceanum-auth:sign-in";
+    readonly signOut: "oceanum-auth:sign-out";
+    readonly account: "oceanum-auth:account";
+    /**
+     * For other parts of oceanumlab and other extensions, such as the AI chat: resolves to
+     * the current access token, or `null` when signed out. Never rejects.
+     */
+    readonly accessToken: "oceanum-auth:access-token";
+};
+/**
+ * The top-bar account control: "Sign in" when signed out, the user's email with a sign-out
+ * menu when signed in.
+ */
+export declare class AccountWidget extends Widget {
+    constructor(auth: ServerAuth, commands: CommandRegistry);
+    dispose(): void;
+    private _onClick;
+    private _render;
+    private _auth;
+    private _commands;
+    private _menu;
+}
+/**
+ * What the sign-in dialog shows: the code to confirm, and a link to the page that confirms
+ * it. A real link rather than `window.open`, which a popup blocker stops once there has
+ * been an `await` between the click and the call -- and there always has, because the code
+ * comes from the server.
+ */
+export declare class SignInBody extends Widget {
+    constructor(pending: IPendingSignIn);
+}