@oceanum/oceanumlab 4.7.1 → 4.8.0

package/lib/DatameshWidget.d.ts

@@ -57,6 +57,17 @@ export interface IDatameshWidgetProps {
     auth?: IOceanumAuth | null;
     /** Open a stored notebook by spec store id. */
     openStoredNotebook?: (id: string) => void;
+    /** Open a copy of an example by spec store id, named from its title. */
+    openExample?: (id: string, title: string) => void;
+    /** Upload a notebook from the user's computer. */
+    uploadNotebook?: () => void;
+    /**
+     * The `showExamples` setting: whether the Notebooks tab lists the examples; null
+     * until the settings have loaded.
+     */
+    showExamples?: () => boolean | null;
+    /** Save the `showExamples` setting, from the switch on the Examples heading. */
+    setShowExamples?: (show: boolean) => void;
 }
 /**
  * A widget for Datamesh Connections.

package/lib/DatameshWidget.js

@@ -9,9 +9,10 @@ import { Signal } from '@lumino/signaling';
 import React from 'react';
 import { marked } from 'marked';
 import { DatasourceItem } from './DatasourceItem';
+import { startSignIn } from './auth/startSignIn';
 import { StoredNotebooks } from './StoredNotebooks';
 import { Tabs } from './Tabs';
-import { SIGN_IN_COMMAND, aiBackendUrl, aiCredentialSource, canSignIn, pastedToken, resolveAiCredential, signInToken } from './aiBackend';
+import { SIGN_IN_COMMAND, aiBackendUrl, aiCredentialSource, canSignIn, isSignedIn, pastedToken, resolveAiCredential, signInToken } from './aiBackend';
 import { isDatameshUiMessage } from './datameshUiUrl';
 import { describeProgress, onProgress } from './progress';
 // Configure marked for safe rendering
@@ -292,6 +293,7 @@ function readAiAccess(commands, settings) {
         source: aiCredentialSource(datameshToken, commands),
         pasted: pastedToken(datameshToken),
         canSignIn: canSignIn(commands),
+        signedIn: isSignedIn(commands),
         backend: aiBackendUrl(settings.aiBackendUrl())
     };
 }
@@ -322,6 +324,26 @@ function useAiAccess(commands, settings) {
     }, [commands, settings]);
     return access;
 }
+/**
+ * The `showExamples` setting, read again whenever the settings change. True where the
+ * host passes no such setting; null while the host's setting has not loaded.
+ */
+function useShowExamples(settingsChanged, read) {
+    const [show, setShow] = React.useState(() => read ? read() : true);
+    React.useEffect(() => {
+        if (!read) {
+            return;
+        }
+        const update = () => setShow(read());
+        // Anything that changed between the first render and now.
+        update();
+        settingsChanged.connect(update);
+        return () => {
+            settingsChanged.disconnect(update);
+        };
+    }, [settingsChanged, read]);
+    return show;
+}
 /**
  * Shows a message prompting the user to sign in to Oceanum.io, or to configure
  * their Datamesh token where the site has no sign-in. Only renders when there
@@ -609,8 +631,9 @@ function AIChatPanel({ commands, settings }) {
  * 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 }) {
+function PanelTabs({ auth, commands, settings, renderDatamesh, openStoredNotebook, openExample, uploadNotebook, showExamples, setShowExamples, selected, onSelect }) {
     const access = useAiAccess(commands, settings);
+    const examplesShown = useShowExamples(settings.settingsChanged, showExamples);
     const tabs = [
         {
             id: 'notebooks',
@@ -618,11 +641,18 @@ function PanelTabs({ auth, commands, settings, renderDatamesh, selected, onSelec
             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."))
+            (auth === null || auth === void 0 ? void 0 : auth.environment) ? (React.createElement(StoredNotebooks, { auth: auth, onOpen: openStoredNotebook && (item => openStoredNotebook(item.id)), onOpenExample: openExample && (item => openExample(item.id, item.title)), onUpload: uploadNotebook, showExamples: examplesShown, onShowExamplesChange: setShowExamples, onSignIn: () => {
+                    startSignIn(commands, auth).catch(error => {
+                        console.warn('Oceanum.io sign-in could not start.', error);
+                    });
+                } })) : (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) {
+    // Signed in, not merely holding a credential: a Datamesh token pasted into the
+    // settings would reach the backend, but the tab stays out of the way until someone
+    // has signed in to Oceanum.io.
+    if (access.signedIn) {
         tabs.push({
             id: 'ai',
             label: 'Oceanum AI',
@@ -684,7 +714,7 @@ export class DatameshConnectWidget extends ReactWidget {
                 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) }));
+                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(), openStoredNotebook: this.props.openStoredNotebook, openExample: this.props.openExample, uploadNotebook: this.props.uploadNotebook, showExamples: this.props.showExamples, setShowExamples: this.props.setShowExamples, selected: this.selectedTab, onSelect: id => this.selectTab(id) }));
             })));
     }
     /**

package/lib/StoredNotebooks.d.ts

@@ -1,16 +1,38 @@
 import * as React from 'react';
 import { IOceanumAuth } from './auth/tokens';
-import { ISpecSummary } from './specStore';
+import { INotebookDemoItem, ISpecSummary } from './share/notebook';
+/** Example rows carry their record id here, not in SPEC_ID_ATTRIBUTE: see Examples. */
+export declare const EXAMPLE_ID_ATTRIBUTE = "data-example-id";
 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.
