@oceanum/oceanumlab 4.7.2 → 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

@@ -324,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
@@ -611,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, openStoredNotebook, 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',
@@ -620,7 +641,7 @@ function PanelTabs({ auth, commands, settings, renderDatamesh, openStoredNoteboo
             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, onOpen: openStoredNotebook && (item => openStoredNotebook(item.id)), onSignIn: () => {
+            (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);
                     });
@@ -693,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(), openStoredNotebook: this.props.openStoredNotebook, 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,6 +1,8 @@
 import * as React from 'react';
 import { IOceanumAuth } from './auth/tokens';
-import { ISpecSummary } from './share/notebook';
+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;
     /**
@@ -8,6 +10,22 @@ export interface IStoredNotebooksProps {
      * 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.
@@ -17,4 +35,4 @@ export interface IStoredNotebooksProps {
 /**
  * The notebooks this user has stored on Oceanum.io, theirs and those shared with them.
  */
-export declare function StoredNotebooks({ auth, onOpen, onSignIn }: IStoredNotebooksProps): React.ReactElement;
+export declare function StoredNotebooks({ auth, onOpen, onOpenExample, onUpload, showExamples, onShowExamplesChange, onSignIn }: IStoredNotebooksProps): React.ReactElement;

package/lib/StoredNotebooks.js

@@ -1,8 +1,82 @@
 import * as React from 'react';
 import { SpecStoreClient } from './share/client';
 import { notebooksChanged } from './share/events';
-import { partitionSummaries } from './share/notebook';
+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.
@@ -24,7 +98,8 @@ function Section({ title, items, empty, onOpen }) {
 /**
  * The notebooks this user has stored on Oceanum.io, theirs and those shared with them.
  */
-export function StoredNotebooks({ auth, onOpen, onSignIn }) {
+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.
@@ -47,19 +122,25 @@ export function StoredNotebooks({ auth, onOpen, onSignIn }) {
         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 client = new SpecStoreClient({
                     specsUrl: specs,
                     getAccessToken: () => auth.getAccessToken()
                 });
-                const items = await client.list();
+                // 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) {
@@ -106,7 +187,15 @@ export function StoredNotebooks({ auth, onOpen, onSignIn }) {
         return React.createElement("div", { className: "oceanum-text-error" }, load.message);
     }
     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/tokens.d.ts

@@ -31,6 +31,12 @@ export interface IOceanumEnvironment {
      * 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.js

@@ -15,6 +15,7 @@ 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';
@@ -55,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');
@@ -70,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
@@ -82,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;
@@ -117,9 +126,34 @@ export const datamesh_connect_extension = {
                 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');

package/lib/share/client.d.ts

@@ -40,9 +40,11 @@ export interface ISpecStoreClientOptions {
     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 the `notebook` spec type of the Oceanum spec store. */
+/** 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. */

package/lib/share/client.js

@@ -52,13 +52,14 @@ function isSummary(value) {
 function isRecord(value) {
     return isSummary(value) && 'spec' in value;
 }
-/** Client for the `notebook` spec type of the Oceanum spec store. */
+/** Client for one spec type of the Oceanum spec store, `notebook` by default. */
 export class SpecStoreClient {
     constructor(options) {
-        var _a;
-        this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/notebook`;
+        var _a, _b;
+        const specType = (_a = options.specType) !== null && _a !== void 0 ? _a : 'notebook';
+        this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/${specType}`;
         this._getAccessToken = options.getAccessToken;
-        this._fetch = (_a = options.fetch) !== null && _a !== void 0 ? _a : ((input, init) => fetch(input, init));
+        this._fetch = (_b = options.fetch) !== null && _b !== void 0 ? _b : ((input, init) => fetch(input, init));
     }
     /** Every notebook the user may read, including public ones. */
     async list() {

package/lib/share/notebook.d.ts

@@ -93,11 +93,24 @@ export declare function withoutTrust(content: INotebookContent): INotebookConten
  * dropped; if it is still too large, the result is not ok.
  */
 export declare function buildSpecBody(content: INotebookContent, path: string, specsUrl: string, maxBytes?: number): BuildResult;
+/**
+ * A notebook uploaded from the user's computer, untrusted and linked to nothing: a file
+ * someone else downloaded from a record must not save over that record, and its outputs
+ * must not run scripts on the origin that holds the Oceanum.io session. Throws if the
+ * text is not an nbformat 4 notebook; the message never quotes the file.
+ */
+export declare function notebookFromUpload(text: string): INotebookContent;
 /**
  * The notebook stored in a record, with its `oceanum` link set. Throws if the record
  * does not hold an nbformat 4 notebook.
  */
 export declare function notebookFromRecord(record: ISpecRecord, specsUrl: string): INotebookContent;
+/**
+ * A copy of the notebook stored in a record, linked to nothing: untrusted, and without
+ * any `oceanum` link, so saving it creates a record of the user's own instead of
+ * writing to this one. Throws if the record does not hold an nbformat 4 notebook.
+ */
+export declare function unlinkedNotebookFromRecord(record: ISpecRecord): INotebookContent;
 /** Make a record name safe to use as a single path segment. */
 export declare function sanitizeName(name: string): string;
 /**
@@ -128,6 +141,25 @@ export declare function partitionSummaries(items: readonly ISpecSummary[], email
     mine: ISpecSummary[];
     shared: ISpecSummary[];
 };
+/** The `kind` of a Notebook Demo record's spec. */
+export declare const NOTEBOOK_DEMO_KIND = "notebook-demo";
+/** One example in a Notebook Demo record: a notebook record and how to list it. */
+export interface INotebookDemoItem {
+    id: string;
+    title: string;
+    summary?: string;
+}
+/** A titled group of examples. */
+export interface INotebookDemoSection {
+    title: string;
+    items: INotebookDemoItem[];
+}
+/**
+ * The sections of a Notebook Demo record's spec, keeping only what can be listed: items
+ * with a record id and a title, in sections with a title and at least one such item.
+ * A spec of another kind or version gives no sections, with a warning.
+ */
+export declare function parseNotebookDemo(spec: unknown): INotebookDemoSection[];
 /** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
 export declare function parseTimestamp(value: string): Date | null;
 /**

package/lib/share/notebook.js

@@ -106,27 +106,65 @@ export function buildSpecBody(content, path, specsUrl, maxBytes = MAX_BODY_BYTES
     return { ok: false, bytes: strippedBytes };
 }
 /**
- * The notebook stored in a record, with its `oceanum` link set. Throws if the record
- * does not hold an nbformat 4 notebook.
+ * The notebook stored in a record, untrusted. Throws if the record does not hold an
+ * nbformat 4 notebook.
  */
-export function notebookFromRecord(record, specsUrl) {
+function recordNotebook(record) {
     const spec = record.spec;
-    if (!isObject(spec) ||
-        spec.nbformat !== 4 ||
-        !Array.isArray(spec.cells) ||
-        !isObject(spec.metadata)) {
+    if (!isNotebook(spec)) {
         throw new Error('This Oceanum.io record is not a valid notebook.');
     }
+    return withoutTrust(spec);
+}
+function isNotebook(value) {
+    return (isObject(value) &&
+        value.nbformat === 4 &&
+        Array.isArray(value.cells) &&
+        value.cells.every(cell => isObject(cell) && typeof cell.cell_type === 'string') &&
+        isObject(value.metadata));
+}
+/**
+ * A notebook uploaded from the user's computer, untrusted and linked to nothing: a file
+ * someone else downloaded from a record must not save over that record, and its outputs
+ * must not run scripts on the origin that holds the Oceanum.io session. Throws if the
+ * text is not an nbformat 4 notebook; the message never quotes the file.
+ */
+export function notebookFromUpload(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (_a) {
+        throw new Error('The file is not a Jupyter notebook: it is not JSON.');
+    }
+    if (!isNotebook(parsed)) {
+        throw new Error('The file is not a Jupyter notebook in nbformat 4.');
+    }
+    return withoutLink(withoutTrust(parsed));
+}
+/**
+ * The notebook stored in a record, with its `oceanum` link set. Throws if the record
+ * does not hold an nbformat 4 notebook.
+ */
+export function notebookFromRecord(record, specsUrl) {
     const link = { spec_id: record.id, specs_url: specsUrl };
     if (record.description) {
         link.description = record.description;
     }
-    const content = withoutTrust(spec);
+    const content = recordNotebook(record);
     return {
         ...content,
         metadata: { ...content.metadata, [METADATA_KEY]: { ...link } }
     };
 }
+/**
+ * A copy of the notebook stored in a record, linked to nothing: untrusted, and without
+ * any `oceanum` link, so saving it creates a record of the user's own instead of
+ * writing to this one. Throws if the record does not hold an nbformat 4 notebook.
+ */
+export function unlinkedNotebookFromRecord(record) {
+    return withoutLink(recordNotebook(record));
+}
 /** Make a record name safe to use as a single path segment. */
 export function sanitizeName(name) {
     const clean = name
@@ -199,6 +237,46 @@ export function partitionSummaries(items, email) {
         shared: sorted.filter(item => !isMine(item))
     };
 }
+/** The `kind` of a Notebook Demo record's spec. */
+export const NOTEBOOK_DEMO_KIND = 'notebook-demo';
+function nonBlank(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/**
+ * The sections of a Notebook Demo record's spec, keeping only what can be listed: items
+ * with a record id and a title, in sections with a title and at least one such item.
+ * A spec of another kind or version gives no sections, with a warning.
+ */
+export function parseNotebookDemo(spec) {
+    if (!isObject(spec) ||
+        spec.kind !== NOTEBOOK_DEMO_KIND ||
+        spec.version !== 1 ||
+        !Array.isArray(spec.sections)) {
+        console.warn('Oceanum: ignoring a Notebook Demo record this version cannot read.');
+        return [];
+    }
+    const sections = [];
+    for (const section of spec.sections) {
+        if (!isObject(section) ||
+            !nonBlank(section.title) ||
+            !Array.isArray(section.items)) {
+            continue;
+        }
+        const items = [];
+        for (const item of section.items) {
+            if (!isObject(item) || !isSpecId(item.id) || !nonBlank(item.title)) {
+                continue;
+            }
+            items.push(typeof item.summary === 'string'
+                ? { id: item.id, title: item.title, summary: item.summary }
+                : { id: item.id, title: item.title });
+        }
+        if (items.length > 0) {
+            sections.push({ title: section.title, items });
+        }
+    }
+    return sections;
+}
 /** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
 export function parseTimestamp(value) {
     const zoned = /(Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}Z`;

package/lib/share/oceanumOnly.d.ts

@@ -11,19 +11,42 @@ import type { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
 import type { Menu, Widget } from '@lumino/widgets';
 /** The widget id `@jupyterlab/filebrowser-extension:browser` gives the file browser. */
 export declare const FILE_BROWSER_ID = "filebrowser";
+/** The widget id of this extension's Oceanum.io panel, which takes the browser's place. */
+export declare const OCEANUM_PANEL_ID = "datamesh-connect";
 /**
  * File menu entries that manage local files. Save, Save All and Rename stay: saving is
  * routed to Oceanum, and renaming the local file is how a notebook gets its name.
  */
 export declare const LOCAL_FILE_COMMANDS: readonly string[];
+/**
+ * File > New entries for files that are not notebooks. The spec store holds notebooks
+ * only, so such a file could never be saved anywhere the user can see.
+ */
+export declare const NON_NOTEBOOK_NEW_COMMANDS: readonly string[];
 /**
  * Take the file browser out of the sidebar; true if it was there. It is closed, not
  * disposed: other extensions hold it through IDefaultFileBrowser and still use it to
- * open paths.
+ * open paths. If it was the open panel, `instead` is opened in its place; a sidebar the
+ * user had collapsed stays collapsed.
  */
 export declare function hideFileBrowser(shell: {
     widgets(area: 'left'): Iterable<Widget>;
-}): boolean;
+    activateById(id: string): void;
+}, instead?: string): boolean;
+/**
+ * Put a left-sidebar widget first, and keep it open if it was. True if it moved.
+ *
+ * A rank alone is not enough: the layout restorer replays the sidebar order each user
+ * last had, so a returning user would keep the panel wherever it used to be. Adding it
+ * again after the restore re-inserts it by rank, and the shell saves the new order.
+ */
+export declare function moveToTop(shell: {
+    widgets(area: 'left'): Iterable<Widget>;
+    add(widget: Widget, area: 'left', options: {
+        rank: number;
+    }): void;
+    activateById(id: string): void;
+}, id: string): boolean;
 /**
  * Submenus of local files. "Open Recent" is built by the document manager rather than
  * declared in a schema, and its menu has no id, so it is known by the commands it holds.

package/lib/share/oceanumOnly.js

@@ -1,6 +1,8 @@
 import { MessageLoop } from '@lumino/messaging';
 /** The widget id `@jupyterlab/filebrowser-extension:browser` gives the file browser. */
 export const FILE_BROWSER_ID = 'filebrowser';
+/** The widget id of this extension's Oceanum.io panel, which takes the browser's place. */
+export const OCEANUM_PANEL_ID = 'datamesh-connect';
 /**
  * File menu entries that manage local files. Save, Save All and Rename stay: saving is
  * routed to Oceanum, and renaming the local file is how a notebook gets its name.
@@ -14,20 +16,55 @@ export const LOCAL_FILE_COMMANDS = [
     'docmanager:duplicate',
     'docmanager:download'
 ];
+/**
+ * File > New entries for files that are not notebooks. The spec store holds notebooks
+ * only, so such a file could never be saved anywhere the user can see.
+ */
+export const NON_NOTEBOOK_NEW_COMMANDS = [
+    'fileeditor:create-new',
+    'fileeditor:create-new-markdown-file'
+];
 /**
  * Take the file browser out of the sidebar; true if it was there. It is closed, not
  * disposed: other extensions hold it through IDefaultFileBrowser and still use it to
- * open paths.
+ * open paths. If it was the open panel, `instead` is opened in its place; a sidebar the
+ * user had collapsed stays collapsed.
  */
-export function hideFileBrowser(shell) {
+export function hideFileBrowser(shell, instead) {
     for (const widget of shell.widgets('left')) {
         if (widget.id === FILE_BROWSER_ID) {
+            const wasOpen = widget.isVisible;
             widget.close();
+            if (wasOpen && instead) {
+                shell.activateById(instead);
+            }
             return true;
         }
     }
     return false;
 }
+/**
+ * Put a left-sidebar widget first, and keep it open if it was. True if it moved.
+ *
+ * A rank alone is not enough: the layout restorer replays the sidebar order each user
+ * last had, so a returning user would keep the panel wherever it used to be. Adding it
+ * again after the restore re-inserts it by rank, and the shell saves the new order.
+ */
+export function moveToTop(shell, id) {
+    const widgets = Array.from(shell.widgets('left'));
+    const index = widgets.findIndex(widget => widget.id === id);
+    if (index <= 0) {
+        return false;
+    }
+    const widget = widgets[index];
+    // Adding hides the widget, so an open panel has to be opened again.
+    const wasOpen = widget.isVisible;
+    shell.add(widget, 'left', { rank: 0 });
+    if (wasOpen) {
+        shell.activateById(id);
+    }
+    return true;
+}
 /**
  * Submenus of local files. "Open Recent" is built by the document manager rather than
  * declared in a schema, and its menu has no id, so it is known by the commands it holds.