+     * Open a stored notebook. Undefined where nothing has registered a way to open one;
+     * the list then reads rather than offering a click that does nothing.
      */
     onOpen?: (item: ISpecSummary) => void;
+    /** Open a copy of an example, as `onOpen` does for a stored notebook. */
+    onOpenExample?: (item: INotebookDemoItem) => void;
+    /** Upload a notebook from the user's computer; no Upload button without it. */
+    onUpload?: () => void;
+    /**
+     * Whether the examples are listed, or folded under their heading. Default true. Null
+     * while the setting is still loading: the Examples wait for it, so examples a user
+     * has hidden never show for a moment first.
+     */
+    showExamples?: boolean | null;
+    /**
+     * Record the user's choice to show or hide the examples. The Examples heading offers
+     * its switch only where this is given: a switch that could not keep its setting
+     * would flip back on the next load.
+     */
+    onShowExamplesChange?: (show: boolean) => void;
+    /**
+     * Start signing in the way this host shows it; without it the auth's own `signIn()`
+     * is used, which on a JupyterLab server shows no code dialog.
+     */
+    onSignIn?: () => 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;
+export declare function StoredNotebooks({ auth, onOpen, onOpenExample, onUpload, showExamples, onShowExamplesChange, onSignIn }: IStoredNotebooksProps): React.ReactElement;

package/lib/StoredNotebooks.js

@@ -1,30 +1,120 @@
 import * as React from 'react';
-import { listNotebooks, partitionNotebooks } from './specStore';
+import { SpecStoreClient } from './share/client';
+import { notebooksChanged } from './share/events';
+import { parseNotebookDemo, partitionSummaries } from './share/notebook';
+import { SPEC_ID_ATTRIBUTE } from './share/plugin';
+/** Example rows carry their record id here, not in SPEC_ID_ATTRIBUTE: see Examples. */
+export const EXAMPLE_ID_ATTRIBUTE = 'data-example-id';
+/**
+ * Read the Notebook Demo record, if the deployment names one. Never rejects: a failure
+ * here is shown in the Examples section and leaves the rest of the tab alone.
+ */
+async function loadExamples(auth, specsUrl, id) {
+    if (!id) {
+        return { state: 'none' };
+    }
+    try {
+        const client = new SpecStoreClient({
+            specsUrl,
+            getAccessToken: () => auth.getAccessToken(),
+            specType: 'notebook-demo'
+        });
+        const record = await client.get(id);
+        return { state: 'ready', sections: parseNotebookDemo(record.spec) };
+    }
+    catch (error) {
+        return {
+            state: 'error',
+            message: error instanceof Error ? error.message : 'Could not reach Oceanum.io.'
+        };
+    }
+}
+/**
+ * The curated examples. Their rows deliberately leave out SPEC_ID_ATTRIBUTE and the
+ * stored-notebook row class: the share plugin's row menu (Open, Rename, Share, Delete)
+ * is bound to those, and none of it applies to Oceanum's own example records.
+ */
+function ExampleSections({ examples, onOpen, show, onShowChange }) {
+    // Not yet known, or hidden with no switch to bring them back: nothing to show.
+    if (examples.state === 'none' || show === null || (!show && !onShowChange)) {
+        return null;
+    }
+    const count = examples.state === 'ready'
+        ? examples.sections.reduce((total, section) => total + section.items.length, 0)
+        : null;
+    if (count === 0) {
+        return null;
+    }
+    const heading = (React.createElement("div", { className: "oceanum-notebooks-heading" },
+        "Examples",
+        React.createElement("span", { className: "oceanum-notebooks-heading-end" },
+            count !== null && (React.createElement("span", { className: "oceanum-notebooks-count" }, count)),
+            onShowChange && (React.createElement("button", { type: "button", role: "switch", "aria-checked": show, "aria-label": "Show examples", title: "Show examples", className: "oceanum-notebooks-switch", onClick: () => onShowChange(!show) },
+                React.createElement("span", { className: "oceanum-notebooks-switch-thumb" }))))));
+    // Hidden: the heading stays, so the switch is there to bring them back.
+    if (!show) {
+        return React.createElement("div", { className: "oceanum-notebooks-section" }, heading);
+    }
+    if (examples.state === 'error') {
+        return (React.createElement("div", { className: "oceanum-notebooks-section" },
+            heading,
+            React.createElement("div", { className: "oceanum-text-error" },
+                "The examples could not be loaded. ",
+                examples.message)));
+    }
+    return (React.createElement("div", { className: "oceanum-notebooks-section" },
+        heading,
+        examples.sections.map((section, index) => (React.createElement("div", { key: index },
+            React.createElement("div", { className: "oceanum-notebooks-subheading" }, section.title),
+            React.createElement("ul", { className: "oceanum-notebooks-list" }, section.items.map((item, position) => {
+                const attributes = {
+                    [EXAMPLE_ID_ATTRIBUTE]: item.id,
+                    title: item.summary
+                };
+                const name = (React.createElement("span", { className: "oceanum-notebooks-name" }, item.title));
+                return (
+                // A record may list the same example twice; the id alone is no key.
+                React.createElement("li", { key: `${position}:${item.id}` }, onOpen ? (React.createElement("button", { type: "button", className: "oceanum-notebooks-example", onClick: () => onOpen(item), ...attributes }, name)) : (React.createElement("div", { className: "oceanum-notebooks-example oceanum-notebooks-item-static", ...attributes }, name))));
+            })))))));
+}
 function Section({ title, items, empty, onOpen }) {
+    // Each row carries its record id so the share plugin's context menu (Open, Rename,
+    // Share, Delete) can tell which one was clicked.
+    const rowAttributes = (item) => {
+        var _a;
+        return ({
+            [SPEC_ID_ATTRIBUTE]: item.id,
+            title: (_a = item.description) !== null && _a !== void 0 ? _a : undefined
+        });
+    };
     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')))));
-        })))));
+        items.length === 0 ? (React.createElement("div", { className: "oceanum-text-empty" }, empty)) : (React.createElement("ul", { className: "oceanum-notebooks-list" }, items.map(item => (React.createElement("li", { key: item.id }, onOpen ? (React.createElement("button", { type: "button", className: "oceanum-notebooks-item", onClick: () => onOpen(item), ...rowAttributes(item) },
+            React.createElement("span", { className: "oceanum-notebooks-name" }, item.name || 'Untitled'))) : (React.createElement("div", { className: "oceanum-notebooks-item oceanum-notebooks-item-static", ...rowAttributes(item) },
+            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 }) {
+export function StoredNotebooks({ auth, onOpen, onOpenExample, onUpload, showExamples = true, onShowExamplesChange, onSignIn }) {
+    var _a;
     const [load, setLoad] = React.useState({ state: 'loading' });
     const [user, setUser] = React.useState(auth.user);
+    // Bumped whenever the store changes, so the list is fetched again.
+    const [version, setVersion] = React.useState(0);
     // Reload whenever the signed-in user changes, so signing in or out does not leave a
-    // stale list from the previous session on screen.
+    // stale list from the previous session on screen; and whenever this extension has
+    // created, renamed or deleted a record.
     React.useEffect(() => {
         const onUser = () => setUser(auth.user);
+        const onChanged = () => setVersion(v => v + 1);
         auth.userChanged.connect(onUser);
+        notebooksChanged.connect(onChanged);
         return () => {
             auth.userChanged.disconnect(onUser);
+            notebooksChanged.disconnect(onChanged);
         };
     }, [auth]);
     React.useEffect(() => {
@@ -32,23 +122,25 @@ export function StoredNotebooks({ auth, onOpen }) {
         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: [] });
+            setLoad({ state: 'ready', items: [], examples: { state: 'none' } });
             return;
         }
         setLoad({ state: 'loading' });
         void (async () => {
+            var _a, _b;
             try {
-                const token = await auth.getAccessToken();
-                if (cancelled) {
-                    return;
-                }
-                if (!token) {
-                    setLoad({ state: 'ready', items: [] });
-                    return;
-                }
-                const items = await listNotebooks(specs, token);
+                const client = new SpecStoreClient({
+                    specsUrl: specs,
+                    getAccessToken: () => auth.getAccessToken()
+                });
+                // Only the record the deployment names: every signed-in user can create
+                // notebook-demo records, so the examples never come from a listing.
+                const [items, examples] = await Promise.all([
+                    client.list(),
+                    loadExamples(auth, specs, (_b = (_a = auth.environment) === null || _a === void 0 ? void 0 : _a.notebookDemo) !== null && _b !== void 0 ? _b : null)
+                ]);
                 if (!cancelled) {
-                    setLoad({ state: 'ready', items });
+                    setLoad({ state: 'ready', items, examples });
                 }
             }
             catch (error) {
@@ -65,9 +157,26 @@ export function StoredNotebooks({ auth, onOpen }) {
         return () => {
             cancelled = true;
         };
-    }, [auth, user]);
+    }, [auth, user, version]);
     if (!user) {
-        return (React.createElement("div", { className: "oceanum-text-empty" }, "Sign in to Oceanum.io to see your notebooks."));
+        const signIn = () => {
+            if (onSignIn) {
+                onSignIn();
+                return;
+            }
+            auth.signIn().catch(error => {
+                console.warn('Oceanum.io sign-in could not start.', error);
+            });
+        };
+        return (React.createElement("div", { className: "oceanum-text-empty" },
+            React.createElement("a", { role: "button", tabIndex: 0, onClick: signIn, onKeyDown: event => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                        event.preventDefault();
+                        signIn();
+                    }
+                } }, "Sign in"),
+            ' ',
+            "to Oceanum.io to see your notebooks."));
     }
     if (load.state === 'loading') {
         return React.createElement("div", { className: "oceanum-text-empty" }, "Loading\u2026");
@@ -77,8 +186,16 @@ export function StoredNotebooks({ auth, onOpen }) {
         // 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);
+    const { mine, shared } = partitionSummaries(load.items, user.email);
+    // A public example is readable by everyone, so the listing returns it as shared with
+    // every signed-in user; it is shown under Examples instead.
+    const exampleIds = new Set(load.examples.state === 'ready'
+        ? load.examples.sections.flatMap(section => section.items.map(item => item.id))
+        : []);
     return (React.createElement("div", { className: "oceanum-notebooks" },
+        onUpload && ((_a = auth.urls) === null || _a === void 0 ? void 0 : _a.specs) ? (React.createElement("div", { className: "oceanum-notebooks-actions" },
+            React.createElement("button", { type: "button", className: "oceanum-notebooks-upload", title: "Upload a notebook from this computer, to save on Oceanum.io", onClick: onUpload }, "Upload notebook\u2026"))) : null,
         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 })));
+        React.createElement(Section, { title: "Shared with me", items: shared.filter(item => !exampleIds.has(item.id)), empty: "No notebooks have been shared with you.", onOpen: onOpen }),
+        React.createElement(ExampleSections, { examples: load.examples, onOpen: onOpenExample, show: showExamples, onShowChange: onShowExamplesChange })));
 }

package/lib/auth/serverAuth.js

@@ -81,6 +81,7 @@ export function readServerAuthOption(option, hostname) {
         clientId: config.clientId,
         oceanumDomain: typeof config.oceanumDomain === 'string' ? config.oceanumDomain : '',
         signInRedirect: false,
+        fileManagement: config.fileManagement === 'oceanum' ? 'oceanum' : 'local',
         urls
     };
 }

package/lib/auth/startSignIn.d.ts

@@ -0,0 +1,11 @@
+import type { CommandRegistry } from '@lumino/commands';
+import type { IOceanumAuth } from './tokens';
+/**
+ * Start signing in the way this host shows it.
+ *
+ * On a JupyterLab server the device sign-in command both starts the flow and shows the
+ * code dialog; `auth.signIn()` alone starts the flow and shows nothing, so the user is
+ * left with a "Signing in…" top bar and no code. notebook.oceanum.io disables that
+ * command and provides an auth whose `signIn()` opens the Oceanum sign-in itself.
+ */
+export declare function startSignIn(commands: CommandRegistry, auth: IOceanumAuth): Promise<void>;

package/lib/auth/startSignIn.js

@@ -0,0 +1,16 @@
+import { CommandIDs } from './accountWidget';
+/**
+ * Start signing in the way this host shows it.
+ *
+ * On a JupyterLab server the device sign-in command both starts the flow and shows the
+ * code dialog; `auth.signIn()` alone starts the flow and shows nothing, so the user is
+ * left with a "Signing in…" top bar and no code. notebook.oceanum.io disables that
+ * command and provides an auth whose `signIn()` opens the Oceanum sign-in itself.
+ */
+export async function startSignIn(commands, auth) {
+    if (commands.hasCommand(CommandIDs.signIn)) {
+        await commands.execute(CommandIDs.signIn);
+        return;
+    }
+    await auth.signIn();
+}

package/lib/auth/tokens.d.ts

@@ -24,6 +24,19 @@ export interface IOceanumEnvironment {
      * the site origin is an allowed callback URL.
      */
     readonly signInRedirect: boolean;
+    /**
+     * Whether Oceanum.io is the only file management this host shows, as on
+     * notebook.oceanum.io: the file browser and the File menu's local-file entries go,
+     * and every local save is pushed to the spec store. `'local'` (the default when
+     * absent) keeps JupyterLab's file management alongside the Oceanum commands.
+     */
+    readonly fileManagement?: 'local' | 'oceanum';
+    /**
+     * The spec store id of this deployment's Notebook Demo record, the curated list the
+     * Notebooks tab shows as Examples. Absent where a deployment has none, and never set
+     * by a JupyterLab server's sign-in.
+     */
+    readonly notebookDemo?: string;
 }
 /** Service base URLs for an environment, without trailing slashes. */
 export interface IOceanumServiceUrls {

package/lib/index.d.ts

@@ -19,5 +19,5 @@ export declare const oceanum_ai_extension: JupyterFrontEndPlugin<void>;
  * JupyterLab shares `@oceanum/oceanumlab` between extensions as a singleton module.
  */
 export * from './auth/tokens';
-declare const _default: (JupyterFrontEndPlugin<IOceanumAuth> | JupyterFrontEndPlugin<void>)[];
+declare const _default: (JupyterFrontEndPlugin<void> | JupyterFrontEndPlugin<IOceanumAuth>)[];
 export default _default;

package/lib/index.js

@@ -14,6 +14,8 @@ import { reporterFor } from './progress';
 import { ConversationPin } from './conversationPin';
 import { deviceAuthPlugin } from './auth/plugin';
 import { IOceanumAuth } from './auth/tokens';
+import { CommandIDs as ShareCommandIDs, sharePlugin } from './share/plugin';
+import { OCEANUM_PANEL_ID } from './share/oceanumOnly';
 import { snapshotFromIpynb, snapshotOf } from './notebookContext';
 import { notebookHost } from './notebookHost';
 import { KernelHandoff } from './kernelHandoff';
@@ -54,6 +56,9 @@ export const datamesh_connect_extension = {
         const aiBackendUrl = (_d = (_c = auth === null || auth === void 0 ? void 0 : auth.urls) === null || _c === void 0 ? void 0 : _c.ai) !== null && _d !== void 0 ? _d : OCEANUM_AI_BACKEND_URL;
         // The `datameshToken` setting for the AI chat; empty until the settings load.
         let datameshTokenSetting = '';
+        // The `showExamples` setting for the Notebooks tab; null until the settings load, so
+        // examples a user has hidden do not show for a moment on every reload.
+        let showExamplesSetting = null;
         // Tells the sidebar the settings above have changed.
         const settingsChanged = new Signal(app);
         const findDatameshUI = () => find(app.shell.widgets('main'), (widget) => widget.id === 'datamesh-ui');
@@ -69,6 +74,7 @@ export const datamesh_connect_extension = {
             }
             window.injectToken = set.get('injectToken').user;
             datameshTokenSetting = set.get('datameshToken').composite;
+            showExamplesSetting = set.get('showExamples').composite;
             settingsChanged.emit();
         };
         //Try to get the datamesh token from the envars
@@ -81,6 +87,10 @@ export const datamesh_connect_extension = {
         })
             .catch(reason => {
             console.error(`Something went wrong when reading the Oceanumlab settings.\n${reason}`);
+            // Unreadable settings fall back to the default rather than leaving the examples
+            // waiting for a value that will never come.
+            showExamplesSetting = true;
+            settingsChanged.emit();
         });
         const getCurrentWidget = () => {
             return app.shell.currentWidget;
@@ -111,14 +121,39 @@ export const datamesh_connect_extension = {
             settingsChanged,
             commands: app.commands,
             getCurrentWidget,
-            auth
-            // No `openStoredNotebook`: nothing can open a spec store record by id yet.
-            // share-oceanum has `oceanum-share:open`, but it takes no arguments — it opens
-            // its own picker — so there is nothing to hand an id to. Opening arrives with
-            // the drive in OCE-182, where the contents API makes it the ordinary path.
-            // Until then the list reads rather than offering a click that does nothing.
+            auth,
+            openStoredNotebook: id => {
+                app.commands.execute(ShareCommandIDs.open, { id }).catch(error => {
+                    console.error('Oceanum: could not open the stored notebook.', error);
+                });
+            },
+            openExample: (id, title) => {
+                app.commands
+                    .execute(ShareCommandIDs.openExample, { id, title })
+                    .catch(error => {
+                    console.error('Oceanum: could not open the example.', error);
+                });
+            },
+            uploadNotebook: () => {
+                app.commands.execute(ShareCommandIDs.upload).catch(error => {
+                    console.error('Oceanum: could not upload the notebook.', error);
+                });
+            },
+            showExamples: () => showExamplesSetting,
+            // Saved as a user setting, so the choice outlasts the page; the settings'
+            // `changed` signal brings the new value back to the panel. The registry waits
+            // for the plugin's settings to load, so a click before then is not lost.
+            setShowExamples: show => {
+                settingRegistry.set(PLUGIN_ID, 'showExamples', show).catch(error => {
+                    // The switch moves only once the setting is saved, so say why it did not.
+                    console.error('Oceanum: could not save the Examples setting.', error);
+                    Notification.error('Could not save whether to show the examples.', {
+                        autoClose: 5000
+                    });
+                });
+            }
         });
-        datameshConnectWidget.id = 'datamesh-connect';
+        datameshConnectWidget.id = OCEANUM_PANEL_ID;
         datameshConnectWidget.title.icon = oceanumIcon;
         datameshConnectWidget.title.caption = 'Datamesh Connect';
         restorer.add(datameshConnectWidget, 'datamesh-connect');
@@ -327,6 +362,7 @@ export const oceanum_ai_extension = {
 export * from './auth/tokens';
 export default [
     deviceAuthPlugin,
+    sharePlugin,
     datamesh_connect_extension,
     oceanum_ai_extension
 ];

package/lib/share/client.d.ts

@@ -0,0 +1,86 @@
+import { ISpecBody, ISpecPatch, ISpecRecord, ISpecSummary } from './notebook';
+export type ErrorKind = 'signed-out' | 'expired' | 'forbidden' | 'not-found' | 'too-large' | 'network' | 'invalid' | 'unsupported' | 'server';
+/** A spec store failure with a message that is safe to show to the user. */
+export declare class SpecStoreError extends Error {
+    readonly kind: ErrorKind;
+    readonly status: number | null;
+    constructor(kind: ErrorKind, status?: number | null);
+}
+/** Map a failed HTTP status to an error. */
+export declare function errorForStatus(status: number): SpecStoreError;
+export type SharePermission = 'read' | 'write';
+/** A permission grant, as accepted by `POST /specs/notebook/{id}/permissions`. */
+export type PermissionGrant = {
+    type: 'user';
+    entity: string;
+    permission: SharePermission;
+} | {
+    type: 'public';
+    entity: '';
+    permission: 'read';
+};
+/**
+ * What the share dialog asks for: add grants, or remove one (e.g. stop public access).
+ *
+ * Granting carries a list because the dialog shares with several people at once, while
+ * the spec store takes one grant per request. `invalid` carries back anything typed that
+ * is not a shareable address, so the caller can name it rather than failing with
+ * "invalid email".
+ */
+export type ShareChoice = {
+    action: 'grant';
+    grants: PermissionGrant[];
+    invalid: string[];
+} | {
+    action: 'revoke';
+    grant: PermissionGrant;
+};
+export interface ISpecStoreClientOptions {
+    /** Spec store base URL, e.g. `https://specs.oceanum.io`. */
+    specsUrl: string;
+    /** Returns a current access token or `null`. Called for every request. */
+    getAccessToken: () => Promise<string | null>;
+    /** The spec type the client reads and writes; `notebook` unless given. */
+    specType?: string;
+    fetch?: typeof fetch;
+}
+/** Client for one spec type of the Oceanum spec store, `notebook` by default. */
+export declare class SpecStoreClient {
+    constructor(options: ISpecStoreClientOptions);
+    /** Every notebook the user may read, including public ones. */
+    list(): Promise<ISpecSummary[]>;
+    /** Read a record, anonymously when signed out. */
+    get(id: string): Promise<ISpecRecord>;
+    /** Create a record. The server mints the id: use the returned record's. */
+    create(body: ISpecBody): Promise<ISpecRecord>;
+    /** Replace a record's name, description and notebook. */
+    update(id: string, body: ISpecBody): Promise<ISpecRecord>;
+    /**
+     * Change some of a record's fields and leave the rest as they are. Needs the same
+     * write access as `update`, which the store enforces a patch as.
+     */
+    patch(id: string, changes: ISpecPatch): Promise<ISpecRecord>;
+    /**
+     * Give a record a new name, without sending the notebook back with it.
+     *
+     * Falls back to reading the record and putting it back where the store has no PATCH
+     * (production had none when this was written). That fallback races another writer's
+     * change to the notebook, which is the whole reason to prefer a patch.
+     */
+    rename(id: string, name: string): Promise<ISpecRecord>;
+    /** Delete a record (requires admin access to it). */
+    remove(id: string): Promise<void>;
+    /** Grant a permission on a record (requires admin access to it). */
+    addPermission(id: string, grant: PermissionGrant): Promise<void>;
+    /**
+     * Remove a permission (requires admin access). The server matches the exact grant and
+     * answers 404 when there is no such permission.
+     */
+    removePermission(id: string, grant: PermissionGrant): Promise<void>;
+    private _url;
+    private _record;
+    private _request;
+    private readonly _base;
+    private readonly _getAccessToken;
+    private readonly _fetch;
+}